diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/UserGuide.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/Tk/UserGuide.pod | 586 |
1 files changed, 0 insertions, 586 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/UserGuide.pod b/Master/tlpkg/tlperl/lib/Tk/UserGuide.pod deleted file mode 100644 index caf34ece8d7..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/UserGuide.pod +++ /dev/null @@ -1,586 +0,0 @@ -=head1 NAME - -Tk::UserGuide - Writing Tk applications in Perl 5 - -=for category Introduction - -=head1 DESCRIPTION - -This document is for beginners. It assumes you know some B<Perl>, and -have it and Tk running. If you are I<not> currently reading this -document courtesy of the B<widget> demonstration program, please be -sure to run B<widget>, as it will show you the various widget types -supported by Tk and how to use them. B<widget> should be installed in -your default path, so type I<widget> at a command prompt. - -Here are links to other novice tutorials: - -L<http://www.lehigh.edu/~sol0/ptk/tpj1.html> -L<http://www.lehigh.edu/~sol0/ptk/perlmonth01/pm1.html> - -I<Mastering Perl/Tk> is the definitive book on Perl/Tk: - -L<http://www.oreilly.com/catalog/mastperltk> - -=head1 Some Background - -Tk GUI programming is event-driven. (This may already be familiar to -you.) In event-driven programs, the main GUI loop is outside of the -user program and inside the GUI library. This loop - initiated by -calling B<MainLoop> - watches all events of interest and activates -the correct handler procedures to handle these events. Some of these -handler procedures may be user-supplied; others will be part of the -library. - -For a programmer, this means that you're not watching what is happening; -instead, you are requested by the toolkit to perform actions whenever -necessary. -So, you're not watching for 'raise window / close window / redraw window' -requests, but you tell the toolkit which routine will handle such cases, -and the toolkit will call the procedures when required. These procedures -are known as I<callbacks>, and some of them you write yourself. - -=head1 First Requirements - -B<Perl> programs that use Tk need to include C<use Tk>. -A program should also use C<use strict> and the B<-w> switch to ensure -the program is working without common errors. - -Any Perl/Tk application starts by creating the Tk B<L<MainWindow|Tk::MainWindow>>. You -then create items inside the B<MainWindow>, and/or create new windows -called B<L<Toplevel|Tk::Toplevel>>s that also contain child items, before starting the -B<MainLoop>, which is the last logical statment in your program. You -can also create more items and windows while you're running, using -callbacks. Items are only shown on the display after they have been -arranged by a I<geometry manager> like B<L<pack|Tk::pack>>; more information on -this later. B<MainLoop> starts the GUI and handle all events. That's -all there is to it! A trivial one-window example is shown below: - - #!/usr/bin/perl -w - use Tk; - use strict; - - my $mw = MainWindow->new; - $mw->Label(-text => 'Hello, world!')->pack; - $mw->Button( - -text => 'Quit', - -command => sub { exit }, - )->pack; - MainLoop; - -Please run this example. It shows you two widget types, a B<L<Label|Tk::Label>> -and a B<L<Button|Tk::Button>>, and how they are packed. When clicked, the B<Button> -widget invokes the callback specified by the C<-command> option. Finally, -note the typical Tk style using C<-option> =E<gt> C<value> pairs. - -=head1 Widget creation - -Tk windows and widgets are hierarchical, S<i.e. one> window includes -one or more other windows. You create the first Tk window using -C<MainWindow-E<gt>new>. This returns a window handle, assigned to -C<$mw> in the example above. Keep track of the main handle, commonly -called a I<widget reference>. - -You can use any Tk handle to create child widgets within the window (or -widget). This is done by calling the Tk constructor method on the -variable. In the example above, the C<Label> method called from -C<$mw> creates a B<Label> widget inside the B<MainWindow>. In the -constructor call, you can specify various options; you can later add -or change options for any widget using the B<configure> method, which -takes the same parameters as the constructor. The one exception to -the hierarchical structure is the B<Toplevel> constructor, which -creates a new outermost window. - -After you create any widget (other than the B<MainWindow> or -B<Toplevel>s, you must render it by calling B<pack>. (This is not -entirely true; more later)). If you do not need to refer to the widget -after construction and packing, call B<pack> off the constructor -results, as shown for the B<Label> and B<Button> in the example above. Note -that the result of the compound call is the result of B<pack>, which -is a valid Tk handle. - -Windows and widgets are deleted by calling B<destroy> on them; -this will delete and un-draw the widget and all its children. - -=head1 Standard Tk widgets - -Here is an itemize of the standard Tk widget set. - -=over 4 - -=item L<Button|Tk::Button> - -=item L<Canvas|Tk::Canvas> - -=item L<Checkbutton|Tk::Checkbutton> - -=item L<Entry|Tk::Entry> - -=item L<Frame|Tk::Frame> - -=item L<Label|Tk::Label> - -=item L<Labelframe|Tk::Labelframe> - -=item L<Listbox|Tk::Listbox> - -=item L<Menu|Tk::Menu> - -=item L<Menubutton|Tk::Menubutton> - -=item L<Message|Tk::Message> - -=item L<Panedwindow|Tk::Panedwindow> - -=item L<Radiobutton|Tk::Radiobutton> - -=item L<Scale|Tk::Scale> - -=item L<Scrollbar|Tk::Scrollbar> - -=item L<Spinbox|Tk::Spinbox> - -=item L<Text|Tk::Text> - -=item L<Toplevel|Tk::Toplevel> - -=back - -Perl/Tk provides an equal number of new widgets, above and beyond this -core set. - -=over 4 - -=item L<Adjuster|Tk::Adjuster> - -=item L<Balloon|Tk::Balloon> - -=item L<BrowseEntry|Tk::BrowseEntry> - -=item L<ColorEditor|Tk::ColorEditor> - -=item L<Dialog|Tk::Dialog> - -=item L<DialogBox|Tk::DialogBox> - -=item L<DirTree|Tk::DirTree> - -=item ErrorDialog - -=item L<FBox|Tk::FBox> - -=item L<FileSelect|Tk::FileSelect> - -=item L<HList|Tk::HList> - -=item LabEntry - -=item L<LabFrame|Tk::LabFrame> - -=item L<NoteBook|Tk::NoteBook> - -=item L<Optionmenu|Tk::Optionmenu> - -=item L<Pane|Tk::Pane> - -=item L<ProgressBar|Tk::ProgressBar> - -=item L<ROText|Tk::ROText> - -=item L<Table|Tk::Table> - -=item L<TextUndo|Tk::TextUndo> - -=item L<Tiler|Tk::Tiler> - -=item L<TList|Tk::TList> - -=item L<Tree|Tk::Tree> - -=back - -=head1 Variables and callback routines - -Most graphical interfaces are used to set up a set of values and conditions, -and then perform the appropriate action. The Tk toolkit is different -from your average text-based prompting or menu driven system in that you do -not collect settings yourself, and decide on an action based on an -input code; instead, you leave these -values to your toolkit and only get them when the action is performed. - -So, where a traditional text-based system would look like this: - - #!/usr/bin/perl -w - use strict; - - print "Please type a font name\n"; - my $font = <>; chomp $font; - # Validate font - - print "Please type a file name\n"; - my $filename = <>; chomp $filename; - # Validate filename - - print "Type <1> to fax, <2> to print\n"; - my $option = <>; chomp $option; - if ($option eq 1) { - print "Faxing $filename in font $font\n"; - } elsif ($option eq 2) { - print "Now sending $filename to printer in font $font\n"; - } - -The slightly larger example below shows how to do this in Tk. -Note the use of callbacks. Note, also, that Tk handles the values, and -the subroutine uses the method B<get> to get at the values. -If a user changes his mind and wants to change the font again, -the application never notices; it's all handled by Tk. - - #!/usr/bin/perl -w - use Tk; - use strict; - - my $mw = MainWindow->new; - - $mw->Label(-text => 'File Name')->pack; - my $filename = $mw->Entry(-width => 20); - $filename->pack; - - $mw->Label(-text => 'Font Name')->pack; - my $font = $mw->Entry(-width => 10); - $font->pack; - - $mw->Button( - -text => 'Fax', - -command => sub{do_fax($filename, $font)} - )->pack; - - $mw->Button( - -text => 'Print', - -command => sub{do_print($filename, $font)} - )->pack; - - MainLoop; - - sub do_fax { - my ($file, $font) = @_; - my $file_val = $file->get; - my $font_val = $font->get; - print "Now faxing $file_val in font $font_val\n"; - } - - sub do_print { - my ($file, $font) = @_; - my $file_val = $file->get; - my $font_val = $font->get; - print "Sending file $file_val to printer in font $font_val\n"; - } - -=head1 The packer - grouping with Frame widgets - -In the examples above, you must have noticed the B<pack> calls. This -is one of the more complicated parts of Tk. The basic idea is that -any window or widget should be subject to a Tk geometry manager; the -I<packer> is one of the placement managers, and B<L<grid|Tk::grid>> is another. - -The actions of the packer are rather simple: when applied -to a widget, the packer positions that widget on the indicated position -within the remaining space in its parent. By default, the position is -on top; this means the next items will be put below. You can also -specify the left, right, or bottom positions. Specify position -using B<-side =E<gt> 'right'>. - -Additional packing parameters specify the behavior of the widget when -there is some space left in the B<L<Frame|Tk::Frame>> or when the window size is -increased. If widgets should maintain a fixed size, specify nothing; -this is the default. For widgets that you want to fill up the current -horizontal and/or vertical space, specify B<-fill =E<gt> 'x'>, B<'y'>, -or B<'both'>; for widgets that should grow, specify B<-expand =E<gt> 1>. -These parameters are not shown in the example below; see the B<widget> -demonstration. - -If you want to group some items within a window that have a different -packing order than others, you can include them in a Frame. This is a -do-nothing window type that is meant for packing or filling (and to -play games with borders and colors). - -The example below shows the use of pack and Frames: - - #!/usr/bin/perl -w - use Tk; - use strict; - - # Take top and the bottom - now implicit top is in the middle - my $mw = MainWindow->new; - $mw->title( 'The MainWindow' ); - $mw->Label(-text => 'At the top (default)')->pack; - $mw->Label(-text => 'At the bottom')->pack(-side => 'bottom'); - $mw->Label(-text => 'The middle remains')->pack; - - # Since left and right are taken, bottom will not work... - my $top1 = $mw->Toplevel; - $top1->title( 'Toplevel 1' ); - $top1->Label(-text => 'Left')->pack(-side => 'left'); - $top1->Label(-text => 'Right')->pack(-side => 'right'); - $top1->Label(-text => '?Bottom?')->pack(-side => 'bottom'); - - # But when you use Frames, things work quite alright - my $top2 = $mw->Toplevel; - $top2->title( 'Toplevel 2' ); - my $frame = $top2->Frame; - $frame->pack; - $frame->Label(-text => 'Left2')->pack(-side => 'left'); - $frame->Label(-text => 'Right2')->pack(-side => 'right'); - $top2->Label(-text => 'Bottom2')->pack(-side => 'bottom'); - - MainLoop; - -=head1 More than one window - -Most real applications require more than one window. As you just saw, -you can create more outermost windows by using a B<Toplevel> widget. -Each window is independent; destroying a B<Toplevel> window does not -affect the others as long as they are not a child of the closed -B<Toplevel>. However, exiting the B<MainWindow> will destroy all remaining -B<Toplevel> widgets and end the application. The -example below shows a trivial three-window application: - - #!/usr/bin/perl -w - use Tk; - use strict; - - my $mw = MainWindow->new; - fill_window($mw, 'Main'); - my $top1 = $mw->Toplevel; - fill_window($top1, 'First top-level'); - my $top2 = $mw->Toplevel; - fill_window($top2, 'Second top-level'); - MainLoop; - - sub fill_window { - my ($window, $header) = @_; - $window->Label(-text => $header)->pack; - $window->Button( - -text => 'close', - -command => [$window => 'destroy'] - )->pack(-side => 'left'); - $window->Button( - -text => 'exit', - -command => [$mw => 'destroy'] - )->pack(-side => 'right'); - } - -=head1 More callbacks - -So far, all callback routines shown called a user procedure. -You can also have a callback routine call another Tk routine. -This is the way that scroll bars are implemented: scroll-bars -can call a Tk item or a user procedure, whenever their position -has changed. The Tk item that has a scrollbar attached calls the -scrollbar when its size or offset has changed. In this way, -the items are linked. You can still ask a scrollbar's position, -or set it by hand - but the defaults will be taken care of. - -The example below shows a B<L<Listbox|Tk::Listbox>> with a scroll bar. Moving -the scrollbar moves the B<Listbox>. Scanning a B<Listbox> (dragging -an item with the left mouse button) moves the scrollbar. - - #!/usr/bin/perl -w - use Tk; - use strict; - - my $mw = MainWindow->new; - my $box = $mw->Listbox( - -relief => 'sunken', - -height => 5, - -setgrid => 1, - ); - my @items = qw(One Two Three Four Five Six Seven - Eight Nine Ten Eleven Twelve); - foreach (@items) { - $box->insert('end', $_); - } - my $scroll = $mw->Scrollbar(-command => ['yview', $box]); - $box->configure(-yscrollcommand => ['set', $scroll]); - $box->pack(-side => 'left', -fill => 'both', -expand => 1); - $scroll->pack(-side => 'right', -fill => 'y'); - - MainLoop; - -Note that there's a convenience method B<L<Scrolled|Tk::Scrolled>> -which helps constructing widgets with automatically managed -scrollbars. - -=head1 Canvases and tags - -One of the most powerful widgets in Tk is the B<L<Canvas|Tk::Canvas>> window. -In a B<Canvas> window, you can draw simple graphics and include -other widgets. The B<Canvas> area may be larger than the visible window, -and may then be scrolled. Any item you draw on the canvas has its own id, -and may optionally have one or more I<tags>. You may refer to any -item by its id, and may refer to any group of items by a common tag; -you can move, delete, or change groups of items using these tags, -and you can I<bind> actions to tags. For a properly designed (often -structured) B<Canvas>, you can specify powerful actions quite simply. - -In the example below, actions are bound to circles (single click) -and blue items (double-click); obviously, this can be extended to any -tag or group of tags. - - #!/usr/bin/perl -w - use Tk; - use strict; - - # Create B<MainWindow> and canvas - my $mw = MainWindow->new; - my $canvas = $mw->Canvas; - $canvas->pack(-expand => 1, -fill => 'both'); - - # Create various items - create_item($canvas, 1, 1, 'circle', 'blue', 'Jane'); - create_item($canvas, 4, 4, 'circle', 'red', 'Peter'); - create_item($canvas, 4, 1, 'square', 'blue', 'James'); - create_item($canvas, 1, 4, 'square', 'red', 'Patricia'); - - # Single-clicking with left on a 'circle' item invokes a procedure - $canvas->bind('circle', '<1>' => sub {handle_circle($canvas)}); - # Double-clicking with left on a 'blue' item invokes a procedure - $canvas->bind('blue', '<Double-1>' => sub {handle_blue($canvas)}); - MainLoop; - - # Create an item; use parameters as tags (this is not a default!) - sub create_item { - my ($can, $x, $y, $form, $color, $name) = @_; - - my $x2 = $x + 1; - my $y2 = $y + 1; - my $kind; - $kind = 'oval' if ($form eq 'circle'); - $kind = 'rectangle' if ($form eq 'square'); - $can->create( - ($kind, "$x" . 'c', "$y" . 'c', - "$x2" . 'c', "$y2" . 'c'), - -tags => [$form, $color, $name], - -fill => $color); - } - - # This gets the real name (not current, blue/red, square/circle) - # Note: you'll want to return a list in realistic situations... - sub get_name { - my ($can) = @_; - my $item = $can->find('withtag', 'current'); - my @taglist = $can->gettags($item); - my $name; - foreach (@taglist) { - next if ($_ eq 'current'); - next if ($_ eq 'red' or $_ eq 'blue'); - next if ($_ eq 'square' or $_ eq 'circle'); - $name = $_; - last; - } - return $name; - } - - sub handle_circle { - my ($can) = @_; - my $name = get_name($can); - print "Action on circle $name...\n"; - } - - sub handle_blue { - my ($can) = @_; - my $name = get_name($can); - print "Action on blue item $name...\n"; - } - -=head1 Perl/Tk and Unicode - -Perl/Tk follows Perl's model of handling Unicode. That is, if a string -is correctly flagged as a E<quot>characterE<quot> string in the sense -like described in L<Encode/TERMINOLOGY>, then Perl/Tk will very -probably display and handle this string correctly. - -Note that every variable which is passed somehow into a Perl/Tk method -will be implicitely changed into an internally utf8-flagged variable. -Semantically nothing changes, as the series of codepoints stays the -same, but things will change when variables with high-bit iso-8859-1 -characters will be passed to the "outer" world. In this case you have -to explicitely mark the encoding of your output stream if using IO, or -encode the variables using L<Encode> for other style of communication. - -This is the theory, now some examples. - -If you use non-iso-8859-1 characters in the source code, then use -either the C<use utf8;> or C<use encoding 'I<encodingname>'> pragma: - - use utf8; - use Tk; - my $x = "some characters using utf8 encoding"; - tkinit->Label(-text => $x)->pack; - MainLoop; - -For data that comes from a file you have to specify the encoding -unless it's encoded as ascii or iso-8559-1: - - use Tk; - open my $FH, "<:encoding(utf-8)", "filename" or die $!; - # or for utf-16 data: open my $FH, "<:encoding(utf-16)", "filename" or die $!; - my $data = <$FH>; - tkinit->Label(-text => $data)->pack; - MainLoop; - -Likewise, the encoding must be specified for all data which is read -from Tk widgets and that shall be output into a file. For the output, -the encoding should be always specified, even if it is iso-8859-1: - - use Tk; - $mw = tkinit; - $mw->Entry(-textvariable => \$input)->pack; - $mw->Button( - -text => "Write to file", - -command => sub { - open my $FH, ">:encoding(iso-8859-1)", "filename" or die $!; - print $FH $input; - }, - )->pack; - MainLoop; - -Note that Tk is Unicode-capable. So you need to be prepared that the -user has the appropriate input methods activated to enter non-ascii -characters. If an output encoding is used which does not cover the -whole of Unicode codepoints then a warning will be issued when writing -the file, like this: - - "\x{20ac}" does not map to iso-8859-1 at /usr/local/lib/perl5/site_perl/5.8.8/mach/Tk.pm line 250. - -Also, the same hexadecimal notation will be used as replacements for -the unhandled characters. - -Handling encoding in I/O is pretty simple using the C<encoding> PerlIO -layer, as described above. In other cases, such as when dealing with -databases, encoding the data usually has to be done manually, unless -the database driver has some means for automatically do this for you. -So when working with a MySQL database, one could use: - - use Tk; - use DBI; - use Encode qw(encode); - $mw = tkinit; - $mw->Entry(-textvariable => \$input)->pack; - $mw->Button( - -text => "Write to database", - -command => sub { - my $dbh = DBI->connect("dbi:mysql:test", "root", "") or die; - my $encoded_input = encode("iso-8859-1", $input); - $dbh->do("INSERT INTO testtable VALUES (?)", undef, $encoded_input) or die; - }, - )->pack; - MainLoop; - -Unfortunately, there are still places in Perl ignorant of Unicode. One -of these places are filenames. Consequently, the file selectors in -Perl/Tk do not handle encoding of filenames properly. Currently they -suppose that filenames are in iso-8859-1 encoding, at least on Unix -systems. As soon as Perl has a concept of filename encodings, then -Perl/Tk will also implement such schemes. - -=cut |