diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/Balloon.pod')
| -rwxr-xr-x | Master/tlpkg/tlperl/lib/Tk/Balloon.pod | 282 |
1 files changed, 0 insertions, 282 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/Balloon.pod b/Master/tlpkg/tlperl/lib/Tk/Balloon.pod deleted file mode 100755 index c5afb91e089..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Balloon.pod +++ /dev/null @@ -1,282 +0,0 @@ - -=head1 NAME - -Tk::Balloon - pop up help balloons. - -=for pm Tixish/Balloon.pm - -=for category Tix Extensions - -=head1 SYNOPSIS - - use Tk::Balloon; - ... - $b = $top->Balloon(-statusbar => $status_bar_widget); - - # Normal Balloon: - $b->attach($widget, - -balloonmsg => "Balloon help message", - -statusmsg => "Status bar message"); - - # Balloon attached to entries in a menu widget: - $b->attach($menu, -state => 'status', - -msg => ['first menu entry', - 'second menu entry', - ... - ], - ); - - # Balloon attached to individual items in a canvas widget: - $b->attach($canvas, -balloonposition => 'mouse', - -msg => {'item1' => 'msg1', - 'tag2' => 'msg2', - ... - }, - ); - - # Balloon attached to items in a listbox widget: - $b->attach($listbox, -balloonposition => 'mouse', - -msg => ['first listbox element', - '2nd listbox element', - ... - ], - ); - -=head1 DESCRIPTION - -B<Balloon> provides the framework to create and attach help -balloons to various widgets so that when the mouse pauses over the -widget for more than a specified amount of time, a help balloon is -popped up. - -=head2 Balloons and Menus or Listboxes - -If the balloon is attached to a B<Menu> or B<Listbox> widget and the -message arguments are array references, then each element in the array -will be the message corresponding to a menu entry or listbox element. -The balloon message will then be shown for the entry which the mouse -pauses over. Otherwise it is assumed that the balloon is to be -attached to the B<Menu> or B<Listbox> as a whole. You can have -separate status and balloon messages just like normal balloons. - -=head2 Balloons and Canvases - -If the balloon is attached to a B<Canvas> widget and the message -arguments are hash references, then each hash key should correspond to -a canvas item ID or tag and the associated value will correspond to the -message for that canvas item. The balloon message will then be shown for -the current item (the one at the position of the mouse). Otherwise it is -assumed that the balloon is to be attached to the B<Canvas> as a whole. -You can have separate status and balloon messages just like normal -balloons. - -=head2 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 - - |