Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | |
2 | =head1 NAME | |
3 | ||
4 | B<Tk> - An overview of an Object Oriented Tk8.0 extension for perl5 | |
5 | ||
6 | =for category Introduction | |
7 | ||
8 | =head1 SYNOPSIS | |
9 | ||
10 | use Tk; | |
11 | ||
12 | $main = MainWindow-E<gt>new(); | |
13 | ||
14 | $widget = $main-E<gt>I<Widget>(...); | |
15 | ||
16 | $widget-E<gt>pack(...); | |
17 | ||
18 | ... | |
19 | ||
20 | MainLoop; | |
21 | ||
22 | =head1 DESCRIPTION | |
23 | ||
24 | In writing the perl Tk extension, the goals were to provide a complete | |
25 | interface to the latest production version of John Ousterhout's Tk, while providing | |
26 | an Object Oriented interface to perl code. | |
27 | ||
28 | =head1 CONTENTS | |
29 | ||
30 | The package is composed of three loosely connected parts: | |
31 | ||
32 | =over 4 | |
33 | ||
34 | =item I<pTk> - Converted Tk source | |
35 | ||
36 | The I<pTk> sub-directory is a copy of the C code of Tk4.0, modified | |
37 | to allow use by languages other than the original Tcl. | |
38 | (The pTk can be read as 'perl' Tk or 'portable' Tk, depending on | |
39 | your sensibilities.) | |
40 | ||
41 | =item B<Tk> to Perl 'Glue' | |
42 | ||
43 | The top level directory provides I<Tk.xs> and I<tkGlue.c> | |
44 | which provide the perl-callable interfaces to pTk | |
45 | ||
46 | =item Perl code for 'Widget' Classes | |
47 | ||
48 | The I<Tk/Tk> sub-directory contains the various perl modules that comprise | |
49 | the "Classes" that are visible to Tk applications. | |
50 | ||
51 | The "major" widgets such as B<Tk::Text> are actually in separate directories | |
52 | at the top level (e.g. I<Text/*> for B<Tk::Text>) and are dynamically | |
53 | loaded as needed on platforms which support perl5's B<DynaLoader>. | |
54 | ||
55 | =back | |
56 | ||
57 | =head1 CLASS HIERARCHY | |
58 | ||
59 | =over 4 | |
60 | ||
61 | =item B<package Tk;> - the 'base class' | |
62 | ||
63 | All the "command names" documented in Tcl/Tk are made to look like perl | |
64 | sub's and reside in the Tk package. Their names are all lower case. | |
65 | Typically there are very few commands at this level which are called | |
66 | directly by applications. | |
67 | ||
68 | =item B<package Tk::Widget;> - the 'Widget class' | |
69 | ||
70 | There are no actual objects of the B<Tk::Widget> class; however all | |
71 | the various Tk window "widgets" inherit from it, and it in turn | |
72 | inherits all the core Tk functions from Tk. | |
73 | ||
74 | B<Tk::Widget> provides various functions and interfaces which are | |
75 | common to all Widgets. | |
76 | ||
77 | A widget is represented to perl as a blessed reference to a hash. There are some | |
78 | members of the hash which are private to Tk and its tkGlue code. Keys | |
79 | starting with B<'.'> and of the form B</_[A-Z][A-Za-z_]+_/> | |
80 | (i.e. starting and ending in _ and with first char after _ being upper case) should be | |
81 | considered reserved to B<Tk>. | |
82 | ||
83 | =item B<Tk::Button>, B<Tk::Entry>, B<Tk::Text> ... | |
84 | ||
85 | There is one class for each of the "Tk" widget item types. | |
86 | Some of them like B<Tk::Frame> do very little indeed, and really | |
87 | only exist so that they can be derived from or so that focus or menu | |
88 | traversal can discover the "kind" of window being processed. | |
89 | ||
90 | Other classes, B<Tk::Text> for example, provide a lot of methods | |
91 | used with Tk's "bind" to provide a rich keyboard/mouse interface | |
92 | to the widgets' data. | |
93 | ||
94 | These widget classes also include conversions of the Tcl code for | |
95 | event bindings, keyboard focus traversal, menu bars, and menu keyboard | |
96 | traversal. All the Tcl functions have been converted, but the names have | |
97 | changed (systematically) and they have been split up between the various | |
98 | classes in what I hope is an appropriate manner. | |
99 | Name changes are normally: dropping initial tk_ as the Tk-ness is implicit | |
100 | in the B<Tk::> prefix, and similarly dropping say Menu from the name if it | |
101 | has been moved the Tk::Menu class. | |
102 | Thus 'proc tkMenuNextEntry' becomes 'sub NextEntry' in the Tk::Menu package. | |
103 | ||
104 | =item B<Tk::Image> | |
105 | ||
106 | This does for Tk4.0's "images" what B<Tk::Widget> does for widgets. | |
107 | Images are new to Tk4.0 and the class structure is not mature either. | |
108 | ||
109 | There are three sub-classes B<Tk::Bitmap>, B<Tk::Pixmap> and B<Tk::Photo>. | |
110 | ||
111 | It is expected that B<Tk::Image> hierarchy will evolve during the "beta" | |
112 | phase of Tk to allow dynamic or auto-loaded image types or photo formats | |
113 | (e.g. support for JPEG format for photos). | |
114 | ||
115 | =item Composite Widgets | |
116 | ||
117 | A composite is some kind of 'frame' with subwidgets which give it useful behaviour. | |
118 | B<Tk::Dialog> is an example of | |
119 | a composite widget classes built from the basic B<Tk> ones. | |
120 | It is intended that user code should not need to be aware that a particular | |
121 | class is a composite, and create and configure such widgets in the same manner | |
122 | as any other kind. The B<configure> mechanism and the methods of the | |
123 | class manipulate the subwidgets as required. | |
124 | ||
125 | Composite widgets are implemented via B<Tk::Frame> and multiple inheritance. | |
126 | The two 'frame' base classes B<Tk::Frame> and | |
127 | B<Tk::Toplevel> include the additional class B<Tk::Derived> | |
128 | in their inheritance. B<Tk::Derived> provides methods to allow additional | |
129 | B<configure> options to be defined for a widget. | |
130 | ||
131 | A Composite widget is typically defined as derived | |
132 | from B<Tk::Frame> or B<Tk::Toplevel> | |
133 | (e.g. B<Tk::Dialog>). | |
134 | ||
135 | =back | |
136 | ||
137 | =cut | |
138 |