Pmw.Balloon

Name

Pmw.Balloon() - display "tool tips" for a number of widgets

Inherits

Pmw.MegaToplevel

Description

A balloon megawidget can be used to give short help messages to the user when they place the mouse over a button or other widget for a short time. It can also be used to display help messages for canvas or text items.

One balloon megawidget can be used to display help for many widgets or items. For each widget or item that requires balloon help, the bind() or bindtag() method is used to specify the help text that should be displayed.

The help message is displayed in a popup balloon window when the mouse remains over the widget or item for a short time. The popup balloon is withdrawn when the mouse leaves the widget or item, or any mouse buttons are pressed.

The position of the popup balloon is configurable and may appear either relative to the widget or item or relative to the position of the mouse.

The popup balloon is displayed without any window manager decorations.

The megawidget can cooperate with a Pmw.MessageBar to display a single-line help message as well as the balloon help.

Options

Options for this megawidget and its base classes are described below.

activatecommand

If this is callable, it will be called whenever the megawidget is activated by a call to activate(). The default is None.

deactivatecommand

If this is callable, it will be called whenever the megawidget is deactivated by a call to deactivate(). The default is None.

initwait

The number of milliseconds delay between when the mouse enters a widget or item and when the popup balloon window should be displayed. The default is 500.

master

This is used by the activate() method to control whether the window is made transient during modal dialogs. See the activate() method. The default is 'parent'.

relmouse

This may be one of 'both', 'x', 'y' or 'none' and indicates that the top left corner of the popup balloon window should be placed relative to the current position of the mouse rather than relative to the bottom left corner of the widget or item (the default). The positioning may be set for the horizontal (x) and vertical (y) axes independently. The default is 'none'.

state

This may be one of 'both', 'balloon', 'status' or 'none' and indicates whether the help message should be displayed in the popup balloon window, in an associated messagebar (via the statuscommand option), or both. The default is 'both'.

statuscommand

This specifies a function to call when the mouse enters a widget or item bound to this balloon megawidget. To configure a Pmw.MessageBar to display help, set this option to the helpmessage method of the messagebar. The default is None.

title

This is the title that the window manager displays in the title bar of the window. The default is None.

xoffset

This specifies the horizontal offset of the position of the left side of the popup balloon window relative the point determined by the relmouse option. The default is 20.

yoffset

This specifies the vertical offset of the position of the top of the popup balloon window relative the point determined by the relmouse option. The default is 1.

Components

Components created by this megawidget and its base classes are described below.

hull

This acts as the body for the entire megawidget. Other components are created as children of the hull to further specialise this class. By default, this component is a Tkinter.Toplevel.

label

This component displays the text of the help message in the popup balloon window. By default it is created with a 'lightyellow' background, a 'black' foreground and is 'left' justified. By default, this component is a Tkinter.Label.

Methods

Only methods specific to this megawidget are described below. For a description of its inherited methods, see the manual for its base class Pmw.MegaToplevel.

bind(widget, balloonHelp, statusHelp = None)

Create bindings for widget so that balloon help and/or status help is displayed when the mouse enters the widget. The balloon help message is given by balloonHelp and the status help message is given by statusHelp. If balloonHelp is None, no balloon is displayed. If statusHelp is not set, it defaults to balloonHelp. Any previous bindings for this widget are removed.

clearstatus()

Clear the text in the associated messagebar by passing None to the statuscommand function.

showstatus(statusHelp)

Set the text in the associated messagebar by passing statusHelp to the statuscommand function.

tagbind(widget, tagOrItem, balloonHelp, statusHelp = None)

Create bindings for the tag or item specified by tagOrItem in the text or canvas widget so that balloon help and/or status help is displayed when the mouse enters the tag or item. The balloon help message is given by balloonHelp and the status help message is given by statusHelp. If balloonHelp is None, no balloon is displayed. If statusHelp is not set, it defaults to balloonHelp. Any previous bindings for this tag or item are removed.

tagunbind(widget, tagOrItem)

Remove the balloon help bindings from the tag or item specified by tagOrItem in the text or canvas widget.

Note that tagunbind() must be called when deleting a canvas item, so that the popup balloon window can be withdrawn if it was triggered by the item. (Unfortunately this can not be automated as is done for widgets since Tk does not support <Destroy> bindings on canvas items, so there is no way that Pmw.Balloon can be notified of the deletion of an item.)

unbind(widget)

Remove the balloon help bindings from widget.

Example

The image at the top of this manual is a snapshot of the window (or part of the window) produced by the following code.

