| << Prev | - Up - | Next >> |
A menu is a widget that displays a collection of one-line entries arranged in one or more columns. There exist several different types of entries, each with different properties. Entries of different types may be combined in a single menu. Menu entries are not the same as entry widgets. In fact, menu entries are not even distinct widgets; the entire menu is one widget.
Menu description records are records of the form menu(E1 E2 .. Ex param1:value1 ... paramY:valueY) where Ex are records of the form command(...), checkbutton(...), radiobutton(...), cascade(...) or separator. The first three record types (command, checkbutton and radiobutton) are very similar to the widgets of the same name, and have many parameters in common. The cascade(...) record form is similar to the menu(...) one as that entry pulls out a sub-menu. The separator record inserts an horizontal line.
Menu descriptions usage:
As the menu parameter of the td or lr toplevel widget. This menu's items will be displayed in a menubar accross the top of the window. These menus will behave according to the interface guidelines of their platforms. For every menu set as a menubar, a clone menu is made (see below).
As the menu parameter of a menubutton widget. This is the most usual way of using menu declarations.
As the parameter of the function QTk.buildMenu. This function returns an Oz object representing the described menu. This object can be used as the menu parameter of a menubutton widget, or alternatively be displayed anywhere on the screen using its post method (see below). Warning: QTk.buildMenu requires that the menu description specifies a parent parameter set to a QTk window existing inside the display where the menu is to be posted. Example:
T={QTk.build td(title:"Test")}
M={QTk.buildMenu menu(command(text:"Entry 1")
command(text:"Entry 2")
parent:T)}
{M post(100 100)}CLONES
When a menu is set as a menubar for a toplevel window, or when a menu is torn off, a clone of the menu is made. This clone is a menu widget in its own right, but it is a child of the original. Changes in the configuration of the original are reflected in the clone. Additionally, any cascades that are pointed to are also cloned so that menu traversal will work right. Clones are destroyed when either the tearoff or menubar goes away, or when the original menu is destroyed.
The menu description support the following parameters:
x:R: Where x starts from 1 and goes up one by one. R must be record describing a valid menu entry. This parameter defines the menu's xth entry.
activebackground:C: Specifies the background color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. C must be a valid color (see Section 8.2)
activeforeground:C: Specifies the foreground color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. C must be a valid color (see Section 8.2)
activeborderwidth:P: Specifies a non-negative value indicating the width of the 3-D border to draw around active elements. P must be a valid screen distance (see Section 8.6).
background:C: or bg:C: Specifies the normal background color to use when displaying the widget. C must be a valid color (see Section 8.2).
borderwidth:P: Specifies a non-negative value indicating the width of the 3-D border to draw around the outside of the widget (if such a border is being drawn; the relief option typically determines this). The value may also be used when drawing 3-D effects in the interior of the widget. P must be a valid screen distance (see Section 8.6).
cursor:A: Specifies the mouse cursor to be used for the widget. A must be a valid cursor (see Section 8.7)
disabledforeground:C: Specifies foreground color to use when drawing a disabled element. If the option is specified as an empty string (which is typically the case on monochrome displays), disabled elements are drawn with the normal foreground color but they are dimmed by drawing them with a stippled fill pattern. C must be a valid color (see Section 8.2)
font:F: Specifies the font to use when drawing text inside the widget. This parameter can't be get at runtime, however it can be set. F must be a valid font (see Section 8.8)
foreground:C: or fg:C: Specifies the normal foreground color to use when displaying the widget. C must be a valid color (see Section 8.2)
relief:A: Specifies the 3-D effect desired for the widget. Must be one of these atoms: raised, sunken, flat, ridge, solid or groove. The value indicates how the interior of the widget should appear relative to its exterior; for example, raised means the interior of the widget should appear to protrude from the screen, relative to the exterior of the widget.
takefocus:B: Determines whether the window accepts the focus during keyboard traversal (e.g., Tab and Shift-Tab). Before setting the focus to a window, the traversal mechanims consult the value of the takeFocus option. A value of false means that the widget should be skipped entirely during keyboard traversal. true means that the widget should receive the input focus as long as it is viewable (it and all of its ancestors are mapped). B must be a boolean.
tearoff:B: Specifies whether or not the menu should include a tear-off entry at the top. The default menu bindings arrange for the menu to be torn off when the tear-off entry is invoked. B must be a boolean.
title:VS: Specifies title of the window created when this menu is torn off. If the title is NULL, then the window will have the title of the menubutton or the text of the cascade item from which this menu was invoked.
type:A: This option can be one of the following atoms: menubar, tearoff, or normal, and is set when the menu is created.
action:C: Specifies an Oz command to execute just before the menu is posted.
insert(I T): Inserts the menu entry specified by T at the position the position I of the menu. T must be a record describing a value menu entry, I must be a positive integer.
index(I V): Binds V to the object controlling the menu entry referenced by I, or binds V to the atom none if no menu entry is referenced by I. I can be one of the following:
integer: Specifies the entry numerically, where 1 is the first one (topmost).
active: Indicates the entry that is currently active. If no entry is active then this form is equivalent to none.
end: Indicates the bottommost entry in the menu. If there are no entries in the menu then this form is equivalent to none.
last: Same as end.
none: Indicates ``no entry at all''.
"@"#Y: Where Y is an integer. In this form, Y is treated as a y-coordinate in the menu's window; the entry closest to that y-coordinate is used.
post(X Y): Arrange for the menu 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 menu is visible on the screen.
Menu entries are displayed with up to three separate fields. The main field is a label in the form of a text string, a bitmap, or an image, controlled by the label, bitmap, and image options for the entry. If the accelerator option is specified for an entry then a second textual field is displayed to the right of the label. The accelerator typically describes a keystroke sequence that may be typed in the application to cause the same result as invoking the menu entry. The third field is an indicator. The indicator is present only for checkbutton or radiobutton entries. It indicates whether the entry is selected or not, and is displayed to the left of the entry's string.
In normal use, an entry becomes active (displays itself differently) whenever the mouse pointer is over the entry. If a mouse button is released over the entry then the entry is invoked. The effect of invocation is different for each type of entry; these effects are described below in the sections on individual entries.
Entries may be disabled, which causes their labels and accelerators to be displayed with dimmer colors. The default menu bindings will not allow a disabled entry to be activated or invoked. Disabled entries may be re-enabled, at which point it becomes possible to activate and invoke them again.
Whenever a menu's active entry is changed, a MenuSelect virtual event is send to the menu. The active item can then be queried from the menu, and an action can be taken, such as setting context-sensitive help text for the entry.
A tear-off entry appears at the top of the menu if enabled with the tearoff option of the menu. It is not an entry like others because it is not created the same way. When a tear-off entry is created it appears as a dashed line at the top of the menu. Under the default bindings, invoking the tear-off entry causes a torn-off copy to be made of the menu and all of its submenus.
Description
The most common kind of menu entry is a command entry, which behaves much like a button widget. When a command entry is invoked, the Oz command specified by the action parameter is executed.
A command menu entry is described by a record of the form:
command(parameter1:value1 ... parameterX:valueX)Parameters
activebackground:C: Specifies the background color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. C must be a valid color (see Section 8.2)
activeforeground:C: Specifies the foreground color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. C must be a valid color (see Section 8.2)
background:C: or bg:C: Specifies the normal background color to use when displaying the widget. C must be a valid color (see Section 8.2).
bitmap:B: Specifies a Tk pre-defined bitmap to display in the widget, or a file containing a bitmap description in the standard X11 or X10 format. The exact way in which the bitmap is displayed may be affected by other options such as anchor or justify. Typically, if this option is specified then it overrides other options that specify a textual value to display in the widget; the bitmap option may be reset to an empty string to re-enable a text display. In widgets that support both bitmap and image options, image will usually override bitmap. This parameter can't be get at runtime, however it can be set. B can be one of these atoms: error, gray75, gray50, gray25, gray12, hourglass, info, questhead, question, warning, or B can be a virtual string beginning by @ and then containing the name of a bitmap description in the standard X11 or X10 format like "@x11.xbm" for example.
columnbreak:B: When this option is true, the entry appears below the previous entry. When this option isfalse, the menu appears at the top of a new column in the menu.
font:F: Specifies the font to use when drawing text inside the widget. This parameter can't be get at runtime, however it can be set. F must be a valid font (see Section 8.8)
foreground:C: or fg:C: Specifies the normal foreground color to use when displaying the widget. C must be a valid color (see Section 8.2)
hidemargin:B: Specifies whether the standard margins should be drawn for this menu entry. This is useful when creating palette with images in them, i.e., color palettes, pattern palettes, etc. true indicates that the margin for the entry is hidden; false means that the margin is used.
image:I: Specifies an image or a bitmap built by QTk.newImage to display in the widget. Typically, if the image option is specified then it overrides other options that specify a bitmap or textual value to display in the widget; the image option may be reset to an empty string to re-enable a bitmap or text display. This parameter can't be get at runtime, however it can be set. I must be a valid image or bitmap (see Section 8.4 and see Section 8.3)
state:A: Specifies one of three states for the button: normal, active, 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.
underline:I: Specifies the integer index of a character to underline in the widget. This option is used by the default bindings to implement keyboard traversal for menu buttons and menu entries. 0 corresponds to the first character of the text displayed in the widget, 1 to the next character, and so on. I must be a positive integer.
text:VS: Specifies a string to be displayed inside the widget. The way in which the string is displayed depends on the particular widget and may be determined by other options, such as anchor or justify. VS must be a virtual string.
action:C: Specifies an action to execute right after the user clicked the entry. C can take several different forms (see Section 4.3.1).
accelerator:R: Specifies the keyboard accelerator and event binding to be created for the menu entry. They can be used as follows:
| accelerator | event binding |
|---|---|---|
| a |
|
| C-a |
|
| A-a |
|
| A-C-a |
|
| C-A-a |
|
virtual string | virtual string | none |
return:V: If the execution of the action of the button closes the window, Variable is bound to true. In all other cases where the window is closed, Variable is bound to false. This parameter is valid at creation time only. V must be a free variable.
handle:V: Specifies a variable to reference the object controlling this widget. This variable is bound when the window is built. For more details, see Section 4.2. V must be a free variable.
feature:A: Specifies a feature name for the container object to reference the object controlling this widget. For more details, see Section 4.2. A must be an atom.
Interface
The object controlling the menu entry implements the following methods:
set(parameter1:value1 ... parameterX:valueX): Changes the value of one or more parameters. parameterX must be a valid parameter for the widget. valueX must be a valid value for the parameter.
get(parameter1:Variable1 ... parameterX:VariableX): Obtains the value of one or more parameters. parameterX must be a valid parameter for the widget. VariableX must be free variables that will receive the current value of the parameters.
invoke: Invoke the action of the menu entry. If the menu entry is disabled then nothing happens.
delete: Deletes the menu entry from the menu. Further access to this menu entry will raise errors.
position(Y): Binds Y to a positive integer giving the y-coordinate within the menu window of the topmost pixel of the entry.
type(V): Binds V to the type of the entry (in this case, to command).
Description
A checkbutton menu entry behaves much like a checkbutton widget. When it is invoked it toggles back and forth between the selected and deselected states. An indicator box is displayed to the left of the label in a checkbutton entry. If the entry is selected then the indicator's center is displayed in the color given by the selectcolor option for the entry; otherwise the indicator's center is displayed in the background color for the menu. If an action option is specified for a checkbutton entry, then the Oz command is executed each time the user change the state of the entry; this happens after toggling the entry's selected state.
A checkbutton menu entry is described by a record of the form:
checkbutton(parameter1:value1 ... parameterX:valueX)Parameters
1:B: Specifies whether or not the menu entry is toggled on or off. This option can be used with the set() and get() methods only. B must be a boolean.
init:B: Specifies whether or not the menu entry is toggled on or off. This option can be used at creation time only. B must be a boolean.
activebackground:C: Specifies the background color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. C must be a valid color (see Section 8.2)
activeforeground:C: Specifies the foreground color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. C must be a valid color (see Section 8.2)
background:C: or bg:C: Specifies the normal background color to use when displaying the widget. C must be a valid color (see Section 8.2).
bitmap:B: Specifies a Tk pre-defined bitmap to display in the widget, or a file containing a bitmap description in the standard X11 or X10 format. The exact way in which the bitmap is displayed may be affected by other options such as anchor or justify. Typically, if this option is specified then it overrides other options that specify a textual value to display in the widget; the bitmap option may be reset to an empty string to re-enable a text display. In widgets that support both bitmap and image options, image will usually override bitmap. This parameter can't be get at runtime, however it can be set. B can be one of these atoms: error, gray75, gray50, gray25, gray12, hourglass, info, questhead, question, warning, or B can be a virtual string beginning by @ and then containing the name of a bitmap description in the standard X11 or X10 format like "@x11.xbm" for example.
columnbreak:B: When this option is true, the entry appears below the previous entry. When this option isfalse, the menu appears at the top of a new column in the menu.
font:F: Specifies the font to use when drawing text inside the widget. This parameter can't be get at runtime, however it can be set. F must be a valid font (see Section 8.8)
foreground:C: or fg:C: Specifies the normal foreground color to use when displaying the widget. C must be a valid color (see Section 8.2)
hidemargin:B: Specifies whether the standard margins should be drawn for this menu entry. This is useful when creating palette with images in them, i.e., color palettes, pattern palettes, etc. true indicates that the margin for the entry is hidden; false means that the margin is used.
image:I: Specifies an image or a bitmap built by QTk.newImage to display in the widget. Typically, if the image option is specified then it overrides other options that specify a bitmap or textual value to display in the widget; the image option may be reset to an empty string to re-enable a bitmap or text display. This parameter can't be get at runtime, however it can be set. I must be a valid image or bitmap (see Section 8.4 and see Section 8.3)
indicatoron:B: Specifies whether or not the indicator should be displayed. B must be a boolean.
selectcolor:C: Specifies the color to display in the indicator when the entry is selected. If the value is nil (default) then the selectcolor option for the menu determines the indicator color.
selectimage:I: Specifies an image to display in the entry (in place of the image option) when it is selected. I must be a valid image (see above). This option is ignored unless the image option has been specified.
state:A: Specifies one of three states for the button: normal, active, 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.
underline:I: Specifies the integer index of a character to underline in the widget. This option is used by the default bindings to implement keyboard traversal for menu buttons and menu entries. 0 corresponds to the first character of the text displayed in the widget, 1 to the next character, and so on. I must be a positive integer.
text:VS: Specifies a string to be displayed inside the widget. The way in which the string is displayed depends on the particular widget and may be determined by other options, such as anchor or justify. VS must be a virtual string.
action:C: Specifies an action to execute right after the user clicked the entry. C can take several different forms (see Section 4.3.1).
accelerator:R: Specifies the keyboard accelerator and event binding to be created for the menu entry. They can be used as follows:
| accelerator | event binding |
|---|---|---|
| a |
|
| C-a |
|
| A-a |
|
| A-C-a |
|
| C-A-a |
|
virtual string | virtual string | none |
return:V: When the toplevel window is closed, V is bound to true is the menu entry is selected, otherwise it is bound to false.
handle:V: Specifies a variable to reference the object controlling this widget. This variable is bound when the window is built. For more details, see Section 4.2. V must be a free variable.
feature:A: Specifies a feature name for the container object to reference the object controlling this widget. For more details, see Section 4.2. A must be an atom.
Interface
The object controlling the menu entry implements the following methods:
set(parameter1:value1 ... parameterX:valueX): Changes the value of one or more parameters. parameterX must be a valid parameter for the widget. valueX must be a valid value for the parameter.
get(parameter1:Variable1 ... parameterX:VariableX): Obtains the value of one or more parameters. parameterX must be a valid parameter for the widget. VariableX must be free variables that will receive the current value of the parameters.
invoke: Invoke the action of the menu entry. If the menu entry is disabled then nothing happens.
delete: Deletes the menu entry from the menu. Further access to this menu entry will raise errors.
position(Y): Binds Y to a positive integer giving the y-coordinate within the menu window of the topmost pixel of the entry.
type(V): Binds V to the type of the entry (in this case, to checkbutton).
Description
A radiobutton menu entry behaves much like a radiobutton widget. Radiobutton entries are organized in groups along with the radiobutton and tbradiobutton widgets. Widgets are grouped together if their group parameters are set to the same atom. Only one entry of a group may be selected at a time. An indicator diamond is displayed to the left of the label in each radiobutton entry. If the entry is selected then the indicator's center is displayed in the color given by the selectcolor option for the entry; otherwise the indicator's center is displayed in the background color for the menu. If an action option is specified for a radiobutton entry, then the specified Oz command is executed just after the user selects the entry.
A radiobutton menu entry is described by a record of the form:
radiobutton(parameter1:value1 ... parameterX:valueX)Parameters
1:B: Specifies if the button is on or off. If B is true then the button is selected. All other radiobuttons in the same group are deselected. If B is false then the button is deselected. This can end in no radiobutton in the same group selected at all. This parameter can be used with the set() and get() methods only. B must be a boolean.
init:B: Specifies if the button is on or off. If B is true then the button is selected. All other radiobuttons in the same group are deselected. If B is false then the button is deselected. This can end in no radiobutton in the same group selected at all. This parameter is valid at creation time only. B must be a boolean.
return:V: When the window is closed, V is bound to true if the radiobutton, false otherwise. This parameter is valid at creation time only. V must be a free variable.
action:C: Specifies an action to execute right after the user clicked the button. C can take several different forms (see Section 4.3.1).
group:A: Specifies what group the radiobutton belongs to. All radiobuttons that use the same A belong to the same group (only one can be selected at a time in a group). Must be specified at creation time. A must be an atom.
activebackground:C: Specifies the background color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. C must be a valid color (see Section 8.2)
activeforeground:C: Specifies the foreground color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. C must be a valid color (see Section 8.2)
background:C: or bg:C: Specifies the normal background color to use when displaying the widget. C must be a valid color (see Section 8.2).
bitmap:B: Specifies a Tk pre-defined bitmap to display in the widget, or a file containing a bitmap description in the standard X11 or X10 format. The exact way in which the bitmap is displayed may be affected by other options such as anchor or justify. Typically, if this option is specified then it overrides other options that specify a textual value to display in the widget; the bitmap option may be reset to an empty string to re-enable a text display. In widgets that support both bitmap and image options, image will usually override bitmap. This parameter can't be get at runtime, however it can be set. B can be one of these atoms: error, gray75, gray50, gray25, gray12, hourglass, info, questhead, question, warning, or B can be a virtual string beginning by @ and then containing the name of a bitmap description in the standard X11 or X10 format like "@x11.xbm" for example.
columnbreak:B: When this option is true, the entry appears below the previous entry. When this option isfalse, the menu appears at the top of a new column in the menu.
font:F: Specifies the font to use when drawing text inside the widget. This parameter can't be get at runtime, however it can be set. F must be a valid font (see Section 8.8)
foreground:C: or fg:C: Specifies the normal foreground color to use when displaying the widget. C must be a valid color (see Section 8.2)
hidemargin:B: Specifies whether the standard margins should be drawn for this menu entry. This is useful when creating palette with images in them, i.e., color palettes, pattern palettes, etc. true indicates that the margin for the entry is hidden; false means that the margin is used.
image:I: Specifies an image or a bitmap built by QTk.newImage to display in the widget. Typically, if the image option is specified then it overrides other options that specify a bitmap or textual value to display in the widget; the image option may be reset to an empty string to re-enable a bitmap or text display. This parameter can't be get at runtime, however it can be set. I must be a valid image or bitmap (see Section 8.4 and see Section 8.3)
indicatoron:B: Specifies whether or not the indicator should be displayed. B must be a boolean.
selectcolor:C: Specifies the color to display in the indicator when the entry is selected. If the value is nil (default) then the selectcolor option for the menu determines the indicator color.
selectimage:I: Specifies an image to display in the entry (in place of the image option) when it is selected. I must be a valid image (see above). This option is ignored unless the image option has been specified.
state:A: Specifies one of three states for the button: normal, active, 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.
underline:I: Specifies the integer index of a character to underline in the widget. This option is used by the default bindings to implement keyboard traversal for menu buttons and menu entries. 0 corresponds to the first character of the text displayed in the widget, 1 to the next character, and so on. I must be a positive integer.
text:VS: Specifies a string to be displayed inside the widget. The way in which the string is displayed depends on the particular widget and may be determined by other options, such as anchor or justify. VS must be a virtual string.
accelerator:R: Specifies the keyboard accelerator and event binding to be created for the menu entry. They can be used as follows:
| accelerator | event binding |
|---|---|---|
| a |
|
| C-a |
|
| A-a |
|
| A-C-a |
|
| C-A-a |
|
virtual string | virtual string | none |
handle:V: Specifies a variable to reference the object controlling this widget. This variable is bound when the window is built. For more details, see Section 4.2. V must be a free variable.
feature:A: Specifies a feature name for the container object to reference the object controlling this widget. For more details, see Section 4.2. A must be an atom.
Interface
The object controlling the menu entry implements the following methods:
set(parameter1:value1 ... parameterX:valueX): Changes the value of one or more parameters. parameterX must be a valid parameter for the widget. valueX must be a valid value for the parameter.
get(parameter1:Variable1 ... parameterX:VariableX): Obtains the value of one or more parameters. parameterX must be a valid parameter for the widget. VariableX must be free variables that will receive the current value of the parameters.
invoke: Invoke the action of the menu entry. If the menu entry is disabled then nothing happens.
delete: Deletes the menu entry from the menu. Further access to this menu entry will raise errors.
position(Y): Binds Y to a positive integer giving the y-coordinate within the menu window of the topmost pixel of the entry.
type(V): Binds V to the type of the entry (in this case, to radiobutton).
Description
A cascade entry is one with an associated menu (determined by the menu option). Cascade entries allow the construction of cascading menus.
A cascade menu entry is described by a record of the form:
cascade(parameter1:value1 ... parameterX:valueX)Parameters
activebackground:C: Specifies the background color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. C must be a valid color (see Section 8.2)
activeforeground:C: Specifies the foreground color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. C must be a valid color (see Section 8.2)
background:C: or bg:C: Specifies the normal background color to use when displaying the widget. C must be a valid color (see Section 8.2).
bitmap:B: Specifies a Tk pre-defined bitmap to display in the widget, or a file containing a bitmap description in the standard X11 or X10 format. The exact way in which the bitmap is displayed may be affected by other options such as anchor or justify. Typically, if this option is specified then it overrides other options that specify a textual value to display in the widget; the bitmap option may be reset to an empty string to re-enable a text display. In widgets that support both bitmap and image options, image will usually override bitmap. This parameter can't be get at runtime, however it can be set. B can be one of these atoms: error, gray75, gray50, gray25, gray12, hourglass, info, questhead, question, warning, or B can be a virtual string beginning by @ and then containing the name of a bitmap description in the standard X11 or X10 format like "@x11.xbm" for example.
columnbreak:B: When this option is true, the entry appears below the previous entry. When this option isfalse, the menu appears at the top of a new column in the menu.
font:F: Specifies the font to use when drawing text inside the widget. This parameter can't be get at runtime, however it can be set. F must be a valid font (see Section 8.8)
foreground:C: or fg:C: Specifies the normal foreground color to use when displaying the widget. C must be a valid color (see Section 8.2)
hidemargin:B: Specifies whether the standard margins should be drawn for this menu entry. This is useful when creating palette with images in them, i.e., color palettes, pattern palettes, etc. true indicates that the margin for the entry is hidden; false means that the margin is used.
image:I: Specifies an image or a bitmap built by QTk.newImage to display in the widget. Typically, if the image option is specified then it overrides other options that specify a bitmap or textual value to display in the widget; the image option may be reset to an empty string to re-enable a bitmap or text display. This parameter can't be get at runtime, however it can be set. I must be a valid image or bitmap (see Section 8.4 and see Section 8.3)
state:A: Specifies one of three states for the button: normal, active, 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.
underline:I: Specifies the integer index of a character to underline in the widget. This option is used by the default bindings to implement keyboard traversal for menu buttons and menu entries. 0 corresponds to the first character of the text displayed in the widget, 1 to the next character, and so on. I must be a positive integer.
text:VS: Specifies a string to be displayed inside the widget. The way in which the string is displayed depends on the particular widget and may be determined by other options, such as anchor or justify. VS must be a virtual string.
action:C: Specifies an action to execute right after the user clicked the entry. C can take several different forms (see Section 4.3.1).
accelerator:R: Specifies the keyboard accelerator and event binding to be created for the menu entry. They can be used as follows:
| accelerator | event binding |
|---|---|---|
| a |
|
| C-a |
|
| A-a |
|
| A-C-a |
|
| C-A-a |
|
virtual string | virtual string | none |
menu:O: Specifies the menu that is posted when the user selects the cascade entry. O must be a record describing a proper menu. See Section 8.10 for menu details.
handle:V: Specifies a variable to reference the object controlling this widget. This variable is bound when the window is built. For more details, see Section 4.2. V must be a free variable.
feature:A: Specifies a feature name for the container object to reference the object controlling this widget. For more details, see Section 4.2. A must be an atom.
Interface
The object controlling the menu entry implements the following methods:
set(parameter1:value1 ... parameterX:valueX): Changes the value of one or more parameters. parameterX must be a valid parameter for the widget. valueX must be a valid value for the parameter.
get(parameter1:Variable1 ... parameterX:VariableX): Obtains the value of one or more parameters. parameterX must be a valid parameter for the widget. VariableX must be free variables that will receive the current value of the parameters.
invoke: Invoke the action of the menu entry. If the menu entry is disabled then nothing happens.
delete: Deletes the menu entry from the menu. Further access to this menu entry will raise errors.
position(Y): Binds Y to a positive integer giving the y-coordinate within the menu window of the topmost pixel of the entry.
type(V): Binds V to the type of the entry (in this case, to cascade).
Description
A separator is an entry that is displayed as a horizontal dividing line. A separator may not be activated or invoked, and it has no behavior other than its display appearance.
A separator menu entry is described by a record of the form:
separator(parameter1:value1 ... parameterX:valueX)Parameters
columnbreak:B: When this option is true, the entry appears below the previous entry. When this option isfalse, the menu appears at the top of a new column in the menu.
hidemargin:B: Specifies whether the standard margins should be drawn for this menu entry. This is useful when creating palette with images in them, i.e., color palettes, pattern palettes, etc. true indicates that the margin for the entry is hidden; false means that the margin is used.
handle:V: Specifies a variable to reference the object controlling this widget. This variable is bound when the window is built. For more details, see Section 4.2. V must be a free variable.
feature:A: Specifies a feature name for the container object to reference the object controlling this widget. For more details, see Section 4.2. A must be an atom.
Interface
The object controlling the menu entry implements the following methods:
set(parameter1:value1 ... parameterX:valueX): Changes the value of one or more parameters. parameterX must be a valid parameter for the widget. valueX must be a valid value for the parameter.
get(parameter1:Variable1 ... parameterX:VariableX): Obtains the value of one or more parameters. parameterX must be a valid parameter for the widget. VariableX must be free variables that will receive the current value of the parameters.
type(V): Binds V to the type of the entry (in this case, to separator).
| << Prev | - Up - | Next >> |