| 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 | |