-
NAME
-
popup - popup widget
-
SYNOPSIS
-
package require popup ?0.0.1?
popup::command ?options?
-
STANDARD OPTIONS
-
-borderwidth or -bd, borderwidth, BorderWidth
-cursor, cursor, Cursor
-highlightbackground, highlightBackground, HighlightBackground
-highlightcolor, highlightColor, HighlightColor
-highlightthickness, highlightThickness, HighlightThickness
-padx, padX, Pad
-pady, padY, Pad
-relief, relief, Relief
-takefocus, takefocus, TakeFocus
-
STANDARD TOPLEVEL OPTIONS
-
-background or -bg, background, Background
-height, height, Height
-width, width, Width
-
WIDGET-SPECIFIC OPTIONS
-
-focus, focus, Focus
-grab, grab, Grab
-
DESCRIPTION
-
COMMANDS
-
popup::popup command ?options?
popup::create W ?option value ...?
popup::cget W option
popup::configure W ?option value? ?option value ...?
popup::destroy W
popup::map W
popup::option:find option
popup::option:get W option
popup::option:set W option value
popup::pkginfo
popup::post W X Y ?option value ...?
popup::unmap W
-
BINDINGS
-
PERFORMANCE
- Widget Commands
- Widget Configuration Data
-
EXAMPLE
-
BUGS
popup - popup widget
package require popup ?0.0.1?
popup::command ?options?
- Command-Line Name: -focus
- Database Name: focus
- Database Class: Focus
- Specifies a widget to focus when the popup widget is displayed.
- Command-Line Name: -grab
- Database Name: grab
- Database Class: Grab
- Specifies a widget to grab when the popup widget is displayed. If the option is set to "" (empty string), no grab will be set, and the popup widget will not receive keyboard or mouse input. Consequently, the default bindings will not work. An alternative method must be provided for unmapping the popup.
The popup package provides a popup widget.
A popup widget is a borderless toplevel widget with a global grab.
The popup::create command creates a new popup widget (given by the W argument). Additional options, described above, may be specified on the command line or in the option database to configure aspects of the popup such as its background color and relief. The popup::create command returns its W argument. At the time this command is invoked, there must not exist a window named W, but W's parent must exist.
-
W popup::popup command ?options?
popup::popup command ?options?
-
This is the main command for the popup package. If command starts with a dot, it is treated as a widget pathname, and is passed along with options as arguments to the popup::create command. Otherwise, the options are passed as arguments to the command popup::command.
-
W popup::create W ?option value ...?
-
Creates a new tcl command whise name is W, and creates a new popup widget with pathname W. Additional option-value pairs may be specified to configure aspects of the widget. The name of the widget W is returned. The widget command W, and the following package commands, may be used to invoke various operations on the widget. The command syntax may take one of two forms:
The first form follows the "standard" syntax for Tk widgets:
W command ?arg arg ...?
The second form provides improved performance:
popup::command W ?arg arg ...?
Command and the args determine the exact behaviour of each command. The following commands are possible for popup widgets:
-
W cget option
popup::cget W option
-
Returns the current value of the configuration option given by option for popup widget W. Option may have any of the values permissible for the popup::create command.
-
W configure ?option? ?value? ?option value ...?
popup::configure W ?option? ?value? ?option value ...?
-
Queries or modifies the configuration options for popup widget W. If no option is specified, returns a list describing all of the available options for the popup (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the popup option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the values permissible for the popup::create command.
-
W destroy
popup::destroy W
-
Destroys the popup widget W, and deletes all associated stored variables. This command is generally called when the popup is destroyed (i.e. in response to a <Destroy> event), but may also be called directly to destroy the popup.
-
W map
popup::map W
-
Maps (displays) the popup widget W at its current position. Returns an empty string.
-
popup::option:find option
-
Returns the index of the configuration option option. The popup package maintains a list of all acceptable configration options, which is searched for an option name matching option. If an exact match is not found,
option is treated as an abbreviation and compared with each option name in the list. If exactly one match is found, the index of that option name in the list is returned, otherwise returns -1. Option may have any of the values permissible for the popup::create command. This command is called from the popup::option:get and popup::option:set commands, and should not generally be called directly.
-
W option:get option
popup::option:get W option
-
Queries a configuration option for popup widget W. Option may have any of the values permissible for the popup::create command. Returns the current value of configuration option option.
-
W option:set option value
popup::option:set W option value
-
Modifies a configuration option for popup widget W. Option may have any of the values permissible for the popup::create command. Returns an empty string.
-
popup::pkginfo
-
Returns the package information for the popup package, as a list of option-value pairs. For example, you could do:
array set pkginfo [popup::pkginfo]
Alternatively, you can access the pkginfo array variable directly:
array set pkginfo [array get popup::pkginfo]
-
W post X Y ?option value ...?
popup::post W X Y ?option value ...?
-
Posts (displays) the popup widget W at screen position X, Y. The top-left corner of the popup is positioned at the specified coordinates. Returns an empty string. The option-value pairs may have any of the following forms:
- -width width
- Specifies the desired width for the popup in any of the forms acceptable to Tk_GetPixels. If this option is less than or equal to zero (the default) then the window will not request any width at all (it will be just wide enough to display all its contents).
- -height height
- Specifies the desired height for the popup in any of the forms acceptable to Tk_GetPixels. If this option is less than or equal to zero (the default) then the window will not request any height at all (it will be just high enough to display all its contents).
-
W unmap
popup::unmap W
-
Unmaps (hides) popup widget W. Releases the global grab, and restores focus. Returns an empty string.
The popup package creates class-level bindings for popup widgets with the following behavior:
- [1]
- Pressing <Escape> will unmap the popup widget.
- [2]
- Clicking <Button-1> outside of the popup widget will unmap the popup.
- [3]
- When the popup widget is destroyed, the popup::destroy command is called (in response to the <Destroy> event).
This section describes a number of ways of improving the performance of the popup widget.
-
Widget Commands
- The global command for each popup widget provides a level of compatibility with the standard tcl syntax for widget commands. However, this interface to the popup package commands may have a noticeable impact on performance. For performance-critical code, or wherever possible, it is recommended that the more direct package commands be used. For instance:
Instead of:
package require popup
namespace import ::popup::popup
set popup [popup .popup]
$popup configure -bg blue
bind . <Button-1> [list $popup post %X %Y]
Use:
package require popup
set popup [popup::create .popup]
popup::option:set $popup -background blue
bind . <Button-1> [list popup::post $popup %X %Y]
-
Widget Configuration Data
- Although it is possible to access popup configuration data through the global popup compatibility command, and through the package commands, in certain circumstances it may be more efficient to access the data directly. The values of all widget-specific configuration options for popup widgets are stored directly in an array variable in the popup package namespace. The name of the array variable is the same as the pathname of the popup widget. Each configuration option is an index into that array variable. For example:
package require popup
popup::create .p
parray popup::.p
Warning: Modifying the list of values in the namespace array variable directly can lead to unexpected results. The popup::configure and popup::option:set commands should be used to modify the popup configuration options.
-
# click anywhere in . to set the window title
package require popup
namespace import ::popup::popup
set command "wm title . \$title ; [list popup::unmap .popup]"
popup .popup -focus .popup.entry
entry .popup.entry -textvariable title
bind .popup.entry <Key-Return> $command
button .popup.ok -command $command
pack .popup.ok -side right
pack .popup.entry -side left -fill x
bind .popup.entry <Key-Return> $command
bind . <Button-1> [list popup::post .popup %X %Y]
Needs testing.
Does not import values from the options database.
Copyright © 2004, Mark G. Saye <markgsaye@yahoo.com>