diff options
author | Karl Berry <karl@freefriends.org> | 2014-04-23 22:10:41 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2014-04-23 22:10:41 +0000 |
commit | e5c6e6d9c56fbfc54508fa2c32b03a5a870b7553 (patch) | |
tree | 40fcc93aa383c1e45d31ddc42d03f15cbada7076 /Master/tlpkg/tlperl/lib/Tk | |
parent | 300c1eb6d37d46078d448d6d58938d5a80cd68ff (diff) |
oops, remove 5.16 tlperl files
git-svn-id: svn://tug.org/texlive/trunk@33649 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk')
104 files changed, 0 insertions, 28988 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/804delta.pod b/Master/tlpkg/tlperl/lib/Tk/804delta.pod deleted file mode 100644 index 1472f38c86b..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/804delta.pod +++ /dev/null @@ -1,110 +0,0 @@ -=head1 NAME - -Tk::804delta - what is new for perl/Tk 804 - -=head1 DESCRIPTION - -This document describes differences between the Tk800 series and the -Tk804 series. - -=head1 Incompatible Changes - -In Tk804.028, there are some additional incompatible changes: - -Return values of some B<Tk::Wm> methods (e.g. B<aspect>, B<wmGrid>, -B<iconposition>, B<resizable> ...) were changed from returning tclish -lists (e.g. "1 2 3 4") to perlish lists (1,2,3,4). - -B<Tk::Wm::wmTracing> needs argument for setting on/off, without argument -just return the current value. - -All Tk804 releases have the following incompatible changes: - -Tk804 will only work with perl 5.8.0 and above. For older perl -versions look for Tk800.025. - -B<curselection> of B<Tk::Listbox> now returns an array reference in -scalar context. This means you have to write - - my(@selected) = $listbox->curselection - -or - - my(@selected) = @{ $listbox->curselection } - -now. - -The B<fontActual> method now returns the pixel value instead of the -point value for B<-size>. Pixel values are expressed as negative -numbers. - -Some enhancements from the E<quot>dashE<quot> patches are lost for now -(i.e. B<-tile>, B<-troughtile> ...). - -The B<-state> option is not available anymore for B<Tk::Text> tags. -Use B<-elide> instead. - -=head1 Enhancements - -Tk804 is Unicode-aware. - -It is possible to build Tk with Xft support on X11. This is strongly -recommened if you are planning to make use of Unicode rendering -capabilities of Tk. It also gives anti-aliased fonts for regular text -(if you have TrueType or Type1 fonts and they are in your fontconfig -config file). - -The new method B<chooseDirectory> is available as a standard directory -selector. - -B<Tk::PNG> and B<Tk::JPEG> are bundled now with the perl/Tk -distribution, providing support for the image formats B<png> and -B<jpeg>. - -Improvements to B<Tk::Listbox>: new option B<-activestyle>, new -methods B<itemconfigure> and B<itemcget>, new virtual event B<<< -<<ListboxSelect>> >>>. - -More tests. - -=head1 New Widgets - -=over - -=item Tk::Labelframe - -An alternative to B<Tk::LabFrame>. - -=item Tk::Panedwindow - -An alternative to B<Tk::Adjuster>. - -=item Tk::Spinbox - -An alternative to the CPAN module B<Tk::NumEntry>. - -=back - -=head1 Selected Bug Fixes - -=head1 Changed Internals - -=head1 Platform Specific Problems - -=head1 Future Directions - -=head1 Reporting Bugs - -If you find what you think is a bug, you might check the articles -recently posted to the comp.lang.perl.tk newsgroup. - -If you believe you have an unreported bug, please send a mail to <ptk@lists.stanford.edu> and/or <nick@ing-simmons.net>. Be sure to trim your bug down -to a tiny but sufficient test case. - -=head1 SEE ALSO - -L<Tk>, C<Changes> file in the Perl/Tk distribution. - -=cut - - diff --git a/Master/tlpkg/tlperl/lib/Tk/Adjuster.pod b/Master/tlpkg/tlperl/lib/Tk/Adjuster.pod deleted file mode 100644 index 7d094f4e262..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Adjuster.pod +++ /dev/null @@ -1,223 +0,0 @@ - -=head1 NAME - -Tk::Adjuster - Allow size of packed widgets to be adjusted by user - -=for pm Tk/Adjuster.pm - -=for category Tk Geometry Management - -=head1 SYNOPSIS - -use Tk::Adjuster; - -I<$adjuster> = I<$widget>->B<Adjuster>I<(?options?)>; - -=head1 WIDGET-SPECIFIC OPTIONS - -=over 4 - -=item Name: B<restore> - -=item Class: B<Restore> - -=item Switch: B<-restore> - -Specifies a boolean value that determines whether the Adjuster -should forcibly attempt to make room -for itself (by reducing the size of its managed widget) when it is -unmapped (for example, due to a size change in a top level window). -The default value is 1. - -=item Name: B<side> - -=item Class: B<Side> - -=item Switch: B<-side> - -Specifies the side on which the managed widget lies relative to the -Adjuster. In conjunction with the pack geometry manager, this relates to -the side of the master against which the managed widget and the Adjuster -are packed. -Must be B<left>, B<right>, B<top>, or B<bottom>. Defaults to B<top>. - -=item Name: B<widget> - -=item Class: B<Widget> - -=item Switch: B<-widget> - -Specifies the widget which is to be managed by the Adjuster. - -=back - -=head1 DESCRIPTION - -B<Tk::Adjuster> is a Frame containing a "line" and a "blob". - -Dragging with Mouse Button-1 results in a line being dragged -to indicate new size. Releasing Button-1 submits GeometryRequests -on behalf of the managed widget which will cause the packer to change the -widget's size. - -If Drag is done with Shift button down, then GeometryRequests are made -in "real time" so that text-flow effects can be seen, but as a lot more -work is done behaviour may be sluggish. - -If widget is packed with -side => left or -side => right then width is -adjusted. If packed -side => top or -side => bottom then height is adjusted. - -B<packPropagate> is turned off for the master window to prevent adjustment -changing overall window size. Similarly B<packPropagate> is turned off -for the managed widget if it has things packed inside it. This is so that -the GeometryRequests made by B<Tk::Adjuster> are not overridden by pack. - -In addition, the managed widget is made non-expandable -to prevent the geometry manager reallocating freed space in the master -back to the managed widget. -Note however that expansion is turned off only after the Adjuster is mapped, -which allows the managed widget to expand naturally on window creation. - -The Tk::Widget method, B<packAdjust>, calls pack on the widget, then -creates an instance of B<Tk::Adjuster>, -and packs that "after" the widget. Its use has two disadvantages however: the -Adjuster widget is not made available to the caller, and -options cannot be set on the Adjuster. For these reasons, the Tk::Adjuster -method, B<packAfter> is preferred, but B<packAdjust> is retained -for backwards compatibility. - -=head1 WIDGET METHODS - -=over 4 - -=item I<$adjuster>->B<packAfter>(I<managed_widget, ?pack_options?>) - -This command configures the Adjuster's B<-widget> and B<-side> options -respectively to I<managed_widget> and the B<-side> value specified in -I<pack_options> (B<top> if not specified). It then packs the Adjuster -after I<managed_widget>, with B<-fill> set to B<x> or B<y> as appropriate. - -=item I<$adjuster>->B<packForget>I<?(boolean)?> - -This command calls B<Tk::Widget::packForget> on the Adjuster. -If a parameter is provided and it has a true boolean value, then -B<packForget> is also called on the managed widget. - -=item I<$adjuster>->B<slave> - -This command returns the value I<$adjuster>->I<cget('-widget')>, ie. the -reference to the managed widget. - -=back - -=head1 EXAMPLES - -B<Using an Adjuster to separate two widgets, whereby the left widget -is managed, and right widget expands to fill space on a window resize> - -a) Using packAfter (preferred interface) - - use Tk; - use Tk::Adjuster; - - my $f = MainWindow->new; - my $lst1 = $f->Listbox(); - my $adj1 = $f->Adjuster(); - my $lst2 = $f->Listbox(); - - my $side = 'left'; - $lst1->pack(-side => $side, -fill => 'both', -expand => 1); - $adj1->packAfter($lst1, -side => $side); - $lst2->pack(-side => $side, -fill => 'both', -expand => 1); - MainLoop; - -b) Using packAdjust - - use Tk; - use Tk::Adjuster; - - my $f = MainWindow->new; - my $lst1 = $f->Listbox(); - my $lst2 = $f->Listbox(); - - my $side = 'left'; - $lst1->packAdjust(-side => $side, -fill => 'both'); - $lst2->pack (-side => $side, -fill => 'both', -expand => 1); - MainLoop; - -c) Using the standard Tk::Widget::pack - - use Tk; - use Tk::Adjuster; - - my $f = MainWindow->new; - my $side = 'left'; - my $lst1 = $f->Listbox(); - my $adj = $f->Adjuster(-widget => $lst1, -side => $side); - my $lst2 = $f->Listbox(); - - $lst1->pack(-side => $side, -fill => 'both', -expand => 1); - $adj->pack (-side => $side, -fill => 'y'); - $lst2->pack(-side => $side, -fill => 'both', -expand => 1); - - MainLoop; - -Changing the above examples so that $side has the value 'right' means the -left widget expands to fill space on a window resize. - -Changing the above examples so that $side has the value 'top' -produces a testcase with a horizontal Adjuster. -Here the bottom widget expands to fill space on a window resize. -Packing to the 'bottom' makes the top widget expand to fill space on window -resize. - -B<Using -restore =E<gt> 0 for multiple columns> - -In the case of multiple columns (or rows) the "restore" functionality of the -Adjuster can be inconvenient. When the user adjusts the width of one column -and thereby pushes the Adjuster of another column off the window, this -adjuster tries to restore itself by reducing the size of its managed widget. -This has the effect that column widths shrink; and the original size -is not restored when -the user reverses the originating change. The B<-restore> option can be -used to turn off this functionality. (It makes some sense, however, to -leave B<-restore> -turned on for the first-packed Adjuster, so that at least one Adjuster -always remains visible.) - - use Tk; - use Tk::Adjuster; - my $f = MainWindow->new; - my $lst1 = $f->Listbox(); - my $adj1 = $f->Adjuster(); - my $lst2 = $f->Listbox(); - my $adj2 = $f->Adjuster(-restore => 0); - my $lst3 = $f->Listbox(); - - my $side = 'left'; - $lst1->pack(-side => $side, -fill => 'both', -expand => 1); - $adj1->packAfter($lst1, -side => $side); - $lst2->pack(-side => $side, -fill => 'both', -expand => 1); - $adj2->packAfter($lst2, -side => $side); - $lst3->pack(-side => $side, -fill => 'both', -expand => 1); - - MainLoop; - -=head1 BUGS - -It is currently not possible to configure the appearance of the Adjuster. -It would be nice to be able to set the width and relief of the Adjuster "line" -and the presence/absence of the "blob" on the Adjuster. - -Tk::Adjuster works theoretically with the grid geometry manager but there -are currently some problems which seem to be due to bugs in grid: - - a) There's never an Unmap event for the adjuster, so the "restore" - functionality has no effect. - b) After adjusting, widgets protrude into the border of the master. - c) grid('Propagate', 0) on MainWindow has no effect - window shrinks/grows - when widgets are adjusted. - d) Widgets shuffle to correct position on startup - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Animation.pod b/Master/tlpkg/tlperl/lib/Tk/Animation.pod deleted file mode 100644 index 996b035b1c5..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Animation.pod +++ /dev/null @@ -1,92 +0,0 @@ - -=head1 NAME - -Tk::Animation - Display sequence of Tk::Photo images - -=for pm Tk/Animation.pm - -=for category Tk Image Classes - -=head1 SYNOPSIS - - use Tk::Animation - my $img = $widget->Animation('-format' => 'gif', -file => 'somefile.gif'); - - $img->add_frame(@images); - - $img->start_animation; - $img->start_animation( $period ); - - $img->next_image; - $img->prev_image; - $img->set_image( 0 .. $#frames ); - - $img->pause_animation; - $img->resume_animation( $period ); - - $img->fast_forward( $multiplier ); - $img->fast_reverse( $multiplier ); - - $img->stop_animation; - - $img->set_disposal_method( $boolean ); - -=head1 DESCRIPTION - -In the simple case when C<Animation> is passed a GIF89 style GIF with -multiple 'frames', it will build an internal array of C<Photo> images. - -The C<add_frame> method adds images to the sequence. It is provided -to allow animations to be constructed from separate images. -All images must be C<Photo>s and should all be the same size. - -C<start_animation($period)> then initiates a C<repeat> with specified -I<$period> to sequence through these images. As for raw C<repeat> -I<$period> is in milliseconds, for a 50Hz monitor it should be at -least 20ms. If I<$period> is omitted it is determined from the GIF -metadata (see below), or if this is not possible it defaults to 100 -milliseconds. - -C<stop_animation> cancels the C<repeat> and resets the image to the first -image in the sequence. - -For fine-grained control C<next_image> and C<prev_image> move one frame forward -or backward. C<set_image> randomly positions the animation to a particular frame. - -C<pause_animation> pauses the movie and C<resume_animation> continues from the -pause point. - -C<fast_forward> and C<fast_reverse> speed through the movie either -forwards or backwards. $multiplier specifies how much faster the -animation moves. - -If L<Image::Info> is installed, then the repeat period time and -disposal method of GIF animations are determined from the GIF metadata -directly. Otherwise the disposal method must be set manually by using -C<set_disposal_method> (1 for blanking the previous images, 0 for -leaving the previous images as is). The repeat period time may be -given in the C<start_animation> method. - -=head1 NOTES - -C<set_disposal_method> was formerly known as C<blank> method, but the -naming of this method was a mistake. - -If the disposal method is not set correctly, either by -C<set_disposal_method> or by determining from the GIF metadata, then -the following may happen: By default Animation leaves the previous -movie frame in the animation photo. Many times overlaying subsequent -frames produces a composite that looks blurred. - -=head1 BUGS - -This module should not depend on a module which is not declared as a -dependency (Image::Info). - -The delays between images may vary in a GIF animation. This cannot be -handled by this module yet. - -The handling of the various disposal methods is not correct. - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Balloon.pod b/Master/tlpkg/tlperl/lib/Tk/Balloon.pod deleted file mode 100644 index 9188a9e25a4..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Balloon.pod +++ /dev/null @@ -1,293 +0,0 @@ - -=head1 NAME - -Tk::Balloon - pop up help balloons. - -=for pm Tixish/Balloon.pm - -=for category Tix Extensions - -=head1 SYNOPSIS - - use Tk::Balloon; - ... - $b = $top->Balloon(-statusbar => $status_bar_widget); - - # Normal Balloon: - $b->attach($widget, - -balloonmsg => "Balloon help message", - -statusmsg => "Status bar message"); - - # Balloon attached to entries in a menu widget: - $b->attach($menu, -state => 'status', - -msg => ['first menu entry', - 'second menu entry', - ... - ], - ); - - # Balloon attached to individual items in a canvas widget: - $b->attach($canvas, -balloonposition => 'mouse', - -msg => {'item1' => 'msg1', - 'tag2' => 'msg2', - ... - }, - ); - - # Balloon attached to items in a listbox widget: - $b->attach($listbox, -balloonposition => 'mouse', - -msg => ['first listbox element', - '2nd listbox element', - ... - ], - ); - -=head1 DESCRIPTION - -B<Balloon> provides the framework to create and attach help -balloons to various widgets so that when the mouse pauses over the -widget for more than a specified amount of time, a help balloon is -popped up. - -=head2 Balloons and Menus or Listboxes - -If the balloon is attached to a B<Menu> or B<Listbox> widget and the -message arguments are array references, then each element in the array -will be the message corresponding to a menu entry or listbox element. -The balloon message will then be shown for the entry which the mouse -pauses over. Otherwise it is assumed that the balloon is to be -attached to the B<Menu> or B<Listbox> as a whole. You can have -separate status and balloon messages just like normal balloons. - -=head2 Balloons and Canvases - -If the balloon is attached to a B<Canvas> widget and the message -arguments are hash references, then each hash key should correspond to -a canvas item ID or tag and the associated value will correspond to the -message for that canvas item. The balloon message will then be shown for -the current item (the one at the position of the mouse). Otherwise it is -assumed that the balloon is to be attached to the B<Canvas> as a whole. -You can have separate status and balloon messages just like normal -balloons. - -=head2 Balloons and HLists - -If the balloon is attached to a B<HList> widget and the message -arguments are hash references, then each hash key should correspond to -a HList path and the associated value will correspond to the message -for that HList item. The balloon message will then be shown for the -current item (the one at the position of the mouse). Otherwise it is -assumed that the balloon is to be attached to the B<HList> as a whole. -You can have separate status and balloon messages just like normal -balloons. - -=head2 Balloon Position - -By default, the balloon pops up at the lower right side of the client. -If it would extend outside the lower screen border, its positioned at the -upper right side. If it would extend outside the right screen border -it's shown on the lower left side of the client. If it would extend -outside both the lower and the right screen border, it's positioned -at the upper left side of the client. Thus, the little arrow always -points to the attached client. - -=head1 OPTIONS - -B<Balloon> accepts all of the options that the B<Frame> widget -accepts. In addition, the following options are also recognized. - -=over 4 - -=item B<-initwait> - -Specifies the amount of time to wait without activity before -popping up a help balloon. Specified in milliseconds. Defaults to -350 milliseconds. This applies to both the popped up balloon and -the status bar message. - -=item B<-state> - -Can be one of B<'balloon'>, B<'status'>, B<'both'> or B<'none'> -indicating that the help balloon, status bar help, both or none -respectively should be activated when the mouse pauses over the -client widget. Default is B<'both'>. - -=item B<-statusbar> - -Specifies the widget used to display the status message. This -widget should accept the B<-text> option and is typically a -B<Label>. If the widget accepts the B<-textvariable> option and -that option is defined then it is used instead of the B<-text> -option. - -=item B<-balloonposition> - -Can be one of B<'widget'> or B<'mouse'>. It controls where the balloon -will popup. B<'widget'> makes the balloon appear at the lower right -corner of the widget it is attached to (default), and B<'mouse'> makes -the balloon appear below and to the right of the current mouse position. - -=item B<-postcommand> - -This option takes a B<CODE> reference which will be executed before the -balloon and statusbar messages are displayed and should return a true -or false value to indicate whether you want the balloon to be displayed -or not. This also lets you control where the balloon is positioned by -returning a true value that looks like I<X,Y> (matches this regular -expression: C</^(\d+),(\d+)$/>). If the postcommand returns a value that -matches that re then those coordinates will be used as the position to -post the balloon. I<Warning:> this subroutine should return quickly or -the balloon response will appear slow. - -=item B<-cancelcommand> - -This option takes a B<CODE> reference which will be executed before the -balloon and statusbar messages are canceled and should return a true -or false value to indicate whether you want the balloon to be canceled -or not. I<Warning:> this subroutine should return quickly or the balloon -response will appear slow. - -=item B<-motioncommand> - -This option takes a B<CODE> reference which will be executed for any -motion event and should return a true or false value to indicate -whether the currently displayed balloon should be canceled (deactivated). -If it returns true then the balloon will definitely be canceled, if it -returns false then it may still be canceled depending the internal rules. -I<Note:> a new balloon may be posted after the B<-initwait> time -interval, use the B<-postcommand> option to control that behavior. -I<Warning:> the subroutine should be extremely fast or the balloon -response will appear slow and consume a lot of CPU time (it is executed -every time the mouse moves over the widgets the balloon is attached to). - -=item B<-numscreens> - -This option accepts an integer 1 or greater. This option should be used -to avoid disjointed balloons across multiple screens in single logical -sceen (SLS) mode. This only currently works in the horizontal direction. -Example: If you are running dual screens in SLS mode then you would set -this value to 2. Default value is 1. - -=back - -=head1 METHODS - -The B<Balloon> widget supports only three non-standard methods: - -=head2 B<attach(>I<widget>, I<options>B<)> - -Attaches the widget indicated by I<widget> to the help system. The -allowed options are: - -=over 4 - -=item B<-statusmsg> - -The argument is the message to be shown on the status bar when the -mouse pauses over this client. If this is not specified, but -B<-msg> is specified then the message displayed on the status bar -is the same as the argument for B<-msg>. If you give it a scalar -reference then it is dereferenced before being displayed. Useful -if the postcommand is used to change the message. - -=item B<-balloonmsg> - -The argument is the message to be displayed in the balloon that -will be popped up when the mouse pauses over this client. As with -B<-statusmsg> if this is not specified, then it takes its value -from the B<-msg> specification if any. If neither B<-balloonmsg> -nor B<-msg> are specified, or they are the empty string then -no balloon is popped up instead of an empty balloon. If you -give it a scalar reference then it is dereferenced before being -displayed. Useful if the postcommand is used to change the message. - -=item B<-msg> - -The catch-all for B<-statusmsg> and B<-balloonmsg>. This is a -convenient way of specifying the same message to be displayed in -both the balloon and the status bar for the client. - -=item B<-initwait> - -=item B<-state> - -=item B<-statusbar> - -=item B<-balloonposition> - -=item B<-postcommand> - -=item B<-cancelcommand> - -=item B<-motioncommand> - -These options allow you to override the balloon's default value for -those option for some of the widgets it is attached to. It accepts the -same values as above and will default to the B<Balloon>'s value. - -=back - -=head2 B<detach(>I<widget>B<)> - -Detaches the specified I<widget> from the help system. - -=head2 B<destroy> - -Destroys the specified balloon. - -=head1 ADVERTISED SUBWIDGETS - -The balloon label is advertised as C<message>. - -=head1 EXAMPLES - -See the balloon demo included with the widget demo script that came with -the distribution for examples on various ways to use balloons. - -=head1 NOTES - -Because of the overhead associated with each balloon you create (from -tracking the mouse movement to know when to activate and deactivate -them) you will see the best performance (low CPU consumption) if you -create as few balloons as possible and attach them to as many widgets -as you can. In other words, don't create a balloon for each widget -you want to attach one to. - -=head1 CAVEATS - -Pressing any button will deactivate (cancel) the current balloon, -if one exists. You can usually make the balloon reappear by moving -the mouse a little. Creative use of the 3 command options can help -you out also. If the mouse is over the balloon when a menu is unposted -then the balloon will remain until you move off of it. - -=head1 BUGS - -If using balloons attached to listbox entries or canvas items in a -scrolled widget, then the subwidget have to be used: - - $balloon->attach($w->Subwidget("scrolled"), -msg => ...); - -=head1 AUTHORS - -B<Rajappa Iyer> <rsi@earthling.net> did the original coding. - -B<Jason A. Smith> <smithj4@rpi.edu> added support for menus and made some -other enhancements. - -B<Slaven Rezic> <srezic@cpan.org> added support for canvas items. - -B<Gerhard Petrowitsch> <gerhard@petrowitsch.de> added intelligent positioning - -B<Jack Dunnigan> <dunniganj@cpan.org> Made positioning I<more> intelligent and -added support for multiple monitors under single logical screen. - -=head1 HISTORY - -The code and documentation was derived from Balloon.tcl from the -Tix4.0 distribution by Ioi Lam and modified by the above mentioned -authors. This code may be redistributed under the same terms as Perl. - -=cut - - diff --git a/Master/tlpkg/tlperl/lib/Tk/Bitmap.pod b/Master/tlpkg/tlperl/lib/Tk/Bitmap.pod deleted file mode 100644 index 49bf20ce4b4..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Bitmap.pod +++ /dev/null @@ -1,103 +0,0 @@ -# Copyright (c) 1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::Bitmap - Images that display two colors - -=for category Tk Image Classes - -=head1 SYNOPSIS - -S< >I<$image> = I<$widget>-E<gt>B<Bitmap>?(I<name>??,I<options>?) - -=head1 DESCRIPTION - -A bitmap is an image whose pixels can display either of two colors -or be transparent. -A bitmap image is defined by four things: a background color, -a foreground color, and two bitmaps, called the I<source> -and the I<mask>. -Each of the bitmaps specifies 0/1 values for a rectangular -array of pixels, and the two bitmaps must have the same -dimensions. -For pixels where the mask is zero, the image displays nothing, -producing a transparent effect. -For other pixels, the image displays the foreground color if -the source data is one and the background color if the source -data is zero. - -=head1 CREATING BITMAPS - -Bitmaps are created using I<$widget>-E<gt>B<Bitmap>. -Bitmaps support the following I<options>: - -=over 4 - -=item B<-background> =E<gt> I<color> - -Specifies a background color for the image in any of the standard -ways accepted by Tk. If this option is set to an empty string -then the background pixels will be transparent. This effect -is achieved by using the source bitmap as the mask bitmap, ignoring -any B<-maskdata> or B<-maskfile> options. - -=item B<-data> =E<gt> I<string> - -Specifies the contents of the source bitmap as a string. -The string must adhere to X11 bitmap format (e.g., as generated -by the B<bitmap> program). -If both the B<-data> and B<-file> options are specified, -the B<-data> option takes precedence. - -=item B<-file> =E<gt> I<name> - -I<name> gives the name of a file whose contents define the -source bitmap. -The file must adhere to X11 bitmap format (e.g., as generated -by the B<bitmap> program). - -=item B<-foreground> =E<gt> I<color> - -Specifies a foreground color for the image in any of the standard -ways accepted by Tk. - -=item B<-maskdata> =E<gt> I<string> - -Specifies the contents of the mask as a string. -The string must adhere to X11 bitmap format (e.g., as generated -by the B<bitmap> program). -If both the B<-maskdata> and B<-maskfile> options are specified, -the B<-maskdata> option takes precedence. - -=item B<-maskfile> =E<gt> I<name> - -I<name> gives the name of a file whose contents define the -mask. -The file must adhere to X11 bitmap format (e.g., as generated -by the B<bitmap> program). - -=back - -=head1 IMAGE METHODS - -When a bitmap image is created, Tk also creates a new object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. - -=head1 SEE ALSO - -L<Tk::Image|Tk::Image> -L<Tk::Pixmap|Tk::Pixmap> -L<Tk::Photo|Tk::Photo> - -=head1 KEYWORDS - -bitmap, image - -=cut diff --git a/Master/tlpkg/tlperl/lib/Tk/BrowseEntry.pod b/Master/tlpkg/tlperl/lib/Tk/BrowseEntry.pod deleted file mode 100644 index 98a547c4084..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/BrowseEntry.pod +++ /dev/null @@ -1,210 +0,0 @@ - -=head1 NAME - -Tk::BrowseEntry - entry widget with popup choices. - -=for pm Tixish/BrowseEntry.pm - -=for category Tix Extensions - -=head1 SYNOPSIS - - use Tk::BrowseEntry; - - $b = $frame->BrowseEntry(-label => "Label", -variable => \$var); - $b->insert("end", "opt1"); - $b->insert("end", "opt2"); - $b->insert("end", "opt3"); - ... - $b->pack; - -=head1 SUPER-CLASS - -The C<BrowseEntry> class is derived from the C<Frame> class and -inherits all the methods, options and subwidgets of its super-class. -By default, options and methods are delegated to the entry subwidget. - -=head1 DESCRIPTION - -BrowseEntry is a poor man's ComboBox. It may be considered an -enhanced version of LabEntry which provides a button to popup the -choices of the possible values that the Entry may -take. BrowseEntry supports all the options LabEntry supports -except B<-textvariable>. This is replaced by B<-variable>. Other -options that BrowseEntry supports: - -=over 4 - -=item B<-arrowimage> - -Specifies the image to be used in the arrow button beside the entry -widget. The default is an downward arrow image in the file cbxarrow.xbm - -=item B<-autolimitheight> - -If set to a true value, then the height of the listbox will be at most -the number of entries in the list. The overall maximum of -C<-listheight> still applies. - -=item B<-autolistwidth> - -If set to a true value, then the width of the listbox will match the -width of the largest entry. - -=item B<-browsecmd> - -Specifies a function to call when a selection is made in the -popped up listbox. It is passed the widget and the text of the -entry selected. This function is called after the entry variable -has been assigned the value. - -=item B<-browse2cmd> - -Like C<-browsecmd>, but the callback is called with the listbox index -instead of the selected value. - -=item B<-buttontakefocus> - -Set the C<-takefocus> option of the button subwidget. - -=item B<-choices> - -Specifies the list of choices to pop up. This is a reference to an -array of strings specifying the choices. - -=item B<-colorstate> - -The state of the widget is reflected by color. A non-editable entry -widget will get a light gray background, while an editable entry will -be almost white. [This may change] - -=item B<-listcmd> - -Specifies the function to call when the button next to the entry -is pressed to popup the choices in the listbox. This is called before -popping up the listbox, so can be used to populate the entries in -the listbox. - -=item B<-listheight> - -Set the height of the listbox. See also C<-autolimitheight>. - -=item B<-listwidth> - -Specifies the width of the popup listbox. - -=item B<-state> - -Specifies one of three states for the widget: normal, readonly, or -disabled. If the widget is disabled then the value may not be changed -and the arrow button won't activate. If the widget is readonly, the -entry may not be edited, but it may be changed by choosing a value -from the popup listbox. normal is the default. - -=item B<-style> - -Set the "style" of the widget. Permitted values are C<MSWin32> and -C<unix>. By default C<-style> is set to the current platform. Widgets -with the C<unix> style will look like a normal C<BrowseEntry> widget, -whereas with the C<MSWin32> style the arrow will look close to the -Windows' standard combobox widget, while moving the mouse the entries -will be highlighted, and probably includes other changes. - -=item B<-variable> - -Specifies the variable in which the entered value is to be stored. - -=back - -=head1 METHODS - -=over 4 - -=item B<insert(>I<index>, I<string>B<)> - -Inserts the text of I<string> at the specified I<index>. This string -then becomes available as one of the choices. - -=item B<delete(>I<index1>, I<index2>B<)> - -Deletes items from I<index1> to I<index2>. - -=item B<get> - -The get method is delegated to the choices listbox. - -=back - -=head1 ADVERTISED WIDGETS - -The following widgets are advertised: - -=over - -=item entry - -The entry widget. - -=item arrow - -The button with the arrow image. - -=item choices - -The toplevel widget containing the choice listbox. - -=item slistbox - -The scrolled listbox with the choices. - -=back - -=head1 SUBCLASSING - -To make subclassing easier, the following methods may be overridden to -use other standard widgets in composing the mega widget: - -=over - -=item LabEntryWidget - -A widget class compatible with Tk::LabEntry used for the entry. - -=item ButtonWidget - -A widget class compatible with Tk::Button used for the arrow button. - -=item ListboxWidget - -A widget class compatible with Tk::Listbox used for the choices -listbox. - -=back - -For example to use a C<NumEntry> widget (from the Tk-GBARR CPAN -distribution) instead of the normal C<Entry> widget: - - package Tk::NumBrowseEntry; - use base qw(Tk::BrowseEntry); - use Tk::NumEntry; - Construct Tk::Widget 'NumBrowseEntry'; - sub LabEntryWidget { "NumEntry" } - -=head1 BUGS - -BrowseEntry should really provide more of the ComboBox options. - -=head1 AUTHOR - -B<Rajappa Iyer> rsi@earthling.net - -B<Chris Dean> ctdean@cogit.com made additions. - -More additions by B<Slaven Rezic> slaven@rezic.de - -This code was inspired by ComboBox.tcl in Tix4.0 by Ioi Lam and -bears more than a passing resemblance to ComboBox code. This may -be distributed under the same conditions as Perl. - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Button.pod b/Master/tlpkg/tlperl/lib/Tk/Button.pod deleted file mode 100644 index 2eb6401ca9d..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Button.pod +++ /dev/null @@ -1,255 +0,0 @@ -# Copyright (c) 1990-1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::Button - Create and manipulate Button widgets - -=for category Tk Widget Classes - -=head1 SYNOPSIS - -I<$button> = I<$parent>-E<gt>B<Button>(?I<options>?); - -=head1 STANDARD OPTIONS - -B<-activebackground> -B<-activeforeground> -B<-anchor> -B<-background> -B<-bitmap> -B<-borderwidth> -B<-compound> -B<-cursor> -B<-disabledforeground> -B<-font> -B<-foreground> -B<-highlightbackground> -B<-highlightcolor> -B<-highlightthickness> -B<-image> -B<-justify> -B<-padx> -B<-pady> -B<-relief> -B<-repeatdelay> -B<-repeatinterval> -B<-takefocus> -B<-text> -B<-textvariable> -B<-underline> -B<-wraplength> - -See L<Tk::options> for details of the standard options. - -=head1 WIDGET-SPECIFIC OPTIONS - -=over 4 - -=item Name: B<command> - -=item Class: B<Command> - -=item Switch: B<-command> - -Specifies a L<Perl/Tk callback|Tk::callbacks> to associate with the -button. This command is typically invoked when mouse button 1 is -released over the button window. - -=item Command-Line Name: B<-compound> - -=item Database Name: B<compound> - -=item Database Class: B<Compound> - -Specifies whether the button should display both an image and text, -and if so, where the image should be placed relative to the text. -Valid values for this option are B<bottom>, B<center>, B<left>, -B<none>, B<right> and B<top>. The default value is B<none>, meaning -that the button will display either an image or text, depending on the -values of the -image and -bitmap options. - -=item Name: B<default> - -=item Class: B<Default> - -=item Switch: B<-default> - -Specifies one of three states for the default ring: B<normal>, -B<active>, or B<disabled>. In active state, the button is drawn -with the platform specific appearance for a default button. In normal -state, the button is drawn with the platform specific appearance for a -non-default button, leaving enough space to draw the default button -appearance. The normal and active states will result in buttons of -the same size. In disabled state, the button is drawn with the -non-default button appearance without leaving space for the default -appearance. The disabled state may result in a smaller button than -the active state. -ring. - -=item Name: B<height> - -=item Class: B<Height> - -=item Switch: B<-height> - -Specifies a desired height for the button. -If an image or bitmap is being displayed in the button then the value is in -screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>); -for text it is in lines of text. -If this option isn't specified, the button's desired height is computed -from the size of the image or bitmap or text being displayed in it. - -=item Command-Line Name: B<-overrelief> - -=item Database Name: B<overRelief> - -=item Database Class: B<OverRelief> - -Specifies an alternative relief for the button, to be used when -the mouse cursor is over the widget. This option can be used to -make toolbar buttons, by configuring B<-relief flat -overrelief -raised>. If the value of this option is the empty string, then -no alternative relief is used when the mouse cursor is over the -button. The empty string is the default value. - -=item Name: B<state> - -=item Class: B<State> - -=item Switch: B<-state> - -Specifies one of three states for the button: B<normal>, B<active>, -or B<disabled>. In normal state the button is displayed using the -B<foreground> and B<background> options. The active state is -typically used when the pointer is over the button. In active state -the button is displayed using the B<activeForeground> and -B<activeBackground> options. Disabled state means that the button -should be insensitive: the default bindings will refuse to activate -the widget and will ignore mouse button presses. -In this state the B<disabledForeground> and -B<background> options determine how the button is displayed. - -=item Name: B<width> - -=item Class: B<Width> - -=item Switch: B<-width> - -Specifies a desired width for the button. -If an image or bitmap is being displayed in the button then the value is in -screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>); -for text it is in characters. -If this option isn't specified, the button's desired width is computed -from the size of the image or bitmap or text being displayed in it. - -=back - -=head1 DESCRIPTION - -The B<Button> method creates a new window (given by the -$widget argument) and makes it into a button widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the button such as its colors, font, -text, and initial relief. The B<button> command returns its -$widget argument. At the time this command is invoked, -there must not exist a window named $widget, but -$widget's parent must exist. - -A button is a widget that displays a textual string, bitmap or image. -If text is displayed, it must all be in a single font, but it -can occupy multiple lines on the screen (if it contains newlines -or if wrapping occurs because of the B<-wraplength> option) and -one of the characters may optionally be underlined using the -B<-underline> option. -It can display itself in either of three different ways, according -to -the B<-state> option; -it can be made to appear raised, sunken, or flat; -and it can be made to flash. When a user invokes the -button (by pressing mouse button 1 with the cursor over the -button), then the L<perl/Tk callback|Tk::callbacks> specified in the B<-command> -option is invoked. - -=head1 WIDGET METHODS - -The B<Button> method creates a widget object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. -The widget also inherits all the methods provided by the generic -L<Tk::Widget|Tk::Widget> class. - -The following additional methods are available for button widgets: - -=over 4 - -=item I<$button>-E<gt>B<flash> - -Flash the button. This is accomplished by redisplaying the button -several times, alternating between active and normal colors. At -the end of the flash the button is left in the same normal/active -state as when the command was invoked. -This command is ignored if the button's state is B<disabled>. - -=item I<$button>-E<gt>B<invoke> - -Invoke the L<callback|Tk::callbacks> associated with the buttons -B<-command> option, if there is one. -The return value is the return value from the callback, or the -undefined value if there is no callback associated with the button. -This command is ignored if the button's state is B<disabled>. - -=back - -=head1 DEFAULT BINDINGS - -Tk automatically creates class bindings for buttons that give them -default behavior: - -=over 4 - -=item [1] - -A button activates whenever the mouse passes over it and deactivates -whenever the mouse leaves the button. -Under Windows, this binding is only active when mouse button 1 has -been pressed over the button. - -=item [2] - -A button's relief is changed to sunken whenever mouse button 1 is -pressed over the button, and the relief is restored to its original -value when button 1 is later released. - -=item [3] - -If mouse button 1 is pressed over a button and later released over -the button, the button is invoked. However, if the mouse is not -over the button when button 1 is released, then no invocation occurs. - -=item [4] - -When a button has the input focus, the space key causes the button -to be invoked. - -If the button's state is B<disabled> then none of the above -actions occur: the button is completely non-responsive. - -The behavior of buttons can be changed by defining new bindings for -individual widgets or by redefining the class bindings. - -=back - -=head1 KEYWORDS - -button, widget - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Canvas.pod b/Master/tlpkg/tlperl/lib/Tk/Canvas.pod deleted file mode 100644 index daf4cf7f32e..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Canvas.pod +++ /dev/null @@ -1,2394 +0,0 @@ -# Copyright (c) 1992-1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# - -=head1 NAME - -Tk::Canvas - Create and manipulate Canvas widgets - -=for category Tk Widget Classes - -=head1 SYNOPSIS - -I<$canvas> = I<$parent>-E<gt>B<Canvas>(?I<options>?); - -=head1 STANDARD OPTIONS - -B<-background> B<-highlightthickness> B<-insertwidth> B<-state> -B<-borderwidth> B<-insertbackground> B<-relief> B<-tile> -B<-cursor> B<-insertborderwidth> B<-selectbackground> B<-takefocus> -B<-highlightbackground> B<-insertofftime> B<-selectborderwidth> B<-xscrollcommand> -B<-highlightcolor> B<-insertontime> B<-selectforeground> B<-yscrollcommand> - -=head1 WIDGET-SPECIFIC OPTIONS - -=over 4 - -=item Name: B<closeEnough> - -=item Class: B<CloseEnough> - -=item Switch: B<-closeenough> - -Specifies a floating-point value indicating how close the mouse cursor -must be to an item before it is considered to be ``inside'' the item. -Defaults to 1.0. - -=item Name: B<confine> - -=item Class: B<Confine> - -=item Switch: B<-confine> - -Specifies a boolean value that indicates whether or not it should be -allowable to set the canvas's view outside the region defined by the -B<scrollRegion> argument. -Defaults to true, which means that the view will -be constrained within the scroll region. - -=item Name: B<height> - -=item Class: B<Height> - -=item Switch: B<-height> - -Specifies a desired window height that the canvas widget should request from -its geometry manager. The value may be specified in any -of the forms described in the L<"COORDINATES"> section below. - -=item Name: B<scrollRegion> - -=item Class: B<ScrollRegion> - -=item Switch: B<-scrollregion> - -Specifies a list with four coordinates describing the left, top, right, and -bottom coordinates of a rectangular region. -This region is used for scrolling purposes and is considered to be -the boundary of the information in the canvas. -Each of the coordinates may be specified -in any of the forms given in the L<"COORDINATES"> section below. - -=item Name: B<state> - -=item Class: B<State> - -=item Switch: B<-state> - -Modifies the default state of the canvas where I<state> may be set to one of: -normal, disabled, or hidden. Individual canvas objects all have their own -state option, which overrides the default state. Many options can take -separate specifications such that the appearance of the item can be different -in different situations. The options that start with "active" control the -appearence when the mouse pointer is over it, while the option starting -with "disabled" controls the appearence when the state is disabled. - -=item Name: B<width> - -=item Class: B<width> - -=item Switch: B<-width> - -Specifies a desired window width that the canvas widget should request from -its geometry manager. The value may be specified in any -of the forms described in the L<"COORDINATES"> section below. - -=item Name: B<xScrollIncrement> - -=item Class: B<ScrollIncrement> - -=item Switch: B<-xscrollincrement> - -Specifies an increment for horizontal scrolling, in any of the usual forms -permitted for screen distances. If the value of this option is greater -than zero, the horizontal view in the window will be constrained so that -the canvas x coordinate at the left edge of the window is always an even -multiple of B<xScrollIncrement>; furthermore, the units for scrolling -(e.g., the change in view when the left and right arrows of a scrollbar -are selected) will also be B<xScrollIncrement>. If the value of -this option is less than or equal to zero, then horizontal scrolling -is unconstrained. - -=item Name: B<yScrollIncrement> - -=item Class: B<ScrollIncrement> - -=item Switch: B<-yscrollincrement> - -Specifies an increment for vertical scrolling, in any of the usual forms -permitted for screen distances. If the value of this option is greater -than zero, the vertical view in the window will be constrained so that -the canvas y coordinate at the top edge of the window is always an even -multiple of B<yScrollIncrement>; furthermore, the units for scrolling -(e.g., the change in view when the top and bottom arrows of a scrollbar -are selected) will also be B<yScrollIncrement>. If the value of -this option is less than or equal to zero, then vertical scrolling -is unconstrained. - -=back - -=head1 DESCRIPTION - -The B<Canvas> method creates a new window (given -by the $canvas argument) and makes it into a canvas widget. -Additional options, described above, may be specified on the -command line or in the option database -to configure aspects of the canvas such as its colors and 3-D relief. -The B<canvas> command returns its -$canvas argument. At the time this command is invoked, -there must not exist a window named $canvas, but -$canvas's parent must exist. - -Canvas widgets implement structured graphics. -A canvas displays any number of I<items>, which may be things like -rectangles, circles, lines, and text. -Items may be manipulated (e.g. moved or re-colored) and -L<callbacks|Tk::callbacks> may -be associated with items in much the same way that the L<bind|Tk::bind> -method allows callbacks to be bound to widgets. For example, -a particular callback may be associated with the B<E<lt>Button-1E<gt>> event -so that the callback is invoked whenever button 1 is pressed with -the mouse cursor over an item. -This means that items in a canvas can have behaviors defined by -the Callbacks bound to them. - -=head1 DISPLAY LIST - -The items in a canvas are ordered for purposes of display, -with the first item in the display list being displayed -first, followed by the next item in the list, and so on. -Items later in the display list obscure those that are -earlier in the display list and are sometimes referred to -as being I<``on top''> of earlier items. -When a new item is created it is placed at the end of the -display list, on top of everything else. -Widget methods may be used to re-arrange the order of the -display list. - -Window items are an exception to the above rules. The underlying -window systems require them always to be drawn on top of other items. -In addition, the stacking order of window items -is not affected by any of the canvas methods; you must use -the L<raise|Tk::Widget> and L<lower|Tk::Widget> Tk widget methods instead. - -=head1 ITEM IDS AND TAGS - -Items in a canvas widget may be named in either of two ways: -by id or by tag. -Each item has a unique identifying number which is assigned to -that item when it is created. The id of an item never changes -and id numbers are never re-used within the lifetime of a -canvas widget. - -Each item may also have any number of I<tags> associated -with it. A tag is just a string of characters, and it may -take any form except that of an integer. -For example, ``x123'' is OK but ``123'' isn't. -The same tag may be associated with many different items. -This is commonly done to group items in various interesting -ways; for example, all selected items might be given the -tag ``selected''. - -The tag B<all> is implicitly associated with every item -in the canvas; it may be used to invoke operations on -all the items in the canvas. - -The tag B<current> is managed automatically by Tk; -it applies to the I<current item>, which is the -topmost item whose drawn area covers the position of -the mouse cursor. -If the mouse is not in the canvas widget or is not over -an item, then no item has the B<current> tag. - -When specifying items in canvas methods, if the -specifier is an integer then it is assumed to refer to -the single item with that id. -If the specifier is not an integer, then it is assumed to -refer to all of the items in the canvas that have a tag -matching the specifier. -The symbol I<tagOrId> is used below to indicate that -an argument specifies either an id that selects a single -item or a tag that selects zero or more items. - -I<tagOrId> may contain a logical expressions of -tags by using operators: 'E<amp>E<amp>', '||', '^' '!', and parenthezised -subexpressions. For example: - -$c-E<gt>find('withtag', '(aE<amp>E<amp>!b)|(!aE<amp>E<amp>b)'); - -or equivalently: - -$c-E<gt>find('withtag', 'a^b'); - -will find only those items with either "a" or "b" tags, but not both. - -Some methods only operate on a single item at a -time; if I<tagOrId> is specified in a way that -names multiple items, then the normal behavior is for -the methods is to use the first (lowest) of these items in -the display list that is suitable for the method. -Exceptions are noted in the method descriptions -below. - -=head1 COORDINATES - -All coordinates related to canvases are stored as floating-point -numbers. -Coordinates and distances are specified in screen units, -which are floating-point numbers optionally followed -by one of several letters. -If no letter is supplied then the distance is in pixels. -If the letter is B<m> then the distance is in millimeters on -the screen; if it is B<c> then the distance is in centimeters; -B<i> means inches, and B<p> means printers points (1/72 inch). -Larger y-coordinates refer to points lower on the screen; larger -x-coordinates refer to points farther to the right. - -=head1 TRANSFORMATIONS - -Normally the origin of the canvas coordinate system is at the -upper-left corner of the window containing the canvas. -It is possible to adjust the origin of the canvas -coordinate system relative to the origin of the window using the -B<xview> and B<yview> methods; this is typically used -for scrolling. -Canvases do not support scaling or rotation of the canvas coordinate -system relative to the window coordinate system. - -Individual items may be moved or scaled using methods -described below, but they may not be rotated. - -=head1 INDICES - -Text items support the notion of an I<index> for identifying -particular positions within the item. - -Indices are used for methods such as inserting text, deleting -a range of characters, and setting the insertion cursor position. -An index may be specified in any of a number of ways, and -different types of items may support different forms for -specifying indices. - -In a similar fashion, line and polygon items support I<index> for -identifying, inserting and deleting subsets of their coordinates. -Indices are used for commands such as inserting or deleting -a range of characters or coordinates, and setting the insertion -cursor position. An index may be specified in any of a number -of ways, and different types of items may support different forms -for specifying indices. - -Text items support the following forms for an index; if you -define new types of text-like items, it would be advisable to -support as many of these forms as practical. -Note that it is possible to refer to the character just after -the last one in the text item; this is necessary for such -tasks as inserting new text at the end of the item. -Lines and Polygons don't support the insertion cursor -and the selection. Their indices are supposed to be even -always, because coordinates always appear in pairs. - -=over 4 - -=item I<number> - -A decimal number giving the position of the desired character -within the text item. -0 refers to the first character, 1 to the next character, and -so on. If indexes are odd for lines and polygons, they will be -automatically decremented by one. -A number less than 0 is treated as if it were zero, and a -number greater than the length of the text item is treated -as if it were equal to the length of the text item. For -polygons, numbers less than 0 or greater then the length -of the coordinate list will be adjusted by adding or substracting -the length until the result is between zero and the length, -inclusive. - -=item B<end> - -Refers to the character or coordinate just after the last one -in the item (same as the number of characters or coordinates -in the item). - -=item B<insert> - -Refers to the character just before which the insertion cursor -is drawn in this item. Not valid for lines and polygons. - -=item B<sel.first> - -Refers to the first selected character in the item. -If the selection isn't in this item then this form is illegal. - -=item B<sel.last> - -Refers to the last selected character in the item. -If the selection isn't in this item then this form is illegal. - -=item B<[>I<x,y>B<]> - -Refers to the character or coordinate at the point given by I<x> and -I<y>, where I<x> and I<y> are specified in the coordinate -system of the canvas. -If I<x> and I<y> lie outside the coordinates covered by the -text item, then they refer to the first or last character in the -line that is closest to the given point. -The Tcl string form "@x,y" is also allowed. - -=back - -=head1 DASH PATTERNS - -Many items support the notion of an dash pattern for outlines. - -The first possible syntax is a list of integers. Each element -represents the number of pixels of a line segment. Only the odd -segments are drawn using the "outline" color. The other segments -are drawn transparent. - -The second possible syntax is a character list containing only -5 possible characters B<[.,-_ ]>, with the first 4 characters -producing a segment of length 1 to 4, respectively, followed -by a transparent segment of length 2. The space can be used -repeatedly to enlarge the space between other line elements -by 1, and can not occur as the first position in the string. -The main difference of this syntax with the previous one is -that it it shape-conserving. This means that all values in the dash -list will be multiplied by the line width before display. This -assures that "." will always be displayed as a dot and "-" -always as a dash regardless of the line width. - -Some examples, for a line width of 2: - - -dash . = -dash [2,4] - -dash - = -dash [6,4] - -dash -. = -dash [6,4,2,4] - -dash -.. = -dash [6,4,2,4,2,4] - -dash '. ' = -dash [2,8] - -dash ',' = -dash [4,4] - -On systems where only a limited set of dash patterns is available, -the dash pattern will be displayed as the closest available dash -pattern. For example, on Windows only the first 4 of the -above examples are available. The last 2 examples will be -displayed identically as the first one. - -=head1 WIDGET METHODS - -The B<Canvas> method creates a widget object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. -The widget also inherits all the methods provided by the generic -L<Tk::Widget|Tk::Widget> class. - -The following additional methods are available for canvas widgets: - -=over 4 - -=item I<$canvas>-E<gt>B<addtag>(I<tag, searchSpec, >?I<arg, arg, ...>?) - -For each item that meets the constraints specified by -I<searchSpec> and the I<arg>s, add -I<tag> to the list of tags associated with the item if it -isn't already present on that list. -It is possible that no items will satisfy the constraints -given by I<searchSpec> and I<arg>s, in which case the -method has no effect. -This command returns an empty string as result. -I<SearchSpec> and I<arg>'s may take any of the following -forms: - -=over 8 - -=item B<above >I<tagOrId> - -Selects the item just after (above) the one given by I<tagOrId> -in the display list. -If I<tagOrId> denotes more than one item, then the last (topmost) -of these items in the display list is used. - -=item B<all> - -Selects all the items in the canvas. - -=item B<below >I<tagOrId> - -Selects the item just before (below) the one given by I<tagOrId> -in the display list. -If I<tagOrId> denotes more than one item, then the first (lowest) -of these items in the display list is used. - -=item B<closest >I<x y >?I<halo>? ?I<start>? - -Selects the item closest to the point given by I<x> and I<y>. -If more than one item is at the same closest distance (e.g. two -items overlap the point), then the top-most of these items (the -last one in the display list) is used. -If I<halo> is specified, then it must be a non-negative -value. -Any item closer than I<halo> to the point is considered to -overlap it. -The I<start> argument may be used to step circularly through -all the closest items. -If I<start> is specified, it names an item using a tag or id -(if by tag, it selects the first item in the display list with -the given tag). -Instead of selecting the topmost closest item, this form will -select the topmost closest item that is below I<start> in -the display list; if no such item exists, then the selection -behaves as if the I<start> argument had not been specified. - -=item B<enclosed> I<x1> I<y1> I<x2> I<y2> - -Selects all the items completely enclosed within the rectangular -region given by I<x1>, I<y1>, I<x2>, and I<y2>. -I<X1> must be no greater then I<x2> and I<y1> must be -no greater than I<y2>. - -=item B<overlapping> I<x1> I<y1> I<x2> I<y2> - -Selects all the items that overlap or are enclosed within the -rectangular region given by I<x1>, I<y1>, I<x2>, -and I<y2>. -I<X1> must be no greater then I<x2> and I<y1> must be -no greater than I<y2>. - -=item B<withtag >I<tagOrId> - -Selects all the items given by I<tagOrId>. - -=back - -=item I<$canvas>-E<gt>B<bbox>(I<tagOrId, >?I<tagOrId, tagOrId, ...>?) - -Returns a list with four elements giving an approximate bounding box -for all the items named by the I<tagOrId> arguments. -The list has the form ``I<x1 y1 x2 y2>'' such that the drawn -areas of all the named elements are within the region bounded by -I<x1> on the left, I<x2> on the right, I<y1> on the top, -and I<y2> on the bottom. -The return value may overestimate the actual bounding box by -a few pixels. -If no items match any of the I<tagOrId> arguments or if the -matching items have empty bounding boxes (i.e. they have nothing -to display) -then an empty string is returned. - -=item I<$canvas>-E<gt>B<bind>(I<tagOrId>?, I<sequence>? ?,I<callback>?) - -This method associates I<callback> with all the items given by -I<tagOrId> such that whenever the event sequence given by -I<sequence> occurs for one of the items the callback will -be invoked. -This method is similar to the B<bind> method except that -it operates on items in a canvas rather than entire widgets. -See L<Tk::bind> for complete details -on the syntax of I<sequence> and the substitutions performed -on I<callback> before invoking it. -If all arguments are specified then a new binding is created, replacing -any existing binding for the same I<sequence> and I<tagOrId> -(if the first character of I<command> is ``+'' then I<command> -augments an existing binding rather than replacing it). -In this case the return value is an empty string. -If I<callback> is omitted then the method returns the I<callback> -associated with I<tagOrId> and I<sequence> (an error occurs -if there is no such binding). -If both I<callback> and I<sequence> are omitted then the method -returns a list of all the sequences for which bindings have been -defined for I<tagOrId>. - -=over 8 - -The only events for which bindings may be specified are those related to -the mouse and keyboard (such as B<Enter>, B<Leave>, -B<ButtonPress>, B<Motion>, and B<KeyPress>) or virtual events. -The handling of events in canvases uses the current item defined -in L<"ITEM IDS AND TAGS"> above. B<Enter> and B<Leave> events trigger for an -item when it becomes the current item or ceases to be the current item; -note that these events are different than B<Enter> and B<Leave> -events for windows. Mouse-related events are directed to the current -item, if any. Keyboard-related events are directed to the focus item, if -any (see the L<focus|/focus> method below for more on this). If a -virtual event is used in a binding, that binding can trigger only if the -virtual event is defined by an underlying mouse-related or -keyboard-related event. - -It is possible for multiple bindings to match a particular event. -This could occur, for example, if one binding is associated with the -item's id and another is associated with one of the item's tags. -When this occurs, all of the matching bindings are invoked. -A binding associated with the B<all> tag is invoked first, -followed by one binding for each of the item's tags (in order), -followed by a binding associated with the item's id. -If there are multiple matching bindings for a single tag, -then only the most specific binding is invoked. -A B<continue> in a callback terminates that -subroutine, and a B<break> method terminates that subroutine -and skips any remaining callbacks for the event, just as for the -B<bind> method. - -If bindings have been created for a canvas window using the B<CanvasBind> -method, then they are invoked in addition to bindings created for -the canvas's items using the B<bind> method. -The bindings for items will be invoked before any of the bindings -for the window as a whole. - -=back - -=item I<$canvas>-E<gt>B<canvasx>(I<screenx>?, I<gridspacing>?) - -Given a window x-coordinate in the canvas I<screenx>, this method returns -the canvas x-coordinate that is displayed at that location. -If I<gridspacing> is specified, then the canvas coordinate is -rounded to the nearest multiple of I<gridspacing> units. - -=item I<$canvas>-E<gt>B<canvasy>(I<screeny, >?I<gridspacing>?) - -Given a window y-coordinate in the canvas I<screeny> this method returns -the canvas y-coordinate that is displayed at that location. -If I<gridspacing> is specified, then the canvas coordinate is -rounded to the nearest multiple of I<gridspacing> units. - -=item I<$canvas>-E<gt>B<coords>(I<tagOrId >?I<x0,y0 ...>?) - -Query or modify the coordinates that define an item. -If no coordinates are specified, this method returns a list -whose elements are the coordinates of the item named by -I<tagOrId>. -If coordinates are specified, then they replace the current -coordinates for the named item. -If I<tagOrId> refers to multiple items, then -the first one in the display list is used. - -=item I<$canvas>-E<gt>B<create>(I<type, x, y, >?I<x, y, ...>?, ?I<option, value, ...>?) - -Create a new item in I<$canvas> of type I<type>. -The exact format of the arguments after B<type> depends -on B<type>, but usually they consist of the coordinates for -one or more points, followed by specifications for zero or -more item options. -See the subsections on individual item types below for more -on the syntax of this method. -This method returns the id for the new item. - -=item I<$canvas>-E<gt>B<dchars>(I<tagOrId, first, >?I<last>?) - -For each item given by I<tagOrId>, delete the characters, or coordinates, -in the range given by I<first> and I<last>, inclusive. -If some of the items given by I<tagOrId> don't support -Text items interpret I<first> and I<last> as indices to a character, -line and polygon items interpret them indices to a coordinate (an x,y pair). -within the item(s) as described in L<"INDICES"> above. -If I<last> is omitted, it defaults to I<first>. -This method returns an empty string. - -=item I<$canvas>-E<gt>B<delete>(?I<tagOrId, tagOrId, ...>?) - -Delete each of the items given by each I<tagOrId>, and return -an empty string. - -=item I<$canvas>-E<gt>B<dtag>(I<tagOrId, >?I<tagToDelete>?) - -For each of the items given by I<tagOrId>, delete the -tag given by I<tagToDelete> from the list of those -associated with the item. -If an item doesn't have the tag I<tagToDelete> then -the item is unaffected by the method. -If I<tagToDelete> is omitted then it defaults to I<tagOrId>. -This method returns an empty string. - -=item I<$canvas>-E<gt>B<find>(I<searchCommand, >?I<arg, arg, ...>?) - -This method returns a list consisting of all the items that -meet the constraints specified by I<searchCommand> and -I<arg>'s. -I<SearchCommand> and I<args> have any of the forms -accepted by the B<addtag> method. -The items are returned in stacking order, with the lowest item first. - -=item focus - -=item I<$canvas>-E<gt>B<focus>(?I<tagOrId>?) - -Set the keyboard focus for the canvas widget to the item given by -I<tagOrId>. -If I<tagOrId> refers to several items, then the focus is set -to the first such item in the display list that supports the -insertion cursor. -If I<tagOrId> doesn't refer to any items, or if none of them -support the insertion cursor, then the focus isn't changed. -If I<tagOrId> is an empty -string, then the focus item is reset so that no item has the focus. -If I<tagOrId> is not specified then the method returns the -id for the item that currently has the focus, or an empty string -if no item has the focus. - -=over 8 - -Once the focus has been set to an item, the item will display -the insertion cursor and all keyboard events will be directed -to that item. -The focus item within a canvas and the focus window on the -screen (set with the B<focus> method) are totally independent: -a given item doesn't actually have the input focus unless (a) -its canvas is the focus window and (b) the item is the focus item -within the canvas. -In most cases it is advisable to follow the B<focus> widget -method with the B<CanvasFocus> method to set the focus window to -the canvas (if it wasn't there already). - -=back - -=item I<$canvas>-E<gt>B<gettags>(I<tagOrId>) - -Return a list whose elements are the tags associated with the -item given by I<tagOrId>. -If I<tagOrId> refers to more than one item, then the tags -are returned from the first such item in the display list. -If I<tagOrId> doesn't refer to any items, or if the item -contains no tags, then an empty string is returned. - -=item I<$canvas>-E<gt>B<icursor>(I<tagOrId, index>) - -Set the position of the insertion cursor for the item(s) given by I<tagOrId> -to just before the character whose position is given by I<index>. -If some or all of the items given by I<tagOrId> don't support -an insertion cursor then this method has no effect on them. -See L<"INDICES"> above for a description of the -legal forms for I<index>. -Note: the insertion cursor is only displayed in an item if -that item currently has the keyboard focus (see the widget -method B<focus>, below), but the cursor position may -be set even when the item doesn't have the focus. -This method returns an empty string. - -=item I<$canvas>-E<gt>B<index>(I<tagOrId, index>) - -This method returns a decimal string giving the numerical index -within I<tagOrId> corresponding to I<index>. -I<Index> gives a textual description of the desired position -as described in L<"INDICES"> above. -Text items interpret I<index> as an index to a character, -line and polygon items interpret it as an index to a coordinate (an x,y pair). -The return value is guaranteed to lie between 0 and the number -of characters, or coordinates, within the item, inclusive. -If I<tagOrId> refers to multiple items, then the index -is processed in the first of these items that supports indexing -operations (in display list order). - -=item I<$canvas>-E<gt>B<insert>(I<tagOrId, beforeThis, string>) - -For each of the items given by I<tagOrId>, if the item supports -text or coordinate, insertion then I<string> is inserted into the item's -text just before the character, or coordinate, whose index is I<beforeThis>. -Text items interpret I<beforethis> as an index to a character, -line and polygon items interpret it as an index to a coordinate (an x,y pair). -For lines and polygons the I<string> must be a valid coordinate -sequence. -See L<"INDICES"> above for information about the forms allowed -for I<beforeThis>. -This method returns an empty string. - -=item I<$canvas>-E<gt>B<itemcget>(I<tagOrId, >I<option>) - -Returns the current value of the configuration option for the -item given by I<tagOrId> whose name is I<option>. -This method is similar to the L<cget|Tk::option> method except that -it applies to a particular item rather than the widget as a whole. -I<Option> may have any of the values accepted by the B<create> -method when the item was created. -If I<tagOrId> is a tag that refers to more than one item, -the first (lowest) such item is used. - -=item I<$canvas>-E<gt>B<itemconfigure>(I<tagOrId, >?I<option>?, ?I<value>?, ?I<option, value, ...>?) - -This method is similar to the L<configure|Tk::option> method except -that it modifies item-specific options for the items given by -I<tagOrId> instead of modifying options for the overall -canvas widget. -If no I<option> is specified, returns a list describing all of -the available options for the first item given by I<tagOrId> -(see L<Tk::options> for -information on the format of this list). If I<option> is specified -with no I<value>, then the method returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no I<option> is specified). If -one or more I<option-value> pairs are specified, then the method -modifies the given widget option(s) to have the given value(s) in -each of the items given by I<tagOrId>; in -this case the method returns an empty string. -The I<option>s and I<value>s are the same as those permissible -in the B<create> method when the item(s) were created; -see the sections describing individual item types below for details -on the legal options. - -=item I<$canvas>-E<gt>B<lower>(I<tagOrId, >?I<belowThis>?) - -Move all of the items given by I<tagOrId> to a new position -in the display list just before the item given by I<belowThis>. -If I<tagOrId> refers to more than one item then all are moved -but the relative order of the moved items will not be changed. -I<BelowThis> is a tag or id; if it refers to more than one -item then the first (lowest) of these items in the display list is used -as the destination location for the moved items. -Note: this method has no effect on window items. Window items always -obscure other item types, and the stacking order of window items is -determined by the B<raise> and B<lower> methods of the widget, not the -B<raise> and B<lower> methods for canvases. -This method returns an empty string. - -=item I<$canvas>-E<gt>B<move>(I<tagOrId, xAmount, yAmount>) - -Move each of the items given by I<tagOrId> in the canvas coordinate -space by adding I<xAmount> to the x-coordinate of each point -associated with the item and I<yAmount> to the y-coordinate of -each point associated with the item. -This method returns an empty string. - -=item I<$canvas>-E<gt>B<postscript>(?I<option, value, option, value, ...>?) - -Generate a Postscript representation for part or all of the canvas. -If the B<-file> option is specified then the Postscript is written -to a file and an empty string is returned; otherwise the Postscript -is returned as the result of the method. -If the interpreter that owns the canvas is marked as safe, the operation -will fail because safe interpreters are not allowed to write files. -If the B<-channel> option is specified, the argument denotes the name -of a channel already opened for writing. The Postscript is written to -that channel, and the channel is left open for further writing at the end -of the operation. -The Postscript is created in Encapsulated Postscript form using -version 3.0 of the Document Structuring Conventions. -Note: by default Postscript is only generated for information that -appears in the canvas's window on the screen. If the canvas is -freshly created it may still have its initial size of 1x1 pixel -so nothing will appear in the Postscript. To get around this problem -either invoke the B<update> method to wait for the canvas window -to reach its final size, or else use the B<-width> and B<-height> -options to specify the area of the canvas to print. -The I<option>-I<value> argument pairs provide additional -information to control the generation of Postscript. The following -options are supported: - -=over 8 - -=item B<-colormap> =E<gt> I<hashRef> - -I<HashRef> must be a reference to a hash variable or an anonymous hash -that specifies a color mapping to use in the Postscript. -Each value of the hash must consist of Postscript -code to set a particular color value (e.g. ``B<1.0 1.0 0.0 setrgbcolor>''). -When outputting color information in the Postscript, Tk checks -to see if there is a key in the hash with the same -name as the color. -If so, Tk uses the value of the element as the Postscript method -to set the color. -If this option hasn't been specified, or if there isn't a key -in I<hashRef> for a given color, then Tk uses the red, green, -and blue intensities from the X color. - -=item B<-colormode> =E<gt> I<mode> - -Specifies how to output color information. I<Mode> must be either -B<color> (for full color output), B<gray> (convert all colors -to their gray-scale equivalents) or B<mono> (convert all colors -to black or white). - -=item B<-file> =E<gt> I<fileName> - -Specifies the name of the file in which to write the Postscript. -If this option isn't specified then the Postscript is returned as the -result of the method instead of being written to a file. - -=item B<-fontmap> =E<gt> I<hashRef> - -I<HashRef> must be a reference to a hash variable or an anonymous hash -that specifies a font mapping to use in the Postscript. -Each value of the hash must consist of an array reference with -two elements, which are the name and point size of a Postscript font. -When outputting Postscript commands for a particular font, Tk -checks to see if I<hashRef> contains a value with the same -name as the font. -If there is such an element, then the font information contained in -that element is used in the Postscript. -Otherwise Tk attempts to guess what Postscript font to use. -Tk's guesses generally only work for well-known fonts such as -Times and Helvetica and Courier, and only if the X font name does not -omit any dashes up through the point size. -For example, B<-*-Courier-Bold-R-Normal--*-120-*> will work but -B<*Courier-Bold-R-Normal*120*> will not; Tk needs the dashes to -parse the font name). - -=item B<-height> =E<gt> I<size> - -Specifies the height of the area of the canvas to print. -Defaults to the height of the canvas window. - -=item B<-pageanchor> =E<gt> I<anchor> - -Specifies which point of the printed area of the canvas should appear over -the positioning point on the page (which is given by the B<-pagex> -and B<-pagey> options). -For example, B<-pageanchor>=>B<n> means that the top center of the -area of the canvas being printed (as it appears in the canvas window) -should be over the positioning point. Defaults to B<center>. - -=item B<-pageheight> =E<gt> I<size> - -Specifies that the Postscript should be scaled in both x and y so -that the printed area is I<size> high on the Postscript page. -I<Size> consists of a floating-point number followed by -B<c> for centimeters, B<i> for inches, B<m> for millimeters, -or B<p> or nothing for printer's points (1/72 inch). -Defaults to the height of the printed area on the screen. -If both B<-pageheight> and B<-pagewidth> are specified then -the scale factor from B<-pagewidth> is used (non-uniform scaling -is not implemented). - -=item B<-pagewidth> =E<gt> I<size> - -Specifies that the Postscript should be scaled in both x and y so -that the printed area is I<size> wide on the Postscript page. -I<Size> has the same form as for B<-pageheight>. -Defaults to the width of the printed area on the screen. -If both B<-pageheight> and B<-pagewidth> are specified then -the scale factor from B<-pagewidth> is used (non-uniform scaling -is not implemented). - -=item B<-pagex> =E<gt> I<position> - -I<Position> gives the x-coordinate of the positioning point on -the Postscript page, using any of the forms allowed for B<-pageheight>. -Used in conjunction with the B<-pagey> and B<-pageanchor> options -to determine where the printed area appears on the Postscript page. -Defaults to the center of the page. - -=item B<-pagey> =E<gt> I<position> - -I<Position> gives the y-coordinate of the positioning point on -the Postscript page, using any of the forms allowed for B<-pageheight>. -Used in conjunction with the B<-pagex> and B<-pageanchor> options -to determine where the printed area appears on the Postscript page. -Defaults to the center of the page. - -=item B<-rotate> =E<gt> I<boolean> - -I<Boolean> specifies whether the printed area is to be rotated 90 -degrees. -In non-rotated output the x-axis of the printed area runs along -the short dimension of the page (``portrait'' orientation); -in rotated output the x-axis runs along the long dimension of the -page (``landscape'' orientation). -Defaults to non-rotated. - -=item B<-width> =E<gt> I<size> - -Specifies the width of the area of the canvas to print. -Defaults to the width of the canvas window. - -=item B<-x> => I<position> - -Specifies the x-coordinate of the left edge of the area of the -canvas that is to be printed, in canvas coordinates, not window -coordinates. -Defaults to the coordinate of the left edge of the window. - -=item B<-y> => I<position> - -Specifies the y-coordinate of the top edge of the area of the -canvas that is to be printed, in canvas coordinates, not window -coordinates. -Defaults to the coordinate of the top edge of the window. - -=back - -=item I<$canvas>-E<gt>B<raise>(I<tagOrId, >?I<aboveThis>?) - -Move all of the items given by I<tagOrId> to a new position -in the display list just after the item given by I<aboveThis>. -If I<tagOrId> refers to more than one item then all are moved -but the relative order of the moved items will not be changed. -I<AboveThis> is a tag or id; if it refers to more than one -item then the last (topmost) of these items in the display list is used -as the destination location for the moved items. -Note: this method has no effect on window items. Window items always -obscure other item types, and the stacking order of window items is -determined by the B<raise> and B<lower> widget commands, not the -B<raise> and B<lower> methods for canvases. -This method returns an empty string. - -=item I<$canvas>-E<gt>B<scale>(I<tagOrId, xOrigin, yOrigin, xScale, yScale>) - -Rescale all of the items given by I<tagOrId> in canvas coordinate -space. -I<XOrigin> and I<yOrigin> identify the origin for the scaling -operation and I<xScale> and I<yScale> identify the scale -factors for x- and y-coordinates, respectively (a scale factor of -1.0 implies no change to that coordinate). -For each of the points defining each item, the x-coordinate is -adjusted to change the distance from I<xOrigin> by a factor -of I<xScale>. -Similarly, each y-coordinate is adjusted to change the distance -from I<yOrigin> by a factor of I<yScale>. -This method returns an empty string. - -=item I<$canvas>-E<gt>B<scan>(I<option, args>) - -This method is used to implement scanning on canvases. It has -two forms, depending on I<option>: - -=over 8 - -=item I<$canvas>-E<gt>B<scanMark>(I<x, y>) - -Records I<x> and I<y> and the canvas's current view; used -in conjunction with later B<scanDragto> method. -Typically this method is associated with a mouse button press in -the widget and I<x> and I<y> are the coordinates of the -mouse. It returns an empty string. - -=item I<$canvas>-E<gt>B<scanDragto>(I<x, y, ?gain?>.) - -This method computes the difference between its I<x> and I<y> -arguments (which are typically mouse coordinates) and the I<x> and -I<y> arguments to the last B<scanMark> method for the widget. -It then adjusts the view by 10 times the -difference in coordinates. This method is typically associated -It then adjusts the view by I<gain> times the -difference in coordinates, where I<gain> defaults to 10. -This command is typically associated -with mouse motion events in the widget, to produce the effect of -dragging the canvas at high speed through its window. The return -value is an empty string. - -=back - -=item I<$canvas>-E<gt>B<select>(I<option, >?I<tagOrId, arg>?) - -Manipulates the selection in one of several ways, depending on -I<option>. -The method may take any of the forms described below. -In all of the descriptions below, I<tagOrId> must refer to -an item that supports indexing and selection; if it refers to -multiple items then the first of -these that supports indexing and the selection is used. -I<Index> gives a textual description of a position -within I<tagOrId>, as described in L<"INDICES"> above. - -=over 8 - -=item I<$canvas>-E<gt>B<selectAdjust>(I<tagOrId, index>) - -Locate the end of the selection in I<tagOrId> nearest -to the character given by I<index>, and adjust that -end of the selection to be at I<index> (i.e. including -but not going beyond I<index>). -The other end of the selection is made the anchor point -for future B<selectTo> method calls. -If the selection isn't currently in I<tagOrId> then -this method behaves the same as the B<selectTo> widget -method. -Returns an empty string. - -=item I<$canvas>-E<gt>B<selectClear> - -Clear the selection if it is in this widget. -If the selection isn't in this widget then the method -has no effect. -Returns an empty string. - -=item I<$canvas>-E<gt>B<selectFrom>(I<tagOrId, index>) - -Set the selection anchor point for the widget to be just -before the character -given by I<index> in the item given by I<tagOrId>. -This method doesn't change the selection; it just sets -the fixed end of the selection for future B<selectTo> -method calls. -Returns an empty string. - -=item I<$canvas>-E<gt>B<selectItem> - -Returns the id of the selected item, if the selection is in an -item in this canvas. -If the selection is not in this canvas then an empty string -is returned. - -=item I<$canvas>-E<gt>B<selectTo>(I<tagOrId, index>) - -Set the selection to consist of those characters of I<tagOrId> -between the selection anchor point and -I<index>. -The new selection will include the character given by I<index>; -it will include the character given by the anchor point only if -I<index> is greater than or equal to the anchor point. -The anchor point is determined by the most recent B<selectAdjust> -or B<selectFrom> method calls for this widget. -If the selection anchor point for the widget isn't currently in -I<tagOrId>, then it is set to the same character given -by I<index>. -Returns an empty string. - -=back - -=item I<$canvas>-E<gt>B<type>(I<tagOrId>) - -Returns the type of the item given by I<tagOrId>, such as -B<rectangle> or B<text>. -If I<tagOrId> refers to more than one item, then the type -of the first item in the display list is returned. -If I<tagOrId> doesn't refer to any items at all then -an empty string is returned. - -=item I<$canvas>-E<gt>B<xview>(?I<args>?) - -This method is used to query and change the horizontal position of the -information displayed in the canvas's window. -It can take any of the following forms: - -=over 8 - -=item I<$canvas>-E<gt>B<xview> - -Returns a list containing two elements. -Each element is a real fraction between 0 and 1; together they describe -the horizontal span that is visible in the window. -For example, if the first element is .2 and the second element is .6, -20% of the canvas's area (as defined by the B<-scrollregion> option) -is off-screen to the left, the middle 40% is visible -in the window, and 40% of the canvas is off-screen to the right. -These are the same values passed to scrollbars via the B<-xscrollcommand> -option. - -=item I<$canvas>-E<gt>B<xviewMoveto>(I<fraction>) - -Adjusts the view in the window so that I<fraction> of the -total width of the canvas is off-screen to the left. -I<Fraction> must be a fraction between 0 and 1. - -=item I<$canvas>-E<gt>B<xviewScroll>(I<number, what>) - -This method shifts the view in the window left or right according to -I<number> and I<what>. -I<Number> must be an integer. -I<What> must be either B<units> or B<pages> or an abbreviation -of one of these. -If I<what> is B<units>, the view adjusts left or right in units -of the B<xScrollIncrement> option, if it is greater than zero, -or in units of one-tenth the window's width otherwise. -If I<what is >B<pages> then the view -adjusts in units of nine-tenths the window's width. -If I<number> is negative then information farther to the left -becomes visible; if it is positive then information farther to the right -becomes visible. - -=back - -=item I<$canvas>-E<gt>B<yview>(I<?args>?) - -This method is used to query and change the vertical position of the -information displayed in the canvas's window. -It can take any of the following forms: - -=over 8 - -=item I<$canvas>-E<gt>B<yview> - -Returns a list containing two elements. -Each element is a real fraction between 0 and 1; together they describe -the vertical span that is visible in the window. -For example, if the first element is .6 and the second element is 1.0, -the lowest 40% of the canvas's area (as defined by the B<-scrollregion> -option) is visible in the window. -These are the same values passed to scrollbars via the B<-yscrollcommand> -option. - -=item I<$canvas>-E<gt>B<yviewMoveto>(I<fraction>) - -Adjusts the view in the window so that I<fraction> of the canvas's -area is off-screen to the top. -I<Fraction> is a fraction between 0 and 1. - -=item I<$canvas>-E<gt>B<yviewScroll>(I<number, what>) - -This method adjusts the view in the window up or down according to -I<number> and I<what>. -I<Number> must be an integer. -I<What> must be either B<units> or B<pages>. -If I<what> is B<units>, the view adjusts up or down in units -of the B<yScrollIncrement> option, if it is greater than zero, -or in units of one-tenth the window's height otherwise. -If I<what> is B<pages> then -the view adjusts in units of nine-tenths the window's height. -If I<number> is negative then higher information becomes -visible; if it is positive then lower information -becomes visible. - -=back - -=back - -=head1 OVERVIEW OF ITEM TYPES - -The sections below describe the various types of items supported -by canvas widgets. Each item type is characterized by two things: -first, the form of the B<create> method used to create -instances of the type; and second, a set of configuration options -for items of that type, which may be used in the -B<create> and B<itemconfigure> methods. -Most items don't support indexing or selection or the methods -related to them, such as B<index> and B<insert>. -Where items do support these facilities, it is noted explicitly -in the descriptions below. -At present, text, line and polygon items provide this support. -For lines and polygons the indexing facility is used to manipulate -the coordinates of the item. - -=head1 ARC ITEMS - -Items of type B<arc> appear on the display as arc-shaped regions. -An arc is a section of an oval delimited by two angles (specified -by the B<-start> and B<-extent> options) and displayed in -one of several ways (specified by the B<-style> option). -Arcs are created with methods of the following form: - - $canvas->createArc(x1, y1, x2, y2, ?option, value, option, value, ...?) - -The arguments I<x1>, I<y1>, I<x2>, and I<y2> give -the coordinates of two diagonally opposite corners of a -rectangular region enclosing the oval that defines the arc. -After the coordinates there may be any number of I<option>-I<value> -pairs, each of which sets one of the configuration options -for the item. These same I<option>-I<value> pairs may be -used in B<itemconfigure> methods to change the item's -configuration. -The following options are supported for arcs: - -=over 4 - -=item B<-dash> =E<gt> I<pattern> - -=item B<-activedash> =E<gt> I<pattern> - -=item B<-disableddash> =E<gt> I<pattern> - -This option specifies dash patterns for the normal state, the active -state, and the disabled state of an arc item. -I<pattern> may have any of the forms accepted by B<Tk_GetDash>. -If the dash options are omitted then the default is a solid outline. - -=item B<-dashoffset> =E<gt> I<offset> - -The starting I<offset> into the pattern provided by the -B<-dash> option. -B<-dashoffset> is ignored if there is no B<-dash> pattern. - -=item B<-extent> =E<gt> I<degrees> - -Specifies the size of the angular range occupied by the arc. -The arc's range extends for I<degrees> degrees counter-clockwise -from the starting angle given by the B<-start> option. -I<Degrees> may be negative. -If it is greater than 360 or less than -360, then I<degrees> -modulo 360 is used as the extent. - -=item B<-fill> =E<gt> I<color> - -=item B<-activefill> =E<gt> I<color> - -=item B<-disabledfill> =E<gt> I<color> - -Specifies the color to be used to fill the arc region in its normal, active, and -disabled states, -I<Color> may have any of the forms accepted by B<Tk_GetColor>. -If I<color> is an empty string (the default), then -then the arc will not be filled. - -=item B<-outline> =E<gt> I<color> - -=item B<-activeoutline> =E<gt> I<color> - -=item B<-disabledoutline> =E<gt> I<color> - -This option specifies the color that should be used to draw the -outline of the arc in its normal, active and disabled states. -I<Color> may have any of the forms accepted by B<Tk_GetColor>. -This option defaults to B<black>. If I<color> is specified -as undef then no outline is drawn for the arc. - -=item B<-outlinestipple> =E<gt> I<bitmap> - -=item B<-activeoutlinestipple> =E<gt> I<bitmap> - -=item B<-disabledoutlinestipple> =E<gt> I<bitmap> - -This option specifies stipple patterns that should be used to draw the -outline of the arc in its normal, active and disabled states. -Indicates that the outline for the arc should be drawn with a stipple pattern; -I<bitmap> specifies the stipple pattern to use, in any of the -forms accepted by B<Tk_GetBitmap>. -If the B<-outline> option hasn't been specified then this option -has no effect. -If I<bitmap> is an empty string (the default), then the outline is drawn -in a solid fashion. - -=item B<-start> =E<gt> I<degrees> - -Specifies the beginning of the angular range occupied by the -arc. -I<Degrees> is given in units of degrees measured counter-clockwise -from the 3-o'clock position; it may be either positive or negative. - -=item B<-state> =E<gt> I<state> - -Modifies the state of the arc item where I<state> may be set to one of: -normal, disabled, hidden or "". If set to empty, the state of the canvas -itself is used. An arc item may also be in the "active" -state if the mouse is currently over it. Many options can take -separate specifications in normal, active and disabled states such that the -appearance of the item can be different in each state. - -=item B<-stipple> =E<gt> I<bitmap> - -=item B<-activestipple> =E<gt> I<bitmap> - -=item B<-disabledstipple> =E<gt> I<bitmap> - -This option specifies stipple patterns that should be used to fill the -the arc in its normal, active and disabled states. -I<bitmap> specifies the stipple pattern to use, in any of the -forms accepted by B<Tk_GetBitmap>. -If the B<-fill> option hasn't been specified then this option -has no effect. -If I<bitmap> is an empty string (the default), then filling is done -in a solid fashion. - -=item B<-style> =E<gt> I<type> - -Specifies how to draw the arc. If I<type> is B<pieslice> -(the default) then the arc's region is defined by a section -of the oval's perimeter plus two line segments, one between the center -of the oval and each end of the perimeter section. -If I<type> is B<chord> then the arc's region is defined -by a section of the oval's perimeter plus a single line segment -connecting the two end points of the perimeter section. -If I<type> is B<arc> then the arc's region consists of -a section of the perimeter alone. -In this last case the B<-fill> option is ignored. - -=item B<-tags> =E<gt> I<tagList> - -Specifies a set of tags to apply to the item. -I<TagList> consists of a list of tag names, which replace any -existing tags for the item. -I<TagList> may be an empty list. - -=item B<-updatecommand> =E<gt> I<command> - -Specifies a callback that is to be executed every time -the arc item is updated on the screen. - -=item B<-width> =E<gt> I<outlineWidth> - -=item B<-activewidth> =E<gt> I<outlineWidth> - -=item B<-disabledwidth> =E<gt> I<outlineWidth> - -Specifies the width of the outline to be drawn around -the arc's region, in its normal, active and disabled states. -I<outlineWidth> may be in any of the forms described in -the L<"COORDINATES"> section above. -If the B<-outline> option has been specified as undef -then this option has no effect. -Wide outlines will be drawn centered on the edges of the arc's region. -This option defaults to 1.0. - -=back - -=head1 BITMAP ITEMS - -Items of type B<bitmap> appear on the display as images with -two colors, foreground and background. -Bitmaps are created with methods of the following form: - - $canvas->createBitmap(x, y, ?option, value, option, value, ...?) - -The arguments I<x> and I<y> specify the coordinates of a -point used to position the bitmap on the display (see the B<-anchor> -option below for more information on how bitmaps are displayed). -After the coordinates there may be any number of I<option>-I<value> -pairs, each of which sets one of the configuration options -for the item. These same I<option>-I<value> pairs may be -used in B<itemconfigure> methods to change the item's -configuration. -The following options are supported for bitmaps: - -=over 4 - -=item B<-anchor> =E<gt> I<anchorPos> - -I<AnchorPos> tells how to position the bitmap relative to the -positioning point for the item; it may have any of the forms -accepted by B<Tk_GetAnchor>. For example, if I<anchorPos> -is B<center> then the bitmap is centered on the point; if -I<anchorPos> is B<n> then the bitmap will be drawn so that -its top center point is at the positioning point. -This option defaults to B<center>. - -=item B<-background> =E<gt> I<color> - -=item B<-activebackground> =E<gt> I<color> - -=item B<-disabledbackground> =E<gt> I<color> - -Specifies the color to use for each of the bitmap's '0' valued pixels -in its normal, active and disabled states. -I<Color> may have any of the forms accepted by B<Tk_GetColor>. -If this option isn't specified, or if it is specified as undef, -then nothing is displayed where the bitmap pixels are 0; this -produces a transparent effect. - -=item B<-bitmap> =E<gt> I<bitmap> - -=item B<-activebitmap> =E<gt> I<bitmap> - -=item B<-disabledbitmap> =E<gt> I<bitmap> - -Specifies the bitmaps to display in the item in its normal, active and -disabled states. All bitmaps must have the same width and height. -I<Bitmap> may have any of the forms accepted by B<Tk_GetBitmap>. - -=item B<-foreground> =E<gt> I<color> - -=item B<-activeforeground> =E<gt> I<color> - -=item B<-disabledforeground> =E<gt> I<color> - -Specifies the color to use for each of the bitmap's '1' valued pixels -in its normal, active and disabled states. -I<Color> may have any of the forms accepted by B<Tk_GetColor> and -defaults to B<black>. - -=item B<-state> =E<gt> I<state> - -Modifies the state of the bitmap item where I<state> may be set to one of: -normal, disabled, or hidden. An bitmap item may also be in the "active" -state if the mouse is currently over it. Many options can take -separate specifications in normal, active and disabled states such that the -appearance of the item can be different in each state. - -=item B<-tags> =E<gt> I<tagList> - -Specifies a set of tags to apply to the item. -I<TagList> consists of a list of tag names, which replace any -existing tags for the item. -I<TagList> may be an empty list. - -=item B<-updatecommand> =E<gt> I<command> - -Specifies a callback that is to be executed every time -the bitmap item is updated on the screen. - -=back - -=head1 GRID ITEMS - -Items of type B<grid> are intended for producing a visual reference for -interpreting other items. They can be drawn as either lines (with dash -style) or as rectangular "dots" at each grid point. - -Items of type B<grid> are unlike other items they always cover the -whole of the canvas, but are never enclosed by nor overlap any area -and are not near any point. That is they are intended to be always visible -but not "pickable", as such they do support the "active" state. -They are like other items in that: multiple -grids are permitted, they can be raised and lowered relative to other -items, they can be moved and scaled. As yet grids do not appear in -PostScript output. - -Grids have outline like configure options. Grids are created with methods of the -following form: - - $canvas->createGrid(x1, y1, x2, y2, ?option, value, option, value, ...?) - -The arguments I<x1>, I<y1> give the origin of the grid. I<x2>, and I<y2> give -the coordinates of the next grid point in their respective directions. -After the coordinates there may be any number of I<option>-I<value> -pairs, each of which sets one of the configuration options -for the item. These same I<option>-I<value> pairs may be -used in B<itemconfigure> methods to change the item's -configuration. - -The following options are supported for grids: - -=over 4 - -=item B<-lines> =E<gt> I<boolean> - -If B<-lines> is set to a true value then lines are drawn for both X and Y -grids in the style determined by B<-dash>. Otherwise retangular "dots" -are drawn at each grid point. - -=item B<-dash> =E<gt> I<pattern> - -=item B<-disableddash> =E<gt> I<pattern> - -This option specifies dash patterns for the normal state, -and the disabled state of a grid item. -I<pattern> may have any of the forms accepted by B<Tk_GetDash>. -If the dash options are omitted then the default is a solid outline. - -=item B<-dashoffset> =E<gt> I<offset> - -The starting I<offset> into the pattern provided by the -B<-dash> option. -B<-dashoffset> is ignored if there is no B<-dash> pattern. - -=item B<-color> =E<gt> I<color> - -=item B<-disabledcolor> =E<gt> I<color> - -This option specifies the color that should be used to draw the -outline of the grid in its normal and disabled states. -I<Color> may have any of the forms accepted by B<Tk_GetColor>. -This option defaults to B<black>. -If I<color> is undef then no grid will be drawn. - -=item B<-stipple> =E<gt> I<bitmap> - -=item B<-disabledstipple> =E<gt> I<bitmap> - -This option specifies stipple patterns that should be used to draw the -outline of the rectangle in its normal and disabled states. -I<bitmap> specifies the stipple pattern to use, in any of the -forms accepted by B<Tk_GetBitmap>. -If I<bitmap> is an empty string (the default), then the outline is drawn -in a solid fashion. - -=item B<-state> =E<gt> I<state> - -Modifies the state of the rectangle item where I<state> may be set to one of: -normal, disabled, or hidden. Many options can take -separate specifications in normal and disabled states such that the -appearance of the item can be different in each state. - -=item B<-tags> =E<gt> I<tagList> - -Specifies a set of tags to apply to the item. -I<TagList> consists of a list of tag names, which replace any -existing tags for the item. -I<TagList> may be an empty list. - -=item B<-updatecommand> =E<gt> I<command> - -Specifies a callback that is to be executed every time -the grid item is updated on the screen. - -=item B<-width> =E<gt> I<outlineWidth> - -=item B<-disabledwidth> =E<gt> I<outlineWidth> - -Specifies the width of the lines drawn by the grid or the size (in both X and Y) -of the dots, in its normal and disabled states. -This option defaults to 1.0. - -=back - -=head1 IMAGE ITEMS - -Items of type B<image> are used to display images on a -canvas. -Images are created with methods of the following form: - - $canvas->createImage(x, y, ?option, value, option, value, ...?) - -The arguments I<x> and I<y> specify the coordinates of a -point used to position the image on the display (see the B<-anchor> -option below for more information). -After the coordinates there may be any number of I<option>-I<value> -pairs, each of which sets one of the configuration options -for the item. These same I<option>-I<value> pairs may be -used in B<itemconfigure> methods to change the item's -configuration. -The following options are supported for images: - -=over 4 - -=item B<-anchor> =E<gt> I<anchorPos> - -I<AnchorPos> tells how to position the image relative to the -positioning point for the item; it may have any of the forms -accepted by B<Tk_GetAnchor>. For example, if I<anchorPos> -is B<center> then the image is centered on the point; if -I<anchorPos> is B<n> then the image will be drawn so that -its top center point is at the positioning point. -This option defaults to B<center>. - -=item B<-image> =E<gt> I<name> - -=item B<-activeimage> =E<gt> I<name> - -=item B<-disabledimage> =E<gt> I<name> - -Specifies the name of the images to display in the item in is normal, -active and disabled states. This image must have been created -previously, see L<Tk::Image>. - -=item B<-state> =E<gt> I<state> - -Modifies the state of the image item where I<state> may be set to one of: -normal, disabled, or hidden. An image item may also be in the "active" -state if the mouse is currently over it. Many options can take -separate specifications in normal, active and disabled states such that the -appearance of the item can be different in each state. - -=item B<-tags> =E<gt> I<tagList> - -Specifies a set of tags to apply to the item. -I<TagList> consists of a list of tag names, which replace any -existing tags for the item; it may be an empty list. - -=item B<-updatecommand> =E<gt> I<command> - -Specifies a callback that is to be executed every time -the image item is updated on the screen. - -=back - -=head1 LINE ITEMS - -Items of type B<line> appear on the display as one or more connected -line segments or curves. -Line items support coordinate indexing operations using the canvas -methods: B<dchars, index, insert.> -Lines are created with methods of the following form: - - $canvas->createLine(x1, y1..., xn, yn, ?option, value, option, value, ...?) - -The arguments I<x1> through I<yn> give -the coordinates for a series of two or more points that describe -a series of connected line segments. -After the coordinates there may be any number of I<option>-I<value> -pairs, each of which sets one of the configuration options -for the item. These same I<option>-I<value> pairs may be -used in B<itemconfigure> methods to change the item's -configuration. -The following options are supported for lines: - -=over 4 - -=item B<-arrow> =E<gt> I<where> - -Indicates whether or not arrowheads are to be drawn at one or both -ends of the line. -I<Where> must have one of the values B<none> (for no arrowheads), -B<first> (for an arrowhead at the first point of the line), -B<last> (for an arrowhead at the last point of the line), or -B<both> (for arrowheads at both ends). -This option defaults to B<none>. - -=item B<-arrowshape> =E<gt> I<shape> - -This option indicates how to draw arrowheads. -The I<shape> argument must be a list with three elements, each -specifying a distance in any of the forms described in -the L<"COORDINATES"> section above. -The first element of the list gives the distance along the line -from the neck of the arrowhead to its tip. -The second element gives the distance along the line from the -trailing points of the arrowhead to the tip, and the third -element gives the distance from the outside edge of the line to the -trailing points. -If this option isn't specified then Tk picks a ``reasonable'' shape. - -=item B<-capstyle> =E<gt> I<style> - -Specifies the ways in which caps are to be drawn at the endpoints -of the line. -I<Style> may have any of the forms accepted by B<Tk_GetCapStyle> -(B<butt>, B<projecting>, or B<round>). -If this option isn't specified then it defaults to B<butt>. -Where arrowheads are drawn the cap style is ignored. - -=item B<-dash> =E<gt> I<pattern> - -=item B<-activedash> =E<gt> I<pattern> - -=item B<-disableddash> =E<gt> I<pattern> - -This option specifies dash patterns for the normal state, the active -state, and the disabled state of a line item. -I<pattern> may have any of the forms accepted by B<Tk_GetDash>. -If the dash options are omitted then the default is a solid outline. - -=item B<-dashoffset> =E<gt> I<offset> - -The starting I<offset> into the pattern provided by the -B<-dash> option. -B<-dashoffset> is ignored if there is no B<-dash> pattern. - -=item B<-fill> =E<gt> I<color> - -=item B<-activefill> =E<gt> I<color> - -=item B<-disabledfill> =E<gt> I<color> - -Specifies the color to be used to fill the line in its normal, active, and -disabled states. -I<Color> may have -any of the forms acceptable to B<Tk_GetColor>. It may also be undef, -in which case the line will be transparent. -This option defaults to B<black>. - -=item B<-joinstyle> =E<gt> I<style> - -Specifies the ways in which joints are to be drawn at the vertices -of the line. -I<Style> may have any of the forms accepted by B<Tk_GetCapStyle> -(B<bevel>, B<miter>, or B<round>). -If this option isn't specified then it defaults to B<miter>. -If the line only contains two points then this option is -irrelevant. - -=item B<-smooth> =E<gt> I<boolean> - -I<Boolean> must have one of the forms accepted by B<Tk_GetBoolean>. -It indicates whether or not the line should be drawn as a curve. -If so, the line is rendered as a set of parabolic splines: one spline -is drawn for the first and second line segments, one for the second -and third, and so on. Straight-line segments can be generated within -a curve by duplicating the end-points of the desired line segment. - -=item B<-splinesteps> =E<gt> I<number> - -Specifies the degree of smoothness desired for curves: each spline -will be approximated with I<number> line segments. This -option is ignored unless the B<-smooth> option is true. - -=item B<-state> =E<gt> I<state> - -Modifies the state of the line item where I<state> may be set to one of: -normal, disabled, or hidden. A line item may also be in the "active" -state if the mouse is currently over it. Many options can take -separate specifications in normal, active and disabled states such that the -appearance of the item can be different in each state. - -=item B<-stipple> =E<gt> I<bitmap> - -=item B<-activestipple> =E<gt> I<bitmap> - -=item B<-disabledstipple> =E<gt> I<bitmap> - -This option specifies stipple patterns that should be used to fill the -the line in its normal, active and disabled states. -I<bitmap> specifies the stipple pattern to use, in any of the -forms accepted by B<Tk_GetBitmap>. -If I<bitmap> is an empty string (the default), then filling is -done in a solid fashion. - -=item B<-tags> =E<gt> I<tagList> - -Specifies a set of tags to apply to the item. -I<TagList> consists of a list of tag names, which replace any -existing tags for the item. -I<TagList> may be an empty list. - -=item B<-updatecommand> =E<gt> I<command> - -Specifies a callback that is to be executed every time -the line item is updated on the screen. - -=item B<-width> =E<gt> I<lineWidth> - -=item B<-activewidth> =E<gt> I<lineWidth> - -=item B<-disabledwidth> =E<gt> I<lineWidth> - -Specifies the width of the line -in its normal, active and disabled states. -I<lineWidth> may be in any of the forms -described in the L<"COORDINATES"> section above. - -Wide lines will be drawn centered on the path specified by the -points. -If this option isn't specified then it defaults to 1.0. - -=back - -=head1 OVAL ITEMS - -Items of type B<oval> appear as circular or oval regions on -the display. Each oval may have an outline, a fill, or -both. Ovals are created with methods of the -following form: - - $canvas->createOval(x1, y1, x2, y2, ?option, value, option, value, ...?) - -The arguments I<x1>, I<y1>, I<x2>, and I<y2> give -the coordinates of two diagonally opposite corners of a -rectangular region enclosing the oval. -The oval will include the top and left edges of the rectangle -not the lower or right edges. -If the region is square then the resulting oval is circular; -otherwise it is elongated in shape. -After the coordinates there may be any number of I<option>-I<value> -pairs, each of which sets one of the configuration options -for the item. These same I<option>-I<value> pairs may be -used in B<itemconfigure> methods to change the item's -configuration. -The following options are supported for ovals: - -=over 4 - -=item B<-dash> =E<gt> I<pattern> - -=item B<-activedash> =E<gt> I<pattern> - -=item B<-disableddash> =E<gt> I<pattern> - -This option specifies dash patterns for the normal state, the active -state, and the disabled state of an oval item. -I<pattern> may have any of the forms accepted by B<Tk_GetDash>. -If the dash options are omitted then the default is a solid outline. - -=item B<-dashoffset> =E<gt> I<offset> - -The starting I<offset> into the pattern provided by the -B<-dash> option. -B<-dashoffset> is ignored if there is no B<-dash> pattern. - -=item B<-fill> =E<gt> I<color> - -=item B<-activefill> =E<gt> I<color> - -=item B<-disabledfill> =E<gt> I<color> - -Specifies the color to be used to fill the oval in its normal, active, and -disabled states. -I<Color> may have any of the forms accepted by B<Tk_GetColor>. -If I<color> is undef (the default), then -then the oval will not be filled. - -=item B<-outline> =E<gt> I<color> - -=item B<-activeoutline> =E<gt> I<color> - -=item B<-disabledoutline> =E<gt> I<color> - -This option specifies the color that should be used to draw the -outline of the oval in its normal, active and disabled states. -I<Color> may have any of the forms accepted by B<Tk_GetColor>. -This option defaults to B<black>. -If I<color> is undef then no outline will be -drawn for the oval. - -=item B<-outlinestipple> =E<gt> I<bitmap> - -=item B<-activeoutlinestipple> =E<gt> I<bitmap> - -=item B<-disabledoutlinestipple> =E<gt> I<bitmap> - -This option specifies stipple patterns that should be used to draw the -outline of the oval in its normal, active and disabled states. -I<bitmap> specifies the stipple pattern to use, in any of the -forms accepted by B<Tk_GetBitmap>. -If the B<-outline> option hasn't been specified then this option -has no effect. -If I<bitmap> is an empty string (the default), then the outline is drawn -in a solid fashion. - -=item B<-state> =E<gt> I<state> - -Modifies the state of the oval item where I<state> may be set to one of: -normal, disabled, or hidden. An oval item may also be in the "active" -state if the mouse is currently over it. Many options can take -separate specifications in normal, active and disabled states such that the -appearance of the item can be different in each state. - -=item B<-stipple> =E<gt> I<bitmap> - -=item B<-activestipple> =E<gt> I<bitmap> - -=item B<-disabledstipple> =E<gt> I<bitmap> - -This option specifies stipple patterns that should be used to fill the -the oval in its normal, active and disabled states. -I<bitmap> specifies the stipple pattern to use, in any of the -forms accepted by B<Tk_GetBitmap>. -If the B<-fill> option hasn't been specified then this option -has no effect. -If I<bitmap> is an empty string (the default), then filling is done -in a solid fashion. - -=item B<-tags> =E<gt> I<tagList> - -Specifies a set of tags to apply to the item. -I<TagList> consists of a list of tag names, which replace any -existing tags for the item. -I<TagList> may be an empty list. - -=item B<-updatecommand> =E<gt> I<command> - -Specifies a callback that is to be executed every time -the oval item is updated on the screen. - -=item B<-width> =E<gt> I<outlineWidth> - -=item B<-activewidth> =E<gt> I<outlineWidth> - -=item B<-disabledwidth> =E<gt> I<outlineWidth> - -Specifies the width of the outline to be drawn around -the oval, in its normal, active and disabled states. -I<outlineWidth> specifies the width of the outline to be drawn around -the oval, in any of the forms described in the L<"COORDINATES"> section above. - -If the B<-outline> option hasn't been specified then this option -has no effect. -Wide outlines are drawn centered on the oval path defined by -I<x1>, I<y1>, I<x2>, and I<y2>. -This option defaults to 1.0. - -=back - -=head1 POLYGON ITEMS - -Items of type B<polygon> appear as polygonal or curved filled regions -on the display. -Polygon items support coordinate indexing operations using the canvas -methods: B<dchars, index, insert.> -Polygons are created with methods of the following form: - - $canvas->createPolygon(x1, y1, ..., xn, yn, ?option, value, option, value, ...?) - -The arguments I<x1> through I<yn> specify the coordinates for -three or more points that define a closed polygon. -The first and last points may be the same; whether they are or not, -Tk will draw the polygon as a closed polygon. -After the coordinates there may be any number of I<option>-I<value> -pairs, each of which sets one of the configuration options -for the item. These same I<option>-I<value> pairs may be -used in B<itemconfigure> methods to change the item's -configuration. -The following options are supported for polygons: - -=over 4 - -=item B<-dash> =E<gt> I<pattern> - -=item B<-activedash> =E<gt> I<pattern> - -=item B<-disableddash> =E<gt> I<pattern> - -This option specifies dash patterns for the normal state, the active -state, and the disabled state of an polygon item. -I<pattern> may have any of the forms accepted by B<Tk_GetDash>. -If the dash options are omitted then the default is a solid outline. - -=item B<-dashoffset> =E<gt> I<offset> - -The starting I<offset> into the pattern provided by the -B<-dash> option. -B<-dashoffset> is ignored if there is no B<-dash> pattern. - -=item B<-fill> =E<gt> I<color> - -=item B<-activefill> =E<gt> I<color> - -=item B<-disabledfill> =E<gt> I<color> - -Specifies the color to be used to fill the polygon in its normal, active, and -disabled states. -I<Color> -may have any of the forms acceptable to B<Tk_GetColor>. -If I<color> is undef then the polygon will be -transparent. -This option defaults to B<black>. - -=item B<-joinstyle> =E<gt> I<style> - -Specifies the ways in which joints are to be drawn at the vertices -of the outline. -I<Style> may have any of the forms accepted by B<Tk_GetCapStyle> -(B<bevel>, B<miter>, or B<round>). -If this option isn't specified then it defaults to B<miter>. - -=item B<-outline> =E<gt> I<color> - -=item B<-activeoutline> =E<gt> I<color> - -=item B<-disabledoutline> =E<gt> I<color> - -This option specifies the color that should be used to draw the -outline of the polygon in its normal, active and disabled states. -I<Color> may have any of the forms accepted by B<Tk_GetColor>. -If I<color> is undef then no outline will be -drawn for the polygon. -This option defaults to undef (no outline). - -=item B<-outlinestipple> =E<gt> I<bitmap> - -=item B<-activeoutlinestipple> =E<gt> I<bitmap> - -=item B<-disabledoutlinestipple> =E<gt> I<bitmap> - -This option specifies stipple patterns that should be used to draw the -outline of the polygon in its normal, active and disabled states. -I<bitmap> specifies the stipple pattern to use, in any of the -forms accepted by B<Tk_GetBitmap>. -If the B<-outline> option hasn't been specified then this option -has no effect. -If I<bitmap> is an empty string (the default), then the outline is drawn -in a solid fashion. - -=item B<-smooth> =E<gt> I<boolean> - -I<Boolean> must have one of the forms accepted by B<Tk_GetBoolean> -It indicates whether or not the polygon should be drawn with a -curved perimeter. -If so, the outline of the polygon becomes a set of parabolic splines, -one spline for the first and second line segments, one for the second -and third, and so on. Straight-line segments can be generated in a -smoothed polygon by duplicating the end-points of the desired line segment. - -=item B<-splinesteps> =E<gt> I<number> - -Specifies the degree of smoothness desired for curves: each spline -will be approximated with I<number> line segments. This -option is ignored unless the B<-smooth> option is true. - -=item B<-state> =E<gt> I<state> - -Modifies the state of the polygon item where I<state> may be set to one of: -normal, disabled, or hidden. A polygon item may also be in the "active" -state if the mouse is currently over it. Many options can take -separate specifications in normal, active and disabled states such that the -appearance of the item can be different in each state. - -=item B<-stipple> =E<gt> I<bitmap> - -=item B<-activestipple> =E<gt> I<bitmap> - -=item B<-disabledstipple> =E<gt> I<bitmap> - -This option specifies stipple patterns that should be used to fill the -the polygon in its normal, active and disabled states. -I<bitmap> specifies the stipple pattern to use, in any of the -forms accepted by B<Tk_GetBitmap>. -If I<bitmap> is an empty string (the default), then filling is -done in a solid fashion. - -=item B<-tags> =E<gt> I<tagList> - -Specifies a set of tags to apply to the item. -I<TagList> consists of a list of tag names, which replace any -existing tags for the item. -I<TagList> may be an empty list. - -=item B<-updatecommand> =E<gt> I<command> - -Specifies a callback that is to be executed every time -the polygon item is updated on the screen. - -=item B<-width> =E<gt> I<outlineWidth> - -=item B<-activewidth> =E<gt> I<outlineWidth> - -=item B<-disabledwidth> =E<gt> I<outlineWidth> - -=item Specifies the width of the outline to be drawn around - -the polygon, in its normal, active and disabled states. -I<outlineWidth> may be in any of the forms described in the COORDINATES -section above. -I<OutlineWidth> specifies the width of the outline to be drawn around -the polygon, in any of the forms described in the L<"COORDINATES"> section above. -If the B<-outline> option hasn't been specified then this option -has no effect. This option defaults to 1.0. - -Polygon items are different from other items such as rectangles, ovals -and arcs in that interior points are considered to be ``inside'' a -polygon (e.g. for purposes of the B<find closest> and -B<find overlapping> methods) even if it is not filled. -For most other item types, an -interior point is considered to be inside the item only if the item -is filled or if it has neither a fill nor an outline. If you would -like an unfilled polygon whose interior points are not considered -to be inside the polygon, use a line item instead. - -=back - -=head1 RECTANGLE ITEMS - -Items of type B<rectangle> appear as rectangular regions on -the display. Each rectangle may have an outline, a fill, or -both. Rectangles are created with methods of the -following form: - - $canvas->createRectangle(x1, y1, x2, y2, ?option, value, option, value, ...?) - -The arguments I<x1>, I<y1>, I<x2>, and I<y2> give -the coordinates of two diagonally opposite corners of the rectangle -(the rectangle will include its upper and left edges but not -its lower or right edges). -After the coordinates there may be any number of I<option>-I<value> -pairs, each of which sets one of the configuration options -for the item. These same I<option>-I<value> pairs may be -used in B<itemconfigure> methods to change the item's -configuration. -The following options are supported for rectangles: - -=over 4 - -=item B<-dash> =E<gt> I<pattern> - -=item B<-activedash> =E<gt> I<pattern> - -=item B<-disableddash> =E<gt> I<pattern> - -This option specifies dash patterns for the normal state, the active -state, and the disabled state of a rectangle item. -I<pattern> may have any of the forms accepted by B<Tk_GetDash>. -If the dash options are omitted then the default is a solid outline. - -=item B<-dashoffset> =E<gt> I<offset> - -The starting I<offset> into the pattern provided by the -B<-dash> option. -B<-dashoffset> is ignored if there is no B<-dash> pattern. - -=item B<-fill> =E<gt> I<color> - -=item B<-activefill> =E<gt> I<color> - -=item B<-disabledfill> =E<gt> I<color> - -Specifies the color to be used to fill the rectangle in its normal, active, and -disabled states. -I<Color> -may be specified in any of the forms accepted by B<Tk_GetColor>. -If I<color> is undef (the default), -then the rectangle will not be filled. - -=item B<-outline> =E<gt> I<color> - -=item B<-activeoutline> =E<gt> I<color> - -=item B<-disabledoutline> =E<gt> I<color> - -This option specifies the color that should be used to draw the -outline of the rectangle in its normal, active and disabled states. -I<Color> may have any of the forms accepted by B<Tk_GetColor>. -This option defaults to B<black>. -If I<color> is undef then no outline will be -drawn for the rectangle. - -=item B<-outlinestipple> =E<gt> I<bitmap> - -=item B<-activeoutlinestipple> =E<gt> I<bitmap> - -=item B<-disabledoutlinestipple> =E<gt> I<bitmap> - -This option specifies stipple patterns that should be used to draw the -outline of the rectangle in its normal, active and disabled states. -I<bitmap> specifies the stipple pattern to use, in any of the -forms accepted by B<Tk_GetBitmap>. -If the B<-outline> option hasn't been specified then this option -has no effect. -If I<bitmap> is an empty string (the default), then the outline is drawn -in a solid fashion. - -=item B<-state> =E<gt> I<state> - -Modifies the state of the rectangle item where I<state> may be set to one of: -normal, disabled, or hidden. A rectangle item may also be in the "active" -state if the mouse is currently over it. Many options can take -separate specifications in normal, active and disabled states such that the -appearance of the item can be different in each state. - -=item B<-stipple> =E<gt> I<bitmap> - -=item B<-activestipple> =E<gt> I<bitmap> - -=item B<-disabledstipple> =E<gt> I<bitmap> - -This option specifies stipple patterns that should be used to fill the -the rectangle in its normal, active and disabled states. -I<bitmap> specifies the stipple pattern to use, in any of the -forms accepted by B<Tk_GetBitmap>. -If the B<-fill> option hasn't been specified then this option -has no effect. -If I<bitmap> is an empty string (the default), then filling -is done in a solid fashion. - -=item B<-tags> =E<gt> I<tagList> - -Specifies a set of tags to apply to the item. -I<TagList> consists of a list of tag names, which replace any -existing tags for the item. -I<TagList> may be an empty list. - -=item B<-updatecommand> =E<gt> I<command> - -Specifies a callback that is to be executed every time -the rectangle item is updated on the screen. - -=item B<-width> =E<gt> I<outlineWidth> - -=item B<-activewidth> =E<gt> I<outlineWidth> - -=item B<-disabledwidth> =E<gt> I<outlineWidth> - -Specifies the width of the outline to be drawn around -the rectangle, in its normal, active and disabled states. -I<OutlineWidth> specifies the width of the outline to be drawn around -the rectangle, in any of the forms described in the L<"COORDINATES"> section above. - -If the B<-outline> option hasn't been specified then this option -has no effect. -Wide outlines are drawn centered on the rectangular path -defined by I<x1>, I<y1>, I<x2>, and I<y2>. -This option defaults to 1.0. - -=back - -=head1 TEXT ITEMS - -A text item displays a string of characters on the screen in one -or more lines. -Text items support indexing and selection, along with the -following text-related canvas methods: B<dchars>, -B<focus>, B<icursor>, B<index>, B<insert>, -B<select>. -Text items are created with methods of the following -form: - - $canvas->createText(x, y, ?option, value, option, value, ...?) - -The arguments I<x> and I<y> specify the coordinates of a -point used to position the text on the display (see the options -below for more information on how text is displayed). -After the coordinates there may be any number of I<option>-I<value> -pairs, each of which sets one of the configuration options -for the item. These same I<option>-I<value> pairs may be -used in B<itemconfigure> methods to change the item's -configuration. -The following options are supported for text items: - -=over 4 - -=item B<-anchor> =E<gt> I<anchorPos> - -I<AnchorPos> tells how to position the text relative to the -positioning point for the text; it may have any of the forms -accepted by B<Tk_GetAnchor>. For example, if I<anchorPos> -is B<center> then the text is centered on the point; if -I<anchorPos> is B<n> then the text will be drawn such that -the top center point of the rectangular region occupied by the -text will be at the positioning point. -This option defaults to B<center>. - -=item B<-fill> =E<gt> I<color> - -=item B<-activefill> =E<gt> I<color> - -=item B<-disabledfill> =E<gt> I<color> - -Specifies the color to be used to fill the text in its normal, active, and -disabled states. -I<Color> may have any of the forms accepted by B<Tk_GetColor>. -If I<color> is undef then the text will be transparent. -If this option isn't specified then it defaults to B<black>. - -=item B<-font> =E<gt> I<fontName> - -Specifies the font to use for the text item. -I<FontName> may be any string acceptable to B<Tk_GetFontStruct>. -If this option isn't specified, it defaults to a system-dependent -font. - -=item B<-justify> =E<gt> I<how> - -Specifies how to justify the text within its bounding region. -I<How> must be one of the values B<left>, B<right>, -or B<center>. -This option will only matter if the text is displayed as multiple -lines. -If the option is omitted, it defaults to B<left>. - -=item B<-state> =E<gt> I<state> - -Modifies the state of the text item where I<state> may be set to one of: -normal, disabled, or hidden. A text item may also be in the "active" -state if the mouse is currently over it. Many options can take -separate specifications in normal, active and disabled states such that the -appearance of the item can be different in each state. - -=item B<-stipple> =E<gt> I<bitmap> - -=item B<-activestipple> =E<gt> I<bitmap> - -=item B<-disabledstipple> =E<gt> I<bitmap> - -This option specifies stipple patterns that should be used to fill the -the text in its normal, active and disabled states. -I<bitmap> specifies the stipple pattern to use, in any of the -forms accepted by B<Tk_GetBitmap>. -If I<bitmap> is an empty string (the default) then the text -is drawn in a solid fashion. - -=item B<-tags> =E<gt> I<tagList> - -Specifies a set of tags to apply to the item. -I<TagList> consists of a list of tag names, which replace any -existing tags for the item. -I<TagList> may be an empty list. - -=item B<-text> =E<gt> I<string> - -I<String> specifies the characters to be displayed in the text item. -Newline characters cause line breaks. -The characters in the item may also be changed with the -B<insert> and B<delete> methods. -This option defaults to an empty string. - -=item B<-updatecommand> =E<gt> I<command> - -Specifies a callback that is to be executed every time -the text item is updated on the screen. - -=item B<-width> =E<gt> I<lineLength> - -Specifies a maximum line length for the text, in any of the forms -described in the L<"COORDINATES"> section above. -If this option is zero (the default) the text is broken into -lines only at newline characters. -However, if this option is non-zero then any line that would -be longer than I<lineLength> is broken just before a space -character to make the line shorter than I<lineLength>; the -space character is treated as if it were a newline -character. - -=back - -=head1 WINDOW ITEMS - -Items of type B<window> cause a particular window to be displayed -at a given position on the canvas. -Window items are created with methods of the following form: - -S< >I<$canvas>->B<createWindow>(I<x, y>?, I<-option>=>I<value>, I<-option>=>I<value>, ...?) - -The arguments I<x> and I<y> specify the coordinates of a -point used to position the window on the display (see the B<-anchor> -option below for more information on how bitmaps are displayed). -After the coordinates there may be any number of I<option-value> -pairs, each of which sets one of the configuration options -for the item. These same I<option>-I<value> pairs may be -used in B<itemconfigure> method to change the item's -configuration. -The following options are supported for window items: - -=over 4 - -=item B<-anchor> =E<gt> I<anchorPos> - -I<AnchorPos> tells how to position the window relative to the -positioning point for the item; it may have any of the forms -accepted by B<Tk_GetAnchor>. For example, if I<anchorPos> -is B<center> then the window is centered on the point; if -I<anchorPos> is B<n> then the window will be drawn so that -its top center point is at the positioning point. -This option defaults to B<center>. - -=item B<-height> =E<gt> I<pixels> - -Specifies the height to assign to the item's window. -I<Pixels> may have any of the -forms described in the L<"COORDINATES"> section above. -If this option isn't specified, or if it is specified as an empty -string, then the window is given whatever height it requests internally. - -=item B<-state> =E<gt> I<state> - -Modifies the state of the window item where I<state> may be set to one of: -normal, disabled, or hidden. - -=item B<-tags> =E<gt> I<tagList> - -Specifies a set of tags to apply to the item. -I<TagList> consists of a list of tag names, which replace any -existing tags for the item. -I<TagList> may be an empty list. - -=item B<-updatecommand> =E<gt> I<command> - -Specifies a callback that is to be executed every time -the window item is updated on the screen. - -=item B<-width> =E<gt> I<pixels> - -Specifies the width to assign to the item's window. -I<Pixels> may have any of the -forms described in the L<"COORDINATES"> section above. -If this option isn't specified, or if it is specified as an empty -string, then the window is given whatever width it requests internally. - -=item B<-window> =E<gt> I<$widget> - -Specifies the window to associate with this item. -The window specified by $widget must either be a child of -the canvas widget or a child of some ancestor of the canvas widget. -I<PathName> may not refer to a top-level window. - -Note: due to restrictions in the ways that windows are managed, it is not -possible to draw other graphical items (such as lines and images) on top -of window items. A window item always obscures any graphics that -overlap it, regardless of their order in the display list. - -=back - -=head1 APPLICATION-DEFINED ITEM TYPES - -It is possible for individual applications to define new item -types for canvas widgets using C code. -See the documentation for B<Tk_CreateItemType>. - -=head1 BINDINGS - -Canvas has default bindings to allow scrolling if necessary: -<Up>, <Down>, <Left> and <Right> (and their <Control-*> counter -parts). Further <Proir>, <Next>, <Home> and <End>. These -bindings allow you to navigate the same way as in other -widgets that can scroll. - -=head1 Perl/Tk Methods - -The following methods are added as perl code: - -=over 4 - -=item $canvas->get_corners - -Returns the bounding box in Canvas coordinates of the visible portion -of the Canvas. (Written by Slaven Rezic.) - -=back - -=head1 CREDITS - -Tk's canvas widget is a blatant ripoff of ideas from Joel Bartlett's -I<ezd> program. I<Ezd> provides structured graphics in a Scheme -environment and preceded canvases by a year or two. Its simple -mechanisms for placing and animating graphical objects inspired the -functions of canvases. - -=head1 KEYWORDS - -canvas, widget - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Checkbutton.pod b/Master/tlpkg/tlperl/lib/Tk/Checkbutton.pod deleted file mode 100644 index 35c4fa8ffbc..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Checkbutton.pod +++ /dev/null @@ -1,347 +0,0 @@ -# Copyright (c) 1990-1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::Checkbutton - Create and manipulate Checkbutton widgets - -=for category Tk Widget Classes - -=head1 SYNOPSIS - -I<$checkbutton> = I<$parent>-E<gt>B<Checkbutton>(?I<options>?); - -=head1 STANDARD OPTIONS - -B<-activebackground> -B<-activeforeground> -B<-anchor> -B<-background> -B<-bitmap> -B<-borderwidth> -B<-compound> -B<-cursor> -B<-disabledforeground> -B<-font> -B<-foreground> -B<-highlightbackground> -B<-highlightcolor> -B<-highlightthickness> -B<-image> -B<-justify> -B<-padx> -B<-pady> -B<-relief> -B<-takefocus> -B<-text> -B<-textvariable> -B<-underline> -B<-wraplength> - -See L<Tk::options> for details of the standard options. - -=head1 WIDGET-SPECIFIC OPTIONS - -=over 4 - -=item Name: B<command> - -=item Class: B<Command> - -=item Switch: B<-command> - -Specifies a L<perl/Tk callback|Tk::callbacks> to associate with the button. This command -is typically invoked when mouse button 1 is released over the button -window. The button's global variable (B<-variable> option) will -be updated before the command is invoked. - -=item Name: B<height> - -=item Class: B<Height> - -=item Switch: B<-height> - -Specifies a desired height for the button. -If an image or bitmap is being displayed in the button then the value is in -screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>); -for text it is in lines of text. -If this option isn't specified, the button's desired height is computed -from the size of the image or bitmap or text being displayed in it. - -=item Name: B<indicatorOn> - -=item Class: B<IndicatorOn> - -=item Switch: B<-indicatoron> - -Specifies whether or not the indicator should be drawn. Must be a -proper boolean value. If false, the B<relief> option is -ignored and the widget's relief is always sunken if the widget is -selected and raised otherwise. - -=item Command-Line Name: B<-offrelief> - -=item Database Name: B<offRelief> - -=item Database Class: B<OffRelief> - -Specifies the relief for the checkbutton when the indicator is not -drawn and the checkbutton is off. The default value is B<raised>. By -setting this option to B<flat> and setting -B<-indicatoron false -overrelief raised>, the effect is achieved of -having a flat button -that raises on mouse-over and which is depressed when activated. This -is the behavior typically exhibited by the Bold, Italic, and -Underline checkbuttons on the toolbar of a word-processor, for -example. - -=item Name: B<offValue> - -=item Class: B<Value> - -=item Switch: B<-offvalue> - -Specifies value to store in the button's associated variable whenever -this button is deselected. Defaults to ``0''. - -=item Name: B<onValue> - -=item Class: B<Value> - -=item Switch: B<-onvalue> - -Specifies value to store in the button's associated variable whenever -this button is selected. Defaults to ``1''. - -=item Command-Line Name: B<-overrelief> - -=item Database Name: B<overRelief> - -=item Database Class: B<OverRelief> - -Specifies an alternative relief for the button, to be used when -the mouse cursor is over the widget. This option can be used to -make toolbar buttons, by configuring B<-relief flat -overrelief -raised>. If the value of this option is the empty string, then -no alternative relief is used when the mouse cursor is over the -button. The empty string is the default value. - -=item Name: B<selectColor> - -=item Class: B<Background> - -=item Switch: B<-selectcolor> - -Specifies a background color to use when the button is selected. -If B<indicatorOn> is true then the color applies to the indicator. -Under Windows, this color is used as the background for the indicator -regardless of the select state. -If B<indicatorOn> is false, this color is used as the background -for the entire widget, in place of B<background> or B<activeBackground>, -whenever the widget is selected. -If specified as an empty string then no special color is used for -displaying when the widget is selected. - -=item Name: B<selectImage> - -=item Class: B<SelectImage> - -=item Switch: B<-selectimage> - -Specifies an image to display (in place of the B<image> option) -when the checkbutton is selected. -This option is ignored unless the B<image> option has been -specified. - -=item Name: B<state> - -=item Class: B<State> - -=item Switch: B<-state> - -Specifies one of three states for the checkbutton: B<normal>, B<active>, -or B<disabled>. In normal state the checkbutton is displayed using the -B<foreground> and B<background> options. The active state is -typically used when the pointer is over the checkbutton. In active state -the checkbutton is displayed using the B<activeForeground> and -B<activeBackground> options. Disabled state means that the checkbutton -should be insensitive: the default bindings will refuse to activate -the widget and will ignore mouse button presses. -In this state the B<disabledForeground> and -B<background> options determine how the checkbutton is displayed. - -=item Name: B<variable> - -=item Class: B<Variable> - -=item Switch: B<-variable> - -Specifies reference to a variable to set to indicate whether -or not this button is selected. Defaults to C<\$widget-E<gt>{'Value'}> -member of the widget's hash. In general perl variables are C<undef> unless -specifically initialized which will not match either default B<-onvalue> or -default B<-offvalue>. - -=item Name: B<width> - -=item Class: B<Width> - -=item Switch: B<-width> - -Specifies a desired width for the button. -If an image or bitmap is being displayed in the button then the value is in -screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>); -for text it is in characters. -If this option isn't specified, the button's desired width is computed -from the size of the image or bitmap or text being displayed in it. - -=back - -=head1 DESCRIPTION - -The B<Checkbutton> method creates a new window (given by the -$widget argument) and makes it into a checkbutton widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the checkbutton such as its colors, font, -text, and initial relief. The B<checkbutton> command returns its -$widget argument. At the time this command is invoked, -there must not exist a window named $widget, but -$widget's parent must exist. - -A checkbutton is a widget -that displays a textual string, bitmap or image -and a square called an I<indicator>. -If text is displayed, it must all be in a single font, but it -can occupy multiple lines on the screen (if it contains newlines -or if wrapping occurs because of the B<wrapLength> option) and -one of the characters may optionally be underlined using the -B<underline> option. -A checkbutton has -all of the behavior of a simple button, including the -following: it can display itself in either of three different -ways, according to the B<state> option; -it can be made to appear -raised, sunken, or flat; it can be made to flash; and it invokes -a L<perl/Tk callback|Tk::callbacks> whenever mouse button 1 is clicked over the -checkbutton. - -In addition, checkbuttons can be I<selected>. -If a checkbutton is selected then the indicator is normally -drawn with a selected appearance, and -a Tcl variable associated with the checkbutton is set to a particular -value (normally 1). -Under Unix, the indicator is drawn with a sunken relief and a special -color. Under Windows, the indicator is drawn with a check mark inside. -If the checkbutton is not selected, then the indicator is drawn with a -deselected appearance, and the associated variable is -set to a different value (typically 0). -Under Unix, the indicator is drawn with a raised relief and no special -color. Under Windows, the indicator is drawn without a check mark inside. -By default, the name of the variable associated with a checkbutton is the -same as the I<name> used to create the checkbutton. -The variable name, and the ``on'' and ``off'' values stored in it, -may be modified with options on the command line or in the option -database. -Configuration options may also be used to modify the way the -indicator is displayed (or whether it is displayed at all). -By default a checkbutton is configured to select and deselect -itself on alternate button clicks. -In addition, each checkbutton monitors its associated variable and -automatically selects and deselects itself when the variables value -changes to and from the button's ``on'' value. - -=head1 WIDGET METHODS - -The B<Checkbutton> method creates a widget object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. -The widget also inherits all the methods provided by the generic -L<Tk::Widget|Tk::Widget> class. - -The following additional methods are available for checkbutton widgets: - -=over 4 - -=item I<$checkbutton>-E<gt>B<deselect> - -Deselects the checkbutton and sets the associated variable to its ``off'' -value. - -=item I<$checkbutton>-E<gt>B<flash> - -Flashes the checkbutton. This is accomplished by redisplaying the checkbutton -several times, alternating between active and normal colors. At -the end of the flash the checkbutton is left in the same normal/active -state as when the command was invoked. -This command is ignored if the checkbutton's state is B<disabled>. - -=item I<$checkbutton>-E<gt>B<invoke> - -Does just what would have happened if the user invoked the checkbutton -with the mouse: toggle the selection state of the button and invoke -the L<perl/Tk callback|Tk::callbacks> associated with the checkbutton, if there is one. -The return value is the return value from the L<perl/Tk callback|Tk::callbacks>, or an -empty string if there is no command associated with the checkbutton. -This command is ignored if the checkbutton's state is B<disabled>. - -=item I<$checkbutton>-E<gt>B<select> - -Selects the checkbutton and sets the associated variable to its ``on'' -value. - -=item I<$checkbutton>-E<gt>B<toggle> - -Toggles the selection state of the button, redisplaying it and -modifying its associated variable to reflect the new state. - -=back - -=head1 BINDINGS - -Tk automatically creates class bindings for checkbuttons that give them -the following default behavior: - -=over 4 - -=item [1] - -On Unix systems, a checkbutton activates whenever the mouse passes -over it and deactivates whenever the mouse leaves the checkbutton. On -Mac and Windows systems, when mouse button 1 is pressed over a -checkbutton, the button activates whenever the mouse pointer is inside -the button, and deactivates whenever the mouse pointer leaves the -button. - -=item [2] - -When mouse button 1 is pressed over a checkbutton, it is invoked (its -selection state toggles and the command associated with the button is -invoked, if there is one). - -=item [3] - -When a checkbutton has the input focus, the space key causes the checkbutton -to be invoked. Under Windows, there are additional key bindings; plus -(+) and equal (=) select the button, and minus (-) deselects the button. - -If the checkbutton's state is B<disabled> then none of the above -actions occur: the checkbutton is completely non-responsive. - -The behavior of checkbuttons can be changed by defining new bindings for -individual widgets or by redefining the class bindings. - -=back - -=head1 KEYWORDS - -checkbutton, widget - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Clipboard.pod b/Master/tlpkg/tlperl/lib/Tk/Clipboard.pod deleted file mode 100644 index a65eb37a870..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Clipboard.pod +++ /dev/null @@ -1,89 +0,0 @@ -# Copyright (c) 1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::clipboard - Manipulate Tk clipboard - -=for category User Interaction - -=head1 SYNOPSIS - -I<$widget>-E<gt>B<clipboard>I<Option>?(I<args>)? - -=head1 DESCRIPTION - -This command provides an interface to the Tk clipboard, -which stores data for later retrieval using the selection mechanism. -In order to copy data into the clipboard, B<clipboardClear> must -be called, followed by a sequence of one or more calls to -B<clipboardAppend>. To ensure that the clipboard is updated atomically, all -appends should be completed before returning to the event loop. - -The following methods are currently supported: - -=over 4 - -=item I<$widget>-E<gt>B<clipboardClear> - -Claims ownership of the clipboard on I<$widget>'s display and removes -any previous contents. Returns an empty string. - -=item I<$widget>-E<gt>B<clipboardAppend>(?B<-format>=E<gt>I<format>?,?B<-type>=E<gt>I<type>?,?B<-->?,I<data>) - -Appends I<data> to the clipboard on $widget's -display in the form given by I<type> with the representation given -by I<format> and claims ownership of the clipboard on $widget's -display. - -=over 4 - -I<Type> specifies the form in which the selection is to be returned -(the desired ``target'' for conversion, in ICCCM terminology), and -should be an atom name such as STRING or FILE_NAME; see the -Inter-Client Communication Conventions Manual for complete details. -I<Type> defaults to STRING. - -The I<format> argument specifies the representation that should be -used to transmit the selection to the requester (the second column of -Table 2 of the ICCCM), and defaults to STRING. If I<format> is -STRING, the selection is transmitted as 8-bit ASCII characters. -See the L<Tk::Selection> documentation for explanation of what happens -if I<format> is not STRING. -Note that arguments passed to -B<clipboardAppend> are concatenated before conversion, so the -caller must take care to ensure appropriate spacing across string -boundaries. All items appended to the clipboard with the same -I<type> must have the same I<format>. - -A B<--> argument may be specified to mark the end of options: the -next argument will always be used as I<data>. -This feature may be convenient if, for example, I<data> starts -with a B<->. - -=back - -=back - -=over 4 - -=item I<$widget>-E<gt>B<clipboardGet>( ?-type? ); - -Retrieve data from the clipboard on I<widget>'s display. -I<-type> specifies the form in which the data is -to be returned and should be an atom name such as STRING or -FILE_NAME. Type defaults to STRING. This command is equivalent -to C<SelectionGet( -selection =E<gt> 'CLIPBOARD' )>. - -=back - -=head1 KEYWORDS - -clear, format, clipboard, append, selection, type - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/CmdLine.pod b/Master/tlpkg/tlperl/lib/Tk/CmdLine.pod deleted file mode 100644 index 58b69fded17..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/CmdLine.pod +++ /dev/null @@ -1,454 +0,0 @@ -=head1 NAME - -Tk::CmdLine - Process standard X11 command line options and set initial resources - -=for pm Tk/CmdLine.pm - -=for category Creating and Configuring Widgets - -=head1 SYNOPSIS - - Tk::CmdLine::SetArguments([@argument]); - - my $value = Tk::CmdLine::cget([$option]); - - Tk::CmdLine::SetResources((\@resource | $resource) [, $priority]); - - Tk::CmdLine::LoadResources( - [ -symbol => $symbol ] - [ -file => $fileSpec ] - [ -priority => $priority ] - [ -echo => $fileHandle ] ); - -=head1 DESCRIPTION - -Process standard X11 command line options and set initial resources. - -The X11R5 man page for X11 says: "Most X programs attempt to use the same names -for command line options and arguments. All applications written with the -X Toolkit Intrinsics automatically accept the following options: ...". -This module processes these command line options for perl/Tk applications -using the C<SetArguments>() function. - -This module can optionally be used to load initial resources explicitly via -function C<SetResources>(), or from specified files (default: the standard X11 -application-specific resource files) via function C<LoadResources>(). - -=head2 Command Line Options - -=over 4 - -=item B<-background> I<Color> | B<-bg> I<Color> - -Specifies the color to be used for the window background. - -=item B<-class> I<Class> - -Specifies the class under which resources for the application should be found. -This option is useful in shell aliases to distinguish between invocations -of an application, without resorting to creating links to alter the executable -file name. - -=item B<-display> I<Display> | B<-screen> I<Display> - -Specifies the name of the X server to be used. - -=item B<-font> I<Font> | B<-fn> I<Font> - -Specifies the font to be used for displaying text. - -=item B<-foreground> I<Color> | B<-fg> I<Color> - -Specifies the color to be used for text or graphics. - -=item B<-geometry> I<Geometry> - -Specifies the initial size and location of the I<first> -L<MainWindow|Tk::MainWindow>. - -=item B<-iconic> - -Indicates that the user would prefer that the application's windows initially -not be visible as if the windows had been immediately iconified by the user. -Window managers may choose not to honor the application's request. - -=item B<-motif> - -Specifies that the application should adhere as closely as possible to Motif -look-and-feel standards. For example, active elements such as buttons and -scrollbar sliders will not change color when the pointer passes over them. - -=item B<-name> I<Name> - -Specifies the name under which resources for the application should be found. -This option is useful in shell aliases to distinguish between invocations -of an application, without resorting to creating links to alter the executable -file name. - -=item B<-synchronous> - -Indicates that requests to the X server should be sent synchronously, instead of -asynchronously. Since Xlib normally buffers requests to the server, errors do -do not necessarily get reported immediately after they occur. This option turns -off the buffering so that the application can be debugged. It should never -be used with a working program. - -=item B<-title> I<TitleString> - -This option specifies the title to be used for this window. This information is -sometimes used by a window manager to provide some sort of header identifying -the window. - -=item B<-xrm> I<ResourceString> - -Specifies a resource pattern and value to override any defaults. It is also -very useful for setting resources that do not have explicit command line -arguments. - -The I<ResourceString> is of the form E<lt>I<pattern>E<gt>:E<lt>I<value>E<gt>, -that is (the first) ':' is used to determine which part is pattern and which -part is value. The (E<lt>I<pattern>E<gt>, E<lt>I<value>E<gt>) pair is entered -into the options database with B<optionAdd> (for each -L<MainWindow|Tk::MainWindow> configured), with I<interactive> priority. - -=back - -=head2 Initial Resources - -There are several mechanism for initializing the resource database to be used -by an X11 application. Resources may be defined in a $C<HOME>/.Xdefaults file, -a system application defaults file (e.g. -/usr/lib/X11/app-defaults/E<lt>B<CLASS>E<gt>), -or a user application defaults file (e.g. $C<HOME>/E<lt>B<CLASS>E<gt>). -The Tk::CmdLine functionality for setting initial resources concerns itself -with the latter two. - -Resource files contain data lines of the form -E<lt>I<pattern>E<gt>:E<lt>I<value>E<gt>. -They may also contain blank lines and comment lines (denoted -by a ! character as the first non-blank character). Refer to L<option|Tk::option> -for a description of E<lt>I<pattern>E<gt>:E<lt>I<value>E<gt>. - -=over 4 - -=item System Application Defaults Files - -System application defaults files may be specified via environment variable -$C<XFILESEARCHPATH> which, if set, contains a list of file patterns -(joined using the OS-dependent path delimiter, e.g. colon on B<UNIX>). - -=item User Application Defaults Files - -User application defaults files may be specified via environment variables -$C<XUSERFILESEARCHPATH>, $C<XAPPLRESDIR> or $C<HOME>. - -=back - -=head1 METHODS - -=over 4 - -=item B<SetArguments> - Tk::CmdLine::SetArguments([@argument]) - -Extract the X11 options contained in a specified array (@ARGV by default). - - Tk::CmdLine::SetArguments([@argument]) - -The X11 options may be specified using a single dash I<-> as per the X11 -convention, or using two dashes I<--> as per the POSIX standard (e.g. -B<-geometry> I<100x100>, B<-geometry> I<100x100> or B<-geometry=>I<100x100>). -The options may be interspersed with other options or arguments. -A I<--> by itself terminates option processing. - -By default, command line options are extracted from @ARGV the first time -a MainWindow is created. The Tk::MainWindow constructor indirectly invokes -C<SetArguments>() to do this. - -=item B<GetArguments> - Tk::CmdLine::GetArguments() - -Get a list of the X11 options that have been processed by C<SetArguments>(). -(C<GetArguments>() first invokes C<SetArguments>() if it has not already been invoked.) - -=item B<cget> - Tk::CmdLine::cget([$option]) - -Get the value of a configuration option specified via C<SetArguments>(). -(C<cget>() first invokes C<SetArguments>() if it has not already been invoked.) - - Tk::CmdLine::cget([$option]) - -The valid options are: B<-class>, B<-name>, B<-screen> and B<-title>. -If no option is specified, B<-class> is implied. - -A typical use of C<cget>() might be to obtain the application class in order -to define the name of a resource file to be loaded in via C<LoadResources>(). - - my $class = Tk::CmdLine::cget(); # process command line and return class - -=item B<SetResources> - Tk::CmdLine::SetResources((\@resource | $resource) [, $priority]) - -Set the initial resources. - - Tk::CmdLine::SetResources((\@resource | $resource) [, $priority]) - -A single resource may be specified using a string of the form -'E<lt>I<pattern>E<gt>:E<lt>I<value>E<gt>'. Multiple resources may be specified -by passing an array reference whose elements are either strings of the above -form, and/or anonymous arrays of the form [ E<lt>I<pattern>E<gt>, -E<lt>I<value>E<gt> ]. The optional second argument specifies the priority, -as defined in L<option|Tk::option>, to be associated with the resources -(default: I<userDefault>). - -Note that C<SetResources>() first invokes C<SetArguments>() if it has not already -been invoked. - -=item B<LoadResources> - Tk::CmdLine::LoadResources([%options]) - -Load initial resources from one or more files. - - Tk::CmdLine::LoadResources( - [ -symbol => $symbol ] - [ -file => $fileSpec ] - [ -priority => $priority ] - [ -echo => $fileHandle ] ); - -[ B<-symbol> =E<gt> $symbol ] specifies the name of an environment variable -that, if set, defines a list of one or more directories and/or file patterns -(joined using the OS-dependent path delimiter, e.g. colon on B<UNIX>). -$C<XUSERFILESEARCHPATH> is a special case. -If $C<XUSERFILESEARCHPATH> is not set, $C<XAPPLRESDIR> is checked instead. -If $C<XAPPLRESDIR> is not set, $C<HOME> is checked instead. - -An item is identified as a file pattern if it contains one or more /%[A-Za-z]/ -patterns. Only patterns B<%L>, B<%T> and B<%N> are currently recognized. All -others are replaced with the null string. Pattern B<%L> is translated into -$C<LANG>. Pattern B<%T> is translated into I<app-defaults>. Pattern B<%N> is -translated into the application class name. - -Each file pattern, after substitutions are applied, is assumed to define a -FileSpec to be examined. - -When a directory is specified, FileSpecs -E<lt>B<DIRECTORY>E<gt>/E<lt>B<LANG>E<gt>/E<lt>B<CLASS>E<gt> -and E<lt>B<DIRECTORY>E<gt>/E<lt>B<CLASS>E<gt> are defined, in that order. - -[ B<-file> =E<gt> $fileSpec ] specifies a resource file to be loaded in. -The file is silently skipped if if does not exist, or if it is not readable. - -[ B<-priority> =E<gt> $priority ] specifies the priority, as defined in -L<option|Tk::option>, to be associated with the resources -(default: I<userDefault>). - -[ B<-echo> =E<gt> $fileHandle ] may be used to specify that a line should be -printed to the corresponding FileHandle (default: \*STDOUT) everytime a file -is examined / loaded. - -If no B<-symbol> or B<-file> options are specified, C<LoadResources>() -processes symbol $C<XFILESEARCHPATH> with priority I<startupFile> and -$C<XUSERFILESEARCHPATH> with priority I<userDefault>. -(Note that $C<XFILESEARCHPATH> and $C<XUSERFILESEARCHPATH> are supposed to -contain only patterns. $C<XAPPLRESDIR> and $C<HOME> are supposed to be a single -directory. C<LoadResources>() does not check/care whether this is the case.) - -For each set of FileSpecs, C<LoadResources>() examines each FileSpec to -determine if the file exists and is readable. The first file that meets this -criteria is read in and C<SetResources>() is invoked. - -Note that C<LoadResources>() first invokes C<SetArguments>() if it has not already -been invoked. - -=back - -=head1 NOTES - -This module is an object-oriented module whose methods can be invoked as object -methods, class methods or regular functions. This is accomplished via an -internally-maintained object reference which is created as necessary, and which -always points to the last object used. C<SetArguments>(), C<SetResources>() and -C<LoadResources>() return the object reference. - -=head1 EXAMPLES - -=over - -=item 1 - -@ARGV is processed by Tk::CmdLine at MainWindow creation. - - use Tk; - - # <Process @ARGV - ignoring all X11-specific options> - - my $mw = MainWindow->new(); - - MainLoop(); - -=item 2 - -@ARGV is processed by Tk::CmdLine before MainWindow creation. -An @ARGV of (--geometry=100x100 -opt1 a b c -bg red) -is equal to (-opt1 a b c) after C<SetArguments>() is invoked. - - use Tk; - - Tk::CmdLine::SetArguments(); # Tk::CmdLine->SetArguments() works too - - # <Process @ARGV - not worrying about X11-specific options> - - my $mw = MainWindow->new(); - - MainLoop(); - -=item 3 - -Just like 2) except that default arguments are loaded first. - - use Tk; - - Tk::CmdLine::SetArguments(qw(-name test -iconic)); - Tk::CmdLine::SetArguments(); - - # <Process @ARGV - not worrying about X11-specific options> - - my $mw = MainWindow->new(); - - MainLoop(); - -=item 4 - -@ARGV is processed by Tk::CmdLine before MainWindow creation. -Standard resource files are loaded in before MainWindow creation. - - use Tk; - - Tk::CmdLine::SetArguments(); - - # <Process @ARGV - not worrying about X11-specific options> - - Tk::CmdLine::LoadResources(); - - my $mw = MainWindow->new(); - - MainLoop(); - -=item 5 - -@ARGV is processed by Tk::CmdLine before MainWindow creation. -Standard resource files are loaded in before MainWindow creation -using non-default priorities. - - use Tk; - - Tk::CmdLine::SetArguments(); - - # <Process @ARGV - not worrying about X11-specific options> - - Tk::CmdLine::LoadResources(-echo => \*STDOUT, - -priority => 65, -symbol => 'XFILESEARCHPATH' ); - Tk::CmdLine::LoadResources(-echo => \*STDOUT, - -priority => 75, -symbol => 'XUSERFILESEARCHPATH' ); - - my $mw = MainWindow->new(); - - MainLoop(); - -=item 6 - -@ARGV is processed by Tk::CmdLine before MainWindow creation. -Standard resource files are loaded in before MainWindow creation. -Individual resources are also loaded in before MainWindow creation. - - use Tk; - - Tk::CmdLine::SetArguments(); - - # <Process @ARGV - not worrying about X11-specific options> - - Tk::CmdLine::LoadResources(); - - Tk::CmdLine::SetResources( # set a single resource - '*Button*background: red', - 'widgetDefault' ); - - Tk::CmdLine::SetResources( # set multiple resources - [ '*Button*background: red', '*Button*foreground: blue' ], - 'widgetDefault' ); - - my $mw = MainWindow->new(); - - MainLoop(); - -=back - -=head1 ENVIRONMENT - -=over 4 - -=item B<HOME> (optional) - -Home directory which may contain user application defaults files as -$C<HOME>/$C<LANG>/E<lt>B<CLASS>E<gt> or $C<HOME>/E<lt>B<CLASS>E<gt>. - -=item B<LANG> (optional) - -The current language (default: I<C>). - -=item B<XFILESEARCHPATH> (optional) - -List of FileSpec patterns -(joined using the OS-dependent path delimiter, e.g. colon on B<UNIX>) -used in defining system application defaults files. - -=item B<XUSERFILESEARCHPATH> (optional) - -List of FileSpec patterns -(joined using the OS-dependent path delimiter, e.g. colon on B<UNIX>) -used in defining user application defaults files. - -=item B<XAPPLRESDIR> (optional) - -Directory containing user application defaults files as -$C<XAPPLRESDIR>/$C<LANG>/E<lt>B<CLASS>E<gt> or -$C<XAPPLRESDIR>/E<lt>B<CLASS>E<gt>. - -=back - -=head1 SEE ALSO - -L<MainWindow|Tk::MainWindow> -L<option|Tk::option> - -=head1 HISTORY - -=over 4 - -=item * - -1999.03.04 Ben Pavon E<lt>ben.pavon@hsc.hac.comE<gt> - -Rewritten as an object-oriented module. - -Allow one to process command line options in a specified array (@ARGV by default). -Eliminate restrictions on the format and location of the options within the array -(previously the X11 options could not be specified in POSIX format and had to be -at the beginning of the array). - -Added the C<SetResources>() and C<LoadResources>() functions to allow the definition -of resources prior to MainWindow creation. - -=item * - -2000.08.31 Ben Pavon E<lt>ben.pavon@hsc.hac.comE<gt> - -Added the C<GetArguments>() method which returns the list of arguments that -have been processed by C<SetArguments>(). - -Modified C<LoadResources>() to split the symbols using the OS-dependent -path delimiter defined in the B<Config> module. - -Modified C<LoadResources>() to eliminate a warning message when processing -patterns B<%l>, B<%C>, B<%S>. - -=back - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/ColorEditor.pod b/Master/tlpkg/tlperl/lib/Tk/ColorEditor.pod deleted file mode 100644 index 48e6477f3ef..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/ColorEditor.pod +++ /dev/null @@ -1,120 +0,0 @@ - -=head1 NAME - -Tk::ColorEditor - a general purpose Tk widget Color Editor - -=for pm Tk/ColorEditor.pm - -=for category Popups and Dialogs - -=head1 SYNOPSIS - - use Tk::ColorEditor; - - $cref = $mw->ColorEditor(-title => $title, -cursor => @cursor); - - $cref->Show; - -=head1 DESCRIPTION - -ColorEditor is implemented as an object with various methods, described -below. First, create your ColorEditor object during program initialization -(one should be sufficient), and then configure it by specifying a list of Tk -widgets to colorize. When it's time to use the editor, invoke the Show() -method. - -ColorEditor allows some customization: you may alter the color attribute -menu by adding and/or deleting menu items and/or separators, turn the status -window on or off, alter the configurator's list of color widgets, or even -supply your own custom color configurator callback. - -=over 4 - -=item 1. - -Call the constructor to create the editor object, which in turn returns a -blessed reference to the new object: - - use Tk::ColorEditor; - - $cref = $mw->ColorEditor( - -title => $title, - -cursor => @cursor, - ); - - mw - a window reference, usually the result of a MainWindow->new - call. As the default root of a widget tree, $mw and all - descendant widgets at object-creation-time are configured - by the default color configurator procedure. (You probably - want to change this though or you might end up colorizing - ColorEditor!) - title - Toplevel title, default = ' '. - cursor - a valid Tk '-cursor' specification (default is - 'top_left_arrow'). This cursor is used over all ColorEditor - "hot spots". - -=item 2. - -Invoke the configure() method to change editor characteristics: - - $cref->configure(-option => value, ..., -option-n => value-n); - - options: - -command : a callback to a `set_colors' replacement. - -widgets : a reference to a list of widget references - for the color configurator. - -display_status : TRUE IFF display the ColorEditor status - window when applying colors. - -add_menu_item : 'SEP', or a color attribute menu item. - -delete_menu_item : 'SEP', a color attribute menu item, or color - attribute menu ordinal. - - For example: - - $cref->configure(-delete_menu_item => 3, - -delete_menu_item => 'disabledforeground', - -add_menu_item => 'SEP', - -add_menu_item => 'New color attribute', - -widgets => [$ce, $qu, $f2b2], - -widgets => [$f2->Descendants], - -command => [\&my_special_configurator, some, args ] - ); - -=item 3. - -Invoke the Show() method on the editor object, say, by a button or menu press: - - $cref->Show; - -=item 4. - -The cget(-widgets) method returns a reference to a list of widgets that -are colorized by the configurator. Typically, you add new widgets to -this list and then use it in a subsequent configure() call to expand your -color list. - - $cref->configure( - -widgets => [ - @{$Filesystem_ref->cget(-widgets)}, @{$cref->cget(-widgets)}, - ] - ); - -=item 5. - -The delete_widgets() method expects a reference to a list of widgets which are -then removed from the current color list. - - $cref->delete_widgets($OBJTABLE{$objname}->{'-widgets'}) - -=back - -=head1 AUTHORS - -Stephen O. Lidie, Lehigh University Computing Center. 95/03/05 -lusol@Lehigh.EDU - -Many thanks to Guy Decoux (decoux@moulon.inra.fr) for doing the initial -translation of tcolor.tcl to TkPerl, from which this code has been derived. - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Common.pod b/Master/tlpkg/tlperl/lib/Tk/Common.pod deleted file mode 100644 index cd53ab79a99..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Common.pod +++ /dev/null @@ -1,16 +0,0 @@ - -=head1 NAME - -Tk::DragDrop::Common - private class used by Drag&Drop - -=for pm DragDrop/DragDrop/Common.pm - -=for category Experimental Modules - -=head1 DESCRIPTION - -This class provides methods to automate the the loading and declaring -of Drop and Site 'types'. - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Compound.pod b/Master/tlpkg/tlperl/lib/Tk/Compound.pod deleted file mode 100644 index 01f6e5f2639..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Compound.pod +++ /dev/null @@ -1,298 +0,0 @@ -# Copyright (c) 1996, Expert Interface Technologies -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# The file man.macros and some of the macros used by this file are -# copyrighted: (c) 1990 The Regents of the University of California. -# (c) 1994-1995 Sun Microsystems, Inc. -# The license terms of the Tcl/Tk distrobution are in the file -# license.tcl. - -=head1 NAME - -Tk::Compound - Create multi-line compound images. - -=for category Tk Image Classes - -=head1 SYNOPSIS - - use Tk::Compound; - $image = $widget->Compound(name,options); - $image->Line(options); - $image->Text(options); - $image->Bitmap(options); - $image->Image(options); - $image->Space(options); - -=for comment -This paragraph used to be written different, but perldoc 3.14 cannot -display this paragraph. -S< >use Tk::Compound; -S< >I<$image> = I<$widget>-E<gt>B<Compound>?(I<name>??,I<options>?) -S< >I<$image>-E<gt>B<Line>?(I<options>?) -S< >I<$image>-E<gt>B<Text>?(I<options>?) -S< >I<$image>-E<gt>B<Bitmap>?(I<options>?) -S< >I<$image>-E<gt>B<Image>?(I<options>?) -S< >I<$image>-E<gt>B<Space>?(I<options>?) - -=head1 DESCRIPTION - -Compound image types can be used to create images that consists of -multiple horizontal lines; each line is composed of a series of items -(texts, bitmaps, images or spaces) arranged from left to -right. Compound images are mainly used to embed complex drawings into -widgets that support the B<-image> option. As shown in the EXAMPLE -section below, a compound image can be used to display a bitmap and a -text string simutaneously in a Tk B<Button> widget. - -Compound images can only be used on windows on the same display as, and -with the same pixel depth and visual as the I<$widget> used to create them. - -=head1 CREATING COMPOUND IMAGES - -Compounds are created using I<$widget>-E<gt>B<Compound>. -Compounds support the following I<options>: - -=over 4 - -=item B<-background> =E<gt> I<color> - -Specifies the background color of the compound image. This color is -also used as the default background color for the bitmap items in the -compound image. - -=item B<-borderwidth> =E<gt> I<pixels> - -Specifies a non-negative value indicating the width of the 3-D border -drawn around the compound image. - -=item B<-font> =E<gt> I<font> - -Specifies the default font for the text items in the compound image. - -=item B<-foreground> =E<gt> I<color> - -Specifies the default foreground color for the bitmap and text items -in the compound image. - -=item B<-padx> =E<gt> I<value> - -Specifies a non-negative value indicating how much extra space to -request for the compound image in the X-direction. The I<value> may -have any of the forms acceptable to B<Tk_GetPixels(3)>. - -=item B<-pady> =E<gt> I<value> - -Specifies a non-negative value indicating how much extra space to -request for the compound image in the Y-direction. - -=item B<-relief> =E<gt> I<value> - -Specifies the 3-D effect desired for the background of the compound -image. Acceptable values are B<raised>, B<sunken>, B<flat>, -B<ridge>, and B<groove>. - -=item B<-showbackground> =E<gt> I<value> - -Specifies whether the background and the 3D borders should be drawn. -Must be a valid boolean value. By default the background is not drawn -and the compound image appears to have a transparent background. - - -=back - -=head1 IMAGE COMMAND - -When a compound image is created, Tk also creates a new object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. - -The object also supports the following methods: - -=over 4 - -=item I<$compound>-E<gt>B<Line>?(I<option => value ...>)? - -Creates a new line at the bottom of the compound image. Lines support -the following I<options>: - -=over 4 - -=item B<-anchor> value - -Specifies how the line should be aligned along the horizontal axis. -When the values are B<w>, B<sw> or B<nw>, the line is aligned -to the left. When the values are B<c>, B<s> or B<n>, the line -is aligned to the middle. When the values are B<e>, B<se> or -B<ne>, the line is aligned to the right. - -=item B<-padx> =E<gt> I<value> - -Specifies a non-negative value indicating how much extra space to -request for this line in the X-direction. - -=back - -=item I<$compound>-E<gt>I<Itemtype>?(I<option => value ...>)? - -Creates a new item of the type I<Itemtype> at the end of the last -line of the compound image. All types of items support -these following common I<options>: - -=over 4 - -=item B<-anchor> value - -Specifies how the item should be aligned along the vertical axis. When -the values are B<n>, B<nw> or B<ne>, the item is aligned to -the top of the line. When the values are B<c>, B<w> or B<e>, -the item is aligned to the middle of the line. When the values are -B<s>, B<se> or B<sw>, the item is aligned to the bottom of -the line. - -=item B<-padx> =E<gt> I<value> - -Specifies a non-negative value indicating how much extra space to -request for this item in the X-direction. - -=item B<-pady> =E<gt> I<value> - -Specifies a non-negative value indicating how much extra space to -request for this item in the Y-direction. - -=item I<item-type> can be any of the following: - -=back - -=item I<$compound>-E<gt>B<Bitmap>?(I<option => value ...>)? - -Creates a new bitmap item of at the end of the last -line of the compound image. Additional I<options> accepted by the -bitmap type are: - -=over 4 - -=item B<-background> =E<gt> I<color> - -Specifies the background color of the bitmap item. - -=item B<-bitmap> =E<gt> I<name> - -Specifies a bitmap to display in this item, in any of the forms -acceptable to B<Tk_GetBitmap(3)>. - -=item B<-foreground> =E<gt> I<color> - -Specifies the foreground color of the bitmap item. - -=back - -=item I<$compound>-E<gt>B<Image>?(I<option => value ...>)? - -Creates a new image item of at the end of the last -line of the compound image. Additional I<options> accepted by the -image type are: - -=over 4 - -=item B<-image> =E<gt> I<name> - -Specifies an image to display in this item. I<name> -must have been created with the B<image create> command. - -=back - -=item I<$compound>-E<gt>B<Space>?(I<option => value ...>)? - -Creates a new space item of at the end of the last line of the -compound image. Space items do not display anything. They just acts as -space holders that add additional spaces between items inside a -compound image. Additional I<options> accepted by the image type -are: - -=over 4 - -=item B<-width> =E<gt> I<value> - -Specifies the width of this space. The I<value> may have any of the -forms acceptable to B<Tk_GetPixels(3)>. - -=item B<-height> =E<gt> I<value> - -Specifies the height of this space. The I<value> may have any of -the forms acceptable to B<Tk_GetPixels(3)>. - -=back - -=item I<$compound>-E<gt>B<Text>?(I<option => value ...>)? - -Creates a new text item of at the end of the last line of the compound -image. Additional I<options> accepted by the text type are: - -=over 4 - -=item B<-background> =E<gt> I<color> - -Specifies the background color of the text item. - -=item B<-font> =E<gt> I<name> - -Specifies the font to be used for this text item. - -=item B<-foreground> =E<gt> I<color> - -Specifies the foreground color of the text item. - -=item B<-justify> I<value> - -When there are multiple lines of text displayed in a text item, this -option determines how the lines line up with each other. I<value> -must be one of B<left>, B<center>, or B<right>. B<Left> -means that the lines' left edges all line up, B<center> means that -the lines' centers are aligned, and B<right> means that the lines' -right edges line up. - -=item B<-text> =E<gt> I<string> - -Specifies a text string to display in this text item. - -=item B<-underline> I<value> - -Specifies the integer index of a character to underline in the text -item. 0 corresponds to the first character of the text displayed in -the text item, 1 to the next character, and so on. - -=item B<-wraplength> I<value> - -This option specifies the maximum line length of the label string on -this text item. If the line length of the label string exceeds this -length, it is wrapped onto the next line, so that no line is longer -than the specified length. The value may be specified in any of the -standard forms for screen distances. If this value is less than or -equal to 0 then no wrapping is done: lines will break only at newline -characters in the text. - -=back - -=back - -=head1 EXAMPLE - -The following example creates a compound image with a bitmap and a -text string and places this image into a B<Button(n)> -widget. Notice that the image must be created using the widget -that it resides in. - - my $b = $parent->Button; - my $c = $b->Compound; - $b->configure(-image => $c); - $c->Line; - $c->Bitmap(-bitmap => 'warning'); - $c->Space(-width => 8); - $c->Text(-text => "Warning", -underline => 0); - $b->pack; - -=head1 KEYWORDS - -image(n), Tix(n) diff --git a/Master/tlpkg/tlperl/lib/Tk/ConfigSpecs.pod b/Master/tlpkg/tlperl/lib/Tk/ConfigSpecs.pod deleted file mode 100644 index 5f90c2716bb..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/ConfigSpecs.pod +++ /dev/null @@ -1,262 +0,0 @@ -# $Id: configspec.pod 1.2 Wed, 12 Nov 1997 00:30:45 +0100 ach $ - -=head1 NAME - -Tk::ConfigSpecs - Defining behaviour of 'configure' for composite widgets. - -=for category Derived Widgets - -=head1 SYNOPSIS - - sub Populate - { - my ($composite,$args) = @_; - ... - $composite->ConfigSpecs('-attribute' => [ where,dbName,dbClass,default ]); - $composite->ConfigSpecs('-alias' => '-otherattribute'); - $composite->ConfigSpecs('DEFAULT' => [ where ]); - $composite->ConfigSpecs($subwidget->ConfigSpecs); - ... - } - - $composite->configure(-attribute => value); - -=head1 DESCRIPTION - -The aim is to make the composite widget configure method look as much like -a regular Tk widget's configure as possible. -(See L<Tk::options> for a description of this behaviour.) -To enable this the attributes that the composite as a whole accepts -needs to be defined. - -=head2 Defining the ConfigSpecs for a class. - -Typically a widget will have one or more calls like the following - - $composite->ConfigSpecs(-attribute => [where,dbName,dbClass,default]); - -in its B<Populate> method. When B<ConfigSpecs> is called this way -(with arguments) the arguments are used to construct or augment/replace -a hash table for the widget. (More than one I<-option>=E<gt>I<value> -pair can be specified to a single call.) - -B<dbName>, B<dbClass> and default are only used by B<ConfigDefault> described -below, or to respond to 'inquiry' configure commands. - -It may be either one of the values below, or a list of such values -enclosed in B<[]>. - -The currently permitted values of B<where> are: - -=over 4 - -=item B<'ADVERTISED'> - -Apply B<configure> to I<advertised> subwidgets. - -=item B<'DESCENDANTS'> - -Apply B<configure> recursively to all descendants. - -=item B<'CALLBACK'> - -Setting the attribute does C<Tk::Callback-E<gt>new($value)> before storing -in C<$composite-E<gt>{Configure}{-attribute}>. This is appropriate for -C<-command =E<gt> ...> attributes that are handled by the composite and not -forwarded to a subwidget. (E.g. B<Tk::Tiler> has C<-yscrollcommand> to -allow it to have scrollbar attached.) - -This may be the first of several 'validating' keywords (e.g. font, cursor, -anchor etc.) that core Tk makes special for C code. - -=item B<'CHILDREN'> - -Apply B<configure> to all children. (Children are the immediate -descendants of a widget.) - -=item B<'METHOD'> - -Call C<$cw-E<gt>attribute(value)> - -This is the most general case. Simply have a method of the composite -class with the same name as the attribute. The method may do any -validation and have whatever side-effects you like. (It is probably -worth 'queueing' using B<afterIdle> for more complex side-effects.) - -=item B<'PASSIVE'> - -Simply store value in C<$composite-E<gt>{Configure}{-attribute}>. - -This form is also a useful placeholder for attributes which you -currently only handle at create time. - -=item B<'SELF'> - -Apply B<configure> to the core widget (e.g. B<Frame>) that is the basis of -the composite. (This is the default behaviour for most attributes which -makes a simple Frame behave the way you would expect.) Note that once -you have specified B<ConfigSpecs> for an attribute you must explicitly -include C<'SELF'> in the list if you want the attribute to apply to the -composite itself (this avoids nasty infinite recursion problems). - -=item B<$reference> (blessed) - -Call B<$reference>->configure(-attribute => value) - -A common case is where B<$reference> is a subwidget. - -$reference may also be result of - - Tk::Config->new(setmethod,getmethod,args,...); - -B<Tk::Config> class is used to implement all the above keyword types. The -class has C<configure> and C<cget> methods so allows higher level code to -I<always> just call one of those methods on an I<object> of some kind. - -=item B<hash reference> - -Defining: - - $cw->ConfigSpecs( - ... - -option => [ { -optionX=>$w1, -optionY=>[$w2, $w3] }, - dbname dbclass default ], - ... - ); - -So C<$cw-E<gt>configure(-option =E<gt> value)> actually does - - $w1->configure(-optionX => value); - $w2->configure(-optionY => value); - $w3->configure(-optionY => value); - -=item B<'otherstring'> - -Call - - $composite->Subwidget('otherstring')->configure( -attribute => value ); - -While this is here for backward compatibility with Tk-b5, it is probably -better just to use the subwidget reference directly. The only -case for retaining this form is to allow an additional layer of -abstraction - perhaps having a 'current' subwidget - this is unproven. - -=item B<Aliases> - -C<ConfigSpecs( -alias =E<gt> '-otherattribute' )> is used to make C<-alias> -equivalent to C<-otherattribute>. For example the aliases - - -fg => '-foreground', - -bg => '-background' - -are provided automatically (if not already specified). - -=back - -=head2 Delegating all options of a widget class to a subwidget - - $composite->ConfigSpecs($subwidget->ConfigSpecs); - -The above generates a list of I<composite> ConfigSpecs arguments, one -for each valid option in $subwidget's class, and delegates said option -to $subwidget. See L<Tk::Widget> and the I<widget> method -ConfigSpecs. Duplicating I<composite> ConfigSpecs and I<widget> -ConfigSpecs keys will yield undefined results. - - -=head2 Default values - -When the B<Populate> method returns B<ConfigDefault> is called. This calls - - $composite->ConfigSpecs; - -(with no arguments) to return a reference to a hash. Entries in the hash -take the form: - - '-attribute' => [ where, dbName, dbClass, default ] - -B<ConfigDefault> ignores 'where' completely (and also the DEFAULT entry) and -checks the 'options' database on the widget's behalf, and if an entry is -present matching dbName/dbClass - - -attribute => value - -is added to the list of options that B<new> will eventually apply to the -widget. Likewise if there is not a match and default is defined this -default value will be added. - -Alias entries in the hash are used to convert user-specified values for the -alias into values for the real attribute. - -=head2 B<New()-time configure> - -Once control returns to B<new>, the list of user-supplied options -augmented by those from B<ConfigDefault> are applied to the widget using the -B<configure> method below. - -Widgets are most flexible and most Tk-like if they handle the majority of -their attributes this way. - -=head2 Configuring composites - -Once the above have occurred calls of the form: - - $composite->configure( -attribute => value ); - -should behave like any other widget as far as end-user code is concerned. -B<configure> will be handled by B<Tk::Derived::configure> as follows: - - $composite->ConfigSpecs; - -is called (with no arguments) to return a reference to a hash B<-attribute> is -looked up in this hash, if B<-attribute> is not present in the hash then -B<'DEFAULT'> is looked for instead. (Aliases are tried as well and cause -redirection to the aliased attribute). The result should be a reference to a -list like: - - [ where, dbName, dbClass, default ] - -at this stage only I<where> is of interest, it maps to a list of object -references (maybe only one) foreach one - - $object->configure( -attribute => value ); - -is B<eval>ed. - -=head2 Inquiring attributes of composites - - $composite->cget( '-attribute' ); - -This is handled by B<Tk::Derived::cget> in a similar manner to configure. At -present if I<where> is a list of more than one object it is ignored completely -and the "cached" value in - - $composite->{Configure}{-attribute}. - -is returned. - -=head1 CAVEATS - -The C<-background> and C<-foreground> option values are automatically -propagated down to all composite widget's children. This may be -sometimes not desirable, especially if some subwidgets should use own -color schemes, either by using explicit options or by option database -definitions. If this is the case, then just add - - -foreground => 'SELF', - -background => 'SELF', - -to C<ConfigSpecs>. - -It is the author's intention to port as many of the "Tix" composite widgets -as make sense. The mechanism described above may have to evolve in order to -make this possible, although now aliases are handled I think the above is -sufficient. - -=head1 SEE ALSO - -L<Tk::composite|Tk::composite>, -L<Tk::options|Tk::options>, -L<Tk::Widget> - -=cut diff --git a/Master/tlpkg/tlperl/lib/Tk/DItem.pod b/Master/tlpkg/tlperl/lib/Tk/DItem.pod deleted file mode 100644 index 27db79744df..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/DItem.pod +++ /dev/null @@ -1,439 +0,0 @@ -=head1 NAME - -Tk::DItem - Tix Display Items - -=for category Tix Extensions - -=head1 SYNOPSIS - -=head1 DESCRIPTION - -The Tix B<Display Items> and B<Display Types> are devised to -solve a general problem: many Tix widgets (both existing and planned -ones) display many items of many types simultaneously. - -For example, a hierarchical listbox widget (see L<Tk::HList>) can display -items -of images, plain text and subwindows in the form of a -hierarchy. Another widget, the tabular listbox widget (see L<Tk::TList>) -also displays items of the -same types, although it arranges the items in a tabular form. Yet -another widget, the spreadsheet widget (see L<Tk::TixGrid>), -also displays similar types -items, but in yet another format. - -In these examples, the display items in different widgets are only -different in how they are arranged by the B<host widget>. In Tix, -display items are clearly separated from the host widgets. The -advantage is two-fold: first, the creation and configuration of -display items become uniform across different host widgets. Second, -new display item types can be added without the need to modify the -existing host widgets. - -In a way, Tix display items are similar to the items inside Tk -the canvas widget. However, unlike the Tix display items, the canvas -items are not independent of the canvas widget; this makes it -impossible to use the canvas items inside other types of TK widgets. - -The appearance of a display item is controlled by a set of -I<attributes>. It is observed that each the attributes usually fall -into one of two categroies: ``I<individual>'' or -``I<collective>''. For example, the text items inside a HList widget -may all display a different text string; however, in most cases, the -text items share the same color, font and spacing. Instead of keeping -a duplicated version of the same attributes inside each display item, -it will be advantageous to put the collective attributes in a -special object called a B<display style>. First, there is the space -concern: a host widget may have many thousands of items; keeping -dupilcated attributes will be very wasteful. Second, when it becomes -necessary to change a collective attribute, such as changing all the -text items' foreground color to red, it will be more efficient to -change only the display style object than to modify all the text -items one by one. - -The attributes of the a display item are thus stored in two places: it -has a set of B<item options> to store its individual attributes. Each -display item is also associated with a I<display style>, which specifies -the collective attributes of all items associated with itself. - -The division between the individual and collective attributes are -fixed and cannot be changed. Thus, when it becomes necessary for some -items to differ in their collective attributes, two or more B<display styles> -can be used. For example, suppose you want to display two -columns of text items inside an HList widget, one column in red and -the other in blue. You can create a TextStyle object called ``$red'' -which defines a red foreground, and another called ``$blue'', which -defines a blue foreground. You can then associate all text items of -the first column to ``$red'' and the second column to ``$blue'' - -=head1 DISPLAY ITEM TYPES AND OPTIONS - -Currently there are three types of display items: B<text>, -B<imagetext> and I<window>. - -=head1 IMAGETEXT ITEMS - -Display items of the type B<imagetext> are used to display an image -together with a text string. Imagetext items support the following options: - -=head2 Imagetext Item Options - -=over 4 - -=item Name: B<bitmap> - -=item Class: B<Bitmap> - -=item Switch: B<-bitmap> - -Specifies the bitmap to display in the item. - -=item Name: B<image> - -=item Class: B<Image> - -=item Switch: B<-image> - -Specifies the image to display in the item. When both the -B<-bitmap> and B<-image> options are specified, only the image -will be displayed. - -=item Name: B<imageTextStyle> - -=item Class: B<ImageTextStyle> - -=item Switch: B<-style> - -Specifies the display style to use for this item. Must be the -name of a B<imagetext> display style that has already be created with -B<ItemStyle>. - -=item Name: B<showImage> - -=item Class: B<ShowImage> - -=item Switch: B<-showimage> - -A Boolean value that specifies whether the image/bitmap should be -displayed. - -=item Name: B<showText> - -=item Class: B<ShowText> - -=item Switch: B<-showtext> - -A Boolean value that specifies whether the text string should be -displayed. - -=item Name: B<text> - -=item Class: B<Text> - -=item Switch: B<-text> - -Specifies the text string to display in the item. - -=item Name: B<underline> - -=item Class: B<Underline> - -=item Switch: B<-underline> - -Specifies the integer index of a character to underline in the text -string in the item. 0 corresponds to the first character of the text -displayed in the widget, 1 to the next character, and so on. - -=back - -=head2 Imagetext Style Options - -The style information of B<imagetext> items are stored in the -B<imagetext> display style. The following options are supported: - -B<STANDARD OPTIONS> - -B<-activebackground> B<-activeforeground> -B<-anchor> B<-background> -B<-disabledbackground> B<-disabledforeground> -B<-foreground> B<-font> -B<-justify> B<-padx> -B<-pady> B<-selectbackground> -B<-selectforeground> B<-wraplength> - -See L<Tk::options> for details of the standard options. - -B<STYLE-SPECIFIC OPTIONS> - -=over 4 - -=item Name: B<gap> - -=item Class: B<Gap> - -=item Switch: B<-gap> - -Specifies the distance between the bitmap/image and the text string, -in number of pixels. - -=item Name: B<textAnchor> - -=item Class: B<TextAnchor> - -=item Switch: B<-textanchor> - -The anchor position on the image to which text part is attached. -This is a perl/Tk addition. Defaults to B<e> for compatibility with standard -Tix. The interesting cases are - -=over 8 - -=item B<n> - -Text is centred above the image. - -=item B<s> - -Text is centred below the image - -=item B<e> - -Text is centred to right of the image. - -=item B<w> - -Text is centred to left of the image. - -=item B<c> - -Text is centred over the image. - -=back - -The B<sw>, B<se>, B<ne>, and b<nw> cases look rather odd. - -To get items to line up correctly it will usually be necessary -to specify B<-anchor> as well. e.g. with default B<e> then anchoring -item as a whole B<w> lines images up down left with text stuck to right side. - -=back - -=head1 TEXT ITEMS - -Display items of the type B<text> are used to display a text string -in a widget. Text items support the following options: - -=head2 Text Item Options - -=over 4 - -=item Name: B<textStyle> - -=item Class: B<TextStyle> - -=item Switch: B<-style> - -Specifies the display style to use for this text item. Must be the -name of a B<text> display style that has already be created with -B<ItemStyle>. - -=item Name: B<text> - -=item Class: B<Text> - -=item Switch: B<-text> - -Specifies the text string to display in the item. - -=item Name: B<underline> - -=item Class: B<Underline> - -=item Switch: B<-underline> - -Specifies the integer index of a character to underline in the item. -0 corresponds to the first character of the text displayed in the -widget, 1 to the next character, and so on. - -=back - -=head2 Text Style Options - -B<STANDARD OPTIONS> - -B<-activebackground> B<-activeforeground> -B<-anchor> B<-background> -B<-disabledbackground> B<-disabledforeground> -B<-foreground> B<-font> -B<-justify> B<-padx> -B<-pady> B<-selectbackground> -B<-selectforeground> B<-wraplength> - -See L<Tk::options> for details of the standard options. - -=head1 WINDOW ITEMS - -Display items of the type I<window> are used to display a -sub-window in a widget. B<Window> items support the following -options: - -=head2 Window Item Options - -=over 4 - -=item Name: B<windowStyle> - -=item Class: B<WindowStyle> - -=item Switch: B<-style> - -Specifies the display style to use for this window item. Must be the -name of a I<window> display style that has already be created with -the B<ItemStyle> method. - -=item Name: B<window> - -=item Class: B<Window> - -=item Switch: B<-window> - -=item Alias: B<-widget> - -Specifies the sub-window to display in the item. - -=back - -=head2 Window Style Options - -B<STYLE STANDARD OPTIONS> - -B<-anchor> B<-padx> B<-pady> - -See L<Tk::options> for details of the standard options. - -=head1 CREATING DISPLAY ITEMS - -Display items do not exist on their and thus they cannot be created -independently of the widgets they reside in. As a rule, display items -are created by special methods of their ``host'' widgets. For -example, the HList widgets has a method B<item> which can be used -to create new display items. The following code creates a new text -item at the third column of the entry foo inside an HList widget: - - my $hlist = $parent->HList(-columns=>3); - $hlist->add('foo'); - $hlist->itemCreate('foo', 2, -itemtype=>'text', -text=>'Hello'); - -The B<itemCreate> method of the HList widget accepts a variable -number of arguments. The special argument B<-itemtype> specifies -which type of display item to create. Options that are valid for this -type of display items can then be specified by one or more -I<option-value> pairs. - -After the display item is created, they can then be configured or -destroyed using the methods provided by the host widget. For example, -the HList widget has the methods B<itemConfigure>, B<itemCget> -and B<itemDelete> for accessing the display items. - -=head1 CREATING AND MANIPULATING ITEM STYLES - -Item styles are created with B<ItemStyle>: - -=head1 SYNOPSIS - -S< >I<$widget>-E<gt>B<ItemStyle>(I<itemType> ?,B<-stylename>=E<gt>I<name>? ?,B<-refwindow>=E<gt>I<pathName>? ?,I<option>=E<gt>I<value>, ...>?); - -I<itemType> must be one of the existing display items types such as -B<text>, B<imagetext>, B<window> or any new types added by -the user. Additional arguments can be given in one or more -I<option-value> pairs. I<option> can be any of the valid option -for this display style or any of the following: - -=over 4 - -=item B<-stylename> =E<gt> I<name> - -Specifies a name for this style. If unspecified, then a default name -will be chosen for this style. - -=item B<-refwindow> =E<gt> I<$otherwidget> - -Specifies a window to use for determine the default values of the -display type. If unspecified, the I<$widget> will be used. Default -values for the display types can be set via the options database. The -following example sets the B<-disablebackground> and -B<-disabledforeground> options of a B<text> display style via -the option database: - - $widget->optionAdd('*table.list*disabledForeground' => 'blue'); - $widget->optionAdd('*table.list*disabledBackground' => 'darkgray'); - $widget->ItemStyle('text', -refwindow => $table_list, -fg => 'red'); - -By using the option database to set the options of the display styles, -we can advoid hard-coding the option values and give the user more -flexibility in customization. See L<Tk::option> for a detailed description -of the option database. - -=back - -=head1 STYLE METHODS - -The B<ItemStyle> method creates an object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. - -The following additional methods are available for item styles: - -=over 4 - -=item I<$style>-E<gt>B<delete> - -Destroy this display style object. - -=back - -=head1 EXAMPLE - -The following example creates two columns of data in a HList -widget. The first column is in red and the second column in blue. The -colors of the columns are controlled by two different B<text> -styles. Also, the anchor and font of the second column is chosen so -that the income data is aligned properly. - - use strict; - use Tk; - use Tk::HList; - use Tk::ItemStyle; - - my $mw = MainWindow->new(); - - my $hlist = $mw->HList(-columns=>2)->pack; - - my $red = $hlist->ItemStyle('text', -foreground=>'#800000'); - my $blue = $hlist->ItemStyle('text', -foreground=>'#000080', -anchor=>'e'); - - my $e; - foreach ([Joe => '$10,000'], [Peter => '$20,000'], - [Raj => '$90,000'], [Zinh => '$0']) { - $e = $hlist->addchild(""); - $hlist->itemCreate($e, 0, -itemtype=>'text', - -text=>$_->[0], -style=>$red ); - $hlist->itemCreate($e, 1, -itemtype=>'text', - -text=>$_->[1], -style=>$blue); - } - - Tk::MainLoop; - -=head1 SEE ALSO - -L<Tk::HList|Tk::HList> -L<Tk::TixGrid|Tk::TixGrid> -L<Tk::TList|Tk::TList> - -=head1 KEYWORDS - -display item, display style, item style - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Derived.pod b/Master/tlpkg/tlperl/lib/Tk/Derived.pod deleted file mode 100644 index 4b99934d5bd..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Derived.pod +++ /dev/null @@ -1,89 +0,0 @@ - -=head1 NAME - -Tk::Derived - Base class for widgets derived from others - -=for pm Tk/Derived.pm - -=for category Derived Widgets - -=head1 SYNOPSIS - - package Tk::MyNewWidget; - - use Tk::widgets qw/ BaseWidget, list of Tk widgets /; - use base qw/ Tk::Derived Tk::BaseWidget /; - - Construct Tk::Widget 'MyNewWidget'; - - sub ClassInit { - my( $class, $mw ) = @_; - #... e.g., class bindings here ... - $class->SUPER::ClassInit( $mw ); - } - - sub Populate { - my( $self, $args ) = @_; - - my $flag = delete $args->{-flag}; - if( defined $flag ) { - # handle -flag => xxx which can only be done at create - # time the delete above ensures that new() does not try - # and do $self->configure( -flag => xxx ); - } - - $self->SUPER::Populate( $args ); - - $self = $self->Component( ... ); - - $self->Delegates( ... ); - - $self->ConfigSpecs( - '-cursor' => [ SELF, 'cursor', 'Cursor', undef ], - '-something' => [ METHOD, dbName, dbClass, default ], - '-text' => [ $label, dbName, dbClass, default ], - '-heading' => [ {-text => $head}, - heading, Heading, 'My Heading' ], - ); - } - - sub something { - my( $self, $value) = @_; - if ( @_ > 1 ) { - # set it - } - return # current value - } - -=head1 DESCRIPTION - -Tk::Derived is used with Perl's multiple inheritance to override some -methods normally inherited from Tk::Widget. - -Tk::Derived should precede any Tk widgets in the class's base class -definition. - -Tk::Derived's main purpose is to apply wrappers to C<configure> and C<cget> -methods of widgets to allow the derived widget to add to or modify behaviour -of the configure options supported by the base widget. - -The derived class should normally override the C<Populate> method provided -by Tk::Derived and call C<ConfigSpecs> to declare configure options. - -The public methods provided by Tk::Derived are as follows: - -=over 4 - -=item -E<gt>ConfigSpecs(-I<key> =E<gt> [I<kind>, I<name>, I<Class>, I<default>], ...) - -=back - -=head1 SEE ALSO - -L<Tk::ConfigSpecs|Tk::ConfigSpecs> -L<Tk::mega|Tk::mega> -L<Tk::composite|Tk::composite> - - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Dialog.pod b/Master/tlpkg/tlperl/lib/Tk/Dialog.pod deleted file mode 100644 index 871206d504c..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Dialog.pod +++ /dev/null @@ -1,107 +0,0 @@ -# Copyright (c) 1992 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::Dialog - Create modal dialog and wait for a response. - -=for pm Tk/Dialog.pm - -=for category Popups and Dialogs - -=head1 SYNOPSIS - -S< >I<$dialog> = I<$parent>-E<gt>B<Dialog>(I<-option> =E<gt> I<value>, ... ); - -=head1 DESCRIPTION - -This procedure is part of the Tk script library - its arguments -describe a dialog box. After creating a dialog box, B<Dialog> waits -for the user to select one of the Buttons either by clicking on the -Button with the mouse or by typing return to invoke the default Button -(if any). Then it returns the text string of the selected Button. - -While waiting for the user to respond, B<Dialog> sets a local -grab. This prevents the user from interacting with the application -in any way except to invoke the dialog box. See the B<Show()> method. - -=head1 OPTIONS - -The following option/value pairs are supported: - -=over 4 - -=item B<-title> - -Text to appear in the window manager's title bar for the dialog. - -=item B<-text> - -Message to appear in the top portion of the Dialog. - -=item B<-bitmap> - -If non-empty, specifies a bitmap to display in the top portion of the -Dialog, to the left of the text. If this is an empty string then no -bitmap is displayed in the Dialog. - -=item B<-default_button> - -Text label string of the Button that displays the default ring. - -=item B<-buttons> - -A reference to a list of Button label strings. Each I<string> -specifies text to display in a Button, in order from left to right. - -=back - -=head1 METHODS - -=over 4 - -=item I<$answer> = $dialog-E<gt>B<Show(>?-global?B<)>; - -This method displays the Dialog, waits for the user's response, and stores -the text string of the selected Button in I<$answer>. If I<-global> is -specified a global (rather than local) grab is performed. - -The actual Dialog is shown using the B<Popup> method. Any other -options supplied to B<Show> are passed to B<Popup>, and can be used to -position the Dialog on the screen. Please read Tk::Popup for details. - -=back - -=head1 ADVERTISED WIDGETS - -Because Tk::Dialog is a subclass of Tk::DialogBox it inherits all the -advertised subwidgets of its superclass: e.g. "B_button-text", where -'button-text' is a Button's -text value. Additionally, Tk::Dialog -advertises: - -=over 4 - -=item B<message> - -The dialog's Label widget containing the message text. - -=item B<bitmap> - -The dialog's Label widget containing the bitmap image. - -=back - -=head1 EXAMPLE - -I<$dialog> = I<$mw>-E<gt>B<Dialog>(-text =E<gt> 'Save File?', -bitmap =E<gt> 'question', -title =E<gt> 'Save File Dialog', -default_button =E<gt> 'Yes', -buttons =E<gt> [qw/Yes No Cancel/); - -=head1 KEYWORDS - -bitmap, dialog, modal, messageBox - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/DialogBox.pod b/Master/tlpkg/tlperl/lib/Tk/DialogBox.pod deleted file mode 100644 index a091cd98427..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/DialogBox.pod +++ /dev/null @@ -1,156 +0,0 @@ - -=head1 NAME - -Tk::DialogBox - create and manipulate a dialog screen. - -=for pm Tixish/DialogBox.pm - -=for category Tix Extensions - -=head1 SYNOPSIS - - use Tk::DialogBox - ... - $d = $top->DialogBox(-title => "Title", -buttons => ["OK", "Cancel"]); - $w = $d->add(Widget, args)->pack; - ... - $button = $d->Show; - -=head1 DESCRIPTION - -B<DialogBox> is very similar to B<Dialog> except that it allows -any widget in the top Frame. B<DialogBox> creates two -Frames, I<top> and I<bottom>. The bottom Frame shows all the -specified Buttons, lined up from left to right. The top Frame acts -as a container for all other widgets that can be added with the -B<add()> method. - -=head1 OPTIONS - -The options recognized by B<DialogBox> are as follows: - -=over 4 - -=item B<-title> - -Specify the title of the DialogBox. If this is not set, then the -name of the program is used. - -=item B<-buttons> - -The button names to display in the bottom Frame. This is a reference -to an array of strings containing the text to put on each -Button. There is no default value for this. If you do not specify any -button names, no Buttons are displayed. - -=item B<-default_button> - -Specifies the default Button that is considered invoked when user -presses <Return> on the DialogBox. This Button is highlighted. If -no default Button is specified, then the first element of the -array whose reference is passed to the B<-buttons> option is used -as the default. - -=item B<-cancel_button> - -Specifies the Button that is considered invoked when the user closes -the DialogBox using the window manager's close button. If the -B<-cancel_button> option is not given, and if there's only one button -configured, then this button is also used as the cancel button. -Otherwise no button is considered as the cancel button; in such a case -B<Show> just returns C<undef> when the user closes the DialogBox. - -=item B<-command> - -A callback which is executed after invoking an action to close the -DialogBox, but before restoring focus and grab information. The -selected button is passed as the first argument. - -=item B<-focus> - -Specify the widget to receive the initial focus after popping up the -DialogBox. By default the B<-default_button> widget receives the -initial focus. - -=item B<-showcommand> - -A callback which is executed before displaying the DialogBox and -waiting for user input. The DialogBox itself is passed as the first -argument. - -=back - -=head1 METHODS - -B<DialogBox> supports only two methods as of now: - -=over 4 - -=item B<add(>I<widget>, I<options>B<)> - -Add the widget indicated by I<widget>. I<Widget> can be the name -of any Tk widget (standard or contributed). I<options> are the -options that the widget accepts. The widget is advertized as a -subwidget of B<DialogBox>. The name of I<widget> is -lower-cased and used as the advertised name. If multiple instances of -I<widget> are created in the B<DialogBox>, then only the last one gets -the advertised name. B<add()> does not automatically B<pack()> or -B<grid()> I<widget> into the B<DialogBox>. - -=item B<Show(>I<?-global?>B<)> - -Displays the Dialog until the user invokes one of the Buttons in the -bottom Frame. If the grab type I<-global> is specified, then B<Show> -uses that grab; otherwise it defaults to a local grab. Returns the -name of the Button invoked. - -The actual Dialog is shown using the B<Popup> method. Any other -options supplied to B<Show> are passed to B<Popup>, and can be used to -position the Dialog on the screen. Please read Tk::Popup for details. - -=item B<Exit()> - -Close the dialogbox, by emulating a click on the default button. - -=back - -=head1 ADVERTISED WIDGETS - -=over 4 - -=item B<top> - -The subwidget reference to the top half of the DialogBox widget, the Frame -containing widgets added by the B<add> method. - -=item B<bottom> - -The subwidget reference to the bottom half of the DialogBox widget, the Frame -containing the Button widgets. - -=item B<B_"button-text"> - -Individual subwidget references to the Buttons in the DialogBox widget. The -subwidget name is the string I<B_> concatenated with the Button's -text -value. - -=back - -=head1 BUGS - -There is no way of removing a widget once it has been added to the -top Frame, unless you access the I<top> subwidget and go through the -child widgets. - -There is no control over the appearance of the Buttons in the -bottom Frame nor is there any way to control the placement of the -two Frames with respect to each other. - -=head1 AUTHOR - -B<Rajappa Iyer> rsi@earthling.net - -This code is distributed under the same terms as Perl. - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/DirTree.pod b/Master/tlpkg/tlperl/lib/Tk/DirTree.pod deleted file mode 100644 index d8ded2f41b7..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/DirTree.pod +++ /dev/null @@ -1,172 +0,0 @@ - -=head1 NAME - -Tk::DirTree - Create and manipulate DirTree widgets - -=for pm Tixish/DirTree.pm - -=for category Tix Extensions - -=head1 SYNOPSIS - -S< >B<use Tk::DirTree;> - -S< >I<$dirtree> = I<$parent>-E<gt>B<DirTree>(?I<options>?); - -=head1 SUPER-CLASS - -The B<DirTree> class is derived from the L<Tree|Tk::Tree> class and inherits -all the methods, options and subwidgets of its super-class. - -=head1 STANDARD OPTIONS - -B<Tree> supports all the standard options of a Tree widget. See -L<Tk::options> for details on the standard options. - -=head1 WIDGET-SPECIFIC OPTIONS - -=over 4 - -=item Name: B<browseCmd> - -=item Class: B<BrowseCmd> - -=item Switch: B<-browsecmd> - -Specifies a L<callback|Tk::callbacks> to call whenever the user browses on a directory -(usually by single-clicking on the name of the directory). The callback -is called with one argument, the complete pathname of the directory. - -=item Name: B<command> - -=item Class: B<Command> - -=item Switch: B<-command> - -Specifies the L<callback|Tk::callbacks> to be called when the user activates on a directory -(usually by double-clicking on the name of the directory). The callback -is called with one argument, the complete pathname of the directory. - -=item Name: B<dircmd> - -=item Class: B<DirCmd> - -=item Switch: B<-dircmd> - -Specifies the L<callback|Tk::callbacks> to be called when a directory listing is needed -for a particular directory. If this option is not specified, by -default the DirTree widget will attempt to read the directory as a -Unix directory. On special occasions, the application programmer may -want to supply a special method for reading directories: for example, -when he needs to list remote directories. In this case, the B<-dircmd> -option can be used. The specified callback accepts two arguments: the -first is the name of the directory to be listed; the second is a -Boolean value indicating whether hidden sub-directories should be -listed. This callback returns a list of names of the sub-directories of -this directory. For example: - - sub read_dir { - my( $dir, $showhidden ) = @_; - return( qw/DOS NORTON WINDOWS/ ) if $dir eq "C:\\"; - return(); - } - -=item Name: B<showHidden> - -=item Class: B<ShowHidden> - -=item Switch: B<-showhidden> - -Specifies whether hidden directories should be shown. By default, a -directory name starting with a period "." is considered as a hidden -directory. This rule can be overridden by supplying an alternative -B<-dircmd> option. - -=item Name: B<directory> - -=item Class: B<Directory> - -=item Switch: B<-directory> - -=item Alias: B<-value> - -Specifies the name of the current directory to be displayed in the -DirTree widget. - -=back - -=head1 DESCRIPTION - -The B<DirTree> constructor method creates a new window (given by the $dirtree -argument) and makes it into a DirTree widget. Additional options, -described above, may be specified on the command line or in the -option database to configure aspects of the DirTree such as its -cursor and relief. The DirTree widget displays a list view of a -directory, its previous directories and its sub-directories. The -user can choose one of the directories displayed in the list or -change to another directory. - -=head1 WIDGET METHODS - -The B<DirTree> method creates a widget object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. -The widget also inherits all the methods provided by the generic -L<Tk::Widget|Tk::Widget> class. - -The following additional methods are available for DirTree widgets: - -=over 4 - -=item I<$dirtree>-E<gt>B<chdir>(I<dir>) - -Change the current directory to I<dir>. - -=back - -=head1 OTHER METHODS - -These methods have to be documented or made private: - -=over 4 - -=item OpenCmd - -=item Populate - -=item add_to_tree - -=item dirnames - -=item fullpath - -=item has_subdir - -=item opencmd - -=item set_dir - -=back - -=head1 BINDINGS - -The mouse and keyboard bindings of the DirTree widget are the same as -the bindings of the L<Tree|Tk::Tree> widget. - -=head1 KEYWORDS - -directory, tree, tix - -=head1 SEE ALSO - -L<Tk::Tree|Tk::Tree> -L<Tk::HList|Tk::HList> - -=head1 AUTHOR - -Perl/TK version by Chris Dean <ctdean@cogit.com>. Original Tcl/Tix -version by Ioi Kim Lam. - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/DropSite.pod b/Master/tlpkg/tlperl/lib/Tk/DropSite.pod deleted file mode 100644 index 8ae5a199fe3..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/DropSite.pod +++ /dev/null @@ -1,33 +0,0 @@ -=head1 NAME - -Tk::DropSite - Receive side of Drag & Drop abstraction - -=for category User Interaction - -=head1 SYNOPSIS - - use Tk::DropSite qw(...); - $widget->DropSite(-entercommand => ..., - -dropcommand => ..., - -motioncommand => ..., - -dropcommand => ..., - ); - -=head1 DESCRIPTION - -C<DropSite> creates an object which represents a site on which things -may be "Dropped". - -A DropSite provides the following methods: - -=over 4 - -=item $site->Enter($token,$event) - -=item $site->Leave($token,$event) - -=item $site->Motion($token,$event) - -=item $site->Drop($token,$event) - -=back diff --git a/Master/tlpkg/tlperl/lib/Tk/Entry.pod b/Master/tlpkg/tlperl/lib/Tk/Entry.pod deleted file mode 100644 index 1b6dbf15482..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Entry.pod +++ /dev/null @@ -1,693 +0,0 @@ -# Copyright (c) 1990-1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::Entry - Create and manipulate Entry widgets - -=for category Tk Widget Classes - -=head1 SYNOPSIS - -S< >I<$entry> = I<$parent>-E<gt>B<Entry>(?I<options>?); - -=head1 STANDARD OPTIONS - -B<-background> B<-highlightbackground> B<-insertontime> B<-selectforeground> -B<-borderwidth> B<-highlightcolor> B<-insertwidth> B<-takefocus> -B<-cursor> B<-highlightthickness> B<-justify> B<-textvariable> -B<-exportselection> B<-insertbackground> B<-relief> B<-xscrollcommand> -B<-font> B<-insertborderwidth> B<-selectbackground> -B<-foreground> B<-insertofftime> B<-selectborderwidth> - -=head1 WIDGET-SPECIFIC OPTIONS - -=over 4 - -=item Command-Line Name: B<-disabledbackground> - -=item Database Name: B<disabledBackground> - -=item Database Class: B<DisabledBackground> - -Specifies the background color to use when the entry is disabled. If -this option is the empty string, the normal background color is used. - -=item Command-Line Name: B<-disabledforeground> - -=item Database Name: B<disabledForeground> - -=item Database Class: B<DisabledForeground> - -Specifies the foreground color to use when the entry is disabled. If -this option is the empty string, the normal foreground color is used. - -=item Name: B<invalidCommand> - -=item Class: B<InvalidCommand> - -=item Switch: B<-invalidcommand> - -=item Alias: B<-invcmd> - -Specifies a script to eval when B<validateCommand> returns 0. -Setting it to <undef> disables this feature (the default). The best use -of this option is to set it to I<bell>. See B<Validation> -below for more information. - -=item Command-Line Name: B<-readonlybackground> - -=item Database Name: B<readonlyBackground> - -=item Database Class: B<ReadonlyBackground> - -Specifies the background color to use when the entry is read-only. If -this option is the empty string, the normal background color is used. - -=item Name: B<show> - -=item Class: B<Show> - -=item Switch: B<-show> - -If this option is specified, then the true contents of the entry -are not displayed in the window. -Instead, each character in the entry's value will be displayed as -the first character in the value of this option, such as ``*''. -This is useful, for example, if the entry is to be used to enter -a password. -If characters in the entry are selected and copied elsewhere, the -information copied will be what is displayed, not the true contents -of the entry. - -=item Name: B<state> - -=item Class: B<State> - -=item Switch: B<-state> - -Specifies one of three states for the entry: B<normal>, B<disabled>, or -B<readonly>. If the entry is B<readonly>, then the value may not be changed -using widget commands and no insertion cursor will be displayed, even -if the input focus is in the widget; the contents of the widget may -still be selected. If the entry is B<disabled>, the value may not be -changed, no insertion cursor will be displayed, the contents will not -be selectable, and the entry may be displayed in a different color, -depending on the values of the B<-disabledforeground> and -B<-disabledbackground> options. - -=item Name: B<validate> - -=item Class: B<Validate> - -=item Switch: B<-validate> - -Specifies the mode in which validation should operate: B<none>, -B<focus>, B<focusin>, B<focusout>, B<key>, or B<all>. -It defaults to B<none>. When you want validation, you must explicitly -state which mode you wish to use. See B<Validation> below for more. - -=item Name: B<validateCommand> - -=item Class: B<ValidateCommand> - -=item Switch: B<-validatecommand> - -=item Alias: B<-vcmd> - -Specifies a script to eval when you want to validate the input into -the entry widget. Setting it to C<undef> disables this feature (the default). -This command must return a valid boolean value. If it returns 0 (or -the valid boolean equivalent) then it means you reject the new edition -and it will not occur and the B<invalidCommand> will be evaluated if it -is set. If it returns 1, then the new edition occurs. -See B<Validation> below for more information. - -=item Name: B<width> - -=item Class: B<Width> - -=item Switch: B<-width> - -Specifies an integer value indicating the desired width of the entry window, -in average-size characters of the widget's font. -If the value is less than or equal to zero, the widget picks a -size just large enough to hold its current text. - -=back - -=head1 DESCRIPTION - -The B<Entry> method creates a new window (given by the -$entry argument) and makes it into an entry widget. -Additional options, described above, may be specified on the -command line or in the option database -to configure aspects of the entry such as its colors, font, -and relief. The B<entry> command returns its -$entry argument. At the time this command is invoked, -there must not exist a window named $entry, but -$entry's parent must exist. - -An entry is a widget that displays a one-line text string and -allows that string to be edited using methods described below, which -are typically bound to keystrokes and mouse actions. -When first created, an entry's string is empty. -A portion of the entry may be selected as described below. -If an entry is exporting its selection (see the B<exportSelection> -option), then it will observe the standard X11 protocols for handling the -selection; entry selections are available as type B<STRING>. -Entries also observe the standard Tk rules for dealing with the -input focus. When an entry has the input focus it displays an -I<insertion cursor> to indicate where new characters will be -inserted. - -Entries are capable of displaying strings that are too long to -fit entirely within the widget's window. In this case, only a -portion of the string will be displayed; methods described below -may be used to change the view in the window. Entries use -the standard B<xScrollCommand> mechanism for interacting with -scrollbars (see the description of the B<-xscrollcommand> option -for details). They also support scanning, as described below. - -=head1 VALIDATION - -Validation of entry widgets is derived from part of the patch written by -jhobbs@cs.uoregon.edu. This works by setting the B<validateCommand> -option to a callback which will be evaluated according to the B<validate> -option as follows: - -=over 4 - -=item B<none> - -Default. This means no validation will occur. - -=item B<focus> - -B<validateCommand> will be called when the entry receives or -loses focus. - -=item B<focusin> - -B<validateCommand> will be called when the entry receives focus. - -=item B<focusout> - -B<validateCommand> will be called when the entry loses focus. - -=item B<key> - -B<validateCommand> will be called when the entry is edited. - -=item B<all> - -B<validateCommand> will be called for all above conditions. - -=back - -The B<validateCommand> and B<invalidCommand> are called with the following -arguments: - -=over 4 - -=item * The proposed value of the entry. If you are configuring the -entry widget to have a new textvariable, this will be the value of that -textvariable. - -=item * The characters to be added (or deleted). This will be C<undef> -if validation is due to focus, explcit call to validate or if change -is due to C<-textvariable> changing. - -=item * The current value of entry i.e. before the proposed change. - -=item * index of char string to be added/deleted, if any. -1 otherwise - -=item * type of action. 1 == INSERT, 0 == DELETE, --1 if it's a forced validation or textvariable validation - -=back - -In general, the B<textVariable> and B<validateCommand> can be -dangerous to mix. If you try set the B<textVariable> -to something that the B<validateCommand> will not accept it will -be set back to the value of the entry widget. -Using the B<textVariable> for read-only purposes will never cause problems. - -The B<validateCommand> will turn itself off by setting -B<validate> to B<none> when an error occurs, for example -when the B<validateCommand> or B<invalidCommand> encounters -an error in its script while evaluating, or -B<validateCommand> does not return a valid boolean value. - -With the perl/Tk version B<validate> option is supposed to be -"suspended" while executing the B<validateCommand> or the B<invalidCommand>. -This is experimental but in theory either callback can "correct" the -value of the widget, and override the proposed change. (B<validateCommand> -should still return false to inhibit the change from happening when -it returns.) - -=head1 WIDGET METHODS - -The B<Entry> method creates a widget object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. -The widget also inherits all the methods provided by the generic -L<Tk::Widget|Tk::Widget> class. - -Many of the additional methods for entries take one or more indices as -arguments. An index specifies a particular character in the entry's -string, in any of the following ways: - -=over 4 - -=item I<number> - -Specifies the character as a numerical index, where 0 corresponds -to the first character in the string. - -=item B<anchor> - -Indicates the anchor point for the selection, which is set with the -B<selectionFrom> and B<selectionAdjust> methods. - -=item B<end> - -Indicates the character just after the last one in the entry's string. -This is equivalent to specifying a numerical index equal to the length -of the entry's string. - -=item B<insert> - -Indicates the character adjacent to and immediately following the -insertion cursor. - -=item B<sel.first> - -Indicates the first character in the selection. It is an error to -use this form if the selection isn't in the entry window. - -=item B<sel.last> - -Indicates the character just after the last one in the selection. -It is an error to use this form if the selection isn't in the -entry window. - -=item B<@>I<number> - -In this form, I<number> is treated as an x-coordinate in the -entry's window; the character spanning that x-coordinate is used. -For example, ``B<@0>'' indicates the left-most character in the -window. - -=back - -Abbreviations may be used for any of the forms above, e.g. ``B<e>'' -or ``B<sel.f>''. In general, out-of-range indices are automatically -rounded to the nearest legal value. - -The following additional methods are available for entry widgets: - -=over 4 - -=item I<$entry>-E<gt>B<bbox>(I<index>) - -Returns a list of four numbers describing the bounding box of the -character given by I<index>. -The first two elements of the list give the x and y coordinates of -the upper-left corner of the screen area covered by the character -(in pixels relative to the widget) and the last two elements give -the width and height of the character, in pixels. -The bounding box may refer to a region outside the visible area -of the window. - -=item I<$entry>-E<gt>B<cget>(?I<option>?) - -Returns the current value of the configuration option given -by I<option>. -I<Option> may have any of the values accepted by the B<entry> -command. - -=item I<$entry>-E<gt>B<configure>(?I<option>?, ?I<value, option, value, ...>?) - -Query or modify the configuration options of the widget. -If no I<option> is specified, returns a list describing all of -the available options for $entry (see L<Tk::configure> for -information on the format of this list). If I<option> is specified -with no I<value>, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no I<option> is specified). If -one or more I<option-value> pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. -I<Option> may have any of the values accepted by the B<entry> -command. - -=item I<$entry>-E<gt>B<delete>(I<first, >?I<last>?) - -Delete one or more elements of the entry. -I<First> is the index of the first character to delete, and -I<last> is the index of the character just after the last -one to delete. -If I<last> isn't specified it defaults to I<first>+1, -i.e. a single character is deleted. -This method returns an empty string. - -=item I<$entry>-E<gt>B<get> - -Returns the entry's string. - -=item I<$entry>-E<gt>B<icursor>(I<index>) - -Arrange for the insertion cursor to be displayed just before the character -given by I<index>. Returns an empty string. - -=item I<$entry>-E<gt>B<index>(I<index>) - -Returns the numerical index corresponding to I<index>. - -=item I<$entry>-E<gt>B<insert>(I<index, string>) - -Insert the characters of I<string> just before the character -indicated by I<index>. Returns an empty string. - -=item I<$entry>->B<scan>(I<option, args>) - -=item I<$entry>->B<scan>I<Option>(I<args>) - -This method is used to implement scanning on entries. It has -two forms, depending on I<Option>: - -=over 8 - -=item I<$entry>->B<scanMark>(I<x>) - -Records I<x> and the current view in the entry widget; used in -conjunction with later B<scanDragto> methods. Typically this -method is associated with a mouse button press in the widget. It -returns an empty string. - -=item I<$entry>->B<scanDragto>(I<x>) - -This method computes the difference between its I<x> argument -and the I<x> argument to the last B<scanMark> method for -the widget. It then adjusts the view left or right by 10 times the -difference in x-coordinates. This method is typically associated -with mouse motion events in the widget, to produce the effect of -dragging the entry at high speed through the widget. The return -value is an empty string. - -=back - -=item I<$entry>->B<selection>(I<option, arg>) - -=item I<$entry>->B<selection>I<Option>(I<arg>) - -This method is used to adjust the selection within an entry. It -has several forms, depending on I<Option>: - -=over 8 - -=item I<$entry>-E<gt>B<selectionAdjust>(I<index>) - -Locate the end of the selection nearest to the character given by -I<index>, and adjust that end of the selection to be at I<index> -(i.e including but not going beyond I<index>). The other -end of the selection is made the anchor point for future -B<selectionTo> methods. If the selection -isn't currently in the entry, then a new selection is created to -include the characters between I<index> and the most recent -selection anchor point, inclusive. -Returns an empty string. - -=item I<$entry>-E<gt>B<selectionClear> - -Clear the selection if it is currently in this widget. If the -selection isn't in this widget then the method has no effect. -Returns an empty string. - -=item I<$entry>-E<gt>B<selectionFrom>(I<index>) - -Set the selection anchor point to just before the character -given by I<index>. Doesn't change the selection. -Returns an empty string. - -=item I<$entry>-E<gt>B<selectionPresent> - -Returns 1 if there is are characters selected in the entry, -0 if nothing is selected. - -=item I<$entry>-E<gt>B<selectionRange>(I<start, >I<end>) - -Sets the selection to include the characters starting with -the one indexed by I<start> and ending with the one just -before I<end>. -If I<end> refers to the same character as I<start> or an -earlier one, then the entry's selection is cleared. - -=item I<$entry>-E<gt>B<selectionTo>(I<index>) - -If I<index> is before the anchor point, set the selection -to the characters from I<index> up to but not including -the anchor point. -If I<index> is the same as the anchor point, do nothing. -If I<index> is after the anchor point, set the selection -to the characters from the anchor point up to but not including -I<index>. -The anchor point is determined by the most recent B<selectionFrom> -or B<selectionAdjust> method in this widget. -If the selection isn't in this widget then a new selection is -created using the most recent anchor point specified for the widget. -Returns an empty string. - -=back - -=item I<$entry>-E<gt>B<validate> - -This command is used to force an evaluation of the B<validateCommand> -independent of the conditions specified by the B<validate> option. It -returns 0 or 1. - -=item I<$entry>-E<gt>B<xview>(I<args>) - -This command is used to query and change the horizontal position of the -text in the widget's window. It can take any of the following -forms: - -=over 8 - -=item I<$entry>-E<gt>B<xview> - -Returns a list containing two elements. -Each element is a real fraction between 0 and 1; together they describe -the horizontal span that is visible in the window. -For example, if the first element is .2 and the second element is .7, -20% of the entry's text is off-screen to the left, the middle 50% is visible -in the window, and 30% of the text is off-screen to the right. -These are the same values passed to scrollbars via the B<-xscrollcommand> -option. - -=item I<$entry>-E<gt>B<xview>(I<index>) - -Adjusts the view in the window so that the character given by I<index> -is displayed at the left edge of the window. - -=item I<$entry>-E<gt>B<xviewMoveto>(I<fraction>) - -Adjusts the view in the window so that the character I<fraction> of the -way through the text appears at the left edge of the window. -I<Fraction> must be a fraction between 0 and 1. - -=item I<$entry>-E<gt>B<xviewScroll>(I<number, what>) - -This method shifts the view in the window left or right according to -I<number> and I<what>. -I<Number> must be an integer. -I<What> must be either B<units> or B<pages> or an abbreviation -of one of these. -If I<what> is B<units>, the view adjusts left or right by -I<number> average-width characters on the display; if it is -B<pages> then the view adjusts by I<number> screenfuls. -If I<number> is negative then characters farther to the left -become visible; if it is positive then characters farther to the right -become visible. - -=back - -=back - -=head1 DEFAULT BINDINGS - -Tk automatically creates class bindings for entries that give them -the following default behavior. -In the descriptions below, ``word'' refers to a contiguous group -of letters, digits, or ``_'' characters, or any single character -other than these. - -=over 4 - -=item [1] - -Clicking mouse button 1 positions the insertion cursor -just before the character underneath the mouse cursor, sets the -input focus to this widget, and clears any selection in the widget. -Dragging with mouse button 1 strokes out a selection between -the insertion cursor and the character under the mouse. - -=item [2] - -Double-clicking with mouse button 1 selects the word under the mouse -and positions the insertion cursor at the beginning of the word. -Dragging after a double click will stroke out a selection consisting -of whole words. - -=item [3] - -Triple-clicking with mouse button 1 selects all of the text in the -entry and positions the insertion cursor before the first character. - -=item [4] - -The ends of the selection can be adjusted by dragging with mouse -button 1 while the Shift key is down; this will adjust the end -of the selection that was nearest to the mouse cursor when button -1 was pressed. -If the button is double-clicked before dragging then the selection -will be adjusted in units of whole words. - -=item [5] - -Clicking mouse button 1 with the Control key down will position the -insertion cursor in the entry without affecting the selection. - -=item [6] - -If any normal printing characters are typed in an entry, they are -inserted at the point of the insertion cursor. - -=item [7] - -The view in the entry can be adjusted by dragging with mouse button 2. -If mouse button 2 is clicked without moving the mouse, the selection -is copied into the entry at the position of the mouse cursor. - -=item [8] - -If the mouse is dragged out of the entry on the left or right sides -while button 1 is pressed, the entry will automatically scroll to -make more text visible (if there is more text off-screen on the side -where the mouse left the window). - -=item [9] - -The Left and Right keys move the insertion cursor one character to the -left or right; they also clear any selection in the entry and set -the selection anchor. -If Left or Right is typed with the Shift key down, then the insertion -cursor moves and the selection is extended to include the new character. -Control-Left and Control-Right move the insertion cursor by words, and -Control-Shift-Left and Control-Shift-Right move the insertion cursor -by words and also extend the selection. -Control-b and Control-f behave the same as Left and Right, respectively. -Meta-b and Meta-f behave the same as Control-Left and Control-Right, -respectively. - -=item [10] - -The Home key, or Control-a, will move the insertion cursor to the -beginning of the entry and clear any selection in the entry. -Shift-Home moves the insertion cursor to the beginning of the entry -and also extends the selection to that point. - -=item [11] - -The End key, or Control-e, will move the insertion cursor to the -end of the entry and clear any selection in the entry. -Shift-End moves the cursor to the end and extends the selection -to that point. - -=item [12] - -The Select key and Control-Space set the selection anchor to the position -of the insertion cursor. They don't affect the current selection. -Shift-Select and Control-Shift-Space adjust the selection to the -current position of the insertion cursor, selecting from the anchor -to the insertion cursor if there was not any selection previously. - -=item [13] - -Control-/ selects all the text in the entry. - -=item [14] - -Control-\ clears any selection in the entry. - -=item [15] - -The F16 key (labelled Copy on many Sun workstations) or Meta-w -copies the selection in the widget to the clipboard, if there is a selection. - -=item [16] - -The F20 key (labelled Cut on many Sun workstations) or Control-w -copies the selection in the widget to the clipboard and deletes -the selection. -If there is no selection in the widget then these keys have no effect. - -=item [17] - -The F18 key (labelled Paste on many Sun workstations) or Control-y -inserts the contents of the clipboard at the position of the -insertion cursor. - -=item [18] - -The Delete key deletes the selection, if there is one in the entry. -If there is no selection, it deletes the character to the right of -the insertion cursor. - -=item [19] - -The BackSpace key and Control-h delete the selection, if there is one -in the entry. -If there is no selection, it deletes the character to the left of -the insertion cursor. - -=item [20] - -Control-d deletes the character to the right of the insertion cursor. - -=item [21] - -Meta-d deletes the word to the right of the insertion cursor. - -=item [22] - -Control-k deletes all the characters to the right of the insertion -cursor. - -=item [23] - -Control-t reverses the order of the two characters to the right of -the insertion cursor. - -If the entry is disabled using the B<-state> option, then the entry's -view can still be adjusted and text in the entry can still be selected, -but no insertion cursor will be displayed and no text modifications will -take place. - -The behavior of entries can be changed by defining new bindings for -individual widgets or by redefining the class bindings. - -=back - -=head1 KEYWORDS - -entry, widget - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Error.pod b/Master/tlpkg/tlperl/lib/Tk/Error.pod deleted file mode 100644 index 9c38f0b7d74..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Error.pod +++ /dev/null @@ -1,145 +0,0 @@ -# Copyright (c) 1990-1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::Error - Method invoked to process background errors - -=for category Binding Events and Callbacks - -=head1 SYNOPSIS - -Customization: - - require Tk::ErrorDialog; - -or - - sub Tk::Error - { - my ($widget,$error,@locations) = @_; - ... - - } - -=head1 DESCRIPTION - -The B<Tk::Error> method is invoked by perl/Tk when a background -error occurs. Two possible implementations are provided in the -distribution and individual applications or users can (re)define a B<Tk::Error> -method (e.g. as a perl sub) if they wish to handle background -errors in some other manner. - -A background error is one that occurs in a command that didn't -originate with the application. For example, if an error occurs -while executing a L<callback|Tk::callbacks> specified with a -L<bind|Tk::bind> or a L<after|Tk::after> -command, then it is a background error. For a non-background error, -the error can simply be returned up through nested subroutines -until it reaches the top-level code in the application; -then the application can report the error in whatever way it -wishes. When a background error occurs, the unwinding ends in -the Tk library and there is no obvious way for Tk to report -the error. - -When Tk detects a background error, it saves information about the -error and invokes the B<Tk::Error> method later when Tk is idle. - -B<Tk::Error> is invoked by perl/Tk as if by the perl code: - -S< >I<$mainwindow>-E<gt>B<Tk::Error>(I<"error message">, I<location ...>); - -I<$mainwindow> is the B<MainWindow> associated with widget which -detected the error, I<"error message"> is a string describing the error -that has been detected, I<location> is a list of one or more "locations" -which describe the call sequence at the point the error was detected. - -The locations are a typically a mixture of perl location reports giving -script name and line number, and simple strings describing locations in -core Tk or perl/Tk C code. - -Tk will ignore any result returned by the B<Tk::Error> method. -If another error occurs within the B<Tk::Error> method -(for example if it calls B<die>) then Tk reports this error -itself by writing a message to stderr (this is to avoid infinite loops -due to any bugs in B<Tk::Error>). - -If several background errors accumulate before B<Tk::Error> -is invoked to process them, B<Tk::Error> will be invoked once -for each error, in the order they occurred. -However, if B<Tk::Error> calls B<Tk-E<gt>break>, then -any remaining errors are skipped without calling B<Tk::Error>. - -The B<Tk> module includes a default B<Tk::Error> subroutine -that simply reports the error on stderr. - -=head1 Tk::ErrorDialog - -An alternate definition is provided via: - -S< >C<require Tk::ErrorDialog;> - -that posts a dialog box containing the error message and offers -the user a chance to see a stack trace showing where the -error occurred. - -This is an OO implementation of the Tcl/Tk command B<bgerror>, with a -twist: since there is only one B<ErrorDialog> widget, you aren't required -to invoke the constructor to create it; it will be created -automatically when the first background error occurs. However, in -order to configure the I<-cleanupcode> and I<-appendtraceback> -B<ErrorDialog> options you must call the constructor and create it -manually. - -The B<ErrorDialog> object essentially consists of two subwidgets: a -B<Dialog> widget to display the background error and a B<Text> widget -for the traceback information. If required, you can invoke various -widget methods to customize these subwidgets - their advertised names -are described below. - -S< >I<$mw>-E<gt>B<ErrorDialog>(-cleanupcode => I<code>, -appendtraceback => I<bool>); - -$mw is a window reference. - -I<code> is a CODE reference if special post-background error -processing is required (default is undefined). The callback subroutine -is called with @_ having the same arguments that B<Tk::Error> was -invoked with. - -I<bool> is a boolean indicating whether or not to append successive -tracebacks (default is 1, do append). - -=head2 Advertised ErrorDialog widgets - -I<error_dialog> is the Dialog widget reference. - -I<text> is the Text widget reference containing the traceback information. - -=head1 BUGS - -If B<after> or B<fileevent> are not invoked as methods of a widget -then perl/Tk is unable to provide a I<$mainwindow> argument. -To support such code from earlier versions of perl/Tk -perl/Tk therefore calls B<Tk::Error> with string 'Tk' instead: -B<Tk-E<gt>Tk::Error\(...\)>. -In this case the B<Tk::Error> in B<Tk::ErrorDialog> and similar -implementations cannot "popup" a window as they don't know which display -to use. A mechanism to supply I<the> B<MainWindow> in applications -which only have one (a very common case) should be provided. - -=head1 SEE ALSO - -L<Tk::bind|Tk::bind> -L<Tk::after|Tk::after> -L<Tk::fileevent|Tk::fileevent> - -=head1 KEYWORDS - -background error, reporting - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Eventloop.pod b/Master/tlpkg/tlperl/lib/Tk/Eventloop.pod deleted file mode 100644 index a4c99e7988e..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Eventloop.pod +++ /dev/null @@ -1,62 +0,0 @@ - -=head1 NAME - -Tk::Event - ToolKit for Events - -=for category Implementation - -=head1 SYNOPSIS - - use Tk::Event; - - Tk::Event->fileevent(\*FH, 'readable' => callback); - - Tk::Event->lineavail(\*FH, callback); - - use Tk::Event::Signal qw(INT); - - $SIG{'INT'} = callback; - - use Tk::Event::process; - - Tk::Event->proc($pid, callback); - - QueueEvent(callback [, position]) - - -=head1 DESCRIPTION - - -That is better than nothing but still hard to use. Most scripts want higher -level result (a line, a "block" of data etc.) - -So it has occured to me that we could use new-ish TIEHANDLE thus: - - my $obj = tie SOMEHANDLE,Tk::Event::IO; - - while (<SOMEHANDLE>) - { - } - -Then the READLINE routine registers a callback and looks something like: - - sub READLINE - { - my $obj = shift; - Event->io(*$obj,'readable',sub { sysread(*$obj,${*$obj},1,length(${*$obj}) }); - my $pos; - while (($pos = index(${*$obj},$/) < 0) - { - DoOneEvent(); - } - Event->io(*$obj,'readable',''); # unregister - $pos += length($/); - my $result = substr(${*$obj},0,$pos); - substr(${*$obj},0,$pos) = ''; - return $result; - } - -This is using the scalar part of the glob representing the _inner_ IO -as a buffer in which to accumulate chars. - -=cut diff --git a/Master/tlpkg/tlperl/lib/Tk/FBox.pod b/Master/tlpkg/tlperl/lib/Tk/FBox.pod deleted file mode 100644 index dada482a761..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/FBox.pod +++ /dev/null @@ -1,67 +0,0 @@ -=head1 NAME - -Tk::FBox - a file dialog - -=for pm Tk/FBox.pm - -=for category Popups and Dialogs - -=head1 SYNOPSIS - - use Tk::FBox; - $file = $mw->FBox(...)->Show; - -=head1 DESCRIPTION - -C<Tk::FBox> is the dialog implementation behind the C<getOpenFile>, -C<getSaveFile>, and C<chooseDirectory> method calls in the Unix/X11 -world. As such, it supports all options for these methods and -additionally: - -=over - -=item -sortcmd => sub { $_[0] cmp $_[1] } - -Specified a callback for changing the sorting of the icons in the -C<IconList> widget. By default, perl's C<cmp> operator will be used. - -From the source code: - - # Using -sortcmd is really strange :-( - # $top->getOpenFile(-sortcmd => sub { package Tk::FBox; uc $b cmp uc $a}); - # or, un-perlish, but useable (now activated in code): - # $top->getOpenFile(-sortcmd => sub { uc $_[1] cmp uc $_[0]}); - -This is an experimental option! - -=item -type => $type - -Type should be "open" for choosing existing files to open (default), -"save" for choosing existing or non-existing files to save, or "dir" -for choosing directories. - -=item -filter => $glob - -A file glob to restrict displayed files. This is only active if no -B<-filetypes> are defined. - -=item -force => $bool - -If true, then there will be no dialog if a file already exists. - -=back - -=head1 COPYRIGHT - -The original tkfbox.tcl from Tcl/Tk is: - -Copyright (c) 1994-1996 Sun Microsystems, Inc. - -See the file "license.terms" for information on usage and redistribution -of this file, and for a DISCLAIMER OF ALL WARRANTIES. - -Translated to Perl/Tk by Slaven Rezic <srezic@cpan.org>. - -=head1 SEE ALSO - -L<Tk::getOpenFile>, L<Tk::IconList>. diff --git a/Master/tlpkg/tlperl/lib/Tk/FileSelect.pod b/Master/tlpkg/tlperl/lib/Tk/FileSelect.pod deleted file mode 100644 index 2ea633de674..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/FileSelect.pod +++ /dev/null @@ -1,150 +0,0 @@ - -=head1 NAME - -Tk::FileSelect - a widget for choosing files - -=for pm Tk/FileSelect.pm - -=for category Popups and Dialogs - -=head1 SYNOPSIS - - use Tk::FileSelect; - - $FSref = $top->FileSelect(-directory => $start_dir); - $top - a window reference, e.g. MainWindow->new - $start_dir - the starting point for the FileSelect - $file = $FSref->Show; - Executes the fileselector until either a filename is - accepted or the user hits Cancel. Returns the filename - or the empty string, respectively, and unmaps the - FileSelect. - $FSref->configure(option => value[, ...]) - Please see the Populate subroutine as the configuration - list changes rapidly. - -=head1 DESCRIPTION - -This Module pops up a Fileselector box, with a directory entry on -top, a list of directories in the current directory, a list of -files in the current directory, an entry for entering/modifying a -file name, an accept button and a cancel button. - -You can enter a starting directory in the directory entry. After -hitting Return, the listboxes get updated. Double clicking on any -directory shows you the respective contents. Single clicking on a -file brings it into the file entry for further consideration, -double clocking on a file pops down the file selector and calls -the optional command with the complete path for the selected file. -Hitting return in the file selector box or pressing the accept -button will also work. *NOTE* the file selector box will only then -get destroyed if the file name is not zero length. If you want -yourself take care of it, change the if(length(.. in sub -accept_file. - -=head1 AUTHORS - -Based on original FileSelect by -Klaus Lichtenwalder, Lichtenwalder@ACM.org, Datapat GmbH, Munich, -April 22, 1995 adapted by -Frederick L. Wagner, derf@ti.com, Texas Instruments Incorporated, Dallas, -21Jun95 - -=head1 HISTORY - -=head2 950621 -- The following changes were made: - -=over 4 - -=item * - -Rewrote Tk stuff to take advantage of new Compound widget module, so -FileSelect is now composed of 2 LabEntry and 2 ScrlListbox2 -subwidgets. - -=item * - -Moved entry labels (from to the left of) to above the entry fields. - -=item * - -Caller is now able to control these aspects of widget, in both -FileSelect (new) and configure : - -(Please see subroutine Populate for details, as these options -change rapidly!) - -=item * - -I changed from Double-Button-1 to Button-1 in the Files listbox, -to work with multiple mode in addition to browse mode. I also -made some name changes (LastPath --> saved_path, ...). - -=item * - -The show method is not yet updated. - -=item * - -The topLevel stuff is not done yet. I took it out while I toy with -the idea of FileSelect as a subwidget. Then the 'normal' topLevel -thing with Buttons along the bottom could be build on top of it. - -=item * - -By request of Henry Katz <katz@fs09.webo.dg.com>, I added the functionality -of using the Directory entry as a filter. So, if you want to only see the -*.c files, you add a .c (the *'s already there :) and hit return. - -=back - -=head2 95/10/17, SOL, LUCC. lusol@Lehigh.EDU - -=over 4 - -=item * - - Allow either file or directory names to be accepted. - -=item * - -Require double click to move into a new directory rather than a single -click. This allows a single click to select a directory name so it can -be accepted. - -=item * - -Add -verify list option so that standard Perl file test operators (like --d and -x) can be specified for further name validation. The default -value is the special value '!-d' (not a directory), so any name can be -selected as long as it's not a directory - after all, this IS FileSelect! - -For example: - - $fs->configure(-verify => ['-d', [\&verify_code, $P1, $P2, ... $Pn]]); - -ensures that the selected name is a directory. Further, if an element of -the list is an array reference, the first element is a code reference to a -subroutine and the remaining optional elements are it's parameters. The -subroutine is called like this: - - &verify_code($cd, $leaf, $P1, $P2, ... $Pn); - -where $cd is the current directory, $leaf is a directory or file name, and -$P1 .. $Pn are your optional parameters. The subroutine should return TRUE -if success or FALSE if failure. - -=back - -=head2 961008 -- derf@ti.com : - -By request of Jim Stern <js@world.northgrum.com> and Brad Vance -<bvance@ti.com>, I updated the Accept and Show functions to support -selection of multiple files. I also corrected a typo in the -verify code. - -=head1 SEE ALSO - -L<Tk::getOpenFile>, L<Tk::FBox>. - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Font.pod b/Master/tlpkg/tlperl/lib/Tk/Font.pod deleted file mode 100644 index 594efa58bca..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Font.pod +++ /dev/null @@ -1,407 +0,0 @@ -# Copyright (c) 1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -font - Create and inspect fonts. - -=for category Tk Generic Methods - -=head1 SYNOPSIS - -S< >I<$widget>->B<Font>(I<option>?, I<arg, arg, ...>?) - -S< >I<$font>->I<Option>?(I<arg, arg, ...>)? - -=head1 DESCRIPTION - -The B<Font> method provides several facilities for dealing with -fonts, such as defining named fonts and inspecting the actual attributes of -a font. The command has several different forms, determined by the -first argument. The following forms are currently supported: - -=over 4 - -=item I<$font>-E<gt>B<actual>(I<-option>?) - -=item I<$widget>-E<gt>B<fontActual>(I<font>?, I<-option>?) - -Returns information about the actual attributes that are obtained when -I<font> is used on I<$font>'s display; the actual attributes obtained -may differ from the attributes requested due to platform-dependant -limitations, such as the availability of font families and pointsizes. -I<font> is a font description; see L<"FONT DESCRIPTION"> below. If -I<option> is specified, returns the value of that attribute; if it is -omitted, the return value is a list of all the attributes and their values. -See L<"FONT OPTIONS"> below for a list of the possible attributes. - -=item I<$font>-E<gt>B<configure>(I<-option>??=>I<value>, I<-option>=>I<value>, ...?) - -Query or modify the desired attributes for I<$font>. -If no I<-option> is specified, returns a list describing -all the options and their values for I<fontname>. If a single I<-option> -is specified with no I<value>, then returns the current value of that -attribute. If one or more I<option-value> pairs are specified, -then the method modifies the given named font to have the given values; in -this case, all widgets using that font will redisplay themselves using the -new attributes for the font. See L<"FONT OPTIONS"> below for a list of the -possible attributes. - -Note: the above behaviour differs in detail to B<configure> on widgets, -images etc. - -=item I<$font> = I<$widget>-E<gt>B<Font>(I<-option>=>I<value>, ...>?) - -=item I<$font> = I<$widget>-E<gt>B<fontCreate>(?I<fontname>??, I<-option>=>I<value>, ...>?) - -Creates a new font object and returns a reference to it. -I<fontname> specifies the name for the font; if it is omitted, then Tk generates -a new name of the form B<font>I<x>, where I<x> is an integer. There may be any -number of I<option-value> pairs, which provide the desired attributes for -the new named font. See L<"FONT OPTIONS"> below for a list of the possible -attributes. - -Note: the created font is I<not> shared between widgets of different -L<MainWindow|Tk::MainWindow>s. - -=item I<$font>-E<gt>B<delete> - -=item I<$widget>-E<gt>B<fontDelete>(I<fontname>?, I<fontname>, ...?) - -Delete the specified named fonts. If there are widgets using the named font, -the named font won't actually be deleted until all the instances are -released. Those widgets will continue to display using the last known values -for the named font. If a deleted named font is subsequently recreated with -another call to B<fontCreate>, the widgets will use the new named font -and redisplay themselves using the new attributes of that font. - -=item I<$widget>-E<gt>B<fontFamilies> - -The return value is a list of the case-insensitive names of all font families -that exist on I<$widget>'s display. - -=item I<$font>-E<gt>B<measure>(I<text>) - -=item I<$widget>-E<gt>B<fontMeasure>(I<font>, I<text>) - -Measures the amount of space the string I<text> would use in the given -I<font> when displayed in I<$widget>. I<font> is a font description; -see L<"FONT DESCRIPTION"> below. -The return value is the total width in pixels -of I<text>, not including the extra pixels used by highly exagerrated -characters such as cursive ``I<f>''. If the string contains newlines or tabs, -those characters are not expanded or treated specially when measuring the -string. - -=item I<$font>-E<gt>B<metrics>(I<-option>?) - -=item I<$widget>-E<gt>B<fontMetrics>(I<font>?, I<-option>?) - -Returns information about the metrics (the font-specific data), for -I<font> when it is used on I<$widget>'s display. I<font> is a font -description; see L<"FONT DESCRIPTION"> below. -If I<option> is specified, -returns the value of that metric; if it is omitted, the return value is a -list of all the metrics and their values. See L<"FONT METRICS"> below for a list -of the possible metrics. - -=item I<$widget>-E<gt>B<fontNames> - -The return value is a list of all font objects that are currently defined for -I<$widget>'s MainWindow. - -=back - -=head1 FONT DESCRIPTION - -The following formats are accepted as a font description anywhere -I<font> is specified as an argument above; these same forms are also -permitted when specifying the B<-font> option for widgets. - -=over 4 - -=item [1] I<fontname> - -The name of a named font, created using the B<fontCreate> method. When -a widget uses a named font, it is guaranteed that this will never cause an -error, as long as the named font exists, no matter what potentially invalid -or meaningless set of attributes the named font has. If the named font -cannot be displayed with exactly the specified attributes, some other close -font will be substituted automatically. - -=item [1a] I<$font> - -A font object created using the B<Font> method. This is essentially the same -as using a named font. The object is a reference to the name, and carries -additional information e.g. which MainWindow it relates to in an manner peculiar -to perl/Tk. - -=item [3] I<systemfont> - -The platform-specific name of a font, interpreted by the graphics server. -This also includes, under X, an XLFD (see L<[4]|/[4]>) for which a single ``B<*>'' -character was used to elide more than one field in the middle of the -name. See L<"PLATFORM-SPECIFIC ISSUES"> for a list of the system fonts. - -=item [3] [I<family>,?I<size>,??I<style>,??I<style ...>?] - -A properly formed list whose first element is the desired font -I<family> and whose optional second element is the desired I<size>. -The interpretation of the I<size> attribute follows the same rules -described for L<-size|/-size> in L<"FONT OPTIONS"> below. Any additional optional -arguments following the I<size> are font I<style>s. Possible values -for the I<style> arguments are as follows: - - normal bold roman italic - underline overstrike - -=item [4] X-font names (XLFD) - -A Unix-centric font name of the form -I<-foundry-family-weight-slant-setwidth-addstyle-pixel-point-resx-resy-spacing-width-charset-encoding>. -The ``B<*>'' character may be used to skip individual fields that the -user does not care about. There must be exactly one ``B<*>'' for each -field skipped, except that a ``B<*>'' at the end of the XLFD skips any -remaining fields; the shortest valid XLFD is simply ``B<*>'', signifying -all fields as defaults. Any fields that were skipped are given default -values. For compatibility, an XLFD always chooses a font of the specified -pixel size (not point size); although this interpretation is not strictly -correct, all existing applications using XLFDs assumed that one ``point'' -was in fact one pixel and would display incorrectly (generally larger) if -the correct size font were actually used. - -=item [5] I<option value >?I<option value ...>? - -A properly formed list of I<option-value> pairs that specify -the desired attributes of the font, in the same format used when defining -a named font; see L<"FONT OPTIONS"> below. - -=back - -When font description I<font> is used, the system attempts to parse the -description according to each of the above five rules, in the order specified. -Cases [1] and [2] must match the name of an existing named font or of a -system font. Cases [3], [4], and [5] are accepted on all -platforms and the closest available font will be used. In some situations -it may not be possible to find any close font (e.g., the font family was -a garbage value); in that case, some system-dependant default font is -chosen. If the font description does not match any of the above patterns, -an error is generated. - -=head1 FONT METRICS - -The following options are used by the B<metrics>/B<fontMetrics> method to query -font-specific data determined when the font was created. These properties are -for the whole font itself and not for individual characters drawn in that -font. In the following definitions, the ``baseline'' of a font is the -horizontal line where the bottom of most letters line up; certain letters, -such as lower-case ``g'' stick below the baseline. - -=over 4 - -=item B<-ascent> - -The amount in pixels that the tallest letter sticks up above the baseline of -the font, plus any extra blank space added by the designer of the font. -(I<$font>-E<gt>B<ascent> is provided for compatibility.) - -=item B<-descent> - -The largest amount in pixels that any letter sticks down below the baseline -of the font, plus any extra blank space added by the designer of the font. -(I<$font>-E<gt>B<descent> is provided for compatibility.) - -=item B<-linespace> - -Returns how far apart vertically in pixels two lines of text using the same -font should be placed so that none of the characters in one line overlap any -of the characters in the other line. This is generally the sum of the ascent -above the baseline line plus the descent below the baseline. - -=item B<-fixed> - -Returns a boolean flag that is ``B<1>'' if this is a fixed-width font, -where each normal character is the the same width as all the other -characters, or is ``B<0>'' if this is a proportionally-spaced font, where -individual characters have different widths. The widths of control -characters, tab characters, and other non-printing characters are not -included when calculating this value. - -=back - -=head1 FONT OPTIONS - -The following options are supported on all platforms, and are used when -constructing a named font or when specifying a font using style [5] as -above: - -=over 4 - -=item B<-family> => I<name> - -The case-insensitive font family name. Tk guarantees to support the font -families named B<Courier> (a monospaced ``typewriter'' font), B<Times> -(a serifed ``newspaper'' font), and B<Helvetica> (a sans-serif -``European'' font). The most closely matching native font family will -automatically be substituted when one of the above font families is used. -The I<name> may also be the name of a native, platform-specific font -family; in that case it will work as desired on one platform but may not -display correctly on other platforms. If the family is unspecified or -unrecognized, a platform-specific default font will be chosen. - -=item B<-size> => I<size> - -The desired size of the font. If the I<size> argument is a positive -number, it is interpreted as a size in points. If I<size> is a negative -number, its absolute value is interpreted as a size in pixels. If a -font cannot be displayed at the specified size, a nearby size will be -chosen. If I<size> is unspecified or zero, a platform-dependent default -size will be chosen. - -The original Tcl/Tk authors believe sizes should normally be specified in points -so the application will remain the same ruler size on the screen, even when -changing screen resolutions or moving scripts across platforms. While this is an -admirable goal it does not work as well in practice as they hoped. -The mapping between points and pixels is set when the application starts, based -on alleged properties of the installed monitor, but it can be overridden by -calling the L<scaling|Tk::Widget/scaling> command. However this can be -problematic when system has no way of telling if (say) an 11" or 22" monitor is -attached, also if it I<can> tell then some monitor sizes may result in poorer -quality scaled fonts being used rather than a "tuned" bitmap font. -In addition specifying pixels is useful in certain circumstances such as when a piece of text -must line up with respect to a fixed-size bitmap. - -At present the Tcl/Tk scheme is used unchanged, with "point" size being returned -by I<actual> (as an integer), and used internally. Suggestions for work-rounds -to undesirable behaviour welcome. - -=item B<-weight> => I<weight> - -The nominal thickness of the characters in the font. The value -B<normal> specifies a normal weight font, while B<bold> specifies a -bold font. The closest available weight to the one specified will -be chosen. The default weight is B<normal>. - -=item B<-slant> => I<slant> - -The amount the characters in the font are slanted away from the -vertical. Valid values for slant are B<roman> and B<italic>. -A roman font is the normal, upright appearance of a font, while -an italic font is one that is tilted some number of degrees from upright. -The closest available slant to the one specified will be chosen. -The default slant is B<roman>. - -=item B<-underline> => I<boolean> - -The value is a boolean flag that specifies whether characters in this -font should be underlined. The default value for underline is B<false>. - -=item B<-overstrike> => I<boolean> - -The value is a boolean flag that specifies whether a horizontal line should -be drawn through the middle of characters in this font. The default value -for overstrike is B<false>. - -=back - -=head1 PLATFORM-SPECIFIC ISSUES - -The following named system fonts are supported: - -=over 4 - -=item X Windows: - -All valid X font names, including those listed by xlsfonts(1), are available. - -=item MS Windows: - - system ansi device - systemfixed ansifixed oemfixed - -=item Macintosh: - - system application - -=back - -=head1 COMPATIBILITY WITH PREVIOUS VERSIONS - -In prior versions of perl/Tk the I<$widget>-E<gt>B<Font> method was a perl -wrapper on the original "[4] X-font names (XLFD)" style as described above -(which was the only form supported by versions of core tk prior to version -tk8.0). -This module is provided in its original form (it has just been renamed) -via: - - use Tk::X11Font; - I<$widget>-E<gt>B<X11Font>(...) - -However the methods of the old scheme have been mimiced as closely as possible -with the new scheme. It is intended that code should work without modification, -except for the case of using : - - @names = $font->Name; - -i.e. the I<Name> method in an array/list context. This now returns one element -on all platforms (as it did on Win32), while previously on X systems it returned -a list of fonts that matched an under-specified pattern. - -Briefly the methods supported for compatibilty are as follows: - -=over 4 - -=item $newfont = I<$font>-E<gt>B<Clone>(I<-option>=>I<value>, ...>?) - -Returns a new font object I<$newfont> related to the original I<$font> by -changing the values of the specified I<-option>s. - -=item I<$font>-E<gt>Family - maps to -family - -=item I<$font>-E<gt>Weight - maps to -weight - -=item I<$font>-E<gt>Slant - maps to -slant - -=item I<$font>-E<gt>Pixel and Point - map to -size - -=back - -New code should use I<$font>-E<gt>B<configure> to achieve same effect as last -four items above. - -=over 4 - -=item Foundry, Swidth, Adstyle, Xres, Yres, Space, Avgwidth, Registry, Encoding - -Are all ignored if set, and return '*' if queried. - -=item I<$font>-E<gt>B<Name> - -Returns the name of a named font, or a string representation of an unnamed -font. Using I<$font> in a scalar context does the same. Note this is distinctly -different from behaviour of L<X11Font's Name|Tk::X11Font/Name( [ $max ] )> in -a list context. - -=item I<$font>-E<gt>B<Pattern> - -Returns a XLFD string for the font based on I<actual> values, and some heuristics -to map Tk's forms to the "standard" X conventions. - -=back - - -=head1 SEE ALSO - -L<Tk::options|Tk::options> - -L<Tk::X11Font|Tk::X11Font> - -=head1 KEYWORDS - -font - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Frame.pod b/Master/tlpkg/tlperl/lib/Tk/Frame.pod deleted file mode 100644 index 6570b6a18c7..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Frame.pod +++ /dev/null @@ -1,146 +0,0 @@ -# Copyright (c) 1990-1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::Frame - Create and manipulate Frame widgets - -=for category Tk Widget Classes - -=head1 SYNOPSIS - -S< >I<$frame> = I<$parent>-E<gt>B<Frame>(?I<options>?); - -=head1 STANDARD OPTIONS - -B<-borderwidth> B<-highlightbackground> B<-highlightthickness> B<-takefocus> -B<-class> B<-highlightcolor> B<-relief> -B<-cursor> - -See L<Tk::options> for details of the standard options. - -=head1 WIDGET-SPECIFIC OPTIONS - -=over 4 - -=item Name: B<background> - -=item Class: B<Background> - -=item Switch: B<-background> - -This option is the same as the standard B<background> option -except that its value may also be specified as an undefined value. -In this case, the widget will display no background or border, and -no colors will be consumed from its colormap for its background -and border. - -=item Name: B<colormap> - -=item Class: B<Colormap> - -=item Switch: B<-colormap> - -Specifies a colormap to use for the window. -The value may be either B<new>, in which case a new colormap is -created for the window and its children, or the name of another -window (which must be on the same screen and have the same visual -as $widget), in which case the new window will use the colormap -from the specified window. -If the B<colormap> option is not specified, the new window -uses the same colormap as its parent. -This option may not be changed with the B<configure> -method. - -=item Name: B<container> - -=item Class: B<Container> - -=item Switch: B<-container> - -The value must be a boolean. If true, it means that this window will -be used as a container in which some other application will be embedded -(for example, a Tk toplevel can be embedded using the B<-use> option). -The window will support the appropriate window manager protocols for -things like geometry requests. The window should not have any -children of its own in this application. -This option may not be changed with the B<configure> -method. - -=item Name: B<height> - -=item Class: B<Height> - -=item Switch: B<-height> - -Specifies the desired height for the window in any of the forms -acceptable to B<Tk_GetPixels>. -If this option is less than or equal to zero then the window will -not request any size at all. - -=item Name: B<visual> - -=item Class: B<Visual> - -=item Switch: B<-visual> - -Specifies visual information for the new window in any of the -forms accepted by B<Tk_GetVisual>. -If this option is not specified, the new window will use the same -visual as its parent. -The B<visual> option may not be modified with the B<configure> -method. - -=item Name: B<width> - -=item Class: B<Width> - -=item Switch: B<-width> - -Specifies the desired width for the window in any of the forms -acceptable to B<Tk_GetPixels>. -If this option is less than or equal to zero then the window will -not request any size at all. - -=back - -=head1 DESCRIPTION - -The B<Frame> method creates a new window (given by the -$widget argument) and makes it into a frame widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the frame such as its background color -and relief. The B<frame> command returns the -path name of the new window. - -A frame is a simple widget. Its primary purpose is to act as a -spacer or container for complex window layouts. The only features -of a frame are its background color and an optional 3-D border to make the -frame appear raised or sunken. - -=head1 WIDGET METHODS - -The B<Frame> method creates a widget object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. -The widget also inherits all the methods provided by the generic -L<Tk::Widget|Tk::Widget> class. - -=head1 BINDINGS - -When a new frame is created, it has no default event bindings: -frames are not intended to be interactive. - -=head1 KEYWORDS - -frame, widget - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/HList.pod b/Master/tlpkg/tlperl/lib/Tk/HList.pod deleted file mode 100644 index 0843e689843..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/HList.pod +++ /dev/null @@ -1,1050 +0,0 @@ -# Copyright (c) 1996, Expert Interface Technologies -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# The file man.macros and some of the macros used by this file are -# copyrighted: (c) 1990 The Regents of the University of California. -# (c) 1994-1995 Sun Microsystems, Inc. -# The license terms of the Tcl/Tk distribution are in the file -# license.tcl. - -=head1 NAME - -Tk::HList - Create and manipulate Tix Hierarchial List widgets - -=for category Tk Widget Classes - -=head1 SYNOPSIS - -I<$hlist> = I<$parent>-E<gt>B<HList>(?I<options>?); - -=head1 STANDARD OPTIONS - -B<-background> B<-borderwidth> B<-cursor> B<-exportselection> -B<-foreground> B<-font> B<-height> B<-highlightcolor> -B<-highlightthickness> B<-relief> B<-selectbackground> -B<-selectforeground> B<-xscrollcommand> B<-yscrollcommand> -B<-width> - -See L<Tk::options> for details of the standard options. - -=head1 WIDGET-SPECIFIC OPTIONS - -=over 4 - -=item Name: B<browsecmd> - -=item Class: B<BrowseCmd> - -=item Switch: B<-browsecmd> - -Specifies a perl/Tk L<callback|Tk::callbacks> to be executed when the user browses through the -entries in the HList widget. - -=item Name: B<columns> - -=item Class: B<Columns> - -=item Switch: B<-columns> - -Specifies the number of columns in this HList widget. This option can -only be set during the creation of the HList widget and cannot be -changed subsequently. - -=item Name: B<command> - -=item Class: B<Command> - -=item Switch: B<-command> - -Specifies the perl/Tk L<callback|Tk::callbacks> to be executed when the user invokes a list -entry in the HList widget. Normally the user invokes a list -entry by double-clicking it or pressing the Return key. - -=item Name: B<drawBranch> - -=item Class: B<DrawBranch> - -=item Switch: B<-drawbranch> - -A Boolean value to specify whether branch line should be drawn to -connect list entries to their parents. - -=item Name: B<foreground> - -=item Class: B<Foreground> - -=item Switch: B<-foreground> - -=item Alias: B<-fg> - -B<[OBSOLETE]> Specifies the default foreground color for the list entries. - -=item Name: B<gap> - -=item Class: B<Gap> - -=item Switch: B<-gap> - -B<[OBSOLETE]> The default distance between the bitmap/image and the -text in list entries. - -=item Name: B<header> - -=item Class: B<Header> - -=item Switch: B<-header> - -A Boolean value specifying whether headers should be displayed for -this HList widget (see the B<header> method below). - -=item Name: B<height> - -=item Class: B<Height> - -=item Switch: B<-height> - -Specifies the desired height for the window in number of characters. - -=item Name: B<indent> - -=item Class: B<Indent> - -=item Switch: B<-indent> - -Specifies the amount of horizontal indentation between a list entry -and its children. Must be a valid screen distance value. - -=item Name: B<indicator> - -=item Class: B<Indicator> - -=item Switch: B<-indicator> - -Specifies whether the indicators should be displayed inside the HList -widget. See the B<indicator> method below. - -=item Name: B<indicatorCmd> - -=item Class: B<IndicatorCmd> - -=item Switch: B<-indicatorcmd> - -Specifies a perl/Tk L<callback|Tk::callbacks> to be executed when the user manipulates the -indicator of an HList entry. The B<-indicatorcmd> is triggered -when the user press or releases the mouse button over the indicator in -an HList entry. By default the perl/Tk B<callback> specified by -B<-indicatorcmd> is executed with two additional arguments, the -entryPath of the entry whose indicator has been triggered and additional -information about the event. The additional information is one of the -following strings: B<E<lt>ArmE<gt>>, B<E<lt>DisarmE<gt>>, -and B<E<lt>ActivateE<gt>>. - -=item Name: B<itemType> - -=item Class: B<ItemType> - -=item Switch: B<-itemtype> - -Specifies the default type of display item for this HList widget. When -you call the B<itemCreate>, B<add> and B<addchild> methods, display -items of this -type will be created if the B<-itemtype> option is not specified . - -=item Name: B<padX> - -=item Class: B<Pad> - -=item Switch: B<-padx> - -B<[OBSOLETE]> The default horizontal padding for list entries. - -=item Name: B<padY> - -=item Class: B<Pad> - -=item Switch: B<-padx> - -B<[OBSOLETE]> The default vertical padding for list entries. - -=item Name: B<selectBackground> - -=item Class: B<SelectBackground> - -=item Switch: B<-selectbackground> - -Specifies the background color for the selected list entries. - -=item Name: B<selectBorderWidth> - -=item Class: B<BorderWidth> - -=item Switch: B<-selectborderwidth> - -Specifies a non-negative value indicating the width of the 3-D border -to draw around selected items. The value may have any of the forms -acceptable to B<Tk_GetPixels>. - -=item Name: B<selectForeground> - -=item Class: B<SelectForeground> - -=item Switch: B<-selectforeground> - -Specifies the foreground color for the selected list entries. - -=item Name: B<selectMode> - -=item Class: B<SelectMode> - -=item Switch: B<-selectmode> - -Specifies one of several styles for manipulating the selection. The -value of the option may be arbitrary, but the default bindings expect -it to be either B<single>, B<browse>, B<multiple>, or -B<extended>; the default value is B<single>. - -=item Name: B<sizeCmd> - -=item Class: B<SizeCmd> - -=item Switch: B<-sizecmd> - -Specifies a perl/Tk L<callback|Tk::callbacks> to be called whenever the HList widget -changes its size. This method can be useful to implement ``I<user scroll -bars when needed>'' features. - -=item Name: B<separator> - -=item Class: B<Separator> - -=item Switch: B<-separator> - -Specifies the character to used as the separator character when -intepreting the path-names of list entries. By default the character -"." is used. - -=item Name: B<width> - -=item Class: B<Width> - -=item Switch: B<-width> - -Specifies the desired width for the window in characters. - -=back - -=head1 DESCRIPTION - -The B<HList> method creates a new window (given by the -$widget argument) and makes it into a HList widget. -Additional options, described above, may be specified on the command -line or in the option database to configure aspects of the -HList widget such as its cursor and relief. - -The HList widget can be used to display any data that have a -hierarchical structure, for example, file system directory trees. The -list entries are indented and connected by branch lines according to -their places in the hierachy. - -Each list entry is identified by an B<entryPath>. The entryPath is a -sequence of B<entry names> separated by the separator charactor -(specified by the B<-separator> option). An B<entry name> can be -any string that does not contain the separator charactor, or it can be -the a string that contains only one separator charactor. - -For example, when "." is used as the separator charactor, -"one.two.three" is the entryPath for a list entry whose parent is -"one.two", whose parent is "one", which is a toplevel entry (has no -parents). - -Another examples: ".two.three" is the entryPath for a list entry whose -parent is ".two", whose parent is ".", which is a toplevel entry. - -=head1 DISPLAY ITEMS - -Each list entry in an HList widget is associated with a B<display> -item. The display item determines what visual information should -be displayed for this list entry. Please see L<Tk::DItem> -for a list of all display items. -When a list entry is created by the B<itemCreate>, B<add> or -B<addchild> widget -methods, the type of its display item is determined by the -B<-itemtype> option passed to these methods. If the -B<-itemtype> is omitted, then by default the type specified by -this HList widget's B<-itemtype> option is used. - -=head1 WIDGET METHODS - -The B<HList> method creates a widget object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. -The widget also inherits all the methods provided by the generic -L<Tk::Widget|Tk::Widget> class. - -The following additional methods are available HList widgets: - -=over 4 - -=item I<$hlist>-E<gt>B<add>(I<$entryPath> ?,I<option>=E<gt>I<value>, ...?) - -Creates a new list entry with the pathname I<$entryPath>. A list -entry must be created after its parent is created (unless this entry -is a top-level entry, which has no parent). See also L<"BUGS"> below. -This method returns the -entryPath of the newly created list entry. The following -configuration options can be given to configure the list entry: - -=over 8 - -=item B<-at> =E<gt> I<position> - -Insert the new list at the position given by I<position>. -I<position> must be a valid integer. The position B<0> indicates -the first position, B<1> indicates the second position, and so on. - -=item B<-after> =E<gt> I<afterWhich> - -Insert the new list entry after the entry identified by -I<afterWhich>. I<afterWhich> must be a valid list entry and it -mush have the same parent as the new list entry - -=item B<-before> =E<gt> I<beforeWhich> - -Insert the new list entry before the entry identified by -I<beforeWhich>. I<beforeWhich> must be a valid list entry and it -mush have the same parent as the new list entry - -=item B<-data> =E<gt> I<string> - -Specifies a string to associate with this list entry. This string can -be queried by the B<info> method. The application -programmer can use the B<-data> option to associate the list entry -with the data it represents. - -=item B<-itemtype> =E<gt> I<type> - -Specifies the type of display item to be display for the new list -entry. B<type> must be a valid display item type. Currently the -available display item types are B<imagetext>, B<text>, and -$widget. If this option is not specified, then by default the -type specified by this HList widget's B<-itemtype> option is used. - -=item B<-state> =E<gt> I<state> - -Specifies whether this entry can be selected or invoked by the user. -Must be either B<normal> or B<disabled>. - -=back - -The B<add> method accepts additional configuration options -to configure the display item associated with this list entry. The set -of additional configuration options depends on the type of the display -item given by the B<-itemtype> option. Please see -L<Tk::DItem> for a list of the configuration options for -each of the display item types. - -=item I<$hlist>-E<gt>B<addchild>(I<$parentPath, >?I<option, value, ..., >?) - -Adds a new child entry to the children list of the list entry -identified by I<$parentPath>. Or, if I<$parentPath> is set to be -the empty string, then creates a new toplevel entry. The name of the -new list entry will be a unique name automatically generated by the -HList widget. Usually if I<$parentPath> is B<foo>, then the -entryPath of the new entry will be B<foo.0>, B<foo.1>, ... etc. -This method returns the entryPath of the newly created list entry. -I<option> can be any option for the B<add> method. -See also L<"BUGS"> below. - -=item I<$hlist>-E<gt>B<anchorSet>(I<$entryPath>) - -Sets the anchor to the list entry identified by I<$entryPath>. The -anchor is the end of the selection that is fixed while the user is -dragging out a selection with the mouse. - -=item I<$hlist>-E<gt>B<anchorClear> - -Removes the anchor, if any, from this HList widget. This only -removes the surrounding highlights of the anchor entry and does not -affect its selection status. - -=item I<$hlist>-E<gt>B<columnWidth>(I<$col>?, I<-char>?, ?I<width>?) - -Querys or sets the width of a the column I<$col> in the HList -widget. The value of I<$col> is zero-based: 0 stands for the first -column, 1 stands for the second, and so on. If no further parameters -are given, returns the current width of this column (in number of -pixels). Additional parameters can be given to set the width of this -column: - -=over 8 - -=item I<$hlist>-E<gt>B<columnWidth>(I<$col>, B<''>) - -An empty string indicates that the width of the column should be just -wide enough to display the widest element in this column. In this -case, the width of this column may change as a result of the elements -in this column changing their sizes. - -=item I<$hlist>-E<gt>B<columnWidth>(I<$col, >I<width>) - -I<width> must be in a form accepted by B<Tk_GetPixels>. - -=item I<$hlist>-E<gt>B<columnWidth>(I<$col, >B<-char, >I<nChars>) - -The width is set to be the average width occupied by I<nChars> -number of characters of the font specified by the B<-font> option -of this HList widget. - -=back - -=item I<$hlist>-E<gt>B<delete>(I<option>, I<$entryPath>) - -Delete one or more list entries. I<option> may be one of the -following: - -=over 8 - -=item B<all> - -Delete all entries in the HList. In this case the I<$entryPath> -does not need to be specified. - -=item B<entry> - -Delete the entry specified by I<$entryPath> and all its offsprings, -if any. - -=item B<offsprings> - -Delete all the offsprings, if any, of the entry specified by -I<$entryPath>. However, I<$entryPath> itself is not deleted. - -=item B<siblings> - -Delete all the list entries that share the same parent with the entry -specified by I<$entryPath>. However, I<$entryPath> itself is not -deleted. - -=back - -=item I<$hlist>-E<gt>B<dragsiteSet>(I<$entryPath>) - -Sets the dragsite to the list entry identified by -I<$entryPath>. The dragsite is used to indicate the source of a -drag-and-drop action. Currently drag-and-drop functionality has not -been implemented in Tix yet. - -=item I<$hlist>-E<gt>B<dragsiteClear> - -Remove the dragsite, if any, from the this HList widget. This only -removes the surrounding highlights of the dragsite entry and does not -affect its selection status. - -=item I<$hlist>-E<gt>B<dropsiteSet>(I<$entryPath>) - -Sets the dropsite to the list entry identified by I<$entryPath>. The -dropsite is used to indicate the target of a drag-and-drop -action. Currently drag-and-drop functionality has not been implemented -in Tix yet. - -=item I<$hlist>-E<gt>B<dropsiteClear> - -Remove the dropsite, if any, from the this HList widget. This only -removes the surrounding highlights of the dropsite entry and does not -affect its selection status. - -=item I<$hlist>-E<gt>B<entrycget>(I<$entryPath>, I<option>) - -Returns the current value of the configuration option given by -I<option> for the entry indentfied by I<$entryPath>. I<Option> -may have any of the values accepted by the B<add> method. - -=item I<$hlist>-E<gt>B<entryconfigure>(I<$entryPath> ?,I<option>?, ?I<value>=E<gt>I<option>, ...?) - -Query or modify the configuration options of the list entry indentfied -by I<$entryPath>. If no I<option> is specified, returns a list -describing all of the available options for I<$entryPath> (see -L<Tk::options> for information on the format of this list.) If -I<option> is specified with no I<value>, then the method -returns a list describing the one named option (this list will be -identical to the corresponding sublist of the value returned if no -I<option> is specified). If one or more I<option-value> pairs -are specified, then the method modifies the given option(s) to have -the given value(s); in this case the method returns an empty string. -I<Option> may have any of the values accepted by the B<add> or -B<addchild> method. The exact set of options depends on the -value of the B<-itemtype> option passed to the the B<add> or -B<addchild> method when this list entry is created. - -=item I<$hlist>-E<gt>B<header>(I<option>, I<$col> ?,I<args>, ...?) - -Manipulates the header items of this HList widget. If the -B<-header> option of this HList widget is set to true, then a -header item is displayed at the top of each column. The I<$col> -argument for this method must be a valid integer. 0 indicates the -first column, 1 the second column, ... and so on. This method -supports the following options: - -=over 8 - -=item I<$hlist>-E<gt>B<header>(B<cget>, I<$col>, I<option>) - -If the I<$col>-th column has a header display item, returns the -value of the specified I<option> of the header item. If the header -doesn't exist, returns an error. - -=item I<$hlist>-E<gt>B<header>(B<configure, >I<$col, >?I<option>?, I<?value, option, value, ...>?) - -Query or modify the configuration options of the header display item -of the I<$col>-th column. The header item must exist, or an error -will result. If no I<option> is specified, returns a list -describing all of the available options for the header display item -(see L<Tk::options> for information on the format of this -list.) If I<option> is specified with no I<value>, then the -method returns a list describing the one named option (this list will -be identical to the corresponding sublist of the value returned if no -I<option> is specified). If one or more I<option-value> pairs -are specified, then the method modifies the given option(s) to have -the given value(s); in this case the method returns an empty -string. I<Option> may have any of the values accepted by the -B<header create> method. The exact set of options depends -on the value of the B<-itemtype> option passed to the the B<header> -create method when this display item was created. - -=item I<$hlist>-E<gt>B<header>(B<create, >I<$col, >?I<-itemtype type>? ?I<option value ...>? - -Creates a new display item as the header for the I<$col>-th -column. See also L<"BUGS"> below. -If an header display item already exists for this column, it -will be replaced by the new item. An optional parameter -I<-itemtype> can be used to specify what type of display item -should be created. If the I<-itemtype> is not given, then by -default the type specified by this HList widget's B<-itemtype> -option is used. Additional parameters, in I<option-value> pairs, -can be passed to configure the appearance of the display item. Each -I<option-value> pair must be a valid option for this type of -display item or one of the following: - -=over 12 - -=item B<-borderwidth> =E<gt> I<color> - -Specifies the border width of this header item. - -=item B<-headerbackground> =E<gt> I<color> - -Specifies the background color of this header item. - -=item B<-relief> =E<gt> I<type> - -Specifies the relief type of the border of this header item. - -=back - -=item I<$hlist>-E<gt>B<header>(B<delete, >I<$col>) - -Deletes the header display item for the I<$col>-th column. - -=item I<$hlist>-E<gt>B<header>(B<exists, >I<$col>) - -Return true if an header display item exists for the I<$col>-th -column; return false otherwise. - -=item I<$hlist>-E<gt>B<header>(B<size>, I<$col>) - -If an header display item exists for the I<$col>-th column , returns -its size in pixels in a two element list I<(width, height)>; -returns an error if the header display item does not exist. - -=back - -=item I<$hlist>-E<gt>B<hide>(I<option> ?,I<$entryPath>?) - -Makes some of entries invisible without deleting them. -I<Option> can be one of the following: - -=over 8 - -=item B<entry> - -Hides the list entry identified by I<$entryPath>. - -=back - -Currently only the B<entry> option is supported. Other options will -be added in the next release. - -=item I<$hlist>-E<gt>B<indicator>(I<option>, I<$entryPath>, ?I<args, ...>?) - -Manipulates the indicator on the list entries. An indicator is usually -a small display item (such as an image) that is displayed to the left -to an entry to indicate the status of the entry. For example, it may -be used to indicate whether a directory is opened or -closed. I<Option> can be one of the following: - -=over 8 - -=item I<$hlist>-E<gt>B<indicator>(B<cget>, I<$entryPath>, I<option>) - -If the list entry given by I<$entryPath> has an indicator, returns -the value of the specified I<option> of the indicator. If the -indicator doesn't exist, returns an error. - -=item I<$hlist>-E<gt>B<indicator>(B<configure>, I<$entryPath>, ?I<option>?, I<?value, option, value, ...>?) - -Query or modify the configuration options of the indicator display -item of the entry specified by I<$entryPath>. The indicator item -must exist, or an error will result. If no I<option> is specified, -returns a list describing all of the available options for the -indicator display item (see L<Tk::options> for information -on the format of this list). If I<option> is specified with no -I<value>, then the method returns a list describing the one named -option (this list will be identical to the corresponding sublist of -the value returned if no I<option> is specified). If one or more -I<option-value> pairs are specified, then the method modifies the -given option(s) to have the given value(s); in this case the method -returns an empty string. I<Option> may have any of the values -accepted by the B<indicator create> method. The exact set -of options depends on the value of the B<-itemtype> option passed -to the the B<indicator create> method when this display item -was created. - -=item I<$hlist>-E<gt>B<indicator>(B<create, >I<$entryPath, >?, I<-itemtype type>? ?I<option value ...>?) - -Creates a new display item as the indicator for the entry specified by -I<$entryPath>. If an indicator display item already exists for this -entry, it will be replaced by the new item. An optional parameter -I<-itemtype> can be used to specify what type of display item -should be created. If the I<-itemtype> is not given, then by -default the type specified by this HList widget's B<-itemtype> -option is used. Additional parameters, in I<option-value> pairs, -can be passed to configure the appearance of the display item. Each -I<option-value> pair must be a valid option for this type of -display item. - -=item I<$hlist>-E<gt>B<indicator>(B<delete>, I<$entryPath>) - -Deletes the indicator display item for the entry given by I<$entryPath>. - -=item I<$hlist>-E<gt>B<indicator>(B<exists>, I<$entryPath>) - -Return true if an indicator display item exists for the entry given by -I<$entryPath>; return false otherwise. - -=item I<$hlist>-E<gt>B<indicator>(B<size>, I<$entryPath>) - -If an indicator display item exists for the entry given by -I<$entryPath>, returns its size in a two element list of the form -{I<width height>}; returns an error if the indicator display item -does not exist. - -=back - -=item I<$hlist>-E<gt>B<info>(I<option>, I<arg, ...>) - -Query information about the HList widget. I<option> can be one -of the following: - -=over 8 - -=item I<$hlist>-E<gt>B<info>(B<anchor>) - -Returns the entryPath of the current anchor, if any, of the HList -widget. If the anchor is not set, returns the empty string. - -=item I<$hlist>-E<gt>B<infoBbox>(I<$entryPath>) - -Returns a list of four numbers describing the visible bounding box of -the entry given I<$entryPath>. The first two elements of the list -give the x and y coordinates of the upper-left corner of the screen -area covered by the entry (specified in pixels relative to the widget) -and the last two elements give the lower-right corner of the area, in -pixels. If no part of the entry given by index is visible on the -screen then the result is an empty string; if the entry is partially -visible, the result gives the only the visible area of the entry. - -=item I<$hlist>-E<gt>B<info>(B<children> ?,I<$entryPath>?) - -If I<$entryPath> is given, returns a list of the entryPath's of its -children entries. Otherwise returns a list of the toplevel -entryPath's. - -=item I<$hlist>-E<gt>B<info>(B<data> ?,I<$entryPath>?) - -Returns the data associated with I<$entryPath>. - -=item I<$hlist>-E<gt>B<info>(B<dragsite>) - -Returns the entryPath of the current dragsite, if any, of the HList -widget. If the dragsite is not set, returns the empty string. - -=item I<$hlist>-E<gt>B<info>(B<dropsite>) - -Returns the entryPath of the current dropsite, if any, of the HList -widget. If the dropsite is not set, returns the empty string. - -=item I<$hlist>-E<gt>B<info>(B<exists>, I<$entryPath>) - -Returns a boolean value indicating whether the list entry -I<$entryPath> exists. - -=item I<$hlist>-E<gt>B<info>(B<hidden>, I<$entryPath>) - -Returns a boolean value indicating whether the list entry -B<$entryPath> is hidden or not. - -=item I<$hlist>-E<gt>B<info>(B<next>, I<$entryPath>) - -Returns the entryPath of the list entry, if any, immediately below -this list entry. If this entry is already at the bottom of the HList -widget, returns an empty string. - -=item I<$hlist>-E<gt>B<info>(B<parent>, I<$entryPath>) - -Returns the name of the parent of the list entry identified by -I<$entryPath>. If I<entryPath> is a toplevel list entry, -returns the empty string. - -=item I<$hlist>-E<gt>B<info>(B<prev>, I<$entryPath>) - -Returns the entryPath of the list entry, if any, immediately above -this list entry. If this entry is already at the top of the HList -widget, returns an empty string. - -=item I<$hlist>-E<gt>B<info>(B<selection>) - -Returns a list of selected entries in the HList widget. In scalar -context, returns an anonymous list of the selected entries. -If no entries are selected, undef is returned in scalar context, and -an empty list otherwise. - -=back - -=item I<$hlist>-E<gt>B<item>(I<option, >?I<args, ...>?) - -Creates and configures the display items at individual columns the -entries. The form of additional of arguments depends on the choice of -I<option>: - -=over 8 - -=item I<$hlist>-E<gt>B<itemCget>(I<$entryPath>, I<$col>, I<option>) - -Returns the current value of the configure I<option> of the display -item at the column designated by I<$col> of the entry specified by -I<$entryPath>. - -=item I<$hlist>-E<gt>B<itemConfigure>(I<$entryPath>, I<$col> ?,I<option>?, I<?value, option, value, ...>?) - -Query or modify the configuration options of the display item at the -column designated by I<$col> of the entry specified by -I<$entryPath>. If no I<option> is specified, returns a list -describing all of the available options for I<$entryPath> (see -L<Tk::options> for information on the format of this -list). If I<option> is specified with no I<value>, then the -method returns a list describing the one named option (this list will -be identical to the corresponding sublist of the value returned if no -I<option> is specified). If one or more I<option-value> pairs -are specified, then the method modifies the given option(s) to have -the given value(s); in this case the method returns an empty string. -I<Option> may have any of the values accepted by the B<item> -create method. The exact set of options depends on the -value of the B<-itemtype> option passed to the the B<item> -create method when this display item was created. - -=item I<$hlist>-E<gt>B<itemCreate>(I<$entryPath>, I<$col> ?,I<-itemtype>=E<gt>I<type>? ?,I<option value ...>?) - -Creates a new display item at the column designated by I<$col> of -the entry specified by I<$entryPath>. An optional parameter -I<-itemtype> can be used to specify what type of display items -should be created. If the I<-itemtype> is not specified, then by -default the type specified by this HList widget's B<-itemtype> -option is used. Additional parameters, in I<option-value> pairs, -can be passed to configure the appearance of the display item. Each -I<option- value> pair must be a valid option for this type of -display item. - -=item I<$hlist>-E<gt>B<itemDelete>(I<$entryPath>, I<$col>) - -Deletes the display item at the column designated by I<$col> of -the entry specified by I<$entryPath>. - -=item I<$hlist>-E<gt>B<itemExists>(I<$entryPath>, I<$col>) - -Returns true if there is a display item at the column designated by -I<$col> of the entry specified by I<$entryPath>; returns false -otherwise. - -=back - -=item I<$hlist>-E<gt>B<nearest>(I<y>) - -I<$hlist>-E<gt>B<nearest>(I<y>) -Given a y-coordinate within the HList window, this method returns -the entryPath of the (visible) HList element nearest to that -y-coordinate. - -=item I<$hlist>-E<gt>B<see>(I<$entryPath>) - -Adjust the view in the HList so that the entry given by I<$entryPath> is -visible. If the entry is already visible then the method has no -effect; if the entry is near one edge of the window then the HList -scrolls to bring the element into view at the edge; otherwise the -HList widget scrolls to center the entry. - -=item I<$hlist>-E<gt>B<selection>(I<option>, I<arg>, ...) - -=item I<$hlist>-E<gt>B<selection>I<Option>(I<arg>, ...) - -This method is used to adjust the selection within a HList widget. It -has several forms, depending on I<option>: - -=over 8 - -=item I<$hlist>-E<gt>B<selectionClear>(?I<from>?, ?I<to>?) - -When no extra arguments are given, deselects all of the list entrie(s) -in this HList widget. When only I<from> is given, only the list -entry identified by I<from> is deselected. When both I<from> and -I<to> are given, deselects all of the list entrie(s) between -between I<from> and I<to>, inclusive, without affecting the -selection state of elements outside that range. - -=item I<$hlist>-E<gt>B<selectionGet> - -This is an alias for the B<infoSelection> method. - -=item I<$hlist>-E<gt>B<selectionIncludes>(I<$entryPath>) - -Returns 1 if the list entry indicated by I<$entryPath> is currently -selected; returns 0 otherwise. - -=item I<$hlist>-E<gt>B<selectionSet>(I<from>?, I<to>?) - -Selects all of the list entrie(s) between between I<from> and -I<to>, inclusive, without affecting the selection state of entries -outside that range. When only I<from> is given, only the list entry -identified by I<from> is selected. - -=back - -=item I<$hlist>-E<gt>B<show>(I<option> ?,I<$entryPath>?) - -Show the entries that are hidden by the B<hide> method, -I<option> can be one of the following: - -=over 8 - -=item B<entry> - -Shows the list entry identified by I<$entryPath>. - -=back - -Currently only the B<entry> option is supported. Other options will -be added in future releases. - -=item I<$hlist>-E<gt>B<xview>(I<args>) - -This method is used to query and change the horizontal position of the -information in the widget's window. It can take any of the following -forms: - -=over 8 - -=item I<$hlist>-E<gt>B<xview> - -Returns a list containing two elements. Each element is a real -fraction between 0 and 1; together they describe the horizontal span -that is visible in the window. For example, if the first element is -.2 and the second element is .6, 20% of the HList entry is -off-screen to the left, the middle 40% is visible in the window, and -40% of the entry is off-screen to the right. These are the same values -passed to scrollbars via the B<-xscrollcommand> option. - -=item I<$hlist>-E<gt>B<xview>(I<$entryPath>) - -Adjusts the view in the window so that the list entry identified by -I<$entryPath> is aligned to the left edge of the window. - -=item I<$hlist>-E<gt>B<xview>(B<moveto> =E<gt> I<fraction>) - -Adjusts the view in the window so that I<fraction> of the total -width of the HList is off-screen to the left. I<fraction> must be -a fraction between 0 and 1. - -=item I<$hlist>-E<gt>B<xview>(B<scroll> =E<gt> I<number, what>) - -This method shifts the view in the window left or right according to -I<number> and I<what>. I<Number> must be an integer. -I<What> must be either B<units> or B<pages> or an -abbreviation of one of these. If I<what> is B<units>, the view -adjusts left or right by I<number> character units (the width of -the B<0> character) on the display; if it is B<pages> then the -view adjusts by I<number> screenfuls. If I<number> is negative -then characters farther to the left become visible; if it is positive -then characters farther to the right become visible. - -=back - -=item I<$hlist>-E<gt>B<yview>(I<?args>?) - -This method is used to query and change the vertical position of the -entries in the widget's window. It can take any of the following forms: - -=over 8 - -=item I<$hlist>-E<gt>B<yview> - -Returns a list containing two elements, both of which are real -fractions between 0 and 1. The first element gives the position of -the list element at the top of the window, relative to the HList as a -whole (0.5 means it is halfway through the HList, for example). The -second element gives the position of the list entry just after the -last one in the window, relative to the HList as a whole. These are -the same values passed to scrollbars via the B<-yscrollcommand> -option. - -=item I<$hlist>-E<gt>B<yview>(I<$entryPath>) - -Adjusts the view in the window so that the list entry given by -I<$entryPath> is displayed at the top of the window. - -=item I<$hlist>-E<gt>B<yview>(B<moveto> =E<gt> I<fraction>) - -Adjusts the view in the window so that the list entry given by -I<fraction> appears at the top of the window. I<Fraction> is a -fraction between 0 and 1; 0 indicates the first entry in the -HList, 0.33 indicates the entry one-third the way through the -HList, and so on. - -=item I<$hlist>-E<gt>B<yview>(B<scroll> =E<gt> I<number, what>) - -This method adjust the view in the window up or down according to -I<number> and I<what>. I<Number> must be an integer. -I<What> must be either B<units> or B<pages>. If I<what> -is B<units>, the view adjusts up or down by I<number> lines; if -it is B<pages> then the view adjusts by I<number> screenfuls. -If I<number> is negative then earlier entries become visible; if -it is positive then later entries become visible. - -=back - -=back - -=head1 BINDINGS - -=over 4 - -=item [1] - -If the B<-selectmode> is "browse", when the user drags the mouse -pointer over the list entries, the entry under the pointer will be -highlighted and the B<-browsecmd> callback will be called with -one parameter, the entryPath of the highlighted entry. Only one entry -can be highlighted at a time. The B<-command> callback will be -called when the user double-clicks on a list entry. - -=item [2] - -If the B<-selectmode> is "single", the entries will only be -highlighted by mouse E<lt>ButtonRelease-1E<gt> events. When a new list entry -is highlighted, the B<-browsecmd> callback will be called with -one parameter indicating the highlighted list entry. The -B<-command> callback will be called when the user double-clicks -on a list entry. - -=item [3] - -If the B<-selectmode> is "multiple", when the user drags the mouse -pointer over the list entries, all the entries under the pointer will -be highlighted. However, only a contiguous region of list entries can -be selected. When the highlighted area is changed, the -B<-browsecmd> callback will be called with an undefined -parameter. It is the responsibility of the B<-browsecmd> callback -to find out the exact highlighted selection in the HList. The -B<-command> callback will be called when the user double-clicks -on a list entry. - -=item [4] - -If the B<-selectmode> is "extended", when the user drags the mouse -pointer over the list entries, all the entries under the pointer will -be highlighted. The user can also make disjointed selections using -E<lt>Control-ButtonPress-1E<gt>. When the highlighted area is changed, the -B<-browsecmd> callback will be called with an undefined -parameter. It is the responsibility of the B<-browsecmd> callback -to find out the exact highlighted selection in the HList. The -B<-command> callback will be called when the user double-clicks -on a list entry. - -=item [5] - -B<Arrow key bindings:> E<lt>UpE<gt> arrow key moves the anchor point to the -item right on top of the current anchor item. E<lt>DownE<gt> arrow key moves -the anchor point to the item right below the current anchor item. -E<lt>LeftE<gt> arrow key moves the anchor to the parent item of the current -anchor item. E<lt>RightE<gt> moves the anchor to the first child of the -current anchor item. If the current anchor item does not have any -children, moves the anchor to the item right below the current anchor -item. - -=back - -=head1 EXAMPLE - -This example demonstrates how to use an HList to store a file -directory structure and respond to the user's browse events: - - use strict; - use Tk; - use Tk::Label; - use Tk::HList; - - my $mw = MainWindow->new(); - my $label = $mw->Label(-width=>15); - my $hlist = $mw->HList( - -itemtype => 'text', - -separator => '/', - -selectmode => 'single', - -browsecmd => sub { - my $file = shift; - $label->configure(-text=>$file); - } - ); - - foreach ( qw(/ /home /home/ioi /home/foo /usr /usr/lib) ) { - $hlist->add($_, -text=>$_); - } - - $hlist->pack; - $label->pack; - - MainLoop; - -=head1 BUGS - -The fact that the display item at column 0 is implicitly associated -with the whole entry is probably a design bug. This was done for -backward compatibility purposes. The result is that there is a large -overlap between the B<item> method and the B<add>, -B<addchild>, B<entrycget> and B<entryconfigure> -methods. Whenever multiple columns exist, the programmer should use -ONLY the B<item> method to create and configure the display items -in each column; the B<add>, B<addchild>, B<entrycget> and -B<entryconfigure> should be used ONLY to create and configure -entries. - -=head1 KEYWORDS - -Hierarchical Listbox - -=head1 SEE ALSO - -L<Tk::DItem|Tk::DItem> - -=cut - - diff --git a/Master/tlpkg/tlperl/lib/Tk/IO.pod b/Master/tlpkg/tlperl/lib/Tk/IO.pod deleted file mode 100644 index 2781d2e17e6..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/IO.pod +++ /dev/null @@ -1,51 +0,0 @@ - -=head1 NAME - -Tk::IO - high level interface to Tk's 'fileevent' mechanism - -=for pm IO/IO.pm - -=for category Binding Events and Callbacks - -=head1 SYNOPSIS - - my $fh = Tk::IO->new(-linecommand => callback, -childcommand => callback); - $fh->exec("command") - $fh->wait - $fh->kill - -=head1 WARNING - -INTERFACES TO THIS MODULE MAY CHANGE AS PERL'S IO EVOLVES -AND WITH PORT OF TK4.1 - -=head1 DESCRIPTION - -Tk::IO is now layered on perl's IO::Handle class. Interfaces -have changed, and are still evolving. - -In theory C methods which enable non-blocking IO as in earlier Tk-b* -release(s) are still there. I have not changed them to use perl's -additional Configure information, or tested them much. - -Assumption is that B<exec> is -used to fork a child process and a callback is called each time a -complete line arrives up the implied pipe. - -"line" should probably be defined in terms of perl's input record -separator but is not yet. - -The -childcommand callback is called when end-of-file occurs. - -$fh->B<wait> can be used to wait for child process while processing -other Tk events. - -$fh->B<kill> can be used to send signal to child process. - -=head1 BUGS - -Still not finished. -Idea is to use "exec" to emulate "system" in a non-blocking manner. - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/IconList.pod b/Master/tlpkg/tlperl/lib/Tk/IconList.pod deleted file mode 100644 index e68324ce4b6..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/IconList.pod +++ /dev/null @@ -1,82 +0,0 @@ -=head1 NAME - -Tk::IconList - an icon list widget - -=for pm Tk/IconList.pm - -=for category Derived Widgets - -=head1 SYNOPSIS - - use Tk::IconList; - $il = $mw->IconList(-browsecmd => sub { ... }, - -command => sub { ... })->pack; - $il->Add($icon1, $text1); - $il->Add($icon2, $text2); - $il->Arrange; - ... - $il->DeleteAll; - -=head1 DESCRIPTION - -=head2 OPTIONS - -=over - -=item -browsecmd - -=item -command - -=item -font - --item -foreground|-fg - -=back - -=head2 METHODS - -=over 4 - -=item DeleteAll - -Deletes all the items inside the canvas subwidget and reset the IconList's -state. - -=item Add($image, $text) - -Adds an icon into the IconList with the designated image and text. - -=item Arrange - -Places the icons in a column-major arrangement. - -=item Get - -Return the selected item. - -=item Invoke - -Gets called when the user invokes the IconList (usually by double-clicking -or pressing the Return key) (internal method). - -=item See($tag) - -If the item is not (completely) visible, scroll the canvas so that it -becomes visible (internal method). - -=back - -=head1 COPYRIGHT - -The original tkfbox.tcl from Tcl/Tk is: - -Copyright (c) 1994-1996 Sun Microsystems, Inc. - -See the file "license.terms" for information on usage and redistribution -of this file, and for a DISCLAIMER OF ALL WARRANTIES. - -Translated to Perl/Tk by Slaven Rezic <srezic@cpan.org>. - -=head1 SEE ALSO - -L<Tk::FBox>. diff --git a/Master/tlpkg/tlperl/lib/Tk/Image.pod b/Master/tlpkg/tlperl/lib/Tk/Image.pod deleted file mode 100644 index 797ecc23cbf..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Image.pod +++ /dev/null @@ -1,145 +0,0 @@ -# Copyright (c) 1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::Image - Create and manipulate images - -=for category Tk Image Classes - -=head1 SYNOPSIS - -I<$image> = I<$widget>-E<gt>I<type>(?I<arg arg ...>?) - -I<$image>-E<gt>I<method>(?I<arg arg ...>?) - -=head1 DESCRIPTION - -The B<image> constructors and methods are used to create, delete, and query images. -It can take several different forms, depending on the -I<type>. - -The constructors require a I<$widget> to invoke them, this is used -to locate a B<MainWindow>. (This is because the underlying Tk code -registers the images in the data structure for the B<MainWindow>.) - -The legal forms are: - -=over 4 - -=item I<$widget>-E<gt>I<type>?(?I<name>?,?I<option>=E<gt>I<value ...>)? - -Creates a new image and returns an object. -I<type> specifies the type of the image, which must be one of -the types currently defined (e.g., B<Bitmap>). -I<name> specifies the name for the image; if it is omitted then -Tk picks a name of the form B<image>I<x>, where I<x> is -an integer. -There may be any number of I<option>=E<gt>I<value> pairs, -which provide configuration options for the new image. -The legal set of options is defined separately for each image -type; see below for details on the options for built-in image types. -If an image already exists by the given name then it is replaced -with the new image and any instances of that image will redisplay -with the new contents. - -=item I<$image>-E<gt>B<delete> - -Deletes the image I<$image> and returns an empty string. -If there are instances of the image displayed in widgets, -the image won't actually be deleted until all of the instances -are released. -However, the association between the instances and the image -manager will be dropped. -Existing instances will retain their sizes but redisplay as -empty areas. -If a deleted image is recreated (with the same I<name>) -the existing instances will use the new image. - -=item I<$image>-E<gt>B<height> - -Returns a decimal string giving the height of image I<name> -in pixels. - -=item I<$image>-E<gt>B<inuse> - -Returns a boolean value indicating whether or not the image is in use -by any widgets. - -=item I<$widget>-E<gt>B<imageNames> - -Returns a list containing all existing images for I<$widget>'s -B<MainWindow>. - -=item I<$image>-E<gt>B<type> - -Returns the type of I<$image> (the value of the I<type> -method when the image was created). - -=item I<$widget>-E<gt>B<imageTypes> - -Returns a list whose elements are all of the valid image types -(i.e., all of the values that may be supplied for the I<type> -to create an image). - -=item I<$image>-E<gt>B<width> - -Returns a decimal string giving the width of image I<name> -in pixels. - -=back - -=head1 BUILT-IN IMAGE TYPES - -The following image types are defined by Tk so they will be available -in any Tk application. -Individual applications or extensions may define additional types. - -=over 4 - -=item B<Bitmap> - -Each pixel in the image displays a foreground color, a background -color, or nothing. -See L<Tk::Bitmap> for more information. - -=item B<Pixmap> - -B<Pixmap> is slightly more general than B<Bitmap>, each pixel can -be any available color or "transparent" (rendered as background color of the -widget image is displayed in). B<Pixmap> is best used for icons and other -simple graphics with only a few colors. - -B<Pixmap> is derived from Tix. See L<Tk::Pixmap> for more information. - -=item B<Photo> - -Displays a variety of full-color images, using dithering to -approximate colors on displays with limited color capabilities. -See L<Tk::Photo> documentation for more information. - -=back - -=head1 CAVEATS - -It's necessary to use the L</delete> method to delete an image object -and free memory associated with it. Just using a lexical variable for -storing the image object and letting the variable to go out of scope -or setting to C<undef> is not sufficient. - -=head1 SEE ALSO - -L<Tk::Bitmap|Tk::Bitmap> -L<Tk::Pixmap|Tk::Pixmap> -L<Tk::Photo|Tk::Photo> - -=head1 KEYWORDS - -height, image, types of images, width - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/InputO.pod b/Master/tlpkg/tlperl/lib/Tk/InputO.pod deleted file mode 100644 index 03a43b29ed7..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/InputO.pod +++ /dev/null @@ -1,50 +0,0 @@ -=head1 NAME - -Tk::InputO - Create and manipulate TIX InputO widgets - -=for category Tix Extensions - -=head1 SYNOPSIS - -I<$inputonly> = I<$parent>-E<gt>B<InputO>(?I<options>?); - -=head1 STANDARD OPTIONS - -Only the following three standard options are supported by -B<InputO>: - -B<cursor> B<width> B<height> - -See L<Tk::options> for details of the standard options. - -=head1 WIDGET-SPECIFIC OPTIONS - -B<InputO> does not have any widget specific options. - -=head1 DESCRIPTION - -The B<InputO> method creates a new window (given by the -$widget argument) and makes it into a B<InputO> -widget. Additional options, described above, may be specified on the -command line or in the option database to configure aspects of the -B<InputO> such as its cursor or width. - -B<InputO> widgets are not visible to the user. The only -purpose of B<InputO> widgets are to accept inputs from the -user, which can be done with the B<bind> method. - -=head1 WIDGET METHODS - -The B<InputO> method creates a widget object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. -The widget also inherits all the methods provided by the generic -L<Tk::Widget|Tk::Widget> class. - -=head1 BINDINGS - -B<InputO> widgets have no default bindings. - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Internals.pod b/Master/tlpkg/tlperl/lib/Tk/Internals.pod deleted file mode 100644 index 4ee1e0126ca..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Internals.pod +++ /dev/null @@ -1,142 +0,0 @@ -=head1 NAME - -CallingTk - what is Perl Tk interface doing when you call Tk functions. - -=for category C Programming - -This information is worse than useless for C<perlTk> users, but can of -some help for people interested in using modified Tk source with -C<perlTk>. - -I<This document is under construction. The information is believed to -be pertinent to the version of> C<portableTk> I<available when it was -created. All the details are subject to change.> - -=head1 DESCRIPTION - -=over 4 - -=item PreCompiling - -Before the actual compilation stage a script scans the source -and extracts the subcommands of different commands. This information -resides in the file C<pTk/Methods.def>. - -=item Compilation - -During compilation the above file is included in the source of booting -routine of dynamic (or static) library. More precisely, the booting -code of module C<Tk> calls the subroutine Boot_Glue() from the module -C<tkGlue.c>, and this subroutine includes the file (with appropriate -macro definitions). - -=item Inside C<use Tk;> - -The module bootstraps the C code, then loads the Perl libraries. The -heart of the Perl code is contained in the C<Tk::Widget> library, all the -widgets inherit from this module. Code for toplevels is loaded from -C<Tk::MainWindow>. - -During bootstrap of the C glue code the C<Xevent::?> codes and a -handful of C<Tk::Widget> and C<Tk::Image> routines are defined. (Much -more XSUBs are created from C<Tk.xs> code.) The widget subcommands are -glued to Perl basing on the list included from C<pTk/Methods.def>. In -fact all the subcommands are glued to XSUBs that are related to the -same C subroutine XStoWidget(), but have different data parts. - -During the Perl code bootstrap the method C<Tk::Widget::import> is -called. This call requires all the code from particular widget -packages. - -Code from the widget packages calls an obscure command like - - (bless \"Text")->WidgetClass; - -This command (actually Tk::Widget::WidgetClass()) creates three -routines: Tk::Widget::Text(), Tk::Widget::isText(), and -Tk::Text::isText(). The first one is basically C<new> of C<Tk::Text>, -the other two return constants. It also puts the class into -depository. - -=item Inside C<$top = MainWindow-E<gt>new;> - -This is quite intuitive. This call goes direct to -C<Tk::MainWindow::new>, that calls XSUB -C<Tk::MainWindow::CreateMainWindow>, that calls C subroutine -Tk_CreateMainWindow(). It is a C<Tk> subroutine, so here black magic -ends (almost). - -The only remaining black magic is that the C<Tk> initialization -routine creates a lot of commands, but the subroutine for creation is -usurped by B<portableTk> and the commands are created in the package -C<Tk>. They are associated to XSUBs that are related to one of three C -subroutines XStoSubCmd(), XStoBind(), or XStoTk(), but have different -data parts. - -The result of the call is blessed into C<Tk::MainWindow>, as it should. - -=item Inside C<$top-E<gt>title('Text demo');> - -The package C<Tk::Toplevel> defines a lot of subroutines on the fly on -some list. All the commands from the list are converted to the -corresponding subcommands of C<wm> method of the widget. Here -subcommand is a command with some particular second argument (in this -case C<"title">). Recall that the first argument is $self. - -Now C<Tk::Toplevel> @ISA C<Tk::Widget>, that in turn @ISA C<Tk>. So a -call to C<$top-E<gt>wm('title','Text demo')> calls C<Tk::wm>, that is -defined during call to Tk_CreateMainWindow(). As it is described -above, the XSUB associated to XStoSubCmd() is called. - -This C routine is defined in C<tkGlue.c>. It gets the data part of -XSUB, creates a C<SV> with the name of the command, and calls -Call_Tk() with the XSUB data as the first argument, and with the name -of XSUB stuffed into the Perl stack in the place there C<tk> expects -it. (In fact it can also reorder the arguments if it thinks it is -what you want). - -The latter procedure extracts name of C<tk> procedure and -C<clientData> from the first argument and makes a call, using Perl -stack as C<argv> for the procedure. A lot of black magic is performed -afterwards to convert result of the procedure to a Perl array return. - -=item Inside C<$text = $top-E<gt>Text(background =E<gt> $txtBg);> - -Above we discussed how the command C<Tk::Widget::Text> is created. The -above command calls it via inheritance. It is translated to - - Tk::Text::new($top, background => $txtBg); - -The package C<Tk::Text> has no method C<new>, so the -C<Tk::Widget::new> is called. In turn it calls -C<Tk::Text-E<gt>DoInit($top)>, that is -C<Tk::Widget::DoInit(Tk::Text,$top)>, that initializes the bindings if -necessary. Then it creates the name for the widget of the form -C<.text0>, and calls C<Tk::text('.text0', background =E<gt> $txtBg)> -(note lowercase). The result of the call is blessed into C<Tk::Text>, -and the method C<bindtags> for this object is called. - -Now the only thing to discuss is who defines the methods C<text> and -C<bindtags>. The answer is that they are defined in C<tkWindow.c>, -and these commands are created in the package C<Tk> in the same sweep -that created the command C<Tk::wm> discussed above. - -So the the same C code that corresponds to the processing of -corresponding TCL commands is called here as well (this time via -C<XStoTk> interface). - -=item Inside C<$text-E<gt>insert('insert','Hello, world!');> - -As we discussed above, the subcommands of widget procedures correspond -to XSUB C<XStoWidget>. This XSUB substitutes the first argument $text -(that is a hash reference) to an appropriate value from this hash, -adds the additional argument after the first one that contains the -name of the subcommand extracted from the data part of XSUB, and calls -the corresponding Tk C subroutine via C<Call_Tk>. - -=back - -Ilya Zakharevich <ilya@math.ohio-state.edu> - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/LabFrame.pod b/Master/tlpkg/tlperl/lib/Tk/LabFrame.pod deleted file mode 100644 index cf5cebf754a..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/LabFrame.pod +++ /dev/null @@ -1,110 +0,0 @@ -=head1 NAME - -Tk::LabFrame - labeled frame. - -=for pm Tixish/LabFrame.pm - -=for category Tix Extensions - -=head1 SYNOPSIS - -S< >B<use Tk::LabFrame;> - -S< >I<$f> = I<$parent>-E<gt>B<LabFrame>(?B<-label>=E<gt>I<text>, -B<-labelside>=E<gt>I<where>, ...?); - -=head1 DESCRIPTION - -B<LabFrame> is exactly like B<Frame> and additionaly allows to -add a label to the frame. - -=head1 WIDGET-OPTIONS - -B<LabFrame> supports the same options as the -L<Frame|Tk::Frame/"STANDARD OPTIONS"> widget. - -Additional options of B<LabFrame> are: - -=over 4 - -=item B<-font> =E<gt> I<font> - -Specifies the label's font - -=item B<-foreground> =E<gt> I<color> - -Specifies the label's foreground color - -=item B<-label> =E<gt> I<text> - -The text of the label to be placed with the Frame. - -=item B<-labelside> =E<gt> I<where> - -I<Where> can be one of B<left>, B<right>, B<top>, B<bottom> or B<acrosstop>. -The first four work as might be expected and place the label to the -left, right, above or below the frame respectively. The B<acrosstop> -creates a grooved frame around the central frame and puts the label -near the northwest corner such that it appears to "overwrite" the -groove. - -=item B<-labelvariable> =E<gt> I<scalar_ref> - -Specifies a reference to a variable and used as an -alternative to -label. If the value of the variable changes, -then the widget will be updated automatically to reflect the -change. Used like -textvariable. - -=back - -=head1 ADVERTISED SUBWIDGETS - -See L<Tk::mega/"Subwidget"> how to use advertised widgets. - -=over 4 - -=item I<border> - - Frame used to display the border - -=item I<frame> - - Frame used to create new LabFrame children. - -=item I<label> - - Label used for displaying text - -=back - -=head1 EXAMPLE - -Run the following test program to see this in action: - - use strict; - use Tk; - require Tk::LabFrame; - require Tk::LabEntry; - - my $test = 'Test this'; - my $mw = Tk::MainWindow->new; - my $f = $mw->LabFrame(-label => "This is a label", - -labelside => "acrosstop"); - $f->LabEntry(-label => "Testing", -textvariable => \$test)->pack; - $f->pack; - Tk::MainLoop; - -=head1 BUGS - -Perhaps B<LabFrame> should be subsumed within the generic pTk -labeled widget mechanism. - -=head1 AUTHOR - -B<Rajappa Iyer> rsi@earthling.net - -This code is derived from LabFrame.tcl and LabWidg.tcl in the Tix4.0 -distribution by Ioi Lam. The code may be redistributed under the same -terms as Perl. - -=cut diff --git a/Master/tlpkg/tlperl/lib/Tk/Label.pod b/Master/tlpkg/tlperl/lib/Tk/Label.pod deleted file mode 100644 index 96386b09b5c..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Label.pod +++ /dev/null @@ -1,133 +0,0 @@ -# Copyright (c) 1990-1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::Label - Create and manipulate Label widgets - -=for category Tk Widget Classes - -=head1 SYNOPSIS - -I<$label> = I<$parent>-E<gt>B<Label>(?I<options>?); - -=head1 STANDARD OPTIONS - -B<-activebackground> -B<-activeforeground> -B<-anchor> -B<-background> -B<-bitmap> -B<-borderwidth> -B<-compound> -B<-cursor> -B<-disabledforeground> -B<-font> -B<-foreground> -B<-highlightbackground> -B<-highlightcolor> -B<-highlightthickness> -B<-image> -B<-justify> -B<-padx> -B<-pady> -B<-relief> -B<-takefocus> -B<-text> -B<-textvariable> -B<-underline> -B<-wraplength> - -See L<Tk::options> for details of the standard options. - -=head1 WIDGET-SPECIFIC OPTIONS - -=over 4 - -=item Name: B<height> - -=item Class: B<Height> - -=item Switch: B<-height> - -Specifies a desired height for the label. -If an image or bitmap is being displayed in the label then the value is in -screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>); -for text it is in lines of text. -If this option isn't specified, the label's desired height is computed -from the size of the image or bitmap or text being displayed in it. - -=item Name: B<state> - -=item Class: B<State> - -=item Switch: B<-state> - -Specifies one of three states for the label: B<normal>, B<active>, or -B<disabled>. In normal state the label is displayed using the -B<foreground> and B<background> options. In active state the label is -displayed using the B<activeForeground> and B<activeBackground> -options. In the disabled state the B<disabledForeground> and -B<background> options determine how the button is displayed. - -=item Name: B<width> - -=item Class: B<Width> - -=item Switch: B<-width> - -Specifies a desired width for the label. -If an image or bitmap is being displayed in the label then the value is in -screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>); -for text it is in characters. -If this option isn't specified, the label's desired width is computed -from the size of the image or bitmap or text being displayed in it. - -=back - -=head1 DESCRIPTION - -The B<Label> method creates a new window (given by the -$widget argument) and makes it into a label widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the label such as its colors, font, -text, and initial relief. The B<label> command returns its -$widget argument. At the time this command is invoked, -there must not exist a window named $widget, but -$widget's parent must exist. - -A label is a widget that displays a textual string, bitmap or image. -If text is displayed, it must all be in a single font, but it -can occupy multiple lines on the screen (if it contains newlines -or if wrapping occurs because of the B<wrapLength> option) and -one of the characters may optionally be underlined using the -B<underline> option. -The label can be manipulated in a few simple ways, such as -changing its relief or text, using the commands described below. - -=head1 WIDGET METHODS - -The B<Label> method creates a widget object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. -The widget also inherits all the methods provided by the generic -L<Tk::Widget|Tk::Widget> class. - -=head1 BINDINGS - -When a new label is created, it has no default event bindings: -labels are not intended to be interactive. - -=head1 KEYWORDS - -label, widget - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Labelframe.pod b/Master/tlpkg/tlperl/lib/Tk/Labelframe.pod deleted file mode 100644 index b904ad7775b..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Labelframe.pod +++ /dev/null @@ -1,206 +0,0 @@ -# Copyright (c) 1990-1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# RCS: @(#) $Id: labelframe.n,v 1.1 2001/09/26 21:36:19 pspjuth Exp $ - -=head1 NAME - -Tk::Labelframe - Create and manipulate Labelframe widgets - -=for category Tk Generic Methods - -=head1 SYNOPSIS - -I<$labelframe> = I<$parent>-E<gt>B<Labelframe>(?I<options>?); - - -borderwidth -highlightbackground -pady - -cursor -highlightcolor -relief - -font -highlightthickness -takefocus - -foreground -padx -text - -=head1 WIDGET-SPECIFIC OPTIONS - -=over 4 - -=item Option: B<-background> - -=item Name: B<background> - -=item Class: B<Background> - -This option is the same as the standard B<background> option -except that its value may also be specified as an empty string. -In this case, the widget will display no background or border, and -no colors will be consumed from its colormap for its background -and border. - -=item Option: B<-class> - -=item Name: B<class> - -=item Class: B<Class> - -Specifies a class for the window. -This class will be used when querying the option database for -the window's other options, and it will also be used later for -other purposes such as bindings. -The B<class> option may not be changed with the B<configure> -method. - -=item Option: B<-colormap> - -=item Name: B<colormap> - -=item Class: B<Colormap> - -Specifies a colormap to use for the window. -The value may be either B<new>, in which case a new colormap is -created for the window and its children, or the name of another -window (which must be on the same screen and have the same visual -as $widget), in which case the new window will use the colormap -from the specified window. -If the B<colormap> option is not specified, the new window -uses the same colormap as its parent. -This option may not be changed with the B<configure> -method. - -=item Option: B<-container> - -=item Name: B<container> - -=item Class: B<Container> - -The value must be a boolean. If true, it means that this window will -be used as a container in which some other application will be embedded -(for example, a Tk toplevel can be embedded using the B<-use> option). -The window will support the appropriate window manager protocols for -things like geometry requests. The window should not have any -children of its own in this application. -This option may not be changed with the B<configure> -method. - -=item Option: B<-height> - -=item Name: B<height> - -=item Class: B<Height> - -Specifies the desired height for the window in any of the forms -acceptable to B<Tk_GetPixels>. -If this option is less than or equal to zero then the window will -not request any size at all. - -=item Option: B<-labelanchor> - -=item Name: B<labelAnchor> - -=item Class: B<LabelAnchor> - -Specifies where to place the label. A label is only displayed if the -B<-text> option is not the empty string. -Valid values for this option are (listing them clockwise) -B<nw>, B<n>, B<ne>, B<en>, B<e>, B<es>, -B<se>, B<s>,B<sw>, B<ws>, B<w> and B<wn>. -The default value is B<nw>. - -=item Option: B<-labelwidget> - -=item Name: B<labelWidget> - -=item Class: B<LabelWidget> - -Specifies a widget to use as label. This overrides any B<-text> -option. The widget must exist before being used as B<-labelwidget> -and if it is not a descendant of this window, it will be raised -above it in the stacking order. - -=item Option: B<-visual> - -=item Name: B<visual> - -=item Class: B<Visual> - -Specifies visual information for the new window in any of the -forms accepted by B<Tk_GetVisual>. -If this option is not specified, the new window will use the same -visual as its parent. -The B<visual> option may not be modified with the B<configure> -method. - -=item Option: B<-width> - -=item Name: B<width> - -=item Class: B<Width> - -Specifies the desired width for the window in any of the forms -acceptable to B<Tk_GetPixels>. -If this option is less than or equal to zero then the window will -not request any size at all. - -=back - -=head1 DESCRIPTION - -The B<Labelframe> method creates a new window (given by the -$labelframe argument) and makes it into a Labelframe widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the Labelframe such as its background color -and relief. - -A Labelframe is a simple widget. Its primary purpose is to act as a -spacer or container for complex window layouts. It has the features -of a B<Frame> plus the ability to display a label. - -=head1 WIDGET METHODS - -The B<Labelframe> method -may be used to invoke various operations on the widget. It has the -following general form: - - $widget->method(?arg arg ...?); - -The following -methods are possible for Labelframe widgets: - -=over 4 - -=item I<$widget>-E<gt>B<cget>(I<option>); - -Returns the current value of the configuration option given -by I<option>. -I<Option> may have any of the values accepted by the B<Labelframe> -command. - -=item I<$widget>-E<gt>B<configure>(?I<option>?, I<?value, option, value, ...>?); - -Query or modify the configuration options of the widget. -If no I<option> is specified, returns a list describing all of -the available options for $widget (see L<Tk::configure> for -information on the format of this list). If I<option> is specified -with no I<value>, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no I<option> is specified). If -one or more I<option-value> pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. -I<Option> may have any of the values accepted by the B<Labelframe> -command. - -=back - -=head1 BINDINGS - -When a new Labelframe is created, it has no default event bindings: -Labelframes are not intended to be interactive. - -=head1 SEE ALSO - -L<Tk::Frame>, L<Tk::Label> - -=head1 KEYWORDS - -Labelframe, widget diff --git a/Master/tlpkg/tlperl/lib/Tk/Listbox.pod b/Master/tlpkg/tlperl/lib/Tk/Listbox.pod deleted file mode 100644 index ba00afe3ed9..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Listbox.pod +++ /dev/null @@ -1,794 +0,0 @@ -# Copyright (c) 1990 The Regents of the University of California. -# Copyright (c) 1994-1997 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::Listbox - Create and manipulate Listbox widgets - -=for category Tk Widget Classes - -=head1 SYNOPSIS - -I<$listbox> = I<$parent>-E<gt>B<Listbox>(?I<options>?); - -=head1 STANDARD OPTIONS - -B<-background> B<-borderwidth> B<-cursor> B<-disabledforeground> -B<-exportselection> B<-font> B<-foreground> B<-height> -B<-highlightbackground> B<-highlightcolor> B<-highlightthickness> -B<-offset> B<-relief> B<-selectbackground> B<-selectborderwidth> -B<-selectforeground> B<-setgrid> B<-state> B<-takefocus> B<-tile> -B<-width> B<-xscrollcommand> B<-yscrollcommand> - - -See L<Tk::options> for details of the standard options. - -=head1 WIDGET-SPECIFIC OPTIONS - -=over 4 - -=item Name: B<activeStyle> - -=item Class: B<ActiveStyle> - -=item Switch: B<-activestyle> - -Specifies the style in which to draw the active element. This must be -one of B<dotbox> (show a focus ring around the active element), B<none> -(no special indication of active element) or B<underline> (underline the -active element). The default is B<underline>. - -=item Name: B<height> - -=item Class: B<Height> - -=item Switch: B<-height> - -Specifies the desired height for the window, in lines. -If zero or less, then the desired height for the window is made just -large enough to hold all the elements in the listbox. - -=item Name: B<listVariable> - -=item Class: B<Variable> - -=item Switch: B<-listvariable> - -I<The following is only partially implemented in Perl/Tk:> - -Specifies the reference of a variable. The value of the variable is an array -to be displayed inside the widget; if the variable value changes -then the widget will automatically update itself to reflect the new -value. Attempts to assign a variable with an invalid list value to -B<-listvariable> will cause an error. Attempts to unset a variable in use -as a B<-listvariable> will fail but will not generate an error. - -=item Name: B<selectMode> - -=item Class: B<SelectMode> - -=item Switch: B<-selectmode> - -Specifies one of several styles for manipulating the selection. -The value of the option may be arbitrary, but the default bindings -expect it to be either B<single>, B<browse>, B<multiple>, -or B<extended>; the default value is B<browse>. - -=item Name: B<state> - -=item Class: B<State> - -=item Switch: B<-state> - -Specifies one of two states for the listbox: B<normal> or B<disabled>. -If the listbox is disabled then items may not be inserted or deleted, -items are drawn in the B<-disabledforeground> color, and selection -cannot be modified and is not shown (though selection information is -retained). - -=item Name: B<width> - -=item Class: B<Width> - -=item Switch: B<-width> - -Specifies the desired width for the window in characters. -If the font doesn't have a uniform width then the width of the -character ``0'' is used in translating from character units to -screen units. -If zero or less, then the desired width for the window is made just -large enough to hold all the elements in the listbox. - -=back - -=head1 DESCRIPTION - -The B<Listbox> method creates a new window (given by the -$widget argument) and makes it into a listbox widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the listbox such as its colors, font, -text, and relief. The B<listbox> command returns its -$widget argument. At the time this command is invoked, -there must not exist a window named $widget, but -$widget's parent must exist. - -A listbox is a widget that displays a list of strings, one per line. -When first created, a new listbox has no elements. -Elements may be added or deleted using methods described -below. In addition, one or more elements may be selected as described -below. -If a listbox is exporting its selection (see B<exportSelection> -option), then it will observe the standard X11 protocols -for handling the selection. -Listbox selections are available as type B<STRING>; -the value of the selection will be the text of the selected elements, with -newlines separating the elements. - -It is not necessary for all the elements to be -displayed in the listbox window at once; commands described below -may be used to change the view in the window. Listboxes allow -scrolling in both directions using the standard B<xScrollCommand> -and B<yScrollCommand> options. -They also support scanning, as described below. - -=head1 INDICES - -Many of the methods for listboxes take one or more indices -as arguments. -An index specifies a particular element of the listbox, in any of -the following ways: - -=over 4 - -=item I<number> - -Specifies the element as a numerical index, where 0 corresponds -to the first element in the listbox. - -=item B<active> - -Indicates the element that has the location cursor. This element -will be displayed with an underline when the listbox has the -keyboard focus, and it is specified with the B<activate> -method. - -=item B<anchor> - -Indicates the anchor point for the selection, which is set with the -B<selection anchor> method. - -=item B<end> - -Indicates the end of the listbox. -For most commands this refers to the last element in the listbox, -but for a few commands such as B<index> and B<insert> -it refers to the element just after the last one. - -=item B<@>I<x>B<,>I<y> - -Indicates the element that covers the point in the listbox window -specified by I<x> and I<y> (in pixel coordinates). If no -element covers that point, then the closest element to that -point is used. - -=back - -In the method descriptions below, arguments named I<index>, -I<first>, and I<last> always contain text indices in one of -the above forms. - -=head1 WIDGET METHODS - -The B<Listbox> method creates a widget object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. -The widget also inherits all the methods provided by the generic -L<Tk::Widget|Tk::Widget> class. - -The following additional methods are available for listbox widgets: - -=over 4 - -=item I<$listbox>-E<gt>B<activate>(I<index>) - -Sets the active element to the one indicated by I<index>. -If I<index> is outside the range of elements in the listbox -then the closest element is activated. -The active element is drawn with an underline when the widget -has the input focus, and its index may be retrieved with the -index B<active>. - -=item I<$listbox>-E<gt>B<bbox>(I<index>) - -Returns a list of four numbers describing the bounding box of -the text in the element given by I<index>. -The first two elements of the list give the x and y coordinates -of the upper-left corner of the screen area covered by the text -(specified in pixels relative to the widget) and the last two -elements give the width and height of the area, in pixels. -If no part of the element given by I<index> is visible on the -screen, -or if I<index> refers to a non-existent element, -then the result is an empty string; if the element is -partially visible, the result gives the full area of the element, -including any parts that are not visible. - -=item I<$listbox>-E<gt>B<curselection> - -Returns a list containing the numerical indices of -all of the elements in the listbox that are currently selected. -If there are no elements selected in the listbox then an empty -string is returned. - -=item I<$listbox>-E<gt>B<delete>(I<first, >?I<last>?) - -Deletes one or more elements of the listbox. I<First> and I<last> -are indices specifying the first and last elements in the range -to delete. If I<last> isn't specified it defaults to -I<first>, i.e. a single element is deleted. - -=item I<$listbox>-E<gt>B<get>(I<first, >?I<last>?) - -If I<last> is omitted, returns the contents of the listbox -element indicated by I<first>, -or an empty string if I<first> refers to a non-existent element. -If I<last> is specified, the command returns a list whose elements -are all of the listbox elements between I<first> and I<last>, -inclusive. -Both I<first> and I<last> may have any of the standard -forms for indices. - -=item I<$listbox>-E<gt>B<index>(I<index>) - -Returns the integer index value that corresponds to I<index>. -If I<index> is B<end> the return value is a count of the number -of elements in the listbox (not the index of the last element). - -=item I<$listbox>-E<gt>B<insert>(I<index, >?I<element, element, ...>?) - -Inserts zero or more new elements in the list just before the -element given by I<index>. If I<index> is specified as -B<end> then the new elements are added to the end of the -list. Returns an empty string. - -=item I<$listbox>-E<gt>B<itemcget>(I<index>, I<option>) - -Returns the current value of the item configuration option given by -I<option>. Option may have any of the values accepted by the listbox -B<itemconfigure> command. - -=item I<$listbox>-E<gt>B<itemconfigure>(I<index, >?I<option, value, -option, value, ...>?) - -Query or modify the configuration options of an item in the listbox. -If no option is specified, returns a list describing all of the -available options for the item (see Tk_ConfigureInfo for information -on the format of this list). If option is specified with no value, -then the command returns a list describing the one named option (this -list will be identical to the corresponding sublist of the value -returned if no option is specified). If one or more option-value pairs -are specified, then the command modifies the given widget option(s) to -have the given value(s); in this case the command returns an empty -string. The following options are currently supported for items: - -=over - -=item B<-background> =E<gt> I<color> - -I<Color> specifies the background color to use when displaying the -item. It may have any of the forms accepted by Tk_GetColor. - -=item B<-foreground> =E<gt> I<color> - -I<Color> specifies the foreground color to use when displaying the -item. It may have any of the forms accepted by Tk_GetColor. - -=item B<-selectbackground> =E<gt> I<color> - -I<Color> specifies the background color to use when displaying the -item while it is selected. It may have any of the forms accepted by -Tk_GetColor. - -=item B<-selectforeground> =E<gt> I<color> - -I<Color> specifies the foreground color to use when displaying the -item while it is selected. It may have any of the forms accepted by -Tk_GetColor. - -=back - -=item I<$listbox>-E<gt>B<nearest>(I<y>) - -Given a y-coordinate within the listbox window, this command returns -the index of the (visible) listbox element nearest to that y-coordinate. - -=item I<$listbox>-E<gt>B<scan>(I<option, args>) - -This command is used to implement scanning on listboxes. It has -two forms, depending on I<option>: - -=over 8 - -=item I<$listbox>-E<gt>B<scanMark>(I<x, y>) - -Records I<x> and I<y> and the current view in the listbox -window; used in conjunction with later B<scan dragto> commands. -Typically this command is associated with a mouse button press in -the widget. It returns an empty string. - -=item I<$listbox>-E<gt>B<scanDragto>(I<x, y>.) - -This command computes the difference between its I<x> and I<y> -arguments and the I<x> and I<y> arguments to the last -B<scan mark> command for the widget. -It then adjusts the view by 10 times the -difference in coordinates. This command is typically associated -with mouse motion events in the widget, to produce the effect of -dragging the list at high speed through the window. The return -value is an empty string. - -=back - -=item I<$listbox>-E<gt>B<see>(I<index>) - -Adjust the view in the listbox so that the element given by I<index> -is visible. -If the element is already visible then the command has no effect; -if the element is near one edge of the window then the listbox -scrolls to bring the element into view at the edge; otherwise -the listbox scrolls to center the element. - -=item I<$listbox>-E<gt>B<selection>(I<option, arg>) - -This command is used to adjust the selection within a listbox. It -has several forms, depending on I<option>: - -=over 8 - -=item I<$listbox>-E<gt>B<selectionAnchor>(I<index>) - -Sets the selection anchor to the element given by I<index>. -If I<index> refers to a non-existent element, then the closest -element is used. -The selection anchor is the end of the selection that is fixed -while dragging out a selection with the mouse. -The index B<anchor> may be used to refer to the anchor -element. - -=item I<$listbox>-E<gt>B<selectionClear>(I<first, >?I<last>?) - -If any of the elements between I<first> and I<last> -(inclusive) are selected, they are deselected. -The selection state is not changed for elements outside -this range. - -=item I<$listbox>-E<gt>B<selectionIncludes>(I<index>) - -Returns 1 if the element indicated by I<index> is currently -selected, 0 if it isn't. - -=item I<$listbox>-E<gt>B<selectionSet>(I<first, >?I<last>?) - -Selects all of the elements in the range between -I<first> and I<last>, inclusive, without affecting -the selection state of elements outside that range. - -=back - -=item I<$listbox>-E<gt>B<size> - -Returns a decimal string indicating the total number of elements -in the listbox. - -=item I<$listbox>-E<gt>B<xview>(I<args>) - -This command is used to query and change the horizontal position of the -information in the widget's window. It can take any of the following -forms: - -=over 8 - -=item I<$listbox>-E<gt>B<xview> - -Returns a list containing two elements. -Each element is a real fraction between 0 and 1; together they describe -the horizontal span that is visible in the window. -For example, if the first element is .2 and the second element is .6, -20% of the listbox's text is off-screen to the left, the middle 40% is visible -in the window, and 40% of the text is off-screen to the right. -These are the same values passed to scrollbars via the B<-xscrollcommand> -option. - -=item I<$listbox>-E<gt>B<xview>(I<index>) - -Adjusts the view in the window so that the character position given by -I<index> is displayed at the left edge of the window. -Character positions are defined by the width of the character B<0>. - -=item I<$listbox>-E<gt>B<xviewMoveto>( I<fraction> ); - -Adjusts the view in the window so that I<fraction> of the -total width of the listbox text is off-screen to the left. -I<fraction> must be a fraction between 0 and 1. - -=item I<$listbox>-E<gt>B<xviewScroll>( I<number, what> ); - -This command shifts the view in the window left or right according to -I<number> and I<what>. -I<Number> must be an integer. -I<What> must be either B<units> or B<pages> or an abbreviation -of one of these. -If I<what> is B<units>, the view adjusts left or right by -I<number> character units (the width of the B<0> character) -on the display; if it is B<pages> then the view adjusts by -I<number> screenfuls. -If I<number> is negative then characters farther to the left -become visible; if it is positive then characters farther to the right -become visible. - -=back - -=item I<$listbox>-E<gt>B<yview>(I<?args>?) - -This command is used to query and change the vertical position of the -text in the widget's window. -It can take any of the following forms: - -=over 8 - -=item I<$listbox>-E<gt>B<yview> - -Returns a list containing two elements, both of which are real fractions -between 0 and 1. -The first element gives the position of the listbox element at the -top of the window, relative to the listbox as a whole (0.5 means -it is halfway through the listbox, for example). -The second element gives the position of the listbox element just after -the last one in the window, relative to the listbox as a whole. -These are the same values passed to scrollbars via the B<-yscrollcommand> -option. - -=item I<$listbox>-E<gt>B<yview>(I<index>) - -Adjusts the view in the window so that the element given by -I<index> is displayed at the top of the window. - -=item I<$listbox>-E<gt>B<yviewMoveto>( I<fraction> ); - -Adjusts the view in the window so that the element given by I<fraction> -appears at the top of the window. -I<Fraction> is a fraction between 0 and 1; 0 indicates the first -element in the listbox, 0.33 indicates the element one-third the -way through the listbox, and so on. - -=item I<$listbox>-E<gt>B<yviewScroll>( I<number, what> ); - -This command adjusts the view in the window up or down according to -I<number> and I<what>. -I<Number> must be an integer. -I<What> must be either B<units> or B<pages>. -If I<what> is B<units>, the view adjusts up or down by -I<number> lines; if it is B<pages> then -the view adjusts by I<number> screenfuls. -If I<number> is negative then earlier elements -become visible; if it is positive then later elements -become visible. - -=back - -=back - -=head1 DEFAULT BINDINGS - -Tk automatically creates class bindings for listboxes that give them -Motif-like behavior. Much of the behavior of a listbox is determined -by its B<selectMode> option, which selects one of four ways -of dealing with the selection. - -If the selection mode is B<single> or B<browse>, at most one -element can be selected in the listbox at once. -In both modes, clicking button 1 on an element selects -it and deselects any other selected item. -In B<browse> mode it is also possible to drag the selection -with button 1. - -If the selection mode is B<multiple> or B<extended>, -any number of elements may be selected at once, including discontiguous -ranges. In B<multiple> mode, clicking button 1 on an element -toggles its selection state without affecting any other elements. -In B<extended> mode, pressing button 1 on an element selects -it, deselects everything else, and sets the anchor to the element -under the mouse; dragging the mouse with button 1 -down extends the selection to include all the elements between -the anchor and the element under the mouse, inclusive. - -Most people will probably want to use B<browse> mode for -single selections and B<extended> mode for multiple selections; -the other modes appear to be useful only in special situations. - -Any time the selection changes in the listbox, the virtual event -B<<< <<ListboxSelect>> >>> will be generated. It is easiest to bind to this -event to be made aware of any changes to listbox selection. - - -In addition to the above behavior, the following additional behavior -is defined by the default bindings: - -=over 4 - -=item [1] - -In B<extended> mode, the selected range can be adjusted by pressing -button 1 with the Shift key down: this modifies the selection to -consist of the elements between the anchor and the element under -the mouse, inclusive. -The un-anchored end of this new selection can also be dragged with -the button down. - -=item [2] - -In B<extended> mode, pressing button 1 with the Control key down -starts a toggle operation: the anchor is set to the element under -the mouse, and its selection state is reversed. The selection state -of other elements isn't changed. -If the mouse is dragged with button 1 down, then the selection state -of all elements between the anchor and the element under the mouse -is set to match that of the anchor element; the selection state of -all other elements remains what it was before the toggle operation -began. - -=item [3] - -If the mouse leaves the listbox window with button 1 down, the window -scrolls away from the mouse, making information visible that used -to be off-screen on the side of the mouse. -The scrolling continues until the mouse re-enters the window, the -button is released, or the end of the listbox is reached. - -=item [4] - -Mouse button 2 may be used for scanning. -If it is pressed and dragged over the listbox, the contents of -the listbox drag at high speed in the direction the mouse moves. - -=item [5] - -If the Up or Down key is pressed, the location cursor (active -element) moves up or down one element. -If the selection mode is B<browse> or B<extended> then the -new active element is also selected and all other elements are -deselected. -In B<extended> mode the new active element becomes the -selection anchor. - -=item [6] - -In B<extended> mode, Shift-Up and Shift-Down move the location -cursor (active element) up or down one element and also extend -the selection to that element in a fashion similar to dragging -with mouse button 1. - -=item [7] - -The Left and Right keys scroll the listbox view left and right -by the width of the character B<0>. -Control-Left and Control-Right scroll the listbox view left and -right by the width of the window. -Control-Prior and Control-Next also scroll left and right by -the width of the window. - -=item [8] - -The Prior and Next keys scroll the listbox view up and down -by one page (the height of the window). - -=item [9] - -The Home and End keys scroll the listbox horizontally to -the left and right edges, respectively. - -=item [10] - -Control-Home sets the location cursor to the the first element in -the listbox, selects that element, and deselects everything else -in the listbox. - -=item [11] - -Control-End sets the location cursor to the the last element in -the listbox, selects that element, and deselects everything else -in the listbox. - -=item [12] - -In B<extended> mode, Control-Shift-Home extends the selection -to the first element in the listbox and Control-Shift-End extends -the selection to the last element. - -=item [13] - -In B<multiple> mode, Control-Shift-Home moves the location cursor -to the first element in the listbox and Control-Shift-End moves -the location cursor to the last element. - -=item [14] - -The space and Select keys make a selection at the location cursor -(active element) just as if mouse button 1 had been pressed over -this element. - -=item [15] - -In B<extended> mode, Control-Shift-space and Shift-Select -extend the selection to the active element just as if button 1 -had been pressed with the Shift key down. - -=item [16] - -In B<extended> mode, the Escape key cancels the most recent -selection and restores all the elements in the selected range -to their previous selection state. - -=item [17] - -Control-slash selects everything in the widget, except in -B<single> and B<browse> modes, in which case it selects -the active element and deselects everything else. - -=item [18] - -Control-backslash deselects everything in the widget, except in -B<browse> mode where it has no effect. - -=item [19] - -The F16 key (labelled Copy on many Sun workstations) or Meta-w -copies the selection in the widget to the clipboard, if there is -a selection. - -The behavior of listboxes can be changed by defining new bindings for -individual widgets or by redefining the class bindings. - -=back - -=head1 TIED INTERFACE - -The Tk::Listbox widget can also be tied to a scalar or array variable, with -different behaviour depending on the variable type, with the following -tie commands: - - use Tk; - - my ( @array, $scalar, $other ); - my %options = ( ReturnType => "index" ); - - my $MW = MainWindow->new(); - my $lbox = $MW->Listbox()->pack(); - - my @list = ( "a", "b", "c", "d", "e", "f" ); - $lbox->insert('end', @list ); - - tie @array, "Tk::Listbox", $lbox - tie $scalar, "Tk::Listbox", $lbox; - tie $other, "Tk::Listbox", $lbox, %options; - -currently only one modifier is implemented, a 3 way flag for tied scalars -"ReturnType" which can have values "element", "index" or "both". The default -is "element". - -=over 4 - -=item Tied Arrays - -If you tie an array to the Listbox you can manipulate the items currently -contained by the box in the same manner as a normal array, e.g. - - print @array; - push(@array, @list); - my $popped = pop(@array); - my $shifted = shift(@array); - unshift(@array, @list); - delete $array[$index]; - print $string if exists $array[$i]; - @array = (); - splice @array, $offset, $length, @list - -The delete function is implemented slightly differently from the standard -array implementation. Instead of setting the element at that index to undef -it instead physically removes it from the Listbox. This has the effect of -changing the array indices, so for instance if you had a list on non-continuous -indices you wish to remove from the Listbox you should reverse sort the list -and then apply the delete function, e.g. - - my @list = ( 1, 2, 4, 12, 20 ); - my @remove = reverse sort { $a <=> $b } @list; - delete @array[@remove]; - -would safely remove indices 20, 12, 4, 2 and 1 from the Listbox without -problems. It should also be noted that a similar warning applies to the -splice function (which would normally be used in this context to perform -the same job). - - -=item Tied Scalars - -Unlike tied arrays, if you tie a scalar to the Listbox you can retrieve the -currently selected elements in the box as an array referenced by the scalar, -for instance - - my @list = ( "a", "b", "c", "d", "e", "f" ); - $lbox->insert('end', sort @list ); - $lbox->selectionSet(1); - -inserts @list as elements in an already existing listbox and selects the -element at index 1, which is "b". If we then - - print @$selected; - -this will return the currently selected elements, in this case "b". - -However, if the "ReturnType" arguement is passed when tying the Listbox to the -scalar with value "index" then the indices of the selected elements will be -returned instead of the elements themselves, ie in this case "1". This can be -useful when manipulating both contents and selected elements in the Listbox at -the same time. - -Importantly, if a value "both" is given the scalar will not be tied to an -array, but instead to a hash, with keys being the indices and values being -the elements at those indices - -You can also manipulate the selected items using the scalar. Equating the -scalar to an array reference will select any elements that match elements -in the Listbox, non-matching array items are ignored, e.g. - - my @list = ( "a", "b", "c", "d", "e", "f" ); - $lbox->insert('end', sort @list ); - $lbox->selectionSet(1); - -would insert the array @list into an already existing Listbox and select -element at index 1, i.e. "b" - - @array = ( "a", "b", "f" ); - $selected = \@array; - -would select elements "a", "b" and "f" in the Listbox. - -Again, if the "index" we indicate we want to use indices in the options hash -then the indices are use instead of elements, e.g. - - @array = ( 0, 1, 5 ); - $selected = \@array; - -would have the same effect, selecting elements "a", "b" and "f" if the -$selected variable was tied with %options = ( ReturnType => "index" ). - -If we are returning "both", i.e. the tied scalar points to a hash, both key and -value must match, e.g. - - %hash = ( 0 => "a", 1 => "b", 5 => "f" ); - $selected = \%hash; - -would have the same effect as the previous examples. - -It should be noted that, despite being a reference to an array (or possibly a has), you still can not copy the tied variable without it being untied, instead -you must pass a reference to the tied scalar between subroutines. - -=back - -=head1 KEYWORDS - -listbox, widget, tied - -=head1 SEE ALSO - -L<Tk::HList>, L<Tk::TextList>. - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/MainWindow.pod b/Master/tlpkg/tlperl/lib/Tk/MainWindow.pod deleted file mode 100644 index 565658adc1d..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/MainWindow.pod +++ /dev/null @@ -1,85 +0,0 @@ - -=head1 NAME - -Tk::MainWindow - Root widget of a widget tree - -=for pm Tk/MainWindow.pm - -=for category Creating and Configuring Widgets - -=head1 SYNOPSIS - - use Tk; - - my $mw = MainWindow->new( ... options ... ); - - my $this = $mw->ThisWidget -> pack ; - my $that = $mw->ThatWidget; - ... - - MainLoop; - -=head1 DESCRIPTION - -Perl/Tk applications (which have windows associated with them) create -one or more B<MainWindow>s which act as the containers and parents -of the other widgets. - -B<Tk::MainWindow> is a special kind of L<Toplevel|Tk::Toplevel> widget. It is -the root of a widget tree. Therefore C<$mw-E<gt>Parent> returns -C<undef>. - -The default title of a MainWindow is the basename of the script -(actually the Class name used for options lookup, i.e. with basename -with inital caps) or 'Ptk' as the fallback value. If more than one MainWindow is created -or several instances of the script are running at the same time the -string C<" #n"> is appended where the number C<n> is set to get -a unique value. - -Unlike the standard Tcl/Tk's wish, perl/Tk allows you to create -several MainWindows. When the I<last> B<MainWindow> is destroyed -the Tk eventloop exits (the eventloop is entered with the call of -C<MainLoop>). Various resources (bindings, fonts, images, colors) are -maintained or cached for each MainWindow, so each MainWindow consumes more -resources than a Toplevel. However multiple MainWindows can make sense when -the user can destroy them independently. - -=head1 METHODS - -You can apply all methods that a L<Toplevel|Tk::Toplevel> widget accepts. - -The method I<$w>-E<gt>B<MainWindow> applied to any widget will return the -B<MainWindow> to which the widget belongs (the MainWindow belongs to itself). - -=head1 MISSING - -Documentation is incomplete. -Here are I<some> missing items that should be explained in -more detail: - -=over 4 - -=item * - -The new mechanism for MainWindows is slightly different to -other widgets. - -=item * - -There no explanation about what resources are bound -to a MainWindow (e.g., ClassInit done per MainWindow) - -=item * - -Passing of command line options to override or augment -arguments of the C<new> method (see L<Tk::CmdLine>). - -=back - -=head1 SEE ALSO - -L<Tk::Toplevel|Tk::Toplevel> -L<Tk::CmdLine|Tk::CmdLine> - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Menu.pod b/Master/tlpkg/tlperl/lib/Tk/Menu.pod deleted file mode 100644 index b7414e57510..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Menu.pod +++ /dev/null @@ -1,876 +0,0 @@ -# Copyright (c) 1990-1994 The Regents of the University of California. -# Copyright (c) 1994-1997 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::Menu - Create and manipulate Menu widgets - -=for category Tk Widget Classes - -=head1 SYNOPSIS - -S< >I<$menu> = I<$parent>-E<gt>B<Menu>(?I<options>?); - -=head1 STANDARD OPTIONS - -B<-activebackground> B<-background> B<-disabledforeground> B<-relief> -B<-activeborderwidth> B<-borderwidth> B<-font> B<-takefocus> -B<-activeforeground> B<-cursor> B<-foreground> - -See L<Tk::options> for details of the standard options. - -=head1 WIDGET-SPECIFIC OPTIONS - -=over 4 - -=item Name: B<postCommand> - -=item Class: B<Command> - -=item Switch: B<-postcommand> - -If this option is specified then it provides a L<callback|Tk::callbacks> to execute -each time the menu is posted. The callback is invoked by the B<post> -method before posting the menu. Note that in 8.0 on Macintosh -and Windows, all commands in a menu systems are executed before any -are posted. This is due to the limitations in the individual platforms' -menu managers. - -=item Name: B<selectColor> - -=item Class: B<Background> - -=item Switch: B<-selectcolor> - -For menu entries that are check buttons or radio buttons, this option -specifies the color to display in the indicator when the check button -or radio button is selected. - -=item Name: B<tearOff> - -=item Class: B<TearOff> - -=item Switch: B<-tearoff> - -This option must have a proper boolean value, which specifies -whether or not the menu should include a tear-off entry at the -top. If so, it will exist as entry 0 of the menu and the other -entries will number starting at 1. The default -menu bindings arrange for the menu to be torn off when the tear-off -entry is invoked. - -=item Name: B<tearOffCommand> - -=item Class: B<TearOffCommand> - -=item Switch: B<-tearoffcommand> - -If this option has a non-empty value, then it specifies a L<perl/Tk callback|Tk::callbacks> -to invoke whenever the menu is torn off. The actual command will -consist of the value of this option, followed by a space, followed -by the name of the menu window, followed by a space, followed by -the name of the name of the torn off menu window. For example, if -the option's is ``B<a b>'' and menu B<.x.y> is torn off to -create a new menu B<.x.tearoff1>, then the command -``B<a b .x.y .x.tearoff1>'' will be invoked. - -=item Name: B<title> - -=item Class: B<Title> - -=item Switch: B<-title> - -The string will be used to title the window created when this menu is -torn off. If the title is NULL, then the window will have the title -of the menubutton or the text of the cascade item from which this menu -was invoked. - -=item Name: B<type> - -=item Class: B<Type> - -=item Switch: B<-type> - -This option can be one of B<menubar>, B<tearoff>, or -B<normal>, and is set when the menu is created. While the string -returned by the configuration database will change if this option is -changed, this does not affect the menu widget's behavior. This is used -by the cloning mechanism and is not normally set outside of the Tk -library. - -=back - -=head1 DESCRIPTION - -The B<Menu> method creates a new top-level window (given -by the $widget argument) and makes it into a menu widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the menu such as its colors and font. -The B<menu> command returns its -$widget argument. At the time this command is invoked, -there must not exist a window named $widget, but -$widget's parent must exist. - -A menu is a widget that displays a collection of one-line entries arranged -in one or more columns. There exist several different types of entries, -each with different properties. Entries of different types may be -combined in a single menu. Menu entries are not the same as -entry widgets. In fact, menu entries are not even distinct widgets; -the entire menu is one widget. - -Menu entries are displayed with up to three separate fields. -The main field is a label in the form of a text string, -a bitmap, or an image, controlled by the B<-label>, -B<-bitmap>, and B<-image> options for the entry. -If the B<-accelerator> option is specified for an entry then a second -textual field is displayed to the right of the label. The accelerator -typically describes a keystroke sequence that may be typed in the -application to cause the same result as invoking the menu entry. -The third field is an I<indicator>. The indicator is present only for -checkbutton or radiobutton entries. It indicates whether the entry -is selected or not, and is displayed to the left of the entry's -string. - -In normal use, an entry becomes active (displays itself differently) -whenever the mouse pointer is over the entry. If a mouse -button is released over the entry then the entry is I<invoked>. -The effect of invocation is different for each type of entry; -these effects are described below in the sections on individual -entries. - -Entries may be I<disabled>, which causes their labels -and accelerators to be displayed -with dimmer colors. -The default menu bindings will not allow -a disabled entry to be activated or invoked. -Disabled entries may be re-enabled, at which point it becomes -possible to activate and invoke them again. - -Whenever a menu's active entry is changed, a E<lt>E<lt>MenuSelectE<gt>E<gt> virtual -event is sent to the menu. The active item can then be queried from -the menu, and an action can be taken, such as setting -context-sensitive help text for the entry. - -=head2 COMMAND ENTRIES - -The most common kind of menu entry is a command entry, which -behaves much like a button widget. When a command entry is -invoked, a callback is executed. The callback -is specified with the B<-command> option. - -=head2 SEPARATOR ENTRIES - -A separator is an entry that is displayed as a horizontal dividing -line. A separator may not be activated or invoked, and it has -no behavior other than its display appearance. - -=head2 CHECKBUTTON ENTRIES - -A checkbutton menu entry behaves much like a checkbutton widget. -When it is invoked it toggles back and forth between the selected -and deselected states. When the entry is selected, a particular -value is stored in a particular global variable (as determined by -the B<-onvalue> and B<-variable> options for the entry); when -the entry is deselected another value (determined by the -B<-offvalue> option) is stored in the global variable. -An indicator box is displayed to the left of the label in a checkbutton -entry. If the entry is selected then the indicator's center is displayed -in the color given by the B<-selectcolor> option for the entry; -otherwise the indicator's center is displayed in the background color for -the menu. If a B<-command> option is specified for a checkbutton -entry, then its value is evaluated each time the entry -is invoked; this happens after toggling the entry's -selected state. - -=head2 RADIOBUTTON ENTRIES - -A radiobutton menu entry behaves much like a radiobutton widget. -Radiobutton entries are organized in groups of which only one -entry may be selected at a time. Whenever a particular entry -becomes selected it stores a particular value into a particular -global variable (as determined by the B<-value> and -B<-variable> options for the entry). This action -causes any previously-selected entry in the same group -to deselect itself. -Once an entry has become selected, any change to the entry's -associated variable will cause the entry to deselect itself. -Grouping of radiobutton entries is determined by their -associated variables: if two entries have the same associated -variable then they are in the same group. -An indicator diamond is displayed to the left of the label in each -radiobutton entry. If the entry is selected then the indicator's -center is displayed in the color given by the B<-selectcolor> option -for the entry; -otherwise the indicator's center is displayed in the background color for -the menu. If a B<-command> option is specified for a radiobutton -entry, then its value is evaluated each time the entry -is invoked; this happens after selecting the entry. - -=head2 CASCADE ENTRIES - -A cascade entry is one with an associated menu (determined -by the B<-menu> option). Cascade entries allow the construction -of cascading menus. -The B<postcascade> method can be used to post and unpost -the associated menu just next to of the cascade entry. -The associated menu must be a child of the menu containing -the cascade entry (this is needed in order for menu traversal to -work correctly). - -A cascade entry posts its associated menu by invoking - -=over 4 - -I<$menu>-E<gt>B<post>(I<x,y>) - -=back - -where I<menu> is the path name of the associated menu, and I<x> -and I<y> are the root-window coordinates of the upper-right -corner of the cascade entry. -On Unix, the lower-level menu is unposted by executing - -=over 4 - -I<$menu>-E<gt>B<unpost> - -=back - -where I<menu> is the name of the associated menu. -On other platforms, the platform's native code takes care of unposting the -menu. - -If a B<-command> option is specified for a cascade entry then it is -evaluated whenever the entry is invoked. This is not supported on Windows. - -=head2 TEAR-OFF ENTRIES - -A tear-off entry appears at the top of the menu if enabled with the -B<tearOff> option. It is not like other menu entries in that -it cannot be created with the B<add> method and -cannot be deleted with the B<delete> method. -When a tear-off entry is created it appears as a dashed line at -the top of the menu. Under the default bindings, invoking the -tear-off entry causes a torn-off copy to be made of the menu and -all of its submenus. - -=head2 MENUBARS - -Any menu can be set as a menubar for a toplevel window (see the -L<Toplevel|Tk::Toplevel> constructor for syntax). On the Macintosh, whenever the -toplevel is in front, this menu's cascade items will appear in the -menubar across the top of the main monitor. On Windows and Unix, this -menu's items will be displayed in a menubar accross the top of the -window. These menus will behave according to the interface guidelines -of their platforms. For every menu set as a menubar, a clone menu is -made. See L<"CLONES"> for more information. - -As noted, menubars may behave differently on different platforms. One -example of this concerns the handling of checkbuttons and radiobuttons -within the menu. While it is permitted to put these menu elements on -menubars, they may not be drawn with indicators on some platforms, due -to system restrictions. - -=head2 SPECIAL MENUS IN MENUBARS - -Certain menus in a menubar will be treated specially. On the Macintosh, -access to the special Apple and Help menus is provided. On Windows, -access to the Windows System menu in each window is provided. On X Windows, -a special right-justified help menu is provided. In all cases, these -menus must be created with the command name of the menubar menu concatenated -with the special name. So for a menubar named .menubar, on the Macintosh, -the special menus would be .menubar.apple and .menubar.help; on Windows, -the special menu would be .menubar.system; on X Windows, the help -menu would be .menubar.help. - -When Tk sees an Apple menu on the Macintosh, that menu's contents make -up the first items of the Apple menu on the screen whenever the window -containing the menubar is in front. The menu is the -first one that the user sees and has a title which is an Apple logo. -After all of the Tk-defined items, the menu will have a separator, -followed by all of the items in the user's Apple Menu Items folder. -Since the System uses a different menu definition procedure for -the Apple menu than Tk uses for its menus, and the system APIs do -not fully support everything Tk tries to do, the menu item will only -have its text displayed. No font attributes, images, bitmaps, or colors -will be displayed. In addition, a menu with a tearoff item will have -the tearoff item displayed as "(TearOff)". - -When Tk see a Help menu on the Macintosh, the menu's contents are -appended to the standard help menu on the right of the user's menubar -whenever the user's menubar is in front. The first items in the menu -are provided by Apple. Similar to the Apple Menu, cusomization in this -menu is limited to what the system provides. - -When Tk sees a System menu on Windows, its items are appended to the -system menu that the menubar is attached to. This menu has an icon -representing a spacebar, and can be invoked with the mouse or by typing -Alt+Spacebar. Due to limitations in the Windows API, any font changes, -colors, images, bitmaps, or tearoff images will not appear in the -system menu. - -When Tk see a Help menu on X Windows, the menu is moved to be last in -the menubar and is right justified. - -=head2 CLONES - -When a menu is set as a menubar for a toplevel window, or when a menu -is torn off, a clone of the menu is made. This clone is a menu widget -in its own right, but it is a child of the original. Changes in the -configuration of the original are reflected in the -clone. Additionally, any cascades that are pointed to are also cloned -so that menu traversal will work right. Clones are destroyed when -either the tearoff or menubar goes away, or when the original menu is -destroyed. - -=head2 WIDGET METHODS - -The B<Menu> method creates a widget object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. -The widget also inherits all the methods provided by the generic -L<Tk::Widget|Tk::Widget> class, and the L<Tk::Wm|Tk::Wm> class. - -Many of the methods for a menu take as one argument an -indicator of which entry of the menu to operate on. These -indicators are called I<index>es and may be specified in -any of the following forms: - -=over 4 - -=item I<number> - -Specifies the entry numerically, where 0 corresponds -to the top-most entry of the menu, 1 to the entry below it, and -so on. - -=item B<active> - -Indicates the entry that is currently active. If no entry is -active then this form is equivalent to B<none>. This form may -not be abbreviated. - -=item B<end> - -Indicates the bottommost entry in the menu. If there are no -entries in the menu then this form is equivalent to B<none>. -This form may not be abbreviated. - -=item B<last> - -Same as B<end>. - -=item B<none> - -Indicates ``no entry at all''; this is used most commonly with -the B<activate> option to deactivate all the entries in the -menu. In most cases the specification of B<none> causes -nothing to happen in the method. -This form may not be abbreviated. - -=item B<@>I<number> - -In this form, I<number> is treated as a y-coordinate in the -menu's window; the entry closest to that y-coordinate is used. -For example, ``B<@0>'' indicates the top-most entry in the -window. - -=item I<pattern> - -If the index doesn't satisfy one of the above forms then this -form is used. I<Pattern> is pattern-matched against the label of -each entry in the menu, in order from the top down, until a -matching entry is found. -(In perl/Tk the matching is under review, but exact match -should work.) - -=back - -The following methods are possible for menu widgets: - -=over 4 - -=item I<$menu>-E<gt>B<activate>(I<index>) - -Change the state of the entry indicated by I<index> to B<active> -and redisplay it using its active colors. -Any previously-active entry is deactivated. If I<index> -is specified as B<none>, or if the specified entry is -disabled, then the menu ends up with no active entry. -Returns an empty string. - -=item I<$menu>-E<gt>B<add>(I<type, >?I<option, value, option, value, ...>?) - -Add a new entry to the bottom of the menu. The new entry's type -is given by I<type> and must be one of B<cascade>, -B<checkbutton>, B<command>, B<radiobutton>, or B<separator>, -or a unique abbreviation of one of the above. If additional arguments -are present, they specify any of the following options: - -=over 8 - -=item B<-activebackground> =E<gt> I<value> - -Specifies a background color to use for displaying this entry when it -is active. -If this option is specified as an empty string (the default), then the -B<activeBackground> option for the overall menu is used. -If the B<$Tk::strictMotif> variable has been set to request strict -Motif compliance, then this option is ignored and the B<-background> -option is used in its place. -This option is not available for separator or tear-off entries. - -=item B<-activeforeground> =E<gt> I<value> - -Specifies a foreground color to use for displaying this entry when it -is active. -If this option is specified as an empty string (the default), then the -B<activeForeground> option for the overall menu is used. -This option is not available for separator or tear-off entries. - -=item B<-accelerator> =E<gt> I<value> - -Specifies a string to display at the right side of the menu entry. -Normally describes an accelerator keystroke sequence that may be -typed to invoke the same function as the menu entry. This option -is not available for separator or tear-off entries. - -=item B<-background> =E<gt> I<value> - -Specifies a background color to use for displaying this entry when it -is in the normal state (neither active nor disabled). -If this option is specified as an empty string (the default), then the -B<background> option for the overall menu is used. -This option is not available for separator or tear-off entries. - -=item B<-bitmap> =E<gt> I<value> - -Specifies a bitmap to display in the menu instead of a textual -label, in any of the forms accepted by B<Tk_GetBitmap>. -This option overrides the B<-label> option but may be reset -to an empty string to enable a textual label to be displayed. -If a B<-image> option has been specified, it overrides -B<-bitmap>. -This option is not available for separator or tear-off entries. - -=item B<-columnbreak> =E<gt> I<value> - -When this option is zero, the appears below the previous entry. When -this option is one, the menu appears at the top of a new column in the -menu. - -=item B<-compound> =E<gt> I<value> - -Specifies whether the button should display both an image and text, -and if so, where the image should be placed relative to the text. -Valid values for this option are B<bottom>, B<center>, B<left>, -B<none>, B<right> and B<top>. The default value is B<none>, meaning -that the button will display either an image or text, depending on the -values of the -image and -bitmap options. - -=item B<-command> =E<gt> I<value> - -For command, checkbutton, and radiobutton entries, specifies a -callback to execute when the menu entry is invoked. -For cascade entries, specifies a callback to execute -when the entry is activated (i.e. just before its submenu is -posted). -Not available for separator or tear-off entries. - -=item B<-font> =E<gt> I<value> - -Specifies the font to use when drawing the label or accelerator -string in this entry. -If this option is specified as an empty string (the default) then -the B<font> option for the overall menu is used. -This option is not available for separator or tear-off entries. - -=item B<-foreground> =E<gt> I<value> - -Specifies a foreground color to use for displaying this entry when it -is in the normal state (neither active nor disabled). -If this option is specified as an empty string (the default), then the -B<foreground> option for the overall menu is used. -This option is not available for separator or tear-off entries. - -=item B<-hidemargin> =E<gt> I<value> - -Specifies whether the standard margins should be drawn for this menu -entry. This is useful when creating palette with images in them, i.e., -color palettes, pattern palettes, etc. 1 indicates that the margin for -the entry is hidden; 0 means that the margin is used. - -=item B<-image> =E<gt> I<value> - -Specifies an image to display in the menu instead of a text string -or bitmap -The image must have been created by some previous invocation of -B<image create>. -This option overrides the B<-label> and B<-bitmap> options -but may be reset to an empty string to enable a textual or -bitmap label to be displayed. -This option is not available for separator or tear-off entries. - -=item B<-indicatoron> =E<gt> I<value> - -Available only for checkbutton and radiobutton entries. -I<Value> is a boolean that determines whether or not the -indicator should be displayed. - -=item B<-label> =E<gt> I<value> - -Specifies a string to display as an identifying label in the menu -entry. Not available for separator or tear-off entries. - -=item B<-menu> =E<gt> I<value> - -Available only for cascade entries. Specifies the path name of -the submenu associated with this entry. -The submenu must be a child of the menu. - -=item B<-offvalue> =E<gt> I<value> - -Available only for checkbutton entries. Specifies the value to -store in the entry's associated variable when the entry is -deselected. - -=item B<-onvalue> =E<gt> I<value> - -Available only for checkbutton entries. Specifies the value to -store in the entry's associated variable when the entry is selected. - -=item B<-selectcolor> =E<gt> I<value> - -Available only for checkbutton and radiobutton entries. -Specifies the color to display in the indicator when the entry is -selected. -If the value is an empty string (the default) then the B<selectColor> -option for the menu determines the indicator color. - -=item B<-selectimage> =E<gt> I<value> - -Available only for checkbutton and radiobutton entries. -Specifies an image to display in the entry (in place of -the B<-image> option) when it is selected. -I<Value> is the name of an image, which must have been created -by some previous invocation of B<image create>. -This option is ignored unless the B<-image> option has -been specified. - -=item B<-state> =E<gt> I<value> - -Specifies one of three states for the entry: B<normal>, B<active>, -or B<disabled>. In normal state the entry is displayed using the -B<foreground> option for the menu and the B<background> -option from the entry or the menu. -The active state is typically used when the pointer is over the entry. -In active state the entry is displayed using the B<activeForeground> -option for the menu along with the B<activebackground> option from -the entry. Disabled state means that the entry -should be insensitive: the default bindings will refuse to activate -or invoke the entry. -In this state the entry is displayed according to the -B<disabledForeground> option for the menu and the -B<background> option from the entry. -This option is not available for separator entries. - -=item B<-underline> =E<gt> I<value> - -Specifies the integer index of a character to underline in the entry. -This option is also queried by the default bindings and used to -implement keyboard traversal. -0 corresponds to the first character of the text displayed in the entry, -1 to the next character, and so on. -If a bitmap or image is displayed in the entry then this option is ignored. -This option is not available for separator or tear-off entries. - -=item B<-value> =E<gt> I<value> - -Available only for radiobutton entries. Specifies the value to -store in the entry's associated variable when the entry is selected. -If an empty string is specified, then the B<-label> option -for the entry as the value to store in the variable. - -=item B<-variable> =E<gt> I<value> - -Available only for checkbutton and radiobutton entries. Specifies -the name of a global value to set when the entry is selected. -For checkbutton entries the variable is also set when the entry -is deselected. For radiobutton entries, changing the variable -causes the currently-selected entry to deselect itself. - -=back - -The B<add> method returns an empty string. - -=item I<$menu>-E<gt>B<clone>(I<$parent> ?, I<cloneType?>) - -Makes a clone of the current menu as a child of I<$parent>. This clone -is a menu in its own right, but any changes to the clone are -propogated to the original menu and vice versa. I<cloneType> can be -B<normal>, B<menubar>, or B<tearoff>. Should not normally be -called outside of the Tk library. See L<"CLONES"> for -more information. - -=item I<$menu>-E<gt>B<delete>(I<index1>?, I<index2>?) - -Delete all of the menu entries between I<index1> and -I<index2> inclusive. -If I<index2> is omitted then it defaults to I<index1>. -Attempts to delete a tear-off menu entry are ignored (instead, you -should change the B<tearOff> option to remove the tear-off entry). - -=item I<$menu>-E<gt>B<entrycget>(I<index, option>) - -Returns the current value of a configuration option for -the entry given by I<index>. -I<Option> may have any of the values accepted by the B<add> -method. - -=item I<$menu>-E<gt>B<entryconfigure>(I<index> ?,I<options>?) - -This method is similar to the B<configure> method, except that -it applies to the options for an individual entry, whereas B<configure> -applies to the options for the menu as a whole. -I<Options> may have any of the values accepted by the B<add> -method. If I<options> are specified, options are modified -as indicated -in the method call and the method returns an empty string. -If no I<options> are specified, returns a list describing -the current options for entry I<index> (see L<Tk::options> for -information on the format of this list). - -=item I<$menu>-E<gt>B<index>(I<index>) - -Returns the numerical index corresponding to I<index>, or -B<none> if I<index> was specified as B<none>. - -=item I<$menu>-E<gt>B<insert>(I<index, type>?, I<-option>=E<gt>I<value>, ...?) - -Same as the B<add> method except that it inserts the new -entry just before the entry given by I<index>, instead of appending -to the end of the menu. The I<type>, I<-option>, and I<value> -arguments have the same interpretation as for the B<add> widget -method. It is not possible to insert new menu entries before the -tear-off entry, if the menu has one. - -=item I<$menu>-E<gt>B<invoke>(I<index>) - -Invoke the action of the menu entry. See the sections on the -individual entries above for details on what happens. If the -menu entry is disabled then nothing happens. If the -entry has a callback associated with it then the result of that -callback is returned as the result of the B<invoke> widget -method. Otherwise the result is an empty string. Note: invoking -a menu entry does not automatically unpost the menu; the default -bindings normally take care of this before invoking the B<invoke> -method. - -=item I<$menu>-E<gt>B<post>(I<x, y>) - -Arrange for the menu to be displayed on the screen at the root-window -coordinates given by I<x> and I<y>. These coordinates are -adjusted if necessary to guarantee that the entire menu is visible on -the screen. This method normally returns an empty string. -If the B<postCommand> option has been specified, then its value is -executed before posting the menu and the result of -that callback is returned as the result of the B<post> widget -method. -If an error returns while executing the method, then the error is -returned without posting the menu. - -=item I<$menu>-E<gt>B<postcascade>(I<index>) - -Posts the submenu associated with the cascade entry given by -I<index>, and unposts any previously posted submenu. -If I<index> doesn't correspond to a cascade entry, -or if I<$menu> isn't posted, -the method has no effect except to unpost any currently posted -submenu. - -=item I<$menu>-E<gt>B<type>(I<index>) - -Returns the type of the menu entry given by I<index>. -This is the I<type> argument passed to the B<add> widget -method when the entry was created, such as B<command> -or B<separator>, or B<tearoff> for a tear-off entry. - -=item I<$menu>-E<gt>B<unpost> - -Unmap the window so that it is no longer displayed. If a -lower-level cascaded menu is posted, unpost that menu. Returns an -empty string. This method does not work on Windows and the -Macintosh, as those platforms have their own way of unposting menus. - -=item I<$menu>-E<gt>B<yposition>(I<index>) - -Returns a decimal string giving the y-coordinate within the menu -window of the topmost pixel in the entry specified by I<index>. - -=back - -=head1 MENU CONFIGURATIONS - -The default bindings support four different ways of using menus: - -=over 4 - -=item B<Pulldown Menus in Menubar> - -This is the most command case. You create a menu widget that will become the -menu bar. You then add cascade entries to this menu, specifying the -pull down menus you wish to use in your menu bar. You then create all -of the pulldowns. Once you have done this, specify the menu using the -B<-menu> option of the toplevel's method. See the -B<toplevel> manual entry for details. - -=item B<Pulldown Menus in Menu Buttons> - -This is the compatable way to do menu bars. You create one menubutton -widget for each top-level menu, and typically you arrange a series of -menubuttons in a row in a menubar window. You also create the top-level menus -and any cascaded submenus, and tie them together with B<-menu> -options in menubuttons and cascade menu entries. The top-level menu must -be a child of the menubutton, and each submenu must be a child of the -menu that refers to it. Once you have done this, the default bindings -will allow users to traverse and invoke the tree of menus via its -menubutton; see the B<menubutton> documentation for details. - -=item B<Popup Menus> - -Popup menus typically post in response to a mouse button press or -keystroke. You create the popup menus and any cascaded submenus, -then you call the B<Post> method at the appropriate time -to post the top-level menu. - -I<$menu>-E<gt>B<Post>(I<$x>,I<$y>?,I<$entry>?) - -I<$x> and I<$y> are the root window coordinates at which the I<$menu> -will be displayed. If I<$entry> is specified then that entry is centred -on that point, otherwise the top-left corner of the I<$menu> is placed -at that point. - -B<Menu> also inherits methods from L<Tk::Wm> and so the method -B<Popup> can be used to position menu relative to other windows, the -mouse cursor or the screen. - -=item B<Option Menus> - -An option menu consists of a menubutton with an associated menu -that allows you to select one of several values. The current value -is displayed in the menubutton and is also stored in a global -variable. Use the L<Tk::Optionmenu> class to create option -menubuttons and their menus. - -=item B<Torn-off Menus> - -You create a torn-off menu by invoking the tear-off entry at -the top of an existing menu. The default bindings will create a new menu -that is a copy of the original menu and leave it permanently -posted as a top-level window. The torn-off menu behaves just -the same as the original menu. - -=back - -=head1 DEFAULT BINDINGS - -Tk automatically creates class bindings for menus that give them -the following default behavior: - -=over 4 - -=item [1] - -When the mouse enters a menu, the entry underneath the mouse -cursor activates; as the mouse moves around the menu, the active -entry changes to track the mouse. - -=item [2] - -When the mouse leaves a menu all of the entries in the menu -deactivate, except in the special case where the mouse moves from -a menu to a cascaded submenu. - -=item [3] - -When a button is released over a menu, the active entry (if any) is invoked. -The menu also unposts unless it is a torn-off menu. - -=item [4] - -The Space and Return keys invoke the active entry and -unpost the menu. - -=item [5] - -If any of the entries in a menu have letters underlined with -with B<-underline> option, then pressing one of the underlined -letters (or its upper-case or lower-case equivalent) invokes that -entry and unposts the menu. - -=item [6] - -The Escape key aborts a menu selection in progress without invoking any -entry. It also unposts the menu unless it is a torn-off menu. - -=item [7] - -The Up and Down keys activate the next higher or lower entry -in the menu. When one end of the menu is reached, the active -entry wraps around to the other end. - -=item [8] - -The Left key moves to the next menu to the left. -If the current menu is a cascaded submenu, then the submenu is -unposted and the current menu entry becomes the cascade entry -in the parent. -If the current menu is a top-level menu posted from a -menubutton, then the current menubutton is unposted and the -next menubutton to the left is posted. -Otherwise the key has no effect. -The left-right order of menubuttons is determined by their stacking -order: Tk assumes that the lowest menubutton (which by default -is the first one created) is on the left. - -=item [9] - -The Right key moves to the next menu to the right. -If the current entry is a cascade entry, then the submenu is -posted and the current menu entry becomes the first entry -in the submenu. -Otherwise, if the current menu was posted from a -menubutton, then the current menubutton is unposted and the -next menubutton to the right is posted. - -Disabled menu entries are non-responsive: they don't activate and -they ignore mouse button presses and releases. - -The behavior of menus can be changed by defining new bindings for -individual widgets or by redefining the class bindings. - -=back - -=head1 BUGS - -At present it isn't possible to use the -option database to specify values for the options to individual -entries. - -=head1 SEE ALSO - -L<Tk::callbacks|Tk::callbacks> - -=head1 KEYWORDS - -menu, widget - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Menu/Item.pod b/Master/tlpkg/tlperl/lib/Tk/Menu/Item.pod deleted file mode 100644 index dabaadb8a58..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Menu/Item.pod +++ /dev/null @@ -1,96 +0,0 @@ - -=head1 NAME - -Tk::Menu::Item - Base class for Menu items - -=for pm Tk/Menu/Item.pm - -=for category Implementation - -=head1 SYNOPSIS - - require Tk::Menu::Item; - - my $but = $menu->Button(...); - $but->configure(...); - my $what = $but->cget(); - - package Whatever; - require Tk::Menu::Item; - @ISA = qw(Tk::Menu::Item); - - sub PreInit - { - my ($class,$menu,$info) = @_; - $info->{'-xxxxx'} = ... - my $y = delete $info->{'-yyyy'}; - } - -=head1 DESCRIPTION - -Tk::Menu::Item is the base class from which Tk::Menu::Button, -Tk::Menu::Cascade, Tk::Menu::Radiobutton and Tk::Menu::Checkbutton are derived. -There is also a Tk::Menu::Separator. - -Constructors are declared so that $menu-E<gt>Button(...) etc. do what you would -expect. - -The C<-label> option is pre-processed allowing ~ to be prefixed to the character -to derive a C<-underline> value. Thus - - $menu->Button(-label => 'Goto ~Home',...) - - is equivalent to - - $menu->Button(-label => 'Goto Home', -underline => 6, ...) - -The C<Cascade> menu item creates a sub-menu and accepts -these options: - -=over 4 - -=item B<-menuitems> - -A list of items for the sub-menu. -Within this list (which is also accepted by Menu and Menubutton) the first -two elements of each item should be the "constructor" name and the label: - - -menuitems => [ - [Button => '~Quit', -command => [destroy => $mw]], - [Checkbutton => '~Oil', -variable => \$oil], - ] - -=item B<-postcommand> - -A callback to be invoked before posting the menu. - -=item B<-tearoff> - -Specifies whether sub-menu can be torn-off or not. - -=item B<-menuvar> - -Scalar reference that will be set to the newly-created sub-menu. - -=back - -The returned object is currently a blessed reference to an array of two items: -the containing Menu and the 'label'. -Methods C<configure> and C<cget> are mapped onto underlying C<entryconfigure> -and C<entrycget>. - -The main purpose of the OO interface is to allow derived item classes to -be defined which pre-set the options used to create a more basic item. - -=head1 BUGS - -This OO interface is very new. Using the label as the "key" is a problem -for separaror items which don't have one. The alternative would be to -use an index into the menu but that is a problem if items are deleted -(or inserted other than at the end). - -There should probably be a PostInit entry point too, or a more widget like -defered 'configure'. - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Menubutton.pod b/Master/tlpkg/tlperl/lib/Tk/Menubutton.pod deleted file mode 100644 index fcda3e958aa..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Menubutton.pod +++ /dev/null @@ -1,249 +0,0 @@ -# Copyright (c) 1990-1994 The Regents of the University of California. -# Copyright (c) 1994-1997 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::Menubutton - Create and manipulate Menubutton widgets - -=for category Tk Widget Classes - -=head1 SYNOPSIS - -I<$menubutton> = I<$parent>-E<gt>B<Menubutton>(?I<options>?); - -=head1 STANDARD OPTIONS - -B<-activebackground> B<-cursor> B<-highlightthickness> B<-takefocus> -B<-activeforeground> B<-disabledforeground> B<-image> B<-text> -B<-anchor> B<-font> B<-justify> B<-textvariable> -B<-background> B<-foreground> B<-padx> B<-underline> -B<-bitmap> B<-highlightbackground> B<-pady> B<-wraplength> -B<-borderwidth> B<-highlightcolor> B<-relief> - -See L<Tk::options> for details of the standard options. - -=head1 WIDGET-SPECIFIC OPTIONS - -=over 4 - -=item Command-Line Name: B<-compound> - -=item Database Name: B<compound> - -=item Database Class: B<Compound> - -Specifies whether the button should display both an image and text, -and if so, where the image should be placed relative to the text. -Valid values for this option are B<bottom>, B<center>, B<left>, -B<none>, B<right> and B<top>. The default value is B<none>, meaning -that the button will display either an image or text, depending on the -values of the -image and -bitmap options. - -=item Name: B<direction> - -=item Class: B<Height> - -=item Switch: B<-direction> - -Specifies where the menu is going to be popup up. B<above> tries to -pop the menu above the menubutton. B<below> tries to pop the menu -below the menubutton. B<left> tries to pop the menu to the left of -the menubutton. B<right> tries to pop the menu to the right of the -menu button. B<flush> pops the menu directly over the menubutton. - -=item Name: B<height> - -=item Class: B<Height> - -=item Switch: B<-height> - -Specifies a desired height for the menubutton. -If an image or bitmap is being displayed in the menubutton then the value is in -screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>); -for text it is in lines of text. -If this option isn't specified, the menubutton's desired height is computed -from the size of the image or bitmap or text being displayed in it. - -=item Name: B<indicatorOn> - -=item Class: B<IndicatorOn> - -=item Switch: B<-indicatoron> - -The value must be a proper boolean value. If it is true then -a small indicator rectangle will be displayed on the right side -of the menubutton and the default menu bindings will treat this -as an option menubutton. If false then no indicator will be -displayed. - -=item Name: B<menu> - -=item Class: B<MenuName> - -=item Switch: B<-menu> - -Specifies the path name of the menu associated with this menubutton. -The menu must be a child of the menubutton. - -=item Name: B<state> - -=item Class: B<State> - -=item Switch: B<-state> - -Specifies one of three states for the menubutton: B<normal>, B<active>, -or B<disabled>. In normal state the menubutton is displayed using the -B<foreground> and B<background> options. The active state is -typically used when the pointer is over the menubutton. In active state -the menubutton is displayed using the B<activeForeground> and -B<activeBackground> options. Disabled state means that the menubutton -should be insensitive: the default bindings will refuse to activate -the widget and will ignore mouse button presses. -In this state the B<disabledForeground> and -B<background> options determine how the button is displayed. - -=item Name: B<width> - -=item Class: B<Width> - -=item Switch: B<-width> - -Specifies a desired width for the menubutton. -If an image or bitmap is being displayed in the menubutton then the value is in -screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>); -for text it is in characters. -If this option isn't specified, the menubutton's desired width is computed -from the size of the image or bitmap or text being displayed in it. - -=back - -=head1 DESCRIPTION - -The B<Menubutton> method creates a new window (given by the -$widget argument) and makes it into a menubutton widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the menubutton such as its colors, font, -text, and initial relief. The B<menubutton> command returns its -$widget argument. At the time this command is invoked, -there must not exist a window named $widget, but -$widget's parent must exist. - -A menubutton is a widget that displays a textual string, bitmap, or image -and is associated with a menu widget. -If text is displayed, it must all be in a single font, but it -can occupy multiple lines on the screen (if it contains newlines -or if wrapping occurs because of the B<wrapLength> option) and -one of the characters may optionally be underlined using the -B<underline> option. In normal usage, pressing -mouse button 1 over the menubutton causes the associated menu to -be posted just underneath the menubutton. If the mouse is moved over -the menu before releasing the mouse button, the button release -causes the underlying menu entry to be invoked. When the button -is released, the menu is unposted. - -Menubuttons are typically organized into groups called menu bars -that allow scanning: -if the mouse button is pressed over one menubutton (causing it -to post its menu) and the mouse is moved over another menubutton -in the same menu bar without releasing the mouse button, then the -menu of the first menubutton is unposted and the menu of the -new menubutton is posted instead. - -There are several interactions between menubuttons and menus; see -the B<menu> manual entry for information on various menu configurations, -such as pulldown menus and option menus. - -=head1 WIDGET METHODS - -The B<Menubutton> method creates a widget object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. -The B<menu> method returns the menu associated with the widget. -The widget also inherits all the methods provided by the generic -L<Tk::Widget|Tk::Widget> class. - -=head1 DEFAULT BINDINGS - -Tk automatically creates class bindings for menubuttons that give them -the following default behavior: - -=over 4 - -=item [1] - -A menubutton activates whenever the mouse passes over it and deactivates -whenever the mouse leaves it. - -=item [2] - -Pressing mouse button 1 over a menubutton posts the menubutton: -its relief changes to raised and its associated menu is posted -under the menubutton. If the mouse is dragged down into the menu -with the button still down, and if the mouse button is then -released over an entry in the menu, the menubutton is unposted -and the menu entry is invoked. - -=item [3] - -If button 1 is pressed over a menubutton and then released over that -menubutton, the menubutton stays posted: you can still move the mouse -over the menu and click button 1 on an entry to invoke it. -Once a menu entry has been invoked, the menubutton unposts itself. - -=item [4] - -If button 1 is pressed over a menubutton and then dragged over some -other menubutton, the original menubutton unposts itself and the -new menubutton posts. - -=item [5] - -If button 1 is pressed over a menubutton and released outside -any menubutton or menu, the menubutton unposts without invoking -any menu entry. - -=item [6] - -When a menubutton is posted, its associated menu claims the input -focus to allow keyboard traversal of the menu and its submenus. -See the B<menu> documentation for details on these bindings. - -=item [7] - -If the B<underline> option has been specified for a menubutton -then keyboard traversal may be used to post the menubutton: -Alt+I<x>, where I<x> is the underlined character (or its -lower-case or upper-case equivalent), may be typed in any window -under the menubutton's toplevel to post the menubutton. - -=item [8] - -The F10 key may be typed in any window to post the first menubutton -under its toplevel window that isn't disabled. - -=item [9] - -If a menubutton has the input focus, the space and return keys -post the menubutton. - -If the menubutton's state is B<disabled> then none of the above -actions occur: the menubutton is completely non-responsive. - -The behavior of menubuttons can be changed by defining new bindings for -individual widgets or by redefining the class bindings. - -=back - -=head1 KEYWORDS - -menubutton, widget - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Message.pod b/Master/tlpkg/tlperl/lib/Tk/Message.pod deleted file mode 100644 index 9b0d67f3118..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Message.pod +++ /dev/null @@ -1,151 +0,0 @@ -# Copyright (c) 1990-1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::Message - Create and manipulate Message widgets - -=for category Tk Widget Classes - -=head1 SYNOPSIS - -I<$message> = I<$parent>-E<gt>B<Message>(?I<options>?); - -=head1 STANDARD OPTIONS - -B<-anchor> B<-font> B<-highlightthickness> B<-takefocus> -B<-background> B<-foreground> B<-padx> B<-text> -B<-borderwidth> B<-highlightbackground> B<-pady> B<-textvariable> -B<-cursor> B<-highlightcolor> B<-relief> B<-width> - -See L<Tk::options> for details of the standard options. - -=head1 WIDGET-SPECIFIC OPTIONS - -=over 4 - -=item Name: B<aspect> - -=item Class: B<Aspect> - -=item Switch: B<-aspect> - -Specifies a non-negative integer value indicating desired -aspect ratio for the text. The aspect ratio is specified as -100*width/height. 100 means the text should -be as wide as it is tall, 200 means the text should -be twice as wide as it is tall, 50 means the text should -be twice as tall as it is wide, and so on. -Used to choose line length for text if B<width> option -isn't specified. -Defaults to 150. - -=item Name: B<justify> - -=item Class: B<Justify> - -=item Switch: B<-justify> - -Specifies how to justify lines of text. -Must be one of B<left>, B<center>, or B<right>. Defaults -to B<left>. -This option works together with the B<anchor>, B<aspect>, -B<padX>, B<padY>, and B<width> options to provide a variety -of arrangements of the text within the window. -The B<aspect> and B<width> options determine the amount of -screen space needed to display the text. -The B<anchor>, B<padX>, and B<padY> options determine where this -rectangular area is displayed within the widget's window, and the -B<justify> option determines how each line is displayed within that -rectangular region. -For example, suppose B<anchor> is B<e> and B<justify> is -B<left>, and that the message window is much larger than needed -for the text. -The the text will displayed so that the left edges of all the lines -line up and the right edge of the longest line is B<padX> from -the right side of the window; the entire text block will be centered -in the vertical span of the window. - -=item Name: B<width> - -=item Class: B<Width> - -=item Switch: B<-width> - -Specifies the length of lines in the window. -The value may have any of the forms acceptable to B<Tk_GetPixels>. -If this option has a value greater than zero then the B<aspect> -option is ignored and the B<width> option determines the line -length. -If this option has a value less than or equal to zero, then -the B<aspect> option determines the line length. - -=back - -=head1 DESCRIPTION - -The B<Message> method creates a new window (given by the -$widget argument) and makes it into a message widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the message such as its colors, font, -text, and initial relief. The B<message> command returns its -$widget argument. At the time this command is invoked, -there must not exist a window named $widget, but -$widget's parent must exist. - -A message is a widget that displays a textual string. A message -widget has three special features. First, it breaks up -its string into lines in order to produce a given aspect ratio -for the window. The line breaks are chosen at word boundaries -wherever possible (if not even a single word would fit on a -line, then the word will be split across lines). Newline characters -in the string will force line breaks; they can be used, for example, -to leave blank lines in the display. - -The second feature of a message widget is justification. The text -may be displayed left-justified (each line starts at the left side of -the window), centered on a line-by-line basis, or right-justified -(each line ends at the right side of the window). - -The third feature of a message widget is that it handles control -characters and non-printing characters specially. Tab characters -are replaced with enough blank space to line up on the next -8-character boundary. Newlines cause line breaks. Other control -characters (ASCII code less than 0x20) and characters not defined -in the font are displayed as a four-character sequence B<\x>I<hh> where -I<hh> is the two-digit hexadecimal number corresponding to -the character. In the unusual case where the font doesn't contain -all of the characters in ``0123456789abcdef\x'' then control -characters and undefined characters are not displayed at all. - -=head1 WIDGET METHODS - -The B<Message> method creates a widget object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. -The widget also inherits all the methods provided by the generic -L<Tk::Widget|Tk::Widget> class. - -=head1 DEFAULT BINDINGS - -When a new message is created, it has no default event bindings: -messages are intended for output purposes only. - -=head1 BUGS - -Tabs don't work very well with text that is centered or right-justified. -The most common result is that the line is justified wrong. - -=head1 KEYWORDS - -message, widget - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/MsgBox.pod b/Master/tlpkg/tlperl/lib/Tk/MsgBox.pod deleted file mode 100644 index 6f5536cf89c..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/MsgBox.pod +++ /dev/null @@ -1,83 +0,0 @@ - -=head1 NAME - -Tk::MsgBox - create and manipulate a message dialog - -=for pm Tk/MsgBox.pm - -=for category Popups and Dialogs - -=head1 SYNOPSIS - - use Tk::MsgBox - ... - $d = $top->MsgBox(-title => "Title", -type => "okcancel"); - ... - $button = $d->Show; - -=head1 DESCRIPTION - -B<MsgBox> is a simple dialog with predefined buttons. - -=head1 OPTIONS - -The options recognized by B<MsgBox> are as follows: - -=over 4 - -=item B<-icon> - -Specify the icon of the MsgBox. Valid values are B<error>, B<info>, -B<question>, or B<warning>. - -=item B<-type> - -Specify the type of the MsgBox. Valid values are B<abortretryignore>, -B<ok>, B<okcancel>, B<retrycancel>, B<yesno>, or B<yesnocancel>. The -type determines the buttons to be shown. - -=item B<-default> - -Specify the default button. This must be one of B<abort>, B<retry>, -B<ignore>, B<ok>, B<cancel>, B<yes>, or B<no>, depending on the type -of the MsgBox previously specified. - -=item B<-detail> - -Specify text for the detail region of the MsgBox. - -=item B<-message> - -Specify the message text of the MsgBox. - -=item B<-title> - -Specify the title of the MsgBox. - -=back - -=head1 METHODS - -B<MsgBox> supports only one method as of now: - -=over 4 - -=item B<Show()> - -Displays the MsgBox until the user invokes one of the buttons. Returns -the name of the button invoked. - -=back - -=head1 AUTHOR - -Translated from Tcl/Tk by B<Slaven Rezic> srezic@cpan.org - -This code is distributed under the same terms as Perl. - -=head1 SEE ALSO - -L<Tk::messageBox>, L<Tk::DialogBox>, L<Tk::Dialog>. - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Mwm.pod b/Master/tlpkg/tlperl/lib/Tk/Mwm.pod deleted file mode 100644 index e9c09cd0358..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Mwm.pod +++ /dev/null @@ -1,109 +0,0 @@ - -=head1 NAME - -Tk::Mwm - Communicate with the Motif(tm) window manager. - -=for category Tix Extensions - -=head1 SYNOPSIS - -S< >B<use Tk::Mwm;> - -S< >I<$toplevel>-E<gt>B<mwm>I<Option>?(I<args>)? - -S< >I<$toplevel>-E<gt>B<mwm>(I<option> ?,I<args>?) - -=head1 DESCRIPTION - -Interface to special extentions supported by mwm. - -=head1 METHODS - -=over 4 - -=item I<$toplevel>-E<gt>B<mwmDecoration>?(?option??=E<gt>value? ?,...?)? - -When no options are given, this method returns the values of all the -decorations options for the toplevel window with the I<$toplevel>. -When only one option is given without specifying the value, the -current value of that option is returned. -When more than one "option-value" pairs are passed to this method, -the specified values will be assigned to the corresponding options. As -a result, the appearance of the Motif decorations around the toplevel -window will be changed. -Possible options are: B<-border>, B<-menu>, B<-maximize>, -B<-minimize>, B<-resizeh> and B<-title>. The value must be a -Boolean value. The values returned by this command are undefined when -the window is not managed by mwm. - -=item I<$toplevel>-E<gt>B<mwmIsmwmrunning> - -This returns value is true if mwm is running on the screen where the specified -window is located, false otherwise. - -=item I<$toplevel>-E<gt>B<mwmProtocol> - -When no additional options are given, this method returns all -protocols associated with this toplevel window. - -=item I<$toplevel>-E<gt>B<mwmProtocol>(B<activate> =E<gt> I<protocol_name>) - -Activate the mwm protocol message in mwm's menu. - -=item I<$toplevel>-E<gt>B<MwmProtocol>(B<add> =E<gt> I<protocol_name>, I<menu_message>) - -Add a new mwm protocol message for this toplevel window. The -message is identified by the string name specified in -I<protocol_name>. A menu item will be added into mwm's menu as -specified by I<menu_message>. Once a new mwm protocol message is -added to a toplevel, it can be caught by the TK B<protocol> -method. Here is an example: - -S< >I<$toplevel>-E<gt>B<mwmProtocol>(B<'add'> =E<gt> 'MY_PRINT_HELLO', '"Print Hello" _H CtrlE<lt>KeyE<gt>H'); - -S< >I<$toplevel>-E<gt>B<protocol>(B<'MY_PRINT_HELLO'> =E<gt> sub {print "Hello"}); - -=item I<$toplevel>-E<gt>B<mwmProtocol>(B<'deactivate'> =E<gt> I<protocol_name>) - -Deactivate the mwm protocol message in mwm's menu. - -=item I<$toplevel>-E<gt>B<mwmProtocol>(B<'delete'> =E<gt> I<protocol_name>) - -Delete the mwm protocol message from mwm's menu. Please note that the -window manager protocol handler associated with this protocol (by the -B<protocol> method) is not deleted automatically. You have to -delete the protocol handle explicitly. E.g.: - -S< >I<$mw>-E<gt>B<mwmProtocol>(B<'delete'> =E<gt> 'MY_PRINT_HELLO'); - -S< >I<$mw>-E<gt>B<protocol>(B<'MY_PRINT_HELLO'> =E<gt> ''); - -=back - -=head1 BUGS - -This is a Tix extension which perl/Tk has adopted. It has not been -tested as perl/Tk's author has not got round to installing a Motif Window -Manager. - -On some versions of mwm, the B<-border> will not disappear unless -B<-resizeh> is turned off. Also, the B<-title> will not disappear -unless all of B<-title>, B<-menu>, B<-maximize> and -B<-minimize> are turned off. - -=head1 SEE ALSO - -L<Tk::Wm|Tk::Wm> -L<Tk::tixWm|Tk::tixWm> -L<Tk::Toplevel|Tk::Toplevel> - -=head1 KEYWORDS - -window manager, mwm, TIX - -=head1 AUTHOR - -Ioi Kim Lam - ioi@graphics.cis.upenn.edu - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/NoteBook.pod b/Master/tlpkg/tlperl/lib/Tk/NoteBook.pod deleted file mode 100644 index 2cc84bb3fad..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/NoteBook.pod +++ /dev/null @@ -1,235 +0,0 @@ - -=head1 NAME - -Tk::NoteBook - display several windows in limited space with notebook metaphor. - -=for pm Tixish/NoteBook.pm - -=for category Tix Extensions - -=head1 SYNOPSIS - - use Tk::NoteBook; - ... - $w = $frame->NoteBook(); - $page1 = $w->add("page1", options); - $page2 = $w->add("page2", options); - ... - $page2 = $w->add("page2", options); - -=head1 DESCRIPTION - -The NoteBook widget provides a notebook metaphor to display several -windows in limited space. The notebook is divided into a stack of pages -of which only one is displayed at any time. The other pages can be -selected by means of choosing the visual "tabs" at the top of the -widget. Additionally, the <Tab> key may be used to traverse the pages. -If B<-underline> is used, Alt- bindings will also work. - -The widget takes all the options that a Frame does. In addition, -it supports the following options: - -=over 4 - -=item B<-dynamicgeometry> - -If set to false (default and recommended), the size of the NoteBook -will match the size of the largest page. Otherwise the size will -match the size of the current page causing the NoteBook to change -size when different pages of different sizes are selected. - -=item B<-ipadx> - -The amount of internal horizontal padding around the pages. - -=item B<-ipady> - -The amount of internal vertical padding around the pages. - -=item B<-backpagecolor> - -The background color of the tabs and back page. - -=item B<-disabledforeground> - -XXX - -=item B<-focuscolor> - -The color of the focus border around the tabs. - -=item B<-font> - -The font of the tab labels. - -=item B<-inactivebackground> - -XXX - -=item B<-tabpadx> - -Horizonzal padding around the tab label. - -=item B<-tabpady> - -Vertical padding around the tab label. - -=back - -=head1 METHODS - -The following methods may be used with a NoteBook object in addition -to standard methods. - -=over 4 - -=item B<add(>I<pageName>, I<options>B<)> - -Adds a page with name I<pageName> to the notebook. Returns an object -of type B<Frame>. The recognized I<options> are: - -=over 4 - -=item B<-anchor> - -Specifies how the information in a tab is to be displayed. Must be -one of B<n>, B<ne>, B<e>, B<se>, B<s>, B<sw>, B<w>, B<nw> or -B<center>. - -=item B<-bitmap> - -Specifies a bitmap to display on the tab of this page. The bitmap -is displayed only if none of the B<-label> or B<-image> options -are specified. - -=item B<-image> - -Specifies an image to display on the tab of this page. The image -is displayed only if the B<-label> option is not specified. - -=item B<-label> - -Specifies the text string to display on the tab of this page. - -=item B<-justify> - -When there are multiple lines of text displayed in a tab, this -option determines the justification of the lines. - -=item B<-createcmd> - -Specifies a L<callback|Tk::callbacks> to be called the first time the page is -shown on the screen. This option can be used to delay the creation -of the contents of a page until necessary. It can be useful in -situations where there are a large number of pages in a NoteBook -widget; with B<-createcmd> you do not have to make the user wait -until all pages are constructed before displaying the first page. - -=item B<-raisecmd> - -Specifies a L<callback|Tk::callbacks> to be called whenever this page is raised -by the user. - -=item B<-state> - -Specifies whether this page can be raised by the user. Must be -either B<normal> or B<disabled>. - -=item B<-underline> - -Specifies the integer index of a character to underline in the -tab. This option is used by the default bindings to implement -keyboard traversal for menu buttons and menu entries. 0 -corresponds to the first character of text displayed on the -widget, 1 to the next character and so on. - -=item B<-wraplength> - -This option specifies the maximum line length of the label string -on this tab. If the line length of the label string exceeds this -length, then it is wrapped onto the next line so that no line is -longer than the specified length. The value may be specified in -any standard forms for screen distances. If this value is less -than or equal to 0, then no wrapping is done: lines will break -only at newline characters in the text. - -=back - -=item B<delete(>I<pageName>B<)> - -Deletes the page identified by I<pageName>. - -=item B<pagecget(>I<pageName>, I<-option>B<)> - -Returns the current value of the configuration option given by -I<-option> in the page given by I<pageName>. I<Option> may have any of -the values accepted in the B<add> method. - -=item B<pageconfigure(>I<pageName>, I<options>B<)> - -Like configure for the page indicated by I<pageName>. I<Options> may -be any of the options accepted by the B<add> method. - -=item B<pages> - -Returns a list consisting of the names of all currently defined -pages, i.e., those created with the B<add> method. - -=item B<page_widget(>I<pageName>B<)> - -Returns the page with name I<pageName>. - -=item B<raise(>I<pageName>B<)> - -Raise the page identified by I<pageName>. - -=item B<raised()> - -Returns the name of the currently raised page. - -=item B<geometryinfo> - -Return the dimensions of the tab area. - -=item B<identify(>I<x>,I<y>B<)> - -Identify the tab's page name under the specified coordinates. Return -an empty string if there's no tab. - -=item B<info(E<quot>pagesE<quot>)> - -Return a list of all pages. - -=item B<info(E<quot>focusE<quot>)> - -Return the page name of the tab with the current focus. - -=item B<info(E<quot>focusnextE<quot>)> - -Return the page name of the tab which would receive the next focus. - -=item B<info(E<quot>focusprevE<quot>)> - -Return the page name of the tab which had the previous focus. - -=item B<info(E<quot>activeE<quot>)> - -Return the page name of the active tab. - -=back - -=head1 BUGS - -The options C<-width> and C<-height> do not work. - -=head1 AUTHORS - -B<Rajappa Iyer> <rsi@earthling.net> -Nick Ing-Simmons <nick@ni-s.u-net.com> - -This code and documentation was derived from NoteBook.tcl in -Tix4.0 written by Ioi Lam. It may be distributed under the same -conditions as Perl itself. - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Optionmenu.pod b/Master/tlpkg/tlperl/lib/Tk/Optionmenu.pod deleted file mode 100644 index f5e514c63b3..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Optionmenu.pod +++ /dev/null @@ -1,100 +0,0 @@ - -=head1 NAME - -Tk::Optionmenu - Let the user select one of some predefined options values - -=for pm Tk/Optionmenu.pm - -=for category Tk Widget Classes - -=head1 SYNOPSIS - - use Tk::Optionmenu; - - $opt = $w->Optionmenu( - -options => REFERENCE_to_OPTIONLIST, - -command => CALLBACK, - -variable => SCALAR_REF, - ); - - $opt->addOptions( OPTIONLIST ); - - # OPTION LIST is - # a) $val1, $val2, $val3,... - # b) [ $lab1=>$val1], [$lab2=>val2], ... ] - # c) combination of a) and b), e.g., - # val1, [$lab2=>val2], val3, val4, [...], ... - -=head1 DESCRIPTION - -The B<Optionmenu> widget allows the user chose between a given set -of options. - -If the user should be able to change the available option have a look -at L<Tk::BrowseEntry>. - -=head1 OPTIONS - -=over 4 - -=item -options - -(Re)sets the list of options presented. - -=item -command - -Defines the L<callback|Tk::callbacks> that is invokes when a new option -is selected. - -=item -variable - -Reference to a scalar that contains the current value of the -selected option. - -=item -textvariable - -Reference to a scalar that contains the text label of the current value of the -selected option. - -=back - -=head1 METHODS - -=over 4 - -=item addOptions - -Adds OPTION_LIST to the already available options. - -=back - -=head1 EXAMPLE - - use Tk; - my $mw = MainWindow->new(); - - my ($var, $tvar); - my $opt = $mw->Optionmenu( - -options => [[jan=>1], [feb=>2], [mar=>3], [apr=>4]], - -command => sub { print "got: ", shift, "\n" }, - -variable => \$var, - -textvariable => \$tvar - )->pack; - - $opt->addOptions([may=>5],[jun=>6],[jul=>7],[aug=>8]); - - my $f = $mw->Frame(-relief=>'groove', -borderwidth => 2)->pack; - $f->Label(-textvariable=>\$tvar)->pack(-side => 'left'); - $f->Label(-text => " -> ")->pack(-side => 'left'); - $f->Label(-textvariable=>\$var)->pack(-side => 'left'); - - $mw->Button(-text=>'Exit', -command=>sub{$mw->destroy})->pack; - - MainLoop; - -=head1 SEE ALSO - -L<Tk::Menubutton>, L<Tk::BrowseEntry> - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Panedwindow.pod b/Master/tlpkg/tlperl/lib/Tk/Panedwindow.pod deleted file mode 100644 index 673938d55e5..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Panedwindow.pod +++ /dev/null @@ -1,326 +0,0 @@ -# Copyright (c) 1992 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# RCS: @(#) $Id: panedwindow.n,v 1.2.2.1 2003/07/17 20:49:00 dkf Exp $ - -=head1 NAME - -Tk::Panedwindow - Create and manipulate Panedwindow widgets - -=for category Tk Generic Methods - -=head1 SYNOPSIS - -I<$panedwindow> = I<$parent>-E<gt>B<Panedwindow>(?I<options>?); - - -background -height -width - -borderwidth -orient - -cursor -relief - -=head1 WIDGET-SPECIFIC OPTIONS - -=over 4 - -=item Option: B<-handlepad> - -=item Name: B<handlePad> - -=item Class: B<HandlePad> - -When sash handles are drawn, specifies the distance from the top or -left end of the sash (depending on the orientation of the widget) at -which to draw the handle. May be any value accepted by B<Tk_GetPixels>. - -=item Option: B<-handlesize> - -=item Name: B<handleSize> - -=item Class: B<HandleSize> - -Specifies the side length of a sash handle. Handles are always -drawn as squares. May be any value accepted by B<Tk_GetPixels>. - -=item Option: B<-opaqueresize> - -=item Name: B<opaqueResize> - -=item Class: B<OpaqueResize> - -Specifies whether panes should be resized as a sash is moved (true), -or if resizing should be deferred until the sash is placed (false). - -=item Option: B<-sashcursor> - -=item Name: B<sashCursor> - -=item Class: B<SashCursor> - -Mouse cursor to use when over a sash. If null, -B<sb_h_double_arrow> will be used for horizontal Panedwindows, and -B<sb_v_double_arrow> will be used for vertical Panedwindows. - -=item Option: B<-sashpad> - -=item Name: B<sashPad> - -=item Class: B<SashPad> - -Specifies the amount of padding to leave of each side of a sash. May -be any value accepted by B<Tk_GetPixels>. - -=item Option: B<-sashrelief> - -=item Name: B<sashRelief> - -=item Class: B<SashRelief> - -Relief to use when drawing a sash. May be any of the standard Tk -relief values. - -=item Option: B<-sashwidth> - -=item Name: B<sashWidth> - -=item Class: B<SashWidth> - -Specifies the width of each sash. May be any value accepted by -B<Tk_GetPixels>. - -=item Option: B<-showhandle> - -=item Name: B<showHandle> - -=item Class: B<ShowHandle> - -Specifies whether sash handles should be shown. May be any valid -boolean value. - -=back - -=head1 DESCRIPTION - -The B<Panedwindow> method creates a new window (given by the -$panedwindow argument) and makes it into a Panedwindow widget. -Additional options, described above, may be specified on the command -line or in the option database to configure aspects of the Panedwindow -such as its default background color and relief. - -A Panedwindow widget contains any number of panes, arranged -horizontally or vertically, according to the value of the -B<-orient> option. Each pane contains one widget, and each pair of -panes is separated by a moveable (via mouse movements) sash. Moving a -sash causes the widgets on either side of the sash to be resized. - -=head1 WIDGET METHODS - -The B<Panedwindow> method -may be used to invoke various operations on the widget. It has the -following general form: - - $widget->method(?arg arg ...?); - -The following -commands are possible for Panedwindow widgets: - -=over 4 - -=item I<$widget>-E<gt>B<add>(?window ...? ?option value ...?); - -Add one or more windows to the Panedwindow, each in a separate pane. -The arguments consist of the names of one or more windows -followed by pairs of arguments that specify how to manage the windows. -I<Option> may have any of the values accepted by the -B<configure> subcommand. - -=item I<$widget>-E<gt>B<cget>(I<option>); - -Returns the current value of the configuration option given by -I<option>. I<Option> may have any of the values accepted by the -B<Panedwindow> command. - -=item I<$widget>-E<gt>B<configure>(I<?option?, ?value, option, value, ...?>); - -Query or modify the configuration options of the widget. If no -I<option> is specified, returns a list describing all of the -available options for $widget (see L<Tk::configure> for -information on the format of this list). If I<option> is specified -with no I<value>, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no I<option> is specified). If -one or more I<option-value> pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. I<Option> may have -any of the values accepted by the B<Panedwindow> command. - -=item I<$widget>-E<gt>B<forget>(?window ...?); - -Remove the pane containing $widget from the Panedwindow. All -geometry management options for $widget will be forgotten. - -=item I<$widget>-E<gt>B<identify>(I<x, y>); - -Identify the Panedwindow component underneath the point given by -I<x> and I<y>, in window coordinates. If the point is over a -sash or a sash handle, the result is a two element list containing the -index of the sash or handle, and a word indicating whether it is over -a sash or a handle, such as [0, 'sash'] or [2, 'handle']. If the point is -over any other part of the Panedwindow, the result is an empty list. - -=item I<$widget>-E<gt>B<proxy>(I<?args?>); - -This command is used to query and change the position of the sash -proxy, used for rubberband-style pane resizing. It can take any of -the following forms: - -=over 4 - -=item I<$widget>-E<gt>B<proxyCoord>; - -Return a list containing the x and y coordinates of the most recent -proxy location. - -=item I<$widget>-E<gt>B<proxyForget>; - -Remove the proxy from the display. - -=item I<$widget>-E<gt>B<proxyPlace>(I<x, y>); - -Place the proxy at the given I<x> and I<y> coordinates. - -=back - -=item I<$widget>-E<gt>B<sash>(I<?args?>); - -This command is used to query and change the position of sashes in the -Panedwindow. It can take any of the following forms: - -=over 4 - -=item I<$widget>-E<gt>B<sashCoord>(I<index>); - -Return the current x and y coordinate pair for the sash given by -I<index>. I<Index> must be an integer between 0 and 1 less than -the number of panes in the Panedwindow. The coordinates given are -those of the top left corner of the region containing the sash. -I<$widget>-E<gt>B<sashDragto>(I<index, x, y>) -This command computes the difference between the given coordinates and the -coordinates given to the last B<sash coord> command for the given -sash. It then moves that sash the computed difference. The return -value is the empty string. - -=item I<$widget>-E<gt>B<sashMark>(I<index, x, y>); - -Records I<x> and I<y> for the sash given by I<index>; used in -conjunction with later dragto commands to move the sash. - -=item I<$widget>-E<gt>B<sashPlace>(I<index, x, y>); - -Place the sash given by I<index> at the given coordinates. - -=back - -=item $widget I<$widget>-E<gt>B<panecget>(option); - -Query a management option for $widget. I<Option> may be any -value allowed by the B<paneconfigure> subcommand. - -=item $widget I<$widget>-E<gt>B<paneconfigure>(?option? ?value option value ...?); - -Query or modify the management options for $widget. If no -I<option> is specified, returns a list describing all of the -available options for $widget (see L<Tk::configure> for -information on the format of this list). If I<option> is specified -with no I<value>, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no I<option> is specified). If -one or more I<option-value> pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. The following options -are supported: - -=over 4 - -=item B<-after> =E<gt> $widget - -Insert the window after the window specified. $widget should be the -name of a window already managed by $widget. - -=item B<-before> =E<gt> $widget - -Insert the window before the window specified. $widget should be -the name of a window already managed by $widget. - -=item B<-height> =E<gt> I<size> - -Specify a height for the window. The height will be the outer -dimension of the window including its border, if any. If I<size> -is an empty string, or if B<-height> is not specified, then the -height requested internally by the window will be used initially; the -height may later be adjusted by the movement of sashes in the -Panedwindow. I<Size> may be any value accepted by B<Tk_GetPixels>. - -=item B<-minsize> =E<gt> I<n> - -Specifies that the size of the window cannot be made less than -I<n>. This constraint only affects the size of the widget in the -paned dimension -- the x dimension for horizontal Panedwindows, the y -dimension for vertical Panedwindows. May be any value accepted by -B<Tk_GetPixels>. - -=item B<-padx> =E<gt> I<n> - -Specifies a non-negative value indicating how much extra space to -leave on each side of the window in the X-direction. The value may -have any of the forms accepted by B<Tk_GetPixels>. - -=item B<-pady> =E<gt> I<n> - -Specifies a non-negative value indicating how much extra space to -leave on each side of the window in the Y-direction. The value may -have any of the forms accepted by B<Tk_GetPixels>. - -=item B<-sticky> =E<gt> I<style> - -If a window's pane is larger than the requested dimensions of the -window, this option may be used to position (or stretch) the window -within its pane. I<Style> is a string that contains zero or more -of the characters B<n>, B<s>, B<e> or B<w>. The string -can optionally contains spaces or commas, but they are ignored. Each -letter refers to a side (north, south, east, or west) that the window -will "stick" to. If both B<n> and B<s> (or B<e> and B<w>) -are specified, the window will be stretched to fill the entire height -(or width) of its cavity. - -=item B<-width> =E<gt> I<size> - -Specify a width for the window. The width will be the outer -dimension of the window including its border, if any. If I<size> -is an empty string, or if B<-width> is not specified, then the -width requested internally by the window will be used initially; the -width may later be adjusted by the movement of sashes in the -Panedwindow. I<Size> may be any value accepted by B<Tk_GetPixels>. - -=back - -=item I<$widget>-E<gt>B<panes>; - -Returns an ordered list of the widgets managed by $widget. - -=back - -=head1 RESIZING PANES - -A pane is resized by grabbing the sash (or sash handle if present) and -dragging with the mouse. This is accomplished via mouse motion -bindings on the widget. When a sash is moved, the sizes of the panes -on each side of the sash, and thus the widgets in those panes, are -adjusted. - -When a pane is resized from outside (eg, it is packed to expand and -fill, and the containing toplevel is resized), space is added to the final -(rightmost or bottommost) pane in the window. - -=head1 KEYWORDS - -Panedwindow, widget, geometry management diff --git a/Master/tlpkg/tlperl/lib/Tk/Photo.pod b/Master/tlpkg/tlperl/lib/Tk/Photo.pod deleted file mode 100644 index 02a691d6261..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Photo.pod +++ /dev/null @@ -1,475 +0,0 @@ -# Copyright (c) 1994 The Australian National University -# Copyright (c) 1994-1997 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# Author: Paul Mackerras (paulus@cs.anu.edu.au), -# Department of Computer Science, -# Australian National University. -# RCS: @(#) $Id: photo.n,v 1.2 1998/09/14 18:22:59 stanton Exp $ -# - -=head1 NAME - -Tk::Photo - Full-color images - -=for category Tk Image Classes - -=head1 SYNOPSIS - -S< >I<$widget>-E<gt>B<Photo>(?I<name>??, I<options>?) - -=head1 DESCRIPTION - -A photo is an L<image|Tk::Image> whose pixels can display any color or be -transparent. A photo image is stored internally in full color (32 -bits per pixel), and is displayed using dithering if necessary. Image -data for a photo image can be obtained from a file or a string, or it -can be supplied from -C code through a procedural interface. At present, only GIF, -XBM, XPM, BMP, JPEG, PNG and PPM/PGM -formats are supported, but an interface exists to allow additional -image file formats to be added easily. A photo image is transparent -in regions where no image data has been supplied -or where it has been set transparent by the B<transparencySet> -subcommand. - -=head1 CREATING PHOTOS - -Photos are created using the B<Photo> method. -B<Photo> supports the following I<options>: - -=over 4 - -=item B<-data> =E<gt> I<string> - -Specifies the contents of the image as a string. -The string can -contain base64 encoded data or binary data. -The format of the -string must be one of those for which there is an image file format -handler that will accept string data. If both the B<-data> -and B<-file> options are specified, the B<-file> option takes -precedence. - -=item B<-format> =E<gt> I<format-name> - -Specifies the name of the file format for the data specified with the -B<-data> or B<-file> option. - -=item B<-file> =E<gt> I<name> - -I<name> gives the name of a file that is to be read to supply data -for the photo image. The file format must be one of those for which -there is an image file format handler that can read data. - -=item B<-gamma> =E<gt> I<value> - -Specifies that the colors allocated for displaying this image in a -window should be corrected for a non-linear display with the specified -gamma exponent value. (The intensity produced by most -CRT displays is a power function of the input value, to a good -approximation; gamma is the exponent and is typically around 2). -The value specified must be greater than zero. The default -value is one (no correction). In general, values greater than one -will make the image lighter, and values less than one will make it -darker. - -=item B<-height> =E<gt> I<number> - -Specifies the height of the image, in pixels. This option is useful -primarily in situations where the user wishes to build up the contents -of the image piece by piece. A value of zero (the default) allows the -image to expand or shrink vertically to fit the data stored in it. - -=item B<-palette> =E<gt> I<palette-spec> - -Specifies the resolution of the color cube to be allocated for -displaying this image, and thus the number of colors used from the -colormaps of the windows where it is displayed. The -I<palette-spec> string may be either a single decimal number, -specifying the number of shades of gray to use, or three decimal -numbers separated by slashes (/), specifying the number of shades of -red, green and blue to use, respectively. If the first form (a single -number) is used, the image will be displayed in monochrome (i.e., -grayscale). - -=item B<-width> =E<gt> I<number> - -Specifies the width of the image, in pixels. This option is useful -primarily in situations where the user wishes to build up the contents -of the image piece by piece. A value of zero (the default) allows the -image to expand or shrink horizontally to fit the data stored in it. - -=back - -=head1 IMAGE METHODS - -When a photo image is created, Tk also creates a new object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. - -Those options that write data to the image generally expand the size -of the image, if necessary, to accommodate the data written to the -image, unless the user has specified non-zero values for the -B<-width> and/or B<-height> configuration options, in which -case the width and/or height, respectively, of the image will not be -changed. - -The following addition methods are available for photo images: - -=over 4 - -=item I<$image>-E<gt>B<blank> - -Blank the image; that is, set the entire image to have no data, so it -will be displayed as transparent, and the background of whatever -window it is displayed in will show through. - -=item I<$image>-E<gt>B<copy>(I<sourceImage> ?,I<option value(s) ...>?) - -Copies a region from the image called I<$sourceImage> (which must -be a photo image) to the image called I<$image>, possibly with -pixel zooming and/or subsampling. If no options are specified, this -method copies the whole of I<$sourceImage> into I<$image>, -starting at coordinates (0,0) in I<$image>. The following -options may be specified: - -=over 8 - -=item B<-from> =E<gt> I<x1, y1, ? ,x2, y2?> - -Specifies a rectangular sub-region of the source image to be copied. -(I<x1,y1>) and (I<x2,y2>) specify diagonally opposite corners of -the rectangle. If I<x2> and I<y2> are not specified, the -default value is the bottom-right corner of the source image. The -pixels copied will include the left and top edges of the specified -rectangle but not the bottom or right edges. If the B<-from> -option is not given, the default is the whole source image. - -=item B<-to> =E<gt> I<x1, y1, ?, x2, y2?> - -Specifies a rectangular sub-region of the destination image to be -affected. (I<x1,y1>) and (I<x2,y2>) specify diagonally opposite -corners of the rectangle. If I<x2> and I<y2> are not specified, -the default value is (I<x1,y1>) plus the size of the source -region (after subsampling and zooming, if specified). If I<x2> and -I<y2> are specified, the source region will be replicated if -necessary to fill the destination region in a tiled fashion. - -=item B<-shrink> - -Specifies that the size of the destination image should be reduced, if -necessary, so that the region being copied into is at the bottom-right -corner of the image. This option will not affect the width or height -of the image if the user has specified a non-zero value for the -B<-width> or B<-height> configuration option, respectively. - -=item B<-zoom> =E<gt> I<x, y> - -Specifies that the source region should be magnified by a factor of -I<x> in the X direction and I<y> in the Y direction. If I<y> -is not given, the default value is the same as I<x>. With this -option, each pixel in the source image will be expanded into a block -of I<x> x I<y> pixels in the destination image, all the same -color. I<x> and I<y> must be greater than 0. - -=item B<-subsample> =E<gt> I<x, y> - -Specifies that the source image should be reduced in size by using -only every I<x>th pixel in the X direction and I<y>th pixel in -the Y direction. Negative values will cause the image to be flipped -about the Y or X axes, respectively. If I<y> is not given, the -default value is the same as I<x>. - -=item B<-compositingrule> =E<gt> I<rule> - -Specifies how transparent pixels in the source image are combined with -the destination image. When a compositing rule of I<overlay> is -set, the old contents of the destination image are visible, as if the -source image were printed on a piece of transparent film and placed -over the top of the destination. When a compositing rule of I<set> -is set, the old contents of the destination image are discarded and -the source image is used as-is. The default compositing rule is -I<overlay>. - -=back - -=item I<$image>-E<gt>B<data>(?I<option value(s), ...>?) - -Returns image data in the form of a string. -The following options may be specified: - -=over 8 - -=item B<-background> =E<gt> I< color> - -If the color is specified, the data will not contain any transparency -information. In all transparent pixels the color will be replaced by -the specified color. - -=item B<-format> =E<gt> I<format-name> - -Specifies the name of the image file format handler to be used. -Specifically, this method searches -for the first handler whose name matches a initial substring of -I<format-name> and which has the capability to read this image data. -If this option is not given, this method uses the first -handler that has the capability to read the image data. - -=item B<-from> =E<gt> I<x1, y1, ?, x2, y2?> - -Specifies a rectangular region of I<$image> to be -returned. If only I<x1> and I<y1> are specified, the region -extends from I<(x1,y1)> to the bottom-right corner of -I<$image>. If all four coordinates are given, they specify -diagonally opposite corners of the rectangular region, including x1,y1 -and excluding x2,y2. The default, -if this option is not given, is the whole image. - -=item B<-grayscale> - -If this options is specified, the data will not contain color -information. All pixel data will be transformed into grayscale. - -=back - -=item I<$image>-E<gt>B<get>(I<x, y>) - -Returns the color of the pixel at coordinates (I<x>,I<y>) in the -image as a list of three integers between 0 and 255, representing the -red, green and blue components respectively. - -=item I<$image>-E<gt>B<put>(I<data> ?,B<-format>=E<gt>I<format-name>? ?,B<-to>=E<gt>I< x1 y1 ?x2 y2?>?) - -Sets pixels in I<$image> to the data specified in I<data>. -This command first searches the list of image file format handlers for -a handler that can interpret the data in I<data>, and then reads -the image encoded within into I<$image> (the destination image). -If I<data> does not match any known format, an attempt to interpret -it as a (top-to-bottom) list of scan-lines is made, with each -scan-line being a (left-to-right) list of pixel colors (see -B<Tk_GetColor> for a description of valid colors.) Every scan-line -must be of the same length. Note that when I<data> is a single -color name, you are instructing Tk to fill a rectangular region with -that color. The following options may be specified: - -=over 4 - -=item B<-format> =E<gt>I<format-name> - -Specifies the format of the image data in I<data>. -Specifically, only image file format handlers whose names begin with -I<format-name> will be used while searching for an image data -format handler to read the data. - -=item B<-to> =E<gt>I<x, y> ?I<, x2, y2>? - -Specifies the coordinates of the top-left corner (I<x1>,I<y1>) -of the region of I<$image> into which data from I<filename> -are to be read. The default is (0,0). If I<x2>,I<y2> is given -and I<data> is not large enough to cover the rectangle specified by -this option, the image data extracted will be tiled so it covers the -entire destination rectangle. Note that if I<data> specifies a -single color value, then a region extending to the bottom-right corner -represented by (I<x2>,I<y2>) will be filled with that color. - -=back - -=item I<$image>-E<gt>B<read>(I<filename> ?,I<option value(s), ...>?) - -Reads image data from the file named I<filename> into the image. -This method first searches the list of -image file format handlers for a handler that can interpret the data -in I<filename>, and then reads the image in I<filename> into -I<$image> (the destination image). The following options may be -specified: - -=over 8 - -=item B<-format> =E<gt> I<format-name> - -Specifies the format of the image data in I<filename>. -Specifically, only image file format handlers whose names begin with -I<format-name> will be used while searching for an image data -format handler to read the data. - -=item B<-from> =E<gt> I<x1, y1, x2, y2> - -Specifies a rectangular sub-region of the image file data to be copied -to the destination image. If only I<x1> and I<y1> are -specified, the region extends from (I<x1,y1>) to the bottom-right -corner of the image in the image file. If all four coordinates are -specified, they specify diagonally opposite corners or the region. -The default, if this option is not specified, is the whole of the -image in the image file. - -=item B<-shrink> - -If this option is specified, the size of I<$image> will be reduced, if -necessary, so that the region into which the image file data are read -is at the bottom-right corner of the I<$image>. This option -will not affect the width or height of the image if the user has -specified a non-zero value for the B<-width> or B<-height> -configuration option, respectively. - -=item B<-to> =E<gt> I<x, y> - -Specifies the coordinates of the top-left corner of the region of -I<$image> into which data from I<filename> are to be read. -The default is (0,0). - -=back - -=item I<$image>-E<gt>B<redither> - -The dithering algorithm used in displaying photo images propagates -quantization errors from one pixel to its neighbors. -If the image data for I<$image> is supplied in pieces, the -dithered image may not be exactly correct. Normally the difference is -not noticeable, but if it is a problem, this method can be used to -recalculate the dithered image in each window where the image is -displayed. - -=item I<$image>-E<gt>B<transparency>(I<subcommand, ?arg, arg ...?>); - -Allows examination and manipulation of the transparency information in -the photo image. Several subcommands are available: - -=over 4 - -=item I<$image>-E<gt>B<transparencyGet>(I<x, y>); - -Returns a boolean indicating if the pixel at (I<x>,I<y>) is -transparent. - -=item I<$image>-E<gt>B<transparencySet>(I<x, y, boolean>); - -Makes the pixel at (I<x>,I<y>) transparent if I<boolean> is -true, and makes that pixel opaque otherwise. - -=back - -=item I<$image>-E<gt>B<write>(I<filename> ?,I<option value(s), ...>?) - -Writes image data from I<$image> to a file named I<filename>. -The following options may be specified: - -=over 8 - -=item B<-background> =E<gt> I< color> - -If the color is specified, the data will not contain any transparency -information. In all transparent pixels the color will be replaced by -the specified color. - -=item B<-format> =E<gt> I<format-name> - -Specifies the name of the image file format handler to be used to -write the data to the file. Specifically, this subcommand searches -for the first handler whose name matches a initial substring of -I<format-name> and which has the capability to write an image -file. If this option is not given, this subcommand uses the first -handler that has the capability to write an image file. - -=item B<-from> =E<gt> I<x1, y1, ?, x2, y2?> - -Specifies a rectangular region of I<$image> to be written to the -image file. If only I<x1> and I<y1> are specified, the region -extends from I<(x1,y1)> to the bottom-right corner of -I<$image>. If all four coordinates are given, they specify -diagonally opposite corners of the rectangular region. The default, -if this option is not given, is the whole image. - - -=item B<-grayscale> - -If this options is specified, the data will not contain color -information. All pixel data will be transformed into grayscale. - -=back - -=back - -=head1 IMAGE FORMATS - -The photo image code is structured to allow handlers for additional -image file formats to be added easily. The photo image code maintains -a list of these handlers. Handlers are added to the list by -registering them with a call to B<Tk_CreatePhotoImageFormat>. The -standard Tk distribution comes with handlers for XBM, XPM, BMP, JPEG, -PNG and PPM/PGM formats, which are automatically registered on -initialization. - -When reading an image file or processing -string data specified with the B<-data> configuration option, the -photo image code invokes each handler in turn until one is -found that claims to be able to read the data in the file or string. -Usually this will find the correct handler, but if it doesn't, the -user may give a format name with the B<-format> option to specify -which handler to use. In fact the photo image code will try those -handlers whose names begin with the string specified for the -B<-format> option (the comparison is case-insensitive). For -example, if the user specifies B<-format> B<=E<gt>> B<gif>, then a handler -named GIF87 or GIF89 may be invoked, but a handler -named JPEG may not (assuming that such handlers had been -registered). - -When writing image data to a file, the processing of the -B<-format> option is slightly different: the string value given -for the B<-format> option must begin with the complete name of the -requested handler, and may contain additional information following -that, which the handler can use, for example, to specify which variant -to use of the formats supported by the handler. -Note that not all image handlers may support writing transparency data -to a file, even where the target image format does. - -=head1 COLOR ALLOCATION - -When a photo image is displayed in a window, the photo image code -allocates colors to use to display the image and dithers the image, if -necessary, to display a reasonable approximation to the image using -the colors that are available. The colors are allocated as a color -cube, that is, the number of colors allocated is the product of the -number of shades of red, green and blue. - -Normally, the number of -colors allocated is chosen based on the depth of the window. For -example, in an 8-bit PseudoColor window, the photo image code will -attempt to allocate seven shades of red, seven shades of green and -four shades of blue, for a total of 198 colors. In a 1-bit StaticGray -(monochrome) window, it will allocate two colors, black and white. In -a 24-bit DirectColor or TrueColor window, it will allocate 256 shades -each of red, green and blue. Fortunately, because of the way that -pixel values can be combined in DirectColor and TrueColor windows, -this only requires 256 colors to be allocated. If not all of the -colors can be allocated, the photo image code reduces the number of -shades of each primary color and tries again. - -The user can exercise some control over the number of colors that a -photo image uses with the B<-palette> configuration option. If -this option is used, it specifies the maximum number of shades of -each primary color to try to allocate. It can also be used to force -the image to be displayed in shades of gray, even on a color display, -by giving a single number rather than three numbers separated by -slashes. - -=head1 CREDITS - -The photo image type was designed and implemented by Paul Mackerras, -based on his earlier photo widget and some suggestions from -John Ousterhout. - -=head1 SEE ALSO - -L<Tk::Bitmap|Tk::Bitmap> -L<Tk::Image|Tk::Image> -L<Tk::Pixmap|Tk::Pixmap> - -=head1 KEYWORDS - -photo, image, color - -=cut - - diff --git a/Master/tlpkg/tlperl/lib/Tk/Pixmap.pod b/Master/tlpkg/tlperl/lib/Tk/Pixmap.pod deleted file mode 100644 index d0f36b00e65..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Pixmap.pod +++ /dev/null @@ -1,64 +0,0 @@ -# Copyright (c) 1996, Expert Interface Technologies -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# The file man.macros and some of the macros used by this file are -# copyrighted: (c) 1990 The Regents of the University of California. -# (c) 1994-1995 Sun Microsystems, Inc. -# The license terms of the Tcl/Tk distribution are in the file -# license.tcl. - -=head1 NAME - -Tk::Pixmap - Create color images from XPM files. - -=for category Tk Image Classes - -=head1 SYNOPSIS - -S< >I<$widget>-E<gt>B<Pixmap>?(I<name>?,I<options>?)? - -=head1 DESCRIPTION - -XPM is a popular X Window image file format for storing color icons. -The B<Pixmap> image type can be used to create color images using XPM files. - -Pixmaps support the following I<options>: - -=over 4 - -=item B<-data> =E<gt> I<string> - -Specifies the contents of the source pixmap as a string. The string -must adhere to the XPM file format (e.g., as generated by the -B<pixmap(1)> program). If both the B<-data> and B<-file> -options are specified, the B<-data> option takes precedence. -Please note that the XPM file parsing code in the xpm library is -somewhat fragile. The first line of the string must be "B</* XPM> -*/" or otherwise a segmatation fault will be caused. - -=item B<-file> =E<gt> I<name> - -I<name> gives the name of a file whose contents define the source -pixmap. The file must adhere to the XPM file format (e.g., as -generated by the B<pixmap(1)> program). - -=back - -=head1 IMAGE METHODS - -When a pixmap image is created, Tk also creates a new object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. - -=head1 SEE ALSO - -L<Tk::Image|Tk::Image> - -=head1 KEYWORDS - -pixmap, image, tix - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Popup.pod b/Master/tlpkg/tlperl/lib/Tk/Popup.pod deleted file mode 100644 index 8d40a4ed275..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Popup.pod +++ /dev/null @@ -1,89 +0,0 @@ - -=head1 NAME - -Tk::Wm::Popup - popup dialog windows. - -=for pm Tk/Wm.pm - -=for category Tk Toplevel widgets - -=head1 SYNOPSIS - - $dialog->Popup(qw/ - -popover => 'cursor' | $widget | undef, - -overanchor => c | n | ne | e | se | s | sw | w | nw, - -popanchor => c | n | ne | e | se | s | sw | w | nw, - /); - -=head1 DESCRIPTION - -You've probably had occasion to use a Dialog (or DialogBox) -widget. These widgets are derived from a Toplevel (which is a subclass -of Tk::Wm, the window manager) and spend most of their time in a -withdrawn state. It's also common to use Toplevels as containers for -custom built popup windows. Menus, too, are dialogs derived from the -window manager class. For this discussion, we'll use the simple term -I<dialog> to refer any widget that pops up and awaits user -interaction, whether it be a Menu, a special purpose Toplevel, or any -of the dialog-type widgets, including, but not limited to, ColorEditor, -Dialog, DialogBox, ErrorDialog, FileSelect, FBox, getOpenFile and -getSaveFile. - -When it's time to display these dialogs, we call the Perl/Tk -window manager B<Popup> method. B<Popup> accepts three special purpose -options that specify placement information in high-level terms rather -than numerical coordinates. It is B<Popup>'s responsibility to take -our human specifications and turn them into actual screen -coordinates before displaying the dialog. - -We can direct the dialog to appear in two general locations, either -over another window (e.g. the root window (screen) or a particular -widget), or over the cursor. This is called the I<popover -location>. Once we've made this decision we can further refine the -exact placement of the dialog relative to the popover location by -specifying the intersection of two I<anchor points>. The I<popanchor -point> is associated with the dialog and the I<overanchor point> is -associated with the popover location (whether it be a window or the -cursor). The point where the two anchor points coincide is the I<popup -locus>. Anchor points are string values and can be I<c> (for center), -or any of the eight cardinal compass points: I<n>, I<ne>, I<e>, I<se>, -I<s>, I<sw>, I<w> or I<nw>. - -For example, if I<-popover> specifies a widget, I<-popanchor> is I<sw>, -and I<-overanchor> is I<ne>, the the dialog's southwest corner pops up -at the widget's northeast corner. - -=head1 OPTIONS - -The options recognized by B<Popup> are as follows: - -=over 4 - -=item B<-popover> - -Specifies whether the dialog "pops over" a window or the cursor. -It may be the string I<cursor>, a widget reference, or undef for the -root window. - -=item B<-popanchor> - -Specifies the anchor point of the dialog. For instance, if I<e> is -specified, the right side of the dialog is the anchor. - -=item B<-overanchor> - -Specifies where the dialog should anchor relative to the popover -location. For instance, if I<e> is specified the dialog appears over -the right side of the popover location and if it's I<ne> the the -dialog is positioned at the upper-right corner of the popover location. - -=back - -=head1 AUTHOR - -Nick Ing-Simmons, Steve Lidie - -This code is distributed under the same terms as Perl. - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/ROText.pod b/Master/tlpkg/tlperl/lib/Tk/ROText.pod deleted file mode 100644 index b442164ae72..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/ROText.pod +++ /dev/null @@ -1,48 +0,0 @@ - -=head1 NAME - -Tk::ROText - 'readonly' perl/Tk Text widget - -=for pm Tk/ROText.pm - -=for category Derived Widgets - -=head1 SYNOPSIS - - use Tk::ROText; - ... - $ro = $mw->ROText(?options,...?); - -=head1 DESCRIPTION - -This "I<IS A>" text widget with all bindings removed that would alter -the contents of the text widget. The contents can still be modified -via method calls. - -=head2 BINDINGS - -Only read-only bindings from L<Tk::Text> are available in -B<Tk::ROText>. Additionally the following bindings are defined: - -=over - -=item <space> - -Move the cursor forward by one screenful. - -=item <BackSpace> - -Move the cursor backward by one screenful. - -=back - -=head1 KEYWORDS - -widget, text, readonly - -=head1 SEE ALSO - -L<Tk::Text> - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Radiobutton.pod b/Master/tlpkg/tlperl/lib/Tk/Radiobutton.pod deleted file mode 100644 index 82fad4893fd..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Radiobutton.pod +++ /dev/null @@ -1,333 +0,0 @@ -# Copyright (c) 1990-1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::Radiobutton - Create and manipulate Radiobutton widgets - -=for category Tk Widget Classes - -=head1 SYNOPSIS - -I<$radiobutton> = I<$parent>-E<gt>B<Radiobutton>(?I<options>?); - -=head1 STANDARD OPTIONS - -B<-activebackground> -B<-activeforeground> -B<-anchor> -B<-background> -B<-bitmap> -B<-borderwidth> -B<-compound> -B<-cursor> -B<-disabledforeground> -B<-font> -B<-foreground> -B<-highlightbackground> -B<-highlightcolor> -B<-highlightthickness> -B<-image> -B<-justify> -B<-padx> -B<-pady> -B<-relief> -B<-takefocus> -B<-text> -B<-textvariable> -B<-underline> -B<-wraplength> - -See L<Tk::options> for details of the standard options. - -=head1 WIDGET-SPECIFIC OPTIONS - -=over 4 - -=item Name: B<command> - -=item Class: B<Command> - -=item Switch: B<-command> - -Specifies a L<perl/Tk callback|Tk::callbacks> to associate with the button. This command -is typically invoked when mouse button 1 is released over the button -window. The button's global variable (B<-variable> option) will -be updated before the command is invoked. - -=item Name: B<height> - -=item Class: B<Height> - -=item Switch: B<-height> - -Specifies a desired height for the button. -If an image or bitmap is being displayed in the button then the value is in -screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>); -for text it is in lines of text. -If this option isn't specified, the button's desired height is computed -from the size of the image or bitmap or text being displayed in it. - -=item Name: B<indicatorOn> - -=item Class: B<IndicatorOn> - -=item Switch: B<-indicatoron> - -Specifies whether or not the indicator should be drawn. Must be a -proper boolean value. If false, the B<relief> option is -ignored and the widget's relief is always sunken if the widget is -selected and raised otherwise. - -=item Command-Line Name: B<-offrelief> - -=item Database Name: B<offRelief> - -=item Database Class: B<OffRelief> - -Specifies the relief for the checkbutton when the indicator is not -drawn and the checkbutton is off. The default value is B<raised>. By -setting this option to B<flat> and setting -B<-indicatoron false -overrelief raised>, the effect is achieved of -having a flat button -that raises on mouse-over and which is depressed when activated. This -is the behavior typically exhibited by the Bold, Italic, and -Underline checkbuttons on the toolbar of a word-processor, for -example. - -=item Command-Line Name: B<-overrelief> - -=item Database Name: B<overRelief> - -=item Database Class: B<OverRelief> - -Specifies an alternative relief for the button, to be used when -the mouse cursor is over the widget. This option can be used to -make toolbar buttons, by configuring B<-relief flat -overrelief -raised>. If the value of this option is the empty string, then -no alternative relief is used when the mouse cursor is over the -button. The empty string is the default value. - -=item Name: B<selectColor> - -=item Class: B<Background> - -=item Switch: B<-selectcolor> - -Specifies a background color to use when the button is selected. -If B<indicatorOn> is true then the color applies to the indicator. -Under Windows, this color is used as the background for the indicator -regardless of the select state. -If B<indicatorOn> is false, this color is used as the background -for the entire widget, in place of B<background> or B<activeBackground>, -whenever the widget is selected. -If specified as an empty string then no special color is used for -displaying when the widget is selected. - -=item Name: B<selectImage> - -=item Class: B<SelectImage> - -=item Switch: B<-selectimage> - -Specifies an image to display (in place of the B<image> option) -when the radiobutton is selected. -This option is ignored unless the B<image> option has been -specified. - -=item Name: B<state> - -=item Class: B<State> - -=item Switch: B<-state> - -Specifies one of three states for the radiobutton: B<normal>, B<active>, -or B<disabled>. In normal state the radiobutton is displayed using the -B<foreground> and B<background> options. The active state is -typically used when the pointer is over the radiobutton. In active state -the radiobutton is displayed using the B<activeForeground> and -B<activeBackground> options. Disabled state means that the radiobutton -should be insensitive: the default bindings will refuse to activate -the widget and will ignore mouse button presses. -In this state the B<disabledForeground> and -B<background> options determine how the radiobutton is displayed. - -=item Name: B<value> - -=item Class: B<Value> - -=item Switch: B<-value> - -Specifies value to store in the button's associated variable whenever -this button is selected. - -=item Name: B<variable> - -=item Class: B<Variable> - -=item Switch: B<-variable> - -Specifies reference to a variable to set whenever this button is -selected. Changes in this variable also cause the button to select -or deselect itself. Defaults to the value C<\$Tk::selectedButton>. - -=item Name: B<width> - -=item Class: B<Width> - -=item Switch: B<-width> - -Specifies a desired width for the button. -If an image or bitmap is being displayed in the button, the value is in -screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>); -for text it is in characters. -If this option isn't specified, the button's desired width is computed -from the size of the image or bitmap or text being displayed in it. - -=back - -=head1 DESCRIPTION - -The B<Radiobutton> method creates a new window (given by the -$widget argument) and makes it into a radiobutton widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the radiobutton such as its colors, font, -text, and initial relief. The B<radiobutton> command returns its -$widget argument. At the time this command is invoked, -there must not exist a window named $widget, but -$widget's parent must exist. - -A radiobutton is a widget that displays a textual string, bitmap or image -and a diamond or circle called an I<indicator>. -If text is displayed, it must all be in a single font, but it -can occupy multiple lines on the screen (if it contains newlines -or if wrapping occurs because of the B<wrapLength> option) and -one of the characters may optionally be underlined using the -B<underline> option. A radiobutton has -all of the behavior of a simple button: it can display itself in either -of three different ways, according to the B<state> option; -it can be made to appear -raised, sunken, or flat; it can be made to flash; and it invokes -a L<perl/Tk callback|Tk::callbacks> whenever mouse button 1 is clicked over the -check button. - -In addition, radiobuttons can be I<selected>. -If a radiobutton is selected, the indicator is normally -drawn with a selected appearance, and -a Tcl variable associated with the radiobutton is set to a particular -value (normally 1). -Under Unix, the indicator is drawn with a sunken relief and a special -color. Under Windows, the indicator is drawn with a round mark inside. -If the radiobutton is not selected, then the indicator is drawn with a -deselected appearance, and the associated variable is -set to a different value (typically 0). -Under Unix, the indicator is drawn with a raised relief and no special -color. Under Windows, the indicator is drawn without a round mark inside. -Typically, several radiobuttons share a single variable and the -value of the variable indicates which radiobutton is to be selected. -When a radiobutton is selected it sets the value of the variable to -indicate that fact; each radiobutton also monitors the value of -the variable and automatically selects and deselects itself when the -variable's value changes. -By default the variable B<selectedButton> -is used; its contents give the name of the button that is -selected, or the empty string if no button associated with that -variable is selected. -The name of the variable for a radiobutton, -plus the variable to be stored into it, may be modified with options -on the command line or in the option database. -Configuration options may also be used to modify the way the -indicator is displayed (or whether it is displayed at all). -By default a radiobutton is configured to select itself on button clicks. - -=head1 WIDGET METHODS - -The B<Radiobutton> method creates a widget object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. -The widget also inherits all the methods provided by the generic -L<Tk::Widget|Tk::Widget> class. - -The following additional methods are available for radiobutton widgets: - -=over 4 - -=item I<$radiobutton>-E<gt>B<deselect> - -Deselects the radiobutton and sets the associated variable to an -empty string. -If this radiobutton was not currently selected, the command has -no effect. - -=item I<$radiobutton>-E<gt>B<flash> - -Flashes the radiobutton. This is accomplished by redisplaying the radiobutton -several times, alternating between active and normal colors. At -the end of the flash the radiobutton is left in the same normal/active -state as when the command was invoked. -This command is ignored if the radiobutton's state is B<disabled>. - -=item I<$radiobutton>-E<gt>B<invoke> - -Does just what would have happened if the user invoked the radiobutton -with the mouse: selects the button and invokes -its associated Tcl command, if there is one. -The return value is the return value from the Tcl command, or an -empty string if there is no command associated with the radiobutton. -This command is ignored if the radiobutton's state is B<disabled>. - -=item I<$radiobutton>-E<gt>B<select> - -Selects the radiobutton and sets the associated variable to the -value corresponding to this widget. - -=back - -=head1 BINDINGS - -Tk automatically creates class bindings for radiobuttons that give them -the following default behavior: - -=over 4 - -=item [1] - -On Unix systems, a radiobutton activates whenever the mouse passes -over it and deactivates whenever the mouse leaves the radiobutton. On -Mac and Windows systems, when mouse button 1 is pressed over a -radiobutton, the button activates whenever the mouse pointer is inside -the button, and deactivates whenever the mouse pointer leaves the -button. - -=item [2] - -When mouse button 1 is pressed over a radiobutton it is invoked (it -becomes selected and the command associated with the button is -invoked, if there is one). - -=item [3] - -When a radiobutton has the input focus, the space key causes the radiobutton -to be invoked. - -If the radiobutton's state is B<disabled> then none of the above -actions occur: the radiobutton is completely non-responsive. - -The behavior of radiobuttons can be changed by defining new bindings for -individual widgets or by redefining the class bindings. - -=back - -=head1 KEYWORDS - -radiobutton, widget - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Scale.pod b/Master/tlpkg/tlperl/lib/Tk/Scale.pod deleted file mode 100644 index f7de2390bba..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Scale.pod +++ /dev/null @@ -1,356 +0,0 @@ -# Copyright (c) 1990-1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::Scale - Create and manipulate Scale widgets - -=for category Tk Widget Classes - -=head1 SYNOPSIS - -I<$scale> = I<$parent>-E<gt>B<Scale>(?I<options>?); - -=head1 STANDARD OPTIONS - -B<-activebackground> B<-font> B<-highlightthickness> B<-repeatinterval> -B<-background> B<-foreground> B<-orient> B<-takefocus> -B<-borderwidth> B<-highlightbackground> B<-relief> B<-troughcolor> -B<-cursor> B<-highlightcolor> B<-repeatdelay> - -See L<Tk::options> for details of the standard options. - -=head1 WIDGET-SPECIFIC OPTIONS - -=over 4 - -=item Name: B<bigIncrement> - -=item Class: B<BigIncrement> - -=item Switch: B<-bigincrement> - -Some interactions with the scale cause its value to change by -``large'' increments; this option specifies the size of the -large increments. If specified as 0, the large increments default -to 1/10 the range of the scale. - -=item Name: B<command> - -=item Class: B<Command> - -=item Switch: B<-command> - -Specifies the prefix of a L<perl/Tk callback|Tk::callbacks> to invoke whenever the scale's -value is changed via a method. -The actual command consists -of this option followed by a space and a real number indicating the -new value of the scale. - -=item Name: B<digits> - -=item Class: B<Digits> - -=item Switch: B<-digits> - -An integer specifying how many significant digits should be retained -when converting the value of the scale to a string. -If the number is less than or equal to zero, then the scale picks -the smallest value that guarantees that every possible slider -position prints as a different string. - -=item Name: B<from> - -=item Class: B<From> - -=item Switch: B<-from> - -A real value corresponding to the left or top end of the scale. - -=item Name: B<label> - -=item Class: B<Label> - -=item Switch: B<-label> - -A string to display as a label for the scale. For -vertical scales the label is displayed just to the right of the -top end of the scale. For horizontal scales the label is displayed -just above the left end of the scale. If the option is specified -as an empty string, no label is displayed. - -=item Name: B<length> - -=item Class: B<Length> - -=item Switch: B<-length> - -Specifies the desired long dimension of the scale in screen units -(i.e. any of the forms acceptable to B<Tk_GetPixels>). -For vertical scales this is the scale's height; for horizontal scales -it is the scale's width. - -=item Name: B<resolution> - -=item Class: B<Resolution> - -=item Switch: B<-resolution> - -A real value specifying the resolution for the scale. -If this value is greater than zero then the scale's value will always be -rounded to an even multiple of this value, as will tick marks and -the endpoints of the scale. If the value is less than zero then no -rounding occurs. Defaults to 1 (i.e., the value will be integral). - -=item Name: B<showValue> - -=item Class: B<ShowValue> - -=item Switch: B<-showvalue> - -Specifies a boolean value indicating whether or not the current -value of the scale is to be displayed. - -=item Name: B<sliderLength> - -=item Class: B<SliderLength> - -=item Switch: B<-sliderlength> - -Specfies the size of the slider, measured in screen units along the slider's -long dimension. The value may be specified in any of the forms acceptable -to B<Tk_GetPixels>. - -=item Name: B<sliderRelief> - -=item Class: B<SliderRelief> - -=item Switch: B<-sliderrelief> - -Specifies the relief to use when drawing the slider, such as B<raised> -or B<sunken>. - -=item Name: B<state> - -=item Class: B<State> - -=item Switch: B<-state> - -Specifies one of three states for the scale: B<normal>, -B<active>, or B<disabled>. -If the scale is disabled then the value may not be changed and the scale -won't activate. -If the scale is active, the slider is displayed using the color -specified by the B<activeBackground> option. - -=item Name: B<tickInterval> - -=item Class: B<TickInterval> - -=item Switch: B<-tickinterval> - -Must be a real value. -Determines the spacing between numerical -tick marks displayed below or to the left of the slider. -If 0, no tick marks will be displayed. - -=item Name: B<to> - -=item Class: B<To> - -=item Switch: B<-to> - -Specifies a real value corresponding -to the right or bottom end of the scale. -This value may be either less than or greater than the B<from> option. - -=item Name: B<variable> - -=item Class: B<Variable> - -=item Switch: B<-variable> - -Specifies the name of a global variable to link to the scale. Whenever the -value of the variable changes, the scale will update to reflect this -value. -Whenever the scale is manipulated interactively, the variable -will be modified to reflect the scale's new value. - -=item Name: B<width> - -=item Class: B<Width> - -=item Switch: B<-width> - -Specifies the desired narrow dimension of the trough in screen units -(i.e. any of the forms acceptable to B<Tk_GetPixels>). -For vertical scales this is the trough's width; for horizontal scales -this is the trough's height. - -=back - -=head1 DESCRIPTION - -The B<Scale> method creates a new window (given by the -$widget argument) and makes it into a scale widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the scale such as its colors, orientation, -and relief. The B<scale> command returns its -$widget argument. At the time this command is invoked, -there must not exist a window named $widget, but -$widget's parent must exist. - -A scale is a widget that displays a rectangular I<trough> and a -small I<slider>. The trough corresponds to a range -of real values (determined by the B<from>, B<to>, and -B<resolution> options), -and the position of the slider selects a particular real value. -The slider's position (and hence the scale's value) may be adjusted -with the mouse or keyboard as described in -the L<"BINDINGS"> section below. Whenever the scale's value is changed, a Tcl -command is invoked (using the B<command> option) to notify -other interested widgets of the change. -In addition, the value -of the scale can be linked to a Tcl variable (using the B<variable> -option), so that changes in either are reflected in the other. - -Three annotations may be displayed in a scale widget: a label -appearing at the top right of the widget (top left for horizontal -scales), a number displayed just to the left of the slider -(just above the slider for horizontal scales), and a collection -of numerical tick marks just to the left of the current value -(just below the trough for horizontal scales). Each of these three -annotations may be enabled or disabled using the -configuration options. - -=head1 WIDGET METHODS - -The B<Scale> method creates a widget object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. -The widget also inherits all the methods provided by the generic -L<Tk::Widget|Tk::Widget> class. - -The following additional methods are available for scale widgets: - -=over 4 - -=item I<$scale>-E<gt>B<coords>(?I<value>?) - -Returns a list whose elements are the x and y coordinates of -the point along the centerline of the trough that corresponds -to I<value>. -If I<value> is omitted then the scale's current value is used. - -=item I<$scale>-E<gt>B<get>(?I<x, y>?) - -If I<x> and I<y> are omitted, returns the current value -of the scale. If I<x> and I<y> are specified, they give -pixel coordinates within the widget; the command returns -the scale value corresponding to the given pixel. -Only one of I<x> or I<y> is used: for horizontal scales -I<y> is ignored, and for vertical scales I<x> is ignored. - -=item I<$scale>-E<gt>B<identify>(I<x, y>) - -Returns a string indicating what part of the scale lies under -the coordinates given by I<x> and I<y>. -A return value of B<slider> means that the point is over -the slider; B<trough1> means that the point is over the -portion of the slider above or to the left of the slider; -and B<trough2> means that the point is over the portion -of the slider below or to the right of the slider. -If the point isn't over one of these elements, an empty string -is returned. - -=item I<$scale>-E<gt>B<set>(I<value>) - -This command is invoked to change the current value of the scale, -and hence the position at which the slider is displayed. I<Value> -gives the new value for the scale. -The command has no effect if the scale is disabled. - -=back - -=head1 BINDINGS - -Tk automatically creates class bindings for scales that give them -the following default behavior. -Where the behavior is different for vertical and horizontal scales, -the horizontal behavior is described in parentheses. - -=over 4 - -=item [1] - -If button 1 is pressed in the trough, the scale's value will -be incremented or decremented by the value of the B<resolution> -option so that the slider moves in the direction of the cursor. -If the button is held down, the action auto-repeats. - -=item [2] - -If button 1 is pressed over the slider, the slider can be dragged -with the mouse. - -=item [3] - -If button 1 is pressed in the trough with the Control key down, -the slider moves all the way to the end of its range, in the -direction towards the mouse cursor. - -=item [4] - -If button 2 is pressed, the scale's value is set to the mouse -position. If the mouse is dragged with button 2 down, the scale's -value changes with the drag. - -=item [5] - -The Up and Left keys move the slider up (left) by the value -of the B<resolution> option. - -=item [6] - -The Down and Right keys move the slider down (right) by the value -of the B<resolution> option. - -=item [7] - -Control-Up and Control-Left move the slider up (left) by the -value of the B<bigIncrement> option. - -=item [8] - -Control-Down and Control-Right move the slider down (right) by the -value of the B<bigIncrement> option. - -=item [9] - -Home moves the slider to the top (left) end of its range. - -=item [10] - -End moves the slider to the bottom (right) end of its range. - -If the scale is disabled using the B<state> option then -none of the above bindings have any effect. - -The behavior of scales can be changed by defining new bindings for -individual widgets or by redefining the class bindings. - -=back - -=head1 KEYWORDS - -scale, slider, trough, widget - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Scrollbar.pod b/Master/tlpkg/tlperl/lib/Tk/Scrollbar.pod deleted file mode 100644 index 838eb97e666..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Scrollbar.pod +++ /dev/null @@ -1,429 +0,0 @@ -# Copyright (c) 1990-1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::Scrollbar - Create and manipulate Scrollbar widgets - -=for category Tk Widget Classes - -=head1 SYNOPSIS - -I<$scrollbar> = I<$parent>-E<gt>B<Scrollbar>(?I<options>?); - -=head1 STANDARD OPTIONS - -B<-activebackground> B<-highlightbackground> B<-orient> B<-takefocus> -B<-background> B<-highlightcolor> B<-relief> B<-troughcolor> -B<-borderwidth> B<-highlightthickness> B<-repeatdelay> -B<-cursor> B<-jump> B<-repeatinterval> - -See L<Tk::options> for details of the standard options. - -=head1 WIDGET-SPECIFIC OPTIONS - -=over 4 - -=item Name: B<activeRelief> - -=item Class: B<ActiveRelief> - -=item Switch: B<-activerelief> - -Specifies the relief to use when displaying the element that is -active, if any. -Elements other than the active element are always displayed with -a raised relief. - -=item Name: B<command> - -=item Class: B<Command> - -=item Switch: B<-command> - -Specifies a callback to invoke to change the view -in the widget associated with the scrollbar. When a user requests -a view change by manipulating the scrollbar, the callback is -invoked. The callback is passed -additional arguments as described later. This option almost always has -a value such as B<[xview =E<gt> $widget]> or B<[yview =E<gt> $widget]>, consisting of the -a widget object and either B<xview> (if the scrollbar is for -horizontal scrolling) or B<yview> (for vertical scrolling). -All scrollable widgets have B<xview> and B<yview> methods -that take exactly the additional arguments appended by the scrollbar -as described in L<"SCROLLING COMMANDS"> below. - -=item Name: B<elementBorderWidth> - -=item Class: B<BorderWidth> - -=item Switch: B<-elementborderwidth> - -Specifies the width of borders drawn around the internal elements -of the scrollbar (the two arrows and the slider). The value may -have any of the forms acceptable to B<Tk_GetPixels>. -If this value is less than zero, the value of the B<borderWidth> -option is used in its place. - -=item Name: B<width> - -=item Class: B<Width> - -=item Switch: B<-width> - -Specifies the desired narrow dimension of the scrollbar window, -not including 3-D border, if any. For vertical -scrollbars this will be the width and for horizontal scrollbars -this will be the height. -The value may have any of the forms acceptable to B<Tk_GetPixels>. - -=back - -=head1 DESCRIPTION - -The B<Scrollbar> method creates a new window (given by the -$widget argument) and makes it into a scrollbar widget. -Additional options, described above, may be specified on the command -line or in the option database to configure aspects of the scrollbar -such as its colors, orientation, and relief. -The B<scrollbar> command returns its $widget argument. -At the time this command is invoked, there must not exist a window -named $widget, but $widget's parent must exist. - -A scrollbar is a widget that displays two arrows, one at each end of -the scrollbar, and a I<slider> in the middle portion of the -scrollbar. -It provides information about what is visible in an I<associated window> -that displays an document of some sort (such as a file being edited or -a drawing). -The position and size of the slider indicate which portion of the -document is visible in the associated window. For example, if the -slider in a vertical scrollbar covers the top third of the area -between the two arrows, it means that the associated window displays -the top third of its document. - -Scrollbars can be used to adjust the view in the associated window -by clicking or dragging with the mouse. -See L<"BINDINGS"> below for details. - -=head1 ELEMENTS - -A scrollbar displays five elements, which are referred to in the -methods for the scrollbar: - -=over 4 - -=item B<arrow1> - -The top or left arrow in the scrollbar. - -=item B<trough1> - -The region between the slider and B<arrow1>. - -=item B<slider> - -The rectangle that indicates what is visible in the associated widget. - -=item B<trough2> - -The region between the slider and B<arrow2>. - -=item B<arrow2> - -The bottom or right arrow in the scrollbar. - -=back - -=head1 WIDGET METHODS - -The B<Scrollbar> method creates a widget object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. -The widget also inherits all the methods provided by the generic -L<Tk::Widget|Tk::Widget> class. - -The following additional methods are available for scrollbar widgets: - -=over 4 - -=item I<$scrollbar>-E<gt>B<activate>(?I<element>?) - -Marks the element indicated by I<element> as active, which -causes it to be displayed as specified by the B<activeBackground> -and B<activeRelief> options. -The only element values understood by this command are B<arrow1>, -B<slider>, or B<arrow2>. -If any other value is specified then no element of the scrollbar -will be active. -If I<element> is not specified, the command returns -the name of the element that is currently active, or an empty string -if no element is active. - -=item I<$scrollbar>-E<gt>B<delta>(I<deltaX, deltaY>) - -Returns a real number indicating the fractional change in -the scrollbar setting that corresponds to a given change -in slider position. For example, if the scrollbar is horizontal, -the result indicates how much the scrollbar setting must change -to move the slider I<deltaX> pixels to the right (I<deltaY> is -ignored in this case). -If the scrollbar is vertical, the result indicates how much the -scrollbar setting must change to move the slider I<deltaY> pixels -down. The arguments and the result may be zero or negative. - -=item I<$scrollbar>-E<gt>B<fraction>(I<x, y>) - -Returns a real number between 0 and 1 indicating where the point -given by I<x> and I<y> lies in the trough area of the scrollbar. -The value 0 corresponds to the top or left of the trough, the -value 1 corresponds to the bottom or right, 0.5 corresponds to -the middle, and so on. -I<X> and I<y> must be pixel coordinates relative to the scrollbar -widget. -If I<x> and I<y> refer to a point outside the trough, the closest -point in the trough is used. - -=item I<$scrollbar>-E<gt>B<get> - -Returns the scrollbar settings in the form of a list whose -elements are the arguments to the most recent B<set> method. - -=item I<$scrollbar>-E<gt>B<identify>(I<x, y>) - -Returns the name of the element under the point given by I<x> and -I<y> (such as B<arrow1>), or an empty string if the point does -not lie in any element of the scrollbar. -I<X> and I<y> must be pixel coordinates relative to the scrollbar -widget. - -=item I<$scrollbar>-E<gt>B<set>(I<first, last>) - -This command is invoked by the scrollbar's associated widget to -tell the scrollbar about the current view in the widget. -The command takes two arguments, each of which is a real fraction -between 0 and 1. -The fractions describe the range of the document that is visible in -the associated widget. -For example, if I<first> is 0.2 and I<last> is 0.4, it means -that the first part of the document visible in the window is 20% -of the way through the document, and the last visible part is 40% -of the way through. - -=back - -=head1 SCROLLING COMMANDS - -When the user interacts with the scrollbar, for example by dragging -the slider, the scrollbar notifies the associated widget that it -must change its view. -The scrollbar makes the notification by evaluating a callback -specified as the scrollbar's B<-command> option. -The callback may take several forms. -In each case, the intial arguments passed are those -specified in the B<-command> callback itself, -which usually has a form like [B<yview> =E<gt> I<$widget>]. -(Which will invoke I<$widget>-E<gt>B<yview>(...) where -the ... part is as below. See L<Tk::callbacks> for details.) -The callback is passed additional arguments as follows: - -=over 4 - -=item B<moveto>,I<fraction> - -I<Fraction> is a real number between 0 and 1. -The widget should adjust its view so that the point given -by I<fraction> appears at the beginning of the widget. -If I<fraction> is 0 it refers to the beginning of the -document. 1.0 refers to the end of the document, 0.333 -refers to a point one-third of the way through the document, -and so on. - -=item B<scroll,>I<number,>B<units> - -The widget should adjust its view by I<number> units. -The units are defined in whatever way makes sense for the widget, -such as characters or lines in a text widget. -I<Number> is either 1, which means one unit should scroll off -the top or left of the window, or -1, which means that one unit -should scroll off the bottom or right of the window. - -=item B<scroll>,I<number>,B<page> - -The widget should adjust its view by I<number> pages. -It is up to the widget to define the meaning of a page; typically -it is slightly less than what fits in the window, so that there -is a slight overlap between the old and new views. -I<Number> is either 1, which means the next page should -become visible, or -1, which means that the previous page should -become visible. - -=back - -=head1 OLD COMMAND SYNTAX - -In versions of Tk before 4.0, the B<set> and B<get> widget -commands used a different form. -This form is still supported for backward compatibility, but it -is deprecated. -In the old command syntax, the B<set> method has the -following form: - -=over 4 - -=item I<$scrollbar>-E<gt>B<set>(I<totalUnits, windowUnits, firstUnit, lastUnit>) - -In this form the arguments are all integers. -I<TotalUnits> gives the total size of the object being displayed in the -associated widget. The meaning of one unit depends on the associated -widget; for example, in a text editor widget units might -correspond to lines of -text. I<WindowUnits> indicates the total number of units that -can fit in the associated window at one time. I<FirstUnit> -and I<lastUnit> give the indices of the first and last units -currently visible in the associated window (zero corresponds to the -first unit of the object). - -=back - -Under the old syntax the B<get> method returns a list -of four integers, consisting of the I<totalUnits>, I<windowUnits>, -I<firstUnit>, and I<lastUnit> values from the last B<set> -method. - -The callbacks generated by scrollbars also have a different form -when the old syntax is being used, the callback is passed a single argument: - -=over 4 - -=item I<unit> - -I<Unit> is an integer that indicates what should appear at -the top or left of the associated widget's window. -It has the same meaning as the I<firstUnit> and I<lastUnit> -arguments to the B<set> method. - -=back - -The most recent B<set> method determines whether or not -to use the old syntax. -If it is given two real arguments then the new syntax will be -used in the future, and if it is given four integer arguments then -the old syntax will be used. - -=head1 BINDINGS - -Tk automatically creates class bindings for scrollbars that give them -the following default behavior. -If the behavior is different for vertical and horizontal scrollbars, -the horizontal behavior is described in parentheses. - -=over 4 - -=item [1] - -Pressing button 1 over B<arrow1> causes the view in the -associated widget to shift up (left) by one unit so that the -document appears to move down (right) one unit. -If the button is held down, the action auto-repeats. - -=item [2] - -Pressing button 1 over B<trough1> causes the view in the -associated widget to shift up (left) by one screenful so that the -document appears to move down (right) one screenful. -If the button is held down, the action auto-repeats. - -=item [3] - -Pressing button 1 over the slider and dragging causes the view -to drag with the slider. -If the B<jump> option is true, then the view doesn't drag along -with the slider; it changes only when the mouse button is released. - -=item [4] - -Pressing button 1 over B<trough2> causes the view in the -associated widget to shift down (right) by one screenful so that the -document appears to move up (left) one screenful. -If the button is held down, the action auto-repeats. - -=item [5] - -Pressing button 1 over B<arrow2> causes the view in the -associated widget to shift down (right) by one unit so that the -document appears to move up (left) one unit. -If the button is held down, the action auto-repeats. - -=item [6] - -If button 2 is pressed over the trough or the slider, it sets -the view to correspond to the mouse position; dragging the -mouse with button 2 down causes the view to drag with the mouse. -If button 2 is pressed over one of the arrows, it causes the -same behavior as pressing button 1. - -=item [7] - -If button 1 is pressed with the Control key down, then if the -mouse is over B<arrow1> or B<trough1> the view changes -to the very top (left) of the document; if the mouse is over -B<arrow2> or B<trough2> the view changes -to the very bottom (right) of the document; if the mouse is -anywhere else then the button press has no effect. - -=item [8] - -In vertical scrollbars the Up and Down keys have the same behavior -as mouse clicks over B<arrow1> and B<arrow2>, respectively. -In horizontal scrollbars these keys have no effect. - -=item [9] - -In vertical scrollbars Control-Up and Control-Down have the same -behavior as mouse clicks over B<trough1> and B<trough2>, respectively. -In horizontal scrollbars these keys have no effect. - -=item [10] - -In horizontal scrollbars the Up and Down keys have the same behavior -as mouse clicks over B<arrow1> and B<arrow2>, respectively. -In vertical scrollbars these keys have no effect. - -=item [11] - -In horizontal scrollbars Control-Up and Control-Down have the same -behavior as mouse clicks over B<trough1> and B<trough2>, respectively. -In vertical scrollbars these keys have no effect. - -=item [12] - -The Prior and Next keys have the same behavior -as mouse clicks over B<trough1> and B<trough2>, respectively. - -=item [13] - -The Home key adjusts the view to the top (left edge) of the document. - -=item [14] - -The End key adjusts the view to the bottom (right edge) of the document. - -=back - -=head1 SEE ALSO - -L<Tk::callbacks|Tk::callbacks> -L<Tk::Scrolled|Tk::Scrolled> - -=head1 KEYWORDS - -scrollbar, widget - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Scrolled.pod b/Master/tlpkg/tlperl/lib/Tk/Scrolled.pod deleted file mode 100644 index cd6c648ef5e..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Scrolled.pod +++ /dev/null @@ -1,86 +0,0 @@ -=head1 NAME - -Tk::Scrolled - Create a widget with attached scrollbar(s) - -=for category Derived Widgets - -=for index_group Perl/Tk Constructs - -=head1 SYNOPSIS - -S< >I<$whatever> = I<$parent>-E<gt>B<Scrolled>(I<Whatever> ?,B<-scrollbars>=E<gt>I<where>? ?,...?); - -=head1 DESCRIPTION - -To stop a flood of B<ScrlWhatever> widgets Perl/Tk introcuded the special -constructor B<Scrolled>. B<Scrolled> creates a widget of the given Class -I<Whatever> with attached L<scrollbar(s)|Tk::Scrollbar>. - -=head1 OPTIONS - -All options beside B<-scrollbars> explained below are passed to -the I<Whatever> widget constructor. - -=over 4 - -=item -scrollbars - -Expects as argument the position where the scrollbars should be -created: B<w>, B<e> or B<n>, B<s> or a combination of -them. If the one or both positions are prefixed with B<o> the -scrollbar will only show up if there is a 'real' need to scroll. - -=back - -=head1 ADVERTISED SUBWIDGETS - -See L<Tk::mega/"Subwidget"> how to use advertised widgets. - -=over 4 - -=item scrolled - -the scrolled widget - -=item I<widget> - -same as B<scrolled> above. I<widget> is the kind of widget passed -to scrolled as first argument in all lowercase. - -=item xscrollbar - -the B<Scrollbar> widget used for horizontal scrolling (if it exists) - -=item yscrollbar - -the B<Scrollbar> widget used for vertical scrolling (if it exists) - -=item corner - -a frame in the corner between the vertical and horizontal scrolbar - -=back - -=head1 BUGS - -If a widget does not support I<-{x,y}scrollcommand> options, -B<Scrolled> does not complain if the specified widget class does -not support them. E.g., - -S< >I<$parent>->B<Scrolled>(B<'Button'>, ...) - -One does not get an error message or warning when one tries to -configure scrollbars after the widget construction: - -S< >I<$ascrolled>->B<configure>(B<-scrollbars> => B<'e'>); - -=head1 SEE ALSO - -L<Tk::Scrollbar|Tk::Scrollbar> - -=head1 KEYWORDS - -scrolled, scrollbar - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Spinbox.pod b/Master/tlpkg/tlperl/lib/Tk/Spinbox.pod deleted file mode 100644 index b18b7e1b9ae..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Spinbox.pod +++ /dev/null @@ -1,819 +0,0 @@ -# Copyright (c) 2000 Jeffrey Hobbs. -# Copyright (c) 2000 Ajuba Solutions. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# RCS: @(#) $Id: spinbox.n,v 1.3 2001/12/18 23:02:35 hobbs Exp $ - -=head1 NAME - -Tk::Spinbox - Create and manipulate Spinbox widgets - -=for category Tk Generic Methods - -=head1 SYNOPSIS - -I<$spinbox> = I<$parent>-E<gt>Spinbox(?I<options>?); - - -activebackground -highlightthickness -repeatinterval - -background -insertbackground -selectbackground - -borderwidth -insertborderwidth -selectborderwidth - -cursor -insertontime -selectforeground - -exportselection -insertwidth -takefocus - -font -insertofftime -textvariable - -foreground -justify -xscrollcommand - -highlightbackground -relief - -highlightcolor -repeatdelay - -=head1 WIDGET-SPECIFIC OPTIONS - -=over 4 - -=item Option: B<-buttonbackground> - -=item Name: B<buttonBackground> - -=item Class: B<Background> - -The background color to be used for the spin buttons. - -=item Option: B<-buttoncursor> - -=item Name: B<buttonCursor> - -=item Class: B<Cursor> - -The cursor to be used when over the spin buttons. If this is empty -(the default), a default cursor will be used. - -=item Option: B<-buttondownrelief> - -=item Name: B<buttonDownRelief> - -=item Class: B<Relief> - -The relief to be used for the upper spin button. - -=item Option: B<-buttonuprelief> - -=item Name: B<buttonUpRelief> - -=item Class: B<Relief> - -The relief to be used for the lower spin button. - -=item Option: B<-command> - -=item Name: B<command> - -=item Class: B<Command> - -Specifies a Perl/Tk callback to invoke whenever a Spinbutton is invoked. -The callback has these two arguments I<appended> to any existing callback -arguments: the current value of the widget and the direction of the button -press (B<up> or B<down>). - -=item Option: B<-disabledbackground> - -=item Name: B<disabledBackground> - -=item Class: B<DisabledBackground> - -Specifies the background color to use when the Spinbox is disabled. If -this option is the empty string, the normal background color is used. - -=item Option: B<-disabledforeground> - -=item Name: B<disabledForeground> - -=item Class: B<DisabledForeground> - -Specifies the foreground color to use when the Spinbox is disabled. If -this option is the empty string, the normal foreground color is used. - -=item Option: B<-format> - -=item Name: B<format> - -=item Class: B<Format> - -Specifies an alternate format to use when setting the string value -when using the B<-from> and B<-to> range. -This must be a format specifier of the form B<%E<lt>padE<gt>.E<lt>padE<gt>f>, -as it will format a floating-point number. - -=item Option: B<-from> - -=item Name: B<from> - -=item Class: B<From> - -A floating-point value corresponding to the lowest value for a Spinbox, to -be used in conjunction with B<-to> and B<-increment>. When all -are specified correctly, the Spinbox will use these values to control its -contents. This value must be less than the B<-to> option. -If B<-values> is specified, it supercedes this option. - -=item Option: B<-invalidcommand> - -=item Alias: B<-invcmd> - -=item Name: B<invalidCommand> - -=item Class: B<InvalidCommand> - -Specifies a script to eval when B<validateCommand> returns 0. Setting -it to an empty string disables this feature (the default). The best use of -this option is to set it to I<bell>. See B<Validation> below for -more information. - -=item Option: B<-increment> - -=item Name: B<increment> - -=item Class: B<Increment> - -A floating-point value specifying the increment. When used with -B<-from> and B<-to>, the value in the widget will be adjusted by -B<-increment> when a spin button is pressed (up adds the value, -down subtracts the value). - -=item Option: B<-readonlybackground> - -=item Name: B<readonlyBackground> - -=item Class: B<ReadonlyBackground> - -Specifies the background color to use when the Spinbox is readonly. If -this option is the empty string, the normal background color is used. - -=item Option: B<-state> - -=item Name: B<state> - -=item Class: B<State> - -Specifies one of three states for the Spinbox: B<normal>, -B<disabled>, or B<readonly>. If the Spinbox is readonly, then the -value may not be changed using methods and no insertion cursor -will be displayed, even if the input focus is in the widget; the -contents of the widget may still be selected. If the Spinbox is -disabled, the value may not be changed, no insertion cursor will be -displayed, the contents will not be selectable, and the Spinbox may -be displayed in a different color, depending on the values of the -B<-disabledforeground> and B<-disabledbackground> options. - -=item Option: B<-to> - -=item Name: B<to> - -=item Class: B<To> - -A floating-point value corresponding to the highest value for the Spinbox, -to be used in conjunction with B<-from> and B<-increment>. When -all are specified correctly, the Spinbox will use these values to control -its contents. This value must be greater than the B<-from> option. -If B<-values> is specified, it supercedes this option. - -=item Option: B<-validate> - -=item Name: B<validate> - -=item Class: B<Validate> - -Specifies the mode in which validation should operate: B<none>, -B<focus>, B<focusin>, B<focusout>, B<key>, or B<all>. -It defaults to B<none>. When you want validation, you must explicitly -state which mode you wish to use. See B<Validation> below for more. - -=item Option: B<-validatecommand> - -=item Alias: B<-vcmd> - -=item Name: B<validateCommand> - -=item Class: B<ValidateCommand> - -Specifies a script to evaluate when you want to validate the input in the -widget. Setting it to an empty string disables this feature (the default). -Validation occurs according to the value of B<-validate>. -This command must return a valid boolean value. If it returns 0 (or -the valid boolean equivalent) then the value of the widget will not -change and the B<invalidCommand> will be evaluated if it is set. If it -returns 1, then value will be changed. -See B<Validation> below for more information. - -=item Option: B<-values> - -=item Name: B<values> - -=item Class: B<Values> - -Must be a proper list value. If specified, the Spinbox will use these -values as to control its contents, starting with the first value. This -option has precedence over the B<-from> and B<-to> range. - -=item Option: B<-width> - -=item Name: B<width> - -=item Class: B<Width> - -Specifies an integer value indicating the desired width of the Spinbox window, -in average-size characters of the widget's font. -If the value is less than or equal to zero, the widget picks a -size just large enough to hold its current text. - -=item Option: B<-wrap> - -=item Name: B<wrap> - -=item Class: B<Wrap> - -Must be a proper boolean value. If on, the Spinbox will wrap around the -values of data in the widget. - -=back - -=head1 DESCRIPTION - -The B<Spinbox> method creates a new window (given by the -$spinbox argument) and makes it into a Spinbox widget. -Additional options, described above, may be specified on the -command line or in the option database -to configure aspects of the Spinbox such as its colors, font, -and relief. - -A B<Spinbox> is an extended B<Entry> widget that allows he user -to move, or spin, through a fixed set of ascending or descending values -such as times or dates in addition to editing the value as in an -B<entry>. When first created, a Spinbox's string is empty. -A portion of the Spinbox may be selected as described below. -If a Spinbox is exporting its selection (see the B<exportSelection> -option), then it will observe the standard protocols for handling the -selection; Spinbox selections are available as type B<STRING>. -Spinboxes also observe the standard Tk rules for dealing with the -input focus. When a Spinbox has the input focus it displays an -I<insertion cursor> to indicate where new characters will be -inserted. - -Spinboxes are capable of displaying strings that are too long to -fit entirely within the widget's window. In this case, only a -portion of the string will be displayed; commands described below -may be used to change the view in the window. Spinboxes use -the standard B<-xscrollcommand> mechanism for interacting with -scrollbars (see the description of the B<-xscrollcommand> option -for details). They also support scanning, as described below. - -=head1 VALIDATION - -Validation works by setting the B<validateCommand> -option to a callback which will be evaluated according to the B<validate> -option as follows: - -=over 4 - -=item B<none> - -Default. This means no validation will occur. - -=item B<focus> - -B<validateCommand> will be called when the Spinbox receives or -loses focus. - -=item B<focusin> - -B<validateCommand> will be called when the Spinbox receives focus. - -=item B<focusout> - -B<validateCommand> will be called when the Spinbox loses focus. - -=item B<key> - -B<validateCommand> will be called when the Spinbox is edited. - -=item B<all> - -B<validateCommand> will be called for all above conditions. - - -The B<validateCommand> and B<invalidCommand> callbacks are invoked -with at least 5 positional arguments, which are I<appended> to any already -existing callback arguments: - -=over 4 - -=item * 1 - -The proposed value of the entry. If you are configuring the -entry widget to have a new textVariable, this will be the value of that -textVariable. - -=item * 2 - -The characters to be added (or deleted). This will be C<undef> -if validation is due to focus, explcit call to validate or if change -is due to C<-textvariable> changing. - -=item * 3 - -The current value of entry i.e. before the proposed change. - -=item * 4 - -The index of character string to be added/deleted, if any. Otherwise -1. - -=item * 5 - -Type of action. 1 == INSERT, 0 == DELETE, --1 if it's a forced validation or textVariable validation. - -=back - -In general, the B<textVariable> and B<validateCommand> can be -dangerous to mix. Any problems have been overcome so that using the -B<validateCommand> will not interfere with the traditional behavior of -the Spinbox widget. Using the B<textVariable> for read-only purposes will -never cause problems. The danger comes when you try set the -B<textVariable> to something that the B<validateCommand> would not -accept, which causes B<validate> to become I<none> (the -B<invalidCommand> will not be triggered). The same happens -when an error occurs evaluating the B<validateCommand>. - -Primarily, an error will occur when the B<validateCommand> or -B<invalidCommand> encounters an error in its script while evaluating or -B<validateCommand> does not return a valid boolean value. The -B<validate> option will also set itself to B<none> when you edit the -Spinbox widget from within either the B<validateCommand> or the -B<invalidCommand>. Such editions will override the one that was being -validated. If you wish to edit the value of the widget -during validation and still have the B<validate> option set, you should -include the command - - my $val = $spinbox->cget(-validate); - $spinbox->configure(-validate => $val); - -in the B<validateCommand> or B<invalidCommand> (whichever one you -were editing the Spinbox widget from). It is also recommended to not set an -associated B<textVariable> during validation, as that can cause the -Spinbox widget to become out of sync with the B<textVariable>. - -=back - -=head1 WIDGET METHODS - -The B<Spinbox> command creates a widget object whose -name is $widget. This command may be used to invoke various -operations on the widget. It has the following general form: - - $widget->method(?arg arg ...?); - -Many of the methods for Spinboxes take one or more indices as -arguments. An index specifies a particular character in the Spinbox's -string, in any of the following ways: - -=over 4 - -=item I<number> - -Specifies the character as a numerical index, where 0 corresponds -to the first character in the string. - -=item B<anchor> - -Indicates the anchor point for the selection, which is set with the -B<select from> and B<select adjust> methods. - -=item B<end> - -Indicates the character just after the last one in the Spinbox's string. -This is equivalent to specifying a numerical index equal to the length -of the Spinbox's string. - -=item B<insert> - -Indicates the character adjacent to and immediately following the -insertion cursor. - -=item B<sel.first> - -Indicates the first character in the selection. It is an error to -use this form if the selection isn't in the Spinbox window. - -=item B<sel.last> - -Indicates the character just after the last one in the selection. -It is an error to use this form if the selection isn't in the -Spinbox window. - -=item B<@>I<number> - -In this form, I<number> is treated as an x-coordinate in the -Spinbox's window; the character spanning that x-coordinate is used. -For example, ``B<@0>'' indicates the left-most character in the -window. - -=back - -Abbreviations may be used for any of the forms above, e.g. ``B<e>'' -or ``B<sel.f>''. In general, out-of-range indices are automatically -rounded to the nearest legal value. - -The following commands are possible for Spinbox widgets: - -=over 4 - -=item I<$widget>-E<gt>B<bbox>(I<index>); - -Returns a list of four numbers describing the bounding box of the -character given by I<index>. -The first two elements of the list give the x and y coordinates of -the upper-left corner of the screen area covered by the character -(in pixels relative to the widget) and the last two elements give -the width and height of the character, in pixels. -The bounding box may refer to a region outside the visible area -of the window. - -=item I<$widget>-E<gt>B<cget>(I<option>); - -Returns the current value of the configuration option given -by I<option>. -I<Option> may have any of the values accepted by the B<Spinbox> -command. - -=item I<$widget>-E<gt>B<configure>(?I<option>?, ?I<value, option, value, ...>?); - -Query or modify the configuration options of the widget. -If no I<option> is specified, returns a list describing all of -the available options for $widget (see L<Tk::configure> for -information on the format of this list). If I<option> is specified -with no I<value>, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no I<option> is specified). If -one or more I<option-value> pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. -I<Option> may have any of the values accepted by the B<Spinbox> -command. - -=item I<$widget>-E<gt>B<delete>(I<first, >?I<last>?); - -Delete one or more elements of the Spinbox. -I<First> is the index of the first character to delete, and -I<last> is the index of the character just after the last -one to delete. -If I<last> isn't specified it defaults to I<first>+1, -i.e. a single character is deleted. -This command returns an empty string. - -=item I<$widget>-E<gt>B<get>; - -Returns the Spinbox's string. - -=item I<$widget>-E<gt>B<icursor>(I<index>); - -Arrange for the insertion cursor to be displayed just before the character -given by I<index>. Returns an empty string. - -=item I<$widget>-E<gt>B<identify>(I<x, y>); - -Returns the name of the window element corresponding to coordinates -I<x> and I<y> in the Spinbox. Return value is one of: -B<none>, B<buttondown>, B<buttonup>, B<entry>. - -=item I<$widget>-E<gt>B<index>(I<index>); - -Returns the numerical index corresponding to I<index>. - -=item I<$widget>-E<gt>B<insert>(I<index, string>); - -Insert the characters of I<string> just before the character -indicated by I<index>. Returns an empty string. - -=item I<$widget>-E<gt>B<invoke>(I<element>); - -Causes the specified element, either B<buttondown> or B<buttonup>, -to be invoked, triggering the action associated with it. - -=item I<$widget>-E<gt>B<scan>(I<option, args>); - -This command is used to implement scanning on Spinboxes. It has -two forms, depending on I<option>: - -=over 4 - -=item I<$widget>-E<gt>B<scanMark>(I<x>); - -Records I<x> and the current view in the Spinbox window; used in -conjunction with later B<scan dragto> commands. Typically this -command is associated with a mouse button press in the widget. It -returns an empty string. - -=item I<$widget>-E<gt>B<scanDragto>(I<x>); - -This command computes the difference between its I<x> argument -and the I<x> argument to the last B<scan mark> command for -the widget. It then adjusts the view left or right by 10 times the -difference in x-coordinates. This command is typically associated -with mouse motion events in the widget, to produce the effect of -dragging the Spinbox at high speed through the window. The return -value is an empty string. - -=back - -=item I<$widget>-E<gt>B<selection>(I<option, arg>); - -This command is used to adjust the selection within a Spinbox. It -has several forms, depending on I<option>: - -=over 4 - -=item I<$widget>-E<gt>B<selectionAdjust>(I<index>); - -Locate the end of the selection nearest to the character given by -I<index>, and adjust that end of the selection to be at I<index> -(i.e including but not going beyond I<index>). The other -end of the selection is made the anchor point for future -B<select to> commands. If the selection -isn't currently in the Spinbox, then a new selection is created to -include the characters between I<index> and the most recent -selection anchor point, inclusive. -Returns an empty string. - -=item I<$widget>-E<gt>B<selectionClear>; - -Clear the selection if it is currently in this widget. If the -selection isn't in this widget then the command has no effect. -Returns an empty string. - -=item I<$widget>-E<gt>B<selectionElement>(?I<element>?); - -Sets or gets the currently selected element. If a spinbutton element -is specified, it will be displayed depressed. - -=item I<$widget>-E<gt>B<selectionFrom>(I<index>); - -Set the selection anchor point to just before the character -given by I<index>. Doesn't change the selection. -Returns an empty string. - -=item I<$widget>-E<gt>B<selectionPresent>; - -Returns 1 if there is are characters selected in the Spinbox, -0 if nothing is selected. - -=item I<$widget>-E<gt>B<selectionRange>(I<start, >I<end>); - -Sets the selection to include the characters starting with -the one indexed by I<start> and ending with the one just -before I<end>. -If I<end> refers to the same character as I<start> or an -earlier one, then the Spinbox's selection is cleared. - -=item I<$widget>-E<gt>B<selectionTo>(I<index>); - -If I<index> is before the anchor point, set the selection -to the characters from I<index> up to but not including -the anchor point. -If I<index> is the same as the anchor point, do nothing. -If I<index> is after the anchor point, set the selection -to the characters from the anchor point up to but not including -I<index>. -The anchor point is determined by the most recent B<select from> -or B<select adjust> command in this widget. -If the selection isn't in this widget then a new selection is -created using the most recent anchor point specified for the widget. -Returns an empty string. - -=back - -=item I<$widget>-E<gt>B<set>(?I<string>?); - -If I<string> is specified, the Spinbox will try and set it to this -value, otherwise it just returns the Spinbox's string. -If validation is on, it will occur when setting the string. - -=item I<$widget>-E<gt>B<validate>; - -This command is used to force an evaluation of the B<validateCommand> -independent of the conditions specified by the B<validate> option. -This is done by temporarily setting the B<validate> option to B<all>. -It returns 0 or 1. - -=item I<$widget>-E<gt>B<xview>(I<args>); - -This command is used to query and change the horizontal position of the -text in the widget's window. It can take any of the following -forms: - -=over 4 - -=item I<$widget>-E<gt>B<xview>; - -Returns a list containing two elements. -Each element is a real fraction between 0 and 1; together they describe -the horizontal span that is visible in the window. -For example, if the first element is .2 and the second element is .6, -20% of the Spinbox's text is off-screen to the left, the middle 40% is visible -in the window, and 40% of the text is off-screen to the right. -These are the same values passed to scrollbars via the B<-xscrollcommand> -option. - -=item I<$widget>-E<gt>B<xview>(I<index>); - -Adjusts the view in the window so that the character given by I<index> -is displayed at the left edge of the window. - -=item I<$widget>-E<gt>B<xviewMoveto>(I<fraction>); - -Adjusts the view in the window so that the character I<fraction> of the -way through the text appears at the left edge of the window. -I<Fraction> must be a fraction between 0 and 1. - -=item I<$widget>-E<gt>B<xviewScroll>(I<number, what>); - -This command shifts the view in the window left or right according to -I<number> and I<what>. -I<Number> must be an integer. -I<What> must be either B<units> or B<pages> or an abbreviation -of one of these. -If I<what> is B<units>, the view adjusts left or right by -I<number> average-width characters on the display; if it is -B<pages> then the view adjusts by I<number> screenfuls. -If I<number> is negative then characters farther to the left -become visible; if it is positive then characters farther to the right -become visible. - -=back - -=back - -=head1 DEFAULT BINDINGS - -Tk automatically creates class bindings for Spinboxes that give them -the following default behavior. -In the descriptions below, ``word'' refers to a contiguous group -of letters, digits, or ``_'' characters, or any single character -other than these. - -=over 4 - -=item [1] - -Clicking mouse button 1 positions the insertion cursor -just before the character underneath the mouse cursor, sets the -input focus to this widget, and clears any selection in the widget. -Dragging with mouse button 1 strokes out a selection between -the insertion cursor and the character under the mouse. - -=item [2] - -Double-clicking with mouse button 1 selects the word under the mouse -and positions the insertion cursor at the beginning of the word. -Dragging after a double click will stroke out a selection consisting -of whole words. - -=item [3] - -Triple-clicking with mouse button 1 selects all of the text in the -Spinbox and positions the insertion cursor before the first character. - -=item [4] - -The ends of the selection can be adjusted by dragging with mouse -button 1 while the Shift key is down; this will adjust the end -of the selection that was nearest to the mouse cursor when button -1 was pressed. -If the button is double-clicked before dragging then the selection -will be adjusted in units of whole words. - -=item [5] - -Clicking mouse button 1 with the Control key down will position the -insertion cursor in the Spinbox without affecting the selection. - -=item [6] - -If any normal printing characters are typed in a Spinbox, they are -inserted at the point of the insertion cursor. - -=item [7] - -The view in the Spinbox can be adjusted by dragging with mouse button 2. -If mouse button 2 is clicked without moving the mouse, the selection -is copied into the Spinbox at the position of the mouse cursor. - -=item [8] - -If the mouse is dragged out of the Spinbox on the left or right sides -while button 1 is pressed, the Spinbox will automatically scroll to -make more text visible (if there is more text off-screen on the side -where the mouse left the window). - -=item [9] - -The Left and Right keys move the insertion cursor one character to the -left or right; they also clear any selection in the Spinbox and set -the selection anchor. -If Left or Right is typed with the Shift key down, then the insertion -cursor moves and the selection is extended to include the new character. -Control-Left and Control-Right move the insertion cursor by words, and -Control-Shift-Left and Control-Shift-Right move the insertion cursor -by words and also extend the selection. -Control-b and Control-f behave the same as Left and Right, respectively. -Meta-b and Meta-f behave the same as Control-Left and Control-Right, -respectively. - -=item [10] - -The Home key, or Control-a, will move the insertion cursor to the -beginning of the Spinbox and clear any selection in the Spinbox. -Shift-Home moves the insertion cursor to the beginning of the Spinbox -and also extends the selection to that point. - -=item [11] - -The End key, or Control-e, will move the insertion cursor to the -end of the Spinbox and clear any selection in the Spinbox. -Shift-End moves the cursor to the end and extends the selection -to that point. - -=item [12] - -The Select key and Control-Space set the selection anchor to the position -of the insertion cursor. They don't affect the current selection. -Shift-Select and Control-Shift-Space adjust the selection to the -current position of the insertion cursor, selecting from the anchor -to the insertion cursor if there was not any selection previously. - -=item [13] - -Control-/ selects all the text in the Spinbox. - -=item [14] - -Control-\ clears any selection in the Spinbox. - -=item [15] - -The F16 key (labelled Copy on many Sun workstations) or Meta-w -copies the selection in the widget to the clipboard, if there is a selection. - -=item [16] - -The F20 key (labelled Cut on many Sun workstations) or Control-w -copies the selection in the widget to the clipboard and deletes -the selection. -If there is no selection in the widget then these keys have no effect. - -=item [17] - -The F18 key (labelled Paste on many Sun workstations) or Control-y -inserts the contents of the clipboard at the position of the -insertion cursor. - -=item [18] - -The Delete key deletes the selection, if there is one in the Spinbox. -If there is no selection, it deletes the character to the right of -the insertion cursor. - -=item [19] - -The BackSpace key and Control-h delete the selection, if there is one -in the Spinbox. -If there is no selection, it deletes the character to the left of -the insertion cursor. - -=item [20] - -Control-d deletes the character to the right of the insertion cursor. - -=item [21] - -Meta-d deletes the word to the right of the insertion cursor. - -=item [22] - -Control-k deletes all the characters to the right of the insertion -cursor. - -=item [23] - -Control-t reverses the order of the two characters to the right of -the insertion cursor. - -If the Spinbox is disabled using the B<-state> option, then the Spinbox's -view can still be adjusted and text in the Spinbox can still be selected, -but no insertion cursor will be displayed and no text modifications will -take place. - -The behavior of Spinboxes can be changed by defining new bindings for -individual widgets or by redefining the class bindings. - -=back - -=head1 KEYWORDS - -Spinbox, Entry, widget diff --git a/Master/tlpkg/tlperl/lib/Tk/Submethods.pod b/Master/tlpkg/tlperl/lib/Tk/Submethods.pod deleted file mode 100644 index 2a83334f8b2..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Submethods.pod +++ /dev/null @@ -1,27 +0,0 @@ - -=head1 NAME - -Tk::Submethods - add aliases for tk sub-commands - -=for pm Tk/Submethods.pm - -=for category Implementation - -=head1 SYNOPSIS - - use Tk::Submethods ( 'command1' => [qw(sub1 sub2 sub3)], - 'command2' => [qw(sub1 sub2 sub3)]); - -=head1 DESCRIPTION - -Creates C<-E<gt>commandSub(...)> as an alias for C<-E<gt>command('sub',...)> -e.g. C<-E<gt>grabRelease> for C<-E<gt>grab('release')>. - -For each command/subcommand pair this creates a closure with command -and subcommand as bound lexical variables and assigns a reference to this -to a 'glob' in the callers package. - -Someday the sub-commands may be created directly in the C code. - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/SunConst.pod b/Master/tlpkg/tlperl/lib/Tk/SunConst.pod deleted file mode 100644 index eb5d892871b..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/SunConst.pod +++ /dev/null @@ -1,18 +0,0 @@ - -=head1 NAME - -Tk::DragDrop::SunConst - Constants for Sun's Drag&Drop protocol - -=for pm DragDrop/DragDrop/SunConst.pm - -=for category Experimental Modules - -=head1 DESCRIPTION - -This module defines symbolic name subs for the numeric constants that -make up Sun's Drag&Drop protocol. They are in this module with Exporter -as they are shared between the two halves (Dropper and Receiver) of -the protocol. - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/TList.pod b/Master/tlpkg/tlperl/lib/Tk/TList.pod deleted file mode 100644 index b8937fa8ef0..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/TList.pod +++ /dev/null @@ -1,597 +0,0 @@ -# Copyright (c) 1996, Expert Interface Technologies -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# The file man.macros and some of the macros used by this file are -# copyrighted: (c) 1990 The Regents of the University of California. -# (c) 1994-1995 Sun Microsystems, Inc. -# The license terms of the Tcl/Tk distribution are in the file -# license.tcl. - -=head1 NAME - -Tk::TList - Create and manipulate Tix Tabular List widgets - -=for category Tix Extensions - -=head1 SYNOPSIS - -S< >I<$tlist> = I<$parent>-E<gt>B<TList>(?I<options>?); - -=head1 SUPER-CLASS - -None. - -=head1 STANDARD OPTIONS - -B<-background> B<-borderwidth> B<-class> B<-cursor> B<-foreground> -B<-font> B<-height> B<-highlightcolor> B<-highlightthickness> -B<-relief> B<-selectbackground> B<-selectforeground> -B<-xscrollcommand> B<-yscrollcommand> B<-width> - -See L<Tk::options> for details of the standard options. - -=head1 WIDGET-SPECIFIC OPTIONS - -=over 4 - -=item Name: B<browsecmd> - -=item Class: B<BrowseCmd> - -=item Switch: B<-browsecmd> - -Specifies a perl/Tk B<callback> to be executed when the user browses through the -entries in the TList widget. - -=item Name: B<command> - -=item Class: B<Command> - -=item Switch: B<-command> - -Specifies the perl/Tk B<callback> to be executed when the user invokes a list -entry in the TList widget. Normally the user invokes a list -entry by double-clicking it or pressing the Return key. - -=item Name: B<foreground> - -=item Class: B<Foreground> - -=item Switch: B<-foreground> - -=item Alias: B<-fg> - -Specifies the default foreground color for the list entries. - -=item Name: B<height> - -=item Class: B<Height> - -=item Switch: B<-height> - -Specifies the desired height for the window in number of characters. - -=item Name: B<itemType> - -=item Class: B<ItemType> - -=item Switch: B<-itemtype> - -Specifies the default type of display item for this TList widget. When -you call the B<insert> methods, display items of this -type will be created if the B<-itemtype> option is not specified. - -=item Name: B<orient> - -=item Class: B<Orient> - -=item Switch: B<-orient> - -Specifies the order of tabularizing the list entries. When set to -"B<vertical>", the entries are arranged in a column, from top to -bottom. If the entries cannot be contained in one column, the -remaining entries will go to the next column, and so on. When set to -"B<horizontal>", the entries are arranged in a row, from left to -right. If the entries cannot be contained in one row, the remaining -entries will go to the next row, and so on. - -=item Name: B<padX> - -=item Class: B<Pad> - -=item Switch: B<-padx> - -The default horizontal padding for list entries. - -=item Name: B<padY> - -=item Class: B<Pad> - -=item Switch: B<-padx> - -The default vertical padding for list entries. - -=item Name: B<selectBackground> - -=item Class: B<SelectBackground> - -=item Switch: B<-selectbackground> - -Specifies the background color for the selected list entries. - -=item Name: B<selectBorderWidth> - -=item Class: B<BorderWidth> - -=item Switch: B<-selectborderwidth> - -Specifies a non-negative value indicating the width of the 3-D border -to draw around selected items. The value may have any of the forms -acceptable to B<Tk_GetPixels>. - -=item Name: B<selectForeground> - -=item Class: B<SelectForeground> - -=item Switch: B<-selectforeground> - -Specifies the foreground color for the selected list entries. - -=item Name: B<selectMode> - -=item Class: B<SelectMode> - -=item Switch: B<-selectmode> - -Specifies one of several styles for manipulating the selection. The -value of the option may be arbitrary, but the default bindings expect -it to be either B<single>, B<browse>, B<multiple>, or -B<extended>; the default value is B<single>. - -=item Name: B<sizeCmd> - -=item Class: B<SizeCmd> - -=item Switch: B<-sizecmd> - -Specifies a perl/Tk B<callback> to be called whenever the TList widget -changes its size. This command can be useful to implement "user scroll -bars when needed" features. - -=item Name: B<state> - -=item Class: B<State> - -=item Switch: B<-state> - -Specifies whether the TList command should react to user actions. When -set to "B<normal>", the TList reacts to user actions in the normal -way. When set to "B<disabled>", the TList can only be scrolled, but -its entries cannot be selected or activated. - -=item Name: B<width> - -=item Class: B<Width> - -=item Switch: B<-width> - -Specifies the desired width for the window in characters. - -=back - -=head1 DESCRIPTION - -The B<TList> method creates a new window (given by the -$widget argument) and makes it into a TList widget. -Additional options, described above, may be specified on the command -line or in the option database to configure aspects of the -TList widget such as its cursor and relief. - -The TList widget can be used to display data in a tabular format. The -list entries of a TList widget are similar to the entries in the Tk -listbox widget. The main differences are (1) the TList widget can -display the list entries in a two dimensional format and (2) you can -use graphical images as well as multiple colors and fonts for -the list entries. - -Each list entry is identified by an B<index>, which can be in the -following forms: - -=over 4 - -=item I<number> - -An integer that indicates the position of the entry in the list. 0 -means the first position, 1 means the second position, and so on. - -=item B<end> - -Indicates the end of the listbox. For some commands this means just -after the last entry; for other commands it means the last entry. - -=item B<@>I<x>,I<y> - -Indicates the element that covers the point in the listbox window -specified by x and y (in pixel coordinates). If no element covers that -point, then the closest element to that point is used. - -=back - -=head1 DISPLAY ITEMS - -Each list entry in an TList widget is associated with a B<display> -item. The display item determines what visual information should -be displayed for this list entry. Please see L<Tk::DItem> -for a list of all display items. - -When a list entry is created by the B<insert> command, the type of -its display item is determined by the B<-itemtype> option passed -to these commands. If the B<-itemtype> is omitted, then by default -the type specified by this TList widget's B<-itemtype> option is -used. - -=head1 WIDGET METHODS - -The B<TList> method creates a widget object. - -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. -The widget also inherits all the methods provided by the generic -L<Tk::Widget|Tk::Widget> class. - -The following additional methods are available for TList widgets: - -=over 4 - -=item I<$tlist>-E<gt>B<anchorSet>(I<index>) - -Sets the anchor to the list entry identified by I<index>. The -anchor is the end of the selection that is fixed while dragging out a -selection with the mouse. - -=item I<$tlist>-E<gt>B<anchorClear> - -Removes the anchor, if any, from this TList widget. This only removes -the surrounding highlights of the anchor entry and does not affect its -selection status. - -=item I<$tlist>-E<gt>B<delete>(I<from, >?I<to>?) - -Deletes one or more list entries between the two entries specified by -the indices I<from> and I<to>. If I<to> is not specified, deletes -the single entry specified by I<from>. - -=item I<$tlist>-E<gt>B<dragsiteSet>(I<index>) - -Sets the dragsite to the list entry identified by -I<index>. The dragsite is used to indicate the source of a -drag-and-drop action. Currently drag-and-drop functionality has not -been implemented in Tix yet. - -=item I<$tlist>-E<gt>B<dragsiteClear> - -Remove the dragsite, if any, from the this TList widget. This only -removes the surrounding highlights of the dragsite entry and does not -affect its selection status. - -=item I<$tlist>-E<gt>B<dropsiteSet>(I<index>) - -Sets the dropsite to the list entry identified by I<index>. The -dropsite is used to indicate the target of a drag-and-drop -action. Currently drag-and-drop functionality has not been implemented -in Tix yet. - -=item I<$tlist>-E<gt>B<dropsiteClear> - -Remove the dropsite, if any, from the this TList widget. This only -removes the surrounding highlights of the dropsite entry and does not -affect its selection status. - -=item I<$tlist>-E<gt>B<entrycget>(I<index, option>) - -Returns the current value of the configuration option given by -I<option> for the entry indentfied by I<index>. I<Option> may -have any of the values accepted by the B<insert> method. - -=item I<$tlist>-E<gt>B<entryconfigure>(I<index, >?I<option>?, I<?value, option, value, ...>?) - -Query or modify the configuration options of the list entry identified -by I<index>. If no I<option> is specified, returns a list -describing all of the available options for I<index> (see -B<Tk_ConfigureInfo> for information on the format of this list). If -I<option> is specified with no I<value>, then the method -returns a list describing the one named option (this list will be -identical to the corresponding sublist of the value returned if no -I<option> is specified). If one or more I<option-value> pairs -are specified, then the command modifies the given option(s) to have -the given value(s); in this case the method returns an empty string. -I<Option> may have any of the values accepted by the B<insert> -method. The exact set of options depends on the -value of the B<-itemtype> option passed to the the B<insert> -method when this list entry is created. - -=item I<$tlist>-E<gt>B<insert>(I<index, >?I<option, value, ...>?) - -Creates a new list entry at the position indicated by I<index>. The -following configuration options can be given to configure the list -entry: - -=over 8 - -=item B<-itemtype> => I<type> - -Specifies the type of display item to be display for the new list -entry. I<type> must be a valid display item type. Currently the -available display item types are B<image>, B<imagetext>, -B<text>, and I<$widget>. If this option is not specified, then by -default the type specified by this TList widget's B<-itemtype> -option is used. - -=item B<-state> => I<state> - -Specifies whether this entry can be selected or invoked by the user. -Must be either B<normal> or B<disabled>. - -=item B<-data> => I<data> - -Arbitrary data to be associated with the entry (a perl scalar value). - -=back - -The B<insert> method accepts additional configuration options -to configure the display item associated with this list entry. The set -of additional configuration options depends on the type of the display -item given by the B<-itemtype> option. Please see -L<Tk::DItem> for a list of the configuration options for -each of the display item types. - -=item I<$tlist>-E<gt>B<info>(I<option, >I<arg, ...>) - -Query information about the TList widget. I<option> can be one -of the following: - -=over 8 - -=item I<$tlist>-E<gt>B<info>(B<anchor, >I<index>) - -Returns the index of the current anchor, if any, of the TList -widget. If the anchor is not set, returns the empty string. - -=item I<$tlist>-E<gt>B<info>(B<dragsite, >I<index>) - -Returns the index of the current dragsite, if any, of the TList -widget. If the dragsite is not set, returns the empty string. - -=item I<$tlist>-E<gt>B<info>(B<dropsite, >I<index>) - -Returns the index of the current dropsite, if any, of the TList -widget. If the dropsite is not set, returns the empty string. - -=item I<$tlist>-E<gt>B<info>(B<selection>) - -Returns a list of selected elements in the TList widget. If no entries -are selected, returns an empty string. - -=back - -=item I<$tlist>-E<gt>B<nearest>(I<x, y>) - -Given an I<(x,y)> coordinate within the TList window, this command -returns the index of the TList element nearest to that coordinate. - -=item I<$tlist>-E<gt>B<see>(I<index>) - -Adjust the view in the TList so that the entry given by I<index> is -visible. If the entry is already visible then the command has no -effect; otherwise TList scrolls to bring the element into view at the edge -to which it is nearest. - -=item I<$tlist>-E<gt>B<selection>(I<option, >I<arg, ...>) - -This command is used to adjust the selection within a TList widget. It -has several forms, depending on I<option>: - -=over 8 - -=item I<$tlist>-E<gt>B<selectionClear>(?I<from>?, ?I<to>?) - -When no extra arguments are given, deselects all of the list entrie(s) -in this TList widget. When only I<from> is given, only the list -entry identified by I<from> is deselected. When both I<from> and -I<to> are given, deselects all of the list entrie(s) between -between I<from> and I<to>, inclusive, without affecting the -selection state of entries outside that range. - -=item I<$tlist>-E<gt>B<selectionIncludes>(I<index>) - -Returns 1 if the list entry indicated by I<index> is currently -selected; returns 0 otherwise. - -=item I<$tlist>-E<gt>B<selectionSet>(I<from, >?I<to>?) - -Selects all of the list entrie(s) between between I<from> and -I<to>, inclusive, without affecting the selection state of entries -outside that range. When only I<from> is given, only the list entry -identified by I<from> is selected. - -=back - -=item I<$tlist>-E<gt>B<xview>(I<args>) - -This command is used to query and change the horizontal position of the -information in the widget's window. It can take any of the following -forms: - -=over 8 - -=item I<$tlist>-E<gt>B<xview> - -Returns a list containing two elements. Each element is a real -fraction between 0 and 1; together they describe the horizontal span -that is visible in the window. For example, if the first element is -0.2 and the second element is 0.6, 20% of the TList entry is -off-screen to the left, the middle 40% is visible in the window, and -40% of the entry is off-screen to the right. These are the same values -passed to scrollbars via the B<-xscrollcommand> option. - -=item I<$tlist>-E<gt>B<xview>(I<index>) - -Adjusts the view in the window so that the list entry identified by -I<index> is aligned to the left edge of the window. - -=item I<$tlist>-E<gt>B<xviewMoveto>(I<fraction>) - -Adjusts the view in the window so that I<fraction> of the total -width of the TList is off-screen to the left. I<fraction> must be -a fraction between 0 and 1. - -=item I<$tlist>-E<gt>B<xviewScroll>(I<number, what>) - -This command shifts the view in the window left or right according to -I<number> and I<what>. I<Number> must be an integer. -I<What> must be either B<units> or B<pages> or an -abbreviation of one of these. If I<what> is B<units>, the view -adjusts left or right by I<number> character units (the width of -the B<0> character) on the display; if it is B<pages> then the -view adjusts by I<number> screenfuls. If I<number> is negative -then characters farther to the left become visible; if it is positive -then characters farther to the right become visible. - -=back - -=item I<$tlist>-E<gt>B<yview>(I<?args>?) - -This command is used to query and change the vertical position of the -entries in the widget's window. It can take any of the following forms: - -=over 8 - -=item I<$tlist>-E<gt>B<yview> - -Returns a list containing two elements, both of which are real -fractions between 0 and 1. The first element gives the position of -the list element at the top of the window, relative to the TList as a -whole (0.5 means it is halfway through the TList, for example). The -second element gives the position of the list entry just after the -last one in the window, relative to the TList as a whole. These are -the same values passed to scrollbars via the B<-yscrollcommand> -option. - -=item I<$tlist>-E<gt>B<yview>(I<index>) - -Adjusts the view in the window so that the list entry given by -I<index> is displayed at the top of the window. - -=item I<$tlist>-E<gt>B<yviewMoveto>(I<fraction>) - -Adjusts the view in the window so that the list entry given by -I<fraction> appears at the top of the window. I<Fraction> is a -fraction between 0 and 1; 0 indicates the first entry in the TList, -0.33 indicates the entry one-third the way through the TList, and so -on. - -=item I<$tlist>-E<gt>B<yviewScroll>(I<number, what>) - -This command adjust the view in the window up or down according to -I<number> and I<what>. I<Number> must be an integer. -I<What> must be either B<units> or B<pages>. If I<what> -is B<units>, the view adjusts up or down by I<number> lines; if -it is B<pages> then the view adjusts by I<number> screenfuls. -If I<number> is negative then earlier entries become visible; if -it is positive then later entries become visible. - -=back - -=back - -=head1 BINDINGS - -=over 4 - -=item [1] - -If the B<-selectmode> is "browse", when the user drags the mouse -pointer over the list entries, the entry under the pointer will be -highlighted and the B<-browsecmd> procedure will be called with -one parameter, the index of the highlighted entry. Only one entry -can be highlighted at a time. The B<-command> procedure will be -called when the user double-clicks on a list entry. - -=item [2] - -If the B<-selectmode> is "single", the entries will only be -highlighted by mouse E<lt>ButtonRelease-1E<gt> events. When a new list entry -is highlighted, the B<-browsecmd> procedure will be called with -one parameter indicating the highlighted list entry. The -B<-command> procedure will be called when the user double-clicks -on a list entry. - -=item [3] - -If the B<-selectmode> is "multiple", when the user drags the mouse -pointer over the list entries, all the entries under the pointer will -be highlighted. However, only a contiguous region of list entries can -be selected. When the highlighted area is changed, the -B<-browsecmd> procedure will be called with an undefined -parameter. It is the responsibility of the B<-browsecmd> procedure -to find out the exact highlighted selection in the TList. The -B<-command> procedure will be called when the user double-clicks -on a list entry. - -=item [4] - -If the B<-selectmode> is "extended", when the user drags the mouse -pointer over the list entries, all the entries under the pointer will -be highlighted. The user can also make disjointed selections using -E<lt>Control-ButtonPress-1E<gt>. When the highlighted area is changed, the -B<-browsecmd> procedure will be called with an undefined -parameter. It is the responsibility of the B<-browsecmd> procedure -to find out the exact highlighted selection in the TList. The -B<-command> procedure will be called when the user double-clicks -on a list entry. - -=back - -=cut - -# BUG: -# click on 'one' in example below does not make -# it 'active' item (didn't GBARR reported this before!?) - -=head1 EXAMPLE - -This example demonstrates how to use an TList to store a list of -numbers: - - use strict; - use Tk (); - use Tk::TList; - - my $mw = Tk::MainWindow->new(); - my $image = $mw->Getimage('folder'); - my $tlist = $mw->TList(-orient => 'vertical'); - for my $text ( qw/one two three four five six seven eight nine/ ) { - $tlist->insert('end', - -itemtype=>'imagetext', -image=>$image, -text=>$text); - } - - $tlist->pack(-expand=>'yes', -fill=>'both'); - - Tk::MainLoop; - -=head1 SEE ALSO - -L<Tk::options|Tk::options> -L<Tk::Widget|Tk::Widget> -L<Tk::DItem|Tk::DItem> -L<Tk::HList|Tk::HList> -L<Tk::TixGrid|Tk::TixGrid> - -=head1 KEYWORDS - -Tix(n), Tabular Listbox, Display Items - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Table.pod b/Master/tlpkg/tlperl/lib/Tk/Table.pod deleted file mode 100644 index f73e93907b4..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Table.pod +++ /dev/null @@ -1,97 +0,0 @@ - -=head1 NAME - -Tk::Table - Scrollable 2 dimensional table of Tk widgets - -=for pm Tk/Table.pm - -=for category Tk Geometry Management - -=head1 SYNOPSIS - - use Tk::Table; - - $table = $parent->Table(-rows => number, - -columns => number, - -scrollbars => anchor, - -fixedrows => number, - -fixedcolumns => number, - -takefocus => boolean); - - $widget = $table->Button(...); - - $old = $table->put($row,$col,$widget); - $old = $table->put($row,$col,"Text"); # simple Label - $widget = $table->get($row,$col); - - $cols = $table->totalColumns; - $rows = $table->totalRows; - - $table->see($widget); - $table->see($row,$col); - - ($row,$col) = $table->Posn($widget); - -=head1 DESCRIPTION - -Tk::Table is an all-perl widget/geometry manager which allows a two dimensional -table of arbitary perl/Tk widgets to be displayed. - -Entries in the Table are simply ordinary perl/Tk widgets. They should -be created with the Table as their parent. Widgets are positioned in the -table using: - - $table->put($row,$col,$widget) - -If I<$widget> is not a reference it is treated as a string, and -a Lable widget is created with the string as its text. - -All the widgets in each column are set to the same width - the requested -width of the widest widget in the column. -Likewise, all the widgets in each row are set to the same height - the requested -height of the tallest widget in the column. - -A number of rows and/or columns can be marked as 'fixed' - and so can serve -as 'headings' for the remainder the rows which are scrollable. - -The requested size of the table as a whole is such that the number of rows -specified by -rows (default 10), and number of columns specified by -columns -(default 10) can be displayed. - -If the Table is told it can take the keyboard focus then cursor and scroll -keys scroll the displayed widgets. - -The Table will create and manage its own scrollbars if requested via --scrollbars. - -The table can be emptied using - - $table->clear - -the widgets which were in the table are destroyed. - - -The Tk::Table widget is derived from a Tk::Frame, so inherits all its -configure options. - -=head1 BUGS / Snags / Possible enhancements - -=over 4 - -=item * - -Very large Tables consume a lot of X windows. - -=item * - -No equivalent of pack's -anchor/-pad etc. options - -=back - -=head1 SEE ALSO - -L<Tk::grid>, L<Tk::HList>, L<Tk::TableMatrix>, L<Tk::MListbox>, -L<Tk::Columns> - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Tcl-perl.pod b/Master/tlpkg/tlperl/lib/Tk/Tcl-perl.pod deleted file mode 100644 index 2310e0738e4..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Tcl-perl.pod +++ /dev/null @@ -1,200 +0,0 @@ -=head1 NAME - -Tcl vs perl - very old suspect documentation on porting. - -=for category Other Modules and Languages - -=head1 DESCRIPTION - -This isn't really a .pod yet, nor is it Tcl vs perl -it is a copy of John's comparison of Malcolm's original perl/Tk -port with the current one. It is also out-of-date in places. - - From: john@WPI.EDU (John Stoffel ) - - Here are some thoughts on the new Tk extension and how I think the - organization of the commands looks. Mostly, I'm happy with it, it - makes some things more organized and more consistent with tcl/tk, but - since the overlying language is so different, I don't think we need to - follow exactly the tcl/tk model for how to call the language. - - The basic structure of the Tk program is: - - require Tk; - - $top = MainWindow->new(); - - # - # create widgets - # - - Tk::MainLoop; - - sub method1 { - } - - sub methodN { - } - - This is pretty much the same as tkperl5a5, with some cosmetic naming - changes, and some more useful command name and usage changes. A quick - comparison in no particular order follows: - - tkperl5a5 Tk - ------------------------------- ----------------------------------- - $top=tkinit(name,display,sync); $top=MainWindow->new(); - - tkpack $w, ... ; $w->pack(...) - - $w = Class::new($top, ...); $w = $top->Class(...); - - tkmainloop; Tk::MainLoop; - - tkbind($w,"<key>",sub); $w->bind("<key>",sub); - - tkdelete($w, ...); $w->delete(...); - - $w->scanmark(...); $w->scan("mark", ...); - - $w->scandragto(...); $w->scan("dragto", ...); - - $w->tkselect(); $w->Select(); - - $w->selectadjust(...); $w->selection("adjust", ...); - - $w->selectto(...); $w->selection("to", ...); - - $w->selectfrom(...); $w->selection("from", ...); - - $w->tkindex(...); $w->index(...); - - tclcmd("xxx",...); &Tk::xxx(...) # all Tk commands, but no Tcl at all - - tclcmd("winfo", xxx, $w, ...); $w->xxx(...); - - $w->mark(...); - - $w->tag(...); - - $w->grabstatus(); $w->grab("status"); - - $w->grabrelease(...); $w->grab("release", ...); - - focus($w); $w->focus; - - update(); Tk->update(); - - idletasks(); Tk->update("idletasks"); - - wm("cmd",$w, ...); $w->cmd(...); - - destroy($w); $w->destroy(); - - Tk::option(...); - $w->OptionGet(name,Class) - - $w->place(...) - - Tk::property(...); - - $w = Entry::new($parent,...) - - is now - - $w = $parent->Entry(...) - - As this allows new to be inherited from a Window class. - - -method=>x,-slave=>y - - is now - - -command => [x,y] - - 1st element of list is treated as "method" if y is an object reference. - (You can have -command => [a,b,c,d,e] too; b..e get passed as args). - - Object references are now hashes rather than scalars and there - is only ever one such per window. The Tcl_CmdInfo and PathName - are entries in the hash. - - (This allows derived classes to - re-bless the hash and keep their on stuff in it too.) - - Tk's "Tcl_Interp" is in fact a ref to "." window. - You can find all the Tk windows descended from it as their object - references get added (by PathName) into this hash. - $w->MainWindow returns this hash from any window. - - I think that it should extend to multiple tkinits / Tk->news - with different Display's - if Tk code does. - - Finally "bind" passes window as "extra" (or only) - argument. Thus - - Tk::Button->bind(<Any-Enter>,"Enter"); - - Binds Enter events to Tk::Button::Enter by default - but gets called as $w->Enter so derived class of Button can just - define its own Enter method. &EvWref and associated globals and race - conditions are no longer needed. - - One thing to beware of : commands bound to events with $widget->bind - follow same pattern, but get passed extra args : - - $widget->bind(<Any-1>,[sub {print shift}, $one, $two ]); - - When sub gets called it has : - - $widget $one $two - - passed. - - 1st extra arg is reference to the per-widget hash that serves as the - perl object for the widget. - - Every time an XEvent a reference to a special class is placed - in the widget hash. It can be retrieved by $w->XEvent method. - - The methods of the XEvent class are the - Tcl/Tk % special characters. - - Thus: - - $widget->bind(<Any-KeyPress>, - sub { - my $w = shift; - my $e = $w->XEvent; - print $w->PathName," ",$e->A," pressed ,$e->xy,"\n"); - }); - - XEvent->xy is a special case which returns "@" . $e->x . "," . $e->y - which is common in Text package. - - Because of passing a blessed widget hash to "bound" subs they can be - bound to (possibly inherited) methods of the widget's class: - - Class->bind(<Any-Down>,Down); - - sub Class::Down - { - my $w = shift; - # handle down arrow - } - - Also: - - -command and friends can take a list the 1st element can be a ref to - as sub or a method name. Remaining elements are passed as args to the - sub at "invoke" time. Thus : - - $b= $w->Button(blah blah, '-command' => [sub{print shift} , $fred ]); - - Should do the trick, provided $fred is defined at time of button creation. - - Thus 1st element of list is equivalent to Malcolm's -method and second - would be his -slave. Any further elements are a bonus and avoid - having to pass ref to an array/hash as a slave. - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Text.pod b/Master/tlpkg/tlperl/lib/Tk/Text.pod deleted file mode 100644 index 200cda9b033..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Text.pod +++ /dev/null @@ -1,2220 +0,0 @@ -# Copyright (c) 1992 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# Copyright (c) 2002 O'Reilly & Associates Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::Text - Create and manipulate Text widgets - -=for category Tk Widget Classes - -=head1 SYNOPSIS - -I<$text> = I<$parent>-E<gt>B<Text>(?I<options>?); - -B<-background> B<-highlightbackground> B<-insertontime> B<-selectborderwidth> -B<-borderwidth> B<-highlightcolor> B<-insertwidth> B<-selectforeground> -B<-cursor> B<-highlightthickness> B<-padx> B<-setgrid> -B<-exportselection> B<-insertbackground> B<-pady> B<-takefocus> -B<-font> B<-insertborderwidth> B<-relief> B<-xscrollcommand> -B<-foreground> B<-insertofftime> B<-selectbackground> B<-yscrollcommand> - -=head1 WIDGET-SPECIFIC OPTIONS - -=over 4 - -=item Name: B<height> - -=item Class: B<Height> - -=item Switch: B<-height> - -Specifies the desired height for the window, in units of characters -in the font given by the B<-font> option. -Must be at least one. - -=item Name: B<spacing1> - -=item Class: B<Spacing1> - -=item Switch: B<-spacing1> - -Requests additional space above each text line in the widget, -using any of the standard forms for screen distances. -If a line wraps, this option only applies to the first line -on the display. -This option may be overriden with B<-spacing1> options in -tags. - -=item Name: B<spacing2> - -=item Class: B<Spacing2> - -=item Switch: B<-spacing2> - -For lines that wrap (so that they cover more than one line on the -display) this option specifies additional space to provide between -the display lines that represent a single line of text. -The value may have any of the standard forms for screen distances. -This option may be overriden with B<-spacing2> options in -tags. - -=item Name: B<spacing3> - -=item Class: B<Spacing3> - -=item Switch: B<-spacing3> - -Requests additional space below each text line in the widget, -using any of the standard forms for screen distances. -If a line wraps, this option only applies to the last line -on the display. -This option may be overriden with B<-spacing3> options in -tags. - -=item Name: B<state> - -=item Class: B<State> - -=item Switch: B<-state> - -Specifies one of two states for the text: B<normal> or B<disabled>. -If the text is disabled then characters may not be inserted or deleted -and no insertion cursor will be displayed, even if the input focus is -in the widget. - -=item Name: B<tabs> - -=item Class: B<Tabs> - -=item Switch: B<-tabs> - -Specifies a set of tab stops for the window. The option's value consists -of a list of screen distances giving the positions of the tab stops. Each -position may optionally be followed in the next list element -by one of the keywords B<left>, B<right>, B<center>, -or B<numeric>, which specifies how to justify -text relative to the tab stop. B<Left> is the default; it causes -the text following the tab character to be positioned with its left edge -at the tab position. B<Right> means that the right edge of the text -following the tab character is positioned at the tab position, and -B<center> means that the text is centered at the tab position. -B<Numeric> means that the decimal point in the text is positioned -at the tab position; if there is no decimal point then the least -significant digit of the number is positioned just to the left of the -tab position; if there is no number in the text then the text is -right-justified at the tab position. -For example, B<-tabs =E<gt> [qw/2c left 4c 6c center/]> creates three -tab stops at two-centimeter intervals; the first two use left -justification and the third uses center justification. -If the list of tab stops does not have enough elements to cover all -of the tabs in a text line, then Tk extrapolates new tab stops using -the spacing and alignment from the last tab stop in the list. -The value of the B<tabs> option may be overridden by B<-tabs> -options in tags. -If no B<-tabs> option is specified, or if it is specified as -an empty list, then Tk uses default tabs spaced every eight -(average size) characters. - -=item Name: B<width> - -=item Class: B<Width> - -=item Switch: B<-width> - -Specifies the desired width for the window in units of characters -in the font given by the B<-font> option. -If the font doesn't have a uniform width then the width of the -character ``0'' is used in translating from character units to -screen units. - -=item Name: B<wrap> - -=item Class: B<Wrap> - -=item Switch: B<-wrap> - -Specifies how to handle lines in the text that are too long to be -displayed in a single line of the text's window. -The value must be B<none> or B<char> or B<word>. -A wrap mode of B<none> means that each line of text appears as -exactly one line on the screen; extra characters that don't fit -on the screen are not displayed. -In the other modes each line of text will be broken up into several -screen lines if necessary to keep all the characters visible. -In B<char> mode a screen line break may occur after any character; -in B<word> mode a line break will only be made at word boundaries. - -=back - -=head1 DESCRIPTION - -The B<Text> method creates a new window (given by the -$text argument) and makes it into a text widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the text such as its default background color -and relief. The B<text> command returns the -path name of the new window. - -A text widget displays one or more lines of text and allows that -text to be edited. -Text widgets support four different kinds of annotations on the -text, called tags, marks, embedded windows or embedded images. -Tags allow different portions of the text -to be displayed with different fonts and colors. -In addition, L<perl/Tk callbacks|Tk::callbacks> can be associated with tags so -that scripts are invoked when particular actions such as keystrokes -and mouse button presses occur in particular ranges of the text. -See L<"TAGS"> below for more details. - -The second form of annotation consists of marks, which are floating -markers in the text. -Marks are used to keep track of various interesting positions in the -text as it is edited. -See L<"MARKS"> below for more details. - -The third form of annotation allows arbitrary windows to be -embedded in a text widget. -See L<"EMBEDDED WINDOWS"> below for more details. - -The fourth form of annotation allows Tk images to be embedded in a text -widget. -See L<"EMBEDDED IMAGES"> below for more details. - -The Perl/Tk B<Text> widget does not support undo/redo, use the B<TextUndo> -widget instead. - -=head1 INDICES - -Many of the methods for texts take one or more indices -as arguments. -An index is a string used to indicate a particular place within -a text, such as a place to insert characters or one endpoint of a -range of characters to delete. -Indices have the syntax - - base modifier modifier modifier ... - -Where I<base> gives a starting point and the I<modifier>s -adjust the index from the starting point (e.g. move forward or -backward one character). Every index must contain a I<base>, -but the I<modifier>s are optional. - -The I<base> for an index must have one of the following forms: - -=over 4 - -=item I<line>B<.>I<char> - -Indicates I<char>'th character on line I<line>. -Lines are numbered from 1 for consistency with other UNIX programs -that use this numbering scheme. -Within a line, characters are numbered from 0. -If I<char> is B<end> then it refers to the newline character -that ends the line. - -=item B<@>I<x>B<,>I<y> - -Indicates the character that covers the pixel whose x and y coordinates -within the text's window are I<x> and I<y>. - -=item B<end> - -Indicates the end of the text (the character just after the last -newline). - -=item I<mark> - -Indicates the character just after the mark whose name is I<mark>. - -=item I<tag>B<.first> - -Indicates the first character in the text that has been tagged with -I<tag>. -This form generates an error if no characters are currently tagged -with I<tag>. - -=item I<tag>B<.last> - -Indicates the character just after the last one in the text that has -been tagged with I<tag>. -This form generates an error if no characters are currently tagged -with I<tag>. - -=item I<$widget> - -Indicates the position of the embedded window referenced by I<$widget>. -This form generates an error if I<$widget> does not reference to an -embedded window. - -=item I<imageName> - -Indicates the position of the embedded image whose name is -I<imageName>. -This form generates an error if there is no embedded image -by the given name. - -If the I<base> could match more than one of the above forms, such -as a I<mark> and I<imageName> both having the same value, then -the form earlier in the above list takes precedence. -If modifiers follow the base index, each one of them must have one -of the forms listed below. Keywords such as B<chars> and B<wordend> -may be abbreviated as long as the abbreviation is unambiguous. - -=item B<+ >I<count>B< chars> - -Adjust the index forward by I<count> characters, moving to later -lines in the text if necessary. If there are fewer than I<count> -characters in the text after the current index, then set the index -to the last character in the text. -Spaces on either side of I<count> are optional. - -=item B<- >I<count>B< chars> - -Adjust the index backward by I<count> characters, moving to earlier -lines in the text if necessary. If there are fewer than I<count> -characters in the text before the current index, then set the index -to the first character in the text. -Spaces on either side of I<count> are optional. - -=item B<+ >I<count>B< lines> - -Adjust the index forward by I<count> lines, retaining the same -character position within the line. If there are fewer than I<count> -lines after the line containing the current index, then set the index -to refer to the same character position on the last line of the text. -Then, if the line is not long enough to contain a character at the indicated -character position, adjust the character position to refer to the last -character of the line (the newline). -Spaces on either side of I<count> are optional. - -=item B<- >I<count>B< lines> - -Adjust the index backward by I<count> lines, retaining the same -character position within the line. If there are fewer than I<count> -lines before the line containing the current index, then set the index -to refer to the same character position on the first line of the text. -Then, if the line is not long enough to contain a character at the indicated -character position, adjust the character position to refer to the last -character of the line (the newline). -Spaces on either side of I<count> are optional. - -=item B<linestart> - -Adjust the index to refer to the first character on the line. - -=item B<lineend> - -Adjust the index to refer to the last character on the line (the newline). - -=item B<wordstart> - -Adjust the index to refer to the first character of the word containing -the current index. A word consists of any number of adjacent characters -that are letters, digits, or underscores, or a single character that -is not one of these. - -=item B<wordend> - -Adjust the index to refer to the character just after the last one of the -word containing the current index. If the current index refers to the last -character of the text then it is not modified. - -If more than one modifier is present then they are applied in -left-to-right order. For example, the index ``B<end - 1 chars>'' -refers to the next-to-last character in the text and -``B<insert wordstart - 1 c>'' refers to the character just before -the first one in the word containing the insertion cursor. - -=back - -=head1 TAGS - -The first form of annotation in text widgets is a tag. -A tag is a textual string that is associated with some of the characters -in a text. -Tags may contain arbitrary characters, but it is probably best to -avoid using the the characters `` '' (space), B<+>, or B<->: -these characters have special meaning in indices, so tags containing -them can't be used as indices. -There may be any number of tags associated with characters in a -text. -Each tag may refer to a single character, a range of characters, or -several ranges of characters. -An individual character may have any number of tags associated with it. - -A priority order is defined among tags, and this order is used in -implementing some of the tag-related functions described below. -When a tag is defined (by associating it with characters or setting -its display options or binding callbacks to it), it is given -a priority higher than any existing tag. -The priority order of tags may be redefined using the -``I<$text>-E<gt>B<tagRaise>'' and ``I<$text>-E<gt>B<tagLower>'' -methods. - -Tags serve three purposes in text widgets. -First, they control the way information is displayed on the screen. -By default, characters are displayed as determined by the -B<background>, B<font>, and B<foreground> options for the -text widget. -However, display options may be associated with individual tags -using the ``I<$text>-E<gt>B<tagConfigure>'' method. -If a character has been tagged, then the display options associated -with the tag override the default display style. -The following options are currently supported for tags: - -=over 4 - -=item B<-background> =E<gt> I<color> - -I<Color> specifies the background color to use for characters -associated with the tag. -It may have any of the forms accepted by B<Tk_GetColor>. - -=item B<-bgstipple> =E<gt> I<bitmap> - -I<Bitmap> specifies a bitmap that is used as a stipple pattern -for the background. -It may have any of the forms accepted by B<Tk_GetBitmap>. -If I<bitmap> hasn't been specified, or if it is specified -as an empty string, then a solid fill will be used for the -background. - -=item B<-borderwidth> =E<gt> I<pixels> - -I<Pixels> specifies the width of a 3-D border to draw around -the background. -It may have any of the forms accepted by B<Tk_GetPixels>. -This option is used in conjunction with the B<-relief> -option to give a 3-D appearance to the background for characters; -it is ignored unless the B<-background> option -has been set for the tag. - -=item B<-elide> =E<gt> boolean - -Elide specifies whether the data should be elided. Elided data -is not displayed and takes no space on screen, but further on -behaves just as normal data. - -=item B<-data> =E<gt> I<value> - -Allows an arbitrary perl scalar I<value> to be associated with the tag. - -=item B<-fgstipple> =E<gt> I<bitmap> - -I<Bitmap> specifies a bitmap that is used as a stipple pattern -when drawing text and other foreground information such as -underlines. -It may have any of the forms accepted by B<Tk_GetBitmap>. -If I<bitmap> hasn't been specified, or if it is specified -as an empty string, then a solid fill will be used. - -=item B<-font> =E<gt> I<fontName> - -I<FontName> is the name of a font to use for drawing characters. -It may have any of the forms accepted by B<Tk_GetFontStruct>. - -=item B<-foreground> =E<gt> I<color> - -I<Color> specifies the color to use when drawing text and other -foreground information such as underlines. -It may have any of the forms accepted by B<Tk_GetColor>. - -=item B<-justify> =E<gt> I<justify> - -If the first character of a display line has a tag for which this -option has been specified, then I<justify> determines how to -justify the line. -It must be one of B<left>, B<right>, or B<center>. -If a line wraps, then the justification for each line on the -display is determined by the first character of that display line. - -=item B<-lmargin1> =E<gt> I<pixels> - -If the first character of a text line has a tag for which this -option has been specified, then I<pixels> specifies how -much the line should be indented from the left edge of the -window. -I<Pixels> may have any of the standard forms for screen -distances. -If a line of text wraps, this option only applies to the -first line on the display; the B<-lmargin2> option controls -the indentation for subsequent lines. - -=item B<-lmargin2> =E<gt> I<pixels> - -If the first character of a display line has a tag for which this -option has been specified, and if the display line is not the -first for its text line (i.e., the text line has wrapped), then -I<pixels> specifies how much the line should be indented from -the left edge of the window. -I<Pixels> may have any of the standard forms for screen -distances. -This option is only used when wrapping is enabled, and it only -applies to the second and later display lines for a text line. - -=item B<-offset> =E<gt> I<pixels> - -I<Pixels> specifies an amount by which the text's baseline -should be offset vertically from the baseline of the overall -line, in pixels. -For example, a positive offset can be used for superscripts -and a negative offset can be used for subscripts. -I<Pixels> may have any of the standard forms for screen -distances. - -=item B<-overstrike> =E<gt> I<boolean> - -Specifies whether or not to draw a horizontal rule through -the middle of characters. -I<Boolean> may have any of the forms accepted by B<Tk_GetBoolean>. - -=item B<-relief> =E<gt> I<relief> - -I<Relief> specifies the 3-D relief to use for drawing backgrounds, -in any of the forms accepted by B<Tk_GetRelief>. -This option is used in conjunction with the B<-borderwidth> -option to give a 3-D appearance to the background for characters; -it is ignored unless the B<-background> option -has been set for the tag. - -=item B<-rmargin> =E<gt> I<pixels> - -If the first character of a display line has a tag for which this -option has been specified, then I<pixels> specifies how wide -a margin to leave between the end of the line and the right -edge of the window. -I<Pixels> may have any of the standard forms for screen -distances. -This option is only used when wrapping is enabled. -If a text line wraps, the right margin for each line on the -display is determined by the first character of that display -line. - -=item B<-spacing1> =E<gt> I<pixels> - -I<Pixels> specifies how much additional space should be -left above each text line, using any of the standard forms for -screen distances. -If a line wraps, this option only applies to the first -line on the display. - -=item B<-spacing2> =E<gt> I<pixels> - -For lines that wrap, this option specifies how much additional -space to leave between the display lines for a single text line. -I<Pixels> may have any of the standard forms for screen -distances. - -=item B<-spacing3> =E<gt> I<pixels> - -I<Pixels> specifies how much additional space should be -left below each text line, using any of the standard forms for -screen distances. -If a line wraps, this option only applies to the last -line on the display. - -=item B<-tabs> =E<gt> I<tabList> - -I<TabList> specifies a set of tab stops in the same form -as for the B<-tabs> option for the text widget. This -option only applies to a display line if it applies to the -first character on that display line. -If this option is specified as an empty string, it cancels -the option, leaving it unspecified for the tag (the default). -If the option is specified as a non-empty string that is -an empty list, such as B<-tabs => " ">, then it requests -default 8-character tabs as described for the B<tabs> -widget option. - -=item B<-underline> =E<gt> I<boolean> - -I<Boolean> specifies whether or not to draw an underline underneath -characters. -It may have any of the forms accepted by B<Tk_GetBoolean>. - -=item B<-wrap> =E<gt> I<mode> - -I<Mode> specifies how to handle lines that are wider than the -text's window. -It has the same legal values as the B<-wrap> option -for the text widget: B<none>, B<char>, or B<word>. -If this tag option is specified, it overrides the B<-wrap> option -for the text widget. - -=back - -If a character has several tags associated with it, and if their -display options conflict, then the options of the highest priority -tag are used. -If a particular display option hasn't been specified for a -particular tag, or if it is specified as an empty string, then -that option will never be used; the next-highest-priority -tag's option will used instead. -If no tag specifies a particular display option, then the default -style for the widget will be used. - -The second purpose for tags is event bindings. -You can associate bindings with a tag in much the same way you can -associate bindings with a widget class: whenever particular X -events occur on characters with the given tag, a given -<perl/Tk callback|Tk::callbacks> will be executed. -Tag bindings can be used to give behaviors to ranges of characters; -among other things, this allows hypertext-like -features to be implemented. -For details, see the description of the B<tagBind> widget -method below. - -The third use for tags is in managing the selection. -See L<"THE SELECTION"> below. - -=head1 MARKS - -The second form of annotation in text widgets is a mark. -Marks are used for remembering particular places in a text. -They are something like tags, in that they have names and -they refer to places in the file, but a mark isn't associated -with particular characters. -Instead, a mark is associated with the gap between two characters. -Only a single position may be associated with a mark at any given -time. -If the characters around a mark are deleted the mark will still -remain; it will just have new neighbor characters. -In contrast, if the characters containing a tag are deleted then -the tag will no longer have an association with characters in -the file. -Marks may be manipulated with the ``I<$text>-E<gt>B<mark>'' text widget -method, and their current locations may be determined by using the -mark name as an index in methods. - -Each mark also has a I<gravity>, which is either B<left> or -B<right>. -The gravity for a mark specifies what happens to the mark when -text is inserted at the point of the mark. -If a mark has left gravity, then the mark is treated as if it -were attached to the character on its left, so the mark will -remain to the left of any text inserted at the mark position. -If the mark has right gravity, new text inserted at the mark -position will appear to the right of the mark. The gravity -for a mark defaults to B<right>. - -The name space for marks is different from that for tags: the -same name may be used for both a mark and a tag, but they will refer -to different things. - -Two marks have special significance. -First, the mark B<insert> is associated with the insertion cursor, -as described under L<"THE INSERTION CURSOR"> below. -Second, the mark B<current> is associated with the character -closest to the mouse and is adjusted automatically to track the -mouse position and any changes to the text in the widget (one -exception: B<current> is not updated in response to mouse -motions if a mouse button is down; the update will be deferred -until all mouse buttons have been released). -Neither of these special marks may be deleted. - -=head1 EMBEDDED WINDOWS - -The third form of annotation in text widgets is an embedded window. -Each embedded window annotation causes a window to be displayed -at a particular point in the text. -There may be any number of embedded windows in a text widget, -and any widget may be used as an embedded window (subject to the -usual rules for geometry management, which require the text window -to be the parent of the embedded window or a descendant of its -parent). -The embedded window's position on the screen will be updated as the -text is modified or scrolled, and it will be mapped and unmapped as -it moves into and out of the visible area of the text widget. -Each embedded window occupies one character's worth of index space -in the text widget, and it may be referred to either by the name -of its embedded window or by its position in the widget's -index space. -If the range of text containing the embedded window is deleted then -the window is destroyed. - -When an embedded window is added to a text widget with the -B<widgetCreate> method, several configuration -options may be associated with it. -These options may be modified later with the B<widgetConfigure> -method. -The following options are currently supported: - -=over 4 - -=item B<-align> =E<gt> I<where> - -If the window is not as tall as the line in which it is displayed, -this option determines where the window is displayed in the line. -I<Where> must have one of the values B<top> (align the top of the window -with the top of the line), B<center> (center the window -within the range of the line), B<bottom> (align the bottom of the -window with the bottom of the line's area), -or B<baseline> (align the bottom of the window with the baseline -of the line). - -=item B<-create> =E<gt> I<callback> - -Specifies a L<callback|Tk::callbacks> that may be evaluated to create the window -for the annotation. -If no B<-window> option has been specified for the annotation -this I<callback> will be evaluated when the annotation is about to -be displayed on the screen. -I<Callback> must create a window for the annotation and return -the name of that window as its result. -If the annotation's window should ever be deleted, I<callback> -will be evaluated again the next time the annotation is displayed. - -=item B<-padx> =E<gt> I<pixels> - -I<Pixels> specifies the amount of extra space to leave on -each side of the embedded window. -It may have any of the usual forms defined for a screen distance -(see B<Tk_GetPixels>). - -=item B<-pady> =E<gt> I<pixels> - -I<Pixels> specifies the amount of extra space to leave on -the top and on the bottom of the embedded window. -It may have any of the usual forms defined for a screen distance -(see B<Tk_GetPixels>). - -=item B<-stretch> =E<gt> I<boolean> - -If the requested height of the embedded window is less than the -height of the line in which it is displayed, this option can be -used to specify whether the window should be stretched vertically -to fill its line. -If the B<-pady> option has been specified as well, then the -requested padding will be retained even if the window is -stretched. - -=item B<-window> =E<gt> I<$widget> - -Specifies the name of a window to display in the annotation. - -=back - -=head1 EMBEDDED IMAGES - -The final form of annotation in text widgets is an embedded image. -Each embedded image annotation causes an image to be displayed -at a particular point in the text. -There may be any number of embedded images in a text widget, -and a particular image may be embedded in multiple places in the same -text widget. -The embedded image's position on the screen will be updated as the -text is modified or scrolled. -Each embedded image occupies one character's worth of index space -in the text widget, and it may be referred to either by -its position in the widget's index space, or the name it is assigned -when the image is inserted into the text widget with B<imageCreate>. -If the range of text containing the embedded image is deleted then -that copy of the image is removed from the screen. - -When an embedded image is added to a text widget with the B<image> -create method, a name unique to this instance of the image -is returned. This name may then be used to refer to this image -instance. The name is taken to be the value of the B<-name> option -(described below). If the B<-name> option is not provided, the -B<-image> name is used instead. If the I<imageName> is already -in use in the text widget, then B<#>I<nn> is added to the end of the -I<imageName>, where I<nn> is an arbitrary integer. This insures -the I<imageName> is unique. -Once this name is assigned to this instance of the image, it does not -change, even though the B<-image> or B<-name> values can be changed -with B<image configure>. - -When an embedded image is added to a text widget with the -B<imageCreate> method, several configuration -options may be associated with it. -These options may be modified later with the B<image configure> -method. -The following options are currently supported: - -=over 4 - -=item B<-align> =E<gt> I<where> - -If the image is not as tall as the line in which it is displayed, -this option determines where the image is displayed in the line. -I<Where> must have one of the values B<top> (align the top of the image -with the top of the line), B<center> (center the image -within the range of the line), B<bottom> (align the bottom of the -image with the bottom of the line's area), -or B<baseline> (align the bottom of the image with the baseline -of the line). - -=item B<-image> =E<gt> I<image> - -Specifies the name of the Tk image to display in the annotation. -If I<image> is not a valid Tk image, then an error is returned. - -=item B<-name> =E<gt> I<ImageName> - -Specifies the name by which this image instance may be referenced in -the text widget. If I<ImageName> is not supplied, then the -name of the Tk image is used instead. -If the I<imageName> is already in use, I<#nn> is appended to -the end of the name as described above. - -=item B<-padx> =E<gt> I<pixels> - -I<Pixels> specifies the amount of extra space to leave on -each side of the embedded image. -It may have any of the usual forms defined for a screen distance. - -=item B<-pady> =E<gt> I<pixels> - -I<Pixels> specifies the amount of extra space to leave on -the top and on the bottom of the embedded image. -It may have any of the usual forms defined for a screen distance. - -=back - -=head1 THE SELECTION - -Selection support is implemented via tags. -If the B<exportSelection> option for the text widget is true -then the B<sel> tag will be associated with the selection: - -=over 4 - -=item [1] - -Whenever characters are tagged with B<sel> the text widget -will claim ownership of the selection. - -=item [2] - -Attempts to retrieve the -selection will be serviced by the text widget, returning all the -characters with the B<sel> tag. - -=item [3] - -If the selection is claimed away by another application or by another -window within this application, then the B<sel> tag will be removed -from all characters in the text. - -=item [4] - -Whenever the sel tag range changes a virtual event B<<<Selection>>> -is generated. - -The B<sel> tag is automatically defined when a text widget is -created, and it may not be deleted with the ``I<$text>-E<gt>B<tagDelete>'' -method. Furthermore, the B<selectBackground>, -B<selectBorderWidth>, and B<selectForeground> options for -the text widget are tied to the B<-background>, -B<-borderwidth>, and B<-foreground> options for the B<sel> -tag: changes in either will automatically be reflected in the -other. - -=back - -=head1 THE INSERTION CURSOR - -The mark named B<insert> has special significance in text widgets. -It is defined automatically when a text widget is created and it -may not be unset with the ``I<$text>-E<gt>B<markUnset>'' widget -command. -The B<insert> mark represents the position of the insertion -cursor, and the insertion cursor will automatically be drawn at -this point whenever the text widget has the input focus. - -=head1 THE MODIFIED FLAG - -The text widget can keep track of changes to the content of the widget -by means of the modified flag. Inserting or deleting text will set this -flag. The flag can be queried, set and cleared programatically as well. -Whenever the flag changes state a B<<<Modified>>> virtual event is gener- -ated. See the edit modified widget command for more details. - - -=head1 WIDGET METHODS - -The B<Text> method creates a widget object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. -The widget also inherits all the methods provided by the generic -L<Tk::Widget|Tk::Widget> class. - -The following additional methods are available for text widgets. -In addition, the extended text widget methods as documented -in I<"Mastering Perl/Tk"> are included in this pod (with -permission from the publisher, B<O'Reilly and Associates Inc.>). - -=over 4 - -=item I<$text>-E<gt>B<adjustSelect> - -Moves the end point of the selection and anchor point to the -mouse pointer location. - -=item I<$text>-E<gt>B<bbox>(I<index>) - -Returns a list of four elements describing the screen area -of the character given by I<index>. -The first two elements of the list give the x and y coordinates -of the upper-left corner of the area occupied by the -character, and the last two elements give the width and height -of the area. -If the character is only partially visible on the screen, then -the return value reflects just the visible part. -If the character is not visible on the screen then the return -value is an empty list. - -=item I<$text>-E<gt>B<clipboardColumnCopy> - -Performs a rectangular copy of the currently selected text with -basic compensation for tab characters. - -=item I<$text>-E<gt>B<clipboardColumnCut> - -Performs a rectangular cut of the currently selected text with -basic compensation for tab characters. - -=item I<$text>-E<gt>B<clipboardColumnPaste> - -Performs a rectangular paste of the text in the clipboard. The -upper-left corner is specified by the current position of the -insert mark with basic compensation for tab characters. - -=item I<$text>-E<gt>B<compare>(I<index1, op, index2>) - -Compares the indices given by I<index1> and I<index2> according -to the relational operator given by I<op>, and returns 1 if -the relationship is satisfied and 0 if it isn't. -I<Op> must be one of the operators E<lt>, E<lt>=, ==, E<gt>=, E<gt>, or !=. -If I<op> is == then 1 is returned if the two indices refer to -the same character, if I<op> is E<lt> then 1 is returned if I<index1> -refers to an earlier character in the text than I<index2>, and -so on. - -=item I<$text>-E<gt>B<Contents>(I<?args>?) - -Query or change the entire contents of the text widget. If no -arguments are given, the entire contents of the text widget are -returned. If any arguments are given, the entire contents of the -text widget are deleted and replaced by the argument list. - -=item I<$text>-E<gt>B<debug>(?I<boolean>?) - -If I<boolean> is specified, then it must have one of the true or -false values accepted by Tcl_GetBoolean. -If the value is a true one then internal consistency checks will be -turned on in the B-tree code associated with text widgets. -If I<boolean> has a false value then the debugging checks will -be turned off. -In either case the command returns an empty string. -If I<boolean> is not specified then the command returns B<on> -or B<off> to indicate whether or not debugging is turned on. -There is a single debugging switch shared by all text widgets: turning -debugging on or off in any widget turns it on or off for all widgets. -For widgets with large amounts of text, the consistency checks may -cause a noticeable slow-down. - -=item I<$text>-E<gt>B<delete>(I<index1, >?I<index2>?) - -Delete a range of characters from the text. -If both I<index1> and I<index2> are specified, then delete -all the characters starting with the one given by I<index1> -and stopping just before I<index2> (i.e. the character at -I<index2> is not deleted). -If I<index2> doesn't specify a position later in the text -than I<index1> then no characters are deleted. -If I<index2> isn't specified then the single character at -I<index1> is deleted. -It is not allowable to delete characters in a way that would leave -the text without a newline as the last character. -The command returns an empty string. -If more indices are given, multiple ranges of text will -be deleted. All indices are first checked for validity before -any deletions are made. They are sorted and the text is removed -from the last range to the first range to deleted text does not -cause a undesired index shifting side-effects. If multiple -ranges with the same start index are given, then the longest -range is used. If overlapping ranges are given, then they will -be merged into spans that do not cause deletion of text outside -the given ranges due to text shifted during deletion. - -=item I<$text>-E<gt>B<deleteSelected> - -Delete the currently selected text. - -=item I<$text>-E<gt>B<deleteTextTaggedWith>(I<tag>) - -Delete the text tagged with the I<tag> parameter. - -=item I<$text>-E<gt>B<deleteToEndofLine> - -Delete from the insert mark location to the end of line. - -=item I<$text>-E<gt>B<dlineinfo>(I<index>) - -Returns a list with five elements describing the area occupied -by the display line containing I<index>. -The first two elements of the list give the x and y coordinates -of the upper-left corner of the area occupied by the -line, the third and fourth elements give the width and height -of the area, and the fifth element gives the position of the baseline -for the line, measured down from the top of the area. -All of this information is measured in pixels. -If the current wrap mode is B<none> and the line extends beyond -the boundaries of the window, -the area returned reflects the entire area of the line, including the -portions that are out of the window. -If the line is shorter than the full width of the window then the -area returned reflects just the portion of the line that is occupied -by characters and embedded windows. -If the display line containing I<index> is not visible on -the screen then the return value is an empty list. - -=item I<$text>-E<gt>B<dump>(?I<switches>?, I<index1, >?I<index2>?) - -Return the contents of the text widget from I<index1> up to, -but not including I<index2>, -including the text and -information about marks, tags, and embedded windows. -If I<index2> is not specified, then it defaults to -one character past I<index1>. The information is returned -in the following format: - -I<key1 value1 index1 key2 value2 index2> ... - -The possible I<key> values are B<text>, B<mark>, -B<tagon>, B<tagoff>, and I<$text>. The corresponding -I<value> is the text, mark name, tag name, or window name. -The I<index> information is the index of the -start of the text, the mark, the tag transition, or the window. -One or more of the following switches (or abbreviations thereof) -may be specified to control the dump: - -=over 4 - -=item B<-all> - -Return information about all elements: text, marks, tags, and windows. -This is the default. - -=item B<-command> =E<gt> I<callback> - -Instead of returning the information as the result of the dump operation, -invoke the I<callback> on each element of the text widget within the range. -The callback has three arguments appended to it before it is evaluated: -the I<key>, I<value>, and I<index>. - -=item B<-mark> - -Include information about marks in the dump results. - -=item B<-tag> - -Include information about tag transitions in the dump results. Tag information is -returned as B<tagon> and B<tagoff> elements that indicate the -begin and end of each range of each tag, respectively. - -=item B<-text> - -Include information about text in the dump results. The value is the -text up to the next element or the end of range indicated by I<index2>. -A text element does not span newlines. A multi-line block of text that -contains no marks or tag transitions will still be dumped as a set -of text seqments that each end with a newline. The newline is part -of the value. - -=item B<-window> - -=back - -Include information about embedded windows in the dump results. -The value of a window is its Tk pathname, unless the window -has not been created yet. (It must have a create script.) -In this case an empty string is returned, and you must query the -window by its index position to get more information. - -=item I<$text>-E<gt>B<edit>( I< option, ?arg, arg ...?> ); - -This command controls the undo mechanism and the modified flag. -The exact behavior of the command depends on the option argument -that follows the edit argument. The following forms of the command -are currently supported: - -=over 4 - -=item I<$text>-E<gt>B<editModified>( ?boolean? ); - -If boolean is not specified, returns the modified flag of -the widget. The insert, delete, edit undo and edit redo -commands or the user can set or clear the modified flag. -If boolean is specified, sets the modified flag of the -widget to boolean. - -=item I<$text>-E<gt>B<editRedo>; - -(Not implemented, use B<TextUndo>.) When the B<-undo> option is true, -reapplies the last undone edits provided no other edits were done -since then. Generates an error when the redo stack is empty. Does -nothing when the B<-undo> option is false. - -=item I<$text>-E<gt>B<editReset>; - -(Not implemented, use B<TextUndo>.) Clears the undo and redo stacks. - -=item I<$text>-E<gt>B<editSeparator>; - -(Not implemented, use B<TextUndo>.) Inserts a separator (boundary) on -the undo stack. Does nothing when the -undo option is false. - -=item I<$text>-E<gt>B<editUndo>; - -(Not implemented, use B<TextUndo>.) Undoes the last edit action when -the -undo option is true. An edit action is defined as all the insert -and delete commands that are recorded on the undo stack in between two -separators. Generates an error when the undo stack is empty. Does -nothing when the -undo option is false. - -=back - -=item I<$text>-E<gt>B<FindAll>(I<mode, case, pattern>) - -Removes any current selections and then performs a global text -search. All matches are tagged with the B<sel> tag. - -I<mode> can be be B<-exact> or B<-regexp>. See the B<search> command -for more information - -I<case> can be B<-nocase> or B<-case>. See the B<search> command -for more information - -I<pattern> is an exact string to match if I<mode> is B<-exact> or a -regular expression if the match I<mode> is B<-regexp>. - - -=item I<$text>-E<gt>B<FindAndReplaceAll>(I<mode, case, find, replace>) - -Same as the B<FindAll> method, however additionally substitutes the -matched text with the characters I<replace>. - -=item I<$text>-E<gt>B<FindAndReplacePopUp> - -Creates a find-and-replace popup window if one does not already exist. -If there is currently selected text, then the 'find' field will be -'pre-filled' with the selection. - -=item I<$text>-E<gt>B<FindNext>(I<direction, mode, case, pattern>) - -Removes any current selections and then performs a forward or reverse -text search. All matches are tagged with the B<sel> tag. I<direction> -can be B<-forwards> or B<-backwards>. I<mode, case> and I<pattern> are -as for the B<FindAll> method. - -=item I<$text>-E<gt>B<FindPopUp> - -Creates a find popup, if one does not yet exist. If there is currently -selected text, then the 'find' field will be 'pre-filled' with the -selection. - -=item I<$text>-E<gt>B<FindSelectionNext> - -Gets the currently selected text and removes all selections. It then -finds the next exact, case-sensitive string that matches in a forward -direction and selects the text and makes the new selection visible. - -=item I<$text>-E<gt>B<FindSelectionPrevious> - -Gets the currently selected text and removes all selections. It then -finds the next exact, case-sensitive string that matches in a reverse -direction and selects the text and makes the new selection visible. - -=item I<$text>-E<gt>B<get>(I<index1, >?I<index2>?) - -Return a range of characters from the text. The return value will be -all the characters in the text starting with the one whose index is -I<index1> and ending just before the one whose index is I<index2> (the -character at I<index2> will not be returned). If I<index2> is omitted -then the single character at I<index1> is returned. If there are no -characters in the specified range (e.g. I<index1> is past the end of -the file or I<index2> is less than or equal to I<index1>) then an -empty string is returned. If the specified range contains embedded -windows, no information about them is included in the returned string. -If multiple index pairs are given, multiple ranges of text will be -returned in a list. Invalid ranges will not be represented with empty -strings in the list. The ranges are returned in the order passed to -B<get>. - -=item I<$text>-E<gt>B<getSelected> - -Return the currently selected text. - -=item I<$text>-E<gt>B<GetTextTaggedWith>(I<tag>) - -Return the text tagged with the I<tag> parameter. - -=item I<$text>-E<gt>B<GotoLineNumber>(I<line_number>) - -Set the insert mark to I<line_number> and ensures the line is -visible. - -=item I<$text>-E<gt>B<GotoLineNumberPopUp>(I<line_number>) - -Displays a popup, pre-filling it with selected numeric text -(if any), or the line number from B<GotoLineNumber> (if any). - -=item I<$text>-E<gt>B<image>(I<option>, ?I<arg, arg, ...>?) - -=item I<$text>-E<gt>B<image>I<Option>(?I<arg, arg, ...>?) - -This method is used to manipulate embedded images. -The behavior of the method depends on the I<option> argument -that follows the B<image> prefix. -The following forms of the methods are currently supported: - -=over 8 - -=item I<$text>-E<gt>B<imageCget>(I<index, option>) - -Returns the value of a configuration option for an embedded image. -I<Index> identifies the embedded image, and I<option> -specifies a particular configuration option, which must be one of -the ones listed in L<"EMBEDDED IMAGES">. - -=item I<$text>-E<gt>B<imageConfigure>(I<index, >?I<option, value, ...>?) - -Query or modify the configuration options for an embedded image. -If no I<option> is specified, returns a list describing all of -the available options for the embedded image at I<index> -(see L<Tk::options> for information on the format of this list). -If I<option> is specified with no I<value>, then the command -returns a list describing the one named option (this list will be -identical to the corresponding sublist of the value returned if no -I<option> is specified). -If one or more I<option-value> pairs are specified, then the command -modifies the given option(s) to have the given value(s); in -this case the command returns an empty string. -See L<"EMBEDDED IMAGES"> for information on the options that -are supported. - -=item I<$text>-E<gt>B<imageCreate>(I<index, >?I<option, value, ...>?) - -This command creates a new image annotation, which will appear -in the text at the position given by I<index>. -Any number of I<option-value> pairs may be specified to -configure the annotation. -Returns a unique identifier that may be used as an index to refer to -this image. -See L<"EMBEDDED IMAGES"> for information on the options that -are supported, and a description of the identifier returned. - -=item I<$text>-E<gt>B<imageNames> - -Returns a list whose elements are the names of all image instances currently -embedded in $text. - -=back - -=item I<$text>-E<gt>B<index>(I<index>) - -Returns the position corresponding to I<index> in the form -I<line.char> where I<line> is the line number and I<char> -is the character number. -I<Index> may have any of the forms described under L<"INDICES"> above. - -=item I<$text>-E<gt>B<insert>(I<index, chars, >?I<tagList, chars, tagList, ...>?) - -Inserts all of the I<chars> arguments just before the character at -I<index>. -If I<index> refers to the end of the text (the character after -the last newline) then the new text is inserted just before the -last newline instead. -If there is a single I<chars> argument and no I<tagList>, then -the new text will receive any tags that are present on both the -character before and the character after the insertion point; if a tag -is present on only one of these characters then it will not be -applied to the new text. -If I<tagList> is specified then it consists of a list of -tag names; the new characters will receive all of the tags in -this list and no others, regardless of the tags present around -the insertion point. -If multiple I<chars>-I<tagList> argument pairs are present, -they produce the same effect as if a separate B<insert> widget -command had been issued for each pair, in order. -The last I<tagList> argument may be omitted. - -=item I<$text>-E<gt>B<Insert>(I<string>) - -Do NOT confuse this with the lower-case B<insert> method. -Insert I<string> at the point of the insertion cursor. If there is -a selection in the text, and it covers the point of the insertion -cursor, then it deletes the selection before inserting. - -=item I<$text>-E<gt>B<InsertKeypress>(I<character>) - -Inserts I<character> at the B<insert> mark. If in overstrike mode, -it firsts deletes the character at the B<insert> mark. - -=item I<$text>-E<gt>B<InsertSelection> - -Inserts the current selection at the B<insert> mark. - -=item I<$text>-E<gt>B<insertTab> - -Inserts a tab (\t) character at the B<insert> mark. - -=item I<$text>-E<gt>B<mark>(I<option, >?I<arg, arg, ...>?) - -This command is used to manipulate marks. The exact behavior of -the command depends on the I<option> argument that follows -the B<mark> argument. The following forms of the command -are currently supported: - -=over 8 - -=item I<$text>-E<gt>B<markGravity>(I<markName, >?I<direction>?) - -If I<direction> is not specified, returns B<left> or B<right> -to indicate which of its adjacent characters I<markName> is attached -to. -If I<direction> is specified, it must be B<left> or B<right>; -the gravity of I<markName> is set to the given value. - -=item I<$text>-E<gt>B<markNames> - -Returns a list whose elements are the names of all the marks that -are currently set. - -=item I<$text>-E<gt>B<markNext>(I<index>) - -Returns the name of the next mark at or after I<index>. -If I<index> is specified in numerical form, then the search for -the next mark begins at that index. -If I<index> is the name of a mark, then the search for -the next mark begins immediately after that mark. -This can still return a mark at the same position if -there are multiple marks at the same index. -These semantics mean that the B<mark next> operation can be used to -step through all the marks in a text widget in the same order -as the mark information returned by the B<dump> operation. -If a mark has been set to the special B<end> index, -then it appears to be I<after> B<end> with respect to the B<mark next> operation. -An empty string is returned if there are no marks after I<index>. - -=item I<$text>-E<gt>B<markPrevious>(I<index>) - -Returns the name of the mark at or before I<index>. -If I<index> is specified in numerical form, then the search for -the previous mark begins with the character just before that index. -If I<index> is the name of a mark, then the search for -the next mark begins immediately before that mark. -This can still return a mark at the same position if -there are multiple marks at the same index. -These semantics mean that the B<mark previous> operation can be used to -step through all the marks in a text widget in the reverse order -as the mark information returned by the B<dump> operation. -An empty string is returned if there are no marks before I<index>. - -=item I<$text>-E<gt>B<markSet>(I<markName, index>) - -Sets the mark named I<markName> to a position just before the -character at I<index>. -If I<markName> already exists, it is moved from its old position; -if it doesn't exist, a new mark is created. -This command returns an empty string. - -=item I<$text>-E<gt>B<markUnset>(I<markName>?, I<markName, markName, ...>?) - -Remove the mark corresponding to each of the I<markName> arguments. -The removed marks will not be usable in indices and will not be -returned by future calls to ``I<$text>-E<gt>B<markNames>''. -This command returns an empty string. - -=back - -=item I<$text>-E<gt>B<markExists>(I<markname>) - -Returns true if I<markname> exists - false otherwise. - -=item I<$text>-E<gt>B<menu>(I<?menu?>) - -If I<menu> reference is given as an argument, then the text widget -menu is adjusted to use this new I<menu>. If the I<menu> argument -is B<undef>, then this command disables the current text widget menu. -If the I<menu> argument is omitted altogether, then the current text -widget menu reference is returned. - -=item I<$text>-E<gt>B<openLine> - -Inserts a newline (\n) at the insert mark. - -=item I<$text>-E<gt>B<OverstrikeMode>(I<?boolean?>) - -Returns the overstrike mode if I<boolean> is omitted or sets the -overstrike mode to I<boolean>. True means overstrike mode is enabled. - -=item I<$text>-E<gt>B<PostPopupMenu>(I<x,y>) - -Creates a popup menu at the specified (I<x,y>) pixel coordinates. The -default menu has File, Edit, Search and View menu items which cascade -to sub-menus for further commands. There is an implicit E<lt>Button-3E<gt> -binding to this method that posts the menu over the cursor. - -=item I<$text>-E<gt>B<ResetAnchor> - -Sets the selection anchor to whichever end is farthest from the index -argument. - -=item I<$text>-E<gt>B<scan>(I<option>, I<args>) or - -=item I<$text>-E<gt>B<scan>I<option>(I<args>) - -This method is used to implement scanning on texts. It has -two forms, depending on I<option>: - -=over 8 - -=item I<$text>-E<gt>B<scanMark>(I<x, y>) - -Records I<x> and I<y> and the current view in the text window, -for use in conjunction with later B<scanDragto> method. -Typically this method is associated with a mouse button press in -the widget. It returns an empty string. - -=item I<$text>-E<gt>B<scanDragto>(I<x, y>) - -This command computes the difference between its I<x> and I<y> -arguments and the I<x> and I<y> arguments to the last -B<scanMark> method for the widget. -It then adjusts the view by 10 times the difference in coordinates. -This command is typically associated -with mouse motion events in the widget, to produce the effect of -dragging the text at high speed through the window. The return -value is an empty string. - -=back - -=item I<$text>-E<gt>B<search>(?I<switches>,? I<pattern, index, >?I<stopIndex>?) - -Searches the text in I<$text> starting at I<index> for a range -of characters that matches I<pattern>. -If a match is found, the index of the first character in the match is -returned as result; otherwise an empty string is returned. -One or more of the following switches (or abbreviations thereof) -may be specified to control the search: - -=over 8 - -=item B<-forwards> - -The search will proceed forward through the text, finding the first -matching range starting at or after the position given by I<index>. -This is the default. - -=item B<-backwards> - -The search will proceed backward through the text, finding the -matching range closest to I<index> whose first character -is before I<index>. - -=item B<-exact> - -Use exact matching: the characters in the matching range must be -identical to those in I<pattern>. -This is the default. - -=item B<-regexp> - -Treat I<pattern> as a regular expression and match it against -the text using the rules for regular expressions (see the B<regexp> -command for details). - -=item B<-nocase> - -Ignore case differences between the pattern and the text. - -=item B<-count>I< varName> - -The argument following B<-count> gives the name of a variable; -if a match is found, the number of characters in the matching -range will be stored in the variable. - -=item B<-hidden> - -Find hidden text as well. By default only displayed text is found. - -=item B<--> - -This switch has no effect except to terminate the list of switches: -the next argument will be treated as I<pattern> even if it starts -with B<->. - -=back - -=back - -The matching range must be entirely within a single line of text. -For regular expression matching the newlines are removed from the ends -of the lines before matching: use the B<$> feature in regular -expressions to match the end of a line. -For exact matching the newlines are retained. -If I<stopIndex> is specified, the search stops at that index: -for forward searches, no match at or after I<stopIndex> will -be considered; for backward searches, no match earlier in the -text than I<stopIndex> will be considered. -If I<stopIndex> is omitted, the entire text will be searched: -when the beginning or end of the text is reached, the search -continues at the other end until the starting location is reached -again; if I<stopIndex> is specified, no wrap-around will occur. - -=over 4 - -=item I<$text>-E<gt>B<see>(I<index>) - -Adjusts the view in the window so that the character given by I<index> -is completely visible. -If I<index> is already visible then the command does nothing. -If I<index> is a short distance out of view, the command -adjusts the view just enough to make I<index> visible at the -edge of the window. -If I<index> is far out of view, then the command centers -I<index> in the window. - -=item I<$text>-E<gt>B<selectAll> - -Selects all the text in the widget. - -=item I<$text>-E<gt>B<selectLine> - -Selects the line with the insert mark. - -=item I<$text>-E<gt>B<selectWord> - -Selects the word with the insert mark. - -=item I<$text>-E<gt>B<SetCursor>(I<position>) - -Moves the insert mark to I<position>. - -=item I<$text>-E<gt>B<tag>(I<option, >?I<arg, arg, ...>?) - -This command is used to manipulate tags. The exact behavior of the -command depends on the I<option> argument that follows the -B<tag> argument. The following forms of the command are currently -supported: - -=over 8 - -=item I<$text>-E<gt>B<tagAdd>(I<tagName, index1, >?I<index2, index1, index2, ...>?) - -Associate the tag I<tagName> with all of the characters starting -with I<index1> and ending just before -I<index2> (the character at I<index2> isn't tagged). -A single command may contain any number of I<index1>-I<index2> -pairs. -If the last I<index2> is omitted then the single character at -I<index1> is tagged. -If there are no characters in the specified range (e.g. I<index1> -is past the end of the file or I<index2> is less than or equal -to I<index1>) then the command has no effect. - -=item I<$text>-E<gt>B<tagBind>(I<tagName, >?I<sequence>?, ?I<script>?) - -This command associates I<script> with the tag given by -I<tagName>. -Whenever the event sequence given by I<sequence> occurs for a -character that has been tagged with I<tagName>, -the script will be invoked. -This method is similar to the B<bind> command except that -it operates on characters in a text rather than entire widgets. -See the L<Tk::bind> documentation for complete details -on the syntax of I<sequence> and the substitutions performed -on I<script> before invoking it. -If all arguments are specified then a new binding is created, replacing -any existing binding for the same I<sequence> and I<tagName> -(if the first character of I<script> is ``+'' then I<script> -augments an existing binding rather than replacing it). -In this case the return value is an empty string. -If I<script> is omitted then the command returns the I<script> -associated with I<tagName> and I<sequence> (an error occurs -if there is no such binding). -If both I<script> and I<sequence> are omitted then the command -returns a list of all the sequences for which bindings have been -defined for I<tagName>. - -The only events for which bindings may be specified are those related -to the mouse and keyboard (such as B<Enter>, B<Leave>, -B<ButtonPress>, B<Motion>, and B<KeyPress>) or virtual events. -Event bindings for a text widget use the B<current> mark described -under L<"MARKS"> above. An B<Enter> event triggers for a tag when the tag -first becomes present on the current character, and a B<Leave> event -triggers for a tag when it ceases to be present on the current character. -B<Enter> and B<Leave> events can happen either because the -B<current> mark moved or because the character at that position -changed. Note that these events are different than B<Enter> and -B<Leave> events for windows. Mouse and keyboard events are directed -to the current character. If a virtual event is used in a binding, that -binding can trigger only if the virtual event is defined by an underlying -mouse-related or keyboard-related event. - -It is possible for the current character to have multiple tags, -and for each of them to have a binding for a particular event -sequence. -When this occurs, one binding is invoked for each tag, in order -from lowest-priority to highest priority. -If there are multiple matching bindings for a single tag, then -the most specific binding is chosen (see the the documentation for -the B<bind> command for details). -B<continue> and B<break> commands within binding scripts -are processed in the same way as for bindings created with -the B<bind> command. - -If bindings are created for the widget as a whole using the -B<bind> command, then those bindings will supplement the -tag bindings. -The tag bindings will be invoked first, followed by bindings -for the window as a whole. - -=item I<$text>-E<gt>B<tagCget>(I<tagName, option>) - -This command returns the current value of the option named I<option> -associated with the tag given by I<tagName>. -I<Option> may have any of the values accepted by the B<tag configure> -method. - -=item I<$text>-E<gt>B<tagConfigure>(I<tagName, >?I<option>?, ?I<value>?, ?I<option, value, ...>?) - -This command is similar to the B<configure> method except -that it modifies options associated with the tag given by I<tagName> -instead of modifying options for the overall text widget. -If no I<option> is specified, the command returns a list describing -all of the available options for I<tagName> -(see L<Tk::options> for information on the format of this list). -If I<option> is specified with no I<value>, then the command returns -a list describing the one named option (this list will be identical to -the corresponding sublist of the value returned if no I<option> -is specified). -If one or more I<option-value> pairs are specified, then the command -modifies the given option(s) to have the given value(s) in I<tagName>; -in this case the command returns an empty string. -See L<"TAGS"> above for details on the options available for tags. - -=item I<$text>-E<gt>B<tagDelete>(I<tagName, >?I<tagName, ...>?) - -Deletes all tag information for each of the I<tagName> -arguments. -The command removes the tags from all characters in the file -and also deletes any other information associated with the tags, -such as bindings and display information. -The command returns an empty string. - -=item I<$text>-E<gt>B<tagLower>(I<tagName>?, I<belowThis>?) - -Changes the priority of tag I<tagName> so that it is just lower -in priority than the tag whose name is I<belowThis>. -If I<belowThis> is omitted, then I<tagName>'s priority -is changed to make it lowest priority of all tags. - -=item I<$text>-E<gt>B<tagNames>(?I<index>?) - -Returns a list whose elements are the names of all the tags that -are active at the character position given by I<index>. -If I<index> is omitted, then the return value will describe -all of the tags that exist for the text (this includes all tags -that have been named in a ``I<$text>-E<gt>B<tag>'' widget -command but haven't been deleted by a ``I<$text>-E<gt>B<tagDelete>'' -method, even if no characters are currently marked with -the tag). -The list will be sorted in order from lowest priority to highest -priority. - -=item I<$text>-E<gt>B<tagNextrange>(I<tagName, index1, >?I<index2>?) - -This command searches the text for a range of characters tagged -with I<tagName> where the first character of the range is -no earlier than the character at I<index1> and no later than -the character just before I<index2> (a range starting at -I<index2> will not be considered). -If several matching ranges exist, the first one is chosen. -The command's return value is a list containing -two elements, which are the index of the first character of the -range and the index of the character just after the last one in -the range. -If no matching range is found then the return value is an -empty string. -If I<index2> is not given then it defaults to the end of the text. - -=item I<$text>-E<gt>B<tagPrevrange>(I<tagName, index1, >?I<index2>?) - -This command searches the text for a range of characters tagged -with I<tagName> where the first character of the range is -before the character at I<index1> and no earlier than -the character at I<index2> (a range starting at -I<index2> will be considered). -If several matching ranges exist, the one closest to I<index1> is chosen. -The command's return value is a list containing -two elements, which are the index of the first character of the -range and the index of the character just after the last one in -the range. -If no matching range is found then the return value is an -empty string. -If I<index2> is not given then it defaults to the beginning of the text. - -=item I<$text>-E<gt>B<tagRaise>(I<tagName, >?I<aboveThis>?) - -Changes the priority of tag I<tagName> so that it is just higher -in priority than the tag whose name is I<aboveThis>. -If I<aboveThis> is omitted, then I<tagName>'s priority -is changed to make it highest priority of all tags. - -=item I<$text>-E<gt>B<tagRanges>(I<tagName>) - -Returns a list describing all of the ranges of text that have been -tagged with I<tagName>. -The first two elements of the list describe the first tagged range -in the text, the next two elements describe the second range, and -so on. -The first element of each pair contains the index of the first -character of the range, and the second element of the pair contains -the index of the character just after the last one in the -range. -If there are no characters tagged with I<tag> then an -empty string is returned. - -=item I<$text>-E<gt>B<tagRemove>(I<tagName, index1, >?I<index2, index1, index2, ...>?) - -Remove the tag I<tagName> from all of the characters starting -at I<index1> and ending just before -I<index2> (the character at I<index2> isn't affected). -A single command may contain any number of I<index1>-I<index2> -pairs. -If the last I<index2> is omitted then the single character at -I<index1> is tagged. -If there are no characters in the specified range (e.g. I<index1> -is past the end of the file or I<index2> is less than or equal -to I<index1>) then the command has no effect. -This command returns an empty string. - -=back - -=item I<$text>-E<gt>B<ToggleInsertMode> - -Toggles the current overstrike mode. - -=item I<$text>-E<gt>B<unselectAll> - -Unselects all the text in the widget. - -=item I<$text>-E<gt>B<WhatLineNumberPopup> - -Creates a popup that displays the current line number of the -insert mark. - -=item I<$text>->B<widget>(I<option?, arg, arg, ...>?) - -=item I<$text>->B<widget>I<Option>(?I<arg, arg, ...>?) - -This method is used to manipulate embedded windows. -The behavior of the method depends on the I<option> argument -that follows the B<window> argument. -The following forms of the method are currently supported: - -=over 8 - -=item I<$text>->B<windowCget>(I<index, option>) - -Returns the value of a configuration option for an embedded window. -I<Index> identifies the embedded window, and I<option> -specifies a particular configuration option, which must be one of -the ones listed in L<"EMBEDDED WINDOWS"> above. - -=item I<$text>->B<windowConfigure>(I<index>?, I<option, value, ...>?) - -Query or modify the configuration options for an embedded window. -If no I<option> is specified, returns a list describing all of -the available options for the embedded window at I<index> -(see L<Tk::options> for information on the format of this list). -If I<option> is specified with no I<value>, then the command -returns a list describing the one named option (this list will be -identical to the corresponding sublist of the value returned if no -I<option> is specified). -If one or more I<option-value> pairs are specified, then the command -modifies the given option(s) to have the given value(s); in -this case the command returns an empty string. -See L<"EMBEDDED WINDOWS"> above for information on the options that -are supported. - -=item I<$text>->B<windowCreate>(I<index>?, I<option, value, ...>?) - -This command creates a new window annotation, which will appear -in the text at the position given by I<index>. -Any number of I<option-value> pairs may be specified to -configure the annotation. -See L<"EMBEDDED WINDOWS"> above for information on the options that -are supported. -Returns an empty string. - -=item I<$text>->B<windowNames> - -Returns a list whose elements are the names of all windows currently -embedded in $text. - -=back - -=item I<$text>->B<xview>(I<option, args>) - -This command is used to query and change the horizontal position of the -text in the widget's window. It can take any of the following -forms: - -=over 8 - -=item I<$text>->B<xview> - -Returns a list containing two elements. -Each element is a real fraction between 0 and 1; together they describe -the portion of the document's horizontal span that is visible in -the window. -For example, if the first element is .2 and the second element is .6, -20% of the text is off-screen to the left, the middle 40% is visible -in the window, and 40% of the text is off-screen to the right. -The fractions refer only to the lines that are actually visible in the -window: if the lines in the window are all very short, so that they -are entirely visible, the returned fractions will be 0 and 1, -even if there are other lines in the text that are -much wider than the window. -These are the same values passed to scrollbars via the B<-xscrollcommand> -option. - -=item I<$text>-E<gt>B<xviewMoveto>(I<fraction>) - -Adjusts the view in the window so that I<fraction> of the horizontal -span of the text is off-screen to the left. -I<Fraction> is a fraction between 0 and 1. - -=item I<$text>-E<gt>B<xviewScroll>(I<number, what>) - -This command shifts the view in the window left or right according to -I<number> and I<what>. -I<Number> must be an integer. -I<What> must be either B<units> or B<pages> or an abbreviation -of one of these. -If I<what> is B<units>, the view adjusts left or right by -I<number> average-width characters on the display; if it is -B<pages> then the view adjusts by I<number> screenfuls. -If I<number> is negative then characters farther to the left -become visible; if it is positive then characters farther to the right -become visible. - -=back - -=item I<$text>-E<gt>B<yview>(I<?args>?) - -This command is used to query and change the vertical position of the -text in the widget's window. -It can take any of the following forms: - -=over 8 - -=item I<$text>-E<gt>B<yview> - -Returns a list containing two elements, both of which are real fractions -between 0 and 1. -The first element gives the position of the first character in the -top line in the window, relative to the text as a whole (0.5 means -it is halfway through the text, for example). -The second element gives the position of the character just after -the last one in the bottom line of the window, -relative to the text as a whole. -These are the same values passed to scrollbars via the B<-yscrollcommand> -option. - -=item I<$text>-E<gt>B<yviewMoveto>(I<fraction>) - -Adjusts the view in the window so that the character given by I<fraction> -appears on the top line of the window. -I<Fraction> is a fraction between 0 and 1; 0 indicates the first -character in the text, 0.33 indicates the character one-third the -way through the text, and so on. - -=item I<$text>-E<gt>B<yviewScroll>(I<number, what>) - -This command adjust the view in the window up or down according to -I<number> and I<what>. -I<Number> must be an integer. -I<What> must be either B<units> or B<pages>. -If I<what> is B<units>, the view adjusts up or down by -I<number> lines on the display; if it is B<pages> then -the view adjusts by I<number> screenfuls. -If I<number> is negative then earlier positions in the text -become visible; if it is positive then later positions in the text -become visible. - -=item I<$text>->B<yview>(?B<-pickplace>,? I<index>) - -Changes the view in the I<$text>'s window to make I<index> visible. -If the B<-pickplace> option isn't specified then I<index> will -appear at the top of the window. -If B<-pickplace> is specified then the widget chooses where -I<index> appears in the window: - -=over 12 - -=item [1] - -If I<index> is already visible somewhere in the window then the -command does nothing. - -=item [2] - -If I<index> is only a few lines off-screen above the window then -it will be positioned at the top of the window. - -=item [3] - -If I<index> is only a few lines off-screen below the window then -it will be positioned at the bottom of the window. - -=item [4] - -Otherwise, I<index> will be centered in the window. - -=back - -=back - -=back - -The B<-pickplace> option has been obsoleted by the B<see> widget -command (B<see> handles both x- and y-motion to make a location -visible, whereas B<-pickplace> only handles motion in y). - -=over 4 - -=item I<$text>-E<gt>B<yview>(I<number>) - -This command makes the first character on the line after -the one given by I<number> visible at the top of the window. -I<Number> must be an integer. -This command used to be used for scrolling, but now it is obsolete. - -=back - -=head1 BINDINGS - -Tk automatically creates class bindings for texts that give them -the following default behavior. -In the descriptions below, ``word'' refers to a contiguous group -of letters, digits, or ``_'' characters, or any single character -other than these. - -=over 4 - -=item [1] - -Clicking mouse button 1 positions the insertion cursor -just before the character underneath the mouse cursor, sets the -input focus to this widget, and clears any selection in the widget. -Dragging with mouse button 1 strokes out a selection between -the insertion cursor and the character under the mouse. - -=item [2] - -Double-clicking with mouse button 1 selects the word under the mouse -and positions the insertion cursor at the beginning of the word. -Dragging after a double click will stroke out a selection consisting -of whole words. - -=item [3] - -Triple-clicking with mouse button 1 selects the line under the mouse -and positions the insertion cursor at the beginning of the line. -Dragging after a triple click will stroke out a selection consisting -of whole lines. - -=item [4] - -The ends of the selection can be adjusted by dragging with mouse -button 1 while the Shift key is down; this will adjust the end -of the selection that was nearest to the mouse cursor when button -1 was pressed. -If the button is double-clicked before dragging then the selection -will be adjusted in units of whole words; if it is triple-clicked -then the selection will be adjusted in units of whole lines. - -=item [5] - -Clicking mouse button 1 with the Control key down will reposition the -insertion cursor without affecting the selection. - -=item [6] - -If any normal printing characters are typed, they are -inserted at the point of the insertion cursor. - -=item [7] - -The view in the widget can be adjusted by dragging with mouse button 2. -If mouse button 2 is clicked without moving the mouse, the selection -is copied into the text at the position of the mouse cursor. -The Insert key also inserts the selection, but at the position of -the insertion cursor. - -=item [8] - -If the mouse is dragged out of the widget -while button 1 is pressed, the entry will automatically scroll to -make more text visible (if there is more text off-screen on the side -where the mouse left the window). - -=item [9] - -The Left and Right keys move the insertion cursor one character to the -left or right; they also clear any selection in the text. -If Left or Right is typed with the Shift key down, then the insertion -cursor moves and the selection is extended to include the new character. -Control-Left and Control-Right move the insertion cursor by words, and -Control-Shift-Left and Control-Shift-Right move the insertion cursor -by words and also extend the selection. -Control-b and Control-f behave the same as Left and Right, respectively. -Meta-b and Meta-f behave the same as Control-Left and Control-Right, -respectively. - -=item [10] - -The Up and Down keys move the insertion cursor one line up or -down and clear any selection in the text. -If Up or Right is typed with the Shift key down, then the insertion -cursor moves and the selection is extended to include the new character. -Control-Up and Control-Down move the insertion cursor by paragraphs (groups -of lines separated by blank lines), and -Control-Shift-Up and Control-Shift-Down move the insertion cursor -by paragraphs and also extend the selection. -Control-p and Control-n behave the same as Up and Down, respectively. - -=item [11] - -The Next and Prior keys move the insertion cursor forward or backwards -by one screenful and clear any selection in the text. -If the Shift key is held down while Next or Prior is typed, then -the selection is extended to include the new character. -Control-v moves the view down one screenful without moving the -insertion cursor or adjusting the selection. - -=item [12] - -Control-Next and Control-Prior scroll the view right or left by one page -without moving the insertion cursor or affecting the selection. - -=item [13] - -Home and Control-a move the insertion cursor to the -beginning of its line and clear any selection in the widget. -Shift-Home moves the insertion cursor to the beginning of the line -and also extends the selection to that point. - -=item [14] - -End and Control-e move the insertion cursor to the -end of the line and clear any selection in the widget. -Shift-End moves the cursor to the end of the line and extends the selection -to that point. - -=item [15] - -Control-Home and Meta-E<lt> move the insertion cursor to the beginning of -the text and clear any selection in the widget. -Control-Shift-Home moves the insertion cursor to the beginning of the text -and also extends the selection to that point. - -=item [16] - -Control-End and Meta-E<gt> move the insertion cursor to the end of the -text and clear any selection in the widget. -Control-Shift-End moves the cursor to the end of the text and extends -the selection to that point. - -=item [17] - -The Select key and Control-Space set the selection anchor to the position -of the insertion cursor. They don't affect the current selection. -Shift-Select and Control-Shift-Space adjust the selection to the -current position of the insertion cursor, selecting from the anchor -to the insertion cursor if there was not any selection previously. - -=item [18] - -Control-/ selects the entire contents of the widget. - -=item [19] - -Control-\ clears any selection in the widget. - -=item [20] - -The F16 key (labelled Copy on many Sun workstations) or Meta-w -copies the selection in the widget to the clipboard, if there is a selection. - -=item [21] - -The F20 key (labelled Cut on many Sun workstations) or Control-w -copies the selection in the widget to the clipboard and deletes -the selection. -If there is no selection in the widget then these keys have no effect. - -=item [22] - -The F18 key (labelled Paste on many Sun workstations) or Control-y -inserts the contents of the clipboard at the position of the -insertion cursor. - -=item [23] - -The Delete key deletes the selection, if there is one in the widget. -If there is no selection, it deletes the character to the right of -the insertion cursor. - -=item [24] - -Backspace and Control-h delete the selection, if there is one -in the widget. -If there is no selection, they delete the character to the left of -the insertion cursor. - -=item [25] - -Control-d deletes the character to the right of the insertion cursor. - -=item [26] - -Meta-d deletes the word to the right of the insertion cursor. - -=item [27] - -Control-k deletes from the insertion cursor to the end of its line; -if the insertion cursor is already at the end of a line, then -Control-k deletes the newline character. - -=item [28] - -Control-o opens a new line by inserting a newline character in -front of the insertion cursor without moving the insertion cursor. - -=item [29] - -Meta-backspace and Meta-Delete delete the word to the left of the -insertion cursor. - -=item [30] - -Control-x deletes whatever is selected in the text widget. - -=item [31] - -Control-t reverses the order of the two characters to the right of -the insertion cursor. - -=item [32] - -Control-z (and Control-underscore on UNIX when tk_strictMotif is -true) undoes the last edit action if the -undo option is true. -Does nothing otherwise. - -=item [33] - -Control-Z (or Control-y on Windows) reapplies the last undone edit -action if the -undo option is true. Does nothing otherwise. - -=back - -If the widget is disabled using the B<-state> option, then its -view can still be adjusted and text can still be selected, -but no insertion cursor will be displayed and no text modifications will -take place. - -The behavior of texts can be changed by defining new bindings for -individual widgets or by redefining the class bindings. - - -=head1 TIED INTERFACE - -The Perl/Tk Text widget also has built-in TIEHANDLE methods for -B<print> and B<printf> statements. This means you can print to file -handles tied to a Text widget, and the tied methods automatically -insert the print statement's arguments into the Text widget. - -For example: - - #!/usr/local/bin/perl -w - use POSIX 'acos'; - use Tk; - use strict; - - my $mw = MainWindow->new; - my $text = $mw->Text(qw/-width 40 -height 10/)->pack; - - tie *STDOUT, ref $text, $text; - - print "Hello Text World!\n"; - printf "pi ~= %1.5f", acos(-1.0); - - MainLoop; - -To tie a scrolled Text widget, use the Subwidget method to get to the -E<quot>realE<quot> widget: - - my $text = $mw->Scrolled('Text')->pack; - tie *STDOUT, 'Tk::Text', $text->Subwidget('scrolled'); - -=head1 PERFORMANCE ISSUES - -Text widgets should run efficiently under a variety -of conditions. The text widget uses about 2-3 bytes of -main memory for each byte of text, so texts containing a megabyte -or more should be practical on most workstations. -Text is represented internally with a modified B-tree structure -that makes operations relatively efficient even with large texts. -Tags are included in the B-tree structure in a way that allows -tags to span large ranges or have many disjoint smaller ranges -without loss of efficiency. -Marks are also implemented in a way that allows large numbers of -marks. -In most cases it is fine to have large numbers of unique tags, -or a tag that has many distinct ranges. - -One performance problem can arise if you have hundreds or thousands -of different tags that all have the following characteristics: -the first and last ranges of each tag are near the beginning and -end of the text, respectively, -or a single tag range covers most of the text widget. -The cost of adding and deleting tags like this is proportional -to the number of other tags with the same properties. -In contrast, there is no problem with having thousands of distinct -tags if their overall ranges are localized and spread uniformly throughout -the text. - -Very long text lines can be expensive, -especially if they have many marks and tags within them. - -The display line with the insert cursor is redrawn each time the -cursor blinks, which causes a steady stream of graphics traffic. -Set the B<-insertofftime> option to 0 avoid this. - -=head1 SEE ALSO - -L<Tk::ROText|Tk::ROText> -L<Tk::TextUndo|Tk::TextUndo> - -=head1 KEYWORDS - -text, widget - -=cut - - diff --git a/Master/tlpkg/tlperl/lib/Tk/TextUndo.pod b/Master/tlpkg/tlperl/lib/Tk/TextUndo.pod deleted file mode 100644 index 2b9d98a3c4a..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/TextUndo.pod +++ /dev/null @@ -1,73 +0,0 @@ - -=head1 NAME - -Tk::TextUndo - perl/tk text widget with bindings to undo changes. - -=for pm Tk/TextUndo.pm - -=for category Derived Widgets - -=head1 SYNOPSIS - -S< >B<use Tk::TextUndo;> - -S< >I<$testundo> = I<$parent>-E<gt>B<TextUndo>(?I<-option>=E<gt>I<value>, ...?); - -=head1 DESCRIPTION - -This IS-A text widget with an unlimited 'undo' history but without -a re'undo' capability. - -=head2 Bindings - -The C<TextUndo> widget has the same bindings as the L<Text|Tk::Text> widget. -In addition there are the following bindings: - -=over 4 - -=item Event <L4> <<Undo>> - -undo the last change. Pressing <L4> several times undo -step by step the changes made to the text widget. - -=back - -=head2 Methods - -The C<TextUndo> widget has the same methods as C<Text> widget. -Additional methods for the C<TextUndo> widget are: - -=over 4 - -=item $text->Load($filename); - -Loads the contents of the $filename into the text widget. Load() -delete the previous contents of the text widget as well as it's -undo history of the previous file. - -=item $text->Save(?$otherfilename?) - -Save contents of the text widget to a file. If the -$otherfilename is not specified, the text widget contents -writes the file of $filename used in the last Load() -call. If no file was previously Load()'ed an error message -pops up. The default filename of the last Load() call -is not overwriten by $otherfilename. - -=item $text->FileName(?$otherfilename?) - -If passed an argument sets the file name associated with the loaded -document. Returns the current file name associated with the document. - -=back - -=head1 KEYS - -widget, text, undo - -=head1 SEE ALSO - -L<Tk::Text>, L<Tk::ROText> - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Tiler.pod b/Master/tlpkg/tlperl/lib/Tk/Tiler.pod deleted file mode 100644 index 2db172ebaf1..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Tiler.pod +++ /dev/null @@ -1,32 +0,0 @@ - -=head1 NAME - -Tk::Tiler - Scrollable frame with sub-widgets arranged into rows - -=for pm Tk/Tiler.pm - -=for category Tk Geometry Management - -=head1 SYNOPSIS - - use Tk::Tiler; - - my $tl = $parent->Scrolled('Tiler', -columns => n, -rows => n); - - my $a = $tl->Xxxxx(...); - my $b = $tl->Xxxxx(...); - my $c = $tl->Xxxxx(...); - - $tl->Manage($a,$b,$c); - -=head1 DESCRIPTION - -Tiler is derived form Tk::Frame. It is a geometry managing widget which -accepts widgets to manage. It places the widgets in a grid with as many -widgets as possible in a row. All the "slots" in the grid are the same size, -which is determined by the largest managed widget. - -The grid may be scrolled vertically. - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/TixGrid.pod b/Master/tlpkg/tlperl/lib/Tk/TixGrid.pod deleted file mode 100644 index 93484db0076..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/TixGrid.pod +++ /dev/null @@ -1,539 +0,0 @@ -# Copyright (c) 1996, Expert Interface Technologies -# See the file "license.terms" for information on usage and -# redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# The file man.macros and some of the macros used by this file are -# copyrighted: (c) 1990 The Regents of the University of California. -# (c) 1994-1995 Sun Microsystems, Inc. -# The license terms of the Tcl/Tk distribution are in the file -# license.tcl. - -## TO CHECK: -## -## callback: checked for defined of code ref (compare -edit*cmd) -## -## option -## formatcmd mentions format method but there is no format -## method documented -## -## methods: -## bdtype: what is it? no description given -## see: not documented? Not implemented?? -## -## todo: missing peaces marked by ???? - -=head1 NAME - -Tk::TixGrid - Create and manipulate Tix Grid widgets - -=for pm TixGrid/TixGrid.pm - -=for category Tix Extensions - -=head1 SYNOPSIS - -S< >I<$tixgrid> = I<$parent>->B<TixGrid>?(I<options>)?; - -=head1 DESCRIPTION - -This widget is intended as the basis of "spread sheet" like interfaces. -The widget displays its contents in a two dimensional "grid" of cells. -Each cell may contain one Tix display item, which may be in text, -graphics or other formats. See L<Tk::DItem> for more information -about Tix display items. Because these "items" need not be "windows" large -grids can be handled without consuming excessive display system resources. - -Individual cells, or groups of cells, can be formatted with a wide range of -attributes, such as its color, relief and border. However because the -widget is intended to handle large grids the mechanisms to achieve these -are lower level, and more callback oriented than for other widgets. The -assumption is that to avoid storing display details of a large number -of cells, the data will be re-computed as needed. - -The port of Tix C code and some of the bindings to perl/Tk is done but still -need further work. In several places the intent of the Tix code is not -yet understood. For example the 'edit' interface is clearly intended -for spread-sheet like cell content editing in an auxillary "entry" widget -or similar, but how that should work is not yet clear. - -The B<TixGrid> method creates a new TixGrid window and returns a -blessed reference of this TixGrid widget. Additional options, -described below, may be specified on the command line or in the -option database to configure aspects of the B<TixGrid> widget. - -=head1 STANDARD OPTIONS - -B<-background> - B<-borderwidth> - B<-cursor> - B<-font> - B<-foreground> - B<-height> - B<-highlightbackground> - B<-highlightcolor> - B<-highlightthickness> - B<-padx> - B<-pady> - B<-relief> - B<-selectbackground> - B<-selectborderwidth> - B<-selectforeground> - B<-state> - B<-takefocus> - B<-width> - B<-xscrollcommand> - B<-yscrollcommand> - -See L<Tk::options> for details of the standard options. - -=head1 WIDGET-SPECIFIC OPTIONS - -=over 4 - -=item Name: B<browseCmd> - -=item Class: B<BrowseCmd> - -=item Switch: B<-browsecmd> - -If defined, gives a perl/Tk L<callback|Tk::callbacks> to be executed when the -user browses a grid cell (This is normally the case when the user clicks on an -entry). When this callback is called, it is passed with two additional -parameters: I<x> I<y>, where (I<x>,I<y>) is the location of the cell that has -just been clicked. - -=item Name: B<Command> - -=item Class: B<Command> - -=item Switch: B<-command> - -If defined, gives a perl/Tk L<callback|Tk::callbacks> to be executed when the -user double-clicks a grid cell. When this callback is called, it is passed -with two additional parameters: I<x> I<y>, where (I<x>,I<y>) is the location of -the cell that has just been clicked. - -=item Name: B<editDoneCmd> - -=item Class: B<EditDoneCmd> - -=item Switch: B<-editdonecmd> - -If defined, gives a perl/Tk L<callback|Tk::callbacks> -to be executed when the -user has edited grid cell. When this callback is called, it is -passed with two additional parameters: I<x> I<y>, where (I<x>,I<y>) -is the location of the cell that has just been edited. - -=item Name: B<editNotifyCmd> - -=item Class: B<EditNotifyCmd> - -=item Switch: B<-editnotifycmd> - -If defined gives a perl/Tk L<callback|Tk::callbacks> -to be executed when the user tries to edit a grid cell. -When this callback is called, it is passed with two additional -parameters: I<x> I<y>, where (I<x>,I<y>,) is the location -of the cell. This callback should return a boolean value: B<true> -indicates that the cell is editable and B<false> otherwise. - -=item Name: B<FloatingCols> - -=item Class: B<floatingCols> - -=item Switch: B<-floatingcols> - -Defines the number of extra columns beyond the existing grid -that can be brought into view by scrolling. - -=item Name: B<FloatingRows> - -=item Class: B<floatingRows> - -=item Switch: B<-floatingrows> - -Defines the number of extra rows beyond the the existing grid -that can be brought into view by scrolling. - -=item Name: B<formatCmd> - -=item Class: B<FormatCmd> - -=item Switch: B<-formatcmd> - -If defined, gives a perl/Tk L<callback|Tk::callbacks> to be -executed when the grid cells need to be displayed on the screen. -Its primary purpose is to draw the background of the region -before the cells are rendered on top. This is normally -achieved by calling B<formatGrid> or B<formatBorder> (see below). -However other uses can be made of this low-level callback. For example it can be used -to "lazily" populate the grid by calling the B<set> method only as cells come -into view. - -When this callback is called, it is passed with five additional -parameters: I<type> I<x1> I<y1> I<x2> I<y2>. - -I<x1> I<y1> I<x2> I<y2> gives the extent of the region that needs -formatting. - -I<type> gives the logical type of the region in the grid. It may be one of the -following. - -=over 8 - -=item B<x_margin> - -The horizontal margin. - -=item B<y_margin> - -The vertical margin. - -=item B<s_margin> - -The area in the top left corner where the horizontal and vertical margins -are joined. - -=item B<main> - -The main body i.e. all the cells that do not fall into the above three types. - -=back - -=item Name: B<leftMargin> - -=item Class: B<LeftMargin> - -=item Switch: B<-leftmargin> - -Gives the width of vertical margin in cells (columns). -A zero indicates that no vertical margin exists. A positive value I<N> -indicates that first I<N> columns are "labels" and are always displayed -and not scrolled. - -=item Name: B<itemType> - -=item Class: B<ItemType> - -=item Switch: B<-itemtype> - -Default item type for cells. - -=item Name: B<selectMode> - -=item Class: B<SelectMode> - -=item Switch: B<-selectmode> - -Specifies one of several styles for manipulating the selection. -The value of the option may be arbitrary, but the default bindings -expect it to be either B<single>, B<browse>, B<multiple>, or B<extended>; -the default value is B<single>. - -=item Name: B<selectUnit> - -=item Class: B<SelectUnit> - -=item Switch: B<-selectunit> - -Specifies the selection unit. Valid values are B<cell>, B<column> or B<row>. - -=item Name: B<sizeCmd> - -=item Class: B<SizeCmd> - -=item Switch: B<-sizecmd> - -Callback is called (with no extra arguments) when grid sizes are -re-computed. For example if window changes size, a different font -is specified etc. - -It is called just after scrollbars (if present) are updated. - -=item Name: B<topMargin> - -=item Class: B<TopMargin> - -=item Switch: B<-topmargin> - -Gives the width of horizontal margin in cells (rows). -A zero indicates that no horizontal margin exists. A positive value -I<N> indicates that first I<N> rows are "labels" and are always -displayed and not scrolled. - -=back - -=head1 WIDGET METHODS - -The B<TixGrid> method creates a TixGrid widget and returns a blessed -reference of this TixGrid widget. This reference may be used to -invoke various operations on the widget. It has the following general -form: - -S< >I<$tixgrid>->B<method>?(I<arg, arg, ...>)? - -I<arg>s determine the exact behavior of the method. - -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. -The widget also inherits all the methods provided by the generic -L<Tk::Widget|Tk::Widget> class. - -The following additional methods are possible for B<TixGrid> widgets: - -=over 4 - -=item I<$tixgrid>->B<anchorGet>(I<x>, I<y>) - -=item I<$tixgrid>->B<anchorSet>(I<x>, I<y>) - -=item I<$tixgrid>->B<anchorClear> - -Manipulates the B<anchor cell> of the B<TixGrid> widget. -The anchor cell is the end of the selection that is fixed -while the user is dragging out a selection with the mouse. - -=item ($bd,$col,$row) = I<$tixgrid>->B<bdtype>(I<x,y> ?,I<xDelta>,I<yDelta>?) - -Determines if the the screen (pixel) position I<x,y> is in a border. -This is useful for changing the mouse cursor when the user points at a -border - e.g. to indicate that the border can be adjusted -interactively. - -If in a border returns a list of three elements. First element -is 'xy', 'x' or 'y', second two elements are integers. -(Value of these are not understood, seem to indicate which -column and row of the border the screen position corresponds to?) - -If not in a border returns an empty list. - -=item I<$tixgrid>->B<delete>(I<dim>, I<from>?, I<to>?) - -=item I<$tixgrid>->B<deleteColumn>(I<from>?, I<to>?) - -=item I<$tixgrid>->B<deleteRow>(I<from>?, I<to>?) - -I<Dim> may be B<row> or B<column>. If I<to> is not given, -deletes a single row (or column) at the position I<from>. -If I<to> is given, deletes the range of rows (or columns) -from position I<from> through I<to>. - -=item I<$tixgrid>->B<dragsite>(I<option>, I<x>, I<y>) - -=item I<$tixgrid>->B<dropsite>(I<option>, I<x>, I<y>) - -Tcl/Tix has (or was going to have) Drag&Drop support. -Meaning for perl/Tk is not clear yet. - -=item I<$tixgrid>->B<editApply> - -If any cell is being edited, de-highlight the cell and -applies the changes. - -=item I<$tixgrid>->B<editSet>(I<x>, I<y>) - -Highlights the cell at (I<x>,I<y>) for editing, -if the B<-editnotify> callback returns true for this cell. - -=item I<$tixgrid>->B<entrycget>(I<x>, I<y>, 'I<-option>') - -=item I<$tixgrid>->B<entryconfigure>(I<x>, I<y>?, I<-option>??=>I<value>, I<-option>=>I<value>, I<...>?) - -Provide a configue interface to cells in the grid. -The I<-option>s depend on the item type of the cell. - -=item I<$tixgrid>->B<formatBorder>(I<x1,y1>, I<x2,y2>, I<options>); - -=item I<$tixgrid>->B<formatGrid>(I<x1,y1>, I<x2,y2>, I<options>); - -The B<formatBorder> and B<formatBorder> methods can only be called by the -B<-formatcmd> callback of the tixGrid widget. They draw the background of -the region described by I<x1,y1>, I<x2,y2> according the the supplied -I<options>. One call to B<-formatcmd> callback can make multiple -calls to B<formatBorder> and/or B<formatBorder> for different -sub-regions. - -B<formatBorder> draws the background using Tk relief style, -B<formatGrid> also draws grid lines between the cells. -It only makes sense to call one or the other for a particular -sub-region as one will over-write the other. - -The options allowed are: - -=over 8 - -=item -background / -bg - -=item -borderwidth / -bd - -=item -filled - -=item -relief - -=item -selectbackground - -=item -xoff - -=item -xon - -=item -yoff - -=item -yon - -=back - -The B<-xon/-xoff and -yon/-yoff> options are obscure. If anyone -can figure out how to do something interesting given what -F<pTk/tixGrFmt.c> is doing with them please let Nick know!. - -=item I<$tixgrid>->B<geometryinfo>(?I<width>, I<height>?) - -Returns list of four values - two sets of two floating point numbers. -First set is the scrollbar fractions for x direction, second set -is scrollbar fractions for y direction. If I<width> and I<height> -are specified then fractions are based on as if window size was of -specified size (in pixels, but not allowing normal GetPixels units). -Otherwise fractions are based on current size of the window. - -Usage obscure. - -=item I<$tixgrid>->B<index>(I<xcoord>, I<ycoord>) - -Retuns I<(x, y)> of entry at position (I<$coordx>, I<$coordy>). -Either coordinate may be B<'max'> which is largest existing entry -in that direction, B<'end'> which is one I<beyond> largest existing -entry, or a number. (This is how you find out how big the grid is.) - -=item I<$tixgrid>->B<infoBbox>(I<x>,I<y>) - -Return the pixel bounding box of the cell at I<x,y>. - -=item I<$tixgrid>->B<infoExists>(I<x>,I<y>) - -Returns true if there is an item in the cell at I<x,y>. -Throws an exception (dies) if I<x,y> is outside the -grid - this may change (Nick doesn't like it). - -=item I<$tixgrid>->B<move>(I<dim>, I<from>, I<to>, I<offset>) - -=item I<$tixgrid>->B<moveColumn>(I<from>, I<to>, I<offset>) - -=item I<$tixgrid>->B<moveRow>(I<from>, I<to>, I<offset>) - -I<Dim> may be B<row> or B<column>. Moves the range of rows -(or columns) from position I<from> through I<to> by the distance -indicated by I<offset>. For example, -I<$tixgrid>->B<moveRow>(B<2>, B<4>, B<1>) moves the rows 2,3,4 -to rows 3,4,5. - -=item I<$tixgrid>->B<nearest>(I<x>, I<y>) - -Screen pos (pixels) to entry (nx,ny) translation. - -=item I<$tixgrid>->B<selectionAdjust>(I<x1>, I<y1> ?,I<x2>, I<y2>?) - -=item I<$tixgrid>->B<selectionClear>(I<x1>, I<y1> ?,I<x2>, I<y2>?) - -=item I<$tixgrid>->B<selectionIncludes>(I<x1>, I<y1> ?,I<x2>, I<y2>?) - -=item I<$tixgrid>->B<selectionSet>(I<x1>, I<y1> ?,I<x2>, I<y2>?) - -=item I<$tixgrid>->B<selectionToggle>(I<x1>, I<y1> ?,I<x2>, I<y2>?) - -Selection support methods - probably buggy. - -x1 (y1) has not to be greater than x2 (y2), but only x2 and y2 can be 'max'. - -BUG: I<selectionIncludes>: has no visible effect (as in Tix). Eh??? - -BUG: I<selectionClear>: only works for 0, 0, max, max (as in Tix). Eh??? - -When I<x2, y2> are not given they default to I<x1, y1>, respectively. - -=item I<$tixgrid>->B<set>(I<x>, I<y>?, B<-itemtype>=>I<type>??, I<-option>=>I<value>, I<...>?) - -Creates a new display item at the cell at (I<x>,I<y>). The optional -B<-itemtype> parameter gives the type of the display item. -An additional list of I<option-value> pairs specify options -of the display item. If a display item already exists at this cell, -the old item will be deleted automatically. - -=item I<$tixgrid>->B<size>(I<dim>, I<index>?, I<-option>??=>I<value>, I<...>?) - -=item I<$tixgrid>->B<sizeColumn>(I<index>?, I<-option>??=>I<value>, I<...>?) - -=item I<$tixgrid>->B<sizeRow>(I<index>?, I<-option>??=>I<value>, I<...>?) - -Queries or sets the size of the row or column given by I<dim> and -I<index>. I<Dim> may be B<row> or B<column>. I<Index> may be any -non-negative integer that gives the position of a given row (or column). -I<Index> can also be the string B<default>; in this case, this method -queries or sets the default size of all rows (or columns). -When no I<option-value> pair is given, this method returns -a list containing the current size setting of the given row (or column). -When I<option-value> pairs are given, the corresponding options -of the size setting of the given row are changed. I<-option> may be -one of the following: - -=over 8 - -=item B<-pad0> => I<pixels> - -Specifies the paddings to the left of a column or the top of a row. - -=item B<-pad1> => I<pixels> - -Specifies the paddings to the right of a column or the bottom of a row. - -=item B<-size> => I<val> - -Specifies the width of a column or the height of a row. -I<Val> may be: B<auto> -- the width of the column is set -the widest cell in the column; a valid Tk screen distance -unit (see B<Tk_GetPixels>); or a real number following by the -word B<chars> (e.g. B<3.4chars>) that sets the width of the -column to the given number of characters. - -=back - -=item I<$tixgrid>->B<sort>(I<dimension>, I<start>, I<end>, ?I<args ...>?) - -?docu here? (not supported on Win* OSs up to now) - -=item I<$tixgrid>->B<unset>(I<x>, I<y>) - -Clears the cell at (I<x>,I<y>) by removing its display item. - -=item I<$tixgrid>->B<xview> - -Normal horizontal scrollbar method. - -=item I<$tixgrid>->B<yview> - -Normal vertical scrollbar method. - -=back - -=head1 BINDINGS - -To be done - only most obvious basic bindings work. The Tcl/Tix code -was coded as a "state machine" which is not easy to follow. - -=head1 SEE ALSO - -L<Tk::DItem|Tk::DItem> -L<Tk::callbacks|Tk::callbacks> -L<Tk::FloatEntry|Tk::FloatEntry> - -=head1 BUGS - -Tcl/Tix was/is not finished and both C code and bindings of TixGrid -have some bugs. - -=head1 KEYWORDS - -tix, tixgrid, table, display item, spreadsheet - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Toplevel.pod b/Master/tlpkg/tlperl/lib/Tk/Toplevel.pod deleted file mode 100644 index e3bbf579c0b..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Toplevel.pod +++ /dev/null @@ -1,199 +0,0 @@ -# Copyright (c) 1990-1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::Toplevel - Create and manipulate Toplevel widgets - -=for category Tk Widget Classes - -=head1 SYNOPSIS - -S< >I<$toplevel> = I<$parent>-E<gt>B<Toplevel>(?I<options>?); - -=head1 STANDARD OPTIONS - -B<-borderwidth> B<-highlightbackground> B<-highlightthickness> B<-takefocus> -B<-class> B<-highlightcolor> B<-relief> -B<-cursor> - -See L<Tk::options> for details of the standard options. - -=head1 WIDGET-SPECIFIC OPTIONS - -=over 4 - -=item Name: B<background> - -=item Class: B<Background> - -=item Switch: B<-background> - -This option is the same as the standard B<background> option -except that its value may also be specified as an undefined value. -In this case, the widget will display no background or border, and -no colors will be consumed from its colormap for its background -and border. - -=item Name: B<colormap> - -=item Class: B<Colormap> - -=item Switch: B<-colormap> - -Specifies a colormap to use for the window. -The value may be either B<new>, in which case a new colormap is -created for the window and its children, or the name of another -window (which must be on the same screen and have the same visual -as $widget), in which case the new window will use the colormap -from the specified window. -If the B<colormap> option is not specified, the new window -uses the default colormap of its screen. -This option may not be changed with the B<configure> -method. - -=item Name: B<container> - -=item Class: B<Container> - -=item Switch: B<-container> - -The value must be a boolean. If true, it means that this window will -be used as a container in which some other application will be embedded -(for example, a Tk toplevel can be embedded using the B<-use> option). -The window will support the appropriate window manager protocols for -things like geometry requests. The window should not have any -children of its own in this application. -This option may not be changed with the B<configure> -method. - -=item Name: B<height> - -=item Class: B<Height> - -=item Switch: B<-height> - -Specifies the desired height for the window in any of the forms -acceptable to B<Tk_GetPixels>. -If this option is less than or equal to zero then the window will -not request any size at all. - -=item Name: B<menu> - -=item Class: B<Menu> - -=item Switch: B<-menu> - -Specifies a menu widget to be used as a menubar. On the Macintosh, the -menubar will be displayed accross the top of the main monitor. On -Microsoft Windows and all UNIX platforms, the menu will appear accross -the toplevel window as part of the window dressing maintained by the -window manager. - -=item Name: B<""> - -=item Class: B<""> - -=item Switch: B<-screen> - -Specifies the screen on which to place the new window. -Any valid screen name may be used, even one associated with a -different display. -Defaults to the same screen as its parent. -This option is special in that it may not be specified via the option -database, and it may not be modified with the B<configure> -method. - -=item Switch: B<-title> - -Specifies the title of the toplevel window. - -=item Name: B<use> - -=item Class: B<Use> - -=item Switch: B<-use> - -This option is used for embedding. If the value isn't an empty string, -it must be the the window identifier of a container window, specified as -a hexadecimal string like the ones returned by the B<winfo id> -command. The toplevel widget will be created as a child of the given -container instead of the root window for the screen. If the container -window is in a Tk application, it must be a frame or toplevel widget for -which the B<-container> option was specified. -This option may not be changed with the B<configure> -method. - -=item Name: B<visual> - -=item Class: B<Visual> - -=item Switch: B<-visual> - -Specifies visual information for the new window in any of the -forms accepted by B<Tk_GetVisual>. -If this option is not specified, the new window will use the default -visual for its screen. -The B<visual> option may not be modified with the B<configure> -method. - -=item Name: B<width> - -=item Class: B<Width> - -=item Switch: B<-width> - -Specifies the desired width for the window in any of the forms -acceptable to B<Tk_GetPixels>. -If this option is less than or equal to zero then the window will -not request any size at all. - -=back - -=head1 DESCRIPTION - -The B<Toplevel> method creates a new toplevel widget (given -by the $widget argument). Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the toplevel such as its background color -and relief. The B<toplevel> command returns the -path name of the new window. - -A toplevel is similar to a frame except that it is created as a -top-level window: its X parent is the root window of a screen -rather than the logical parent from its path name. The primary -purpose of a toplevel is to serve as a container for dialog boxes -and other collections of widgets. The only visible features -of a toplevel are its background color and an optional 3-D border -to make the toplevel appear raised or sunken. - -=head1 WIDGET METHODS - -The B<Toplevel> method creates a widget object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. -The widget also inherits all the methods provided by the generic -L<Tk::Widget|Tk::Widget> class, and the L<Tk::Wm|Tk::Wm> class. - -=head1 BINDINGS - -When a new toplevel is created, it has no default event bindings: -toplevels are not intended to be interactive. - -=head1 SEE ALSO - -L<Tk::Widget|Tk::Widget> -L<Tk::Wm|Tk::Wm> - -=head1 KEYWORDS - -toplevel, widget - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Tree.pod b/Master/tlpkg/tlperl/lib/Tk/Tree.pod deleted file mode 100644 index 445d2f0765b..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Tree.pod +++ /dev/null @@ -1,274 +0,0 @@ - -=head1 NAME - -Tk::Tree - Create and manipulate Tree widgets - -=for pm Tixish/Tree.pm - -=for category Tix Extensions - -=head1 SYNOPSIS - -S< >B<use Tk::Tree;> - -S< >I<$tree> = I<$parent>-E<gt>B<Tree>(?I<options>?); - -=head1 SUPER-CLASS - -The B<Tree> class is derived from the L<HList|Tk::HList> class and inherits all -the methods, options and subwidgets of its super-class. A B<Tree> widget is -not scrolled by default. - -=head1 STANDARD OPTIONS - -B<Tree> supports all the standard options of an HList widget. -See L<Tk::options> for details on the standard options. - -=head1 WIDGET-SPECIFIC OPTIONS - -=over 4 - -=item Name: B<browseCmd> - -=item Class: B<BrowseCmd> - -=item Switch: B<-browsecmd> - -Specifies a L<callback|Tk::callbacks> to call whenever the user browses on an entry -(usually by single-clicking on the entry). The callback is called with -one argument, the pathname of the entry. - -=item Name: B<closeCmd> - -=item Class: B<CloseCmd> - -=item Switch: B<-closecmd> - -Specifies a L<callback|Tk::callbacks> to call whenever an entry needs to be closed (See -L<"BINDINGS"> below). This method is called with one argument, -the pathname of the entry. This method should perform appropriate -actions to close the specified entry. If the B<-closecmd> option -is not specified, the default closing action is to hide all child -entries of the specified entry. - -=item Name: B<command> - -=item Class: B<Command> - -=item Switch: B<-command> - -Specifies a L<callback|Tk::callbacks> to call whenever the user activates an entry -(usually by double-clicking on the entry). The callback -is called with one argument, the pathname of the entry. - -=item Name: B<ignoreInvoke> - -=item Class: B<IgnoreInvoke> - -=item Switch: B<-ignoreinvoke> - -A Boolean value that specifies when a branch should be opened or -closed. A branch will always be opened or closed when the user presses -the (+) and (-) indicators. However, when the user invokes a branch -(by doublc-clicking or pressing E<lt>ReturnE<gt>), the branch will be opened -or closed only if B<-ignoreinvoke> is set to false (the default -setting). - -=item Name: B<openCmd> - -=item Class: B<OpenCmd> - -=item Switch: B<-opencmd> - -Specifies a L<callback|Tk::callbacks> to call whenever an entry needs to be opened (See -L<"BINDINGS"> below). This method is called with one argument, -the pathname of the entry. This method should perform appropriate -actions to open the specified entry. If the B<-opencmd> option -is not specified, the default opening action is to show all the child -entries of the specified entry. - -=back - -=head1 DESCRIPTION - -The B<Tree> method creates a new window and makes it into a Tree widget -and return a reference to it. Additional options, described above, may -be specified on the command line or in the option database to configure -aspects of the Tree widget such as its cursor and relief. - -The Tree widget can be used to display hierarchical data in a tree -form. The user can adjust the view of the tree by opening or closing -parts of the tree. - -To display a static tree structure, you can add the entries into the -Tree widget and hide any entries as desired. Then you can call -the B<autosetmode> method. This will set up the Tree widget so that it -handles all the I<open> and I<close> events automatically. -the demonstration program F<Tixish/examples/perl-tix-tree>). - -The above method is not applicable if you want to maintain a dynamic tree -structure, i.e, you do not know all the entries in the tree and you need -to add or delete entries subsequently. To do this, you should first create -the entries in the Tree widget. Then, use the B<setmode> method to -indicate the entries that can be opened or closed, and use the B<-opencmd> -and B<-closecmd> options to handle the opening and closing events. (Please -see the demonstration program F<Tixish/examples/perl-tix-dyntree>). - -Use either - -S< >I<$parent>-E<gt>B<Scrolled>(B<'Tree'>, ... ); - -or - -S< >I<$parent>-E<gt>B<ScrlTree>( ... ); - -to create a scrolled B<Tree>. See L<Tk::Scrolled> for details. - -=head1 WIDGET METHODS - -The B<Tree> method creates a widget object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. -The widget also inherits all the methods provided by the generic -L<Tk::Widget|Tk::Widget> class. - -The following additional methods are available for Tree widgets: - -=over 4 - -=item I<$tree-E<gt>>B<add_pathimage>(I<treeRegExp [, openImg, closeImg]>) - -This method defines images for a given path (images must be in xpm -format). The path can be determined by a simplified regular -expression. There are just three metasymbols: - -=over - -=item ^ - -at the beginning of the C<treeRegExp> same as in Perl regular -expressions - -=item * - -anything - -=item $ - -at the end of the C<TreeRegExp>, the same as in Perl regular -expressions - -=back - -Examples: - - $tree->add_pathimage('^root','openfolder','folder'); - -matches C<root>, C<root.foo>, C<root.bar>, but not C<foo.root> - - $tree->add_pathimage('root.*.class','openfolder','folder'); - -matches all paths containing C<< root.<anything>.class >>, but not -C<< root.<anything>.<anything>.class >> C<*> is one part of the path. If -you want to use a wildcard for two steps, you have to use C<*.*>. - - $tree->add_pathimage('class$','openfolder','folder'); - -This matches all path with C<class> at the end. - -=item I<$tree>-E<gt>B<autosetmode> - -This method calls the B<setmode> method for all the entries in -this Tree widget: if an entry has no child entries, its mode is set to -B<none>. Otherwise, if the entry has any hidden child entries, its -mode is set to B<open>; otherwise its mode is set to B<close>. - -=item I<$tree-E<gt>>B<child_entries>([$path][,$depth]) - -This method returns in list context an array that contains all -pathnames of subentries within the given path. In scalar context it -returns the number of subentries in the given path. - - Example: - root - | foo - | bar - | | bar1 - | | bar2 - - my @childentries = $tree->child_entries('root.bar'); - # returns (root.bar.bar1, root.bar.bar2) - - my $nr_of_subentries = $tree->child_entries('root',2); - # returns 4 - -If C<$path> is omitted, all it is assumed, that the entry above -'root' is meant. C<$depth> defines the numbers of levels. - -=item I<$tree>-E<gt>B<close>(I<entryPath>) - -Close the entry given by I<entryPath> if its I<mode> is B<close>. - -=item I<$tree>-E<gt>B<getmode>(I<entryPath>) - -Returns the current I<mode> of the entry given by I<entryPath>. - -=item I<$tree>-E<gt>B<open>(I<entryPath>) - -Open the entry given by I<entryPath> if its I<mode> is B<open>. - -=item I<$tree>-E<gt>B<setmode>(I<entryPath, mode>) - -This method is used to indicate whether the entry given by -I<entryPath> has children entries and whether the children are -visible. I<mode> must be one of B<open>, -B<close> or B<none>. If I<mode> is set to B<open>, a (+) -indicator is drawn next to the entry. If I<mode> is set to -B<close>, a (-) indicator is drawn next to the entry. If -I<mode> is set to B<none>, no indicators will be drawn for this -entry. The default I<mode> is none. The B<open> mode indicates -the entry has hidden children and this entry can be opened by the -user. The B<close> mode indicates that all the children of the entry -are now visible and the entry can be closed by the user. - -=back - -=head1 BINDINGS - -The basic mouse and keyboard bindings of the Tree widget are the same -as the L<bindings of the HList|Tk::HList/"BINDINGS"> widget. -In addition, the entries can be opened or closed under the following -conditions: - -=over 4 - -=item [1] - -If the I<mode> of the entry is B<open>, it can be opened by clicking -on its (+) indicator. - -=item [2] - -If the I<mode> of the entry is B<close>, it can be closed by clicking -on its (-) indicator. - -=back - -=head1 SEE ALSO - -L<Tk::HList|Tk::HList> - -=head1 AUTHOR - -Perl/TK version by Chris Dean <ctdean@cogit.com>. Original Tcl/Tix -version by Ioi Kim Lam. - -Additions by Renee Baecker <module@renee-baecker.de> - -=head1 ACKNOWLEDGEMENTS - -Thanks to Achim Bohnet <ach@mpe.mpg.de> for all his help. - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/UserGuide.pod b/Master/tlpkg/tlperl/lib/Tk/UserGuide.pod deleted file mode 100644 index 08d397d4db7..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/UserGuide.pod +++ /dev/null @@ -1,586 +0,0 @@ -=head1 NAME - -Perl/Tk - 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 diff --git a/Master/tlpkg/tlperl/lib/Tk/Widget.pod b/Master/tlpkg/tlperl/lib/Tk/Widget.pod deleted file mode 100644 index 696bbab22b7..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Widget.pod +++ /dev/null @@ -1,678 +0,0 @@ -# Copyright (c) 1990-1994 The Regents of the University of California. -# Copyright (c) 1994-1997 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::Widget - Base class of all widgets - -=for pm Tk/Widget.pm - -=for category Tk Generic Methods - -=head1 SYNOPSIS - - package Tk::Whatever; - require Tk::Widget; - @ISA = qw(Tk::Widget); - Construct Tk::Widget 'Whatever'; - - sub Tk_cmd { \&Tk::whatever } - -S< >I<$widget>-E<gt>I<method>(?I<arg, arg, ...>?) - -=head1 DESCRIPTION - -The B<Tk::Widget> is an abstract base class for all Tk widgets. - -Generic methods available to all widgets include the methods based on core -C<winfo> mechanism and are used to retrieve information about windows managed by -Tk. They can take any of a number of different forms, depending on the I<method>. -The legal forms are: - -=over 4 - -=item I<$widget>-E<gt>B<appname>?(I<newName>)? - -If I<newName> isn't specified, this method returns the name -of the application (the name that may be used in B<send> -commands to communicate with the application). -If I<newName> is specified, then the name of the application -is changed to I<newName>. -If the given name is already in use, then a suffix of the form -``B< #2>'' or ``B< #3>'' is appended in order to make the name unique. -The method's result is the name actually chosen. -I<newName> should not start with a capital letter. -This will interfere with L<option|Tk::option> processing, since names starting with -capitals are assumed to be classes; as a result, Tk may not -be able to find some options for the application. -If sends have been disabled by deleting the B<send> command, -this command will reenable them and recreate the B<send> -command. - -=item I<$widget>-E<gt>B<atom>(I<name>) - -Returns a decimal string giving the integer identifier for the -atom whose name is I<name>. If no atom exists with the name -I<name> then a new one is created. - -=item I<$widget>-E<gt>B<atomname>(I<id>) - -Returns the textual name for the atom whose integer identifier is -I<id>. -This command is the inverse of the I<$widget>-E<gt>B<atom> command. -It generates an error if no such atom exists. - -=item I<$widget>-E<gt>B<bell>( ?-nice? ); - -This command rings the bell on the display for I<$widget> and -returns an empty string. -The command uses the current bell-related settings for the display, which -may be modified with programs such as B<xset>. - -If I<-nice> is not specified, this command also resets the screen saver -for the screen. Some screen savers will ignore this, but others will -reset so that the screen becomes visible again. - -=item I<$widget>-E<gt>B<bindDump> - -This command returns a list of strings suitable for printing detailing -binding information for a widget. It prints a widget's -bindtags. For each binding tag it prints all the bindings, comprised -of the event descriptor and the callback. Callback arguments are -printed, and B<Tk::Ev> objects are expanded. - -=item I<$widget>-E<gt>B<Busy>?(?-recurse => 1?,I<-option> => I<value>?)? - -This method B<configure>s a B<-cursor> option for I<$widget> and -(if B<-recurse => 1> is specified) all its descendants. The cursor to -be set may be passed as S<B<-cursor> => I<cursor>> or defaults to 'watch'. -Additional B<configure> options are applied to I<$widget> only. -It also adds a special tag B<'Busy'> to the B<bindtags> of the widgets so -configured so that B<KeyPress>, B<KeyRelease>, B<ButtonPress> and -B<ButtonRelease> events are ignored (with press events generating a call to -B<bell>). It then acquires a local B<grab> for I<$widget>. -The state of the widgets and the grab is restored by a call to -I<$widget>-E<gt>B<Unbusy>. - -=item I<$widget>-E<gt>B<caret>( ?-x => I<x>?, ?-y => I<y>?, ?-height -=> I<height>? ); - -Sets and queries the caret location for the display of the specified -Tk window window. The caret is the per-display cursor location used -for indicating global focus (e.g. to comply with Microsoft -Accessibility guidelines), as well as for location of the -over-the-spot XIM (X Input Methods) or Windows IME windows. If no -options are specified, the last values used for setting the caret are -return in option-value pair format. -x and -y represent -window-relative coordinates, and -height is the height of the current -cursor location, or the height of the specified window if none is -given. - -=item I<$widget>-E<gt>B<cells> - -Returns a decimal string giving the number of cells in the -color map for I<$widget>. - -=item I<$widget>-E<gt>B<children> - -I<$widget->>B<children> -Returns a list containing all the children -of $widget. The list is in stacking order, with the lowest -window first. Top-level windows are returned as children -of their logical parents. - -=item I<$widget>-E<gt>B<class> - -Returns the class name for I<$widget>. - -=item I<$widget>-E<gt>B<colormapfull> - -Returns 1 if the colormap for I<$widget> is known to be full, 0 -otherwise. The colormap for a window is ``known'' to be full if the last -attempt to allocate a new color on that window failed and this -application hasn't freed any colors in the colormap since the -failed allocation. - -=item I<$widget>-E<gt>B<ConfigSpecs> - -Used to perform delegated option configuration for a mega-widget. -Returns, in Tk::Derived::ConfigSpecs notation (see L<Tk::ConfigSpecs>), -all possible options for a widget. For example, - - $s = $self->Scale; - $self->ConfigSpecs( - $s->ConfigSpecs, - .... more ConfigSpecs specifications - ); - -returns a hash of all Tk::Scale options, delegated to $s - e.g. some -representative examples: - - -bigincrement => [$s, bigIncrement, BigIncrement, 0, 0] - -digits => [$s, digits, Digits, 0, 0] - -sliderlength => [$s, sliderLength, SliderLength, 10m, 30] - -troughcolor => [$s, troughColor, Background, #c3c3c3, #c3c3c3] - -This provides an easy means of populating a mega-widget's ConfigSpecs -with initializers. - -=item I<$widget>-E<gt>B<containing>(I<rootX,rootY>) - -Returns the window containing the point given -by I<rootX> and I<rootY>. -I<RootX> and I<rootY> are specified in screen units (i.e. -any form acceptable to B<Tk_GetPixels>) in the coordinate -system of the root window (if a virtual-root window manager is in -use then the coordinate system of the virtual root window is used). -If no window in this application contains the point then an empty -string is returned. -In selecting the containing window, children are given higher priority -than parents and among siblings the highest one in the stacking order is -chosen. - -=item I<$widget>-E<gt>B<depth> - -Returns a decimal string giving the depth of I<$widget> (number -of bits per pixel). - -=item I<$widget>-E<gt>B<destroy> - -This command deletes the window related to -I<$widget>, plus all its descendants. -If all the B<MainWindows> are deleted then the entire application -will be destroyed. - -The perl object I<$widget> continues to exist while references -to it still exist, e.g. until variable goes out of scope. -However any attempt to use Tk methods on the object will fail. -B<Exists>(I<$widget>) will return false on such objects. - -Note however that while a window exists for I<$widget> the -perl object is maintained (due to "references" in perl/Tk internals) -even though original variables may have gone out of scope. -(Normally this is intuitive.) - -=item B<Exists>(I<$widget>) - -Returns 1 if there exists a window for I<$widget>, 0 if no such -window exists. - -=item I<$widget>-E<gt>B<font>(I<option>?, I<arg, arg, ...>?) - -Create and inspect fonts. See L<Tk::Font> for further details. - -=item I<$widget>-E<gt>B<fpixels>(I<number>) - -Returns a floating-point value giving the number of pixels -in I<$widget> corresponding to the distance given by I<number>. -I<Number> may be specified in any of the forms acceptable -to B<Tk_GetScreenMM>, such as ``2.0c'' or ``1i''. -The return value may be fractional; for an integer value, use -I<$widget>-E<gt>B<pixels>. - -=item I<$widget>-E<gt>B<Getimage>(I<name>) - -Given I<name>, look for an image file with that base name and return -a L<Tk::Image>. File extensions are tried in this order: F<xpm>, -F<gif>, F<ppm>, F<xbm> until a valid iamge is found. If no image is -found, try a builtin image with that name. - -=item I<$widget>-E<gt>B<geometry> - -Returns the geometry for I<$widget>, in the form -I<width>B<x>I<height>B<+>I<x>B<+>I<y>. All dimensions are -in pixels. - -=item I<$widget>-E<gt>B<height> - -Returns a decimal string giving I<$widget>'s height in pixels. -When a window is first created its height will be 1 pixel; the -height will eventually be changed by a geometry manager to fulfill -the window's needs. -If you need the true height immediately after creating a widget, -invoke B<update> to force the geometry manager to arrange it, -or use I<$widget>-E<gt>B<reqheight> to get the window's requested height -instead of its actual height. - -=item I<$widget>-E<gt>B<id> - -Returns a hexadecimal string giving a low-level platform-specific -identifier for $widget. On Unix platforms, this is the X -window identifier. Under Windows, this is the Windows -HWND. On the Macintosh the value has no meaning outside Tk. - -=item I<$widget>-E<gt>B<idletasks> - -One of two methods which are used to bring the application ``up to date'' -by entering the event loop repeated until all pending events -(including idle callbacks) have been processed. - -If the B<idletasks> method is specified, then no new events or errors -are processed; only idle callbacks are invoked. This causes operations -that are normally deferred, such as display updates and window layout -calculations, to be performed immediately. - -The B<idletasks> command is useful in scripts where changes have been -made to the application's state and you want those changes to appear -on the display immediately, rather than waiting for the script to -complete. Most display updates are performed as idle callbacks, so -B<idletasks> will cause them to run. However, there are some kinds of -updates that only happen in response to events, such as those -triggered by window size changes; these updates will not occur in -B<idletasks>. - -=item I<$widget>-E<gt>B<interps> - -Returns a list whose members are the names of all Tcl interpreters -(e.g. all Tk-based applications) currently registered for -a particular display. -The return value refers -to the display of I<$widget>. - -=item I<$widget>-E<gt>B<ismapped> - -Returns B<1> if I<$widget> is currently mapped, B<0> otherwise. - -=item I<$widget->>B<lower>(?I<belowThis>?) - -If the I<belowThis> argument is omitted then the command lowers -$widget so that it is below all of its siblings in the stacking -order (it will be obscured by any siblings that overlap it and -will not obscure any siblings). -If I<belowThis> is specified then it must be the path name of -a window that is either a sibling of $widget or the descendant -of a sibling of $widget. -In this case the B<lower> command will insert -$widget into the stacking order just below I<belowThis> -(or the ancestor of I<belowThis> that is a sibling of $widget); -this could end up either raising or lowering $widget. - -=item I<$widget>-E<gt>B<MapWindow> - -Cause I<$widget> to be "mapped" i.e. made visible on the display. -May confuse the geometry manager (pack, grid, place, ...) -that thinks it is managing the widget. - -=item I<$widget>-E<gt>B<manager> - -Returns the name of the geometry manager currently -responsible for I<$widget>, or an empty string if I<$widget> -isn't managed by any geometry manager. -The name is usually the name of the method for the geometry -manager, such as B<pack> or B<place>. -If the geometry manager is a widget, such as canvases or text, the -name is the widget's class command, such as B<canvas>. - -=item I<$widget>-E<gt>B<name> - -Returns I<$widget>'s name (i.e. its name within its parent, as opposed -to its full path name). -The command I<$mainwin>-E<gt>B<name> will return the name of the application. - -=item I<$widget>-E<gt>B<OnDestroy>(I<callback>); - -OnDestroy accepts a standard perl/Tk I<callback>. -When the window associated with I<$widget> is destroyed then -the callback is invoked. Unlike I<$widget->>bind('E<lt>DestroyE<gt>',...) -the widgets methods are still available when I<callback> is executed, -so (for example) a B<Text> widget can save its contents to a file. - -OnDestroy was required for new B<after> mechanism. - -=item I<$widget>-E<gt>B<parent> - -Returns I<$widget>'s parent, or an empty string -if I<$widget> is the main window of the application. - -=item I<$widget>-E<gt>B<PathName> - -Returns the Tk path name of I<$widget>. This is the inverse of the -L</Widget> method. (This is an import from the C interface.) - -=item I<$widget>-E<gt>B<pathname>(I<id>) - -Returns an object whose X identifier is I<id>. -The identifier is looked up on the display of I<$widget>. -I<Id> must be a decimal, hexadecimal, or octal integer and must -correspond to a window in the invoking application, or an error -occurs which can be trapped with C<eval { }> or C<Tk::catch { }>. -If the window belongs to the application, but is not an object -(for example wrapper windows, HList header, etc.) then C<undef> -is returned. - -=item I<$widget>-E<gt>B<pixels>(I<number>) - -Returns the number of pixels in I<$widget> corresponding -to the distance given by I<number>. -I<Number> may be specified in any of the forms acceptable -to B<Tk_GetPixels>, such as ``2.0c'' or ``1i''. -The result is rounded to the nearest integer value; for a -fractional result, use I<$widget>-E<gt>B<fpixels>. - -=item I<$widget>-E<gt>B<pointerx> - -If the mouse pointer is on the same screen as I<$widget>, returns the -pointer's x coordinate, measured in pixels in the screen's root window. -If a virtual root window is in use on the screen, the position is -measured in the virtual root. -If the mouse pointer isn't on the same screen as I<$widget> then --1 is returned. - -=item I<$widget>-E<gt>B<pointerxy> - -If the mouse pointer is on the same screen as I<$widget>, returns a list -with two elements, which are the pointer's x and y coordinates measured -in pixels in the screen's root window. -If a virtual root window is in use on the screen, the position -is computed in the virtual root. -If the mouse pointer isn't on the same screen as I<$widget> then -both of the returned coordinates are -1. - -=item I<$widget>-E<gt>B<pointery> - -If the mouse pointer is on the same screen as I<$widget>, returns the -pointer's y coordinate, measured in pixels in the screen's root window. -If a virtual root window is in use on the screen, the position -is computed in the virtual root. -If the mouse pointer isn't on the same screen as I<$widget> then --1 is returned. - -=item I<$widget>-E<gt>B<raise>(?I<aboveThis>?) - -If the I<aboveThis> argument is omitted then the command raises -$widget so that it is above all of its siblings in the stacking -order (it will not be obscured by any siblings and will obscure -any siblings that overlap it). -If I<aboveThis> is specified then it must be the path name of -a window that is either a sibling of $widget or the descendant -of a sibling of $widget. -In this case the B<raise> command will insert -$widget into the stacking order just above I<aboveThis> -(or the ancestor of I<aboveThis> that is a sibling of $widget); -this could end up either raising or lowering $widget. - -=item I<$widget>-E<gt>B<reqheight> - -Returns a decimal string giving I<$widget>'s requested height, -in pixels. This is the value used by I<$widget>'s geometry -manager to compute its geometry. - -=item I<$widget>-E<gt>B<reqwidth> - -Returns a decimal string giving I<$widget>'s requested width, -in pixels. This is the value used by I<$widget>'s geometry -manager to compute its geometry. - -=item I<$widget>-E<gt>B<rgb>(I<color>) - -Returns a list containing three decimal values, which are the -red, green, and blue intensities that correspond to I<color> in -the window given by I<$widget>. I<Color> -may be specified in any of the forms acceptable for a color -option. - -=item I<$widget>-E<gt>B<rootx> - -Returns a decimal string giving the x-coordinate, in the root -window of the screen, of the -upper-left corner of I<$widget>'s border (or I<$widget> if it -has no border). - -=item I<$widget>-E<gt>B<rooty> - -Returns a decimal string giving the y-coordinate, in the root -window of the screen, of the -upper-left corner of I<$widget>'s border (or I<$widget> if it -has no border). - -=item I<$widget>-E<gt>B<scaling>?(I<number>)? - -Sets and queries the current scaling factor used by Tk to convert between -physical units (for example, points, inches, or millimeters) and pixels. The -I<number> argument is a floating point number that specifies the number of -pixels per point on $widget's display. If the I<number> argument is -omitted, the current value of the scaling factor is returned. - -A ``point'' is a unit of measurement equal to 1/72 inch. A scaling factor -of 1.0 corresponds to 1 pixel per point, which is equivalent to a standard -72 dpi monitor. A scaling factor of 1.25 would mean 1.25 pixels per point, -which is the setting for a 90 dpi monitor; setting the scaling factor to -1.25 on a 72 dpi monitor would cause everything in the application to be -displayed 1.25 times as large as normal. The initial value for the scaling -factor is set when the application starts, based on properties of the -installed monitor (as reported via the window system), -but it can be changed at any time. Measurements made -after the scaling factor is changed will use the new scaling factor, but it -is undefined whether existing widgets will resize themselves dynamically to -accomodate the new scaling factor. - -=item I<$widget>-E<gt>B<screen> - -Returns the name of the screen associated with I<$widget>, in -the form I<displayName>.I<screenIndex>. - -=item I<$widget>-E<gt>B<screencells> - -Returns a decimal string giving the number of cells in the default -color map for I<$widget>'s screen. - -=item I<$widget>-E<gt>B<screendepth> - -Returns a decimal string giving the depth of the root window -of I<$widget>'s screen (number of bits per pixel). - -=item I<$widget>-E<gt>B<screenheight> - -Returns a decimal string giving the height of I<$widget>'s screen, -in pixels. - -=item I<$widget>-E<gt>B<screenmmheight> - -Returns a decimal string giving the height of I<$widget>'s screen, -in millimeters. - -=item I<$widget>-E<gt>B<screenmmwidth> - -Returns a decimal string giving the width of I<$widget>'s screen, -in millimeters. - -=item I<$widget>-E<gt>B<screenvisual> - -Returns one of the following strings to indicate the default visual -class for I<$widget>'s screen: B<directcolor>, B<grayscale>, -B<pseudocolor>, B<staticcolor>, B<staticgray>, or -B<truecolor>. - -=item I<$widget>-E<gt>B<screenwidth> - -Returns a decimal string giving the width of I<$widget>'s screen, -in pixels. - -=item I<$widget>-E<gt>B<server> - -Returns a string containing information about the server for -I<$widget>'s display. The exact format of this string may vary -from platform to platform. For X servers the string -has the form ``B<X>I<major>B<R>I<minor vendor vendorVersion>'' -where I<major> and I<minor> are the version and revision -numbers provided by the server (e.g., B<X11R5>), I<vendor> -is the name of the vendor for the server, and I<vendorRelease> -is an integer release number provided by the server. - -=item I<$widget>-E<gt>B<toplevel> - -Returns the reference of the top-level window containing I<$widget>. - -=item I<$widget>-E<gt>B<Unbusy> - -Restores widget state after a call to I<$widget>-E<gt>B<Busy>. - -=item I<$widget>-E<gt>B<UnmapWindow> - -Cause I<$widget> to be "unmapped" i.e. removed from the display. -This does for any widget what I<$widget>-E<gt>withdraw does for -toplevel widgets. May confuse the geometry manager (pack, grid, place, ...) -that thinks it is managing the widget. - -=item I<$widget>-E<gt>B<update> - -One of two methods which are used to bring the application ``up to date'' -by entering the event loop repeated until all pending events -(including idle callbacks) have been processed. - -The B<update> method is useful in scripts where you are performing a -long-running computation but you still want the application to respond -to events such as user interactions; if you occasionally call -B<update> then user input will be processed during the next call to -B<update>. - -=item I<$widget>-E<gt>B<useinputmethods>( ?I<boolean>? ) - -Sets and queries the state of whether Tk should use XIM (X Input -Methods) for filtering events. The resulting state is returned. -XIM is used in some locales (ie: Japanese, Korean), to handle -special input devices. This feature is only significant on X. -If XIM support is not available, this will always return 0. -If the boolean argument is omitted, the current state is -returned. This is turned on by default for the main display. - -=item I<$widget>-E<gt>B<viewable> - -Returns 1 if I<$widget> and all of its ancestors up through the -nearest toplevel window are mapped. Returns 0 if any of these -windows are not mapped. - -=item I<$widget>-E<gt>B<visual> - -Returns one of the following strings to indicate the visual -class for I<$widget>: B<directcolor>, B<grayscale>, -B<pseudocolor>, B<staticcolor>, B<staticgray>, or -B<truecolor>. - -=item I<$widget>-E<gt>B<visualid> - -Returns the X identifier for the visual for $widget. - -=item I<$widget>-E<gt>B<visualsavailable>(?B<includeids>?) - -Returns a list whose elements describe the visuals available for -I<$widget>'s screen. -Each element consists of a visual class followed by an integer depth. -The class has the same form as returned by I<$widget>-E<gt>B<visual>. -The depth gives the number of bits per pixel in the visual. -In addition, if the B<includeids> argument is provided, then the -depth is followed by the X identifier for the visual. - -=item I<$widget>-E<gt>B<vrootheight> - -Returns the height of the virtual root window associated with I<$widget> -if there is one; otherwise returns the height of I<$widget>'s screen. - -=item I<$widget>-E<gt>B<vrootwidth> - -Returns the width of the virtual root window associated with I<$widget> -if there is one; otherwise returns the width of I<$widget>'s screen. - -=item I<$widget>-E<gt>B<vrootx> - -Returns the x-offset of the virtual root window associated with I<$widget>, -relative to the root window of its screen. -This is normally either zero or negative. -Returns 0 if there is no virtual root window for I<$widget>. - -=item I<$widget>-E<gt>B<vrooty> - -Returns the y-offset of the virtual root window associated with I<$widget>, -relative to the root window of its screen. -This is normally either zero or negative. -Returns 0 if there is no virtual root window for I<$widget>. - -=item I<$widget->>B<waitVariable>(\$I<name>) - -=item I<$widget->>B<waitVisibility> - -=item I<$widget->>B<waitWindow> - -The B<tk wait> methods wait for one of several things to happen, -then it returns without taking any other actions. -The return value is always an empty string. -B<waitVariable> expects a reference to a perl -variable and the command waits for that variable to be modified. -This form is typically used to wait for a user to finish interacting -with a dialog which sets the variable as part (possibly final) -part of the interaction. -B<waitVisibility> waits for a change in I<$widget>'s -visibility state (as indicated by the arrival of a VisibilityNotify -event). This form is typically used to wait for a newly-created -window to appear on the screen before taking some action. -B<waitWindow> waits for I<$widget> to be destroyed. -This form is typically used to wait for a user to finish interacting -with a dialog box before using the result of that interaction. -Note that creating and destroying the window each time a dialog is required -makes code modular but imposes overhead which can be avoided by B<withdrawing> -the window instead and using B<waitVisibility>. - -While the B<tk wait> methods are waiting they processes events in -the normal fashion, so the application will continue to respond -to user interactions. -If an event handler invokes B<tkwait> again, the nested call -to B<tkwait> must complete before the outer call can complete. - -=item I<$widget>-E<gt>B<Walk>(I<proc>?, I<arg, ...>?) - -Traverse a widget hierarchy starting at I<$widget> while executing the -subroutine I<proc> to every visited widget. The arguments I<arg, ...> -are supplied to the subroutine. - -=item I<$widget>-E<gt>B<Widget>(I<pathname>) - -Returns the widget reference for the given Tk path name, or C<undef> -if the path name does not match a Tk widget. This is the inverse of -the L</PathName> method. (This is an import from the C interface.) - -=item I<$widget>-E<gt>B<width> - -Returns a decimal string giving I<$widget>'s width in pixels. -When a window is first created its width will be 1 pixel; the -width will eventually be changed by a geometry manager to fulfill -the window's needs. -If you need the true width immediately after creating a widget, -invoke B<update> to force the geometry manager to arrange it, -or use I<$widget>-E<gt>B<reqwidth> to get the window's requested width -instead of its actual width. - -=item I<$widget>-E<gt>B<windowingsystem> - -Returns the current Tk windowing system, one of B<x11> (X11-based), -B<win32> (MS Windows), B<classic> (Mac OS Classic), or B<aqua> (Mac OS X Aqua). - -=item I<$widget>-E<gt>B<x> - -Returns a decimal string giving the x-coordinate, in I<$widget>'s -parent, of the upper-left corner of I<$widget>'s border (or I<$widget> -if it has no border). - -=item I<$widget>-E<gt>B<y> - -Returns a decimal string giving the y-coordinate, in I<$widget>'s -parent, of the -upper-left corner of I<$widget>'s border (or I<$widget> if it -has no border). - -=back - -=head1 CAVEATS - -The above documentaion on generic methods is incomplete. - -=head1 KEYWORDS - -atom, children, class, geometry, height, identifier, information, interpreters, -mapped, parent, path name, screen, virtual root, width, window - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/WidgetDemo.pod b/Master/tlpkg/tlperl/lib/Tk/WidgetDemo.pod deleted file mode 100644 index 32c7a101dc6..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/WidgetDemo.pod +++ /dev/null @@ -1,59 +0,0 @@ - -=head1 NAME - -WidgetDemo() - create a standard widget demonstration window. - -=for pm demos/demos/widget_lib/WidgetDemo.pm - -=for category Implementation - -=head1 SYNOPSIS - - use WidgetDemo; - my $TOP = $MW->WidgetDemo( - -name => $demo, - -text => 'Learn how to write a widget demonstration!', - -title => 'WidgetDemo Demonstration', - -iconname => 'WidgetDemo', - -geometry_manager => 'grid', - -font => $FONT, - ); - -=head1 DESCRIPTION - -This constructor builds a standard widget demonstration window, composed of -three frames. The top frame contains descriptive demonstration text. The -bottom frame contains the "Dismiss" and "See Code" buttons. The middle frame -is demonstration container, which came be managed by either the pack or grid -geometry manager. - -The -text attribute is supplied to a Label widget, which is left-adjusted -with -wraplength set to 4 inches. If you require different specifications -then pass an array to -text; the first element is the text string and -the remaining array elements are standard Label widget attributes - WidgetDemo -will rearrange things as required.. - - -text => ['Hello World!', qw/-wraplength 6i/], - -=head1 AUTHOR - -Steve Lidie <Stephen.O.Lidie@Lehigh.EDU> - -=head1 HISTORY - -lusol@Lehigh.EDU, LUCC, 97/02/11 -lusol@Lehigh.EDU, LUCC, 97/06/07 -Stephen.O.Lidie@Lehigh.EDU, LUCC, 97/06/07 - . Add Delegates() call that obviates the need for Top(). Many thanks to - Achim Bohnet for this patch. - . Fix -title so that it works. - -=head1 COPYRIGHT - -Copyright (C) 1997 - 1998 Stephen O. Lidie. All rights reserved. - -This program is free software; you can redistribute it and/or modify it under -the same terms as Perl itself. - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Wm.pod b/Master/tlpkg/tlperl/lib/Tk/Wm.pod deleted file mode 100644 index 395fdf07d22..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Wm.pod +++ /dev/null @@ -1,667 +0,0 @@ -# Copyright (c) 1991-1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::Wm - Communicate with window manager - -=for category Tk Geometry Management - -=head1 SYNOPSIS - -S< >I<$toplevel>-E<gt>I<method>(?I<args>?) - -=head1 DESCRIPTION - -The B<wm> methods are used to interact with window managers in -order to control such things as the title for a window, its geometry, -or the increments in terms of which it may be resized. -The B<wm> methods can take any of a number of different forms, depending on -the particular I<method> argument. -All of the forms expect I<$toplevel>, which must be a -top-level window object. - -The legal forms for the B<wm> methods are: - -=over 4 - -=item I<$toplevel>-E<gt>B<aspect>(?I<minNumer minDenom maxNumer maxDenom>?) - -If I<minNumer>, I<minDenom>, I<maxNumer>, and I<maxDenom> -are all specified, then they will be passed to the window manager -and the window manager should use them to enforce a range of -acceptable aspect ratios for I<$toplevel>. The aspect ratio of -I<$toplevel> (width/length) will be constrained to lie -between I<minNumer>/I<minDenom> and I<maxNumer>/I<maxDenom>. -If I<minNumer> etc. are all specified as empty strings, then -any existing aspect ratio restrictions are removed. -If I<minNumer> etc. are specified, then the method returns an -empty string. Otherwise, it returns -a array containing four elements, which are the current values -of I<minNumer>, I<minDenom>, I<maxNumer>, and I<maxDenom> -(if no aspect restrictions are in effect, then an empty string is -returned). - -=item I<$widget>-E<gt>B<attributes>( I<?args?> ); - -This subcommand returns or sets platform specific attributes -associated with a window. - -=over 4 - -=item I<$widget>-E<gt>B<attributes>; - -Returns a list of the platform specific flags and their values. - -=item I<$widget>-E<gt>B<attributes>( I<?option?> ); - -Returns the value for the specific option. - -=item I<$widget>-E<gt>B<attributes>( I<?option value option value...?> ); - -Sets one or more of the values. The values are as follows: - -On Windows, B<-disabled> gets or sets whether the window is in a -disabled state. B<-toolwindow> gets or sets the style of the window -to toolwindow (as defined in the MSDN). B<-topmost> gets or sets -whether this is a topmost window (displays above all other windows). - -On Macintosh, there are currently no special attribute values. - -On Unix, there are currently no special attribute values. - -=back - -=item I<$toplevel>-E<gt>B<client>(?I<name>?) - -If I<name> is specified, this method stores I<name> (which -should be the name of -the host on which the application is executing) in I<$toplevel>'s -B<WM_CLIENT_MACHINE> property for use by the window manager or -session manager. -The method returns an empty string in this case. -If I<name> isn't specified, the method returns the last name -set in a B<client> method for I<$toplevel>. -If I<name> is specified as an empty string, the method deletes the -B<WM_CLIENT_MACHINE> property from I<$toplevel>. - -=item I<$toplevel>-E<gt>B<colormapwindows>(?I<windowList>?) - -This method is used to manipulate the B<WM_COLORMAP_WINDOWS> -property, which provides information to the window managers about -windows that have private colormaps. -If I<windowList> isn't specified, the method returns a list -whose elements are the names of the windows in the B<WM_COLORMAP_WINDOWS> -property. -If I<windowList> is specified, it consists of a list of widgets; -the method overwrites the B<WM_COLORMAP_WINDOWS> -property with the given windows and returns an empty string. -The B<WM_COLORMAP_WINDOWS> property should normally contain a -list of the internal windows within I<$toplevel> whose colormaps differ -from their parents. -The order of the windows in the property indicates a priority order: -the window manager will attempt to install as many colormaps as possible -from the head of this list when I<$widget> gets the colormap focus. -If I<$widget> is not included among the windows in I<windowList>, -Tk implicitly adds it at the end of the B<WM_COLORMAP_WINDOWS> -property, so that its colormap is lowest in priority. -If I<$widget>-E<gt>colormapwindows is not invoked, Tk will automatically set -the property for each top-level window to all the internal windows -whose colormaps differ from their parents, followed by the top-level -itself; the order of the internal windows is undefined. -See the ICCCM documentation for more information on the -B<WM_COLORMAP_WINDOWS> property. - -=item I<$toplevel>-E<gt>B<command>(?I<value>?) - -If I<value> is specified, this method stores I<value> in I<$toplevel>'s -B<WM_COMMAND> property for use by the window manager or -session manager and returns an empty string. -I<Value> must have proper list structure; the elements should -contain the words of the command used to invoke the application. -If I<value> isn't specified then the method returns the last value -set in a B<command> method for I<$toplevel>. -If I<value> is specified as an empty string, the method -deletes the B<WM_COMMAND> property from I<$toplevel>. - -=item I<$toplevel>-E<gt>B<deiconify> - -Arrange for I<$toplevel> to be displayed in normal (non-iconified) form. -This is done by mapping the window. If the window has never been -mapped then this method will not map the window, but it will ensure -that when the window is first mapped it will be displayed -in de-iconified form. Returns an empty string. - -=item I<$toplevel>-E<gt>B<focusmodel>(?B<active>|B<passive>?) - -If B<active> or B<passive> is supplied as an optional argument -to the method, then it specifies the focus model for I<$toplevel>. -In this case the method returns an empty string. If no additional -argument is supplied, then the method returns the current focus -model for I<$toplevel>. -An B<active> focus model means that I<$toplevel> will claim the -input focus for itself or its descendants, even at times when -the focus is currently in some other application. B<Passive> means that -I<$toplevel> will never claim the focus for itself: the window manager -should give the focus to I<$toplevel> at appropriate times. However, -once the focus has been given to I<$toplevel> or one of its descendants, -the application may re-assign the focus among I<$toplevel>'s descendants. -The focus model defaults to B<passive>, and Tk's B<focus> method -assumes a passive model of focusing. - -=item I<$toplevel>-E<gt>B<frame> - -If I<$widget> has been reparented by the window manager into a -decorative frame, the method returns the platform specific window -identifier for the outermost frame that contains I<$toplevel> (the -window whose parent is the root or virtual root). If I<$toplevel> -hasn't been reparented by the window manager then the method returns -the platform specific window identifier for I<$toplevel>. - -=item I<$toplevel>-E<gt>B<geometry>(?I<newGeometry>?) - -If I<newGeometry> is specified, then the geometry of I<$toplevel> -is changed and an empty string is returned. Otherwise the current -geometry for I<$toplevel> is returned (this is the most recent -geometry specified either by manual resizing or -in a B<geometry> method). I<NewGeometry> has -the form B<=>I<width>B<x>I<height>B<+->I<x>B<+->I<y>, where -any of B<=>, I<width>B<x>I<height>, or B<+->I<x>B<+->I<y> -may be omitted. I<Width> and I<height> are positive integers -specifying the desired dimensions of I<$toplevel>. If I<$toplevel> -is gridded (see L<"GRIDDED GEOMETRY MANAGEMENT"> below) then the dimensions -are specified in grid units; otherwise they are specified in pixel -units. I<X> and I<y> specify the desired location of -I<$toplevel> on the screen, in pixels. -If I<x> is preceded by B<+>, it specifies -the number of pixels between the left edge of the screen and the left -edge of I<$toplevel>'s border; if preceded by B<-> then -I<x> specifies the number of pixels -between the right edge of the screen and the right edge of I<$toplevel>'s -border. If I<y> is preceded by B<+> then it specifies the -number of pixels between the top of the screen and the top -of I<$toplevel>'s border; if I<y> is preceded by B<-> then -it specifies the number of pixels between the bottom of I<$toplevel>'s -border and the bottom of the screen. -If I<newGeometry> is specified as an empty string then any -existing user-specified geometry for I<$toplevel> is cancelled, and -the window will revert to the size requested internally by its -widgets. - -=item I<$toplevel>-E<gt>B<wmGrid>(?I<baseWidth,baseHeight,widthInc,heightInc>?) - -This method indicates that I<$toplevel> is to be managed as a -gridded window. -It also specifies the relationship between grid units and pixel units. -I<BaseWidth> and I<baseHeight> specify the number of grid -units corresponding to the pixel dimensions requested internally -by I<$toplevel> using B<Tk_GeometryRequest>. I<WidthInc> -and I<heightInc> specify the number of pixels in each horizontal -and vertical grid unit. -These four values determine a range of acceptable sizes for -I<$toplevel>, corresponding to grid-based widths and heights -that are non-negative integers. -Tk will pass this information to the window manager; during -manual resizing, the window manager will restrict the window's size -to one of these acceptable sizes. -Furthermore, during manual resizing the window manager will display -the window's current size in terms of grid units rather than pixels. -If I<baseWidth> etc. are all specified as empty strings, then -I<$toplevel> will no longer be managed as a gridded window. If -I<baseWidth> etc. are specified then the return value is an -empty string. -Otherwise the return value is a array containing -four elements corresponding to the current I<baseWidth>, -I<baseHeight>, I<widthInc>, and I<heightInc>; if -I<$toplevel> is not currently gridded, then an empty string -is returned. -Note: this command should not be needed very often, since the -B<Tk_SetGrid> library procedure and the B<-setgrid> option -provide easier access to the same functionality. - -=item I<$toplevel>-E<gt>B<group>(?I<$widget>?) - -If I<$widget> is specified, it is the the leader of -a group of related windows. The window manager may use this information, -for example, to unmap all of the windows in a group when the group's -leader is iconified. I<$widget> may be specified as an empty string to -remove I<$toplevel> from any group association. If I<$widget> is -specified then the method returns an empty string; otherwise it -returns the I<$toplevel>'s current group leader, or an empty -string if I<$toplevel> isn't part of any group. - -=item I<$toplevel>-E<gt>B<iconbitmap>(?I<bitmap>?) - -If I<bitmap> is specified, then it names a bitmap in the standard -forms accepted by Tk (see the B<Tk_GetBitmap> documentation for details). -This I<black and white> bitmap is passed to the window manager to be displayed -in I<$toplevel>'s icon, and the method returns an empty string. If -an empty string is specified for I<bitmap>, then any current icon -bitmap or image is cancelled for I<$toplevel>. -If I<bitmap> is specified then the method returns an empty string. -Otherwise it returns the name of -the current icon bitmap associated with I<$toplevel>, or an empty -string if I<$toplevel> has no icon bitmap. - -=item I<$toplevel>-E<gt>B<iconify> - -Arrange for I<$toplevel> to be iconified. It I<$toplevel> hasn't -yet been mapped for the first time, this method will arrange for -it to appear in the iconified state when it is eventually mapped. - -=item I<$toplevel>-E<gt>B<iconimage>(?I<image>?) - -If I<image> is specified, then it names a normal Tk image. -This image is rendered into a private I<coloured> bitmap which is passed to -the window manager to be displayed in I<$toplevel>'s icon, and the method returns -an empty string. If an empty string is specified for I<image>, then any current -icon bitmap or image is cancelled for I<$toplevel>. -If I<image> is specified then the method returns an empty string. -Otherwise it returns the name of -the current icon image associated with I<$toplevel>, or an empty -string if I<$toplevel> has no icon image. -The private pixmap is not pre-cleared so images which are partly "transparent" -display rubbish in their transparent parts. - -The sizes of images that can be used as icons in this manner are platform -dependant. On Win32 this sets the "large" icon, which should be 32x32, it -will automatically be scaled down to 16x16 for use as a small icon. - -=item I<$toplevel>-E<gt>B<iconmask>(?I<bitmap>?) - -If I<bitmap> is specified, then it names a bitmap in the standard -forms accepted by Tk (see the B<Tk_GetBitmap> documentation for details). -This bitmap is passed to the window manager to be used as a mask -in conjunction with the B<iconbitmap> option: where the mask -has zeroes no icon will be displayed; where it has ones, the bits -from the icon bitmap will be displayed. If -an empty string is specified for I<bitmap> then any current icon -mask is cancelled for I<$toplevel> (this is equivalent to specifying -a bitmap of all ones). If I<bitmap> is specified -then the method returns an empty string. Otherwise it -returns the name of the current icon mask associated with -I<$toplevel>, or an empty string if no mask is in effect. - -=item I<$toplevel>-E<gt>B<iconname>(?I<newName>?) - -If I<newName> is specified, then it is passed to the window -manager; the window manager should display I<newName> inside -the icon associated with I<$toplevel>. In this case an empty -string is returned as result. If I<newName> isn't specified -then the method returns the current icon name for I<$toplevel>, -or an empty string if no icon name has been specified (in this -case the window manager will normally display the window's title, -as specified with the B<title> method). - -=item I<$toplevel>-E<gt>B<iconphoto>(?-default? I<image1> ?I<image2> -...?) - -Sets the titlebar icon for window based on the named photo -images. If -default is specified, this is applied to all future -created toplevels as well. The data in the images is taken as a -snapshot at the time of invocation. If the images are later -changed, this is not reflected to the titlebar icons. Multiple -images are accepted to allow different images sizes (eg, 16x16 -and 32x32) to be provided. The window manager may scale pro- -vided icons to an appropriate size. - -On Windows, the images are packed into a Windows icon structure. -This will override an ico specified to wm iconbitmap, and vice -versa. [NOTE: This is not implemented yet!] - -On X, the images are arranged into the _NET_WM_ICON X property, -which most modern window managers support. A wm iconbitmap may -exist simultaneously. It is recommended to use not more than 2 -icons, placing the larger icon first. - -On Macintosh, this is currently does nothing. - -=item I<$toplevel>-E<gt>B<iconposition>(?I<x y>?) - -If I<x> and I<y> are specified, they are passed to the window -manager as a hint about where to position the icon for I<$toplevel>. -In this case an empty string is returned. If I<x> and I<y> are -specified as empty strings then any existing icon position hint is cancelled. -If neither I<x> nor I<y> is specified, then the method returns -a array containing two values, which are the current icon position -hints (if no hints are in effect then an empty string is returned). - -=item I<$toplevel>-E<gt>B<iconwindow>(?I<$widget>?) - -If I<$widget> is specified, it is a window to -use as icon for I<$toplevel>: when I<$toplevel> is iconified then -I<$widget> will be mapped to serve as icon, and when I<$toplevel> -is de-iconified then I<$widget> will be unmapped again. If -I<$widget> is specified as an empty string then any existing -icon window association for I<$toplevel> will be cancelled. If -the I<$widget> argument is specified then an empty string is -returned. Otherwise the method returns the -current icon window for I<$toplevel>, or an empty string if there -is no icon window currently specified for I<$toplevel>. -Button press events are disabled for I<$toplevel> as long as it is -an icon window; this is needed in order to allow window managers -to ``own'' those events. -Note: not all window managers support the notion of an icon window. - -=item I<$toplevel>-E<gt>B<maxsize>(?I<width,height>?) - -If I<width> and I<height> are specified, they give -the maximum permissible dimensions for I<$toplevel>. -For gridded windows the dimensions are specified in -grid units; otherwise they are specified in pixel units. -The window manager will restrict the window's dimensions to be -less than or equal to I<width> and I<height>. -If I<width> and I<height> are -specified, then the method returns an empty string. Otherwise -it returns a array with two elements, which are the -maximum width and height currently in effect. -The maximum size defaults to the size of the screen. -If resizing has been disabled with the B<resizable> method, -then this method has no effect. -See the sections on geometry management below for more information. - -=item I<$toplevel>-E<gt>B<minsize>(?I<width,height>?) - -If I<width> and I<height> are specified, they give the -minimum permissible dimensions for I<$toplevel>. -For gridded windows the dimensions are specified in -grid units; otherwise they are specified in pixel units. -The window manager will restrict the window's dimensions to be -greater than or equal to I<width> and I<height>. -If I<width> and I<height> are -specified, then the method returns an empty string. Otherwise -it returns a array with two elements, which are the -minimum width and height currently in effect. -The minimum size defaults to one pixel in each dimension. -If resizing has been disabled with the B<resizable> method, -then this method has no effect. -See the sections on geometry management below for more information. - -=item I<$toplevel>-E<gt>B<overrideredirect(?>I<boolean>?) - -If I<boolean> is specified, it must have a proper boolean form and -the override-redirect flag for I<$toplevel> is set to that value. -If I<boolean> is not specified then B<1> or B<0> is -returned to indicate whether or not the override-redirect flag -is currently set for I<$toplevel>. -Setting the override-redirect flag for a window causes -it to be ignored by the window manager; among other things, this means -that the window will not be reparented from the root window into a -decorative frame and the user will not be able to manipulate the -window using the normal window manager mechanisms. - -=item I<$toplevel>-E<gt>B<positionfrom>(?I<who>?) - -If I<who> is specified, it must be either B<program> or -B<user>, or an abbreviation of one of these two. It indicates -whether I<$toplevel>'s current position was requested by the -program or by the user. Many window managers ignore program-requested -initial positions and ask the user to manually position the window; if -B<user> is specified then the window manager should position the -window at the given place without asking the user for assistance. -If I<who> is specified as an empty string, then the current position -source is cancelled. -If I<who> is specified, then the method returns an empty string. -Otherwise it returns B<user> or $widget to indicate the -source of the window's current position, or an empty string if -no source has been specified yet. Most window managers interpret -``no source'' as equivalent to B<program>. -Tk will automatically set the position source to B<user> -when a B<geometry> method is invoked, unless the source has -been set explicitly to B<program>. - -=item I<$toplevel>-E<gt>B<protocol>(?I<name>?,?I<callback>?) - -This method is used to manage window manager protocols such as -B<WM_DELETE_WINDOW>. -I<Name> is the name of an atom corresponding to a window manager -protocol, such as B<WM_DELETE_WINDOW> or B<WM_SAVE_YOURSELF> -or B<WM_TAKE_FOCUS>. -If both I<name> and I<callback> are specified, then I<callback> -is associated with the protocol specified by I<name>. -I<Name> will be added to I<$toplevel>'s B<WM_PROTOCOLS> -property to tell the window manager that the application has a -protocol handler for I<name>, and I<callback> will -be invoked in the future whenever the window manager sends a -message to the client for that protocol. -In this case the method returns an empty string. -If I<name> is specified but I<callback> isn't, then the current -callback for I<name> is returned, or an empty string if there -is no handler defined for I<name>. -If I<callback> is specified as an empty string then the current -handler for I<name> is deleted and it is removed from the -B<WM_PROTOCOLS> property on I<$toplevel>; an empty string is -returned. -Lastly, if neither I<name> nor I<callback> is specified, the -method returns a list of all the protocols for which handlers -are currently defined for I<$toplevel>. - -=over 8 - -Tk always defines a protocol handler for B<WM_DELETE_WINDOW>, even if -you haven't asked for one with B<protocol>. -If a B<WM_DELETE_WINDOW> message arrives when you haven't defined -a handler, then Tk handles the message by destroying the window for -which it was received. - -=back - -=item I<$toplevel>-E<gt>B<resizable>(?I<width,height>?) - -This method controls whether or not the user may interactively -resize a top-level window. If I<width> and I<height> are -specified, they are boolean values that determine whether the -width and height of I<$toplevel> may be modified by the user. -In this case the method returns an empty string. -If I<width> and I<height> are omitted then the method -returns a list with two 0/1 elements that indicate whether the -width and height of I<$toplevel> are currently resizable. -By default, windows are resizable in both dimensions. -If resizing is disabled, then the window's size will be the size -from the most recent interactive resize or B<geometry> -method. If there has been no such operation then -the window's natural size will be used. - -=item I<$toplevel>-E<gt>B<sizefrom>(?I<who>?) - -If I<who> is specified, it must be either B<program> or -B<user>, or an abbreviation of one of these two. It indicates -whether I<$toplevel>'s current size was requested by the -program or by the user. Some window managers ignore program-requested -sizes and ask the user to manually size the window; if -B<user> is specified then the window manager should give the -window its specified size without asking the user for assistance. -If I<who> is specified as an empty string, then the current size -source is cancelled. -If I<who> is specified, then the method returns an empty string. -Otherwise it returns B<user> or $widget to indicate the -source of the window's current size, or an empty string if -no source has been specified yet. Most window managers interpret -``no source'' as equivalent to B<program>. - -=item I<$toplevel>-E<gt>B<stackorder>( I<?isabove|isbelow $toplevel?> ); - -The stackorder command returns a list of toplevel windows in -stacking order, from lowest to highest. When a single toplevel -window is passed, the returned list recursively includes all of -the window's children that are toplevels. Only those toplevels -that are currently mapped to the screen are returned. The -stackorder command can also be used to determine if one toplevel -is positioned above or below a second toplevel. When two window -arguments separated by either isabove or isbelow are passed, a -boolean result indicates whether or not the first window is -currently above or below the second window in the stacking order. - - -=item I<$toplevel>-E<gt>B<state>(?I<newstate>?) - -If I<newstate> is specified, the window will be set to -the new state, otherwise it returns the current state of -I<$toplevel>: either B<normal>, B<iconic>, B<withdrawn>, B<icon>, or -(Windows only) B<zoomed>. The -difference between B<iconic> and B<icon> is that B<iconic> refers to a -window that has been iconified (e.g., with the B<iconify> method) -while B<icon> refers to a window whose only purpose is to serve as the -icon for some other window (via the B<iconwindow> method). The -B<icon> state cannot be set. - - -=item I<$toplevel>-E<gt>B<title>(?I<string>?) - -If I<string> is specified, then it will be passed to the window -manager for use as the title for I<$toplevel> (the window manager -should display this string in I<$toplevel>'s title bar). In this -case the method returns an empty string. If I<string> isn't -specified then the method returns the current title for the -I<$toplevel>. The title for a window defaults to its name. - -=item I<$toplevel>-E<gt>B<transient>(?I<master>?) - -If I<master> is specified, then the window manager is informed -that I<$toplevel> is a transient window (e.g. pull-down menu) working -on behalf of I<master> (where I<master> is -a top-level window). Some window managers will use -this information to manage I<$toplevel> specially. If I<master> -is specified as an empty string then I<$toplevel> is marked as not -being a transient window any more. If I<master> is specified, -then the method returns an empty string. Otherwise the method -returns the path name of I<$toplevel>'s current master, or an -empty string if I<$toplevel> isn't currently a transient window. - -=item I<$toplevel>-E<gt>B<withdraw> - -Arranges for I<$toplevel> to be withdrawn from the screen. This -causes the window to be unmapped and forgotten about by the window -manager. If the window -has never been mapped, then this method -causes the window to be mapped in the withdrawn state. Not all -window managers appear to know how to handle windows that are -mapped in the withdrawn state. -Note: it sometimes seems to be necessary to withdraw a -window and then re-map it (e.g. with B<deiconify>) to get some -window managers to pay attention to changes in window attributes -such as group. - -=item I<$toplevel>-E<gt>B<wrapper> - -Returns the window id of the wrapper window in which Tk has placed -I<$toplevel>. This is the id by which window manager will know -I<$toplevel>, and so is appropriate place to add X properties. - -=back - -=head1 ICON SIZES - -The sizes of bitmaps/images that can be used as icons in this manner are platform -and window manager dependant. Unix window managers are typically more tolerant -than Win32. It is possible that coloured C<iconimage> icons may cause problems -on some X window managers. - -=over 4 - -=item * Win32 - -C<iconimage> and C<iconbitmap> set the "large" icon, which should be -32x32, it will automatically be scaled down to 16x16 for use as a small icon. -Win32 ignores C<iconwin> requests. - -=item * KDE's "kwm" - -Accepts coloured C<iconimage> and black and white C<iconbitmap> but -will scale either to a small (14x14?) icon. Kwm ignores C<iconwin>. - -=item * Sun's "olwm" or "olvwm" - -Honours C<iconwin> which will override C<iconimage> or C<iconbitmap>. -Coloured images work. - -=item * Sun's CDE window manager - -Coloured images work. ... - -=back - -=head1 GEOMETRY MANAGEMENT - -By default a top-level window appears on the screen in its -I<natural size>, which is the one determined internally by its -widgets and geometry managers. -If the natural size of a top-level window changes, then the window's size -changes to match. -A top-level window can be given a size other than its natural size in two ways. -First, the user can resize the window manually using the facilities -of the window manager, such as resize handles. -Second, the application can request a particular size for a -top-level window using the B<geometry> method. -These two cases are handled identically by Tk; in either case, -the requested size overrides the natural size. -You can return the window to its natural by invoking B<geometry> -with an empty I<geometry> string. - -Normally a top-level window can have any size from one pixel in each -dimension up to the size of its screen. -However, you can use the B<minsize> and B<maxsize> methods -to limit the range of allowable sizes. -The range set by B<minsize> and B<maxsize> applies to -all forms of resizing, including the window's natural size as -well as manual resizes and the B<geometry> method. -You can also use the method B<resizable> to completely -disable interactive resizing in one or both dimensions. - -=head1 GRIDDED GEOMETRY MANAGEMENT - -Gridded geometry management occurs when one of the widgets of an -application supports a range of useful sizes. -This occurs, for example, in a text editor where the scrollbars, -menus, and other adornments are fixed in size but the edit widget -can support any number of lines of text or characters per line. -In this case, it is usually desirable to let the user specify the -number of lines or characters-per-line, either with the -B<geometry> method or by interactively resizing the window. -In the case of text, and in other interesting cases also, only -discrete sizes of the window make sense, such as integral numbers -of lines and characters-per-line; arbitrary pixel sizes are not useful. - -Gridded geometry management provides support for this kind of -application. -Tk (and the window manager) assume that there is a grid of some -sort within the application and that the application should be -resized in terms of I<grid units> rather than pixels. -Gridded geometry management is typically invoked by turning on -the B<setGrid> option for a widget; it can also be invoked -with the B<wmGrid> method or by calling B<Tk_SetGrid>. -In each of these approaches the particular widget (or sometimes -code in the application as a whole) specifies the relationship between -integral grid sizes for the window and pixel sizes. -To return to non-gridded geometry management, invoke -B<grid> with empty argument strings. - -When gridded geometry management is enabled then all the dimensions specified -in B<minsize>, B<maxsize>, and B<geometry> methods -are treated as grid units rather than pixel units. -Interactive resizing is also carried out in even numbers of grid units -rather than pixels. - -=head1 BUGS - -Most existing window managers appear to have bugs that affect the -operation of the B<wm> methods. For example, some changes won't -take effect if the window is already active: the window will have -to be withdrawn and de-iconified in order to make the change happen. - -=head1 SEE ALSO - -L<Tk::Widget|Tk::Widget> -L<Tk::tixWm|Tk::tixWm> -L<Tk::Mwm|Tk::Mwm> - -=head1 KEYWORDS - -aspect ratio, deiconify, focus model, geometry, grid, group, icon, iconify, increments, position, size, title, top-level window, units, window manager - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/X.pod b/Master/tlpkg/tlperl/lib/Tk/X.pod deleted file mode 100644 index e6c7614a72c..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/X.pod +++ /dev/null @@ -1,373 +0,0 @@ - -=head1 NAME - -Tk::X - Perl extension for Xlib constants. - -=for pm Xlib/X/X.pm - -=for category Other Modules and Languages - -=head1 SYNOPSIS - - use Tk::X; - -=head1 DESCRIPTION - -A module generated by h2xs. It exists to export Xlib #define type -constants for possible use with Tk::Xlib. - -=head1 Exported constants - - Above - AllTemporary - AllocAll - AllocNone - AllowExposures - AlreadyGrabbed - Always - AnyButton - AnyKey - AnyModifier - AnyPropertyType - ArcChord - ArcPieSlice - AsyncBoth - AsyncKeyboard - AsyncPointer - AutoRepeatModeDefault - AutoRepeatModeOff - AutoRepeatModeOn - BadAccess - BadAlloc - BadAtom - BadColor - BadCursor - BadDrawable - BadFont - BadGC - BadIDChoice - BadImplementation - BadLength - BadMatch - BadName - BadPixmap - BadRequest - BadValue - BadWindow - Below - BottomIf - Button1 - Button1Mask - Button1MotionMask - Button2 - Button2Mask - Button2MotionMask - Button3 - Button3Mask - Button3MotionMask - Button4 - Button4Mask - Button4MotionMask - Button5 - Button5Mask - Button5MotionMask - ButtonMotionMask - ButtonPress - ButtonPressMask - ButtonRelease - ButtonReleaseMask - CWBackPixel - CWBackPixmap - CWBackingPixel - CWBackingPlanes - CWBackingStore - CWBitGravity - CWBorderPixel - CWBorderPixmap - CWBorderWidth - CWColormap - CWCursor - CWDontPropagate - CWEventMask - CWHeight - CWOverrideRedirect - CWSaveUnder - CWSibling - CWStackMode - CWWidth - CWWinGravity - CWX - CWY - CapButt - CapNotLast - CapProjecting - CapRound - CenterGravity - CirculateNotify - CirculateRequest - ClientMessage - ClipByChildren - ColormapChangeMask - ColormapInstalled - ColormapNotify - ColormapUninstalled - Complex - ConfigureNotify - ConfigureRequest - ControlMapIndex - ControlMask - Convex - CoordModeOrigin - CoordModePrevious - CopyFromParent - CreateNotify - CurrentTime - CursorShape - DefaultBlanking - DefaultExposures - DestroyAll - DestroyNotify - DirectColor - DisableAccess - DisableScreenInterval - DisableScreenSaver - DoBlue - DoGreen - DoRed - DontAllowExposures - DontPreferBlanking - EastGravity - EnableAccess - EnterNotify - EnterWindowMask - EvenOddRule - Expose - ExposureMask - FamilyChaos - FamilyDECnet - FamilyInternet - FillOpaqueStippled - FillSolid - FillStippled - FillTiled - FirstExtensionError - FocusChangeMask - FocusIn - FocusOut - FontChange - FontLeftToRight - FontRightToLeft - ForgetGravity - GCArcMode - GCBackground - GCCapStyle - GCClipMask - GCClipXOrigin - GCClipYOrigin - GCDashList - GCDashOffset - GCFillRule - GCFillStyle - GCFont - GCForeground - GCFunction - GCGraphicsExposures - GCJoinStyle - GCLastBit - GCLineStyle - GCLineWidth - GCPlaneMask - GCStipple - GCSubwindowMode - GCTile - GCTileStipXOrigin - GCTileStipYOrigin - GXand - GXandInverted - GXandReverse - GXclear - GXcopy - GXcopyInverted - GXequiv - GXinvert - GXnand - GXnoop - GXnor - GXor - GXorInverted - GXorReverse - GXset - GXxor - GrabFrozen - GrabInvalidTime - GrabModeAsync - GrabModeSync - GrabNotViewable - GrabSuccess - GraphicsExpose - GravityNotify - GrayScale - HostDelete - HostInsert - IncludeInferiors - InputFocus - InputOnly - InputOutput - IsUnmapped - IsUnviewable - IsViewable - JoinBevel - JoinMiter - JoinRound - KBAutoRepeatMode - KBBellDuration - KBBellPercent - KBBellPitch - KBKey - KBKeyClickPercent - KBLed - KBLedMode - KeyPress - KeyPressMask - KeyRelease - KeyReleaseMask - KeymapNotify - KeymapStateMask - LASTEvent - LSBFirst - LastExtensionError - LeaveNotify - LeaveWindowMask - LedModeOff - LedModeOn - LineDoubleDash - LineOnOffDash - LineSolid - LockMapIndex - LockMask - LowerHighest - MSBFirst - MapNotify - MapRequest - MappingBusy - MappingFailed - MappingKeyboard - MappingModifier - MappingNotify - MappingPointer - MappingSuccess - Mod1MapIndex - Mod1Mask - Mod2MapIndex - Mod2Mask - Mod3MapIndex - Mod3Mask - Mod4MapIndex - Mod4Mask - Mod5MapIndex - Mod5Mask - MotionNotify - NoEventMask - NoExpose - NoSymbol - Nonconvex - None - NorthEastGravity - NorthGravity - NorthWestGravity - NotUseful - NotifyAncestor - NotifyDetailNone - NotifyGrab - NotifyHint - NotifyInferior - NotifyNonlinear - NotifyNonlinearVirtual - NotifyNormal - NotifyPointer - NotifyPointerRoot - NotifyUngrab - NotifyVirtual - NotifyWhileGrabbed - Opposite - OwnerGrabButtonMask - ParentRelative - PlaceOnBottom - PlaceOnTop - PointerMotionHintMask - PointerMotionMask - PointerRoot - PointerWindow - PreferBlanking - PropModeAppend - PropModePrepend - PropModeReplace - PropertyChangeMask - PropertyDelete - PropertyNewValue - PropertyNotify - PseudoColor - RaiseLowest - ReparentNotify - ReplayKeyboard - ReplayPointer - ResizeRedirectMask - ResizeRequest - RetainPermanent - RetainTemporary - RevertToNone - RevertToParent - RevertToPointerRoot - ScreenSaverActive - ScreenSaverReset - SelectionClear - SelectionNotify - SelectionRequest - SetModeDelete - SetModeInsert - ShiftMapIndex - ShiftMask - SouthEastGravity - SouthGravity - SouthWestGravity - StaticColor - StaticGravity - StaticGray - StippleShape - StructureNotifyMask - SubstructureNotifyMask - SubstructureRedirectMask - Success - SyncBoth - SyncKeyboard - SyncPointer - TileShape - TopIf - TrueColor - UnmapGravity - UnmapNotify - Unsorted - VisibilityChangeMask - VisibilityFullyObscured - VisibilityNotify - VisibilityPartiallyObscured - VisibilityUnobscured - WestGravity - WhenMapped - WindingRule - XYBitmap - XYPixmap - X_H - X_PROTOCOL - X_PROTOCOL_REVISION - YSorted - YXBanded - YXSorted - ZPixmap - -=head1 AUTHOR - -Nick Ing-Simmons ran h2xs ... - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/X11Font.pod b/Master/tlpkg/tlperl/lib/Tk/X11Font.pod deleted file mode 100644 index bd5b353abe0..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/X11Font.pod +++ /dev/null @@ -1,88 +0,0 @@ - -=head1 NAME - -Tk::Font - a class for finding X Fonts - -=for pm Tk/X11Font.pm - -=for category Tk Generic Methods - -=head1 SYNOPSIS - - use Tk::X11Font; - - $font = $widget->X11Font(foundry => 'adobe', - family => 'times', - point => 120 - ); - - $font = $widget->X11Font('*-courier-medium-r-normal-*-*'); - -=head1 DESCRIPTION - - This module can be use to interrogate the X server what fonts are - avaliable. - -=head1 METHODS - -=head2 Foundry( [ $val ] ) - -=head2 Family( [ $val ] ) - -=head2 Weight( [ $val ] ) - -=head2 Slant( [ $val ] ) - -=head2 Swidth( [ $val ] ) - -=head2 Adstyle( [ $val ] ) - -=head2 Pixel( [ $val ] ) - -=head2 Point( [ $val ] ) - -=head2 Xres( [ $val ] ) - -=head2 Yres( [ $val ] ) - -=head2 Space( [ $val ] ) - -=head2 Avgwidth( [ $val ] ) - -=head2 Registry( [ $val ] ) - -=head2 Encoding( [ $val ] ) - -Set the given field in the font name to C<$val> if given and return the current -or previous value - -=head2 Name( [ $max ] ) - -In a list context it returns a list of all font names that match the -fields given. It will return a maximum of C<$max> names, or 128 if -$max is not given. - -In a scalar contex it returns the first matching name or undef - -=head2 Clone( [ key => value, [ ...]] ) - -Create a duplicate of the curent font object and modify the given fields - -=head1 AUTHOR - -Graham Barr <Graham.Barr@tiuk.ti.com> - -=head1 HISTORY - -11-Jan-96 Initial version - -08-Nov-98 Renamed for Tk800.012 - -=head1 COPYRIGHT - -Copyright (c) 1995-1996 Graham Barr. All rights reserved. This program is free -software; you can redistribute it and/or modify it under the same terms -as Perl itself. - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/Xrm.pod b/Master/tlpkg/tlperl/lib/Tk/Xrm.pod deleted file mode 100644 index 55f885bc849..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Xrm.pod +++ /dev/null @@ -1,45 +0,0 @@ - -=head1 NAME - -Tk::Xrm - X Resource/Defaults/Options routines that obey the rules. - -=for pm Tk/Xrm.pm - -=for category Creating and Configuring Widgets - -=head1 SYNOPSIS - - use Tk; - use Tk::Xrm; - -=head1 DESCRIPTION - -Using this modules causes Tk's Option code to be replaced by versions -which use routines from <X11/Xresource.h> - i.e. same ones every other -X toolkit uses. - -Result is that "matching" of name/Class with the options database follows -the same rules as other X toolkits. This makes it more predictable, -and makes it easier to have a single ~/.Xdefaults file which gives sensible -results for both Tk and (say) Motif applications. - -=head1 BUGS - -Currently B<optionAdd>(I<key> =E<gt> I<value>?, I<priority>?) ignores optional -priority completely and just does XrmPutStringResource(). -Perhaps it should be more subtle and do XrmMergeDatabases() or -XrmCombineDatabase(). - -This version is a little slower than Tk's re-invention but there is -more optimization that can be done. - -=head1 SEE ALSO - -L<Tk::option|Tk::option> - -=head1 KEYWORDS - -database, option, priority, retrieve - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/after.pod b/Master/tlpkg/tlperl/lib/Tk/after.pod deleted file mode 100644 index 97c61ba380b..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/after.pod +++ /dev/null @@ -1,168 +0,0 @@ -# Copyright (c) 1990-1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::after - Execute a command after a time delay - -=for category Binding Events and Callbacks - -=head1 SYNOPSIS - -S< >I<$widget>-E<gt>B<after>(I<ms>) - -S< >I<$id> = I<$widget>-E<gt>B<after>(I<ms>?,I<callback>?) - -S< >I<$id> = I<$widget>-E<gt>B<repeat>(I<ms>?,I<callback>?) - -S< >I<$widget>-E<gt>B<afterCancel>(I<$id>) - -S< >I<$id> = I<$widget>-E<gt>B<afterIdle>(I<callback>) - -S< >I<$widget>-E<gt>B<afterInfo>?(I<$id>)? - -S< >I<$id>-E<gt>B<time>(?I<delay>?) - -=head1 DESCRIPTION - -This method is used to delay execution of the program or to execute -a callback in background sometime in the future. - -In perl/Tk I<$widget>-E<gt>B<after> is implemented via the class C<Tk::After>, -and callbacks are associated with I<$widget>, and are automatically cancelled -when the widget is destroyed. An almost identical interface, but without -automatic cancel, and without repeat is provided via Tk::after method. - -=head2 Internal Details - -The internal Tk::After class has the following synopsis: - - $id = Tk::After->new($widget, tid, $time, 'once', callback); - $id = Tk::After->new($widget, tid, $time, 'repeat', callback); - $id->cancel; - $id->time(?delay?); - -$id is a Tk::After object, an array of 5 elements: - -I<$widget> is the parent widget reference. - -I<tid> is the internal timer id, a unique string. - -I<$time> is the string 'idle', representing an idle queue timer, or a -integer millisecond value. - -I<once> or I<repeat> specifies whether the timer is a one-time B<after> -event, or a repeating B<repeat> event. - -I<callback> specifies a Perl/Tk Tk::Callback object. - -=head1 Changing a B<repeat> timer interval - -It's posible to change a B<repeat> timer's delay value, or even cancel -any timer, using the B<time> method. If I<delay> is specified and -non-zero, a new timer delay is established. If I<delay> is zero the -timer event is canceled just as if I<$id>-E<gt>B<cancel> were invoked. -In all cases the current millisecond timer delay is returned. - -Note: the new timer delay will take effect on the I<subsequent> timer -event - this command will not cancel the pending timer event and -re-issue it with the new delay time. - -=head1 The after() method has several forms as follows: - -=over 4 - -=item I<$widget>-E<gt>B<after>(I<ms>) - -The value I<ms> must be an integer giving a time in milliseconds. -The command sleeps for I<ms> milliseconds and then returns. -While the command is sleeping the application does not respond to -events. - -=item I<$widget>-E<gt>B<after>(I<ms>,I<callback>) - -In this form the command returns immediately, but it arranges -for I<callback> be executed I<ms> milliseconds later as an -event handler. -The callback will be executed exactly once, at the given time. -The command will be executed in context of I<$widget>. -If an error occurs while executing the delayed command then the -L<Tk::Error|Tk::Error> mechanism is used to report the error. -The B<after> command returns an identifier (an object in the perl/Tk -case) that can be used to cancel the delayed command using B<afterCancel>. - -=item I<$widget>-E<gt>B<repeat>(I<ms>,I<callback>) - -In this form the command returns immediately, but it arranges -for I<callback> be executed I<ms> milliseconds later as an -event handler. After I<callback> has executed it is re-scheduled, -to be executed in a futher I<ms>, and so on until it is cancelled. - -=item I<$widget>-E<gt>B<afterCancel>(I<$id>) - -=item I<$id>-E<gt>B<cancel> - -Cancels the execution of a delayed command that -was previously scheduled. -I<$id> indicates which command should be canceled; it must have -been the return value from a previous B<after> command. -If the command given by I<$id> has already been executed (and -is not scheduled to be executed again) then B<afterCancel> -has no effect. - -=item I<$widget>-E<gt>B<afterCancel>(I<callback>) - -I<This form is not robust in perl/Tk - its use is deprecated.> -This command should also cancel the execution of a delayed command. -The I<callback> argument is compared with pending callbacks, -if a match is found, that callback is -cancelled and will never be executed; if no such callback is -currently pending then the B<afterCancel> has no effect. - -=item I<$widget>-E<gt>B<afterIdle>(I<callback>) - -Arranges for I<callback> to be evaluated later as an idle callback. -The script will be run exactly once, the next time the event -loop is entered and there are no events to process. -The command returns an identifier that can be used -to cancel the delayed command using B<afterCancel>. -If an error occurs while executing the script then the -L<Tk::Error|Tk::Error> mechanism is used to report the error. - -=item I<$widget>-E<gt>B<afterInfo>?(I<$id>)? - -This command returns information about existing event handlers. If no -I<$id> argument is supplied, the command returns a list of the -identifiers for all existing event handlers created by the B<after> -and B<repeat> commands for I<$widget>. If I<$id> is supplied, it -specifies an existing handler; I<$id> must have been the return value -from some previous call to B<after> or B<repeat> and it must not have -triggered yet or been cancelled. In this case the command returns a -list with three elements. The first element of the list is the -callback associated with I<$id>, the second element is either B<idle> -or the I<integer> timer millisecond value to indicate what kind of -event handler it is, and the third is a string I<once> or I<repeat> to -differentiate an B<after> from a B<repeat> event. - -=back - -The B<after>(I<ms>) and B<afterIdle> forms of the command -assume that the application is event driven: the delayed commands -will not be executed unless the application enters the event loop. -In applications that are not normally event-driven, -the event loop can be entered with the B<vwait> and B<update> commands. - -=head1 SEE ALSO - -L<Tk::Error|Tk::Error> -L<Tk::callbacks|Tk::callbacks> - -=head1 KEYWORDS - -cancel, delay, idle callback, sleep, time - -=cut diff --git a/Master/tlpkg/tlperl/lib/Tk/bind.pod b/Master/tlpkg/tlperl/lib/Tk/bind.pod deleted file mode 100644 index f595a48e318..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/bind.pod +++ /dev/null @@ -1,583 +0,0 @@ -# Copyright (c) 1990 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::bind - Arrange for X events to invoke callbacks - -=for category Binding Events and Callbacks - -=head1 SYNOPSIS - -Retrieve bindings: - -S< >I<$widget>-E<gt>B<bind> - -S< >I<$widget>-E<gt>B<bind>(I<tag>) - -S< >I<$widget>-E<gt>B<bind>(I<sequence>) - -S< >I<$widget>-E<gt>B<bind>(I<tag>,I<sequence>) - -Associate and destroy bindings: - -S< >I<$widget>-E<gt>B<bind>(I<sequence>,I<callback>) - -S< >I<$widget>-E<gt>B<bind>(I<tag>,I<sequence>,I<callback>) - -=head1 DESCRIPTION - -The B<bind> method associates callbacks with X events. -If I<callback> is specified, B<bind> will -arrange for I<callback> to be evaluated whenever -the event(s) given by I<sequence> occur in the window(s) -identified by I<$widget> or I<tag>. -If I<callback> is an empty string then the current binding for -I<sequence> is destroyed, leaving I<sequence> unbound. -In all of the cases where a I<callback> argument is provided, -B<bind> returns an empty string. - -If I<sequence> is specified without a I<callback>, then the -callback currently bound to I<sequence> is returned, or -B<undef> is returned if there is no binding for I<sequence>. -If neither I<sequence> nor I<callback> is specified, then the -return value is a list whose elements are all the sequences -for which there exist bindings for I<tag>. - -If no I<tag> is specified then the B<bind> refers to I<$widget>. -If I<tag> is specified then it is typically a class name and the B<bind> -refers to all instances of the class on the B<MainWindow> associated -with I<$widget>. (It is possible for I<tag> to be another "widget object" -but this practice is deprecated.) Perl's B<ref>(I<$object>) can be used -to get the class name of any object. -Each window has an associated list of tags, and a binding applies -to a particular window if its tag is among those specified for -the window. -Although the B<bindtags> method may be used to assign an -arbitrary set of binding tags to a window, the default binding -tags provide the following behavior: - -If a tag is the name of an internal window the binding applies -to that window. - -If the tag is the name of a toplevel window the binding applies -to the toplevel window and all its internal windows. - -If the tag is the name of a class of widgets, such as B<Tk::Button>, -the binding applies to all widgets in that class; - -If I<tag> has the value B<all>, -the binding applies to all windows descended from the MainWindow -of the application. - -=head1 EVENT PATTERNS - -The I<sequence> argument specifies a sequence of one or more event -patterns, with optional white space between the patterns. Each event -pat may take one of three forms. In the simplest case it is a single -printing ASCII character, such as B<a> or B<[>. The character may not -be a space character or the character <. This form of pattern matches -a B<KeyPress> event for the particular character. The second form of -pattern is longer but more general. It has the following syntax: - -S< >'<modifier-modifier-type-detail>' - -The entire event pattern is surrounded by angle brackets, and normally -needs to be quoted, as angle brackets are special to perl. -Inside the angle brackets are zero or more modifiers, an event -type, and an extra piece of information (I<detail>) identifying -a particular button or keysym. Any of the fields may be omitted, -as long as at least one of I<type> and I<detail> is present. -The fields must be separated by white space or dashes. - -The third form of pattern is used to specify a user-defined, named virtual -event; see L<Tk::event> for details. It has the following syntax: - -S< >'<<name>>' - -The entire virtual event pattern is surrounded by double angle brackets. -Inside the angle brackets is the user-defined name of the virtual event. -Modifiers, such as B<Shift> or B<Control>, may not be combined with a -virtual event to modify it. Bindings on a virtual event may be created -before the virtual event is defined, and if the definition of a virtual -event changes dynamically, all windows bound to that virtual event will -respond immediately to the new definition. - -=head1 MODIFIERS - -Modifiers consist of any of the following values: - - Control Mod2, M2 - Shift Mod3, M3 - Lock Mod4, M4 - Button1, B1 Mod5, M5 - Button2, B2 Meta, M - Button3, B3 Alt - Button4, B4 Double - Button5, B5 Triple - Mod1, M1 Quadruple - -Where more than one value is listed, separated by commas, the values -are equivalent. -Most of the modifiers have the obvious X meanings. -For example, B<Button1> requires that -button 1 be depressed when the event occurs. -For a binding to match a given event, the modifiers in the event -must include all of those specified in the event pattern. -An event may also contain additional modifiers not specified in -the binding. -For example, if button 1 is pressed while the shift and control keys -are down, the pattern B<E<lt>Control-Button-1E<gt>> will match -the event, but B<E<lt>Mod1-Button-1E<gt>> will not. -If no modifiers are specified, then any combination of modifiers may -be present in the event. - -B<Meta> and B<M> refer to whichever of the -B<M1> through B<M5> modifiers is associated with the meta -key(s) on the keyboard (keysyms B<Meta_R> and B<Meta_L>). -If there are no meta keys, or if they are not associated with any -modifiers, then B<Meta> and B<M> will not match any events. -Similarly, the B<Alt> modifier refers to whichever modifier -is associated with the alt key(s) on the keyboard (keysyms -B<Alt_L> and B<Alt_R>). - -The B<Double>, B<Triple> and B<Quadruple> modifiers are a convenience -for specifying double mouse clicks and other repeated events. They -cause a particular event pattern to be repeated 2, 3 or 4 times, and -also place a time and space requirement on the sequence: for a -sequence of events to match a B<Double>, B<Triple> or B<Quadruple> -pattern, all of the events must occur close together in time and -without substantial mouse motion in between. For example, -B<E<lt>Double-Button-1E<gt>> is equivalent to -B<E<lt>Button-1E<gt>E<lt>Button-1E<gt>> with the extra time and space -requirement. - -=head1 EVENT TYPES - -The I<type> field may be any of the standard X event types, with a -few extra abbreviations. Below is a list of all the valid types; -where two names appear together, they are synonyms. - - - Activate Destroy Map - ButtonPress, Button Enter MapRequest - ButtonRelease Expose Motion - Circulate FocusIn MouseWheel - CirculateRequest FocusOut Property - Colormap Gravity Reparent - Configure KeyPress, Key ResizeRequest - ConfigureRequest KeyRelease Unmap - Create Leave Visibility - Deactivate - -Most of the above events have the same fields and behaviors as events -in the X Windowing system. You can find more detailed descriptions of -these events in any X window programming book. A couple of the events -are extensions to the X event system to support features unique to the -Macintosh and Windows platforms. We provide a little more detail on -these events here. These include: - - Activate - Deactivate - -These two events are sent to every sub-window of a toplevel when they -change state. In addition to the focus Window, the Macintosh platform -and Windows platforms have a notion of an active window (which often -has but is not required to have the focus). On the Macintosh, widgets -in the active window have a different appearance than widgets in -deactive windows. The Activate event is sent to all the sub-windows -in a toplevel when it changes from being deactive to active. -Likewise, the Deactive event is sent when the window's state changes -from active to deactive. There are no use- ful percent substitutions -you would make when binding to these events. - - MouseWheel - -Some mice on the Windows platform support a mouse wheel which is -used for scrolling documents without using the scrollbars. By -rolling the wheel, the system will generate MouseWheel events that -the application can use to scroll. Like Key events the event is -always routed to the window that currently has focus. When the -event is received you can use the %D substitution to get the delta -field for the event which is a integer value of motion that the -mouse wheel has moved. The smallest value for which the system -will report is defined by the OS. On Windows 95 & 98 machines -this value is at least 120 before it is reported. However, higher -resolution devices may be available in the future. The sign of -the value determines which direction your widget should scroll. -Positive values should scroll up and negative values should scroll -down. - -The last part of a long event specification is I<detail>. In the -case of a B<ButtonPress> or B<ButtonRelease> event, it is the -number of a button (1-5). If a button number is given, then only an -event on that particular button will match; if no button number is -given, then an event on any button will match. Note: giving a -specific button number is different than specifying a button modifier; -in the first case, it refers to a button being pressed or released, -while in the second it refers to some other button that is already -depressed when the matching event occurs. If a button -number is given then I<type> may be omitted: if will default -to B<ButtonPress>. For example, the specifier B<E<lt>1E<gt>> -is equivalent to B<E<lt>ButtonPress-1E<gt>>. - -If the event type is B<KeyPress> or B<KeyRelease>, then -I<detail> may be specified in the form of an X keysym. Keysyms -are textual specifications for particular keys on the keyboard; -they include all the alphanumeric ASCII characters (e.g. ``a'' is -the keysym for the ASCII character ``a''), plus descriptions for -non-alphanumeric characters (``comma'' is the keysym for the comma -character), plus descriptions for all the non-ASCII keys on the -keyboard (``Shift_L'' is the keysm for the left shift key, and -``F1'' is the keysym for the F1 function key, if it exists). The -complete list of keysyms is not presented here; it is -available in other X documentation and may vary from system to -system. -If necessary, you can use the B<'K'> notation described below -to print out the keysym name for a particular key. -If a keysym I<detail> is given, then the -I<type> field may be omitted; it will default to B<KeyPress>. -For example, B<E<lt>Control-commaE<gt>> is equivalent to -B<E<lt>Control-KeyPress-commaE<gt>>. - -=head1 BINDING CALLBACKS AND SUBSTITUTIONS - -The I<callback> argument to B<bind> is a perl/Tk callback. -which will be executed whenever the given event sequence occurs. -(See L<Tk::callbacks> for description of the possible forms.) -I<Callback> will be associated with the same B<MainWindow> -that is associated with the I<$widget> that was used to invoke -the B<bind> method, and it will run as though called from B<MainLoop>. -If I<callback> contains -any B<Ev>(I<%>) calls, then each "nested" B<Ev>(I<%>) -"callback" will be evaluated when the event occurs to form arguments -to be passed to the main I<callback>. -The replacement -depends on the character I<%>, as defined in the -list below. Unless otherwise indicated, the -replacement string is the numeric (decimal) value of the given field from -the current event. Perl/Tk has enhanced this mechanism slightly compared -to the comparable Tcl/Tk mechanism. The enhancements are not yet all -reflected in the list below. -Some of the substitutions are only valid for -certain types of events; if they are used for other types of events -the value substituted is undefined (not the same as B<undef>!). - -=over 4 - -=item B<'#'> - -The number of the last client request processed by the server -(the I<serial> field from the event). Valid for all event -types. - -=item B<'a'> - -The I<above> field from the event, -formatted as a hexadecimal number. -Valid only for B<Configure> events. - -=item B<'b'> - -The number of the button that was pressed or released. Valid only -for B<ButtonPress> and B<ButtonRelease> events. - -=item B<'c'> - -The I<count> field from the event. Valid only for B<Expose> events. - -=item B<'d'> - -The I<detail> field from the event. The B<'d'> is replaced by -a string identifying the detail. For B<Enter>, -B<Leave>, B<FocusIn>, and B<FocusOut> events, -the string will be one of the following: - - NotifyAncestor NotifyNonlinearVirtual - NotifyDetailNone NotifyPointer - NotifyInferior NotifyPointerRoot - NotifyNonlinear NotifyVirtual - -For B<ConfigureRequest> events, the string will be one of: - - Above Opposite - Below None - BottomIf TopIf - -For events other than these, the substituted string is undefined. -(Note that this is I<not> the same as Detail part of sequence -use to specify the event.) - -=item B<'f'> - -The I<focus> field from the event (B<0> or B<1>). Valid only -for B<Enter> and B<Leave> events. - -=item B<'h'> - -The I<height> field from the event. Valid only for B<Configure>, -B<ConfigureRequest>, B<Create>, B<Expose>, and B<ResizeRequest> events. - -=item B<'i'> - -The window field from the event, represented as a hexadecimal integer. - -=item B<'k'> - -The I<keycode> field from the event. Valid only for B<KeyPress> -and B<KeyRelease> events. - -=item B<'m'> - -The I<mode> field from the event. The substituted string is one of -B<NotifyNormal>, B<NotifyGrab>, B<NotifyUngrab>, or -B<NotifyWhileGrabbed>. Valid only for B<Enter>, -B<FocusIn>, B<FocusOut>, and B<Leave> events. - -=item B<'o'> - -The I<override_redirect> field from the event. Valid only for -B<Map>, B<Reparent>, and B<Configure> events. - -=item B<'p'> - -The I<place> field from the event, substituted as one of the -strings B<PlaceOnTop> or B<PlaceOnBottom>. Valid only -for B<Circulate> and B<CirculateRequest> events. - -=item B<'s'> - -The I<state> field from the event. For B<ButtonPress>, -B<ButtonRelease>, B<Enter>, B<KeyPress>, B<KeyRelease>, -B<Leave>, and B<Motion> events, a decimal string -is substituted. For B<Visibility>, one of the strings -B<VisibilityUnobscured>, B<VisibilityPartiallyObscured>, -and B<VisibilityFullyObscured> is substituted. - -=item B<'t'> - -The I<time> field from the event. Valid only for events that -contain a I<time> field. - -=item B<'w'> - -The I<width> field from the event. Valid only for B<Configure>, -B<ConfigueRequest>, B<Create>, B<Expose>, and B<ResizeREquest> events. - -=item B<'x'> - -The I<x> field from the event. Valid only for events containing -an I<x> field. - -=item B<'y'> - -The I<y> field from the event. Valid only for events containing -a I<y> field. - -=item B<'@'> - -The string "@I<x,y>" where I<x> and I<y> are as above. -Valid only for events containing I<x> and I<y> fields. -This format is used my methods of B<Tk::Text> and similar widgets. - -=item B<'A'> - -Substitutes the UNICODE character corresponding to the event, or -the empty string if the event doesn't correspond to a UNICODE character -(e.g. the shift key was pressed). B<XmbLookupString> does all the -work of translating from the event to a UNICODE character. -Valid only for B<KeyPress> and B<KeyRelease> events. - -=item B<'B'> - -The I<border_width> field from the event. Valid only for -B<Configure>, B<ConfigureRequest> and B<Create> events. - -=item B<'D'> - -This reports the delta value of a B<MouseWheel> event. The delta -value represents the rotation units the mouse wheel has been -moved. On Windows 95 & 98 systems the smallest value for the -delta is 120. Future systems may support higher resolution values -for the delta. The sign of the value represents the direction the -mouse wheel was scrolled. - -=item B<'E'> - -The I<send_event> field from the event. Valid for all event types. - -=item B<'K'> - -The keysym corresponding to the event, substituted as a textual -string. Valid only for B<KeyPress> and B<KeyRelease> events. - -=item B<'N'> - -The keysym corresponding to the event, substituted as -a decimal -number. Valid only for B<KeyPress> and B<KeyRelease> events. - -=item B<'R'> - -The I<root> window identifier from the event. Valid only for -events containing a I<root> field. - -=item B<'S'> - -The I<subwindow> window identifier from the event, -as an object if it is one otherwise as a hexadecimal number. -Valid only for events containing a I<subwindow> field. - -=item B<'T'> - -The I<type> field from the event. Valid for all event types. - -=item B<'W'> - -The window to which the event was reported (the -$widget field from the event) - as an perl/Tk object. -Valid for all event types. - -=item B<'X'> - -The I<x_root> field from the event. -If a virtual-root window manager is being used then the substituted -value is the corresponding x-coordinate in the virtual root. -Valid only for -B<ButtonPress>, B<ButtonRelease>, B<KeyPress>, B<KeyRelease>, -and B<Motion> events. - -=item B<'Y'> - -The I<y_root> field from the event. -If a virtual-root window manager is being used then the substituted -value is the corresponding y-coordinate in the virtual root. -Valid only for -B<ButtonPress>, B<ButtonRelease>, B<KeyPress>, B<KeyRelease>, -and B<Motion> events. - -=back - -=head1 MULTIPLE MATCHES - -It is possible for several bindings to match a given X event. -If the bindings are associated with different I<tag>'s, -then each of the bindings will be executed, in order. -By default, a class binding will be executed first, followed -by a binding for the widget, a binding for its toplevel, and -an B<all> binding. -The B<bindtags> method may be used to change this order for -a particular window or to associate additional binding tags with -the window. - -B<return> and B<Tk-E<gt>break> may be used inside a -callback to control the processing of matching callbacks. -If B<return> is invoked, then the current callback -is terminated but Tk will continue processing callbacks -associated with other I<tag>'s. -If B<Tk-E<gt>break> is invoked within a callback, -then that callback terminates and no other callbacks will be invoked -for the event. -(B<Tk-E<gt>break> is implemented via perl's B<die> with a special value -which is "caught" by the perl/Tk "glue" code.) - -If more than one binding matches a particular event and they -have the same I<tag>, then the most specific binding -is chosen and its callback is evaluated. -The following tests are applied, in order, to determine which of -several matching sequences is more specific: -(a) an event pattern that specifies a specific button or key is more specific -than one that doesn't; -(b) a longer sequence (in terms of number -of events matched) is more specific than a shorter sequence; -(c) if the modifiers specified in one pattern are a subset of the -modifiers in another pattern, then the pattern with more modifiers -is more specific. -(d) a virtual event whose physical pattern matches the sequence is less -specific than the same physical pattern that is not associated with a -virtual event. -(e) given a sequence that matches two or more virtual events, one -of the virtual events will be chosen, but the order is undefined. - -If the matching sequences contain more than one event, then tests -(c)-(e) are applied in order from the most recent event to the least recent -event in the sequences. If these tests fail to determine a winner, then the -most recently registered sequence is the winner. - -If there are two (or more) virtual events that are both triggered by the -same sequence, and both of those virtual events are bound to the same window -tag, then only one of the virtual events will be triggered, and it will -be picked at random: - - $widget->eventAdd('<<Paste>>' => '<Control-y>'); - $widget->eventAdd('<<Paste>>' => '<Button-2>'); - $widget->eventAdd <<Scroll>>' => '<Button-2>'); - $widget->bind('Tk::Entry','<<Paste>>',sub { print 'Paste'}); - $widget->bind('Tk::Entry','<<Scroll>>', sub {print 'Scroll'}); - -If the user types Control-y, the B<E<lt>E<lt>PasteE<gt>E<gt>> binding -will be invoked, but if the user presses button 2 then one of -either the B<E<lt>E<lt>PasteE<gt>E<gt>> or the B<E<lt>E<lt>ScrollE<gt>E<gt>> bindings will -be invoked, but exactly which one gets invoked is undefined. - -If an X event does not match any of the existing bindings, then the -event is ignored. -An unbound event is not considered to be an error. - -=head1 MULTI-EVENT SEQUENCES AND IGNORED EVENTS - -When a I<sequence> specified in a B<bind> method contains -more than one event pattern, then its callback is executed whenever -the recent events (leading up to and including the current event) -match the given sequence. This means, for example, that if button 1 is -clicked repeatedly the sequence B<E<lt>Double-ButtonPress-1E<gt>> will match -each button press but the first. -If extraneous events that would prevent a match occur in the middle -of an event sequence then the extraneous events are -ignored unless they are B<KeyPress> or B<ButtonPress> events. -For example, B<E<lt>Double-ButtonPress-1E<gt>> will match a sequence of -presses of button 1, even though there will be B<ButtonRelease> -events (and possibly B<Motion> events) between the -B<ButtonPress> events. -Furthermore, a B<KeyPress> event may be preceded by any number -of other B<KeyPress> events for modifier keys without the -modifier keys preventing a match. -For example, the event sequence B<aB> will match a press of the -B<a> key, a release of the B<a> key, a press of the B<Shift> -key, and a press of the B<b> key: the press of B<Shift> is -ignored because it is a modifier key. -Finally, if several B<Motion> events occur in a row, only -the last one is used for purposes of matching binding sequences. - -=head1 ERRORS - -If an error occurs in executing the callback for a binding then the -B<Tk::Error> mechanism is used to report the error. -The B<Tk::Error> mechanism will be executed at same call level, -and associated with the same B<MainWindow> as -as the callback was invoked. - -=head1 CAVEATS - -Note that for the B<Canvas> widget, the call to B<bind> has to be -fully qualified. This is because there is already a bind method for -the B<Canvas> widget, which binds individual canvas tags. - -S< >I<$canvas>-E<gt>B<Tk::bind> - -=head1 SEE ALSO - -L<Tk::Error|Tk::Error> -L<Tk::callbacks|Tk::callbacks> -L<Tk::bindtags|Tk::bindtags> - -=head1 KEYWORDS - -Event, binding - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/bindtags.pod b/Master/tlpkg/tlperl/lib/Tk/bindtags.pod deleted file mode 100644 index 3ee6ddb9473..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/bindtags.pod +++ /dev/null @@ -1,107 +0,0 @@ -# Copyright (c) 1990 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::bindtags - Determine which bindings apply to a window, and order of evaluation - -=for category Binding Events and Callbacks - -=head1 SYNOPSIS - -I<$widget>-E<gt>B<bindtags>([I<tagList>]); - -I<@tags> = I<$widget>-E<gt>B<bindtags>; - -=head1 DESCRIPTION - -When a binding is created with the B<bind> command, it is -associated either with a particular window such as I<$widget>, -a class name such as B<Tk::Button>, the keyword B<all>, or any -other string. -All of these forms are called I<binding tags>. -Each window has a list of binding tags that determine how -events are processed for the window. -When an event occurs in a window, it is applied to each of the -window's tags in order: for each tag, the most specific binding -that matches the given tag and event is executed. -See the L<Tk::bind> documentation for more information on the matching -process. - -By default, each window has four binding tags consisting of the -the window's class name, name of the window, the name of the window's -nearest toplevel ancestor, and B<all>, in that order. -Toplevel windows have only three tags by default, since the toplevel -name is the same as that of the window. - -Note that this order is I<different> from order used by Tcl/Tk. -Tcl/Tk has the window ahead of the class name in the binding order. -This is because Tcl is procedural rather than object oriented and -the normal way for Tcl/Tk applications to override class bindings -is with an instance binding. However, with perl/Tk the normal way -to override a class binding is to derive a class. The perl/Tk order -causes instance bindings to execute after the class binding, and -so instance bind callbacks can make use of state changes (e.g. changes -to the selection) than the class bindings have made. - -The B<bindtags> command allows the binding tags for a window to be -read and modified. - -If I<$widget>-E<gt>B<bindtags> is invoked without an argument, then the -current set of binding tags for $widget is returned as a list. -If the I<tagList> argument is specified to B<bindtags>, -then it must be a reference to and array; the tags for $widget are changed -to the elements of the array. (A reference to an anonymous array can -be created by enclosin the elements in B<[ ]>.) -The elements of I<tagList> may be arbitrary strings or widget objects, -if no window exists for an object at the time an event is processed, -then the tag is ignored for that event. -The order of the elements in I<tagList> determines the order in -which binding callbacks are executed in response to events. -For example, the command - - $b->bindtags([$b,ref($b),$b->toplevel,'all']) - -applies the Tcl/Tk binding order which binding callbacks will be -evaluated for a button (say) B<$b> so that B<$b>'s instance bindings -are invoked first, following by bindings for B<$b>'s class, followed by -bindings for B<$b>'s toplevel, followed by 'B<all>' bindings. - -If I<tagList> is an empty list i.e. B<[]>, then the binding -tags for $widget are returned to the perl/Tk default state described above. - -The B<bindtags> command may be used to introduce arbitrary -additional binding tags for a window, or to remove standard tags. -For example, the command - - $b->bindtags(['TrickyButton',$b->toplevel,'all']) - -replaces the (say) B<Tk::Button> tag for B<$b> with B<TrickyButton>. -This means that the default widget bindings for buttons, which are -associated with the B<Tk::Button> tag, will no longer apply to B<$b>, -but any bindings associated with B<TrickyButton> (perhaps some -new button behavior) will apply. - -=head1 BUGS - -The current mapping of the 'native' Tk behaviour of this method -i.e. returning a list but only accepting a reference to an array is -counter intuitive. The perl/Tk interface may be tidied up, returning -a list is sensible so, most likely fix will be to allow a list to be -passed to I<set> the bindtags. - -=head1 SEE ALSO - -L<Tk::bind|Tk::bind> -L<Tk::callbacks|Tk::callbacks> - -=head1 KEYWORDS - -binding, event, tag - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/callbacks.pod b/Master/tlpkg/tlperl/lib/Tk/callbacks.pod deleted file mode 100644 index 5b62cb7c12c..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/callbacks.pod +++ /dev/null @@ -1,104 +0,0 @@ -# $Id: callbacks.pod 1.3 Thu, 27 Nov 1997 00:26:00 +0100 ach $ - -=head1 NAME - -Tk::callbacks - Specifying code for Tk to call. - -=for category Binding Events and Callbacks - -=head1 SYNOPSIS - -One can specify a callback in one of the following ways: - -Without arguments: - - ... => \&subname, ... - ... => sub { ... }, ... - ... => 'methodname', ... - -or with arguments: - - ... => [ \&subname, args ... ], ... - ... => [ sub { ... }, args... ], ... - ... => [ 'methodname', args... ], ... - -=head1 DESCRIPTION - -Perl/Tk has a callback, where Tcl/Tk has a command string (i.e. a fragment of -Tcl to be executed). A perl/Tk callback can take one of the following -basic forms: - -=over 4 - -=item * Reference to a subroutine C<\E<amp>subname> - -=item * Anonymous subroutine (closure) C<sub { ... }> - -=item * A method name C<'methodname'> - -=back - -Any of these can be provided with arguments by enclosing them and the -arguments in B<[]>. Here are some examples: - -I<$mw>->B<bind>(I<$class,> B<"E<lt>DeleteE<gt>" =E<gt> 'Delete'>); - -This will call I<$widget>->B<Delete>, the I<$widget> being provided (by bind) as -the one where the Delete key was pressed. - -While having bind provide a widget object for you is ideal in many cases -it can be irritating in others. Using the list form this behaviour -can be modified: - -I<$a>-E<gt>B<bind>(B<"E<lt>DeleteE<gt>">,[I<$b> =E<gt> 'Delete']); - -because the first element I<$b> is an object bind -will call I<$b>-E<gt>B<Delete>. - -Note that method/object ordering only matters for C<bind> callbacks, -the auto-quoting in perl5.001 makes the first of these a little more readable: - - $w->configure(-yscrollcommand => [ set => $ysb]); - $w->configure(-yscrollcommand => [ $ysb => 'set' ]); - -but both will call C<$ysb>-E<gt>set(args provided by Tk) - -Another use of arguments allows you to write generalized methods which are -easier to re-use: - - $a->bind("<Next>",['Next','Page']); - $a->bind("<Down>",['Next','Line']); - -This will call C<$a>-E<gt>I<Next>('Page') or C<$a>-E<gt>I<Next>('Line') respectively. - -Note that the contents of the C<[]> are evaluated by perl when the -callback is created. It is often desirable for the arguments provided -to the callback to depend on the details of the event which caused -it to be executed. To allow for this callbacks can be nested using the -C<Ev(...)> "constructor". -C<Ev(...)> inserts callback objects into the -argument list. When perl/Tk glue code is preparing the argument list for -the callback it is about to call it spots these special objects and -recursively applies the callback process to them. - -=head1 EXAMPLES - - $entry->bind('<Return>' => [$w , 'validate', Ev(['get'])]); - - $toplevel->bind('all', '<Visibility>', [\&unobscure, Ev('s')]); - - $mw->bind($class, '<Down>', ['SetCursor', Ev('UpDownLine',1)]); - -=head1 SEE ALSO - -L<Tk::bind|Tk::bind> -L<Tk::after|Tk::after> -L<Tk::options|Tk::options> -L<Tk::fileevent|Tk::fileevent> - -=head1 KEYWORDS - -callback, closure, anonymous subroutine, bind - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/chooseColor.pod b/Master/tlpkg/tlperl/lib/Tk/chooseColor.pod deleted file mode 100644 index dbb8f158efa..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/chooseColor.pod +++ /dev/null @@ -1,64 +0,0 @@ -# Copyright (c) 1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -chooseColor - pops up a dialog box for the user to select a color. - -=for category Popups and Dialogs - -=head1 SYNOPSIS - -S< >I<$color> = I<$widget>-E<gt>B<chooseColor>?(I<-option>=E<gt>I<value>, ...)?; - -=head1 DESCRIPTION - -The method B<chooseColor> is implemented as a perl wrapper -on the core tk "command" B<tk_chooseColor>, and I<$widget> -is passed as the argument to the hidden B<-parent> option. -The implementation of internal B<tk_chooseColor> is platform -specific, on Win32 it is a native dialog, and on UNIX/X11 it is implemented -in terms of L<Tk::ColorEditor|Tk::ColorEditor>. - -The B<chooseColor> method pops up a dialog box for the -user to select a color. The following I<option-value> pairs are -possible as command line arguments: - -=over 4 - -=item B<-initialcolor>=E<gt>I<color> - -Specifies the color to display in the color dialog when it pops -up. I<color> must be in a form acceptable to the B<Tk_GetColor> -function. - -=item B<-parent>=E<gt>$widget - -Makes $widget the logical parent of the color dialog. The color -dialog is displayed on top of its parent window. - -=item B<-title>=E<gt>I<titleString> - -Specifies a string to display as the title of the dialog box. If this -option is not specified, then a default title will be displayed. - -=back - -If the user selects a color, B<tk_chooseColor> will return the -name of the color in a form acceptable to B<Tk_GetColor>. If the -user cancels the operation, the command will return B<undef>. - -=head1 EXAMPLE - - $widget->configure(-fg => $parent->chooseColor(-initialcolor => 'gray', - -title => "Choose color")); - -=head1 KEYWORDS - -color selection dialog - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/chooseDirectory.pod b/Master/tlpkg/tlperl/lib/Tk/chooseDirectory.pod deleted file mode 100644 index 8a2edc9d672..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/chooseDirectory.pod +++ /dev/null @@ -1,95 +0,0 @@ -# Copyright (c) 1998-2000 by Scriptics Corporation. -# All rights reserved. -# -# RCS: @(#) $Id: chooseDirectory.n,v 1.1 2000/01/27 00:23:10 ericm Exp $ -# - -=head1 NAME - -chooseDirectory - pops up a dialog box for the user to select a directory. - -=for category Tk Generic Methods - -=head1 SYNOPSIS - -I<$widget>-E<gt>B<chooseDirectory>( ?I<option value ...>? ); - -=head1 DESCRIPTION - -The method B<chooseDirectory> is implemented as a perl wrapper on the -core tk "command" B<tk_chooseDirectory>, and I<$widget> is passed as -the argument to the hidden B<-parent> option. - -The B<chooseDirectory> -method pops up a dialog box for the user to select a directory. The -following I<option-value> pairs are possible as command line -arguments: - -=over 4 - -=item B<-initialdir> I<dirname> - -Specifies that the directories in I<directory> should be displayed -when the dialog pops up. If this parameter is not specified, then -the directories in the current working directory are displayed. If the -parameter specifies a relative path, the return value will convert the -relative path to an absolute path. This option may not always work on -the Macintosh. This is not a bug. Rather, the I<General Controls> -control panel on the Mac allows the end user to override the -application default directory. - -=item B<-parent> $widget - -Makes $widget the logical parent of the dialog. The dialog -is displayed on top of its parent window. - -=item B<-title> I<titleString> - -Specifies a string to display as the title of the dialog box. If this -option is not specified, then a default title will be displayed. - -=item B<-mustexist> I<boolean> - -Specifies whether the user may specify non-existant directories. If -this parameter is true, then the user may only select directories that -already exist. The default value is I<false>. - -=back - -=head1 CAVEATS - -Perl does not have a concept of encoded filesystems yet. This means -that operations on filenames like C<opendir> and C<open> still use -byte semantics. Tk however uses character semantics internally, which -means that you can get filenames with the UTF-8 flag set in functions -like C<chooseDirectory>, C<getOpenFile> and similar. It's the user's -responsibility to determine the encoding of the underlying filesystem -and convert the result into bytes, e.g. - - use Encode; - ... - my $dir = $mw->chooseDirectory; - $dir = encode("windows-1252", $dir); - opendir DIR, $dir or die $!; - ... - -See also L<perlunicode/When Unicode Does Not Happen> and -L<perltodo/Unicode in Filenames>. - -=head1 EXAMPLE - - my $dir = $mw->chooseDirectory(-initialdir => '~', - -title => 'Choose a directory'); - if (!defined $dir) { - warn 'No directory selected'; - } else { - warn "Selected $dir"; - } - -=head1 SEE ALSO - -L<Tk::getOpenFile>, L<Tk::getOpenFile> - -=head1 KEYWORDS - -directory selection dialog diff --git a/Master/tlpkg/tlperl/lib/Tk/composite.pod b/Master/tlpkg/tlperl/lib/Tk/composite.pod deleted file mode 100644 index a493b5ee1f2..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/composite.pod +++ /dev/null @@ -1,171 +0,0 @@ -# $Id: composite.pod 1.2 Wed, 12 Nov 1997 00:30:45 +0100 ach $ - -=head1 NAME - -Tk::composite - Defining a new composite widget class - -=for category Derived Widgets - -=head1 SYNOPSIS - - package Tk::MyNewWidget; - - use Tk:widgets qw/ list of Tk widgets /; - use base qw/ Tk::Frame /; # or Tk::Toplevel - - Construct Tk::Widget 'MyNewWidget'; - - sub ClassInit { - my( $class, $mw ) = @_; - #... e.g., class bindings here ... - $class->SUPER::ClassInit( $mw ); - } - - sub Populate { - my( $self, $args ) = @_; - - my $flag = delete $args->{-flag}; - if( defined $flag ) { - # handle -flag => xxx which can only be done at create - # time the delete above ensures that new() does not try - # and do $self->configure( -flag => xxx ); - } - - $self->SUPER::Populate( $args ); - - $self = $self->Component( ... ); - - $self->Delegates( ... ); - - $self->ConfigSpecs( - '-cursor' => [ SELF, 'cursor', 'Cursor', undef ], - '-something' => [ METHOD, dbName, dbClass, default ], - '-text' => [ $label, dbName, dbClass, default ], - '-heading' => [ {-text => $head}, - heading, Heading, 'My Heading' ], - ); - } - - sub something { - my( $self, $value) = @_; - if ( @_ > 1 ) { - # set it - } - return # current value - } - - 1; - - __END__ - - - =head1 NAME - - Tk::Whatever - a whatever widget - - =head1 SYNOPSIS - - use Tk::Whatever; - - $widget = $parent->Whatever(...); - - =head1 DESCRIPTION - - ... - -=head1 DESCRIPTION - -The intention behind a composite is to create a higher-level widget, -sometimes called a "super-widget" or "mega-widget". Most often, -a composite will be -built upon other widgets by B<using> them, as opposed to specializing on them. -For example, the supplied composite widget B<LabEntry> is I<made of> an -B<Entry> and a B<Label>; it is neither a I<kind-of> B<Label> -nor is it a I<kind-of> B<Entry>. - -Most of the work of a composite widget consistd in creating subwidgets, -arranging to dispatch configure options to the proper subwidgets and manage -composite-specific configure options. - -=head1 GLORY DETAILS - -Depending on your Perl/Tk knowledge this section may be enlighting -or confusing. - -=head2 Composite Widget - -Since Perl/Tk is heavilly using an object-oriented approach, it is no -suprise that creating a composite goes through a B<new()> method. -However, the composite does not normally define a B<new()> method -itself: it is usually sufficient to simply inherit it from -B<Tk::Widget>. - -This is what happens when the composite uses - - use base qw/ Tk::Frame /; # or Tk::Toplevel - -to specify its inheritance chain. To complete the initialisation of the -widget, it must call the B<Construct> method from class B<Widget>. That -method accepts the name of the new class to create, i.e. the package name -of your composite widget: - - Construct Tk::Widget 'MyNewWidget'; - -Here, B<MyNewWidget> is the package name (aka the widget's B<class>). This -will define a constructor method for B<MyNewWidget>, normally named after the -widget's class. Instanciating that composite in client code would -the look like: - - $mw = MainWindow->new; # creates a top-level MainWindow - - $self = $mw->MyNewWidget(); # creates an instance of the - # composite widget MyNewWidget - -Whenever a composite is instanciated in client code, -C<Tk::Widget::new()> will be invoked via the widget's class -constructor. That B<new> method will call - - $self->Populate(\%args); - -where I<%args> is the arguments passed to the widget's constructor. Note -that B<Populate> receives a B<reference> to the hash array -containing all arguments. - -B<Populate> is typically defined in the composite class (package), -which creates the characteristic subwidgets of the class. - -=head2 Creating Subwidgets - -Subwidget creation happens usually in B<Populate()>. -The composite usually calls the -subwidget's constructor method either directly, for "private" subwidgets, -or indirectly through the B<Component> method for subwidgets that should -be advertised to clients. - -B<Populate> may call B<Delegates> to direct calls to methods -of chosen subwidgets. For simple composites, typically most if not all -methods are directed -to a single subwidget - e.g. B<ScrListbox> directs all methods to the core -B<Listbox> so that I<$composite>-E<gt>B<get>(...) calls -I<$listbox>-E<gt>B<get>(...). - -=head2 Defining mega-widget options - -B<Populate> should also call B<ConfigSpecs()> to specify the -way that configure-like options should be handled in the composite. -Once B<Populate> returns, method B<Tk::Frame::ConfigDefault> -walks through the B<ConfigSpecs> entries and populates -%$args hash with defaults for options from X resources (F<.Xdefaults>, etc). - -When B<Populate> returns to B<Tk::Widget::new()>, -a call to B<$self>-E<gt>I<configure>(%$args) is made which sets *all* -the options. - -=head1 SEE ALSO - -L<Tk::ConfigSpecs|Tk::ConfigSpecs> -L<Tk::mega|Tk::mega> -L<Tk::Derived|Tk::Derived> - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/event.pod b/Master/tlpkg/tlperl/lib/Tk/event.pod deleted file mode 100644 index 9012a596267..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/event.pod +++ /dev/null @@ -1,417 +0,0 @@ -# Copyright (c) 1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::event - Miscellaneous event facilities: define virtual events and generate events - -=for category Binding Events and Callbacks - -=head1 SYNOPSIS - -I<$widget>-E<gt>B<event>I<Action>(?I<arg, arg, ...>?); - -=head1 DESCRIPTION - -The B<event>I<Action> methods provides several facilities for dealing with -window system events, such as defining virtual events and synthesizing -events. Virtual events are shared by all widgets of the same -B<MainWindow>. Different L<MainWindow|Tk::MainWindow>s can have different -virtual event. - -The following methods are currently supported: - -=over 4 - -=item I<$widget>-E<gt>B<eventAdd>(B<'E<lt>E<lt>>I<virtual>B<E<gt>E<gt>'>I<, sequence >?,I<sequence, ...>?) - -Associates the virtual event I<virtual> with the physical -event sequence(s) given by the I<sequence> arguments, so that -the virtual event will trigger whenever any one of the I<sequence>s -occurs. -I<Virtual> may be any string value and I<sequence> may have -any of the values allowed for the I<sequence> argument to the -L<bind|Tk::bind> method. -If I<virtual> is already defined, the new physical event sequences -add to the existing sequences for the event. - -=item I<$widget>-E<gt>B<eventDelete>(B<'E<lt>E<lt>>I<virtual>B<E<gt>E<gt>'> ?,I<sequence,> I<sequence, ...>?) - -Deletes each of the I<sequence>s from those associated with -the virtual event given by I<virtual>. -I<Virtual> may be any string value and I<sequence> may have -any of the values allowed for the I<sequence> argument to the -L<bind|Tk::bind> method. -Any I<sequence>s not currently associated with I<virtual> -are ignored. -If no I<sequence> argument is provided, all physical event sequences -are removed for I<virtual>, so that the virtual event will not -trigger anymore. - -=item I<$widget>-E<gt>B<eventGenerate>(I<event> ?,I<option =E<gt> value, option =E<gt> value, ...>?) - -Generates a window event and arranges for it to be processed just as if -it had come from the window system. -I<$window> is a reference to the window for which the event -will be generated. -I<Event> provides a basic description of -the event, such as B<E<lt>Shift-Button-2E<gt>> or B<E<lt>E<lt>PasteE<gt>E<gt>>. -If I<Window> is empty the whole screen is meant, and coordinates -are relative to the screen. -I<Event> may have any of the forms allowed for the I<sequence> -argument of the L<bind|Tk::bind> method except that it must consist -of a single event pattern, not a sequence. -I<Option-value> pairs may be used to specify additional -attributes of the event, such as the x and y mouse position; -see L<"EVENT FIELDS"> below. If the B<-when> option is not specified, the -event is processed immediately: all of the handlers for the event -will complete before the B<eventGenerate> method returns. -If the B<-when> option is specified then it determines when the -event is processed. - -=item I<$widget>-E<gt>B<eventInfo>(?'B<E<lt>E<lt>>I<virtual>B<E<gt>E<gt>'>?) - -Returns information about virtual events. -If the B<E<lt>E<lt>>I<virtual>B<E<gt>E<gt>> argument is omitted, the return value -is a list of all the virtual events that are currently defined. -If B<E<lt>E<lt>>I<virtual>B<E<gt>E<gt>> is specified then the return value is -a list whose elements are the physical event sequences currently -defined for the given virtual event; if the virtual event is -not defined then B<undef> is returned. - -=back - -=head1 EVENT FIELDS - -The following options are supported for the B<eventGenerate> -method. These correspond to the ``%'' expansions -allowed in binding callback for the L<bind|Tk::bind> method. - -=over 4 - -=item B<-above> => I<window> - -I<Window> specifies the I<above> field for the event, -either as a window path name or as an integer window id. -Valid for B<Configure> events. -Corresponds to the L<%a|Tk::bind/'a'> substitution for binding scripts. - -=item B<-borderwidth> => I<size> - -I<Size> must be a screen distance; it specifies the -I<border_width> field for the event. -Valid for B<Configure> events. -Corresponds to the L<%B|Tk::bind/'B'> substitution for binding scripts. - -=item B<-button> => I<number> - -I<Number> must be an integer; it specifies the I<detail> field -for a B<ButtonPress> or B<ButtonRelease> event, overriding -any button number provided in the base I<event> argument. -Corresponds to the L<%b|Tk::bind/'b'> substitution for binding scripts. - -=item B<-count> => I<number> - -I<Number> must be an integer; it specifies the I<count> field -for the event. Valid for B<Expose> events. -Corresponds to the L<%c|Tk::bind/'c'> substitution for binding scripts. - -=item B<-delta> =E<gt> I<number> - -B<number> must be an integer; it specifies the B<delta> field for the -B<MouseWheel> event. The delta refers to the direction and magnitude the -mouse wheel was rotated. Note the value is not a screen distance but -are units of motion in the mouse wheel. Typically these values are -multiples of 120. For example, 120 should scroll the text widget up 4 -lines and -240 would scroll the text widget down 8 lines. Of course, -other widgets may define different behaviors for mouse wheel motion. -This field corresponds to the %D substitution for binding scripts. - -=item B<-detail> => I<detail> - -I<Detail> specifies the I<detail> field for the event -and must be one of the following: - -=over 8 - - NotifyAncestor NotifyNonlinearVirtual - NotifyDetailNone NotifyPointer - NotifyInferior NotifyPointerRoot - NotifyNonlinear NotifyVirtual - -=back - -Valid for B<Enter>, B<Leave>, B<FocusIn> and -B<FocusOut> events. -Corresponds to the L<%d|Tk::bind/'d'> substitution for binding scripts. - -=item B<-focus>I< boolean> - -I<Boolean> must be a boolean value; it specifies the I<focus> -field for the event. -Valid for B<Enter> and B<Leave> events. -Corresponds to the L<%f|Tk::bind/'f'> substitution for binding scripts. - -=item B<-height>I< size> - -I<Size> must be a screen distance; it specifies the I<height> -field for the event. Valid for B<Configure> events. -Corresponds to the L<%h|Tk::bind/'h'> substitution for binding scripts. - -=item B<-keycode>I< number> - -I<Number> must be an integer; it specifies the I<keycode> -field for the event. -Valid for B<KeyPress> and B<KeyRelease> events. -Corresponds to the L<%k|Tk::bind/'k'> substitution for binding scripts. - -=item B<-keysym>I< name> - -I<Name> must be the name of a valid keysym, such as B<g>, -B<space>, or B<Return>; its corresponding -keycode value is used as the I<keycode> field for event, overriding -any detail specified in the base I<event> argument. -Valid for B<KeyPress> and B<KeyRelease> events. -Corresponds to the L<%K|Tk::bind/'K'> substitution for binding scripts. - -=item B<-mode>I< notify> - -I<Notify> specifies the I<mode> field for the event and must be -one of B<NotifyNormal>, B<NotifyGrab>, B<NotifyUngrab>, or -B<NotifyWhileGrabbed>. -Valid for B<Enter>, B<Leave>, B<FocusIn>, and -B<FocusOut> events. -Corresponds to the L<%m|Tk::bind/'m'> substitution for binding scripts. - -=item B<-override>I< boolean> - -I<Boolean> must be a boolean value; it specifies the -I<override_redirect> field for the event. -Valid for B<Map>, B<Reparent>, and B<Configure> events. -Corresponds to the L<%o|Tk::bind/'o'> substitution for binding scripts. - -=item B<-place>I< where> - -I<Where> specifies the I<place> field for the event; it must be -either B<PlaceOnTop> or B<PlaceOnBottom>. -Valid for B<Circulate> events. -Corresponds to the L<%p|Tk::bind/'p'> substitution for binding scripts. - -=item B<-root>I< window> - -I<Window> must be either a window path name or an integer window -identifier; it specifies the I<root> field for the event. -Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>, -B<ButtonRelease>, B<Enter>, B<Leave>, and B<Motion> -events. -Corresponds to the L<%R|Tk::bind/'R'> substitution for binding scripts. - -=item B<-rootx>I< coord> - -I<Coord> must be a screen distance; it specifies the I<x_root> -field for the event. -Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>, -B<ButtonRelease>, B<Enter>, B<Leave>, and B<Motion> -events. Corresponds to the L<%X|Tk::bind/'X'> substitution for binding scripts. - -=item B<-rooty>I< coord> - -I<Coord> must be a screen distance; it specifies the I<y_root> -field for the event. -Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>, -B<ButtonRelease>, B<Enter>, B<Leave>, and B<Motion> -events. -Corresponds to the L<%Y|Tk::bind/'Y'> substitution for binding scripts. - -=item B<-sendevent>I< boolean> - -B<Boolean> must be a boolean value; it specifies the I<send_event> -field for the event. Valid for all events. Corresponds to the -L<%E|Tk::bind/'E'> substitution for binding scripts. - -=item B<-serial>I< number> - -I<Number> must be an integer; it specifies the I<serial> field -for the event. Valid for all events. -Corresponds to the L<%#|Tk::bind/'#'> substitution for binding scripts. - -=item B<-state>I< state> - -I<State> specifies the I<state> field for the event. -For B<KeyPress>, B<KeyRelease>, B<ButtonPress>, -B<ButtonRelease>, B<Enter>, B<Leave>, and B<Motion> events -it must be an integer value. -For B<Visibility> events it must be one of B<VisibilityUnobscured>, -B<VisibilityPartiallyObscured>, or B<VisibilityFullyObscured>. -This option overrides any modifiers such as B<Meta> or B<Control> -specified in the base I<event>. -Corresponds to the L<%s|Tk::bind/'s'> substitution for binding scripts. - -=item B<-subwindow>I< window> - -I<Window> specifies the I<subwindow> field for the event, either -as a path name for a Tk widget or as an integer window identifier. -Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>, -B<ButtonRelease>, B<Enter>, B<Leave>, and B<Motion> events. -Similar to L<%S|Tk::bind/'S'> substitution for binding scripts. - -=item B<-time>I< integer> - -I<Integer> must be an integer value; it specifies the I<time> field -for the event. -Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>, -B<ButtonRelease>, B<Enter>, B<Leave>, B<Motion>, -and B<Property> events. -Corresponds to the L<%t|Tk::bind/'t'> substitution for binding scripts. - - -=item B<-warp>I< boolean> - -I<boolean> must be a boolean value; it specifies whether -the screen pointer should be warped as well. -Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>, -B<ButtonRelease>, and B<Motion> events. - -=item B<-width>I< size> - -I<Size> must be a screen distance; it specifies the I<width> field -for the event. -Valid for B<Configure> events. -Corresponds to the L<%w|Tk::bind/'w'> substitution for binding scripts. - -=item B<-when>I< when> - -I<When> determines when the event will be processed; it must have one -of the following values: - -=over 8 - -=item B<now> - -Process the event immediately, before the command returns. -This also happens if the B<-when> option is omitted. - -=item B<tail> - -Place the event on perl/Tk's event queue behind any events already -queued for this application. - -=item B<head> - -Place the event at the front of perl/Tk's event queue, so that it -will be handled before any other events already queued. - -=item B<mark> - -Place the event at the front of perl/Tk's event queue but behind any -other events already queued with B<-when mark>. -This option is useful when generating a series of events that should -be processed in order but at the front of the queue. - -=back - -=item B<-x>I< coord> - -I<Coord> must be a screen distance; it specifies the I<x> field -for the event. -Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>, -B<ButtonRelease>, B<Motion>, B<Enter>, B<Leave>, -B<Expose>, B<Configure>, B<Gravity>, and B<Reparent> -events. -Corresponds to the the L<%x|Tk::bind/'x'> substitution for binding scripts. -If I<Window> is empty the coordinate is relative to the -screen, and this option corresponds to the L<%X|Tk::bind/'X'> substitution -for binding scripts. - -=item B<-y>I< coord> - -I<Coord> must be a screen distance; it specifies the I<y> -field for the event. -Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>, -B<ButtonRelease>, B<Motion>, B<Enter>, B<Leave>, -B<Expose>, B<Configure>, B<Gravity>, and B<Reparent> -events. -Corresponds to the the L<%y|Tk::bind/'y'> substitution for binding scripts. -If I<Window> is empty the coordinate is relative to the -screen, and this option corresponds to the L<%Y|Tk::bind/'Y'> substitution -for binding scripts. - -Any options that are not specified when generating an event are filled -with the value 0, except for I<serial>, which is filled with the -next X event serial number. - -=back - -=head1 VIRTUAL EVENT EXAMPLES - -In order for a virtual event binding to trigger, two things must -happen. First, the virtual event must be defined with the -B<eventAdd> method. Second, a binding must be created for -the virtual event with the B<bind> method. -Consider the following virtual event definitions: - - $widget->eventAdd('<<Paste>>' => '<Control-y>'); - $widget->eventAdd('<<Paste>>' => '<Button-2>'); - $widget->eventAdd('<<Save>>' => '<Control-X><Control-S>'); - $widget->eventAdd('<<Save>>' => '<Shift-F12>'); - -In the B<bind> method, a virtual event can be bound like any other -builtin event type as follows: - - $entry->bind('Tk::Entry', '<<Paste>>' => sub { - $entry->Insert($entry->selectionGet) }); - -The double angle brackets are used to specify that a virtual event is being -bound. If the user types Control-y or presses button 2, or if -a B<E<lt>E<lt>PasteE<gt>E<gt>> virtual event is synthesized with B<eventGenerate>, -then the B<E<lt>E<lt>PasteE<gt>E<gt>> binding will be invoked. - -If a virtual binding has the exact same sequence as a separate -physical binding, then the physical binding will take precedence. -Consider the following example: - - $mw->eventAdd('<<Paste>>' => '<Control-y>','<Meta-Control-y>'); - $mw->bind('Tk::Entry', '<Control-y>' => sub{print 'Control-y'}); - $mw->bind('Tk::Entry', '<<Paste>>' => sub{print 'Paste'}); - -When the user types Control-y the B<E<lt>Control-yE<gt>> binding -will be invoked, because a physical event is considered -more specific than a virtual event, all other things being equal. -However, when the user types Meta-Control-y the -B<E<lt>E<lt>PasteE<gt>E<gt>> binding will be invoked, because the -B<Meta> modifier in the physical pattern associated with the -virtual binding is more specific than the B<E<lt>Control-y>E<gt> sequence for -the physical event. - -Bindings on a virtual event may be created before the virtual event exists. -Indeed, the virtual event never actually needs to be defined, for instance, -on platforms where the specific virtual event would meaningless or -ungeneratable. - -When a definition of a virtual event changes at run time, all windows -will respond immediately to the new definition. -Starting from the preceding example, if the following code is executed: - - $entry->bind(ref($entry), '<Control-y>' => undef); - $entry->eventAdd('<<Paste>>' => '<Key-F6>'); - -the behavior will change such in two ways. First, the shadowed -B<E<lt>E<lt>PasteE<gt>E<gt>> binding will emerge. -Typing Control-y will no longer invoke the B<E<lt>Control-yE<gt>> binding, -but instead invoke the virtual event B<E<lt>E<lt>PasteE<gt>E<gt>>. Second, -pressing the F6 key will now also invoke the B<E<lt>E<lt>PasteE<gt>E<gt>> binding. - -=head1 SEE ALSO - -L<Tk::bind|Tk::bind> -L<Tk::callbacks|Tk::callbacks> - -=head1 KEYWORDS - -event, binding, define, handle, virtual event - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/exit.pod b/Master/tlpkg/tlperl/lib/Tk/exit.pod deleted file mode 100644 index bb564cd0b82..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/exit.pod +++ /dev/null @@ -1,42 +0,0 @@ -# Copyright (c) 1993 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::exit - End the application - -=for category Binding Events and Callbacks - -=head1 SYNOPSIS - - use Tk qw(exit); - ... - B<exit>?(I<returnCode>)?; - -=head1 DESCRIPTION - -Terminate the process, returning I<returnCode> to the -system as the exit status. -If I<returnCode> isn't specified then it defaults -to 0. - -If calling C<exit> from code invoked via a Tk callback then -this Tk version of C<exit> cleans up more reliably than using -the perl C<exit>. - -=head1 CAVEATS - -Using C<exit> from a forked process will terminate both the child -process B<and> the parent process. As C<Tk::exit> is imported by -default one should use C<CORE::exit> in the forked process instead. - -=head1 KEYWORDS - -exit, process - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/fileevent.pod b/Master/tlpkg/tlperl/lib/Tk/fileevent.pod deleted file mode 100644 index 1a98cfd6b71..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/fileevent.pod +++ /dev/null @@ -1,112 +0,0 @@ -# Copyright (c) 1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::fileevent - Execute a callback when a filehandle becomes readable or writable - -=for category Binding Events and Callbacks - -=head1 SYNOPSIS - -I<$widget>-E<gt>B<fileevent>(I<fileHandle>,B<readable>?,I<callback>?) - -I<$widget>-E<gt>B<fileevent>(I<fileHandle>,B<writable>?,I<callback>?) - -=head1 DESCRIPTION - -This command is used to create I<file event handlers>. A file event -handler is a binding between a filehandle and a callback, such that the callback -is evaluated whenever the filehandle becomes readable or writable. File event -handlers are most commonly used to allow data to be received from another -process on an event-driven basis, so that the receiver can continue to -interact with the user while waiting for the data to arrive. If an -application invokes C<E<lt>E<gt>>, C<sysread> or C<read> on a blocking filehandle when -there is no input data available, the process will block; until the input -data arrives, it will not be able to service other events, so it will -appear to the user to ``freeze up''. With B<fileevent>, the process can -tell when data is present and only invoke B<gets> or B<read> when -they won't block. - -The I<fileHandle> argument to B<fileevent> refers to an open filehandle, -such as the return value from a previous B<open> or B<socket> -command. -If the I<callback> argument is specified, then B<fileevent> -creates a new event handler: I<callback> will be evaluated -whenever the filehandle becomes readable or writable (depending on the -argument to B<fileevent>). -In this case B<fileevent> returns an empty string. -The B<readable> and B<writable> event handlers for a file -are independent, and may be created and deleted separately. -However, there may be at most one B<readable> and one B<writable> -handler for a file at a given time in a given interpreter. -If B<fileevent> is called when the specified handler already -exists in the invoking interpreter, the new callback replaces the old one. - -If the I<callback> argument is not specified, B<fileevent> -returns the current callback for I<fileHandle>, or an empty string -if there is none. -If the I<callback> argument is specified as an empty string -then the event handler is deleted, so that no callback will be invoked. -A file event handler is also deleted automatically whenever -its filehandle is closed or its interpreter is deleted. - -A filehandle is considered to be readable if there is unread data -available on the underlying device. -A filehandle is also considered to be readable if an end of file or -error condition is present on the underlying file or device. -It is important for I<callback> to check for these conditions -and handle them appropriately; for example, if there is no special -check for end of file, an infinite loop may occur where I<callback> -reads no data, returns, and is immediately invoked again. - -A filehandle is considered to be writable if at least one byte of data -can be written to the underlying file or device without blocking, -or if an error condition is present on the underlying file or device. - -Event-driven I/O works best for filehandles that have been -placed into nonblocking mode. -In blocking mode, a C<print> command may block if you give it -more data than the underlying file or device can accept, and a -C<E<lt>E<gt>>, C<sysread> or C<read> command will block if you attempt to read -more data than is ready; no events will be processed while the -commands block. -In nonblocking mode C<print>, C<E<lt>E<gt>>, C<sysread> and C<read> never block. -See the documentation for the individual commands for information -on how they handle blocking and nonblocking filehandles. - -The callback for a file event is executed in the context of I<$widget> -with which B<fileevent> was invoked. -If an error occurs while executing the callback then the -L<Tk::Error> mechanism is used to report the error. -In addition, the file event handler is deleted if it ever returns -an error; this is done in order to prevent infinite loops due to -buggy handlers. - -=head1 BUGS - -On windows platforms B<fileevent> is limited in the types of filehandles -that behave correctly. Making filefhandles non-blocking is only implemented -on a subset of UNIX platforms (see L<Tk::IO>). - -=head1 CREDITS - -B<fileevent> is based on the B<addinput> command created -by Mark Diekhans. - -=head1 SEE ALSO - -L<Tk::IO|Tk::IO> -L<Tk::callbacks|Tk::callbacks> - -=head1 KEYWORDS - -asynchronous I/O, blocking, filehandle, event handler, nonblocking, readable, -callback, writable. - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/focus.pod b/Master/tlpkg/tlperl/lib/Tk/focus.pod deleted file mode 100644 index 61dab55b277..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/focus.pod +++ /dev/null @@ -1,166 +0,0 @@ -# Copyright (c) 1990-1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -focus - Manage the input focus - -=for category User Interaction - -=head1 SYNOPSIS - -S< >I<$widget>-E<gt>B<focus> - -S< >I<$widget>-E<gt>B<focus>I<Option> - -S< >I<$widget>-E<gt>B<focusNext> - -S< >I<$widget>-E<gt>B<focusPrev> - -S< >I<$widget>-E<gt>B<focusFollowsMouse> - -=head1 DESCRIPTION - -The B<focus> methods are used to manage the Tk input focus. -At any given time, one window on each display is designated as -the I<focus window>; any key press or key release events for the -display are sent to that window. -It is normally up to the window manager to redirect the focus among the -top-level windows of a display. For example, some window managers -automatically set the input focus to a top-level window whenever -the mouse enters it; others redirect the input focus only when -the user clicks on a window. -Usually the window manager will set the focus -only to top-level windows, leaving it up to the application to -redirect the focus among the children of the top-level. - -Tk remembers one focus window for each top-level (the most recent -descendant of that top-level to receive the focus); when the window -manager gives the focus -to a top-level, Tk automatically redirects it to the remembered -window. Within a top-level Tk uses an I<explicit> focus model -by default. Moving the mouse within a top-level does not normally -change the focus; the focus changes only when a widget -decides explicitly to claim the focus (e.g., because of a button -click), or when the user types a key such as Tab that moves the -focus. - -The method B<focusFollowsMouse> may be invoked to -create an I<implicit> focus model: it reconfigures Tk so that -the focus is set to a window whenever the mouse enters it. -The methods B<focusNext> and B<focusPrev> -implement a focus order among the windows of a top-level; they -are used in the default bindings for Tab and Shift-Tab, among other -things. - -The B<focus> methods can take any of the following forms: - -=over 4 - -=item I<$widget>-E<gt>B<focusCurrent> - -Returns the focus window on the display containing -the I<$widget>, or an empty string if no window in -this application has the focus on that display. - -=item I<$widget>-E<gt>B<focus> - -If the application currently has the input focus on I<$widget>'s -display, this command resets the input focus for I<$widget>'s display -to I<$widget> and returns an empty string. -If the application doesn't currently have the input focus on -I<$widget>'s display, I<$widget> will be remembered as the focus -for its top-level; the next time the focus arrives at the top-level, -Tk will redirect it to I<$widget>. - -=item I<$widget>-E<gt>B<focusForce> - -Sets the focus of I<$widget>'s display to I<$widget>, even if -the application doesn't currently have the input focus for the display. -This command should be used sparingly, if at all. -In normal usage, an application should not claim the focus for -itself; instead, it should wait for the window manager to give it -the focus. - -=item I<$widget>-E<gt>B<focusLastfor> - -Returns the name of the most recent window to have the input focus -among all the windows in the same top-level as I<$widget>. -If no window in that top-level has ever had the input focus, or -if the most recent focus window has been deleted, then -the top-level is returned. The return value is the window that -will receive the input focus the next time the window manager gives -the focus to the top-level. - -=item I<$widget>-E<gt>B<focusNext> - -=item I<$widget>-E<gt>B<focusPrev> - -B<focusNext> is a utility method used for keyboard traversal, but can be -useful in other contexts. -It sets the focus to the ``next'' window after I<$widget> in focus order. -The focus order is determined by -the stacking order of windows and the structure of the window hierarchy. -Among siblings, the focus order is the same as the stacking order, with the -lowest window being first. -If a window has children, the window is visited first, followed by -its children (recursively), followed by its next sibling. -Top-level windows other than I<$widget> are skipped, so that -B<focusNext> never returns a window in a different top-level -from I<$widget>. - -After computing the next window, B<focusNext> examines the -window's B<-takefocus> option to see whether it should be skipped. -If so, B<focusNext> continues on to the next window in the focus -order, until it eventually finds a window that will accept the focus -or returns back to I<$widget>. - -B<focusPrev> is similar to B<focusNext> except that it -sets the focus to the window just before I<$widget> in the focus order. - -=item I<$widget>-E<gt>B<focusFollowsMouse> - -B<focusFollowsMouse> changes the focus model for the application -to an implicit one where the window under the mouse gets the focus. -After this procedure is called, whenever the mouse enters a window -Tk will automatically give it the input focus. -The B<focus> command may be used to move the focus to a window -other than the one under the mouse, but as soon as the mouse moves -into a new window the focus will jump to that window. -Note: at present there is no built-in support for returning the -application to an explicit focus model; to do this you'll have -to write a script that deletes the bindings created by -B<focusFollowsMouse>. - -=back - -=head1 QUIRKS - -When an internal window receives the input focus, Tk doesn't actually -set the X focus to that window; as far as X is concerned, the focus -will stay on the top-level window containing the window with the focus. -However, Tk generates FocusIn and FocusOut events just as if the X -focus were on the internal window. This approach gets around a -number of problems that would occur if the X focus were actually moved; -the fact that the X focus is on the top-level is invisible unless -you use C code to query the X server directly. - -=head1 CAVEATS - -Note that for the B<Canvas> widget, the call to B<focus> has to be -fully qualified. This is because there is already a focus method for -the B<Canvas> widget, which sets the focus on individual canvas tags. - -S< >I<$canvas>-E<gt>B<Tk::focus> - - -=head1 KEYWORDS - -events, focus, keyboard, top-level, window manager - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/form.pod b/Master/tlpkg/tlperl/lib/Tk/form.pod deleted file mode 100644 index 64208c8e26e..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/form.pod +++ /dev/null @@ -1,397 +0,0 @@ -# Copyright (c) 1996, Expert Interface Technologies -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# The file man.macros and some of the macros used by this file are -# copyrighted: (c) 1990 The Regents of the University of California. -# (c) 1994-1995 Sun Microsystems, Inc. -# The license terms of the Tcl/Tk distribution are in the file -# license.tcl. - -=head1 NAME - -Tk::form - Geometry manager based on attachment rules - -=for category Tk Geometry Management - -=head1 SYNOPSIS - -S< >I<$widget>->B<form>?(I<args>)? - -S< >I<$widget>->B<form>I<Option>?(I<args>)? - -=head1 DESCRIPTION - -The B<form> method is used to communicate with the -B<form> Geometry Manager, a geometry manager that arranges the -geometry of the children in a parent window according to attachment -rules. The B<form> geometry manager is very flexible and -powerful; it can be used to emulate all the existing features of the -Tk packer and placer geometry managers (see L<pack|Tk::pack>, -L<place|Tk::place>). -The B<form> method can have any of several forms, -depending on I<Option>: - -=over 4 - -=item I<$slave>->B<form>?(I<options>)? - -Sets or adjusts the attachment values of the slave window -according to the I<-option>=>I<value> argument pairs. - -=over 8 - -=item B<-b> => I<attachment> - -Abbreviation for the B<-bottom> option. - -=item B<-bottom> => I<attachment> - -Specifies an attachment for the bottom edge of the slave window. The -attachment must specified according to L<"SPECIFYING ATTACHMENTS"> below. - -=item B<-bottomspring> => I<weight> - -Specifies the weight of the spring at the bottom edge of the slave -window. See L<"USING SPRINGS"> below. - -=item B<-bp> => I<value> - -Abbreviation for the B<-padbottom> option. - -=item B<-bs> => I<weight> - -Abbreviation for the B<-bottomspring> option. - -=item B<-fill> => I<style> - -Specifies the fillings when springs are used for this widget. The -value must be B<x>, B<y>, B<both> or B<none>. - -=item B<-in> => I<$master> - -Places the slave window into the specified I<$master> window. If the slave -was originally in another master window, all attachment values with -respect to the original master window are discarded. Even if the -attachment values are the same as in the original master window, they -need to be specified again. The B<-in> flag, when needed, must appear -as the first flag of I<options>. Otherwise an error is -generated. - -=item B<-l> => I<attachment> - -Abbreviation for the B<-left> option. - -=item B<-left> => I<attachment> - -Specifies an attachment for the left edge of the slave window. The -attachment must specified according to L<"SPECIFYING ATTACHMENTS"> below. - -=item B<-leftspring> => I<weight> - -Specifies the weight of the spring at the left edge of the slave -window. See L<"USING SPRINGS"> below. - -=item B<-lp> => I<value> - -Abbreviation for the B<-padleft> option. - -=item B<-ls> => I<weight> - -Abbreviation for the B<-leftspring> option. - -=item B<-padbottom> => I<value> - -Specifies the amount of external padding to leave on the bottom side -of the slave. The I<value> may have any of the forms acceptable to -B<Tk_GetPixels>. - -=item B<-padleft> => I<value> - -Specifies the amount of external padding to leave on the left side of -the slave. - -=item B<-padright> => I<value> - -Specifies the amount of external padding to leave on the right side of -the slave. - -=item B<-padtop> => I<value> - -Specifies the amount of external padding to leave on the top side of -the slave. - -=item B<-padx> => I<value> - -Specifies the amount of external padding to leave on both the left and -the right sides of the slave. - -=item B<-pady> => I<value> - -Specifies the amount of external padding to leave on both the top and -the bottom sides of the slave. - -=item B<-r> => I<attachment> - -Abbreviation for the B<-right> option. - -=item B<-right> => I<attachment> - -Specifies an attachment for the right edge of the slave window. The -attachment must specified according to L<"SPECIFYING ATTACHMENTS"> below. - -=item B<-rightspring> => I<weight> - -Specifies the weight of the spring at the right edge of the slave -window. See L<"USING SPRINGS"> below. - -=item B<-rp> => I<value> - -Abbreviation for the B<-padright> option. - -=item B<-rs> => I<weight> - -Abbreviation for the B<-rightspring> option. - -=item B<-t> => I<attachment> - -Abbreviation for the B<-top> option. - -=item B<-top> => I<attachment> - -Specifies an attachment for the top edge of the slave window. The -attachment must specified according to L<"SPECIFYING ATTACHMENTS"> below. - -=item B<-topspring> => I<weight> - -Specifies the weight of the spring at the top edge of the slave -window. See L<"USING SPRINGS"> below. - -=item B<-tp> => I<value> - -Abbreviation for the B<-padtop> option. - -=item B<-ts> => I<weight> - -Abbreviation for the B<-topspring> option. - -=back - -=item I<$master>->B<formCheck> - -This method checks whether there is circular dependency in the -attachments of the master's slaves (see L<"CIRCULAR DEPENDENCY"> below). -It returns the Boolean value B<TRUE> if it -discover circular dependency and B<FALSE> otherwise. - -=item I<$slave>->B<formForget> - -Removes the slave from its master and unmaps its window. -The slave will no longer be managed by form. All attachment values -with respect to its master window are discarded. If another slave -is attached to this slave, then the attachment of the other slave will -be changed to grid attachment based on its geometry. - -=item I<$master>->B<formGrid>?(I<x_size, y_size>)? - -When I<x_size> and I<y_size> are given, this method returns the -number of grids of the I<$master> window in a pair of integers of the form -(I<x_size, y_size>). When both I<x_size> and I<y_size> are -given, this method changes the number of horizontal and vertical -grids on the master window. - -=item I<$slave>->B<formInfo>?(I<-option)>? - -Queries the attachment options of a slave window. I<-option> can be -any of the options accepted by the B<form> method. If -I<-option> is given, only the value of that option is returned. -Otherwise, this method returns a list whose elements are the current -configuration state of the slave given in the same I<option-value> form -that might be specified to B<form>. The first two -elements in this list list are "B<-in>=>I<$master>" where -I<$master> is the slave's master window. - -=item I<$master>->B<formSlaves> - -Returns a list of all of the slaves for the master window. The order -of the slaves in the list is the same as their order in the packing -order. If master has no slaves then an empty string is returned. - -=back - -=head1 SPECIFYING ATTACHMENTS - -One can specify an attachment for each side of a slave window managed -by form. An attachment is specified in the the form "-I<side> => -[I<anchor_point>, I<offset>]". -I<side> can be one of -B<-top>, B<-bottom>, B<-left> or B<-right>. - -I<Offset> is given in screen units (i.e. any of the forms -acceptable to B<Tk_GetPixels>). A positive offset indicates -shifting to a position to the right or bottom of an anchor point. A -negative offset indicates shifting to a position to the left or top of -an anchor point. - -I<Anchor_point> can be given in one of the -following forms: - -=over 4 - -=item B<Grid Attachment> - -The master window is divided into a number of horizontal and vertical -grids. By default the master window is divided into 100x100 grids; the -number of grids can be adjusted by the B<formGrid> method. A -grid attachment anchor point is given by a B<%> sign followed by an -integer value. For example, B<'%0'> specifies the first grid -line (the top or left edge of the master window). B<'%100'> specifies -the last grid line (the bottom or right edge of the master window). - -=item B<Opposite Side Attachment> - -Opposite attachment specifies an anchor point located on the -B<opposite> side of another slave widget, which must be managed by -form in the same master window. An opposite attachment anchor point -is given by the name of another widget. For example, -"I<$b>->B<form>(B<-top>=>[I<$a>,0])" attaches the top side of the widget I<$b> to the -bottom of the widget I<$a>. - -=item B<Parallel Side Attachment> - -Opposite attachment specifies an anchor point located on the -B<same> side of another slave widget, which must be managed by -form in the same master window. An parallel attachment anchor point -is given by the sign B<E<amp>> follwed by the name of another widget. -For example, "I<$b>->B<form>(B<-top>=>['&',I<$a>,0])" attaches the top side of -the widget I<$b> to the top of the widget I<$a>, making -the top sides of these two widgets at the same vertical position -in their parent window. - -=item B<No Attachment> - -Specifies a side of the slave to be attached to nothing, indicated by -the keyword B<none>. When the B<none> anchor point is given, the -offset must be zero (or not present). -When a side of a slave is attached to B<['none', 0]>, the position -of this side is calculated by the position of the other side and the -natural size of the slave. For example, if a the left side of a -widget is attached to B<['%0', 100]>, its right side attached to -B<['none', 0]>, and the natural size of the widget is B<50> pixels, -the right side of the widget will be positioned at pixel -B<['%0', 149]>. -When both B<-top> and B<-bottom> are attached to B<none>, -then by default B<-top> will be attached to B<['%0', 0]>. When both -B<-left> and B<-right> are attached to none, then by default -B<-left> will be attached to B<['%0', 0]>. - -=back - -Shifting effects can be achieved by specifying a non-zero offset with -an anchor point. In the following example, the top side of -widget I<\$b> is attached to the bottom of -I<\$a>; hence I<\$b> -always appears below I<\$a>. Also, the left edge of I<\$b> -is attached to the left side of I<\$a> with a 10 -pixel offest. Therefore, the left edge of I<\$b> is always -shifted 10 pixels to the right of I<\$a>'s left edge: - -S< >I<$b>->B<form>(B<-left>=>[I<$a>,10], B<-top>=>[I<$a>,0]); - -=head2 ABBREVIATIONS: - -Certain abbreviations can be made on the -attachment specifications: First an offset of zero can be omitted. -Thus, the following two lines are equivalent: - -S< >I<$b>->B<form>(B<-top>=>[I<$a>,0], B<-right>=>['%100',0]); - -S< >I<$b>->B<form>(B<-top>=>[I<$a>], B<-right>=>'%100'); - -In the second case, when the anchor point is omitted, the offset must -be given. A default anchor point is chosen according to the value of -the offset. If the anchor point is B<0> or positive, the default -anchor point %0 is used; thus, "I<$b>->B<form>(B<-top>=>15)" attaches the top -edge of I<$b> to a position 15 pixels below the top edge of the -master window. If the anchor point is "B<-0>" or negative, the -default anchor point B<%100> is used; thus, "I<$a>->B<form>(B<-right>=>-2)" -attaches the right edge of I<\$a> to a position 2 pixels to -the left of the master window's right edge. An further example -below shows a method with its equivalent abbreviation. - -S< >I<$b>->B<form>(B<-top>=>['%0',10], B<-bottom>=>['%100',0]); - -S< >I<$b>->B<form>(B<-top>=>10, B<-bottom>=>-0); - -=head1 USING SPRINGS - -To be written. - -=head1 ALGORITHM OF FORM - -B<form> starts with any slave in the list of slaves of the master -window. Then it tries to determine the position of each side of the -slave. - -If the attachment of a side of the slave is grid attachment, the -position of the side is readily determined. - -If the attachment of this side is B<none>, then form tries to -determine the position of the opposite side first, and then use the -position of the opposite side and the natural size of the slave to -determine the position of this side. - -If the attachment is opposite or parallel widget attachments, then -form tries to determine the positions of the other widget first, -and then use the positions of the other widget and the natural size of -the slave determine the position of this side. This recursive -algorithmis carried on until the positions of all slaves are -determined. - -=head1 CIRCULAR DEPENDENCY - -The algorithm of form will fail if a circular dependency exists in -the attachments of the slaves. For example: - -S< >I<$c>->B<form>(B<-left>=>I<$b>); - -S< >I<$b>->B<form>(B<-right>=>I<$c>); - -In this example, the position of the left side of I<$b> depends on -the right side of I<$c>, which in turn depends on the left side of I<$b>. - -When a circular dependency is discovered during the execution of the -form algorithm, form will generate a background error and the -geometry of the slaves are undefined (and will be arbitrary). Notice -that form only executes the algorithm when the specification of the -slaves' attachments is complete. Therefore, it allows intermediate -states of circular dependency during the specification of the slaves' -attachments. Also, unlike the Motif Form manager widget, form -defines circular dependency as -``I<dependency in the same dimension>''. -Therefore, the following code fragment will does not -have circular dependency because the two widgets do not depend on each -other in the same dimension (I<$b> depends I<$c> in the -horizontal dimension and I<$c> depends on I<$b> in the vertical -dimension): - -S< >I<$b>->B<form>(B<-left>=>I<$c>); - -S< >I<$c>->B<form>(B<-top>=>I<$b>); - -=head1 BUGS - -Springs have not been fully implemented yet. - -=head1 SEE ALSO - -L<Tk::grid|Tk::grid> -L<Tk::pack|Tk::pack> -L<Tk::place|Tk::place> - -=head1 KEYWORDS - -geometry manager, form, attachment, spring, propagation, size, pack, -tix, master, slave - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/getOpenFile.pod b/Master/tlpkg/tlperl/lib/Tk/getOpenFile.pod deleted file mode 100644 index 56d39422afd..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/getOpenFile.pod +++ /dev/null @@ -1,182 +0,0 @@ -# Copyright (c) 1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. - -=head1 NAME - -getOpenFile, getSaveFile - pop up a dialog box for the user to select a file to open or save. - -=for category Popups and Dialogs - -=head1 SYNOPSIS - -S< >I<$widget>-E<gt>B<getOpenFile>(?I<-option>=E<gt>value, ...>?) - -S< >I<$widget>-E<gt>B<getSaveFile>(?I<-option>=E<gt>value, ...>?) - -=head1 DESCRIPTION - -The methods B<getOpenFile> and B<getSaveFile> pop up a -dialog box for the user to select a file to open or save. - -The B<getOpenFile> method is usually associated with the B<Open> -command in the B<File> menu. Its purpose is for the user to select an -existing file I<only>. If the user enters an non-existent file, the -dialog box gives the user an error prompt and requires the user to give -an alternative selection. If an application allows the user to create -new files, it should do so by providing a separate B<New> menu command. - -The B<getSaveFile> method is usually associated with the B<Save> -as command in the B<File> menu. If the user enters a file that -already exists, the dialog box prompts the user for confirmation -whether the existing file should be overwritten or not. - -If the user selects a file, both B<getOpenFile> and -B<getSaveFile> return the full pathname of this file. If the -user cancels the operation, both commands return an undefined value. - -The following I<option-value> pairs are possible as command line -arguments to these two commands: - -=over 4 - -=item B<-defaultextension> =E<gt> I<extension> - -Specifies a string that will be appended to the filename if the user -enters a filename without an extension. The default value is the empty -string, which means no extension will be appended to the filename in -any case. This option is ignored on the Macintosh platform, which -does not require extensions to filenames, and the UNIX implementation -guesses reasonable values for this from the B<-filetypes> -option when this is not supplied. - -=item B<-filetypes> =E<gt> [I<filePattern> ?, ...?] - -If a B<File types> listbox exists in the file dialog on the particular -platform, this option gives the I<filetype>s in this listbox. When -the user choose a filetype in the listbox, only the files of that type -are listed. If this option is unspecified, or if it is set to the -empty list, or if the B<File types> listbox is not supported by the -particular platform then all files are listed regardless of their -types. See L<"SPECIFYING FILE PATTERNS"> below for a -discussion on the contents of I<filePattern>s. - -=item B<-initialdir> =E<gt> I<directory> - -Specifies that the files in I<directory> should be displayed -when the dialog pops up. If this parameter is not specified, then -the files in the current working directory are displayed. This -option may not always work on the Macintosh. This is not a bug. -Rather, the I<General Controls> control panel on the Mac allows the -end user to override the application default directory. - -=item B<-initialfile> =E<gt> I<filename> - -Specifies a filename to be displayed in the dialog when it pops -up. This option is ignored by the B<getOpenFile> method. - -=item B<-multiple> - -Allows the user to choose multiple files from the Open dialog. On the -Macintosh, this is only available when Navigation Services are -installed. - -=item B<-message> =E<gt> I<string> - -Specifies a message to include in the client area of the dialog. This -is only available on the Macintosh, and only when Navigation Services -are installed. - -=item B<-title> =E<gt> I<titleString> - -Specifies a string to display as the title of the dialog box. If this -option is not specified, then a default title is displayed. This -option is ignored on the Macintosh platform. - -=back - -=head1 SPECIFYING FILE PATTERNS - -The I<filePattern>s given by the B<-filetypes> option -are a list of file patterns. Each file pattern is a list of the -form - - typeName [extension ?extension ...?] ?[macType ?macType ...?]? - -I<typeName> is the name of the file type described by this -file pattern and is the text string that appears in the B<File types> -listbox. I<extension> is a file extension for this file pattern. -I<macType> is a four-character Macintosh file type. The list of -I<macType>s is optional and may be omitted for applications that do -not need to execute on the Macintosh platform. - -Several file patterns may have the same I<typeName,> in which case -they refer to the same file type and share the same entry in the -listbox. When the user selects an entry in the listbox, all the files -that match at least one of the file patterns corresponding -to that entry are listed. Usually, each file pattern corresponds to a -distinct type of file. The use of more than one file patterns for one -type of file is necessary on the Macintosh platform only. - -On the Macintosh platform, a file matches a file pattern if its -name matches at least one of the I<extension>(s) AND it -belongs to at least one of the I<macType>(s) of the -file pattern. For example, the B<C Source Files> file pattern in the -sample code matches with files that have a B<\.c> extension AND -belong to the I<macType> B<TEXT>. To use the OR rule instead, -you can use two file patterns, one with the I<extensions> only and -the other with the I<macType> only. The B<GIF Files> file type -in the sample code matches files that EITHER have a B<\.gif> -extension OR belong to the I<macType> B<GIFF>. - -On the Unix and Windows platforms, a file matches a file pattern -if its name matches at at least one of the I<extension>(s) of -the file pattern. The I<macType>s are ignored. - -=head1 SPECIFYING EXTENSIONS - -On the Unix and Macintosh platforms, extensions are matched using -glob-style pattern matching. On the Windows platforms, extensions are -matched by the underlying operating system. The types of possible -extensions are: (1) the special extension * matches any -file; (2) the special extension "" matches any files that -do not have an extension (i.e., the filename contains no full stop -character); (3) any character string that does not contain any wild -card characters (* and ?). - -Due to the different pattern matching rules on the various platforms, -to ensure portability, wild card characters are not allowed in the -extensions, except as in the special extension *. Extensions -without a full stop character (e.g, ~) are allowed but may not -work on all platforms. - -=head1 CAVEATS - -See L<Tk::chooseDirectory/CAVEATS>. - -=head1 EXAMPLE - - my $types = [ - ['Text Files', ['.txt', '.text']], - ['TCL Scripts', '.tcl' ], - ['C Source Files', '.c', 'TEXT'], - ['GIF Files', '.gif', ], - ['GIF Files', '', 'GIFF'], - ['All Files', '*', ], - ]; - my $filename = $widget->getOpenFile(-filetypes=>$types); - - if ($filename ne "") { - # Open the file ... - } - -=head1 SEE ALSO - -L<Tk::FBox|Tk::FBox>, L<Tk::FileSelect|Tk::FileSelect> - -=head1 KEYWORDS - -file selection dialog - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/grab.pod b/Master/tlpkg/tlperl/lib/Tk/grab.pod deleted file mode 100644 index 98a488d09f7..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/grab.pod +++ /dev/null @@ -1,140 +0,0 @@ -# Copyright (c) 1992 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -grab - Confine pointer and keyboard events to a window sub-tree - -=for category User Interaction - -=head1 SYNOPSIS - -I<$widget>-E<gt>B<grab> - -I<$widget>-E<gt>B<grab>I<Option> - -=head1 DESCRIPTION - -This set of methods implement simple pointer and keyboard grabs for Tk. -Tk's grabs are different than the grabs -described in the Xlib documentation. -When a grab is set for a particular window, Tk restricts all pointer -events to the grab window and its descendants in Tk's window hierarchy. -Whenever the pointer is within the grab window's subtree, the pointer -will behave exactly the same as if there had been no grab at all -and all events will be reported in the normal fashion. -When the pointer is outside I<$widget>'s tree, button presses and -releases and -mouse motion events are reported to I<$widget>, and window entry -and window exit events are ignored. -The grab subtree ``owns'' the pointer: -windows outside the grab subtree will be visible on the screen -but they will be insensitive until the grab is released. -The tree of windows underneath the grab window can include top-level -windows, in which case all of those top-level windows -and their descendants will continue to receive mouse events -during the grab. - -Two forms of grabs are possible: local and global. -A local grab affects only the grabbing application: events will -be reported to other applications as if the grab had never occurred. -Grabs are local by default. -A global grab locks out all applications on the screen, -so that only the given subtree of the grabbing application will be -sensitive to pointer events (mouse button presses, mouse button releases, -pointer motions, window entries, and window exits). -During global grabs the window manager will not receive pointer -events either. - -During local grabs, keyboard events (key presses and key releases) -are delivered as usual: the window -manager controls which application receives keyboard events, and -if they are sent to any window in the grabbing application then they are -redirected to the focus window. -During a global grab Tk grabs the keyboard so that all keyboard events -are always sent to the grabbing application. -The B<focus> method is still used to determine which window in the -application receives the keyboard events. -The keyboard grab is released when the grab is released. - -Grabs apply to particular displays. If an application has windows -on multiple displays then it can establish a separate grab on each -display. -The grab on a particular display affects only the windows on -that display. -It is possible for different applications on a single display to have -simultaneous local grabs, but only one application can have a global -grab on a given display at once. - -The B<grab> methods take any of the following forms: - -=over 4 - -=item I<$widget>-E<gt>B<grabCurrent> - -Returns the current grab -window in this application for I<$widget>'s display, or an empty -string if there is no such window. - -=item I<$widget>-E<gt>B<grabs> - -Returns a list whose elements -are all of the windows grabbed by this application for all displays, -or an empty string if the application has no grabs. - -I<Not implemented yet!> - -=item I<$widget>-E<gt>B<grabRelease> - -Releases the grab on I<$widget> if there is one, otherwise does -nothing. Returns an empty string. - -=item I<$widget>-E<gt>B<grab> - -Sets a local grab on I<$widget>. -If a grab was already in effect for this application on -I<$widget>'s display then it is automatically released. -If there is already a local grab on I<$widget>, then the command -does nothing. Returns an empty string. - -=item I<$widget>-E<gt>B<grabGlobal> - -Sets a global grab on I<$widget>. -If a grab was already in effect for this application on -I<$widget>'s display then it is automatically released. -If there is already a global grab on I<$widget>, -then the command does nothing. Returns an empty string. - -=item I<$widget>-E<gt>B<grabStatus> - -Returns B<none> if no grab is currently set on I<$widget>, -B<local> if a local grab is set on I<$widget>, and -B<global> if a global grab is set. - -=back - -=head1 BUGS - -It took an incredibly complex and gross implementation to produce -the simple grab effect described above. -Given the current implementation, it isn't safe for applications -to use the Xlib grab facilities at all except through the Tk grab -procedures. -If applications try to manipulate X's grab mechanisms directly, -things will probably break. - -If a single process is managing several different Tk applications, -only one of those applications can have a local grab for a given -display at any given time. If the applications are in different -processes, this restriction doesn't exist. - -=head1 KEYWORDS - -grab, keyboard events, pointer events, window - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/grid.pod b/Master/tlpkg/tlperl/lib/Tk/grid.pod deleted file mode 100644 index 8db89587a62..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/grid.pod +++ /dev/null @@ -1,409 +0,0 @@ -# Copyright (c) 1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::grid - Geometry manager that arranges widgets in a grid - -=for category Tk Geometry Management - -=head1 SYNOPSIS - -S< >I<$widget>-E<gt>B<grid>?(?I<widget> ...,? ?I<arg> ?...>?)? - -S< >I<$widget>-E<gt>B<grid>I<Option>?(I<arg> ?,I<arg> ...?)? - -=head1 DESCRIPTION - -The B<grid> method is used to communicate with the grid -geometry manager that arranges widgets in rows and columns inside -of another window, called the geometry master (or master window). -The B<grid> method can have any of several forms, depending -on the I<option> argument: - -=over 4 - -=item I<$slave>-E<gt>B<grid>(?I<$slave, ...>??, I<options>?) - -The arguments consist of the optional references to more slave windows -followed by pairs of arguments that specify how to manage the slaves. -The characters B<->, B<x> and B<^>, -can be specified instead of a window reference to alter the default -location of a I<$slave>, as described in L<"RELATIVE PLACEMENT">, below. - -If any of the slaves are already managed by the geometry manager -then any unspecified options for them retain their previous values rather -than receiving default values. - -The following options are supported: - -=over 8 - -=item B<-column> => I<n> - -Insert the I<$slave> so that it occupies the I<n>th column in the grid. -Column numbers start with 0. If this option is not supplied, then the -I<$slave> is arranged just to the right of previous slave specified on this -call to B<grid>, or column "0" if it is the first slave. For each -B<x> that immediately precedes the I<$slave>, the column position -is incremented by one. Thus the B<x> represents a blank column -for this row in the grid. - -=item B<-columnspan> => I<n> - -Insert the slave so that it occupies I<n> columns in the grid. -The default is one column, unless the window name is followed by a -B<->, in which case the columnspan is incremented once for each immediately -following B<->. - -=item B<-in> => I<$other> - -Insert the slave(s) in the master -window given by I<$other>. The default is the first slave's -parent window. - -=item B<-ipadx> => I<amount> - -The I<amount> specifies how much horizontal internal padding to -leave on each side of the slave(s). This is space is added -inside the slave(s) border. -The I<amount> must be a valid screen distance, such as B<2> or B<'.5c'>. -It defaults to 0. - -=item B<-ipady> => I<amount> - -The I<amount> specifies how much vertical internal padding to -leave on on the top and bottom of the slave(s). -This space is added inside the slave(s) border. -The I<amount> defaults to 0. - -=item B<-padx> => I<amount> - -The I<amount> specifies how much horizontal external padding to -leave on each side of the slave(s), in screen units. -The I<amount> defaults to 0. -This space is added outside the slave(s) border. - -=item B<-pady> => I<amount> - -The I<amount> specifies how much vertical external padding to -leave on the top and bottom of the slave(s), in screen units. -The I<amount> defaults to 0. -This space is added outside the slave(s) border. - -=item B<-row> => I<n> - -Insert the slave so that it occupies the I<n>th row in the grid. -Row numbers start with 0. If this option is not supplied, then the -slave is arranged on the same row as the previous slave specified on this -call to B<grid>, or the first unoccupied row if this is the first slave. - -=item B<-rowspan> => I<n> - -Insert the slave so that it occupies I<n> rows in the grid. -The default is one row. If the next B<grid> method contains -B<^> characters instead of I<$slave>s that line up with the columns -of this I<$slave>, then the B<rowspan> of this I<$slave> is -extended by one. - -=item B<-sticky> => I<style> - -If a slave's cell is larger than its requested dimensions, this -option may be used to position (or stretch) the slave within its cell. -I<Style> is a string that contains zero or more of the characters -B<n>, B<s>, B<e> or B<w>. -The string can optionally contain spaces or -commas, but they are ignored. Each letter refers to a side (north, south, -east, or west) that the slave will "stick" to. If both B<n> and B<s> (or -B<e> and B<w>) are specified, the slave will be stretched to fill the entire -height (or width) of its cavity. The B<sticky> option subsumes the -combination of B<-anchor> and B<-fill> that is used by L<pack|Tk::pack>. -The default is B<''>, which causes the slave to be centered in its cavity, -at its requested size. - -=back - -=item I<$master>-E<gt>B<gridBbox>(?I<column, row>,? ?I<column2, row2>?) - -With no arguments, -the bounding box (in pixels) of the grid is returned. -The return value consists of 4 integers. The first two are the pixel -offset from the master window (x then y) of the top-left corner of the -grid, and the second two integers are the width and height of the grid, -also in pixels. If a single I<column> and I<row> is specified on -the command line, then the bounding box for that cell is returned, where the -top left cell is numbered from zero. If both I<column> and I<row> -arguments are specified, then the bounding box spanning the rows and columns -indicated is returned. - -=item I<$master>-E<gt>B<gridColumnconfigure>(I<index>?, I<-option>=>I<value, ...>?) - -Query or set the column properties of the I<index> column of the -geometry master, I<$master>. -The valid options are B<-minsize>, B<-weight> and B<-pad>. -If one or more options are provided, then I<index> may be given as -a list of column indices to which the configuration options will operate on. -The B<-minsize> option sets the minimum size, in screen units, -that will be permitted for this column. -The B<-weight> option (an integer value) -sets the relative weight for apportioning -any extra spaces among -columns. -A weight of zero (0) indicates the column will not deviate from its requested -size. A column whose weight is two will grow at twice the rate as a column -of weight one when extra space is allocated to the layout. -The B<-uniform> option, when a -non-empty value is supplied, places the column in a I<uniform -group> with other columns that have the same value for B<-uniform>. -The space for columns belonging to a uniform group is allocated -so that their sizes are always in strict proportion to their -B<-weight> values. See I<THE GRID ALGORITHM> below for further -details. -The B<-pad> option specifies the number of screen units that will be -added to the largest window contained completely in that column when the -grid geometry manager requests a size from the containing window. -If only an option is specified, with no value, -the current value of that option is returned. -If only the master window and index is specified, all the current settings -are returned in an list of "-option value" pairs. - -=item I<$slave>-E<gt>B<gridConfigure>(?I<$slave, ...>?, I<options>?) - -The same as B<grid> method. - -=item I<$slave>-E<gt>B<gridForget>?(I<$slave, ...>)? - -Removes each of the I<$slave>s from grid for its -master and unmaps their windows. -The slaves will no longer be managed by the grid geometry manager. -The configuration options for that window are forgotten, so that if the -slave is managed once more by the grid geometry manager, the initial -default settings are used. - -=item I<$slave>-E<gt>B<gridInfo> - -Returns a list whose elements are the current configuration state of -the slave given by I<$slave> in the same option-value form that -might be specified to B<gridConfigure>. -The first two elements of the list are ``B<-in>=>I<$master>'' where -I<$master> is the slave's master. - -=item I<$master>-E<gt>B<gridLocation>(I<x, y>) - -Given I<x> and I<y> values in screen units relative to the master window, -the column and row number at that I<x> and I<y> location is returned. -For locations that are above or to the left of the grid, B<-1> is returned. - -=item I<$master>-E<gt>B<gridPropagate>?(I<boolean>)? - -If I<boolean> has a true boolean value such as B<1> or B<on> -then propagation is enabled for I<$master>, which must be a window -name (see L<"GEOMETRY PROPAGATION"> below). -If I<boolean> has a false boolean value then propagation is -disabled for I<$master>. -In either of these cases an empty string is returned. -If I<boolean> is omitted then the method returns B<0> or -B<1> to indicate whether propagation is currently enabled -for I<$master>. -Propagation is enabled by default. - -=item I<$master>-E<gt>B<gridRowconfigure>(I<index>?, I<-option>=>I<value, ...>?) - -Query or set the row properties of the I<index> row of the -geometry master, I<$master>. -The valid options are B<-minsize>, B<-weight> and B<-pad>. -If one or more options are provided, then I<index> may be given as -a list of row indeces to which the configuration options will operate on. -The B<-minsize> option sets the minimum size, in screen units, -that will be permitted for this row. -The B<-weight> option (an integer value) -sets the relative weight for apportioning -any extra spaces among -rows. -A weight of zero (0) indicates the row will not deviate from its requested -size. A row whose weight is two will grow at twice the rate as a row -of weight one when extra space is allocated to the layout. -The B<-uniform> option, when a non-empty value is supplied, places the -row in a I<uniform group> with other rows that have the same value -for B<-uniform>. The space for rows belonging to a uniform group -is allocated so that their sizes are always in strict proportion -to their B<-weight> values. See I<THE GRID ALGORITHM> below for -further details. -The B<-pad> option specifies the number of screen units that will be -added to the largest window contained completely in that row when the -grid geometry manager requests a size from the containing window. -If only an option is specified, with no value, -the current value of that option is returned. -If only the master window and index is specified, all the current settings -are returned in an list of "option-value" pairs. - -=item I<$slave>-E<gt>B<gridRemove>?(I<$slave, ...>)? - -Removes each of the I<$slave>s from grid for its -master and unmaps their windows. -The slaves will no longer be managed by the grid geometry manager. -However, the configuration options for that window are remembered, -so that if the -slave is managed once more by the grid geometry manager, the previous -values are retained. - -=item I<$master>-E<gt>B<gridSize> - -Returns the size of the grid (in columns then rows) for I<$master>. -The size is determined either by the I<$slave> occupying the largest -row or column, or the largest column or row with a B<-minsize>, -B<-weight>, or B<-pad> that is non-zero. - -=item I<$master>-E<gt>B<gridSlaves>?(I<-option>=>I<value>)? - -If no options are supplied, a list of all of the slaves in I<$master> -are returned, most recently manages first. -I<-option> can be either B<-row> or B<-column> which -causes only the slaves in the row (or column) specified by I<value> -to be returned. - -=back - -=head1 RELATIVE PLACEMENT - -The B<grid> method contains a limited set of capabilities that -permit layouts to be created without specifying the row and column -information for each slave. This permits slaves to be rearranged, -added, or removed without the need to explicitly specify row and -column information. -When no column or row information is specified for a I<$slave>, -default values are chosen for -B<-column>, B<-row>, B<-columnspan> and B<-rowspan> -at the time the I<$slave> is managed. The values are chosen -based upon the current layout of the grid, the position of the I<$slave> -relative to other I<$slave>s in the same grid method, and the presence -of the characters B<->, B<^>, and B<^> in B<grid> -method where I<$slave> names are normally expected. - -=over 4 - -=item B<-> - -This increases the columnspan of the I<$slave> to the left. Several -B<->'s in a row will successively increase the columnspan. A B<-> -may not follow a B<^> or a B<x>. - -=item B<x> - -This leaves an empty column between the I<$slave> on the left and -the I<$slave> on the right. - -=item B<^> - -This extends the B<-rowspan> of the I<$slave> above the B<^>'s -in the grid. The number of B<^>'s in a row must match the number of -columns spanned by the I<$slave> above it. - -=back - -=head1 THE GRID ALGORITHM - -The grid geometry manager lays out its slaves in three steps. -In the first step, the minimum size needed to fit all of the slaves -is computed, then (if propagation is turned on), a request is made -of the master window to become that size. -In the second step, the requested size is compared against the actual size -of the master. If the sizes are different, then space is added to or taken -away from the layout as needed. -For the final step, each slave is positioned in its row(s) and column(s) -based on the setting of its I<sticky> flag. - -To compute the minimum size of a layout, the grid geometry manager -first looks at all slaves whose columnspan and rowspan values are one, -and computes the nominal size of each row or column to be either the -I<minsize> for that row or column, or the sum of the I<pad>ding -plus the size of the largest slave, whichever is greater. Then the -slaves whose rowspans or columnspans are greater than one are -examined. If a group of rows or columns need to be increased in size -in order to accommodate these slaves, then extra space is added to each -row or column in the group according to its I<weight>. For each -group whose weights are all zero, the additional space is apportioned -equally. - -When multiple rows or columns belong to a uniform group, the space -allocated to them is always in proportion to their weights. (A weight -of zero is considered to be 1.) In other words, a row or column -configured with B<-weight 1 -uniform> a will have exactly the same size -as any other row or column configured with B<-weight 1 -uniform a>. A -row or column configured with B<-weight 2 -uniform b> will be exactly -twice as large as one that is configured with B<-weight 1 -uniform b>. - -More technically, each row or column in the group will have a size -equal to I<k*weight> for some constant k. The constant k is chosen so -that no row or column becomes smaller than its minimum size. For -example, if all rows or columns in a group have the same weight, then -each row or column will have the same size as the largest row or -column in the group. - - -For masters whose size is larger than the requested layout, the additional -space is apportioned according to the row and column weights. If all of -the weights are zero, the layout is centered within its master. -For masters whose size is smaller than the requested layout, space is taken -away from columns and rows according to their weights. However, once a -column or row shrinks to its minsize, its weight is taken to be zero. -If more space needs to be removed from a layout than would be permitted, as -when all the rows or columns are at there minimum sizes, the layout is -clipped on the bottom and right. - -=head1 GEOMETRY PROPAGATION - -The grid geometry manager normally computes how large a master must be to -just exactly meet the needs of its slaves, and it sets the -requested width and height of the master to these dimensions. -This causes geometry information to propagate up through a -window hierarchy to a top-level window so that the entire -sub-tree sizes itself to fit the needs of the leaf windows. -However, the B<gridPropagate> method may be used to -turn off propagation for one or more masters. -If propagation is disabled then grid will not set -the requested width and height of the master window. -This may be useful if, for example, you wish for a master -window to have a fixed size that you specify. - -=head1 RESTRICTIONS ON MASTER WINDOWS - -The master for each slave must either be the slave's parent -(the default) or a descendant of the slave's parent. -This restriction is necessary to guarantee that the -slave can be placed over any part of its master that is -visible without danger of the slave being clipped by its parent. -In addition, all slaves in one call to B<grid> must have the same master. - -=head1 STACKING ORDER - -If the master for a slave is not its parent then you must make sure -that the slave is higher in the stacking order than the master. -Otherwise the master will obscure the slave and it will appear as -if the slave hasn't been managed correctly. -The easiest way to make sure the slave is higher than the master is -to create the master window first: the most recently created window -will be highest in the stacking order. - -=head1 CREDITS - -The B<grid> method is based on ideas taken from the I<GridBag> -geometry manager written by Doug. Stein, and the B<blt_table> geometry -manager, written by George Howlett. - -=head1 SEE ALSO - -L<Tk::form|Tk::form> -L<Tk::pack|Tk::pack> -L<Tk::place|Tk::place> - -=head1 KEYWORDS - -geometry manager, location, grid, cell, propagation, size, pack, -master, slave - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/mega.pod b/Master/tlpkg/tlperl/lib/Tk/mega.pod deleted file mode 100644 index 76e40e7891f..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/mega.pod +++ /dev/null @@ -1,423 +0,0 @@ - -## Author: Achim Bohnet <ach@mpe.mpg.de> -## -## Copyright (c) 1997-1998 Achim Bohnet. All rights reserved. -## You can redistribute this document and/or modify it under the -## same terms as Perl itself. -## -## Update for Tk804.025, Steve Lidie, 2004/01/11. - -=head1 NAME - -Tk::mega - Perl/Tk support for writing widgets in pure Perl - -=for category Derived Widgets - -=head1 SYNOPSIS - -Define the widget's new class name: - -S< >B<package Tk::>I<MyNewWidget>; - -For composite widget classes: - -S< >B<use base qw/ Tk::container />; # where B<container> is I<Frame> or I<Toplevel> - -For derived widget classes: - -S< >B<use base qw/ Tk::Derived Tk::DerivedWidget /;> - -Install the new widget in Tk's namespace and establish class and instance -constructors. - -S< >B<Construct Tk::>I<Widget> I<'MyNewWidget'>; - -S< >B<sub ClassInit> { I<my ($self, $args) = @_; ...> } - -S< >B<sub Populate> { I<my ($self, $args) = @_; ...> } - -=head1 DESCRIPTION - -The goal of the mega-widget support of Perl/Tk is to make it -easy to write mega-widgets that obey the same protocol and -interface that the Tk core widgets support. -I<For mega-widget sample code please run the B<widget> demonstration program and go to the section B<Sample Perl Mega-Widgets>.> - -There are two kinds of mega-widgets: - -=over 4 - -=item * Composite Widgets - -A composite widget is composed with one or more existing widgets. -The composite widget looks to the user like a simple single widget. -A well known example is the file selection box. - -=item * Derived Widgets - -A derived widget adds/modifies/removes properties and methods -from a single widget (this widget may itself be a mega-widget). - -=back - -=head1 MEGA-WIDGET SUPPORT - -=head2 Advertise - -Give a subwidget a symbolic name. - -Usage: - -S< >I<$self>-E<gt>B<Advertise>(B<name>=E<gt>I<$widget>); - -Gives a subwidget I<$widget> of the mega-widget I<$self> the -name B<name>. One can retrieve the reference of an advertised subwidget -with the L<Subwidget|"Subwidget"> method. - -B<Comment:> Mega-Widget Writers: Please make sure to document the -advertised widgets that are intended for I<public> use. -If there are none, document this fact, e.g.: - - =head1 ADVERTISED WIDGETS - - None. - -=head2 Callback - -Invoke a callback specified with an option. - -Usage: - -S< >I<$self>-E<gt>B<Callback>(I<-option> ?,I<args> ...?); - -B<Callback> executes the L<callback|Tk::callbacks> defined with -I<$self>-E<gt>B<ConfigSpecs>(I<-option>, [B<CALLBACK>, ...]); -If I<args> are given they are passed to the callback. If -I<-option> is not defined it does nothing. - -=head2 ClassInit - -Initialization of the mega-widget class. - -Usage: - -S< >B<sub ClassInit> { I<my ($class, $mw) = @_;> ... } - -B<ClassInit> is called once for I<each> L<MainWindow|Tk::MainWindow> -just before the first widget instance of a class is created in -the widget tree of B<MainWindow>. - -B<ClassInit> is often used to define bindings and/or other -resources shared by all instances, e.g., images. - -Examples: - - $mw->bind($class,"<Tab>", sub { my $w = shift; $w->Insert("\t"); $w->focus; $w->break}); - $mw->bind($class,"<Return>", ['Insert',"\n"]); - $mw->bind($class,"<Delete>",'Delete'); - -Notice that I<$class> is the class name (e.g. B<Tk::MyText>) and I<$mw> is the mainwindow. - -Don't forget to call I<$class>-E<gt>B<SUPER::ClassInit($mw)> in -B<ClassInit>. - -=head2 Component - -Convenience function to create subwidgets. - -Usage: - - $cw->Component('Whatever', 'AdvertisedName', - -delegate => ['method1', 'method2', ...], - ... more widget options ..., - ); - -B<Component> does several things for you with one call: - -=over 4 - -o Creates the widget - -o Advertises it with a given name (overridden by 'Name' option) - -o Delegates a set of methods to this widget (optional) - -=back - -Example: - - $cw->Component('Button', 'quitButton', -command => sub{$mw->'destroy'}); - -=head2 ConfigSpecs - -Defines options and their treatment - -Usage: - - $cw->ConfigSpecs( - -option => [ where, dbname, dbclass, default], - ..., - DEFAULT => [where], - ); - -Defines the options of a mega-widget and what actions -are triggered by configure/cget of an option -(see L<Tk::ConfigSpecs> and L<Tk::Derived> for details). - -=head2 Construct - -Make the new mega-widget known to B<Tk>. - -Usage: - -S< >B<Construct> I<baseclass> B<'Name'>; - -B<Construct> declares the new widget class so that your mega-widget -works like normal Perl/Tk widgets. - -Examples: - -S< >B<Construct Tk::Widget> I<'Whatever'>; -S< >B<Construct Tk::Menu> I<'MyItem'>; - -First example lets one use I<$widget>-E<gt>B<Whatever> to create -new B<Whatever> widget. - -The second example restricts the usage of the B<MyItem> constructor -method to widgets that are derived from B<Menu>: -I<$isamenu>-E<gt>I<MyItem>. - -=head2 CreateArgs - -Process options before any widget is created: - -S< >B<sub CreateArgs> { I<my ($package, $parent, $args) = @_; ...; return @newargs;> } - -I<$package> is the package of the mega-widget (e.g., B<Tk::MyText>, -I<$parent> the parent of the widget to be created and $args the hash -reference to the options specified in the widget constructor call. - -Don't forget to call I<$package>-E<gt>B<SUPER::CreateArgs>(I<$parent>, I<$args>) in -B<CreateArgs>. - -=head2 Delegates - -Redirect a method of the mega-widget to a subwidget of -the composite widget - -Usage: - - $cw->Delegates( - 'method1' => $subwidget1, - 'method2' => 'advertived_name', - ..., - 'Construct' => $subwidget2, - 'DEFAULT' => $subwidget3, - ); - -The B<'Construct'> delegation has a special meaning. After -'Construct' is delegated all Widget constructors are redirected. -E.g. after - -S< >I<$self>-E<gt>B<Delegates>(B<'Construct'>=E<gt>I<$subframe>); - -a I<$self>-E<gt>B<Button> does really a I<$subframe>-E<gt>B<Button> -so the created button is a child of I<$subframe> and not I<$self>. - -B<Comment:> Delegates works only with methods that I<$cw> does -not have itself. - -=head2 InitObject - -I<Note: this method should not, in general, be used, as it has been -superceeded by B<Populate> and specifying B<Tk::Derived> as one of the base -classes.> - -Defines construction and interface of derived widgets. - -Usage: - - sub InitObject { - my ($derived, $args) = @_; - ... - } - -where I<$derived> is the widget reference of the already created -baseclass widget and I<$args> is the reference to a hash of -I<-option-value> pairs. - -B<InitObject> is almost identical to L<Populate|"Populate"> method. -B<Populate> does some more 'magic' things useful for mega-widgets -with several widgets. - -Don't forget to call I<$derived>-E<gt>B<SUPER::InitObject>(I<$args>) in -B<InitObject>. - -=head2 OnDestroy - -Define a callback invoked when the mega-widget is destroyed. - -Usage: - -S< >I<$widget>-E<gt>B<OnDestroy>(I<callback>); - -B<OnDestroy> installs a L<callback|Tk::callbacks> that's called -when a widget is going to to be destroyed. Useful -for special cleanup actions. It differs from a normal B<destroy> -in that all the widget's data structures are still intact. - -B<Comment:> This method could be used with any widgets not just -for mega-widgets. It's listed here because of it's usefulness. - -=head2 Populate - -Defines construction and interface of the composite -widget. - -Usage: - - sub Populate { - my ($self, $args) = @_; - ... - } - -where I<$self> is the widget reference of the already created baseclass -widget and I<$args> is the -reference to a hash of I<-option-value> pairs. - -Most the other support function are normally used inside the B<Populate> -subroutine. - -Don't forget to call I<$cw>-E<gt>B<SUPER::Populate>(I<$args>) in -B<Populate>. - -=head2 privateData - -Set/get a private hash of a widget to storage -composite internal data - -Usage: - -S< >I<$hashref> = I<$self>-E<gt>B<privateData>(); - -S< >I<$another> = I<$self>-E<gt>B<privateData>(I<unique_key>|I<package>); - -=head2 Subwidget - -Get the widget reference of an advertised subwidget. - -S< >I<@subwidget> = I<$cw>-E<gt>B<Subwidget>(); - -S< >I<$subwidget> = I<$cw>-E<gt>B<Subwidget>(I<name>); - -S< >I<@subwidget> = I<$cw>-E<gt>B<Subwidget>(I<name> ?,...?); - -Returns the widget reference(s) of the subwidget known under the given -name(s). Without arguments, return all known subwidgets of I<$cw>. See -L<Advertise|"Advertise"> method how to define I<name> for a subwidget. - -B<Comment:> Mega-Widget Users: Use B<Subwidget> to get I<only> -documented subwidgets. - -=head1 PITFALLS - -=over 4 - -=item * Resource DB class name - -Some of the standard options use a resource date base class -that is not equal to the resource database name. E.g., - - Switch: Name: Class: - - -padx padX Pad - -activerelief activeRelief Relief - -activebackground activeBackground Foreground - -status undef undef - -One should do the same when one defines one of these -options via B<ConfigSpecs>. - -=item * Method delegation - -Redirecting methods to a subwidget with B<Delegate> -can only work if the base widget itself does have a -method with this name. Therefore one can't ``I<delegate>'' -any of the methods listed in L<Tk::Widget|Tk::Widget>. -A common problematic method is B<bind>. In this case -one as to explicitely redirect the method. - - sub bind { - my $self = shift; - my $to = $self->privateData->{'my_bind_target'}; - $to->bind(@_); - } - -=item * privateData - -Graham Barr wrote: ... It is probably -more private than most people think. Not all calls to privateData will -return that same HASH reference. The HASH reference that is returned -depends on the package it was called from, a different HASH is returned -for each package. This allows a widget to hold private data, but then -if it is sub-classed the sub-class will get a different HASH and so not -cause duplicate name clashes. - -But privateData does take an optional argument if you want to -force which HASH is returned. - -=item * Scrolled and Composite - -B<Scrolled>(I<Kind>,...) constructor can not be used with B<Composite>. -One has to use $cw->B<Composite>(B<Scrl>I<Kind> =E<gt> B<'name'>, ...); - -=back - -=head1 MISSING - -Of course Perl/Tk does not define support function for -all necessities. Here's a short list of things you have to -handle yourself: - -=over 4 - -=item * - -No support to define construction-time only options. - -=item * - -No support to remove an option that is known to the -base widget. - -=item * - -It's hard to define B<undef> as fallback for an widget -option that is not already B<undef>. - -=item * - -Frame in Perl/Tk carries magic and overhead not needed -for composite widget class definition. - -=item * - -No support methods for bindings that are shared between all -widgets of a composite widget (makes sense at all?) - -=back - -=head1 KEYWORDS - -mega, composite, derived, widget - -=head1 SEE ALSO - -L<Tk::composite|Tk::composite> -L<Tk::ConfigSpecs|Tk::ConfigSpecs> -L<Tk::option|Tk::option> -L<Tk::callbacks|Tk::callbacks> -L<Tk::bind|Tk::bind> - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/messageBox.pod b/Master/tlpkg/tlperl/lib/Tk/messageBox.pod deleted file mode 100644 index 3cae94beb0d..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/messageBox.pod +++ /dev/null @@ -1,67 +0,0 @@ -=head1 NAME - -messageBox - pop up a message window and wait for user response. - -=for category Popups and Dialogs - -=head1 SYNOPSIS - -S< >I<$response> = I<$widget>-E<gt>B<messageBox>(I<-option> =E<gt> I<value>, ... ); - -=head1 DESCRIPTION - -This method uses L<Tk::Dialog|Tk::Dialog> to quickly create several -common dialog boxes. A dialog widget consists of a message, an icon -and a set of buttons (see the I<-type> option). After the message -window is popped up, B<messageBox> waits for the user to select one of -the buttons and return the button text (note that it's best to check the -returned value in a case insensitive manner). NOTE: unlike -B<Tk::Dialog> which creates its widget once and can be used many -times, the B<messageBox> window is created every time it's used. - -The following option/value pairs are supported: - -=over 4 - -=item B<-default> - -The case-sensitive symbolic name of the default button -for this message window ('Ok', 'Cancel' and so -on). See B<-type> for a list of the symbolic names. -If the message box has just one button it will -automatically be made the default, otherwise if -this option is not specified, there won't be any -default button. - -=item B<-icon> - -Specifies an icon to display. On X11 any of the builtin Tk bitmaps can -specified. On Windows only B<error>, B<info>, B<question> or -B<warning> are supported. - -=item B<-message> - -Specifies the message to display. - -=item B<-title> - -Specifies a string to display as the title. - -=item B<-type> - -Specifies a predefined set of buttons to be displayed. The following -values are possible: 'AbortRetryIgnore', 'Ok', 'OkCancel', -'RetryCancel', 'YesNo' or 'YesNoCancel'. - -=back - -=head1 EXAMPLE - -I<$response> = I<$mw>-E<gt>B<messageBox>(-icon =E<gt> 'question', -message =E<gt> 'Hello World!', -title =E<gt> 'My title', -type =E<gt> 'AbortRetryIgnore', -default =E<gt> 'Retry'); - -=head1 AUTHOR - -Stephen.O.Lidie@Lehigh.EDU. 98/05/25 - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/option.pod b/Master/tlpkg/tlperl/lib/Tk/option.pod deleted file mode 100644 index 1214357d181..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/option.pod +++ /dev/null @@ -1,217 +0,0 @@ -# Copyright (c) 1990 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -option - Using the option database in Perl/Tk - -=for category Creating and Configuring Widgets - -=head1 SYNOPSIS - -S< >I<$widget>-E<gt>B<widgetClass>(B<Name>=E<gt>I<name>, B<-class>=E<gt>I<class>); - -S< >I<$widget>-E<gt>B<PathName>; - -S< >I<$widget>-E<gt>B<optionAdd>(I<pattern>=E<gt>I<value > ?,I<priority>?); - -S< >I<$widget>-E<gt>B<optionClear>; - -S< >I<$widget>-E<gt>B<optionGet>(I<name, class>); - -S< >I<$widget>-E<gt>B<optionReadfile>(I<fileName> ?,I<priority>?); - -=head1 DESCRIPTION - -The option database (also known as the I<resource database> or the -I<application defaults database>) is a set of rules for applying -default options to widgets. Users and system administrators can -set up these rules to customize the appearance of applications -without changing any application code; for example, a user might -set up personal foreground and background colors, or a site -might use fonts associated with visual or language preferences. -Different window managers (and implementations of them) have implemented -the database differently, but most Xt-based window managers use the -I<.Xdefaults> file or the I<xrdb> utility to manage user preferences; -some use both, and/or implement a more complex set of site, user and -application databases. Check your site documentation for these topics -or your window manager's B<RESOURCE_MANAGER> property. - -=head2 Being a good citizen - -For most applications, the option database "just works." The B<option...> -methods are for applications that need to do something unusual, such as -add new rules or test an option's default. Even in such cases, the -application should provide for user preferences. -Do not hardcode widget options without a B<very> good reason. -All users have their own tastes and they are all different. -They choose a special font in a special size and have often spend a -lot of time working out a color scheme that they will love until death. -When you respect their choices they will enjoy working with your -applications much more. Don't destroy the common look and feel of a -personal desktop. - -=head2 Option rules and widget identification - -All widgets in an application are identified hierarchically by I<pathname>, -starting from the B<MainWindow> and passing through each widget used to create -the endpoint. The path elements are I<widget names>, much like the elements -of a file path from the root directory to a file. The rules in the option -database are patterns that are matched against a widget's I<pathname> to -determine which defaults apply. -When a widget is created, the B<Name> option can be -used to assign the widget's name and thus create a distinctive path -for widgets in an application. If the B<Name> option isn't given, -Perl/Tk assigns a default name based on the type of widget; a -B<MainWindow>'s default name is the B<appname>. These defaults are fine -for most widgets, so don't feel you need to find a meaningful name for -every widget you create. -A widget must have a distinctive name to allow users to tailor its -options independently of other widgets in an application. For instance, -to create a B<Text> widget that will -have special options assigned to it, give it a name such as: - - $text = $mw->Text(Name => 'importantText'); - -You can then tailor the widget's attributes with a rule in the option -database such as: - - *importantText*foreground: red - -The I<class> attribute identifies groups of widgets, usually within an -application but also to group similar widgets among different applications. -One typically assigns a class to a B<TopLevel> or B<Frame> so that the -class will apply to all of that widget's children. To extend the example, -we could be more specific about the importantText widget -by giving its frame a class: - - $frame = $mw->Frame(-class => 'Urgent'); - $text = $frame->Text(Name => 'importantText'); - -Then the resource pattern can be specified as so: - - *Urgent*importantText*foreground: red - -Similarly, the pattern C<*Urgent*background: cyan> would apply to all -widgets in the frame. - -=head1 METHODS - -=over 4 - -=item I<$widget>-E<gt>B<widgetClass>(B<Name>=E<gt>I<name>, B<-class>=E<gt>I<class>); - -Identify a new widget with I<name> and/or I<class>. -B<Name> specifies the path element for the widget; names generally begin with a -lowercase letter. B<-class> specifies the class for the widget and its -children; classes generally begin with an uppercase letter. -If not specified, Perl/Tk will assign a unique default name to each widget. -Only B<MainWindow> widgets have a default class, made by uppercasing the -first letter of the application name. - -=item I<$widget>-E<gt>B<PathName>; - -The B<PathName> method returns the widget's I<pathname>, which uniquely -identifies the widget within the application. - -=item I<$widget>-E<gt>B<optionAdd>(I<pattern>=E<gt>I<value >?, I<priority>?); - -The B<optionAdd> method adds a new option to the database. -I<Pattern> contains the option being specified, and consists of -names and/or classes separated by asterisks or dots, in the usual -X format. I<Value> contains a text string to associate with -I<pattern>; this is the value that will be returned in calls to -the B<optionGet> method. If I<priority> is specified, it indicates -the priority level for this option (see below for legal values); -it defaults to B<interactive>. This method always returns an empty -string. - -=item I<$widget>-E<gt>B<optionClear>; - -The B<optionClear> method clears the option database. Default -options (from the B<RESOURCE_MANAGER> property or the B<.Xdefaults> -file) will be reloaded automatically the next time an option is -added to the database or removed from it. This method always returns -an empty string. - -=item I<$widget>-E<gt>B<optionGet>(I<name,class>); - -The B<optionGet> method returns the value of the option specified for -I<$widget> under I<name> and I<class>. To look up the option, -B<optionGet> matches the patterns in the resource database against -I<$widget>'s I<pathname> along with the class of I<$widget> -(or its parent if I<$widget> has no class specified). The widget's -class and name are options set when the widget is created (not -related to class in the sense of L<bless>); the B<MainWindow>'s name -is the B<appname> and its class is (by default) derived from the name -of the script. - -If several entries in the option database match I<$widget>'s I<pathname>, -I<name>, and I<class>, then the method returns whichever was created with -highest I<priority> level. If there are several matching -entries at the same priority level, then it returns whichever entry -was I<most recently entered> into the option database. If there are -no matching entries, then the empty string is returned. - -=item I<$widget>-E<gt>B<optionReadfile>(I<fileName>?,I<priority>?); - -The B<optionReadfile> method reads I<fileName>, which should have the -standard format for an X resource database such as B<.Xdefaults>, and -adds all the options specified in that file to the option database. -If I<priority> is specified, it indicates the priority level at which -to enter the options; I<priority> defaults to B<interactive>. - -The I<priority> arguments to the B<option> methods are -normally specified symbolically using one of the following values: - -=over 8 - -=item B<widgetDefault> - -Level 20. Used for default values hard-coded into widgets. - -=item B<startupFile> - -Level 40. Used for options specified in application-specific -startup files. - -=item B<userDefault> - -Level 60. Used for options specified in user-specific defaults -files, such as B<.Xdefaults>, resource databases loaded into -the X server, or user-specific startup files. - -=item B<interactive> - -Level 80. Used for options specified interactively after the application -starts running. If I<priority> isn't specified, it defaults to -this level. - -=back - -Any of the above keywords may be abbreviated. In addition, priorities -may be specified numerically using integers between 0 and 100, -inclusive. The numeric form is probably a bad idea except for new priority -levels other than the ones given above. - -=back - -=head1 BUGS - -The priority scheme used by core Tk is not the same as used by normal Xlib -routines. In particular is assumes that the order of the entries is defined, -but user commands like B<xrdb -merge> can change the order. - -=head1 SEE ALSO - -L<Tk::Xrm|Tk::Xrm> - -=head1 KEYWORDS - -database, option, priority, retrieve - -=cut diff --git a/Master/tlpkg/tlperl/lib/Tk/options.pod b/Master/tlpkg/tlperl/lib/Tk/options.pod deleted file mode 100644 index 49d81ddd2b4..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/options.pod +++ /dev/null @@ -1,787 +0,0 @@ -# Copyright (c) 1990-1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::options - Standard options supported by widgets and their manipulation - -=for category Creating and Configuring Widgets - -=head1 SYNOPSIS - -S< >I<$value> = I<$widget>-E<gt>B<cget>('I<-option>'); - -S< >I<$widget>-E<gt>B<configure>(I<-option>=E<gt>I<value> ?,I<-option>=E<gt>I<value> ...?); - -S< >I<@list> = I<$widget>-E<gt>B<configure>('I<-option>'); - -S< >I<@lol> = I<$widget>-E<gt>B<configure>; - -=head1 DESCRIPTION - -All widgets, and images have a standard mechanism for setting and querying -attibutes or options. The mechanism is based on two methods B<configure> -and B<cget>. The behaviour of these methods is as follows: - -=over 4 - -=item I<$widget>-E<gt>B<configure>(I<-option>=E<gt>I<value> ?,I<-option>=E<gt>I<value> ...?); - -Sets the values of I<-option> to I<value> for each I<-option>=E<gt>I<value> -pair. The internal B<new> method does an implicit B<configure> in this -form with options passed in at widget create time. - -=item I<$widget>-E<gt>B<configure>('I<-option>') - -In array context returns a list of five or two elements. If I<-option> -is an alias for another options it return a list consisting of the -alias option and the name for the option is is an alias for, e.g., -C<('-bg', 'background')>. If I<-option> is not an alias the returned -list has the following five elements: - -=over 8 - -=item I<Option Name> - -The value of I<-option>, e.g., B<-background>. - -=item I<Name> - -The option's name in the option database, e.g., C<background>. - -=item I<Class> - -The option's class value in the option database, e.g., C<Background>. - -=item I<Default> - -The default value for the option if not specified or in the option database, -e.g., C<grey>. - -=item I<Value> - -The current value (as returned by B<cget>), e.g., C<white>. - -=back - -=item I<$widget>-E<gt>B<configure> - -Returns a list of lists for all the options supported by I<$widget>. -Each sub-list is in the form returned by B<configure>('I<-option>'). -(This mechanism is used by the B<Tk::Derived> class to determine -the options available from base class.) - -=item I<$widget>-E<gt>B<cget>('I<-option>') - -Returns the current value of I<-option> for I<$widget>. - -B<cget>('I<-option>') is clumsy with the need for B<''> due to perl's -parsing rules. Something more subtle using L<tie|perlfunc/tie> might look better. - -=back - -The following paragraphs describe the common configuration options supported by -widgets in the Tk toolkit. Every widget does not necessarily support every option -(see the the documentation entries for individual widgets for a list of the -standard options supported by that widget), but if a widget does support an option -with one of the names listed below, then the option has exactly the effect -described below. - -In the descriptions below, ``Name'' refers to the option's name in the option -database. ``Class'' refers to the option's class value -in the option database. ``Switch'' refers to the switch used in widget-creation -and B<configure> widget methods to set this value. For example, if an option's -configure option is B<-foreground> and there exists a widget I<$widget>, then the -call: - -S< >I<$widget>-E<gt>B<configure>(B<-foreground>=E<gt>B<'black'>) - -may be used to specify the value B<black> for the option in the widget I<$widget>. -Configure options may be abbreviated, as long as the abbreviation is unambiguous -(abbreviation is deprecated in perl/Tk). - -=head2 Creation options: Widget Name and Class - -The B<Name> and B<-class> options can only be specified when a widget is -created, and cannot be changed with B<configure>. These options determine -the widget's identity and how Tk applies resource values from the -option database (see L<Tk::option>) and so they -cannot be assigned by the options database. - -=over 4 - -=item Name: I<name> - -=item Switch: B<Name> - -Specifies the path element for the widget. Names generally begin with a -lowercase letter. - -Each widget has a unique I<pathname> that follows the hierarchy from the -B<MainWindow> to the widget itself. Since the widget's B<PathName> is -used to assign options from the options database, it is important to -specify a distinctive B<Name> for any widget that will have non-default -options. See L<Tk::option> for details. - -=item Name: I<class> - -=item Switch: B<-class> - -Specifies a class for the window. Classes generally begin with an -uppercase letter. - -This class will be used when querying the option database for -the window's other options (see Tk::options), and it will also be used -later for other purposes such as bindings. One typically assigns a class -to a B<TopLevel> or B<Frame> so that the class will apply to all of -that widget's children. - -=back - -=head2 Reconfigurable options - -These options can be set at widget creation or changed later via B<configure>. - -=over 4 - -=item Name: B<activeBackground> - -=item Class: B<Foreground> - -=item Switch: B<-activebackground> - -Specifies background color to use when drawing active elements. -An element (a widget or portion of a widget) is active if the -mouse cursor is positioned over the element and pressing a mouse button -will cause some action to occur. -If strict Motif compliance has been requested by setting the -B<$Tk::strictMotif> variable, this option will normally be -ignored; the normal background color will be used instead. -For some elements on Windows and Macintosh systems, the active color -will only be used while mouse button 1 is pressed over the element. - -=item Name: B<activeBorderWidth> - -=item Class: B<BorderWidth> - -=item Switch: B<-activeborderwidth> - -Specifies a non-negative value indicating -the width of the 3-D border drawn around active elements. -See above for definition of active elements. -The value may have any of the forms acceptable to B<Tk_GetPixels>. -This option is typically only available in widgets displaying more -than one element at a time (e.g. menus but not buttons). - -=item Name: B<activeForeground> - -=item Class: B<Background> - -=item Switch: B<-activeforeground> - -Specifies foreground color to use when drawing active elements. -See above for definition of active elements. - -=item Name: B<activetile> - -=item Class: B<Tile> - -=item Switch: B<-activetile> - -Specifies image used to display inside active elements of the widget. -See above for definition of active elements. - -=item Name: B<anchor> - -=item Class: B<Anchor> - -=item Switch: B<-anchor> - -Specifies how the information in a widget (e.g. text or a bitmap) -is to be displayed in the widget. -Must be one of the values B<n>, B<ne>, B<e>, B<se>, -B<s>, B<sw>, B<w>, B<nw>, or B<center>. -For example, B<nw> means display the information such that its -top-left corner is at the top-left corner of the widget. - -=item Name: B<background> - -=item Class: B<Background> - -=item Switch: B<-background> - -=item Alias: B<-bg> - -Specifies the normal background color to use when displaying the -widget. - -=item Name: B<bitmap> - -=item Class: B<Bitmap> - -=item Switch: B<-bitmap> - -Specifies a bitmap to display in the widget, in any of the forms -acceptable to B<Tk_GetBitmap>. -The exact way in which the bitmap is displayed may be affected by -other options such as B<-anchor> or B<-justify>. -Typically, if this option is specified then it overrides other -options that specify a textual value to display in the widget; -the B<-bitmap> option may be reset to an empty string to re-enable -a text display. -In widgets that support both B<-bitmap> and B<-image> options, -B<-image> will usually override B<-bitmap>. - -=item Name: B<borderWidth> - -=item Class: B<BorderWidth> - -=item Switch: B<-borderwidth> - -=item Alias: B<-bd> - -Specifies a non-negative value indicating the width -of the 3-D border to draw around the outside of the widget (if such a -border is being drawn; the B<relief> option typically determines -this). The value may also be used when drawing 3-D effects in the -interior of the widget. -The value may have any of the forms acceptable to B<Tk_GetPixels>. - -=item Name: B<compound> - -=item Class: B<Compound> - -=item Switch: B<-compound> - -Specifies if the widget should display text and bitmaps/images at the -same time, and if so, where the bitmap/image should be placed relative -to the text. Must be one of the values B<none>, B<bottom>, B<top>, -B<left>, B<right>, or B<center>. For example, the (default) value -B<none> specifies that the bitmap or image should (if defined) be -displayed instead of the text, the value B<left> specifies that the -bitmap or image should be displayed to the left of the text, and the -value B<center> specifies that the bitmap or image should be displayed on -top of the text. - -=item Name: B<cursor> - -=item Class: B<Cursor> - -=item Switch: B<-cursor> - -Specifies the mouse cursor to be used for the widget. -The value may have any of the forms acceptable to B<Tk_GetCursor>. - -=item Name: B<dash> - -=item Class: B<Dash> - -=item Switch: B<-dash> - -The value may have any of the forms accepted by B<Tk_GetDash>, -such as B<4>, B<[6,4]>, B<.>, B<->, B<-.>, or B<-..>. - -=item Name: B<dashoffset> - -=item Class: B<Dashoffset> - -=item Switch: B<-dashoffset> - -Specifies the offset in the dash list where the drawing starts. - -=item Name: B<disabledForeground> - -=item Class: B<DisabledForeground> - -=item Switch: B<-disabledforeground> - -Specifies foreground color to use when drawing a disabled element. -If the option is specified as an empty string (which is typically the -case on monochrome displays), disabled elements are drawn with the -normal foreground color but they are dimmed by drawing them -with a stippled fill pattern. - -=item Name: B<disabledtile> - -=item Class: B<Tile> - -=item Switch: B<-disabledtile> - -Specifies image to use when drawing a disabled element. - -=item Name: B<exportSelection> - -=item Class: B<ExportSelection> - -=item Switch: B<-exportselection> - -Specifies whether or not a selection in the widget should also be -the X selection. -The value may have any of the forms accepted by B<Tcl_GetBoolean>, -such as B<true>, B<false>, B<0>, B<1>, B<yes>, or B<no>. -If the selection is exported, then selecting in the widget deselects -the current X selection, selecting outside the widget deselects any -widget selection, and the widget will respond to selection retrieval -requests when it has a selection. The default is usually for widgets -to export selections. - -=item Name: B<font> - -=item Class: B<Font> - -=item Switch: B<-font> - -Specifies the font to use when drawing text inside the widget. - -=item Name: B<foreground> - -=item Class: B<Foreground> - -=item Switch: B<-foreground> - -=item Alias: B<-fg> - -Specifies the normal foreground color to use when displaying the widget. - -=item Name: B<highlightBackground> - -=item Class: B<HighlightBackground> - -=item Switch: B<-highlightbackground> - -Specifies the color to display in the traversal highlight region when -the widget does not have the input focus. - -=item Name: B<highlightColor> - -=item Class: B<HighlightColor> - -=item Switch: B<-highlightcolor> - -Specifies the color to use for the traversal highlight rectangle that is -drawn around the widget when it has the input focus. - -=item Name: B<highlightThickness> - -=item Class: B<HighlightThickness> - -=item Switch: B<-highlightthickness> - -Specifies a non-negative value indicating the width of the highlight -rectangle to draw around the outside of the widget when it has the -input focus. -The value may have any of the forms acceptable to B<Tk_GetPixels>. -If the value is zero, no focus highlight is drawn around the widget. - -=item Name: B<image> - -=item Class: B<Image> - -=item Switch: B<-image> - -Specifies an image to display in the widget, which must have been -created with an image create. (See L<Tk::Image> for details of image creation.) -Typically, if the B<-image> option is specified then it overrides other -options that specify a bitmap or textual value to display in the widget; -the B<-image> option may be reset to an empty string to re-enable -a bitmap or text display. - -=item Name: B<insertBackground> - -=item Class: B<Foreground> - -=item Switch: B<-insertbackground> - -Specifies the color to use as background in the area covered by the -insertion cursor. This color will normally override either the normal -background for the widget (or the selection background if the insertion -cursor happens to fall in the selection). - -=item Name: B<insertBorderWidth> - -=item Class: B<BorderWidth> - -=item Switch: B<-insertborderwidth> - -Specifies a non-negative value indicating the width -of the 3-D border to draw around the insertion cursor. -The value may have any of the forms acceptable to B<Tk_GetPixels>. - -=item Name: B<insertOffTime> - -=item Class: B<OffTime> - -=item Switch: B<-insertofftime> - -Specifies a non-negative integer value indicating the number of -milliseconds the insertion cursor should remain ``off'' in each blink cycle. -If this option is zero then the cursor doesn't blink: it is on -all the time. - -=item Name: B<insertOnTime> - -=item Class: B<OnTime> - -=item Switch: B<-insertontime> - -Specifies a non-negative integer value indicating the number of -milliseconds the insertion cursor should remain ``on'' in each blink cycle. - -=item Name: B<insertWidth> - -=item Class: B<InsertWidth> - -=item Switch: B<-insertwidth> - -Specifies a value indicating the total width of the insertion cursor. -The value may have any of the forms acceptable to B<Tk_GetPixels>. -If a border has been specified for the insertion -cursor (using the B<insertBorderWidth> option), the border -will be drawn inside the width specified by the B<insertWidth> -option. - -=item Name: B<jump> - -=item Class: B<Jump> - -=item Switch: B<-jump> - -For widgets with a slider that can be dragged to adjust a value, -such as scrollbars, this option determines when -notifications are made about changes in the value. -The option's value must be a boolean of the form accepted by -B<Tcl_GetBoolean>. -If the value is false, updates are made continuously as the -slider is dragged. -If the value is true, updates are delayed until the mouse button -is released to end the drag; at that point a single notification -is made (the value ``jumps'' rather than changing smoothly). - -=item Name: B<justify> - -=item Class: B<Justify> - -=item Switch: B<-justify> - -When there are multiple lines of text displayed in a widget, this -option determines how the lines line up with each other. -Must be one of B<left>, B<center>, or B<right>. -B<Left> means that the lines' left edges all line up, B<center> -means that the lines' centers are aligned, and B<right> means -that the lines' right edges line up. - -=item Name: B<offset> - -=item Class: B<Offset> - -=item Switch: B<-offset> - -Specifies the offset of tiles (see also B<-tile> option). It can -have two different formats B<-offset x,y> or B<-offset side>, -where side can be B<n>, B<ne>, B<e>, B<se>, B<s>, -B<sw>, B<w>, B<nw>, or B<center>. In the first case -the origin is the origin of the toplevel of the current window. -For the canvas itself and canvas objects the origin is the canvas -origin, but putting B<#> in front of the coordinate pair -indicates using the toplevel origin in stead. For canvas objects, -the B<-offset> option is used for stippling as well. -For the line and polygon canvas items you can also specify -an index as argument, which connects the stipple or tile -origin to one of the coordinate points of the line/polygon. - -=item Name: B<orient> - -=item Class: B<Orient> - -=item Switch: B<-orient> - -For widgets that can lay themselves out with either a horizontal -or vertical orientation, such as scrollbars, this option specifies -which orientation should be used. Must be either B<horizontal> -or B<vertical> or an abbreviation of one of these. - -=item Name: B<padX> - -=item Class: B<Pad> - -=item Switch: B<-padx> - -Specifies a non-negative value indicating how much extra space -to request for the widget in the X-direction. -The value may have any of the forms acceptable to B<Tk_GetPixels>. -When computing how large a window it needs, the widget will -add this amount to the width it would normally need (as determined -by the width of the things displayed in the widget); if the geometry -manager can satisfy this request, the widget will end up with extra -internal space to the left and/or right of what it displays inside. -Most widgets only use this option for padding text: if they are -displaying a bitmap or image, then they usually ignore padding -options. - -=item Name: B<padY> - -=item Class: B<Pad> - -=item Switch: B<-pady> - -Specifies a non-negative value indicating how much extra space -to request for the widget in the Y-direction. -The value may have any of the forms acceptable to B<Tk_GetPixels>. -When computing how large a window it needs, the widget will add -this amount to the height it would normally need (as determined by -the height of the things displayed in the widget); if the geometry -manager can satisfy this request, the widget will end up with extra -internal space above and/or below what it displays inside. -Most widgets only use this option for padding text: if they are -displaying a bitmap or image, then they usually ignore padding -options. - -=item Name: B<relief> - -=item Class: B<Relief> - -=item Switch: B<-relief> - -Specifies the 3-D effect desired for the widget. Acceptable -values are B<raised>, B<sunken>, B<flat>, B<ridge>, -B<solid>, and B<groove>. -The value -indicates how the interior of the widget should appear relative -to its exterior; for example, B<raised> means the interior of -the widget should appear to protrude from the screen, relative to -the exterior of the widget. - -=item Name: B<repeatDelay> - -=item Class: B<RepeatDelay> - -=item Switch: B<-repeatdelay> - -Specifies the number of milliseconds a button or key must be held -down before it begins to auto-repeat. Used, for example, on the -up- and down-arrows in scrollbars. - -=item Name: B<repeatInterval> - -=item Class: B<RepeatInterval> - -=item Switch: B<-repeatinterval> - -Used in conjunction with B<repeatDelay>: once auto-repeat -begins, this option determines the number of milliseconds between -auto-repeats. - -=item Name: B<selectBackground> - -=item Class: B<Foreground> - -=item Switch: B<-selectbackground> - -Specifies the background color to use when displaying selected -items. - -=item Name: B<selectBorderWidth> - -=item Class: B<BorderWidth> - -=item Switch: B<-selectborderwidth> - -Specifies a non-negative value indicating the width -of the 3-D border to draw around selected items. -The value may have any of the forms acceptable to B<Tk_GetPixels>. - -=item Name: B<selectForeground> - -=item Class: B<Background> - -=item Switch: B<-selectforeground> - -Specifies the foreground color to use when displaying selected -items. - -=item Name: B<setGrid> - -=item Class: B<SetGrid> - -=item Switch: B<-setgrid> - -Specifies a boolean value that determines whether this widget controls the -resizing grid for its top-level window. -This option is typically used in text widgets, where the information -in the widget has a natural size (the size of a character) and it makes -sense for the window's dimensions to be integral numbers of these units. -These natural window sizes form a grid. -If the B<setGrid> option is set to true then the widget will -communicate with the window manager so that when the user interactively -resizes the top-level window that contains the widget, the dimensions of -the window will be displayed to the user in grid units and the window -size will be constrained to integral numbers of grid units. -See L<Tk::Wm/"GRIDDED GEOMETRY MANAGEMENT"> -for more details. - -=item Name: B<takeFocus> - -=item Class: B<TakeFocus> - -=item Switch: B<-takefocus> - -Determines whether the window accepts the focus during keyboard -traversal (e.g., Tab and Shift-Tab). -Before setting the focus to a window, the traversal scripts -consult the value of the B<takeFocus> option. -A value of B<0> means that the window should be skipped entirely -during keyboard traversal. -B<1> means that the window should receive the input -focus as long as it is viewable (it and all of its ancestors are mapped). -An empty value for the option means that the traversal scripts make -the decision about whether or not to focus on the window: the current -algorithm is to skip the window if it is -disabled, if it has no key bindings, or if it is not viewable. -If the value has any other form, then the traversal scripts take -the value, append the name of the window to it (with a separator space), -and evaluate the resulting string as a Callback. -The script must return B<0>, B<1>, or an empty string: a -B<0> or B<1> value specifies whether the window will receive -the input focus, and an empty string results in the default decision -described above. -Note: this interpretation of the option is defined entirely by -the Callbacks that implement traversal: the widget implementations -ignore the option entirely, so you can change its meaning if you -redefine the keyboard traversal scripts. - -=item Name: B<text> - -=item Class: B<Text> - -=item Switch: B<-text> - -Specifies a string to be displayed inside the widget. The way in which -the string is displayed depends on the particular widget and may be -determined by other options, such as B<anchor> or B<justify>. - -=item Name: B<textVariable> - -=item Class: B<Variable> - -=item Switch: B<-textvariable> - -Specifies the name of a variable. The value of the variable is a text -string to be displayed inside the widget; if the variable value changes -then the widget will automatically update itself to reflect the new value. -The way in which the string is displayed in the widget depends on the -particular widget and may be determined by other options, such as -B<anchor> or B<justify>. - -=item Name: B<tile> - -=item Class: B<Tile> - -=item Switch: B<-tile> - -Specifies image used to display the widget. If image is the empty -string, then the normal background color is displayed. - -=item Name: B<troughColor> - -=item Class: B<Background> - -=item Switch: B<-troughcolor> - -Specifies the color to use for the rectangular trough areas -in widgets such as scrollbars and scales. - -=item Name: B<troughTile> - -=item Class: B<Tile> - -=item Switch: B<-troughtile> - -Specifies image used to display in the rectangular trough areas -in widgets such as scrollbars and scales. - -=item Name: B<underline> - -=item Class: B<Underline> - -=item Switch: B<-underline> - -Specifies the integer index of a character to underline in the widget. -This option is used by the default bindings to implement keyboard -traversal for menu buttons and menu entries. -0 corresponds to the first character of the text displayed in the -widget, 1 to the next character, and so on. - -=item Name: B<wrapLength> - -=item Class: B<WrapLength> - -=item Switch: B<-wraplength> - -For widgets that can perform word-wrapping, this option specifies -the maximum line length. -Lines that would exceed this length are wrapped onto the next line, -so that no line is longer than the specified length. -The value may be specified in any of the standard forms for -screen distances. -If this value is less than or equal to 0 then no wrapping is done: lines -will break only at newline characters in the text. - -=item Name: B<xScrollCommand> - -=item Class: B<ScrollCommand> - -=item Switch: B<-xscrollcommand> - -Specifies a callback used to communicate with horizontal -scrollbars. -When the view in the widget's window changes (or -whenever anything else occurs that could change the display in a -scrollbar, such as a change in the total size of the widget's -contents), the widget will -make a callback passing two numeric arguments in addition to -any specified in the callback. -Each of the numbers is a fraction between 0 and 1, which indicates -a position in the document. 0 indicates the beginning of the document, -1 indicates the end, .333 indicates a position one third the way through -the document, and so on. -The first fraction indicates the first information in the document -that is visible in the window, and the second fraction indicates -the information just after the last portion that is visible. -Typically the -B<xScrollCommand> option consists of the scrollbar widget object -and the method ``set'' i.e. [B<set> =E<gt> I<$sb>]: -this will cause the scrollbar to be updated whenever the view in the window changes. -If this option is not specified, then no command will be executed. - -=item Name: B<yScrollCommand> - -=item Class: B<ScrollCommand> - -=item Switch: B<-yscrollcommand> - -Specifies a calback used to communicate with vertical -scrollbars. This option is treated in the same way as the -B<xScrollCommand> option, except that it is used for vertical -scrollbars and is provided by widgets that support vertical scrolling. -See the description of B<xScrollCommand> for details -on how this option is used. - -=back - -=head1 SEE ALSO - -L<Tk::option> -L<Tk::callbacks> -L<Tk::ConfigSpecs> -L<Tk_GetPixels|Tk::pTk::GetPixels> - -=head1 KEYWORDS - -class, name, standard option, switch - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/overview.pod b/Master/tlpkg/tlperl/lib/Tk/overview.pod deleted file mode 100644 index 0c9e183b68a..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/overview.pod +++ /dev/null @@ -1,138 +0,0 @@ - -=head1 NAME - -B<Tk> - An overview of an Object Oriented Tk8 extension for perl5 - -=for category Introduction - -=head1 SYNOPSIS - -C<< use Tk; >> - -C<< $main = MainWindow-E<gt>new(); >> - -C<< $widget = $main-E<gt>I<Widget>(...); >> - -C<< $widget-E<gt>pack(...); >> - -... - -C<< MainLoop; >> - -=head1 DESCRIPTION - -In writing the perl Tk extension, the goals were to provide a complete -interface to the latest production version of John Ousterhout's Tk, while providing -an Object Oriented interface to perl code. - -=head1 CONTENTS - -The package is composed of three loosely connected parts: - -=over 4 - -=item I<pTk> - Converted Tk source - -The I<pTk> sub-directory is a copy of the C code of Tk8.x, modified -to allow use by languages other than the original Tcl. -(The pTk can be read as 'perl' Tk or 'portable' Tk, depending on -your sensibilities.) - -=item B<Tk> to Perl 'Glue' - -The top level directory provides I<Tk.xs> and I<tkGlue.c> -which provide the perl-callable interfaces to pTk - -=item Perl code for 'Widget' Classes - -The I<Tk> sub-directory contains the various perl modules that comprise -the "Classes" that are visible to Tk applications. - -The "major" widgets such as B<Tk::Text> are actually in separate directories -at the top level (e.g. I<Text/*> for B<Tk::Text>) and are dynamically -loaded as needed on platforms which support perl5's B<DynaLoader>. - -=back - -=head1 CLASS HIERARCHY - -=over 4 - -=item B<package Tk;> - the 'base class' - -All the "command names" documented in Tcl/Tk are made to look like perl -sub's and reside in the Tk package. Their names are all lower case. -Typically there are very few commands at this level which are called -directly by applications. - -=item B<package Tk::Widget;> - the 'Widget class' - -There are no actual objects of the B<Tk::Widget> class; however all -the various Tk window "widgets" inherit from it, and it in turn -inherits all the core Tk functions from Tk. - -B<Tk::Widget> provides various functions and interfaces which are -common to all Widgets. - -A widget is represented to perl as a blessed reference to a hash. There are some -members of the hash which are private to Tk and its tkGlue code. Keys -starting with B<'.'> and of the form B</_[A-Z][A-Za-z_]+_/> -(i.e. starting and ending in _ and with first char after _ being upper case) should be -considered reserved to B<Tk>. - -=item B<Tk::Button>, B<Tk::Entry>, B<Tk::Text> ... - -There is one class for each of the "Tk" widget item types. -Some of them like B<Tk::Frame> do very little indeed, and really -only exist so that they can be derived from or so that focus or menu -traversal can discover the "kind" of window being processed. - -Other classes, B<Tk::Text> for example, provide a lot of methods -used with Tk's "bind" to provide a rich keyboard/mouse interface -to the widgets' data. - -These widget classes also include conversions of the Tcl code for -event bindings, keyboard focus traversal, menu bars, and menu keyboard -traversal. All the Tcl functions have been converted, but the names have -changed (systematically) and they have been split up between the various -classes in what I hope is an appropriate manner. -Name changes are normally: dropping initial tk_ as the Tk-ness is implicit -in the B<Tk::> prefix, and similarly dropping say Menu from the name if it -has been moved the Tk::Menu class. -Thus 'proc tkMenuNextEntry' becomes 'sub NextEntry' in the Tk::Menu package. - -=item B<Tk::Image> - -This does for Tk8.x's "images" what B<Tk::Widget> does for widgets. -Images are new to Tk8.x and the class structure is not mature either. - -There are three sub-classes B<Tk::Bitmap>, B<Tk::Pixmap> and B<Tk::Photo>. - -It is possible to create dynamic or auto-loaded image types inherited -from B<Tk::Image> for other image types or photo formats (e.g. support -for TIFF format). - -=item Composite Widgets - -A composite is some kind of 'frame' with subwidgets which give it useful behaviour. -B<Tk::Dialog> is an example of -a composite widget classes built from the basic B<Tk> ones. -It is intended that user code should not need to be aware that a particular -class is a composite, and create and configure such widgets in the same manner -as any other kind. The B<configure> mechanism and the methods of the -class manipulate the subwidgets as required. - -Composite widgets are implemented via B<Tk::Frame> and multiple inheritance. -The two 'frame' base classes B<Tk::Frame> and -B<Tk::Toplevel> include the additional class B<Tk::Derived> -in their inheritance. B<Tk::Derived> provides methods to allow additional -B<configure> options to be defined for a widget. - -A Composite widget is typically defined as derived -from B<Tk::Frame> or B<Tk::Toplevel> -(e.g. B<Tk::Dialog>). - -=back - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/pTk.pod b/Master/tlpkg/tlperl/lib/Tk/pTk.pod deleted file mode 100644 index 6e1a2a04022..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/pTk.pod +++ /dev/null @@ -1,550 +0,0 @@ -=head1 NAME - -Tk2portableTk - how to make your B<Tk> source portable to other -interpreted languages. - -=for category C Programming - -=head1 Author - -Ilya Zakharevich <ilya@math.ohio-state.edu> has contributed most of -this document. Many thanks. - -=head1 DESCRIPTION - -B<PortableTk> is an attempt to make B<Tk> useful from other -languages. Currently tk4.0 runs under Perl using this -approach. Below, I<Lang> is the notation for an external language to -which B<PortableTk> glues B<Tk> code. - -The main problem with using the code developed for B<TCL> with -different languages is the absence of data types: almost anything is -C<char*>. It makes automatic translation hopeless. However, if you -C<typedef> several new symbols to be C<char*>, you can still use your -code in B<TCL>, I<and> it will make the automatic translation -possible. - -Another problem with the approach that "everything is a string" is -impossibility to have a result that says "NotApplicable" without -setting an error. Thus different B<Tk> command return different string -values that mean "error happened", like C<"">, C<" "> or -C<"??">. Other languages can be more flexible, so in B<portableTk> you -should inform the compiler that what you want to return means "error" -(see L<Setting variables>). - -Currently B<PortableTk> uses several different approachs -to simplify translation: several B<TCL> functions that are especially -dangerous to use are undefined, so you can easily find places that -need to be updated to use Language-independent functions based on -compiler warnings. Eventually a way to use these Language-independent -functions under proper B<TCL> will be also provided. The end of this -document provides a starting point for such a project. - -=head1 Structure of B<pTk>, porting your code - -B<pTk>, that is a port of B<Tk>, is very special with respect to porting -of other code to B<portableTk>. The problem is that currently there is -very little hope to merge the modifications back into B<Tk>, so a -special strategy is needed to maintain this port. Do not use this -strategy to port your own code. - -B<pTk> is produced from B<Tk> via a two-step process: first, some -manual editing (the result is in the subdirectory C<mTk>), and second, -automatic conversion by the C<munge> script (written in Perl). Thus the -subdirectory C<pTk/mTk> contains code with minimal possible difference -from the virgin B<Tk> code, so it is easier to merge(1) the -differences between B<Tk> versions into modified code. - -It looks like the strategy for a portable code should be exactly -opposite: starting from B<TCL>-based code, apply C<munge>, and then -hand-edit the resulting code. Probably it is also possible to target -your code to B<portableTk> from scratch, since this will make it -possible to run it under a lot of I<Lang>uages. - -The only reason anyone would like to look into contents of C<pTk/mTk> -directory is to find out which constructs are not supported by -C<munge>. On the other hand, C<pTk> directory contains code that is -conformant to B<portableTk>, so you can look there to find example code. - -C<munge> is the script that converts most common B<Tk> constructs to -their C<portableTk> equivalent. For your code to qualify, you should -follow B<Tk> conventions on indentation and names of variables, in -particular, the array of arguments for the C<...CmdProc> should be -called C<argv>. - -For details on what C<munge> can do, see -L<Translation of some TCL functions>. - -=head1 B<PortableTk> API - -=head2 Checking what you are running under - -B<PortableTk> provides a symbol C<????>. If this symbol is defined, -your source is compiled with it. - -=head2 New types of configuration options - -B<PortableTk> defines several new types of configuration options: - - TK_CONFIG_CALLBACK - TK_CONFIG_LANGARG - TK_CONFIG_SCALARVAR - TK_CONFIG_HASHVAR - TK_CONFIG_ARRAYVAR - TK_CONFIG_IMAGE - -You should use them instead of TK_CONFIG_STRING whenever -appropriate. This allows your application to receive a direct -representation of the corresponding resource instead of the string -representation, if this is possible under given language. - -???? It looks like C<TK_CONFIG_IMAGE> and C<TK_CONFIG_SCALARVAR> set -variables of type C<char*>. - -=head2 Language data - -The following data types are defined: - -=over 4 - -=item C<Tcl_Obj *> - -is the main datatype of the language. This is a type that your C -function gets pointers to for arguments when the corresponding I<Lang> -function is called. The corresponding config type is -C<TK_CONFIG_LANGARG>. - -This is also a type that keeps information about contents of I<Lang> -variable. - -=item C<Var> - -Is a substitute for a C<char *> that contains name of variable. In -I<Lang> it is an object that contains reference to another I<Lang> -variable. - -=item C<LangResultSave> - -???? - -=item C<LangCallback> - -C<LangCallback*> a substitute for a C<char *> that contains command to -call. The corresponding config type is C<TK_CONFIG_CALLBACK>. - -=item C<LangFreeProc> - -It is the type that the C<Lang_SplitList> sets. Before you call it, -declare - - Args *args; - LangFreeProc *freeProc = NULL; - ... - code = Lang_SplitList(interp, value, - &argc, &args, &freeProc); - -After you use the split values, call - - if (args != NULL && freeProc) (*freeProc)(argc,args); - -It is not guaranteed that the C<args> can survive deletion of C<value>. - -=back - -=head2 Conversion - -The following macros and functions are used for conversion between -strings and the additional types: - - LangCallback * LangMakeCallback(Tcl_Obj *) - Tcl_Obj * LangCallbackArg(LangCallback *) - char * LangString(Tcl_Obj *) - -After you use the result of LangCallbackArg(), you should free it with -C<freeProc> C<LANG_DYNAMIC> (it is not guaranteed that any change of -C<Tcl_Obj *> will not be reflected in <LangCallback>, so you cannot do -LangSet...() in between, and you should reset it to C<NULL> if you -want to do any further assignments to this C<Tcl_Obj *>). - -The following function returns the C<Tcl_Obj *> that is a reference to C<Var>: - - Tcl_Obj * LangVarArg(Var) - -???? It is very anti-intuitive, I hope the name is changed. - - int LangCmpCallback(LangCallback *a,Tcl_Obj * b) - -(currently only a stub), and, at last, - - LangCallback * LangCopyCallback(LangCallback *) - -=head2 Callbacks - -Above we have seen the new datatype C<LangCallback> and the -corresponding I<Config option> C<TK_CONFIG_CALLBACK>. The following -functions are provided for manipulation of C<LangCallback>s: - - void LangFreeCallback(LangCallback *) - int LangDoCallback(Tcl_Interp *,LangCallback *, - int result,int argc, char *format,...) - -The argument C<format> of C<LangDoCallback> should contain a string that is -suitable for C<sprintf> with optional arguments of C<LangDoCallback>. -C<result> should be false if result of callback is not needed. - - int LangMethodCall(Tcl_Interp *,Tcl_Obj *,char *method, - int result,int argc,...) - -???? - -Conceptually, C<LangCallback*> is a substitute for ubiquitous C<char *> -in B<TCL>. So you should use C<LangFreeCallback> instead of C<ckfree> -or C<free> if appropriate. - -=head2 Setting variables - - void LangFreeArg (Tcl_Obj *, Tcl_FreeProc *freeProc) - Tcl_Obj * LangCopyArg (Tcl_Obj *); - void Tcl_AppendArg (Tcl_Interp *interp, Tcl_Obj *) - void LangSetString(Tcl_Obj * *, char *s) - void LangSetDefault(Tcl_Obj * *, char *s) - -These two are equivalent unless s is an empty string. In this case -C<LangSetDefault> behaves like C<LangSetString> with C<s==NULL>, i.e., -it sets the current value of the I<Lang> variable to be false. - - void LangSetInt(Tcl_Obj * *,int) - void LangSetDouble(Tcl_Obj * *,double) - -The I<Lang> functions separate uninitialized and initialized data -comparing data with C<NULL>. So the declaration for an C<Tcl_Obj *> should -look like - - Tcl_Obj * arg = NULL; - -if you want to use this C<arg> with the above functions. After you are -done, you should use C<LangFreeArg> with C<TCL_DYNAMIC> as C<freeProc>. - -=head2 Language functions - -Use - -=over 4 - -=item C<int LangNull(Tcl_Obj *)> - -to check that an object is false; - -=item C<int LangStringMatch(char *string, Tcl_Obj * match)> - -???? - -=item C<void LangExit(int)> - -to make a proper shutdown; - -=item C<int LangEval(Tcl_Interp *interp, char *cmd, int global)> - -to call I<Lang> C<eval>; - -=item C<void Lang_SetErrorCode(Tcl_Interp *interp,char *code)> - -=item C<char *Lang_GetErrorCode(Tcl_Interp *interp)> - -=item C<char *Lang_GetErrorInfo(Tcl_Interp *interp)> - -=item C<void LangCloseHandler(Tcl_Interp *interp,Tcl_Obj * arg,FILE *f,Lang_FileCloseProc *proc)> - -currently stubs only; - -=item C<int LangSaveVar(Tcl_Interp *,Tcl_Obj * arg,Var *varPtr,int type)> - -to save the structure C<arg> into I<Lang> variable C<*varPtr>; - -=item C<void LangFreeVar(Var var)> - -to free the result; - -=item C<int LangEventCallback(Tcl_Interp *,LangCallback *,XEvent *,KeySym)> - -???? - -=item C<int LangEventHook(int flags)> - -=item C<void LangBadFile(int fd)> - -=item C<int LangCmpConfig(char *spec, char *arg, size_t length)> - -unsupported????; - -=item C<void Tcl_AppendArg (Tcl_Interp *interp, Tcl_Obj *)> - -=back - -Another useful construction is - - Tcl_Obj * variable = LangFindVar(interp, Tk_Window tkwin, char *name); - -After using the above function, you should call - - LangFreeVar(Var variable); - -???? Note discrepancy in types! - -If you want to find the value of a variable (of type C<Tcl_Obj *>) given the -variable name, use C<Tcl_GetVar(interp, varName, flags)>. If you are -interested in the string value of this variable, use -C<LangString(Tcl_GetVar(...))>. - -To get a B<C> array of C<Tcl_Obj *> of length C<n>, use - - Tcl_Obj * *args = LangAllocVec(n); - ... - LangFreeVec(n,args); - -You can set the values of the C<Tcl_Obj *>s using C<LangSet...> functions, -and get string value using C<LangString>. - -If you want to merge an array of C<Tcl_Obj *>s into one C<Tcl_Obj *> (that will -be an array variable), use - - result = Tcl_Merge(listLength, list); - -=head2 Translation of some TCL functions - -We mark items that can be dealt with by C<munge> by I<Autoconverted>. - -=over 4 - -=item C<Tcl_AppendResult> - -does not take C<(char*)NULL>, but C<NULL> as delimiter. I<Autoconverted>. - -=item C<Tcl_CreateCommand>, C<Tcl_DeleteCommand> - -C<Tk_CreateWidget>, C<Tk_DeleteWidget>, the second argument is the -window itself, not the pathname. I<Autoconverted>. - -=item C<sprintf(interp-E<gt>result, "%d %d %d %d",...)> - -C<Tcl_IntResults(interp,4,0,...)>. I<Autoconverted>. - -=item C<interp-E<gt>result = "1";> - -C<Tcl_SetResult(interp,"1", TCL_STATIC)>. I<Autoconverted>. - -=item Reading C<interp-E<gt>result> - -C<Tcl_GetResult(interp)>. I<Autoconverted>. - -=item C<interp-E<gt>result = Tk_PathName(textPtr-E<gt>tkwin);> - -C<Tk_WidgetResult(interp,textPtr-E<gt>tkwin)>. I<Autoconverted>. - -=item Sequence C<Tcl_PrintDouble, Tcl_PrintDouble, ..., Tcl_AppendResult> - -Use a single command - - void Tcl_DoubleResults(Tcl_Interp *interp, int append, - int argc,...); - -C<append> governs whether it is required to clear the result first. - -A similar command for C<int> arguments is C<Tcl_IntResults>. - -=item C<Tcl_SplitList> - -Use C<Lang_SplitList> (see the description above). - -=back - -=head1 Translation back to TCL - -To use your B<portableTk> program with B<TCL>, put - - #include "ptcl.h" - -I<before> inclusion of C<tk.h>, and link the resulting code with -C<ptclGlue.c>. - -These files currently implement the following: - -=over 4 - -=item Additional config types: - - TK_CONFIG_CALLBACK - TK_CONFIG_LANGARG - TK_CONFIG_SCALARVAR - TK_CONFIG_HASHVAR - TK_CONFIG_ARRAYVAR - TK_CONFIG_IMAGE - -=item Types: - - Var, Tcl_Obj *, LangCallback, LangFreeProc. - -=item Functions and macros: - - Lang_SplitList, LangString, LangSetString, LangSetDefault, - LangSetInt, LangSetDouble Tcl_ArgResult, LangCallbackArg, - LangSaveVar, LangFreeVar, - LangFreeSplitProc, LangFreeArg, Tcl_DoubleResults, Tcl_IntResults, - LangDoCallback, Tk_WidgetResult, Tcl_CreateCommand, - Tcl_DeleteCommand, Tcl_GetResult. - -=back - -Current implementation contains enough to make it possible to compile -C<mTk/tkText*.[ch]> with the virgin B<Tk>. - -=head2 New types of events ???? - -PortableTk defines following new types of events: - - TK_EVENTTYPE_NONE - TK_EVENTTYPE_STRING - TK_EVENTTYPE_NUMBER - TK_EVENTTYPE_WINDOW - TK_EVENTTYPE_ATOM - TK_EVENTTYPE_DISPLAY - TK_EVENTTYPE_DATA - -and a function - - char * Tk_EventInfo(int letter, - Tk_Window tkwin, XEvent *eventPtr, - KeySym keySym, int *numPtr, int *isNum, int *type, - int num_size, char *numStorage) - -=head1 Checking for trouble - -If you start with working TCL code, you can start convertion using -the above hints. Good indication that you are doing is OK is absence -of C<sprintf> and C<sscanf> in your code (at least in the part that is -working with interpreter). - -=head1 Additional API - -What is described here is not included into base B<portableTk> -distribution. Currently it is coded in B<TCL> and as Perl macros (core -is coded as functions, so theoretically you can use the same object -files with different interpreted languages). - -=head2 C<ListFactory> - -Dynamic arrays in B<TCL> are used for two different purposes: to -construct strings, and to construct lists. These two usages will have -separate interfaces in other languages (since list is a different type -from a string), so you should use a different interface in your code. - -The type for construction of dynamic lists is C<ListFactory>. The API -below is a counterpart of the API for construction of dynamic lists -in B<TCL>: - - void ListFactoryInit(ListFactory *) - void ListFactoryFinish(ListFactory *) - void ListFactoryFree(ListFactory *) - Tcl_Obj * * ListFactoryArg(ListFactory *) - void ListFactoryAppend(ListFactory *, Tcl_Obj * *arg) - void ListFactoryAppendCopy(ListFactory *, Tcl_Obj * *arg) - ListFactory * ListFactoryNewLevel(ListFactory *) - ListFactory * ListFactoryEndLevel(ListFactory *) - void ListFactoryResult(Tcl_Interp *, ListFactory *) - -The difference is that a call to C<ListFactoryFinish> should precede the -actual usage of the value of C<ListFactory>, and there are two -different ways to append an C<Tcl_Obj *> to a C<ListFactory>: -ListFactoryAppendCopy() guarantees that the value of C<arg> is copied -to the list, but ListFactoryAppend() may append to the list a -reference to the current value of C<arg>. If you are not going to change -the value of C<arg> after appending, the call to ListFactoryAppend may -be quicker. - -As in B<TCL>, the call to ListFactoryFree() does not free the -C<ListFactory>, only the objects it references. - -The functions ListFactoryNewLevel() and ListFactoryEndLevel() return a -pointer to a C<ListFactory> to fill. The argument of -ListFactoryEndLevel() cannot be used after a call to this function. - -=head2 DStrings - -Production of strings are still supported in B<portableTk>. - -=head2 Accessing C<Tcl_Obj *>s - -The following functions for getting a value of an C<Tcl_Obj *> I<may> be -provided: - - double LangDouble(Tcl_Obj *) - int LangInt(Tcl_Obj *) - long LangLong(Tcl_Obj *) - int LangIsList(Tcl_Obj * arg) - -The function LangIsList() is supported only partially under B<TCL>, -since there is no data types. It checks whether there is a space -inside the string C<arg>. - -=head2 Assigning numbers to C<Tcl_Obj *>s - -While LangSetDouble() and LangSetInt() are supported ways to assign -numbers to assign an integer value to a variable, for the sake of -efficiency under B<TCL> it is supposed that the destination of these -commands was massaged before the call so it contains a long enough -string to sprintf() the numbers inside it. If you are going to -immediately use the resulting C<Tcl_Obj *>, the best way to do this is to -declare a buffer in the beginning of a block by - - dArgBuffer; - -and assign this buffer to the C<Tcl_Obj *> by - - void LangSetDefaultBuffer(Tcl_Obj * *) - -You can also create the buffer(s) manually and assign them using - - void LangSetBuffer(Tcl_Obj * *, char *) - -This is the only choice if you need to assign numeric values to -several C<Tcl_Obj *>s simultaneously. The advantage of the first approach is -that the above declarations can be made C<nop>s in different languages. - -Note that if you apply C<LangSetDefaultBuffer> to an C<Tcl_Obj *> that -contains some value, you can create a leak if you do not free that -C<Tcl_Obj *> first. This is a non-problem in real languages, but can be a -trouble in C<TCL>, unless you use only the above API. - -=head2 Creating new C<Tcl_Obj *>s - -The API for creating a new C<Tcl_Obj *> is - - void LangNewArg(Tcl_Obj * *, LangFreeProc *) - -The API for creating a new C<Tcl_Obj *> is absent. Just initialize C<Tcl_Obj *> to -be C<NULL>, and apply one of C<LangSet...> methods. - -After you use this C<Tcl_Obj *>, it should be freed thusly: - -C<LangFreeArg(arg, freeProc)>. - -=head2 Evaluating a list - -Use - - int LangArgEval(Tcl_Interp *, Tcl_Obj * arg) - -Here C<arg> should be a list to evaluate, in particular, the first -element should be a C<LangCallback> massaged to be an C<Tcl_Obj *>. The -arguments can be send to the subroutine by reference or by value in -different languages. - -=head2 Getting result as C<Tcl_Obj *> - -Use C<Tcl_ArgResult>. It is not guaranteed that result survives this -operation, so the C<Tcl_Obj *> you get should be the only mean to access the -data from this moment on. After you use this C<Tcl_Obj *>, you should free -it with C<freeProc> C<LANG_DYNAMIC> (you can do LangSet...() in between). - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/pack.pod b/Master/tlpkg/tlperl/lib/Tk/pack.pod deleted file mode 100644 index 0449556265c..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/pack.pod +++ /dev/null @@ -1,324 +0,0 @@ -# Copyright (c) 1990-1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::pack - Geometry manager that packs around edges of cavity - -=for category Tk Geometry Management - -=head1 SYNOPSIS - -S< >I<$widget>-E<gt>B<pack>?(I<args>)? - -S< >I<$widget>-E<gt>B<pack>I<Option>?(I<args>)? - -=head1 DESCRIPTION - -The B<pack> method is used to communicate with the packer, -a geometry manager that arranges the children of a parent by -packing them in order around the edges of the parent. - -In this B<perl> port of Tk it is normal to pack widgets one-at-a-time -using the widget object to be packed to invoke a method call. -This is a slight distortion of underlying Tk interface (which -can handle lists of windows to one pack method call) but has proven -effective in practice. - -The B<pack> method can have any of several forms, depending -on I<Option>: - -=over 4 - -=item I<$slave>-E<gt>B<pack>?(I<options>)? - -The options consist of pairs of arguments that specify how -to manage the slave. -See L<"THE PACKER ALGORITHM"> below for details on how the options -are used by the packer. -The following options are supported: - -=over 8 - -=item B<-after> =E<gt> I<$other> - -I<$other> must be another window. -Use its master as the master for the slave, and insert -the slave just after I<$other> in the packing order. - -=item B<-anchor> =E<gt> I<anchor> - -I<Anchor> must be a valid anchor position such as B<n> -or B<sw>; it specifies where to position each slave in its -parcel. -Defaults to B<center>. - -=item B<-before> =E<gt> I<$other> - -I<$other> must be another window. -Use its master as the master for the slave, and insert -the slave just before I<$other> in the packing order. - -=item B<-expand> =E<gt> I<boolean> - -Specifies whether the slave should be expanded to consume -extra space in their master. -I<Boolean> may have any proper boolean value, such as B<1> -or B<no>. -Defaults to 0. - -=item B<-fill> =E<gt> I<style> - -If a slave's parcel is larger than its requested dimensions, this -option may be used to stretch the slave. -I<Style> must have one of the following values: - -=over 12 - -=item B<none> - -Give the slave its requested dimensions plus any internal padding -requested with B<-ipadx> or B<-ipady>. This is the default. - -=item B<x> - -Stretch the slave horizontally to fill the entire width of its -parcel (except leave external padding as specified by B<-padx>). - -=item B<y> - -Stretch the slave vertically to fill the entire height of its -parcel (except leave external padding as specified by B<-pady>). - -=item B<both> - -Stretch the slave both horizontally and vertically. - -=back - -=item B<-in> =E<gt> I<$master> - -Insert the slave(s) at the end of the packing order for the master -window given by I<$master>. - -=item B<-ipadx> =E<gt> I<amount> - -I<Amount> specifies how much horizontal internal padding to -leave on each side of the slave(s). -I<Amount> must be a valid screen distance, such as B<2> or B<.5c>. -It defaults to 0. - -=item B<-ipady> =E<gt> I<amount> - -I<Amount> specifies how much vertical internal padding to -leave on each side of the slave(s). -I<Amount> defaults to 0. - -=item B<-padx> =E<gt> I<amount> - -I<Amount> specifies how much horizontal external padding to -leave on each side of the slave(s). -I<Amount> defaults to 0. - -=item B<-pady> =E<gt> I<amount> - -I<Amount> specifies how much vertical external padding to -leave on each side of the slave(s). -I<Amount> defaults to 0. - -=item B<-side> =E<gt> I<side> - -Specifies which side of the master the slave(s) will be packed against. -Must be B<left>, B<right>, B<top>, or B<bottom>. -Defaults to B<top>. - -=back - -=back - -If no B<-in>, B<-after> or B<-before> option is specified -then slave will be inserted at the end of the packing list -for its parent unless it is already managed by the packer (in which -case it will be left where it is). -If one of these options is specified then slave will be -inserted at the specified point. -If the slave are already managed by the geometry manager -then any unspecified options for them retain their previous values rather -than receiving default values. - -=over 4 - -=item I<$slave>-E<gt>B<packConfigure>?(I<options>)? - -Same as B<pack>. - -=item I<$slave>-E<gt>B<packForget> - -Removes I<slave> from the packing order for its -master and unmaps its window. -The slave will no longer be managed by the packer. - -=item I<$slave>-E<gt>B<packInfo> - -Returns a list whose elements are the current configuration state of -the slave given by I<$slave> in the same option-value form that -might be specified to B<packConfigure>. -The first two elements of the list are ``B<-in>=E<gt>I<$master>'' where -I<$master> is the slave's master. - -=item I<$master>-E<gt>B<packPropagate>?(I<boolean>)? - -If I<boolean> has a true boolean value such as B<1> or B<on> -then propagation is enabled for I<$master>, -(see L<"GEOMETRY PROPAGATION"> below). -If I<boolean> has a false boolean value then propagation is -disabled for I<$master>. -In either of these cases an empty string is returned. -If I<boolean> is omitted then the method returns B<0> or -B<1> to indicate whether propagation is currently enabled -for I<$master>. -Propagation is enabled by default. - -=item I<$master>-E<gt>B<packSlaves> - -Returns a list of all of the slaves in the packing order for I<$master>. -The order of the slaves in the list is the same as their order in -the packing order. -If I<$master> has no slaves then an empty list/string is returned in -array/scalar context, respectively - -=back - -=head1 THE PACKER ALGORITHM - -For each master the packer maintains an ordered list of slaves -called the I<packing list>. -The B<-in>, B<-after>, and B<-before> configuration -options are used to specify the master for each slave and the slave's -position in the packing list. -If none of these options is given for a slave then the slave -is added to the end of the packing list for its parent. - -The packer arranges the slaves for a master by scanning the -packing list in order. -At the time it processes each slave, a rectangular area within -the master is still unallocated. -This area is called the I<cavity>; for the first slave it -is the entire area of the master. - -For each slave the packer carries out the following steps: - -=over 4 - -=item [1] - -The packer allocates a rectangular I<parcel> for the slave -along the side of the cavity given by the slave's B<-side> option. -If the side is top or bottom then the width of the parcel is -the width of the cavity and its height is the requested height -of the slave plus the B<-ipady> and B<-pady> options. -For the left or right side the height of the parcel is -the height of the cavity and the width is the requested width -of the slave plus the B<-ipadx> and B<-padx> options. -The parcel may be enlarged further because of the B<-expand> -option (see L<"EXPANSION"> below) - -=item [2] - -The packer chooses the dimensions of the slave. -The width will normally be the slave's requested width plus -twice its B<-ipadx> option and the height will normally be -the slave's requested height plus twice its B<-ipady> -option. -However, if the B<-fill> option is B<x> or B<both> -then the width of the slave is expanded to fill the width of the parcel, -minus twice the B<-padx> option. -If the B<-fill> option is B<y> or B<both> -then the height of the slave is expanded to fill the width of the parcel, -minus twice the B<-pady> option. - -=item [3] - -The packer positions the slave over its parcel. -If the slave is smaller than the parcel then the B<-anchor> -option determines where in the parcel the slave will be placed. -If B<-padx> or B<-pady> is non-zero, then the given -amount of external padding will always be left between the -slave and the edges of the parcel. - -Once a given slave has been packed, the area of its parcel -is subtracted from the cavity, leaving a smaller rectangular -cavity for the next slave. -If a slave doesn't use all of its parcel, the unused space -in the parcel will not be used by subsequent slaves. -If the cavity should become too small to meet the needs of -a slave then the slave will be given whatever space is -left in the cavity. -If the cavity shrinks to zero size, then all remaining slaves -on the packing list will be unmapped from the screen until -the master window becomes large enough to hold them again. - -=back - -=head1 EXPANSION - -If a master window is so large that there will be extra space -left over after all of its slaves have been packed, then the -extra space is distributed uniformly among all of the slaves -for which the B<-expand> option is set. -Extra horizontal space is distributed among the expandable -slaves whose B<-side> is B<left> or B<right>, -and extra vertical space is distributed among the expandable -slaves whose B<-side> is B<top> or B<bottom>. - -=head1 GEOMETRY PROPAGATION - -The packer normally computes how large a master must be to -just exactly meet the needs of its slaves, and it sets the -requested width and height of the master to these dimensions. -This causes geometry information to propagate up through a -window hierarchy to a top-level window so that the entire -sub-tree sizes itself to fit the needs of the leaf windows. -However, the B<packPropagate> method may be used to -turn off propagation for one or more masters. -If propagation is disabled then the packer will not set -the requested width and height of the packer. -This may be useful if, for example, you wish for a master -window to have a fixed size that you specify. - -=head1 RESTRICTIONS ON MASTER WINDOWS - -The master for each slave must either be the slave's parent -(the default) or a descendant of the slave's parent. -This restriction is necessary to guarantee that the -slave can be placed over any part of its master that is -visible without danger of the slave being clipped by its parent. - -=head1 PACKING ORDER - -If the master for a slave is not its parent then you must make sure -that the slave is higher in the stacking order than the master. -Otherwise the master will obscure the slave and it will appear as -if the slave hasn't been packed correctly. -The easiest way to make sure the slave is higher than the master is -to create the master window first: the most recently created window -will be highest in the stacking order. -Or, you can use the B<raise> and B<lower> methods to change -the stacking order of either the master or the slave. - -=head1 SEE ALSO - -L<Tk::form|Tk::form> -L<Tk::grid|Tk::grid> -L<Tk::place|Tk::place> - -=head1 KEYWORDS - -geometry manager, location, packer, parcel, propagation, size - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/palette.pod b/Master/tlpkg/tlperl/lib/Tk/palette.pod deleted file mode 100644 index 40a6914fd5c..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/palette.pod +++ /dev/null @@ -1,89 +0,0 @@ -# Copyright (c) 1995-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -setPalette, bisque - Modify the Tk color palette - -=for category Creating and Configuring Widgets - -=head1 SYNOPSIS - -I<$widget>-E<gt>B<setPalette>(I<background>) - -I<$widget>-E<gt>B<setPalette(>I<name>=E<gt>I<value>?,I<name>=E<gt>I<value ...>?) - -I<$widget>-E<gt>B<bisque> - -=head1 DESCRIPTION - -The B<setPalette> method changes the color scheme for Tk. -It does this by modifying the colors of existing widgets and by changing -the option database so that future widgets will use the new color scheme. -If B<setPalette> is invoked with a single argument, the -argument is the name of a color to use as the normal background -color; B<setPalette> will compute a complete color palette -from this background color. -Alternatively, the arguments to B<setPalette> may consist of any number -of I<name>-I<value> pairs, where the first argument of the pair -is the name of an option in the Tk option database and the second -argument is the new value to use for that option. The following -database names are currently supported: - - activeBackground foreground selectColor - activeForeground highlightBackground selectBackground - background highlightColor selectForeground - disabledForeground insertBackground troughColor - -B<setPalette> tries to compute reasonable defaults for any -options that you don't specify. You can specify options other -than the above ones and Tk will change those options on widgets as -well. This feature may be useful if you are using custom widgets with -additional color options. - -Once it has computed the new value to use for each of the color options, -B<setPalette> scans the widget hierarchy to modify the options -of all existing widgets. For each widget, it checks to see if any -of the above options is defined for the widget. If so, and if the -option's current value is the default, then the value is changed; if -the option has a value other than the default, B<setPalette> -will not change it. The default for an option is the one provided by -the widget (B<($w-E<gt>configure('option'))[3]>) unless -B<setPalette> has been run previously, in which case it is the -value specified in the previous invocation of B<setPalette>. - -After modifying all the widgets in the application, B<setPalette> -adds options to the option database to change the defaults for -widgets created in the future. The new options are added at -priority B<widgetDefault>, so they will be overridden by options -from the .Xdefaults file or options specified on the command-line -that creates a widget. - -The method B<bisque> is provided for backward compatibility: -it restores the application's colors to the light brown (``bisque'') -color scheme used in Tk 3.6 and earlier versions. - -=head1 BUGS - -The use of option database names rather than the configure names is -understandable given the mechanism (copied from Tcl/Tk), but -is potentially confusing. - -The interpolation of different 'shades' of color used for 3D effects -in 'RGB' space can lead to undesirable changes in 'hue'. -Interpolation in 'HSV' (as used in B<Tk::ColorEditor>) would be more -robust and X11R5's color support probably even more so. - -=head1 SEE ALSO - -L<Tk::options|Tk::options> - -=head1 KEYWORDS - -bisque, color, palette - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/place.pod b/Master/tlpkg/tlperl/lib/Tk/place.pod deleted file mode 100644 index 9f7e74f210f..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/place.pod +++ /dev/null @@ -1,283 +0,0 @@ -# Copyright (c) 1992 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::place - Geometry manager for fixed or rubber-sheet placement - -=for category Tk Geometry Management - -=head1 SYNOPSIS - -S< >I<$widget>->B<place>?(I<-option>=>I<value>?, I<-option>=>I<value>, ...)? - -S< >I<$widget>->B<placeForget> - -S< >I<$widget>->B<placeInfo> - -S< >I<$master>->B<placeSlaves> - -=head1 DESCRIPTION - -The placer is a geometry manager for Tk. -It provides simple fixed placement of windows, where you specify -the exact size and location of one window, called the I<slave>, -within another window, called the I<master>. -The placer also provides rubber-sheet placement, where you specify the -size and location of the slave in terms of the dimensions of -the master, so that the slave changes size and location -in response to changes in the size of the master. -Lastly, the placer allows you to mix these styles of placement so -that, for example, the slave has a fixed width and height but is -centered inside the master. - -=over 4 - -=item I<$slave>->B<place>?(I<-option>=>I<value>?, I<-option>=>I<value>, ...?)? - -The B<place> method arranges for the placer -to manage the geometry of I<$slave>. -The remaining arguments consist of one or more I<-option>=>I<value> -pairs that specify the way in which I<$slave>'s -geometry is managed. I<-option> may have any of the values accepted -by the L<< placeConfigure|/$slave->placeConfigure >> method. - -The B<place> method returns I<$slave>. - -=item I<$slave>->B<placeConfigure>?(I<-option>=>I<value>?, I<-option>=>I<value>, ...?)? - -Query or modify the geometry options of the I<$slave>. If no option is -specified, this method returns a list describing the available -options (see Tk_ConfigureInfo for information on the format of this -list). If option is specified with no value, then the command returns -a list describing the one named option (this list will be identical to -the corresponding sublist of the value returned if no option is -specified). If one or more option-value pairs are specified, then the -method modifies the given option(s) to have the given value(s); in -this case the command returns C<undef>. - -The following I<-option>=>I<value> pairs are supported: - -=over 8 - -=item B<-anchor> => I<where> - -I<Where> specifies which point of I<$slave> is to be positioned -at the (x,y) location selected by the B<-x>, B<-y>, -B<-relx>, and B<-rely> options. -The anchor point is in terms of the outer area of I<$slave> -including its border, if any. -Thus if I<where> is B<se> then the lower-right corner of -I<$slave>'s border will appear at the given (x,y) location -in the master. -The anchor position defaults to B<nw>. - -=item B<-bordermode> => I<mode> - -I<Mode> determines the degree to which borders within the -master are used in determining the placement of the slave. -The default and most common value is B<inside>. -In this case the placer considers the area of the master to -be the innermost area of the master, inside any border: -an option of B<-x>=>B<0> corresponds to an x-coordinate just -inside the border and an option of B<-relwidth>=>1.0 -means I<$slave> will fill the area inside the master's -border. -If I<mode> is B<outside> then the placer considers -the area of the master to include its border; -this mode is typically used when placing I<$slave> -outside its master, as with the options -B<-x>=>B<0>, B<-y>=>B<0>, B<-anchor>=>B<ne>. -Lastly, I<mode> may be specified as B<ignore>, in which -case borders are ignored: the area of the master is considered -to be its official X area, which includes any internal border but -no external border. A bordermode of B<ignore> is probably -not very useful. - -=item B<-height> => I<size> - -I<Size> specifies the height for I<$slave> in screen units -(i.e. any of the forms accepted by B<Tk_GetPixels>). -The height will be the outer dimension of I<$slave> including its -border, if any. -If I<size> is an empty string, or if no B<-height> or -B<-relheight> option is specified, then the height requested -internally by the window will be used. - -=item B<-in> => I<$master> - -I<$master> is the reference to the window relative -to which I<$slave> is to be placed. -I<$master> must either be I<$slave>'s parent or a descendant -of I<$slave>'s parent. -In addition, I<$master> and I<$slave> must both be descendants -of the same top-level window. -These restrictions are necessary to guarantee -that I<$slave> is visible whenever I<$master> is visible. -If this option isn't specified then the master defaults to -I<$slave>'s parent. - -=item B<-relheight> => I<size> - -I<Size> specifies the height for I<$slave>. -In this case the height is specified as a floating-point number -relative to the height of the master: 0.5 means I<$slave> will -be half as high as the master, 1.0 means I<$slave> will have -the same height as the master, and so on. -If both B<-height> and B<-relheight> are specified for a slave, -their values are summed. For example, B<-relheight>=>1.0, B<-height>=>-2 -makes the slave 2 pixels shorter than the master. - -=item B<-relwidth> => I<size> - -I<Size> specifies the width for I<$slave>. -In this case the width is specified as a floating-point number -relative to the width of the master: 0.5 means I<$slave> will -be half as wide as the master, 1.0 means I<$slave> will have -the same width as the master, and so on. -If both B<-width> and B<-relwidth> are specified for a slave, -their values are summed. For example, B<-relwidth>=>1.0, B<-width>=>5 -makes the slave 5 pixels wider than the master. - -=item B<-relx> => I<location> - -I<Location> specifies the x-coordinate within the master window -of the anchor point for I<$slave> widget. -In this case the location is specified in a relative fashion -as a floating-point number: 0.0 corresponds to the left edge -of the master and 1.0 corresponds to the right edge of the master. -I<Location> need not be in the range 0.0-1.0. -If both B<-x> and B<-relx> are specified for a slave -then their values are summed. For example, "B<-relx>=>0.5, B<-x>=-2" -positions the left edge of the slave 2 pixels to the left of the -center of its master. - -=item B<-rely> => I<location> - -I<Location> specifies the y-coordinate within the master window -of the anchor point for I<$slave> widget. -In this case the value is specified in a relative fashion -as a floating-point number: 0.0 corresponds to the top edge -of the master and 1.0 corresponds to the bottom edge of the master. -I<Location> need not be in the range 0.0-1.0. -If both B<-y> and B<-rely> are specified for a slave -then their values are summed. For example, B<-rely>=>0.5, B<-x>=>3 -positions the top edge of the slave 3 pixels below the -center of its master. - -=item B<-width> => I<size> - -I<Size> specifies the width for I<$slave> in screen units -(i.e. any of the forms accepted by B<Tk_GetPixels>). -The width will be the outer width of I<$slave> including its -border, if any. -If I<size> is an empty string, or if no B<-width> -or B<-relwidth> option is specified, then the width requested -internally by the window will be used. - -=item B<-x> => I<location> - -I<Location> specifies the x-coordinate within the master window -of the anchor point for I<$slave> widget. -The location is specified in screen units (i.e. any of the forms -accepted by B<Tk_GetPixels>) and need not lie within the bounds -of the master window. - -=item B<-y> => I<location> - -I<Location> specifies the y-coordinate within the master window -of the anchor point for I<$slave> widget. -The location is specified in screen units (i.e. any of the forms -accepted by B<Tk_GetPixels>) and need not lie within the bounds -of the master window. - -=back - -If the same value is specified separately with -two different options, such as B<-x> and B<-relx>, then -the most recent option is used and the older one is ignored. - -=item I<$slave>->B<placeForget> - -The B<placeForget> method causes the placer to stop managing -the geometry of I<$slave>. As a side effect of this method call -I<$slave> will be unmapped so that it doesn't appear on the -screen. -If I<$slave> isn't currently managed by the placer then the -method call has no effect. -B<placeForget> returns an empty string as result. - -=item I<$slave>->B<placeInfo> - -The B<placeInfo> method returns a list giving the current -configuration of I<$slave>. -The list consists of I<-option>=>I<value> pairs in exactly the -same form as might be specified to the B<place> -method. - -=item I<$slave>->B<placeSlaves> - -The B<placeSlaves> method returns a list of all the slave -windows for which I<$master> is the master. -If there are no slaves for I<$master> then an empty list is -returned. - -=back - -If the configuration of a window has been retrieved with -B<placeInfo>, that configuration can be restored later by -first using B<placeForget> to erase any existing information -for the window and then invoking B<place> with -the saved information. - -=head1 FINE POINTS - -It is not necessary for the master window to be the parent -of the slave window. -This feature is useful in at least two situations. -First, for complex window layouts it means you can create a -hierarchy of subwindows whose only purpose -is to assist in the layout of the parent. -The ``I<real children>'' of the parent (i.e. the windows that -are significant for the application's user interface) can be -children of the parent yet be placed inside the windows -of the geometry-management hierarchy. -This means that the path names of the ``I<real children>'' -don't reflect the geometry-management hierarchy and users -can specify options for the real children -without being aware of the structure of the geometry-management -hierarchy. - -A second reason for having a master different than the slave's -parent is to tie two siblings together. -For example, the placer can be used to force a window always to -be positioned centered just below one of its -siblings by specifying the configuration - -S< >B<-in>=>I<$sibling>, B<-relx>=>0.5, B<-rely>=>1.0, -B<-anchor>=>'n', B<-bordermode>=>'outside' - -Whenever the I<$sibling> widget is repositioned in the future, the slave -will be repositioned as well. - -Unlike many other geometry managers (such as the packer) -the placer does not make any attempt to manipulate the geometry of -the master windows or the parents of slave windows (i.e. it doesn't -set their requested sizes). -To control the sizes of these windows, make them windows like -frames and canvases that provide configuration options for this purpose. - -=head1 SEE ALSO - -L<Tk::form>, L<Tk::grid>, L<Tk::pack> - -=head1 KEYWORDS - -geometry manager, height, location, master, place, rubber sheet, slave, width - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/selection.pod b/Master/tlpkg/tlperl/lib/Tk/selection.pod deleted file mode 100644 index f8a3ce54856..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/selection.pod +++ /dev/null @@ -1,159 +0,0 @@ -# Copyright (c) 1990-1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -Tk::Selection - Manipulate the X selection - -=for category User Interaction - -=head1 SYNOPSIS - -I<$widget>-E<gt>B<Selection>I<Option>?(I<args>)? - -=head1 DESCRIPTION - -This command provides an interface to the X selection mechanism and -implements the full selection functionality described in the -X Inter-Client Communication Conventions Manual (ICCCM). - -The widget object used to invoke the methods below determines which -display is used to access the selection. -In order to avoid conflicts with B<selection> methods of widget classes -(e.g. B<Text>) this set of methods uses the prefix B<Selection>. -The following methods are currently supported: - -=over 4 - -=item I<$widget>-E<gt>B<SelectionClear>?(B<-selection>=E<gt>I<selection>)? - -If I<selection> exists anywhere on I<$widget>'s display, clear it -so that no window owns the selection anymore. I<Selection> -specifies the X selection that should be cleared, and should be an -atom name such as PRIMARY or CLIPBOARD; see the Inter-Client -Communication Conventions Manual for complete details. -I<Selection> defaults to PRIMARY. -Returns an empty string. - -=item I<$widget>-E<gt>B<SelectionGet>?(?B<-selection>=E<gt>I<selection>?,?B<-type>=E<gt>I<type>?)? - -Retrieves the value of I<selection> from I<$widget>'s display and -returns it as a result. I<Selection> defaults to PRIMARY. - -I<Type> specifies the form in which the selection is to be returned -(the desired ``target'' for conversion, in ICCCM terminology), and -should be an atom name such as STRING or FILE_NAME; see the -Inter-Client Communication Conventions Manual for complete details. -I<Type> defaults to STRING. The selection owner may choose to -return the selection in any of several different representation -formats, such as STRING, ATOM, INTEGER, etc. (this format is different -than the selection type; see the ICCCM for all the confusing details). - -If I<format> is not STRING then things get messy, the following -description is from the Tcl/Tk man page as yet incompetely translated for -the perl version - it is misleading at best. - -If the selection is returned in a non-string format, such as INTEGER -or ATOM, the B<SelectionGet> converts it to a list of perl -values: atoms are converted to their -textual names, and anything else is converted integers. - -A goal of the perl port is to provide better handling of different -formats than Tcl/Tk does, which should be possible given perl's -wider range of ``types''. Although some thought went into this -in very early days of perl/Tk what exactly happens is still -"not quite right" and subject to change. - -=item I<$widget>-E<gt>B<SelectionHandle>(?B<-selection>=E<gt>I<selection>?,?B<-type>=E<gt>I<type>?,?B<-format>=E<gt>I<format>? I<callback>) - -Creates a handler for selection requests, such that I<callback> will -be executed whenever I<selection> is owned by I<$widget> and -someone attempts to retrieve it in the form given by I<type> -(e.g. I<type> is specified in the B<selection get> command). -I<Selection> defaults to PRIMARY, I<type> defaults to STRING, and -I<format> defaults to STRING. If I<callback> is an empty string -then any existing handler for I<$widget>, I<type>, and -I<selection> is removed. - -When I<selection> is requested, I<$widget> is the selection owner, -and I<type> is the requested type, I<callback> will be executed -with two additional arguments. -The two additional arguments -are I<offset> and I<maxBytes>: I<offset> specifies a starting -character position in the selection and I<maxBytes> gives the maximum -number of bytes to retrieve. The command should return a value consisting -of at most I<maxBytes> of the selection, starting at position -I<offset>. For very large selections (larger than I<maxBytes>) -the selection will be retrieved using several invocations of I<callback> -with increasing I<offset> values. If I<callback> returns a string -whose length is less than I<maxBytes>, the return value is assumed to -include all of the remainder of the selection; if the length of -I<callback>'s result is equal to I<maxBytes> then -I<callback> will be invoked again, until it eventually -returns a result shorter than I<maxBytes>. The value of I<maxBytes> -will always be relatively large (thousands of bytes). - -If I<callback> returns an error (e.g. via B<die>) -then the selection retrieval is rejected -just as if the selection didn't exist at all. - -The I<format> argument specifies the representation that should be -used to transmit the selection to the requester (the second column of -Table 2 of the ICCCM), and defaults to STRING. If I<format> is -STRING, the selection is transmitted as 8-bit ASCII characters (i.e. -just in the form returned by I<command>). - -If I<format> is not STRING then things get messy, the following -description is from the Tcl/Tk man page as yet untranslated for -the perl version - it is misleading at best. - -If I<format> is -ATOM, then the return value from I<command> is divided into fields -separated by white space; each field is converted to its atom value, -and the 32-bit atom value is transmitted instead of the atom name. -For any other I<format>, the return value from I<command> is -divided into fields separated by white space and each field is -converted to a 32-bit integer; an array of integers is transmitted -to the selection requester. - -The I<format> argument is needed only for compatibility with -many selection requesters, except Tcl/Tk. If Tcl/Tk is being -used to retrieve the selection then the value is converted back to -a string at the requesting end, so I<format> is -irrelevant. - -A goal of the perl port is to provide better handling of different -formats than Tcl/Tk does, which should be possible given perl's -wider range of ``types''. Although some thought went into this -in very early days of perl/Tk what exactly happens is still -"not quite right" and subject to change. - -=item I<$widget>-E<gt>B<SelectionOwner>?(B<-selection>=E<gt>I<selection>)? - -B<SelectionOwner> returns the -window in this application that owns I<selection> on the display -containing I<$widget>, or an empty string if no window in this -application owns the selection. I<Selection> defaults to PRIMARY. - -=item I<$widget>-E<gt>B<SelectionOwn>?(?B<-command>=E<gt>I<callback>?,?B<-selection>=E<gt>I<selection>?)? - -B<SelectionOwn> causes I<$widget> to become -the new owner of I<selection> on I<$widget>'s display, returning -an empty string as result. The existing owner, if any, is notified -that it has lost the selection. -If I<callback> is specified, it will be executed when -some other window claims ownership of the selection away from -I<$widget>. I<Selection> defaults to PRIMARY. - -=back - -=head1 KEYWORDS - -clear, format, handler, ICCCM, own, selection, target, type - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/send.pod b/Master/tlpkg/tlperl/lib/Tk/send.pod deleted file mode 100644 index 40382f2422d..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/send.pod +++ /dev/null @@ -1,118 +0,0 @@ -# Copyright (c) 1990-1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -send - Execute a command in a different application - -=for category Tk Generic Methods - -=head1 SYNOPSIS - -S< >I<$result> = I<$widget>-E<gt>B<send>(?I<options>,?I<app>=E<gt>I<cmd>?I<arg arg ...>?) - -=head1 DESCRIPTION - -This method arranges for I<cmd> (and I<arg>s) to be 'sent' to the -application named by I<app>. It returns the result or -an error (hence above should probably be 'wrapped' in B<eval{}> and $@ tested). -I<App> may be the name of any application whose main window is -on the display containing the sender's main window; it need not -be within the same process. -If no I<arg> arguments are present, then the string to be sent -is contained entirely within the I<cmd> argument. If one or -more I<arg>s are present, they are concatenated separated by white space to -form the string to be sent. - -If the initial arguments of the call begin with ``-'' -they are treated as options. The following options are -currently defined: - -=over 4 - -=item B<-async> - -Requests asynchronous invocation. In this case the B<send> -command will complete immediately without waiting for I<cmd> -to complete in the target application; no result will be available -and errors in the sent command will be ignored. -If the target application is in the same process as the sending -application then the B<-async> option is ignored. - -=item B<--> - -Serves no purpose except to terminate the list of options. This -option is needed only if I<app> could contain a leading ``-'' -character. - -=back - -=head1 APPLICATION NAMES - -The name of an application is set initially from the name of the -program or script that created the application. -You can query and change the name of an application with the -B<appname> method. - -=head1 WHAT IS A SEND - -The B<send> mechanism was designed to allow Tcl/Tk applications -to send Tcl Scripts to each other. This does not map very well onto perl/Tk. -Perl/Tk "sends" a string to I<app>, what happens as a result of this -depends on the receiving application. If the other application is a Tcl/Tk4.* -application it will be treated as a Tcl Script. If the "other" application is -perl/Tk application (including sends to self) then the string is -passed as an argument to a method call of the following form: - -I<$mainwindow>-E<gt>B<Receive(>I<string>); - -There is a default (AutoLoaded) B<Tk::Receive> which returns an error to the -sending application. A particular application may define its own -B<Receive> method in any class in B<MainWindow>'s inheritance tree -to do whatever it sees fit. For example it could B<eval> the string, -possibly in a B<Safe> "compartment". - -If a Tcl/Tk application "sends" anything to a perl/Tk application -then the perl/Tk application would have to attempt to interpret the -incoming string as a Tcl Script. Simple cases are should not be too hard to -emulate (split on white space and treat first element as "command" and other -elements as arguments). - -=head1 SECURITY - -The B<send> command is potentially a serious security loophole, -since any application that can connect to your X server can send -scripts to your applications. Hence the default behaviour outlined above. -(With the availability of B<Safe> it may make sense to relax default behaviour -a little.) - -Unmonitored B<eval>'ing of these incoming "scripts" can cause perl to -read and write files and invoke subprocesses under your name. -Host-based access control such as that provided by B<xhost> -is particularly insecure, since it allows anyone with an account -on particular hosts to connect to your server, and if disabled it -allows anyone anywhere to connect to your server. -In order to provide at least a small amount of -security, core Tk checks the access control being used by the server -and rejects incoming sends unless (a) B<xhost>-style access control -is enabled (i.e. only certain hosts can establish connections) and (b) the -list of enabled hosts is empty. -This means that applications cannot connect to your server unless -they use some other form of authorization -such as that provide by B<xauth>. - -=head1 SEE ALSO - -L<perlfunc/eval>, L<Safe>, -system's administrator/corporate security guidelines etc. - -=head1 KEYWORDS - -application, name, remote execution, security, send - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/tixWm.pod b/Master/tlpkg/tlperl/lib/Tk/tixWm.pod deleted file mode 100644 index 9bdd02d461c..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/tixWm.pod +++ /dev/null @@ -1,73 +0,0 @@ - - -=head1 NAME - -Tk::tixWm - Tix's addition to the standard TK wm command. - -=for category Tix Extensions - -=head1 SYNOPSIS - -S< >I<$widget>-E<gt>B<wmCapture> - -S< >I<$widget>-E<gt>B<wmRelease> - -=head1 DESCRIPTION - -The B<wmCapture> and the B<wmRelease> methods change the -toplevel attribute of Tk widgets. - -=head1 METHODS - -=over 4 - -=item I<$widget>-E<gt>B<wmCapture> - -Converts the toplevel window specified by I<$widget> into a non-toplevel -widget. Normally this command is called to convert a L<Toplevel|Tk::Toplevel> widget -into a L<Frame|Tk::Frame> widget. The newly-converted frame widget is -un-mapped from the screen. To make it appear inside its parent, you -must call a geometry manager (e.g. grid or pack) explictly. - -=item I<$widget>-E<gt>B<wmRelease> - -Makes the non-toplevel window specified by I<$widget> into a toplevel -widget. Normally this command is called to convert a L<Frame|Tk::Frame> widget -into a L<Toplevel|Tk::Toplevel> widget, but it can also be used on any -non-toplevel widget (e.g, label). The newly-converted toplevel window -is in a B<withdrawn> state. To make it appear on the screen, you must call -B<deiconify> after calling B<wmRelease>. - -Any data associated with I<$widget> via B<wm> methods (icon, protocol, -command etc.) are released, and must be re-established if window is later -re-captured. - -=back - -=head1 BUGS - -B<wmCapture> does not exist in the Win32 window manager code. - -How these methods interact with perl/Tk's class hierarchy is not yet clear. -In particular a B<wmRelease>d window will not automatically ``I<inherit>'' -the B<Tk::Wm> methods, however a B<wmCapture>d window still will. -(A B<release>d B<Label> might make a good candidate for an B<Icon>.) - -=head1 AUTHORS - -Ioi Kim Lam - ioi@graphics.cis.upenn.edu wrote original Tix version. -Updated for tk8.0, Win32 and perl by Nick Ing-Simmons. - -=head1 SEE ALSO - -L<Tk::Wm|Tk::Wm> -L<Tk::Mwm|Tk::Mwm> -L<Tk::Frame|Tk::Frame> -L<Tk::Toplevel|Tk::Toplevel> - -=head1 KEYWORDS - -window manager, wm, TIX - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/tkvars.pod b/Master/tlpkg/tlperl/lib/Tk/tkvars.pod deleted file mode 100644 index 5ae8ac477ef..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/tkvars.pod +++ /dev/null @@ -1,107 +0,0 @@ -# Copyright (c) 1990-1994 The Regents of the University of California. -# Copyright (c) 1994-1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# -# - -=head1 NAME - -tkvars - Variables used or set by Tk - -=for category Tk Generic Methods - -=head1 DESCRIPTION - -The following perl variables are either set or used by Tk at various times -in its execution. (For a list of variables used by perl see L<perlvar>.) - -=over 4 - -=item B<$Tk::library> - -This variable holds the file name for a directory containing the modules -related to Tk. These modules include an initialization -file that is normally processed whenever a Tk application starts up, -plus other files containing procedures that implement default behaviors -for widgets. -The initial value of B<$Tk::library> is set when Tk is added to -an interpreter; this is done by searching searching for a directory -named Tk in the directory where the file F<Tk.pm>, or the first -directory F<Tk> in C<@INC>. - -The B<TK_LIBRARY> environment variable used by Tcl/Tk is not -supported by perl/Tk. Please use L<@INC|perlvar/@INC> to change where modules -are searched. - -B<Note:> This is Tcl remnant. With perl it makes more sense to -use C<@INC> and C<%INC>). - -=item B<$Tk::patchLevel> - -Contains a decimal integer giving the current patch level for Tk. -The patch level is incremented for each new release or patch, and -it uniquely identifies an official version of Tk. - -B<Note:> this is Tcl remnant. With perl it makes more sense to -use B<$Tk::VERSION> described below. - -=item B<$Tk::strictMotif> - -This variable is set to zero by default. -If an application sets it to one, then Tk attempts to adhere as -closely as possible to Motif look-and-feel standards. -For example, active elements such as buttons and scrollbar -sliders will not change color when the pointer passes over them. - -=item B<$Tk::VERSION> - -The variable holds the current version number of the perl/Tk -release in the form I<major>.I<minor>. I<Major> and -I<minor> are integers. - -The I<major> version number shows on which -Tcl/Tk release perl/Tk is based. E.g., B<402> means based on -Tcls Tk 4.2. (Patchlevel of Tcls Tk are not incorporated because -perl/Tk tended to be ``I<ahead>'' of them on some fixes and behind on -others. The first digest of the major version number increases in -any Tk release that includes changes that are not backward compatible -(i.e. whenever existing perl/Tk applications and scripts may have to change to -work with the new release). - -The I<minor> version depends on perl/Tk only. It uses the -'even'='stable', 'odd'='experimental' scheme that linux uses: - - .0xx - inherently 'alpha' - .1xx - experimental 'beta' - .2xx - stable - .3xx - experimental - .4xx - stable - ... - -The minor version number increases with -each new release of Tk, except that it resets to zero whenever the -major version number changes. - -=item B<$Tk::version> - -The variable holds the current version number of the Tk -library in the form I<major>.I<minor>. I<Major> and -I<minor> are integers. The major version number increases in -any Tk release that includes changes that are not backward compatible -(i.e. whenever existing Tk applications and scripts may have to change to -work with the new release). The minor version number increases with -each new release of Tk, except that it resets to zero whenever the -major version number changes. - -B<Note:> this is Tcl remnant. With perl it makes more sense to -use B<$Tk::VERSION> described above. - -=back - -=head1 KEYWORDS - -variables, version - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Tk/widgets.pod b/Master/tlpkg/tlperl/lib/Tk/widgets.pod deleted file mode 100644 index 114f52505d7..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/widgets.pod +++ /dev/null @@ -1,20 +0,0 @@ - -=head1 NAME - -Tk::widgets - preload widget classes - -=for pm Tk/widgets.pm - -=for category Implementation - -=head1 SYNOPSIS - - use Tk::widgets qw(Button Label Frame); - -=head1 DESCRIPTION - -Does a 'require Tk::Foo' for each 'Foo' in the list. -May speed startup by avoiding AUTOLOADs. - -=cut - |