piemenu

A package to create pie menus.

Documentation (DRAFT - on going work)

NAME
piemenu - Create and manipulate piemenu widgets
SYNOPSIS
piemenu pathName ?options?
STANDARD OPTIONS
-activebackground
-activeforeground
-background
-borderwidth
-disabledforeground
-font
-foreground
WIDGET-SPECIFIC OPTIONS
-angles
-menu
-outline
-postcommand
-radius
-ratio
-roundness
-selectcolor
-showdial
-slices
-start
-x
-y

NAME

piemenu - Create and manipulate pie menus

SYNOPSIS

piemenu pathName ?option value ...?

STANDARD OPTIONS

-activebackground
-activeforeground
-background
-borderwidth
-disabledforeground
-font
-foreground

WIDGET-SPECIFIC OPTIONS

Command-Line Name: -angles
Value is a list of {center-angle arc-extend ...} pairs, one per piemenu entry. If the number of slices is greater than the number of pairs, then the angles are calculated internally, by dividing the dial by the -slices value.

Command-Line Name: -menu
Sets the border color of a piemenu.

Command-Line Name: -outline
Sets the border color of a piemenu.

Command-Line Name: -postcommand
If this option is specified then it provides a Tcl command to execute each time the menu is posted. The command is invoked by the post widget command before posting the menu.

Command-Line Name: -radius
The outer radius (or semi-major axis) of the piemenu in pixels, [80]

Command-Line Name: -ratio
The ratio center-button-radius/radius of the piemenu, 0.0 - 1.0, [0.45]

Command-Line Name: -roundness
The ratio y-size / x-size, [1.0]

Command-Line Name: -selectcolor
The color to display when the entry is selected. If the value is an empty string then the selectcolor option for the piemenu determines the color.

Command-Line Name: -showdial
Value is a boolean. If true, the menu's dial is shown. This is relevant only if there are gaps in the buttons or if the -slice value is greater than the number of entries actually present [0]

Command-Line Name: -slices
Defines the number of pie buttons of the menu. This number is incremented internally as buttons are added, but can also be set to a different number for special menus. [-1]

Command-Line Name: -start
The angle at which placing of the piemenu entries will start, in the case that the -angles pairs list is less than the -slices number.

Command-Line Name: -x
The last x coordinate of the center of the piemenu, relative to the piemenu's parent.

Command-Line Name: -y
The last y coordinate of the center of the piemenu, relative to the piemenu's parent.

WIDGET COMMAND

pathName add type ?option value option value ...?
type is one of command, checkbutton, radiobuttonor a unique abbreviation of one of the above. If additional arguments are present, they specify any of the following options:

-command value
Specifies a Tcl command to execute when the piemenu entry is invoked.

-delay value
time delay in milliseconds for a button to be pressed to invoke -delayedcommand

-delayedcommand value
the callback that is invoked after pressing a button for -delay milliseconds.

-font value
Specifies the font to use when drawing the label or accelerator string in this entry. If this option is specified as an empty string (the default) then the font option for the overall menu is used. This option is not available for tear-off entries.

-image value
Specifies an image to display in the entry instead of a text string. The image must have been created by some previous invocation of image create. This option overrides the -label option but may be reset to an empty string to enable a textual label to be displayed.

-label value
Specifies a string to display as an identifying label in the entry.

-menu value
If value is not empty, then the current piemenu is replaced with the piemenu defined in value, after the value of -command is executed. If value is set to "unpost", the piemenu is unposted.

-selectimage value (TODO)
Meaningful only for checkbutton and radiobutton entries. Specifies an image to display in the entry (in place of the -image option) when it is selected. Value is the name of an image, which must have been created by some previous invocation of image create. This option is ignored unless the -image option has been specified.

