| 1 | |
| 2 | <html> |
| 3 | <head> |
| 4 | <meta name="description" content="Pmw - a toolkit for building high-level compound widgets in Python"> |
| 5 | <meta name="content" content="python, megawidget, mega widget, compound widget, gui, tkinter"> |
| 6 | <title>Pmw.Balloon reference manual</title> |
| 7 | </head> |
| 8 | |
| 9 | <body bgcolor="#ffffff" text="#000000" link="#0000ee" |
| 10 | vlink="551a8b" alink="ff0000"> |
| 11 | |
| 12 | <h1 ALIGN="CENTER">Pmw.Balloon</h1> |
| 13 | |
| 14 | <center><IMG SRC=Balloon.gif ALT="" WIDTH=428 HEIGHT=189></center> |
| 15 | <dl> |
| 16 | <dt> <h3>Name</h3></dt><dd> |
| 17 | <p>Pmw.Balloon() - |
| 18 | display "tool tips" for a number of widgets |
| 19 | </p> |
| 20 | |
| 21 | |
| 22 | </dd> |
| 23 | <dt> <h3>Inherits</h3></dt><dd> |
| 24 | <a href="MegaToplevel.html">Pmw.MegaToplevel</a><br> |
| 25 | </dd> |
| 26 | <dt> <h3>Description</h3></dt><dd> |
| 27 | <p> |
| 28 | A balloon megawidget can be used to give short help messages to |
| 29 | the user when they place the mouse over a button or other widget |
| 30 | for a short time. It can also be used to display help messages |
| 31 | for canvas or text items.</p> |
| 32 | |
| 33 | <p> One balloon megawidget can be used to display help for many |
| 34 | widgets or items. For each widget or item that requires balloon |
| 35 | help, the <code>bind()</code> or <code>bindtag()</code> method is used to specify the |
| 36 | help text that should be displayed.</p> |
| 37 | |
| 38 | <p> The help message is displayed in a popup balloon window when the |
| 39 | mouse remains over the widget or item for a short time. The popup |
| 40 | balloon is withdrawn when the mouse leaves the widget or item, or |
| 41 | any mouse buttons are pressed.</p> |
| 42 | |
| 43 | <p> The position of the popup balloon is configurable and may appear |
| 44 | either relative to the widget or item or relative to the position |
| 45 | of the mouse.</p> |
| 46 | |
| 47 | <p> The popup balloon is displayed without any window manager |
| 48 | decorations.</p> |
| 49 | |
| 50 | <p> The megawidget can cooperate with a <a href="MessageBar.html">Pmw.MessageBar</a> to display a |
| 51 | single-line help message as well as the balloon help.</p> |
| 52 | |
| 53 | <p></p> |
| 54 | |
| 55 | |
| 56 | </dd> |
| 57 | <dt> <h3>Options</h3></dt><dd> |
| 58 | Options for this megawidget and its base |
| 59 | classes are described below.<p></p> |
| 60 | <a name=option.activatecommand></a> |
| 61 | <dl><dt> <strong>activatecommand |
| 62 | </strong></dt><dd> |
| 63 | If this is callable, it will be called whenever the megawidget is |
| 64 | activated by a call to <code>activate()</code>. The default is <strong>None</strong>.</p> |
| 65 | |
| 66 | |
| 67 | </dd></dl> |
| 68 | <a name=option.deactivatecommand></a> |
| 69 | <dl><dt> <strong>deactivatecommand |
| 70 | </strong></dt><dd> |
| 71 | If this is callable, it will be called whenever the megawidget is |
| 72 | deactivated by a call to <code>deactivate()</code>. The default is <strong>None</strong>.</p> |
| 73 | |
| 74 | |
| 75 | </dd></dl> |
| 76 | <a name=option.initwait></a> |
| 77 | <dl><dt> <strong>initwait |
| 78 | </strong></dt><dd> |
| 79 | The number of milliseconds delay between when the mouse enters a |
| 80 | widget or item and when the popup balloon window should be |
| 81 | displayed. The default is <strong>500</strong>.</p> |
| 82 | |
| 83 | |
| 84 | </dd></dl> |
| 85 | <a name=option.master></a> |
| 86 | <dl><dt> <strong>master |
| 87 | </strong></dt><dd> |
| 88 | This is used by the <code>activate()</code> method to control whether the |
| 89 | window is made <em>transient</em> during modal dialogs. See the |
| 90 | <code>activate()</code> method. The default is <strong>'parent'</strong>.</p> |
| 91 | |
| 92 | |
| 93 | </dd></dl> |
| 94 | <a name=option.relmouse></a> |
| 95 | <dl><dt> <strong>relmouse |
| 96 | </strong></dt><dd> |
| 97 | This may be one of <strong>'both'</strong>, <strong>'x'</strong>, <strong>'y'</strong> or <strong>'none'</strong> and |
| 98 | indicates that the top left corner of the popup balloon window |
| 99 | should be placed relative to the current position of the mouse |
| 100 | rather than relative to the bottom left corner of the widget or |
| 101 | item (the default). The positioning may be set for the horizontal |
| 102 | (x) and vertical (y) axes independently. The default is <strong>'none'</strong>.</p> |
| 103 | |
| 104 | |
| 105 | </dd></dl> |
| 106 | <a name=option.state></a> |
| 107 | <dl><dt> <strong>state |
| 108 | </strong></dt><dd> |
| 109 | This may be one of <strong>'both'</strong>, <strong>'balloon'</strong>, <strong>'status'</strong> or <strong>'none'</strong> |
| 110 | and indicates whether the help message should be displayed in the |
| 111 | popup balloon window, in an associated messagebar (via the |
| 112 | <strong>statuscommand</strong> option), or both. The default is <strong>'both'</strong>.</p> |
| 113 | |
| 114 | |
| 115 | </dd></dl> |
| 116 | <a name=option.statuscommand></a> |
| 117 | <dl><dt> <strong>statuscommand |
| 118 | </strong></dt><dd> |
| 119 | This specifies a function to call when the mouse enters a widget |
| 120 | or item bound to this balloon megawidget. To configure a |
| 121 | <a href="MessageBar.html">Pmw.MessageBar</a> to display help, set this option to the <code>helpmessage</code> |
| 122 | method of the messagebar. The default is <strong>None</strong>.</p> |
| 123 | |
| 124 | |
| 125 | </dd></dl> |
| 126 | <a name=option.title></a> |
| 127 | <dl><dt> <strong>title |
| 128 | </strong></dt><dd> |
| 129 | This is the title that the window manager displays in the title |
| 130 | bar of the window. The default is <strong>None</strong>.</p> |
| 131 | |
| 132 | |
| 133 | </dd></dl> |
| 134 | <a name=option.xoffset></a> |
| 135 | <dl><dt> <strong>xoffset |
| 136 | </strong></dt><dd> |
| 137 | This specifies the horizontal offset of the position of the left |
| 138 | side of the popup balloon window relative the point determined by |
| 139 | the <strong>relmouse</strong> option. The default is <strong>20</strong>.</p> |
| 140 | |
| 141 | |
| 142 | </dd></dl> |
| 143 | <a name=option.yoffset></a> |
| 144 | <dl><dt> <strong>yoffset |
| 145 | </strong></dt><dd> |
| 146 | This specifies the vertical offset of the position of the top of |
| 147 | the popup balloon window relative the point determined by the |
| 148 | <strong>relmouse</strong> option. The default is <strong>1</strong>.</p> |
| 149 | |
| 150 | |
| 151 | </dd></dl> |
| 152 | </dd> |
| 153 | <dt> <h3>Components</h3></dt><dd> |
| 154 | Components created by this megawidget and its base |
| 155 | classes are described below.<p></p> |
| 156 | <a name=component.hull></a> |
| 157 | <dl><dt> <strong>hull |
| 158 | </strong></dt><dd> |
| 159 | This acts as the body for the entire megawidget. Other components |
| 160 | are created as children of the hull to further specialise this |
| 161 | class. By default, this component is a Tkinter.Toplevel.</p> |
| 162 | |
| 163 | |
| 164 | </dd></dl> |
| 165 | <a name=component.label></a> |
| 166 | <dl><dt> <strong>label |
| 167 | </strong></dt><dd> |
| 168 | This component displays the text of the help message in the popup |
| 169 | balloon window. By default it is created with a <strong>'lightyellow'</strong> |
| 170 | background, a <strong>'black'</strong> foreground and is <strong>'left'</strong> justified. By default, this component is a Tkinter.Label.</p> |
| 171 | |
| 172 | |
| 173 | </dd></dl> |
| 174 | </dd> |
| 175 | <a name=methods></a> |
| 176 | <dt> <h3>Methods</h3></dt><dd> |
| 177 | Only methods specific to this megawidget are described below. |
| 178 | For a description of its inherited methods, see the |
| 179 | manual for its base class |
| 180 | <strong><a href="MegaToplevel.html#methods">Pmw.MegaToplevel</a></strong>. |
| 181 | <p></p> |
| 182 | <a name=method.bind></a> |
| 183 | <dl><dt> <strong>bind</strong>(<em>widget</em>, <em>balloonHelp</em>, <em>statusHelp</em> = <strong>None</strong>)</dt><dd> |
| 184 | Create bindings for <em>widget</em> so that balloon help and/or status |
| 185 | help is displayed when the mouse enters the widget. The balloon |
| 186 | help message is given by <em>balloonHelp</em> and the status help message |
| 187 | is given by <em>statusHelp</em>. If <em>balloonHelp</em> is <strong>None</strong>, no balloon |
| 188 | is displayed. If <em>statusHelp</em> is not set, it defaults to |
| 189 | <em>balloonHelp</em>. Any previous bindings for this widget are removed.</p> |
| 190 | |
| 191 | |
| 192 | </dd></dl> |
| 193 | <a name=method.clearstatus></a> |
| 194 | <dl><dt> <strong>clearstatus</strong>()</dt><dd> |
| 195 | Clear the text in the associated messagebar by passing <strong>None</strong> to |
| 196 | the <strong>statuscommand</strong> function.</p> |
| 197 | |
| 198 | |
| 199 | </dd></dl> |
| 200 | <a name=method.showstatus></a> |
| 201 | <dl><dt> <strong>showstatus</strong>(<em>statusHelp</em>)</dt><dd> |
| 202 | Set the text in the associated messagebar by passing <em>statusHelp</em> |
| 203 | to the <strong>statuscommand</strong> function.</p> |
| 204 | |
| 205 | |
| 206 | </dd></dl> |
| 207 | <a name=method.tagbind></a> |
| 208 | <dl><dt> <strong>tagbind</strong>(<em>widget</em>, <em>tagOrItem</em>, <em>balloonHelp</em>, <em>statusHelp</em> = <strong>None</strong>)</dt><dd> |
| 209 | Create bindings for the tag or item specified by <em>tagOrItem</em> in |
| 210 | the text or canvas <em>widget</em> so that balloon help and/or status |
| 211 | help is displayed when the mouse enters the tag or item. The |
| 212 | balloon help message is given by <em>balloonHelp</em> and the status help |
| 213 | message is given by <em>statusHelp</em>. If <em>balloonHelp</em> is <strong>None</strong>, no |
| 214 | balloon is displayed. If <em>statusHelp</em> is not set, it defaults to |
| 215 | <em>balloonHelp</em>. Any previous bindings for this tag or item are |
| 216 | removed.</p> |
| 217 | |
| 218 | |
| 219 | </dd></dl> |
| 220 | <a name=method.tagunbind></a> |
| 221 | <dl><dt> <strong>tagunbind</strong>(<em>widget</em>, <em>tagOrItem</em>)</dt><dd> |
| 222 | Remove the balloon help bindings from the tag or item specified by |
| 223 | <em>tagOrItem</em> in the text or canvas <em>widget</em>.</p> |
| 224 | <p> Note that <code>tagunbind()</code> must be called when deleting a canvas |
| 225 | item, so that the popup balloon window can be withdrawn if it was |
| 226 | triggered by the item. (Unfortunately this can not be automated |
| 227 | as is done for widgets since Tk does not support <code><Destroy></code> |
| 228 | bindings on canvas items, so there is no way that Pmw.Balloon can |
| 229 | be notified of the deletion of an item.)</p> |
| 230 | |
| 231 | |
| 232 | |
| 233 | </dd></dl> |
| 234 | <a name=method.unbind></a> |
| 235 | <dl><dt> <strong>unbind</strong>(<em>widget</em>)</dt><dd> |
| 236 | Remove the balloon help bindings from <em>widget</em>.</p> |
| 237 | |
| 238 | |
| 239 | </dd></dl> |
| 240 | </dd> |
| 241 | <dt> <h3>Example</h3></dt><dd> |
| 242 | The image at the top of this manual is a snapshot |
| 243 | of the window (or part of the window) produced |
| 244 | by the following code.<p></p> |
| 245 | <pre> |
| 246 | class Demo: |
| 247 | def __init__(self, parent): |
| 248 | # Create the Balloon. |
| 249 | self.balloon = Pmw.Balloon(parent) |
| 250 | |
| 251 | # Create some widgets and megawidgets with balloon help. |
| 252 | frame = Tkinter.Frame(parent) |
| 253 | frame.pack(padx = 10, pady = 5) |
| 254 | field = Pmw.EntryField(frame, |
| 255 | labelpos = 'nw', |
| 256 | label_text = 'Command:') |
| 257 | field.setentry('mycommand -name foo') |
| 258 | field.pack(side = 'left', padx = 10) |
| 259 | self.balloon.bind(field, 'Command to\nstart/stop', |
| 260 | 'Enter the shell command to control') |
| 261 | |
| 262 | start = Tkinter.Button(frame, text='Start') |
| 263 | start.pack(side='left', padx = 10) |
| 264 | self.balloon.bind(start, 'Start the command') |
| 265 | |
| 266 | stop = Tkinter.Button(frame, text='Stop') |
| 267 | stop.pack(side='left', padx = 10) |
| 268 | self.balloon.bind(stop, 'Stop the command') |
| 269 | |
| 270 | self.suicide = Tkinter.Button(frame, text='Kill me soon!', |
| 271 | command = self.killButton) |
| 272 | self.suicide.pack(side='left', padx = 10) |
| 273 | self.balloon.bind(self.suicide, 'Watch this button disappear!') |
| 274 | |
| 275 | scrolledCanvas = Pmw.ScrolledCanvas(parent, |
| 276 | canvas_width = 300, |
| 277 | canvas_height = 115, |
| 278 | ) |
| 279 | scrolledCanvas.pack() |
| 280 | canvas = scrolledCanvas.component('canvas') |
| 281 | self.canvas = canvas |
| 282 | |
| 283 | # Create some canvas items and individual help. |
| 284 | item = canvas.create_arc(5, 5, 35, 35, fill = 'red', extent = 315) |
| 285 | self.balloon.tagbind(canvas, item, 'This is help for\nan arc item') |
| 286 | item = canvas.create_bitmap(20, 150, bitmap = 'question') |
| 287 | self.balloon.tagbind(canvas, item, 'This is help for\na bitmap') |
| 288 | item = canvas.create_line(50, 60, 70, 80, 85, 20, width = 5) |
| 289 | self.balloon.tagbind(canvas, item, 'This is help for\na line item') |
| 290 | item = canvas.create_text(10, 90, text = 'Canvas items with balloons', |
| 291 | anchor = 'nw', font = field.cget('entry_font')) |
| 292 | self.balloon.tagbind(canvas, item, 'This is help for\na text item') |
| 293 | |
| 294 | # Create two canvas items which have the same tag and which use |
| 295 | # the same help. |
| 296 | canvas.create_rectangle(100, 10, 170, 50, fill = 'aliceblue', |
| 297 | tags = 'TAG1') |
| 298 | self.bluecircle = canvas.create_oval(110, 30, 160, 80, fill = 'blue', |
| 299 | tags = 'TAG1') |
| 300 | self.balloon.tagbind(canvas, 'TAG1', |
| 301 | 'This is help for the two blue items' + '\n' * 10 + |
| 302 | 'It is very, very big.', |
| 303 | 'This is help for the two blue items') |
| 304 | item = canvas.create_text(180, 10, text = 'Delete', |
| 305 | anchor = 'nw', font = field.cget('entry_font')) |
| 306 | self.balloon.tagbind(canvas, item, |
| 307 | 'After 2 seconds,\ndelete the blue circle') |
| 308 | canvas.tag_bind(item, '<ButtonPress>', self._canvasButtonpress) |
| 309 | scrolledCanvas.resizescrollregion() |
| 310 | |
| 311 | scrolledText = Pmw.ScrolledText(parent, |
| 312 | text_width = 32, |
| 313 | text_height = 4, |
| 314 | text_wrap = 'none', |
| 315 | ) |
| 316 | scrolledText.pack(pady = 5) |
| 317 | text = scrolledText.component('text') |
| 318 | self.text = text |
| 319 | |
| 320 | text.insert('end', |
| 321 | 'This is a text widget with ', '', |
| 322 | ' balloon', 'TAG1', |
| 323 | '\nhelp. Find the ', '', |
| 324 | ' text ', 'TAG1', |
| 325 | ' tagged with', '', |
| 326 | ' help.', 'TAG2', |
| 327 | '\n', '', |
| 328 | 'Remove tag 1.', 'TAG3', |
| 329 | '\nAnother line.\nAnd another', '', |
| 330 | ) |
| 331 | text.tag_configure('TAG1', borderwidth = 2, relief = 'sunken') |
| 332 | text.tag_configure('TAG3', borderwidth = 2, relief = 'raised') |
| 333 | |
| 334 | self.balloon.tagbind(text, 'TAG1', |
| 335 | 'There is one secret\nballoon help.\nCan you find it?') |
| 336 | self.balloon.tagbind(text, 'TAG2', |
| 337 | 'Well done!\nYou found it!') |
| 338 | self.balloon.tagbind(text, 'TAG3', |
| 339 | 'After 2 seconds\ndelete the tag') |
| 340 | text.tag_bind('TAG3', '<ButtonPress>', self._textButtonpress) |
| 341 | |
| 342 | frame = Tkinter.Frame(parent) |
| 343 | frame.pack(padx = 10) |
| 344 | self.toggleBalloonVar = Tkinter.IntVar() |
| 345 | self.toggleBalloonVar.set(1) |
| 346 | toggle = Tkinter.Checkbutton(frame, |
| 347 | variable = self.toggleBalloonVar, |
| 348 | text = 'Balloon help', command = self.toggle) |
| 349 | toggle.pack(side = 'left', padx = 10) |
| 350 | self.balloon.bind(toggle, 'Toggle balloon help\non and off') |
| 351 | |
| 352 | self.toggleStatusVar = Tkinter.IntVar() |
| 353 | self.toggleStatusVar.set(1) |
| 354 | toggle = Tkinter.Checkbutton(frame, |
| 355 | variable = self.toggleStatusVar, |
| 356 | text = 'Status help', command = self.toggle) |
| 357 | toggle.pack(side = 'left', padx = 10) |
| 358 | self.balloon.bind(toggle, |
| 359 | 'Toggle status help on and off, on and off' + '\n' * 10 + |
| 360 | 'It is very, very big, too.', |
| 361 | 'Toggle status help on and off') |
| 362 | |
| 363 | # Create and pack the MessageBar. |
| 364 | messageBar = Pmw.MessageBar(parent, |
| 365 | entry_width = 40, |
| 366 | entry_relief='groove', |
| 367 | labelpos = 'w', |
| 368 | label_text = 'Status:') |
| 369 | messageBar.pack(fill = 'x', expand = 1, padx = 10, pady = 5) |
| 370 | |
| 371 | # Configure the balloon to display its status messages in the |
| 372 | # message bar. |
| 373 | self.balloon.configure(statuscommand = messageBar.helpmessage) |
| 374 | |
| 375 | def toggle(self): |
| 376 | if self.toggleBalloonVar.get(): |
| 377 | if self.toggleStatusVar.get(): |
| 378 | self.balloon.configure(state = 'both') |
| 379 | else: |
| 380 | self.balloon.configure(state = 'balloon') |
| 381 | else: |
| 382 | if self.toggleStatusVar.get(): |
| 383 | self.balloon.configure(state = 'status') |
| 384 | else: |
| 385 | self.balloon.configure(state = 'none') |
| 386 | |
| 387 | def killButton(self): |
| 388 | # Test for old bug when destroying widgets 1) while the |
| 389 | # balloon was up and 2) during the initwait period. |
| 390 | print 'Destroying button in 2 seconds' |
| 391 | self.suicide.after(2000, self.suicide.destroy) |
| 392 | |
| 393 | def _canvasButtonpress(self, event): |
| 394 | print 'Destroying blue circle in 2 seconds' |
| 395 | self.canvas.after(2000, self.deleteBlueCircle) |
| 396 | |
| 397 | def deleteBlueCircle(self): |
| 398 | self.balloon.tagunbind(self.canvas, self.bluecircle) |
| 399 | self.canvas.delete(self.bluecircle) |
| 400 | |
| 401 | def _textButtonpress(self, event): |
| 402 | print 'Deleting the text tag in 2 seconds' |
| 403 | self.text.after(2000, self.deleteTextTag) |
| 404 | |
| 405 | def deleteTextTag(self): |
| 406 | self.balloon.tagunbind(self.text, 'TAG1') |
| 407 | self.text.tag_delete('TAG1') |
| 408 | |
| 409 | </pre> |
| 410 | </dd> |
| 411 | </dl> |
| 412 | |
| 413 | <center><P ALIGN="CENTER"> |
| 414 | <IMG SRC = blue_line.gif ALT = "" WIDTH=320 HEIGHT=5> |
| 415 | </p></center> |
| 416 | |
| 417 | |
| 418 | <font size=-1> |
| 419 | <center><P ALIGN="CENTER"> |
| 420 | Pmw 1.2 - |
| 421 | 5 Aug 2003 |
| 422 | - <a href="index.html">Home</a> |
| 423 | <br>Manual page last reviewed: 20 May 2002 |
| 424 | </p></center> |
| 425 | </font> |
| 426 | |
| 427 | </body> |
| 428 | </html> |
| 429 | |