commit more files of the tlperl.straw dir, still not complete

git-svn-id: svn://tug.org/texlive/trunk@17244 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 282 insertions, 0 deletions

diff --git a/Master/tlpkg/tlperl.straw/lib/Tk/Balloon.pod b/Master/tlpkg/tlperl.straw/lib/Tk/Balloon.pod
new file mode 100755
index 00000000000..c5afb91e089
--- /dev/null
+++ b/Master/tlpkg/tlperl.straw/lib/Tk/Balloon.pod
@@ -0,0 +1,282 @@
+
+=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 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
+
+