diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk')
113 files changed, 29052 insertions, 23 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/804delta.pod b/Master/tlpkg/tlperl/lib/Tk/804delta.pod new file mode 100644 index 00000000000..1472f38c86b --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/804delta.pod @@ -0,0 +1,110 @@ +=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 new file mode 100644 index 00000000000..7d094f4e262 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Adjuster.pod @@ -0,0 +1,223 @@ + +=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 new file mode 100644 index 00000000000..996b035b1c5 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Animation.pod @@ -0,0 +1,92 @@ + +=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 new file mode 100644 index 00000000000..9188a9e25a4 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Balloon.pod @@ -0,0 +1,293 @@ + +=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 new file mode 100644 index 00000000000..49bf20ce4b4 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Bitmap.pod @@ -0,0 +1,103 @@ +# 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 new file mode 100644 index 00000000000..98a547c4084 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/BrowseEntry.pod @@ -0,0 +1,210 @@ + +=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 new file mode 100644 index 00000000000..6c3eb5ffa72 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Button.pod @@ -0,0 +1,255 @@ +# 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<PerlE<sol>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<perlE<sol>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 new file mode 100644 index 00000000000..daf4cf7f32e --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Canvas.pod @@ -0,0 +1,2394 @@ +# 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 new file mode 100644 index 00000000000..710e1192055 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Checkbutton.pod @@ -0,0 +1,347 @@ +# 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<perlE<sol>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<perlE<sol>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<perlE<sol>Tk callback|Tk::callbacks> associated with the checkbutton, if there is one. +The return value is the return value from the L<perlE<sol>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 new file mode 100644 index 00000000000..a65eb37a870 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Clipboard.pod @@ -0,0 +1,89 @@ +# 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 new file mode 100644 index 00000000000..58b69fded17 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/CmdLine.pod @@ -0,0 +1,454 @@ +=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 new file mode 100644 index 00000000000..48e6477f3ef --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/ColorEditor.pod @@ -0,0 +1,120 @@ + +=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/Compound.pod b/Master/tlpkg/tlperl/lib/Tk/Compound.pod new file mode 100644 index 00000000000..01f6e5f2639 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Compound.pod @@ -0,0 +1,298 @@ +# 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/Config.pm b/Master/tlpkg/tlperl/lib/Tk/Config.pm index fcb413bce3d..c8eaa5e795e 100644 --- a/Master/tlpkg/tlperl/lib/Tk/Config.pm +++ b/Master/tlpkg/tlperl/lib/Tk/Config.pm @@ -2,7 +2,7 @@ package Tk::Config; require Exporter; use base qw(Exporter); -$VERSION = '804.032'; +$VERSION = '804.033'; $inc = '-I$(TKDIR) -I$(TKDIR)/pTk/mTk/xlib'; $define = ''; $xlib = ''; diff --git a/Master/tlpkg/tlperl/lib/Tk/ConfigSpecs.pod b/Master/tlpkg/tlperl/lib/Tk/ConfigSpecs.pod new file mode 100644 index 00000000000..5f90c2716bb --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/ConfigSpecs.pod @@ -0,0 +1,262 @@ +# $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 new file mode 100644 index 00000000000..27db79744df --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/DItem.pod @@ -0,0 +1,439 @@ +=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 new file mode 100644 index 00000000000..4b99934d5bd --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Derived.pod @@ -0,0 +1,89 @@ + +=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 new file mode 100644 index 00000000000..871206d504c --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Dialog.pod @@ -0,0 +1,107 @@ +# 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 new file mode 100644 index 00000000000..a091cd98427 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/DialogBox.pod @@ -0,0 +1,156 @@ + +=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.pm b/Master/tlpkg/tlperl/lib/Tk/DirTree.pm index 46d05fa3ab5..abdfbdb547d 100644 --- a/Master/tlpkg/tlperl/lib/Tk/DirTree.pm +++ b/Master/tlpkg/tlperl/lib/Tk/DirTree.pm @@ -7,7 +7,7 @@ package Tk::DirTree; use strict; use vars qw($VERSION); -$VERSION = '4.021'; +$VERSION = '4.022'; use Tk; use Tk::Derived; @@ -181,7 +181,7 @@ sub dirnames { $w->{curr_dir} = delete $args->{-initialdir}; if (!defined $w->{curr_dir}) { require Cwd; - $w->{curr_dir} = Cwd::cwd(); + $w->{curr_dir} = Cwd::getcwd(); } if (defined $args->{-mustexist}) { die "-mustexist is not yet implemented"; diff --git a/Master/tlpkg/tlperl/lib/Tk/DirTree.pod b/Master/tlpkg/tlperl/lib/Tk/DirTree.pod new file mode 100644 index 00000000000..d8ded2f41b7 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/DirTree.pod @@ -0,0 +1,172 @@ + +=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/DragDrop/Common.pod b/Master/tlpkg/tlperl/lib/Tk/DragDrop/Common.pod new file mode 100644 index 00000000000..cd53ab79a99 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/DragDrop/Common.pod @@ -0,0 +1,16 @@ + +=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/DragDrop/SunConst.pod b/Master/tlpkg/tlperl/lib/Tk/DragDrop/SunConst.pod new file mode 100644 index 00000000000..eb5d892871b --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/DragDrop/SunConst.pod @@ -0,0 +1,18 @@ + +=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/DropSite.pod b/Master/tlpkg/tlperl/lib/Tk/DropSite.pod new file mode 100644 index 00000000000..8ae5a199fe3 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/DropSite.pod @@ -0,0 +1,33 @@ +=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 new file mode 100644 index 00000000000..1b6dbf15482 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Entry.pod @@ -0,0 +1,693 @@ +# 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 new file mode 100644 index 00000000000..9c38f0b7d74 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Error.pod @@ -0,0 +1,145 @@ +# 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/ErrorDialog.pod b/Master/tlpkg/tlperl/lib/Tk/ErrorDialog.pod new file mode 100644 index 00000000000..6e13550967f --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/ErrorDialog.pod @@ -0,0 +1,36 @@ +# 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::ErrorDialog - Method invoked to process background errors + +=for category Binding Events and Callbacks + +=head1 SYNOPSIS + +Customization: + + require Tk::ErrorDialog; + +=head1 DESCRIPTION + +C<Tk::ErrorDialog> is a possibility to handle background errors. For a full descriptionm, see L<Tk::Error>. + +=head1 SEE ALSO + +L<Tk::Error> +L<Tk::bind|Tk::bind> +L<Tk::after|Tk::after> +L<Tk::fileevent|Tk::fileevent> + +=head1 KEYWORDS + +background error, reporting, error dialog + +=cut + diff --git a/Master/tlpkg/tlperl/lib/Tk/Event.pm b/Master/tlpkg/tlperl/lib/Tk/Event.pm index e9253bef602..f00a0b5bdbe 100644 --- a/Master/tlpkg/tlperl/lib/Tk/Event.pm +++ b/Master/tlpkg/tlperl/lib/Tk/Event.pm @@ -1,8 +1,8 @@ package Tk::Event; use vars qw($VERSION $XS_VERSION @EXPORT_OK); END { CleanupGlue() } -$VERSION = '4.030'; -$XS_VERSION = '804.032'; +$VERSION = '4.033'; +$XS_VERSION = '804.033'; $XS_VERSION =~ s{_}{}; use base qw(Exporter); use XSLoader; diff --git a/Master/tlpkg/tlperl/lib/Tk/Eventloop.pod b/Master/tlpkg/tlperl/lib/Tk/Eventloop.pod new file mode 100644 index 00000000000..a4c99e7988e --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Eventloop.pod @@ -0,0 +1,62 @@ + +=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 new file mode 100644 index 00000000000..dada482a761 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/FBox.pod @@ -0,0 +1,67 @@ +=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 new file mode 100644 index 00000000000..2ea633de674 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/FileSelect.pod @@ -0,0 +1,150 @@ + +=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 new file mode 100644 index 00000000000..be85105e475 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Font.pod @@ -0,0 +1,407 @@ +# 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::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 [2] 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 new file mode 100644 index 00000000000..6570b6a18c7 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Frame.pod @@ -0,0 +1,146 @@ +# 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 new file mode 100644 index 00000000000..0843e689843 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/HList.pod @@ -0,0 +1,1050 @@ +# 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 new file mode 100644 index 00000000000..2781d2e17e6 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/IO.pod @@ -0,0 +1,51 @@ + +=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 new file mode 100644 index 00000000000..e68324ce4b6 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/IconList.pod @@ -0,0 +1,82 @@ +=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 new file mode 100644 index 00000000000..797ecc23cbf --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Image.pod @@ -0,0 +1,145 @@ +# 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 new file mode 100644 index 00000000000..03a43b29ed7 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/InputO.pod @@ -0,0 +1,50 @@ +=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 new file mode 100644 index 00000000000..572abdf0f4f --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Internals.pod @@ -0,0 +1,142 @@ +=head1 NAME + +Tk::Internals - 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 new file mode 100644 index 00000000000..cf5cebf754a --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/LabFrame.pod @@ -0,0 +1,110 @@ +=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 new file mode 100644 index 00000000000..96386b09b5c --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Label.pod @@ -0,0 +1,133 @@ +# 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 new file mode 100644 index 00000000000..b904ad7775b --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Labelframe.pod @@ -0,0 +1,206 @@ +# 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 new file mode 100644 index 00000000000..ba00afe3ed9 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Listbox.pod @@ -0,0 +1,794 @@ +# 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/MMutil.pm b/Master/tlpkg/tlperl/lib/Tk/MMutil.pm index 7a78c1b7ebe..df5e9a26644 100644 --- a/Master/tlpkg/tlperl/lib/Tk/MMutil.pm +++ b/Master/tlpkg/tlperl/lib/Tk/MMutil.pm @@ -9,7 +9,7 @@ use Carp; use File::Basename; use vars qw($VERSION); -$VERSION = '4.025'; +$VERSION = '4.026'; # warn __FILE__." $VERSION\n"; @@ -115,19 +115,15 @@ sub mTk_CHO $self->{O_FILES} = [grep s/\.c(pp|xx|c)?$/$self->{OBJ_EXT}/i, @o_files] ; $self->{'MTK'} = $mTk; my $tk = installed_tk(); - my $perl = $self->{'PERL'}; - if ($IsWin32 && !-f $perl && -f "$perl.exe") - { - print "perl=$perl X=$^X\n"; - $perl = "$perl.exe"; - $self->{'PERL'} = $perl; - } + my $perl = $^X; foreach my $file (sort keys %$mTk) { unless (-f $file && -M $file < -M $mTk->{$file}) { warn "Extracting $file\n"; - system($perl,"$tk/pTk/Tcl-pTk",$mTk->{$file},$file); + my @cmd = ($perl,"$tk/pTk/Tcl-pTk",$mTk->{$file},$file); + system @cmd; + die "The command '@cmd' failed with $?" if $? != 0; } } } diff --git a/Master/tlpkg/tlperl/lib/Tk/MainWindow.pod b/Master/tlpkg/tlperl/lib/Tk/MainWindow.pod new file mode 100644 index 00000000000..565658adc1d --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/MainWindow.pod @@ -0,0 +1,85 @@ + +=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 new file mode 100644 index 00000000000..d76e7ef4b82 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Menu.pod @@ -0,0 +1,876 @@ +# 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<perlE<sol>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 new file mode 100644 index 00000000000..dabaadb8a58 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Menu/Item.pod @@ -0,0 +1,96 @@ + +=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 new file mode 100644 index 00000000000..fcda3e958aa --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Menubutton.pod @@ -0,0 +1,249 @@ +# 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 new file mode 100644 index 00000000000..9b0d67f3118 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Message.pod @@ -0,0 +1,151 @@ +# 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 new file mode 100644 index 00000000000..6f5536cf89c --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/MsgBox.pod @@ -0,0 +1,83 @@ + +=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 new file mode 100644 index 00000000000..e9c09cd0358 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Mwm.pod @@ -0,0 +1,109 @@ + +=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 new file mode 100644 index 00000000000..2cc84bb3fad --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/NoteBook.pod @@ -0,0 +1,235 @@ + +=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 new file mode 100644 index 00000000000..f5e514c63b3 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Optionmenu.pod @@ -0,0 +1,100 @@ + +=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 new file mode 100644 index 00000000000..673938d55e5 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Panedwindow.pod @@ -0,0 +1,326 @@ +# 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 new file mode 100644 index 00000000000..02a691d6261 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Photo.pod @@ -0,0 +1,475 @@ +# 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 new file mode 100644 index 00000000000..d0f36b00e65 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Pixmap.pod @@ -0,0 +1,64 @@ +# 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 new file mode 100644 index 00000000000..8d40a4ed275 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Popup.pod @@ -0,0 +1,89 @@ + +=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 new file mode 100644 index 00000000000..b442164ae72 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/ROText.pod @@ -0,0 +1,48 @@ + +=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 new file mode 100644 index 00000000000..4a1cee57d20 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Radiobutton.pod @@ -0,0 +1,333 @@ +# 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<perlE<sol>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<perlE<sol>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 new file mode 100644 index 00000000000..72f6f8c7b5e --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Scale.pod @@ -0,0 +1,356 @@ +# 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<perlE<sol>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 new file mode 100644 index 00000000000..838eb97e666 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Scrollbar.pod @@ -0,0 +1,429 @@ +# 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 new file mode 100644 index 00000000000..cd6c648ef5e --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Scrolled.pod @@ -0,0 +1,86 @@ +=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 new file mode 100644 index 00000000000..b18b7e1b9ae --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Spinbox.pod @@ -0,0 +1,819 @@ +# 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 new file mode 100644 index 00000000000..2a83334f8b2 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Submethods.pod @@ -0,0 +1,27 @@ + +=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/TList.pod b/Master/tlpkg/tlperl/lib/Tk/TList.pod new file mode 100644 index 00000000000..b8937fa8ef0 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/TList.pod @@ -0,0 +1,597 @@ +# 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 new file mode 100644 index 00000000000..02b6690b869 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Table.pod @@ -0,0 +1,102 @@ + +=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. + +The default focus traversal is giving the focus only to the table +widget as a whole. To enable focus traversal into table cells (e.g. if +there are embedded entry widgets), then the option C<-takefocus> has +to be set to C<0>. + +=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 new file mode 100644 index 00000000000..2310e0738e4 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Tcl-perl.pod @@ -0,0 +1,200 @@ +=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.pm b/Master/tlpkg/tlperl/lib/Tk/Text.pm index 2d87bbff49d..bef423c0afb 100644 --- a/Master/tlpkg/tlperl/lib/Tk/Text.pm +++ b/Master/tlpkg/tlperl/lib/Tk/Text.pm @@ -21,7 +21,7 @@ use Text::Tabs; use vars qw($VERSION); #$VERSION = sprintf '4.%03d', q$Revision: #24 $ =~ /\D(\d+)\s*$/; -$VERSION = '4.029'; +$VERSION = '4.030'; use Tk qw(Ev $XS_VERSION); use base qw(Tk::Clipboard Tk::Widget); @@ -61,6 +61,8 @@ sub bindRdOnly $mw->bind($class,'<Meta-B1-Motion>','NoOp'); $mw->bind($class,'<Meta-1>','NoOp'); $mw->bind($class,'<Alt-KeyPress>','NoOp'); + $mw->bind($class,'<Meta-KeyPress>','NoOp'); + $mw->bind($class,'<Control-KeyPress>','NoOp'); $mw->bind($class,'<Escape>','unselectAll'); $mw->bind($class,'<1>',['Button1',Ev('x'),Ev('y')]); diff --git a/Master/tlpkg/tlperl/lib/Tk/Text.pod b/Master/tlpkg/tlperl/lib/Tk/Text.pod new file mode 100644 index 00000000000..a069ee889a2 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Text.pod @@ -0,0 +1,2224 @@ +# 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<perlE<sol>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. + +=back + +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. + +=over 4 + +=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. + +=back + +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. + +=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 new file mode 100644 index 00000000000..2b9d98a3c4a --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/TextUndo.pod @@ -0,0 +1,73 @@ + +=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 new file mode 100644 index 00000000000..2db172ebaf1 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Tiler.pod @@ -0,0 +1,32 @@ + +=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 new file mode 100644 index 00000000000..93484db0076 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/TixGrid.pod @@ -0,0 +1,539 @@ +# 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/Tk.def b/Master/tlpkg/tlperl/lib/Tk/Tk.def deleted file mode 100755 index 4668be8d5c1..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Tk.def +++ /dev/null @@ -1,4 +0,0 @@ -EXPORTS - boot_Tk - _boot_Tk = boot_Tk - diff --git a/Master/tlpkg/tlperl/lib/Tk/Toplevel.pod b/Master/tlpkg/tlperl/lib/Tk/Toplevel.pod new file mode 100644 index 00000000000..e3bbf579c0b --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Toplevel.pod @@ -0,0 +1,199 @@ +# 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 new file mode 100644 index 00000000000..bbb14665008 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Tree.pod @@ -0,0 +1,274 @@ + +=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 Z<>* + +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 new file mode 100644 index 00000000000..caf34ece8d7 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/UserGuide.pod @@ -0,0 +1,586 @@ +=head1 NAME + +Tk::UserGuide - Writing Tk applications in Perl 5 + +=for category Introduction + +=head1 DESCRIPTION + +This document is for beginners. It assumes you know some B<Perl>, and +have it and Tk running. If you are I<not> currently reading this +document courtesy of the B<widget> demonstration program, please be +sure to run B<widget>, as it will show you the various widget types +supported by Tk and how to use them. B<widget> should be installed in +your default path, so type I<widget> at a command prompt. + +Here are links to other novice tutorials: + +L<http://www.lehigh.edu/~sol0/ptk/tpj1.html> +L<http://www.lehigh.edu/~sol0/ptk/perlmonth01/pm1.html> + +I<Mastering Perl/Tk> is the definitive book on Perl/Tk: + +L<http://www.oreilly.com/catalog/mastperltk> + +=head1 Some Background + +Tk GUI programming is event-driven. (This may already be familiar to +you.) In event-driven programs, the main GUI loop is outside of the +user program and inside the GUI library. This loop - initiated by +calling B<MainLoop> - watches all events of interest and activates +the correct handler procedures to handle these events. Some of these +handler procedures may be user-supplied; others will be part of the +library. + +For a programmer, this means that you're not watching what is happening; +instead, you are requested by the toolkit to perform actions whenever +necessary. +So, you're not watching for 'raise window / close window / redraw window' +requests, but you tell the toolkit which routine will handle such cases, +and the toolkit will call the procedures when required. These procedures +are known as I<callbacks>, and some of them you write yourself. + +=head1 First Requirements + +B<Perl> programs that use Tk need to include C<use Tk>. +A program should also use C<use strict> and the B<-w> switch to ensure +the program is working without common errors. + +Any Perl/Tk application starts by creating the Tk B<L<MainWindow|Tk::MainWindow>>. You +then create items inside the B<MainWindow>, and/or create new windows +called B<L<Toplevel|Tk::Toplevel>>s that also contain child items, before starting the +B<MainLoop>, which is the last logical statment in your program. You +can also create more items and windows while you're running, using +callbacks. Items are only shown on the display after they have been +arranged by a I<geometry manager> like B<L<pack|Tk::pack>>; more information on +this later. B<MainLoop> starts the GUI and handle all events. That's +all there is to it! A trivial one-window example is shown below: + + #!/usr/bin/perl -w + use Tk; + use strict; + + my $mw = MainWindow->new; + $mw->Label(-text => 'Hello, world!')->pack; + $mw->Button( + -text => 'Quit', + -command => sub { exit }, + )->pack; + MainLoop; + +Please run this example. It shows you two widget types, a B<L<Label|Tk::Label>> +and a B<L<Button|Tk::Button>>, and how they are packed. When clicked, the B<Button> +widget invokes the callback specified by the C<-command> option. Finally, +note the typical Tk style using C<-option> =E<gt> C<value> pairs. + +=head1 Widget creation + +Tk windows and widgets are hierarchical, S<i.e. one> window includes +one or more other windows. You create the first Tk window using +C<MainWindow-E<gt>new>. This returns a window handle, assigned to +C<$mw> in the example above. Keep track of the main handle, commonly +called a I<widget reference>. + +You can use any Tk handle to create child widgets within the window (or +widget). This is done by calling the Tk constructor method on the +variable. In the example above, the C<Label> method called from +C<$mw> creates a B<Label> widget inside the B<MainWindow>. In the +constructor call, you can specify various options; you can later add +or change options for any widget using the B<configure> method, which +takes the same parameters as the constructor. The one exception to +the hierarchical structure is the B<Toplevel> constructor, which +creates a new outermost window. + +After you create any widget (other than the B<MainWindow> or +B<Toplevel>s, you must render it by calling B<pack>. (This is not +entirely true; more later)). If you do not need to refer to the widget +after construction and packing, call B<pack> off the constructor +results, as shown for the B<Label> and B<Button> in the example above. Note +that the result of the compound call is the result of B<pack>, which +is a valid Tk handle. + +Windows and widgets are deleted by calling B<destroy> on them; +this will delete and un-draw the widget and all its children. + +=head1 Standard Tk widgets + +Here is an itemize of the standard Tk widget set. + +=over 4 + +=item L<Button|Tk::Button> + +=item L<Canvas|Tk::Canvas> + +=item L<Checkbutton|Tk::Checkbutton> + +=item L<Entry|Tk::Entry> + +=item L<Frame|Tk::Frame> + +=item L<Label|Tk::Label> + +=item L<Labelframe|Tk::Labelframe> + +=item L<Listbox|Tk::Listbox> + +=item L<Menu|Tk::Menu> + +=item L<Menubutton|Tk::Menubutton> + +=item L<Message|Tk::Message> + +=item L<Panedwindow|Tk::Panedwindow> + +=item L<Radiobutton|Tk::Radiobutton> + +=item L<Scale|Tk::Scale> + +=item L<Scrollbar|Tk::Scrollbar> + +=item L<Spinbox|Tk::Spinbox> + +=item L<Text|Tk::Text> + +=item L<Toplevel|Tk::Toplevel> + +=back + +Perl/Tk provides an equal number of new widgets, above and beyond this +core set. + +=over 4 + +=item L<Adjuster|Tk::Adjuster> + +=item L<Balloon|Tk::Balloon> + +=item L<BrowseEntry|Tk::BrowseEntry> + +=item L<ColorEditor|Tk::ColorEditor> + +=item L<Dialog|Tk::Dialog> + +=item L<DialogBox|Tk::DialogBox> + +=item L<DirTree|Tk::DirTree> + +=item ErrorDialog + +=item L<FBox|Tk::FBox> + +=item L<FileSelect|Tk::FileSelect> + +=item L<HList|Tk::HList> + +=item LabEntry + +=item L<LabFrame|Tk::LabFrame> + +=item L<NoteBook|Tk::NoteBook> + +=item L<Optionmenu|Tk::Optionmenu> + +=item L<Pane|Tk::Pane> + +=item L<ProgressBar|Tk::ProgressBar> + +=item L<ROText|Tk::ROText> + +=item L<Table|Tk::Table> + +=item L<TextUndo|Tk::TextUndo> + +=item L<Tiler|Tk::Tiler> + +=item L<TList|Tk::TList> + +=item L<Tree|Tk::Tree> + +=back + +=head1 Variables and callback routines + +Most graphical interfaces are used to set up a set of values and conditions, +and then perform the appropriate action. The Tk toolkit is different +from your average text-based prompting or menu driven system in that you do +not collect settings yourself, and decide on an action based on an +input code; instead, you leave these +values to your toolkit and only get them when the action is performed. + +So, where a traditional text-based system would look like this: + + #!/usr/bin/perl -w + use strict; + + print "Please type a font name\n"; + my $font = <>; chomp $font; + # Validate font + + print "Please type a file name\n"; + my $filename = <>; chomp $filename; + # Validate filename + + print "Type <1> to fax, <2> to print\n"; + my $option = <>; chomp $option; + if ($option eq 1) { + print "Faxing $filename in font $font\n"; + } elsif ($option eq 2) { + print "Now sending $filename to printer in font $font\n"; + } + +The slightly larger example below shows how to do this in Tk. +Note the use of callbacks. Note, also, that Tk handles the values, and +the subroutine uses the method B<get> to get at the values. +If a user changes his mind and wants to change the font again, +the application never notices; it's all handled by Tk. + + #!/usr/bin/perl -w + use Tk; + use strict; + + my $mw = MainWindow->new; + + $mw->Label(-text => 'File Name')->pack; + my $filename = $mw->Entry(-width => 20); + $filename->pack; + + $mw->Label(-text => 'Font Name')->pack; + my $font = $mw->Entry(-width => 10); + $font->pack; + + $mw->Button( + -text => 'Fax', + -command => sub{do_fax($filename, $font)} + )->pack; + + $mw->Button( + -text => 'Print', + -command => sub{do_print($filename, $font)} + )->pack; + + MainLoop; + + sub do_fax { + my ($file, $font) = @_; + my $file_val = $file->get; + my $font_val = $font->get; + print "Now faxing $file_val in font $font_val\n"; + } + + sub do_print { + my ($file, $font) = @_; + my $file_val = $file->get; + my $font_val = $font->get; + print "Sending file $file_val to printer in font $font_val\n"; + } + +=head1 The packer - grouping with Frame widgets + +In the examples above, you must have noticed the B<pack> calls. This +is one of the more complicated parts of Tk. The basic idea is that +any window or widget should be subject to a Tk geometry manager; the +I<packer> is one of the placement managers, and B<L<grid|Tk::grid>> is another. + +The actions of the packer are rather simple: when applied +to a widget, the packer positions that widget on the indicated position +within the remaining space in its parent. By default, the position is +on top; this means the next items will be put below. You can also +specify the left, right, or bottom positions. Specify position +using B<-side =E<gt> 'right'>. + +Additional packing parameters specify the behavior of the widget when +there is some space left in the B<L<Frame|Tk::Frame>> or when the window size is +increased. If widgets should maintain a fixed size, specify nothing; +this is the default. For widgets that you want to fill up the current +horizontal and/or vertical space, specify B<-fill =E<gt> 'x'>, B<'y'>, +or B<'both'>; for widgets that should grow, specify B<-expand =E<gt> 1>. +These parameters are not shown in the example below; see the B<widget> +demonstration. + +If you want to group some items within a window that have a different +packing order than others, you can include them in a Frame. This is a +do-nothing window type that is meant for packing or filling (and to +play games with borders and colors). + +The example below shows the use of pack and Frames: + + #!/usr/bin/perl -w + use Tk; + use strict; + + # Take top and the bottom - now implicit top is in the middle + my $mw = MainWindow->new; + $mw->title( 'The MainWindow' ); + $mw->Label(-text => 'At the top (default)')->pack; + $mw->Label(-text => 'At the bottom')->pack(-side => 'bottom'); + $mw->Label(-text => 'The middle remains')->pack; + + # Since left and right are taken, bottom will not work... + my $top1 = $mw->Toplevel; + $top1->title( 'Toplevel 1' ); + $top1->Label(-text => 'Left')->pack(-side => 'left'); + $top1->Label(-text => 'Right')->pack(-side => 'right'); + $top1->Label(-text => '?Bottom?')->pack(-side => 'bottom'); + + # But when you use Frames, things work quite alright + my $top2 = $mw->Toplevel; + $top2->title( 'Toplevel 2' ); + my $frame = $top2->Frame; + $frame->pack; + $frame->Label(-text => 'Left2')->pack(-side => 'left'); + $frame->Label(-text => 'Right2')->pack(-side => 'right'); + $top2->Label(-text => 'Bottom2')->pack(-side => 'bottom'); + + MainLoop; + +=head1 More than one window + +Most real applications require more than one window. As you just saw, +you can create more outermost windows by using a B<Toplevel> widget. +Each window is independent; destroying a B<Toplevel> window does not +affect the others as long as they are not a child of the closed +B<Toplevel>. However, exiting the B<MainWindow> will destroy all remaining +B<Toplevel> widgets and end the application. The +example below shows a trivial three-window application: + + #!/usr/bin/perl -w + use Tk; + use strict; + + my $mw = MainWindow->new; + fill_window($mw, 'Main'); + my $top1 = $mw->Toplevel; + fill_window($top1, 'First top-level'); + my $top2 = $mw->Toplevel; + fill_window($top2, 'Second top-level'); + MainLoop; + + sub fill_window { + my ($window, $header) = @_; + $window->Label(-text => $header)->pack; + $window->Button( + -text => 'close', + -command => [$window => 'destroy'] + )->pack(-side => 'left'); + $window->Button( + -text => 'exit', + -command => [$mw => 'destroy'] + )->pack(-side => 'right'); + } + +=head1 More callbacks + +So far, all callback routines shown called a user procedure. +You can also have a callback routine call another Tk routine. +This is the way that scroll bars are implemented: scroll-bars +can call a Tk item or a user procedure, whenever their position +has changed. The Tk item that has a scrollbar attached calls the +scrollbar when its size or offset has changed. In this way, +the items are linked. You can still ask a scrollbar's position, +or set it by hand - but the defaults will be taken care of. + +The example below shows a B<L<Listbox|Tk::Listbox>> with a scroll bar. Moving +the scrollbar moves the B<Listbox>. Scanning a B<Listbox> (dragging +an item with the left mouse button) moves the scrollbar. + + #!/usr/bin/perl -w + use Tk; + use strict; + + my $mw = MainWindow->new; + my $box = $mw->Listbox( + -relief => 'sunken', + -height => 5, + -setgrid => 1, + ); + my @items = qw(One Two Three Four Five Six Seven + Eight Nine Ten Eleven Twelve); + foreach (@items) { + $box->insert('end', $_); + } + my $scroll = $mw->Scrollbar(-command => ['yview', $box]); + $box->configure(-yscrollcommand => ['set', $scroll]); + $box->pack(-side => 'left', -fill => 'both', -expand => 1); + $scroll->pack(-side => 'right', -fill => 'y'); + + MainLoop; + +Note that there's a convenience method B<L<Scrolled|Tk::Scrolled>> +which helps constructing widgets with automatically managed +scrollbars. + +=head1 Canvases and tags + +One of the most powerful widgets in Tk is the B<L<Canvas|Tk::Canvas>> window. +In a B<Canvas> window, you can draw simple graphics and include +other widgets. The B<Canvas> area may be larger than the visible window, +and may then be scrolled. Any item you draw on the canvas has its own id, +and may optionally have one or more I<tags>. You may refer to any +item by its id, and may refer to any group of items by a common tag; +you can move, delete, or change groups of items using these tags, +and you can I<bind> actions to tags. For a properly designed (often +structured) B<Canvas>, you can specify powerful actions quite simply. + +In the example below, actions are bound to circles (single click) +and blue items (double-click); obviously, this can be extended to any +tag or group of tags. + + #!/usr/bin/perl -w + use Tk; + use strict; + + # Create B<MainWindow> and canvas + my $mw = MainWindow->new; + my $canvas = $mw->Canvas; + $canvas->pack(-expand => 1, -fill => 'both'); + + # Create various items + create_item($canvas, 1, 1, 'circle', 'blue', 'Jane'); + create_item($canvas, 4, 4, 'circle', 'red', 'Peter'); + create_item($canvas, 4, 1, 'square', 'blue', 'James'); + create_item($canvas, 1, 4, 'square', 'red', 'Patricia'); + + # Single-clicking with left on a 'circle' item invokes a procedure + $canvas->bind('circle', '<1>' => sub {handle_circle($canvas)}); + # Double-clicking with left on a 'blue' item invokes a procedure + $canvas->bind('blue', '<Double-1>' => sub {handle_blue($canvas)}); + MainLoop; + + # Create an item; use parameters as tags (this is not a default!) + sub create_item { + my ($can, $x, $y, $form, $color, $name) = @_; + + my $x2 = $x + 1; + my $y2 = $y + 1; + my $kind; + $kind = 'oval' if ($form eq 'circle'); + $kind = 'rectangle' if ($form eq 'square'); + $can->create( + ($kind, "$x" . 'c', "$y" . 'c', + "$x2" . 'c', "$y2" . 'c'), + -tags => [$form, $color, $name], + -fill => $color); + } + + # This gets the real name (not current, blue/red, square/circle) + # Note: you'll want to return a list in realistic situations... + sub get_name { + my ($can) = @_; + my $item = $can->find('withtag', 'current'); + my @taglist = $can->gettags($item); + my $name; + foreach (@taglist) { + next if ($_ eq 'current'); + next if ($_ eq 'red' or $_ eq 'blue'); + next if ($_ eq 'square' or $_ eq 'circle'); + $name = $_; + last; + } + return $name; + } + + sub handle_circle { + my ($can) = @_; + my $name = get_name($can); + print "Action on circle $name...\n"; + } + + sub handle_blue { + my ($can) = @_; + my $name = get_name($can); + print "Action on blue item $name...\n"; + } + +=head1 Perl/Tk and Unicode + +Perl/Tk follows Perl's model of handling Unicode. That is, if a string +is correctly flagged as a E<quot>characterE<quot> string in the sense +like described in L<Encode/TERMINOLOGY>, then Perl/Tk will very +probably display and handle this string correctly. + +Note that every variable which is passed somehow into a Perl/Tk method +will be implicitely changed into an internally utf8-flagged variable. +Semantically nothing changes, as the series of codepoints stays the +same, but things will change when variables with high-bit iso-8859-1 +characters will be passed to the "outer" world. In this case you have +to explicitely mark the encoding of your output stream if using IO, or +encode the variables using L<Encode> for other style of communication. + +This is the theory, now some examples. + +If you use non-iso-8859-1 characters in the source code, then use +either the C<use utf8;> or C<use encoding 'I<encodingname>'> pragma: + + use utf8; + use Tk; + my $x = "some characters using utf8 encoding"; + tkinit->Label(-text => $x)->pack; + MainLoop; + +For data that comes from a file you have to specify the encoding +unless it's encoded as ascii or iso-8559-1: + + use Tk; + open my $FH, "<:encoding(utf-8)", "filename" or die $!; + # or for utf-16 data: open my $FH, "<:encoding(utf-16)", "filename" or die $!; + my $data = <$FH>; + tkinit->Label(-text => $data)->pack; + MainLoop; + +Likewise, the encoding must be specified for all data which is read +from Tk widgets and that shall be output into a file. For the output, +the encoding should be always specified, even if it is iso-8859-1: + + use Tk; + $mw = tkinit; + $mw->Entry(-textvariable => \$input)->pack; + $mw->Button( + -text => "Write to file", + -command => sub { + open my $FH, ">:encoding(iso-8859-1)", "filename" or die $!; + print $FH $input; + }, + )->pack; + MainLoop; + +Note that Tk is Unicode-capable. So you need to be prepared that the +user has the appropriate input methods activated to enter non-ascii +characters. If an output encoding is used which does not cover the +whole of Unicode codepoints then a warning will be issued when writing +the file, like this: + + "\x{20ac}" does not map to iso-8859-1 at /usr/local/lib/perl5/site_perl/5.8.8/mach/Tk.pm line 250. + +Also, the same hexadecimal notation will be used as replacements for +the unhandled characters. + +Handling encoding in I/O is pretty simple using the C<encoding> PerlIO +layer, as described above. In other cases, such as when dealing with +databases, encoding the data usually has to be done manually, unless +the database driver has some means for automatically do this for you. +So when working with a MySQL database, one could use: + + use Tk; + use DBI; + use Encode qw(encode); + $mw = tkinit; + $mw->Entry(-textvariable => \$input)->pack; + $mw->Button( + -text => "Write to database", + -command => sub { + my $dbh = DBI->connect("dbi:mysql:test", "root", "") or die; + my $encoded_input = encode("iso-8859-1", $input); + $dbh->do("INSERT INTO testtable VALUES (?)", undef, $encoded_input) or die; + }, + )->pack; + MainLoop; + +Unfortunately, there are still places in Perl ignorant of Unicode. One +of these places are filenames. Consequently, the file selectors in +Perl/Tk do not handle encoding of filenames properly. Currently they +suppose that filenames are in iso-8859-1 encoding, at least on Unix +systems. As soon as Perl has a concept of filename encodings, then +Perl/Tk will also implement such schemes. + +=cut diff --git a/Master/tlpkg/tlperl/lib/Tk/Widget.pm b/Master/tlpkg/tlperl/lib/Tk/Widget.pm index 96cd136b245..62cb5c44afb 100644 --- a/Master/tlpkg/tlperl/lib/Tk/Widget.pm +++ b/Master/tlpkg/tlperl/lib/Tk/Widget.pm @@ -3,7 +3,7 @@ # modify it under the same terms as Perl itself. package Tk::Widget; use vars qw($VERSION @DefaultMenuLabels); -$VERSION = '4.035'; # was: sprintf '4.%03d', q$Revision: #30 $ =~ /\D(\d+)\s*$/; +$VERSION = '4.036'; # was: sprintf '4.%03d', q$Revision: #30 $ =~ /\D(\d+)\s*$/; require Tk; use AutoLoader; @@ -1475,9 +1475,9 @@ sub bindDump { } } elsif ($callback =~ /ARRAY/) { if (ref $callback->[0]) { - push @out, sprintf( "%s %s\n", ' ' x $spc1, $callback->[0], "\n" ); + push @out, sprintf( "%s %s\n", ' ' x $spc1, $callback->[0] ); } else { - push @out, sprintf( "%s '%s'\n", ' ' x $spc1, $callback->[0], "\n" ); + push @out, sprintf( "%s '%s'\n", ' ' x $spc1, $callback->[0] ); } foreach my $arg (@$callback[1 .. $#$callback]) { if (ref $arg) { diff --git a/Master/tlpkg/tlperl/lib/Tk/Widget.pod b/Master/tlpkg/tlperl/lib/Tk/Widget.pod new file mode 100644 index 00000000000..696bbab22b7 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Widget.pod @@ -0,0 +1,678 @@ +# 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 new file mode 100644 index 00000000000..edc00001a23 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/WidgetDemo.pod @@ -0,0 +1,59 @@ + +=head1 NAME + +Tk::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 new file mode 100644 index 00000000000..0cbb7f1b695 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Wm.pod @@ -0,0 +1,669 @@ +# 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 a list of two elements: the window id of the wrapper window in +which Tk has placed I<$toplevel>, and the height of the menu bar. The +id is the one by which window manager will know I<$toplevel>, and so +is appropriate place to add X properties. The menu height is only +returned on X. On Windows, this value is always zero. + +=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 new file mode 100644 index 00000000000..e6c7614a72c --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/X.pod @@ -0,0 +1,373 @@ + +=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 new file mode 100644 index 00000000000..bd5b353abe0 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/X11Font.pod @@ -0,0 +1,88 @@ + +=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 new file mode 100644 index 00000000000..55f885bc849 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Xrm.pod @@ -0,0 +1,45 @@ + +=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 new file mode 100644 index 00000000000..97c61ba380b --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/after.pod @@ -0,0 +1,168 @@ +# 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 new file mode 100644 index 00000000000..f595a48e318 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/bind.pod @@ -0,0 +1,583 @@ +# 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 new file mode 100644 index 00000000000..3ee6ddb9473 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/bindtags.pod @@ -0,0 +1,107 @@ +# 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 new file mode 100644 index 00000000000..5b62cb7c12c --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/callbacks.pod @@ -0,0 +1,104 @@ +# $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 new file mode 100644 index 00000000000..62c2906e77a --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/chooseColor.pod @@ -0,0 +1,64 @@ +# 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::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 new file mode 100644 index 00000000000..71dc7233902 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/chooseDirectory.pod @@ -0,0 +1,95 @@ +# 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 + +Tk::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 new file mode 100644 index 00000000000..c1dda4dbd19 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/composite.pod @@ -0,0 +1,171 @@ +# $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/demos/widget_lib/HList.pl b/Master/tlpkg/tlperl/lib/Tk/demos/widget_lib/HList.pl index 62d683b2dbb..64330be358a 100644 --- a/Master/tlpkg/tlperl/lib/Tk/demos/widget_lib/HList.pl +++ b/Master/tlpkg/tlperl/lib/Tk/demos/widget_lib/HList.pl @@ -25,7 +25,7 @@ sub HList { $FOLDIMG = $TOP->Bitmap(-file => Tk->findINC('folder.xbm')); my $root = Tk->findINC('demos'); - my $olddir = cwd; + my $olddir = getcwd; chdir $root; show_dir '.', $root, $h; chdir $olddir; diff --git a/Master/tlpkg/tlperl/lib/Tk/event.pod b/Master/tlpkg/tlperl/lib/Tk/event.pod new file mode 100644 index 00000000000..9012a596267 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/event.pod @@ -0,0 +1,417 @@ +# 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 new file mode 100644 index 00000000000..bb564cd0b82 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/exit.pod @@ -0,0 +1,42 @@ +# 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 new file mode 100644 index 00000000000..1a98cfd6b71 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/fileevent.pod @@ -0,0 +1,112 @@ +# 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 new file mode 100644 index 00000000000..d7e610d5d20 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/focus.pod @@ -0,0 +1,166 @@ +# 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::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 new file mode 100644 index 00000000000..64208c8e26e --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/form.pod @@ -0,0 +1,397 @@ +# 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 new file mode 100644 index 00000000000..828634bdf34 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/getOpenFile.pod @@ -0,0 +1,182 @@ +# 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::getOpenFile, Tk::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 new file mode 100644 index 00000000000..d74ee7da502 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/grab.pod @@ -0,0 +1,140 @@ +# 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::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 new file mode 100644 index 00000000000..8db89587a62 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/grid.pod @@ -0,0 +1,409 @@ +# 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 new file mode 100644 index 00000000000..76e40e7891f --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/mega.pod @@ -0,0 +1,423 @@ + +## 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 new file mode 100644 index 00000000000..36c147b1180 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/messageBox.pod @@ -0,0 +1,67 @@ +=head1 NAME + +Tk::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 new file mode 100644 index 00000000000..9ee206bf9ed --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/option.pod @@ -0,0 +1,217 @@ +# 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::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 new file mode 100644 index 00000000000..49d81ddd2b4 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/options.pod @@ -0,0 +1,787 @@ +# 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 new file mode 100644 index 00000000000..62e6b193a31 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/overview.pod @@ -0,0 +1,138 @@ + +=head1 NAME + +Tk::overview - 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 new file mode 100644 index 00000000000..6e1a2a04022 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/pTk.pod @@ -0,0 +1,550 @@ +=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 new file mode 100644 index 00000000000..0449556265c --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/pack.pod @@ -0,0 +1,324 @@ +# 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 new file mode 100644 index 00000000000..35a6ca0a40b --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/palette.pod @@ -0,0 +1,89 @@ +# 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 + +Tk::palette - 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 new file mode 100644 index 00000000000..9f7e74f210f --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/place.pod @@ -0,0 +1,283 @@ +# 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 new file mode 100644 index 00000000000..f8a3ce54856 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/selection.pod @@ -0,0 +1,159 @@ +# 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 new file mode 100644 index 00000000000..4a6e41e4c1e --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/send.pod @@ -0,0 +1,118 @@ +# 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::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 new file mode 100644 index 00000000000..9bdd02d461c --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/tixWm.pod @@ -0,0 +1,73 @@ + + +=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 new file mode 100644 index 00000000000..534fd3cd933 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/tkvars.pod @@ -0,0 +1,107 @@ +# 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::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 new file mode 100644 index 00000000000..114f52505d7 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/widgets.pod @@ -0,0 +1,20 @@ + +=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 + |