-state value
Specifies one of three states for the entry: normal, active (TODO), or disabled. In normal state the entry is displayed using the foreground option for the menu and the background option from the entry or the menu. The active state is typically used when the pointer is over the entry. In active state the entry is displayed using the activeForeground option for the menu along with the activebackground option from the entry. Disabled state means that the entry should be insensitive: the default bindings will refuse to activate or invoke the entry. In this state the entry is displayed according to the disabledForeground option for the menu and the background option from the entry.

pathName cget ?option?
Returns the current value of the configuration option given by option. Option may have any of the values accepted by the piemenu command.

pathName clone newPathname
Makes a clone of the current piemenu named newPathname. This clone is a piemenu in its own right, but any changes to the clone are propagated to the original piemenu and vice versa.

pathName configure ?option? ?value option value ...?
Query or modify the configuration options of the widget. If no option is specified, returns a list describing all of the available options for pathName (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 given widget option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the values accepted by the piemenu command.

pathName delete index1 ?index2 ...? TODO

pathName entrycget index1 option
Returns the current value of a configuration option for the entry given by index. Option may have any of the values accepted by the add widget command.

pathName entryconfigure index ?option? ?value option value ...?
This command is similar to the configure command, except that it applies to the options for an individual entry, whereas configure applies to the options for the piemenu as a whole. Options may have any of the values accepted by the add widget command. If options are specified, options are modified as indicated in the command and the command returns an empty string. If no options are specified, returns a list describing the current options for entry index (see Tk_ConfigureInfo for information on the format of this list).

pathName insert index type ?option value option value ...? TODO
Same as the add widget command except that it inserts the new entry just before the entry given by index, instead of appending to the end of the menu. The type, option, and value arguments have the same interpretation as for the add widget command. It is not possible to insert new menu entries before the tear-off entry, if the menu has one.

pathName invoke index TODO
Invoke the action of the menu entry. See the sections on the individual entries above for details on what happens. If the menu entry is disabled then nothing happens. If the entry has a command associated with it then the result of that command is returned as the result of the invoke widget command. Otherwise the result is an empty string. Note: invoking a menu entry does not automatically unpost the menu; the default bindings normally take care of this before invoking the invoke widget command.

pathName post x y
Arrange for the piemenu to be displayed on the screen at the root-window coordinates given by x and y. These coordinates are adjusted if necessary to guarantee that the entire piemenu is visible on the screen. This command normally returns an empty string. TODO: If the -postcommand option has been specified, then its value is executed as a Tcl script before posting the piemenu and the result of that script is returned as the result of the post widget command. If an error returns while executing the command, then the error is returned without posting the piemenu.

pathName type index
Returns the type of the menu entry given by index. This is the type argument passed to the add widget command when the entry was created, such as command, checkbutton or radiobutton.

pathName unpost
Unmap the window so that it is no longer displayed.Returns an empty string.

EXAMPLE

The following code creates two piemenus and links them with the -menu entry option. By pressing ok/delayed exit for more than 500 msec (0.5 seconds) the exit command is invoked.
lappend auto_path .
package req Tk

package req piemenu

pack [canvas .c -bg white] -expand 1 -fill both

set m [piemenu .c.m -radius 80 -ringratio 0.333 -roundness 0.75]
set m1 .c.n

$m add command -label back \
	-font {Helvetica 8} \
	-background white \
	-menu $m1
$m add command -label ok \
	-menu unpost
$m add checkbutton -label chk1
$m add checkbutton -label chk2
$m add radiobutton -label rad1
$m add radiobutton -label rad2
$m add radiobutton -label rad3

set m1 [piemenu .c.n -radius 80]
$m1 add command -label ok\n------\ndelayed\nexit \
	-font {Helvetica 8} \
	-menu unpost \
	-background white \
	-delay 500 -delayedcommand exit
$m1 add command -label menu \
	-menu $m
$m1 add command -label + \
	-font {Helvetica 18 bold}
$m1 add command -label - \
	-font {Helvetica 18 bold}

bind .c <Button-1> [list $m1 post %x %y]
  

BUGS

This is a beta version.
Bug reports and patches are welcome.
© 2007, Dmitrios Zachariadis
BSD license