view release on metacpan or  search on metacpan

lib/Tcl/pTk.pm  view on Meta::CPAN

The C<use Tcl::pTk;> statement not only creates the C<Tcl::pTk> package, but also creates the
C<Tcl::pTk::Widget> package, which is responsible for widgets. Each widget ( an object
blessed to C<Tcl::pTk::Widget>, or any of its subclasses )
behaves in such a way that its method will result in calling its path on the
interpreter.

=head3 Perl/Tk syntax

C<Tcl::pTk> fully supports perl/Tk widget syntax of the L<Tk> package,
which has been used for many years. This means that any C<Tcl::pTk> widget
has a number of methods like C<Button>, C<Frame>, C<Text>, C<Canvas> and so
on, and invoking those methods will create an appropriate child widget.
C<Tcl::pTk> will generate an unique path-name for a newly created widget.

To demonstrate this concept, the perl/Tk syntax:

    my $label = $frame->Label(-text => "Hello world");

executes the command

    $int->call("label", ".l", "-text", "Hello world");

and this command similar to

    $int->Eval("label .l -text {Hello world}");

This way Tcl::pTk widget commands are translated to Tcl syntax and directed to
the Tcl interpreter. This translation that occurs from perl/Tk syntax to Tcl calls is why the two approaches for
dealing with widgets are interchangeable.

The newly created widget C<$label> will be blessed to package C<Tcl::pTk::Label>
which is isa-C<Tcl::pTk::Widget> (i.e. C<Tcl::pTk::Label> is a subclass of C<Tcl::pTk::Widget>).


=head1 Categories of Tcl::pTk Widgets

C<Tcl::pTk> Widgets fall into the following basic categories, based on how they are implemented in the C<Tcl::pTk> package.

=over 1

=item Direct auto-wrapped widgets

These types of widgets (for example the Entry, Button, Scrollbar, and Label widgets) have no special code written for them
in C<Tcl::pTk>. Their creation and method calls (e.g. C<< $button->configure(-text => 'ButtonText') >>) are handled
by the wrapping code in the base Tcl::pTk::Widget package.

=item Auto-wrapped widgets, with compatibility code

These types of widgets are similar to the Direct auto-wraped widgets, but have additional code written to be completely
compatibile with the perl/Tk syntax. Examples of this type of widget are the Text, Frame, Menu, and Menubutton widgets.

=item Megawidgets

These are widgets that are composed of one-or-more other base widget types. Pure-perl megawidgets are supported in Tcl::pTk,
just like they are in perl/Tk. Examples of these types of widgets are ProgressBar, LabEntry, BrowseEntry, and SlideSwitch
(one of the test cases in the source distribution).

=item Derived Widgets

Derived widgets are sub-classes of existing widgets that provide some additional functions. Derived widgets are created in
Tcl::pTk using very similar syntax to perl/Tk (i.e. using the Tcl::pTk::Derived package, similar to the Tk::Derived package). 
Examples of these types of widgets are Tree, TextEdit, TextUndo, ROText, and DirTree.

=back

=head1 A behind-the-scenes look at auto-wrapped widgets

All widgets in C<Tcl::pTk> are objects, and have an inheritance hierarchy that derives from the C<Tcl::pTk::Widget> 
parent class. Megawidgets and derived widgets are handled very similar (if not exactly) the same as in perl/tk.

Auto-wrapped widgets (like the Entry, Button, Scrollbar, etc.) are handled differently. 
The object system for these types of widgets is dynamic. Classes and/or methods are created when they are 
first used or needed.

The following describes how methods are called for the two different categories of auto-wrapped widgets

=over 1

=item Direct auto-wrapped widget example

Here is an example of a Entry widget, a direct auto-wrapped widget:

  my $entry = $mw->Entry->pack;          # Create an entry widget and pack it
  $entry->insert('end', -text=>'text');  # Insert some text into the Entry
  my $entryText = $entry->get();         # Get the entry's text

Internally, the following mechanics come into play:
The I<Entry> method creates an I<Entry> widget (known as C<entry> in the Tcl/Tk environment). 
When this creation method is invoked the first time, a package 
C<Tcl::pTk::Entry> is created, which sets up the class hierarchy for any
further Entry widgets. The newly-created C<Tcl::pTk::Entry> class is be
a direct subclass of C<Tcl::pTk::Widget>.

The second code line above calls the C<insert> method of the C<$entry> object.
When invoked first time, a method (i.e. subref) C<insert> is 
created in package C<Tcl::pTk::Entry>, which will end-up calling
calling the C<invoke> method on the Tcl/Tk interpreter (i.e. 
C<< $entry->interp()->invoke($entry, 'insert', -text, 'text') >>).

The first time C<insert> is called, the C<insert> method does not exist, so AUTOLOAD
comes into play and creates the method. The second time C<insert> is called, the already-created
method is called directly (i.e. not created again), thus saving execution time.

=item Auto-wrapped widgets, with compatibility code

Here is an example of a Text widget, which is an auto-wrapped widget with extra
code added for compatibility with the perl/tk Text widget.

  my $text = $mw->Text->pack;            # Create an text widget and pack it
  $text->insert('end', -text=>'text');   # Insert some text into the Text
  @names = $text->markNames;             # Get a list of the marks set in the
                                         #  Text widget

Internally, following mechanics come into play:
The I<Text> method creates an I<Text> widget (known as C<text> in Tcl/Tk environment). 
Because a C<Tcl::pTk::Text> package already exists, a new package is not created
at runtime like the case above. 

The second code line above calls the C<insert> of the C<$text> object of type
C<Tcl::pTk::Text>. This C<insert> method is already defined in the C<Tcl::pTk::Text> package,
so it is called directly.