Using the Menu Editor

Index

Introduction
Starting the Menu Editor
Menu Structure
Functions of the Menu Editor
Description of the Menu
Recent Changes

Introduction

The ST/X Menu Editor allows you to build hierarchical menu structures for:

Window Applications (menu bars)
Widgets (popup menus)
Tool Bars

For each of them, components are defined in the Menu Editor using the same mechanism and operations.

The Menu Editor generates a resource method which contains and returns the menu specification. This method is typically created in the menu specs-category of the class protocol. It returns a symbolic representation (literal array) of the menu components and their behavior. The menu resource methods are invoked by the UIBuilder when the application's window is created for those widgets which define a menu aspect.

Of course, menu-specifications can also be converted to a real menu programmatically; by sending the #decodeAsLiteralArray-message to the spec (as returned by a spec method), a corresponding menu object is retrieved.

Starting the Menu Editor

There are multiple ways to start a Menu Editor:

by clicking on the -button, or by selecting the "Tools"-"Menu Editor item of the launcher's menu.

by pressing the Menu-button in the Basics-section in the GUI Builder. This functionality is available for the main-window (to define the application's pull-down window) and for all those widgets which provide support for a popup menu (textViews, for example).

in a System Browser, by double-clicking on a resource method which contains a menu specification. These methods are marked with a icon.

by evaluating one of the following Smalltalk expressions:

MenuEditor open
MenuEditor openOnClass:anApplicationClass andSelector:aMenuSelector

After startup, a Menu Editor appears as shown in next figure:

A View of a Menu Editor

Menu Structure

Menus consist of a hierarchical collection of MenuItems, which can be regular menu items, separators and submenus.
Submenus can be either defined directly inside a menu definition, or indirectly, by referring to another menu specification (so called linked-menus).
The attributes of these menu components are described in more detail below.

Functions of the Menu Editor

The Menu Editor offers all functions for loading, saving, and modifying menu specifications. The basic functions can be accessed both by the menu and the tool bar. The basic functions are as follows:

Menu	Button	Description
File/Load		Opens a dialog to load a menu spec from a class.
File/Save		Saves the current menu spec and (if modified) also saves the help spec.

Edit/Cut		Cuts the selected item(s) and places it/them into clipboard.
Edit/Copy		Copies the selected item(s) to the clipboard.
Edit/Paste		Pastes the contents of the clipboard.

Edit/Move Up		Moves the selected item one step up (towards the top of the menu).
Edit/Move Down		Moves the selected item one step down (towards the end of the menu).
Edit/Move Into Next		Moves the selected item into the next item (which must be a submenu).
Edit/Move Into Previous		Moves the selected item into the previous item (which must be a submenu).
Edit/Move Out		Moves the selected item out of its submenu (i.e. into the parent menu).

Add/Separator		Adds a new menu separator.
Add/Menu Item		Adds a new regular menu item. The items action will be performed when the item is activated (can be defined to activate on press or release).
Add/Slice		Adds a menu slice. A slice is a partial menu and embedded (sliced-into) the menu. (In contrast to submenus, slices are embedded right into the current menu instead of popping up a submenu).
Add/Submenu		Adds a new submenu. The submenus definition will be embedded in the edited menu spec.
Add/Linked Submenu		Adds a new linked submenu. The submenus definition will be requested dynamically from the application, by sending a configured message.

Add/Delayed Submenu		Adds a delayed submenu under the current selected item. Delayed menus have both an action and a submenu. If pressed only for a short time, the action will be preformed. If the mouse button is held down for a longer time, a menu will appear.
Add/Delayed Linked Submenu		Adds a delayed linked submenu under the current selected item. This is typically used for "back-in-history" type of menus.

Further, there are functions from the menu:

File Menu	Description
File/New	Creates a new empty menu spec.
File/Load	Opens a dialog to load a menu spec from a class.
File/Save As	Opens a dialog to save the current menu spec.
File/Pick A Menu...	Lets the user pick a menus definition from an existing menu as present on the screen. Changes the cursor to a cross-hair-cursor to indicate that the user should click on a menu.
File/Show Menu Spec	Displays the current menu spec in a textView (for debugging purposes).
File/Browse Class	Opens a System Browser on the class which contains the edited menu spec.
File/Exit	Exits the Menu Editor.

Test Menu	Description
Test/...	Shows a menu preview of the current menu spec.

History Menu	Description
History/...	Switch to a previously edited menu spec.

The editing of properties of the menu components is described in the next chapter.

Description of the Menu

After creating or loading of a menu specification the menu and its components are displayed in the tree view on the left side of the Menu Editor. The root item of the tree represents the menu itself. This single item is always shown, even if no menu is loaded. The only purpose of this item is to hold the menu spec selector. This selector must also be defined as the menu selector of the corresponding component in the GUI Painter.
If the item is selected, the user is able to configure the selector of the menu under which the generated menu spec is saved.

The basic menu components from which a menu can be constructed are:

Menu Item with an action:

The main attribute of a this item is its action selector; this specifies the name of a method (in your application) which is invoked when the item is selected.

Basic Properties:

If the selector is for a two-argument message, the views controller
is passed as second argument, if the view has a controller;
otherwise, the view itself is passed.
2-arg selectors are supported for VisualWorks compatibility, and normally not used in ST/X.

Name Key Unique identifier of the item (optional).

Label Label of the item.

Action The name (i.e. selector) of the method which is invoked when the item is selected.
Typically, the selector specifies a zero-argument method name.
However, if the selector is for a one-argument method, the argument passed is:
- the 'argument' fields value (see below) if not empty
- otherwise, the boolean toggle state, if the item has an indication.
- otherwise, the menu item itself.

Argument An argument passed to above selector, if the selector is for a 1-arg message.

Indication If defined, the menu item is displayed as a check toggle.
Typically, the name of a method (in your application) is specified here, which returns a Boolean instance or a boolean ValueHolder.
However, it is also possible to place a boolean ValueHolder or a Block which returns a Boolean instance into the applications aspect bindings directory (instead of defining a method).
Choice and Indication are mutually exclusive.

Choice If defined, the menu item is displayed as a radio button.
Typically, the name of a method (in your application) is specified here, which returns a ValueHolder.
Choice and Indication are mutually exclusive.

Value Defines the choice-value, if the item was defined as a choice item (i.e. the choice field is non-empty).
This is the value which is placed into the choice value holder, whenever the item is selected.

Translate Label Turns on/off translation behavior of the label via the application classes resource file (i.e. national strings).

Is Button If on, the item is displayed as a button; if off, it is displayed as a normal menu item. Setting this flag for all items results in a menu which looks like a button panel (as in the launcher).

Trigger On Down The item's action is performed on mouse button pressed;
the default is on button release.

Hide after Activation If on, the menu hides itself (i.e. closes) when the item is activated.
If off, it remains open.
Turing it off only makes sense with checkBox and radioButton items;
(i.e. with non-empty indication or choice aspects)

BusyCursor while active If on, a wait-cursor is shown in the
application while the items action is performing.

Send to Originating Widget If on, the action-message is sent to the originating widget; if off (the default), it is sent to the application.
This is useful if an application sets an explicit menu for a TextEditor or InputField widget, and wants the widget to deal with (some of) its own text editing functions; for example, the copy/cut/paste messages are usually better handled directly by the widget instead of routing them through the application.

Accelerator	Shortkey to select the menu item from the keyboard. Typically something like Cmdx or Ctrlx is defined here.
Enabled	A boolean `ValueHolder` to enable/disable the menu item.
Visibility	A boolean `ValueHolder` which controls the visibility of the menu item.
Aux Value	An arbitrary value, which is stored in the item, and can be used to mark labels or pass additional information. Can only be extracted programatically (i.e. by scanning the menus items)
Start Group	Indicates whether this item starts a new item group. Currently, the only supported group attribute is right, which places this item group towards the right border of the menu. Additional group properties are planned in the future.
Access Character Position	Index of the access character position of the textual label (optional). This character will be underlined. WARNING: If labels are translated (to national variants), the usefulness of this field is very limited. Therefore, we recommend leaving this field blank, and using an ampersand character in the items label instead.
Font	Set a specific font to the item. On default the font derives from the style sheet. .

Retriever	Typically, the class implementing the image resource method. If no class is given, the current application class will be asked for the image.
Selector	Selector of the method returning the image.
Image & Label	Turns on/off displaying both image and textual label.
Image Editor	Opens an Image Editor on the current Image.

assigne a specific help text found under a key to the item.
For more information see document:"Using the Help Tool"

Separator:

Separators are used to structure a menu into group.

Basic Properties:

Separator List of valid separators. There are currently 3 types of separators available:
blanks, single lines and double lines.

Visibility A boolean ValueHolder which controls the visibility of the separator.

Start Group Specify start of right-aligned item group.
-> see Menu Item.

Submenu:

Submenus are fixed containers holding other menu items.

Basic Properties:

Name Key Unique identifier of the submenu (optional).
-> see Menu Item.

Label Label of the submenu.
-> see Menu Item.

Translate Label Turns on/off translation behavior of the label.
-> see Menu Item.

Is Button Turns on/off displaying as a button.
-> see Menu Item.

Has Horizontal Layout If on, the submenu organizes its items horizontal
insteat of vertical (the default).

-> see menu item

Linked Submenu:

To avoid very large menu specifications, linked submenus can be used to embed submenus provided by other menu resource methods or value holders. Using linked submenus, it is possible to build a menu by assembling a base menu frame with reusable submenu building blocks.

Basic Properties:

Name Key Unique identifier of the linked submenu (optional).
-> see Menu Item.

Label Label of the linked submenu.
-> see Menu Item.

Menu A selector or a ValueHolder instance providing the submenu to be
opened if the item is selected.

Argument An optional argument which is passed with the above menu selector
(selector must be for a one-argument method).

Translate Label Turns on/off translation behavior of the label.
-> see Menu Item.

Is Button Turns on/off displaying as a button.
-> see Menu Item.

Has Horizontal Layout If on, the submenu organizes its items horizontal
insteat of vertical (the default).

Do not destroy linked Menu If on, the submenu will only be acquired once from the application.
When closed, the linked submenu will be remembered and reused,
when the linked submenu is to be opened later.
The default is to ask the application whenever the submenu is selected.
Turning this on (i.e. remembering the menu) is useful, if the creation
of the menu is time- or resource consuming.
It should be turned off, of the submenus items are created dynamically (for example, a history menu).

-> see menu item

Delayed Submenu:

A submenu which is assigned to an item with an user defined action. If the item is selected by a mouse click, a timer is started. If the timer expires before the button is released, the action assigned to the item is performed. Otherwise the delayed submenu will be opened.

Basic Properties:

Has Horizontal Layout If on, the submenu organizes its items horizontal
insteat of vertical (the default).

Delayed Linked Submenu:

A linked submenu which is assigned to an item with an user defined action. If the item is selected by a mouse click, a timer is started. If the timer expires before the button is released, the action assigned to the item is performed. Otherwise the delayed submenu will be opened.

Basic Properties:

Menu A selector or a ValueHolder instance providing the submenu to be
opened if the item is selected.

Has Horizontal Layout If on, the submenu organizes its items horizontal
insteat of vertical (the default).

Do not destroy linked Menu If on, the submenu will not be destroyed after the first time
get from the application.
The default is to ask every time the item is selected the application
for the submenu.

Menu-Slice:

A menu slice is defined similar to a linked menu, by defining a retrieval path for another menu specification. However, in contrast to linked menus, the items of a menu slice are added to the current menu (sliced into) whereas a submenu defines a popUp-menu.
Using menu-slices, it is possible to build a menu by assembling a menu from reusable building blocks and avoids duplication of code (menu-dfinitions).

Basic Properties:

Name Key Unique identifier of the slice (optional).
-> see Menu Item.

Menu A selector or a ValueHolder instance providing the slice containing items which are
added to the menu at the slice-items position.

Argument An optional argument which is passed with the above menu selector
(selector must be for a one-argument method).

Recent Changes

5.2.3
Added support for Menu-Slices.

rel4.1.5
Added "send to originating widget" option.
Added support for delayed menus (i.e. pull-down menu if pressed for a while).

Name Key	Unique identifier of the item (optional).
Label	Label of the item.
Action	The name (i.e. selector) of the method which is invoked when the item is selected. Typically, the selector specifies a zero-argument method name. However, if the selector is for a one-argument method, the argument passed is: - the 'argument' fields value (see below) if not empty - otherwise, the boolean toggle state, if the item has an indication. - otherwise, the menu item itself.
Argument	An argument passed to above selector, if the selector is for a 1-arg message.
Indication	If defined, the menu item is displayed as a check toggle. Typically, the name of a method (in your application) is specified here, which returns a `Boolean` instance or a boolean `ValueHolder`. However, it is also possible to place a boolean `ValueHolder` or a `Block` which returns a `Boolean` instance into the applications aspect bindings directory (instead of defining a method). Choice and Indication are mutually exclusive.
Choice	If defined, the menu item is displayed as a radio button. Typically, the name of a method (in your application) is specified here, which returns a `ValueHolder`. Choice and Indication are mutually exclusive.
Value	Defines the choice-value, if the item was defined as a choice item (i.e. the choice field is non-empty). This is the value which is placed into the choice value holder, whenever the item is selected.

Translate Label	Turns on/off translation behavior of the label via the application classes resource file (i.e. national strings).
Is Button	If on, the item is displayed as a button; if off, it is displayed as a normal menu item. Setting this flag for all items results in a menu which looks like a button panel (as in the launcher).
Trigger On Down	The item's action is performed on mouse button pressed; the default is on button release.
Hide after Activation	If on, the menu hides itself (i.e. closes) when the item is activated. If off, it remains open. Turing it off only makes sense with checkBox and radioButton items; (i.e. with non-empty indication or choice aspects)
BusyCursor while active	If on, a wait-cursor is shown in the application while the items action is performing.
Send to Originating Widget	If on, the action-message is sent to the originating widget; if off (the default), it is sent to the application. This is useful if an application sets an explicit menu for a TextEditor or InputField widget, and wants the widget to deal with (some of) its own text editing functions; for example, the copy/cut/paste messages are usually better handled directly by the widget instead of routing them through the application.

Separator	List of valid separators. There are currently 3 types of separators available: blanks, single lines and double lines.
Visibility	A boolean `ValueHolder` which controls the visibility of the separator.
Start Group	Specify start of right-aligned item group. -> see Menu Item.

Name Key	Unique identifier of the submenu (optional). -> see Menu Item.
Label	Label of the submenu. -> see Menu Item.

Name Key	Unique identifier of the linked submenu (optional). -> see Menu Item.
Label	Label of the linked submenu. -> see Menu Item.
Menu	A selector or a `ValueHolder` instance providing the submenu to be opened if the item is selected.
Argument	An optional argument which is passed with the above menu selector (selector must be for a one-argument method).

Has Horizontal Layout	If on, the submenu organizes its items horizontal insteat of vertical (the default).
Do not destroy linked Menu	If on, the submenu will not be destroyed after the first time get from the application. The default is to ask every time the item is selected the application for the submenu.

Name Key	Unique identifier of the slice (optional). -> see Menu Item.
Menu	A selector or a `ValueHolder` instance providing the slice containing items which are added to the menu at the slice-items position.
Argument	An optional argument which is passed with the above menu selector (selector must be for a one-argument method).