👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

CentOS 7.0 - man page for tk::balloon (centos section 3)

Balloon(3)		       User Contributed Perl Documentation		       Balloon(3)

NAME
       Tk::Balloon - pop up help balloons.

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',
					 ...
					],
		     );

DESCRIPTION
       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.

   Balloons and Menus or Listboxes
       If the balloon is attached to a Menu or 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 Menu
       or Listbox as a whole. You can have separate status and balloon messages just like normal
       balloons.

   Balloons and Canvases
       If the balloon is attached to a 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 Canvas as a whole.  You can have
       separate status and balloon messages just like normal balloons.

   Balloons and HLists
       If the balloon is attached to a 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 HList as a whole.  You can have separate status and
       balloon messages just like normal balloons.

   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.

OPTIONS
       Balloon accepts all of the options that the Frame widget accepts. In addition, the
       following options are also recognized.

       -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.

       -state
	   Can be one of 'balloon', 'status', 'both' or '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 'both'.

       -statusbar
	   Specifies the widget used to display the status message. This widget should accept the
	   -text option and is typically a Label. If the widget accepts the -textvariable option
	   and that option is defined then it is used instead of the -text option.

       -balloonposition
	   Can be one of 'widget' or 'mouse'. It controls where the balloon will popup. 'widget'
	   makes the balloon appear at the lower right corner of the widget it is attached to
	   (default), and 'mouse' makes the balloon appear below and to the right of the current
	   mouse position.

       -postcommand
	   This option takes a 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 X,Y (matches this
	   regular expression: "/^(\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. Warning: this subroutine should return quickly or the balloon response will
	   appear slow.

       -cancelcommand
	   This option takes a 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. Warning: this subroutine should
	   return quickly or the balloon response will appear slow.

       -motioncommand
	   This option takes a 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.	Note: a new balloon may be posted after the -initwait time
	   interval, use the -postcommand option to control that behavior.  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).

       -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.

METHODS
       The Balloon widget supports only three non-standard methods:

   attach(widget, options)
       Attaches the widget indicated by widget to the help system. The allowed options are:

       -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 -msg is specified then the message
	   displayed on the status bar is the same as the argument for -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.

       -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 -statusmsg if this is not specified, then
	   it takes its value from the -msg specification if any. If neither -balloonmsg nor -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.

       -msg
	   The catch-all for -statusmsg and -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.

       -initwait
       -state
       -statusbar
       -balloonposition
       -postcommand
       -cancelcommand
       -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 Balloon's value.

   detach(widget)
       Detaches the specified widget from the help system.

   destroy
       Destroys the specified balloon.

ADVERTISED SUBWIDGETS
       The balloon label is advertised as "message".

EXAMPLES
       See the balloon demo included with the widget demo script that came with the distribution
       for examples on various ways to use balloons.

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.

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.

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 => ...);

AUTHORS
       Rajappa Iyer <rsi@earthling.net> did the original coding.

       Jason A. Smith <smithj4@rpi.edu> added support for menus and made some other enhancements.

       Slaven Rezic <srezic@cpan.org> added support for canvas items.

       Gerhard Petrowitsch <gerhard@petrowitsch.de> added intelligent positioning

       Jack Dunnigan <dunniganj@cpan.org> Made positioning more intelligent and added support for
       multiple monitors under single logical screen.

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.

perl v5.16.3				    2014-06-10				       Balloon(3)


All times are GMT -4. The time now is 12:05 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password