class Demo:
    def __init__(self, parent):
        # Create the Balloon.
        self.balloon = Pmw.Balloon(parent)

        # Create some widgets and megawidgets with balloon help.
        frame = Tkinter.Frame(parent)
        frame.pack(padx = 10, pady = 5)
        field = Pmw.EntryField(frame,
                labelpos = 'nw',
                label_text = 'Command:')
        field.setentry('mycommand -name foo')
        field.pack(side = 'left', padx = 10)
        self.balloon.bind(field, 'Command to\nstart/stop',
                'Enter the shell command to control')

        start = Tkinter.Button(frame, text='Start')
        start.pack(side='left', padx = 10)
        self.balloon.bind(start, 'Start the command')

        stop = Tkinter.Button(frame, text='Stop')
        stop.pack(side='left', padx = 10)
        self.balloon.bind(stop, 'Stop the command')

        self.suicide = Tkinter.Button(frame, text='Kill me soon!',
            command = self.killButton)
        self.suicide.pack(side='left', padx = 10)
        self.balloon.bind(self.suicide, 'Watch this button disappear!')

        scrolledCanvas = Pmw.ScrolledCanvas(parent,
                canvas_width = 300,
                canvas_height = 115,
        )
        scrolledCanvas.pack()
        canvas = scrolledCanvas.component('canvas')
        self.canvas = canvas

        # Create some canvas items and individual help.
        item = canvas.create_arc(5, 5, 35, 35, fill = 'red', extent = 315)
        self.balloon.tagbind(canvas, item, 'This is help for\nan arc item')
        item = canvas.create_bitmap(20, 150, bitmap = 'question')
        self.balloon.tagbind(canvas, item, 'This is help for\na bitmap')
        item = canvas.create_line(50, 60, 70, 80, 85, 20, width = 5)
        self.balloon.tagbind(canvas, item, 'This is help for\na line item')
        item = canvas.create_text(10, 90, text = 'Canvas items with balloons',
                anchor = 'nw', font = field.cget('entry_font'))
        self.balloon.tagbind(canvas, item, 'This is help for\na text item')

        # Create two canvas items which have the same tag and which use
        # the same help.
        canvas.create_rectangle(100, 10, 170, 50, fill = 'aliceblue',
                tags = 'TAG1')
        self.bluecircle = canvas.create_oval(110, 30, 160, 80, fill = 'blue',
                tags = 'TAG1')
        self.balloon.tagbind(canvas, 'TAG1',
                'This is help for the two blue items' + '\n' * 10 +
                    'It is very, very big.',
                'This is help for the two blue items')
        item = canvas.create_text(180, 10, text = 'Delete',
                anchor = 'nw', font = field.cget('entry_font'))
        self.balloon.tagbind(canvas, item,
                'After 2 seconds,\ndelete the blue circle')
        canvas.tag_bind(item, '<ButtonPress>', self._canvasButtonpress)
        scrolledCanvas.resizescrollregion()

        scrolledText = Pmw.ScrolledText(parent,
                text_width = 32,
                text_height = 4,
                text_wrap = 'none',
        )
        scrolledText.pack(pady = 5)
        text = scrolledText.component('text')
        self.text = text

        text.insert('end',
                'This is a text widget with ', '',
                ' balloon', 'TAG1',
                '\nhelp. Find the ', '',
                ' text ', 'TAG1',
                ' tagged with', '',
                ' help.', 'TAG2',
                '\n', '',
                'Remove tag 1.', 'TAG3',
                '\nAnother line.\nAnd another', '',
        )
        text.tag_configure('TAG1', borderwidth = 2, relief = 'sunken')
        text.tag_configure('TAG3', borderwidth = 2, relief = 'raised')

        self.balloon.tagbind(text, 'TAG1',
                'There is one secret\nballoon help.\nCan you find it?')
        self.balloon.tagbind(text, 'TAG2',
                'Well done!\nYou found it!')
        self.balloon.tagbind(text, 'TAG3',
                'After 2 seconds\ndelete the tag')
        text.tag_bind('TAG3', '<ButtonPress>', self._textButtonpress)

        frame = Tkinter.Frame(parent)
        frame.pack(padx = 10)
        self.toggleBalloonVar = Tkinter.IntVar()
        self.toggleBalloonVar.set(1)
        toggle = Tkinter.Checkbutton(frame,
                variable = self.toggleBalloonVar,
                text = 'Balloon help', command = self.toggle)
        toggle.pack(side = 'left', padx = 10)
        self.balloon.bind(toggle, 'Toggle balloon help\non and off')

        self.toggleStatusVar = Tkinter.IntVar()
        self.toggleStatusVar.set(1)
        toggle = Tkinter.Checkbutton(frame,
                variable = self.toggleStatusVar,
                text = 'Status help', command = self.toggle)
        toggle.pack(side = 'left', padx = 10)
        self.balloon.bind(toggle,
                'Toggle status help on and off, on and off' + '\n' * 10 +
                    'It is very, very big, too.',
                'Toggle status help on and off')

        # Create and pack the MessageBar.
        messageBar = Pmw.MessageBar(parent,
                entry_width = 40,
                entry_relief='groove',
                labelpos = 'w',
                label_text = 'Status:')
        messageBar.pack(fill = 'x', expand = 1, padx = 10, pady = 5)

        # Configure the balloon to display its status messages in the
        # message bar.
        self.balloon.configure(statuscommand = messageBar.helpmessage)

    def toggle(self):
        if self.toggleBalloonVar.get():
            if self.toggleStatusVar.get():
                self.balloon.configure(state = 'both')
            else:
                self.balloon.configure(state = 'balloon')
        else:
            if self.toggleStatusVar.get():
                self.balloon.configure(state = 'status')
            else:
                self.balloon.configure(state = 'none')

    def killButton(self):
        # Test for old bug when destroying widgets 1) while the
        # balloon was up and 2) during the initwait period.
        print 'Destroying button in 2 seconds'
        self.suicide.after(2000, self.suicide.destroy)

    def _canvasButtonpress(self, event):
        print 'Destroying blue circle in 2 seconds'
        self.canvas.after(2000, self.deleteBlueCircle)

    def deleteBlueCircle(self):
        self.balloon.tagunbind(self.canvas, self.bluecircle)
        self.canvas.delete(self.bluecircle)

    def _textButtonpress(self, event):
        print 'Deleting the text tag in 2 seconds'
        self.text.after(2000, self.deleteTextTag)

    def deleteTextTag(self):
        self.balloon.tagunbind(self.text, 'TAG1')
        self.text.tag_delete('TAG1')