home *** CD-ROM | disk | FTP | other *** search
/ Australian Personal Computer 2004 July / APC0407D2.iso / workshop / apache / files / ActivePerl-5.6.1.638-MSWin32-x86.msi / _5038fa87bbb3b3b86ad8596bebfdc87c < prev    next >
Encoding:
Text File  |  2004-04-13  |  8.2 KB  |  244 lines
  1.  
  2. =head1 NAME
  3.  
  4. Tk::Balloon - pop up help balloons.
  5.  
  6. =for pm Tixish/Balloon.pm
  7.  
  8. =for category Tix Extensions
  9.  
  10. =head1 SYNOPSIS
  11.  
  12.     use Tk::Balloon;
  13.     ...
  14.     $b = $top->Balloon(-statusbar => $status_bar_widget);
  15.  
  16.     # Normal Balloon:
  17.     $b->attach($widget,
  18.            -balloonmsg => "Balloon help message",
  19.            -statusmsg => "Status bar message");
  20.  
  21.     # Balloon attached to entries in a menu widget:
  22.     $b->attach($menu, -state => 'status',
  23.               -msg => ['first menu entry',
  24.                    'second menu entry',
  25.                    ...
  26.                   ],
  27.           );
  28.  
  29.     # Balloon attached to individual items in a canvas widget:
  30.     $b->attach($canvas, -balloonposition => 'mouse',
  31.             -msg => {'item1' => 'msg1',
  32.                  'tag2'  => 'msg2',
  33.                   ...
  34.                 },
  35.           );
  36.  
  37. =head1 DESCRIPTION
  38.  
  39. B<Balloon> provides the framework to create and attach help
  40. balloons to various widgets so that when the mouse pauses over the
  41. widget for more than a specified amount of time, a help balloon is
  42. popped up.
  43.  
  44. =head2 Balloons and Menus
  45.  
  46. If the balloon is attached to a B<Menu> widget and the message arguments
  47. are array references, then each element in the array will be the
  48. message corresponding to a menu entry. The balloon message will then
  49. be shown for the entry which the mouse pauses over. Otherwise it is
  50. assumed that the balloon is to be attached to the B<Menu> as a whole.
  51. You can have separate status and balloon messages just like normal
  52. balloons.
  53.  
  54. =head2 Balloons and Canvases
  55.  
  56. If the balloon is attached to a B<Canvas> widget and the message
  57. arguments are hash references, then each hash key should correspond to
  58. a canvas item ID or tag and the associated value will correspond to the
  59. message for that canvas item. The balloon message will then be shown for
  60. the current item (the one at the position of the mouse). Otherwise it is
  61. assumed that the balloon is to be attached to the B<Canvas> as a whole.
  62. You can have separate status and balloon messages just like normal
  63. balloons.
  64.  
  65. =head1 OPTIONS
  66.  
  67. B<Balloon> accepts all of the options that the B<Frame> widget
  68. accepts. In addition, the following options are also recognized.
  69.  
  70. =over 4
  71.  
  72. =item B<-initwait>
  73.  
  74. Specifies the amount of time to wait without activity before
  75. popping up a help balloon. Specified in milliseconds. Defaults to
  76. 350 milliseconds. This applies to both the popped up balloon and
  77. the status bar message.
  78.  
  79. =item B<-state>
  80.  
  81. Can be one of B<'balloon'>, B<'status'>, B<'both'> or B<'none'>
  82. indicating that the help balloon, status bar help, both or none
  83. respectively should be activated when the mouse pauses over the
  84. client widget. Default is B<'both'>.
  85.  
  86. =item B<-statusbar>
  87.  
  88. Specifies the widget used to display the status message. This
  89. widget should accept the B<-text> option and is typically a
  90. B<Label>. If the widget accepts the B<-textvariable> option and
  91. that option is defined then it is used instead of the B<-text>
  92. option.
  93.  
  94. =item B<-balloonposition>
  95.  
  96. Can be one of B<'widget'> or B<'mouse'>. It controls where the balloon
  97. will popup. B<'widget'> makes the balloon appear at the lower right
  98. corner of the widget it is attached to (default), and B<'mouse'> makes
  99. the balloon appear below and to the right of the current mouse position.
  100.  
  101. =item B<-postcommand>
  102.  
  103. This option takes a B<CODE> reference which will be executed before the
  104. balloon and statusbar messages are displayed and should return a true
  105. or false value to indicate whether you want the balloon to be displayed
  106. or not. This also lets you control where the balloon is positioned by
  107. returning a true value that looks like I<X,Y> (matches this regular
  108. expression: C</^(\d+),(\d+)$/>). If the postcommand returns a value that
  109. matches that re then those coordinates will be used as the position to
  110. post the balloon. I<Warning:> this subroutine should return quickly or
  111. the balloon response will appear slow.
  112.  
  113. =item B<-cancelcommand>
  114.  
  115. This option takes a B<CODE> reference which will be executed before the
  116. balloon and statusbar messages are canceled and should return a true
  117. or false value to indicate whether you want the balloon to be canceled
  118. or not. I<Warning:> this subroutine should return quickly or the balloon
  119. response will appear slow.
  120.  
  121. =item B<-motioncommand>
  122.  
  123. This option takes a B<CODE> reference which will be executed for any
  124. motion event and should return a true or false value to indicate
  125. whether the currently displayed balloon should be canceled (deactivated).
  126. If it returns true then the balloon will definitely be canceled, if it
  127. returns false then it may still be canceled depending the internal rules.
  128. I<Note:> a new balloon may be posted after the B<-initwait> time
  129. interval, use the B<-postcommand> option to control that behavior.
  130. I<Warning:> the subroutine should be extremely fast or the balloon
  131. response will appear slow and consume a lot of CPU time (it is executed
  132. every time the mouse moves over the widgets the balloon is attached to).
  133.  
  134. =back
  135.  
  136. =head1 METHODS
  137.  
  138. The B<Balloon> widget supports only three non-standard methods:
  139.  
  140. =head2 B<attach(>I<widget>, I<options>B<)>
  141.  
  142. Attaches the widget indicated by I<widget> to the help system. The
  143. allowed options are:
  144.  
  145. =over 4
  146.  
  147. =item B<-statusmsg>
  148.  
  149. The argument is the message to be shown on the status bar when the
  150. mouse pauses over this client. If this is not specified, but
  151. B<-msg> is specified then the message displayed on the status bar
  152. is the same as the argument for B<-msg>. If you give it a scalar
  153. reference then it is dereferenced before being displayed. Useful
  154. if the postcommand is used to change the message.
  155.  
  156. =item B<-balloonmsg>
  157.  
  158. The argument is the message to be displayed in the balloon that
  159. will be popped up when the mouse pauses over this client. As with
  160. B<-statusmsg> if this is not specified, then it takes its value
  161. from the B<-msg> specification if any. If neither B<-balloonmsg>
  162. nor B<-msg> are specified, or they are the empty string then
  163. no balloon is popped up instead of an empty balloon. If you
  164. give it a scalar reference then it is dereferenced before being
  165. displayed. Useful if the postcommand is used to change the message.
  166.  
  167. =item B<-msg>
  168.  
  169. The catch-all for B<-statusmsg> and B<-balloonmsg>. This is a
  170. convenient way of specifying the same message to be displayed in
  171. both the balloon and the status bar for the client.
  172.  
  173. =item B<-initwait>
  174.  
  175. =item B<-state>
  176.  
  177. =item B<-statusbar>
  178.  
  179. =item B<-balloonposition>
  180.  
  181. =item B<-postcommand>
  182.  
  183. =item B<-cancelcommand>
  184.  
  185. =item B<-motioncommand>
  186.  
  187. These options allow you to override the balloon's default value for
  188. those option for some of the widgets it is attached to. It accepts the
  189. same values as above and will default to the B<Balloon>'s value.
  190.  
  191. =back
  192.  
  193. =head2 B<detach(>I<widget>B<)>
  194.  
  195. Detaches the specified I<widget> from the help system.
  196.  
  197. =head2 B<destroy>
  198.  
  199. Destroys the specified balloon.
  200.  
  201. =head1 EXAMPLES
  202.  
  203. See the balloon demo included with the widget demo script that came with
  204. the distribution for examples on various ways to use balloons.
  205.  
  206. =head1 NOTES
  207.  
  208. Because of the overhead associated with each balloon you create (from
  209. tracking the mouse movement to know when to activate and deactivate
  210. them) you will see the best performance (low CPU consumption) if you
  211. create as few balloons as possible and attach them to as many widgets
  212. as you can.  In other words, don't create a balloon for each widget
  213. you want to attach one to.
  214.  
  215. =head1 CAVEATS
  216.  
  217. Pressing any button will deactivate (cancel) the current balloon,
  218. if one exists. You can usually make the balloon reappear by moving
  219. the mouse a little. Creative use of the 3 command options can help
  220. you out also. If the mouse is over the balloon when a menu is unposted
  221. then the balloon will remain until you move off of it.
  222.  
  223. =head1 BUGS
  224.  
  225. Hopefully none, probably some.
  226.  
  227. =head1 AUTHORS
  228.  
  229. B<Rajappa Iyer> rsi@earthling.net did the original coding.
  230.  
  231. B<Jason A. Smith> <smithj4@rpi.edu> added support for menus and made some
  232. other enhancements.
  233.  
  234. B<Slaven Rezic> <eserte@cs.tu-berlin.de> added support for canvas items.
  235.  
  236. =head1 HISTORY
  237.  
  238. The code and documentation was derived from Balloon.tcl from the
  239. Tix4.0 distribution by Ioi Lam and modified by the above mentioned
  240. authors. This code may be redistributed under the same terms as Perl.
  241.  
  242. =cut
  243.  
  244.