IBM
Contents Index Previous Next



Defining Menus in the SDL Suite


The graphical the SDL Suite tools allow you to define additional menus and menu items that execute external commands or send PostMaster messages. Separate user-defined menus can be defined and added to each graphical tool. However, the pre-defined menus in each tool can not be removed or changed.

User-defined menus are described by menu definition files that are read by the tools when they start up.

It is sometimes more useful to add user-defined menus to the tools after they have been started; this can be accomplished if you use the IBM Rational Public Interface. For more information see Menu Manipulation Services.

Note:

The fact that a set of menus have been defined in a menu definition file, does not prevent using the public interface services to add additional menus, or even to modify the menus that were defined by the menu definition file.

Tools and Menu Definition File Names

Menu definition files must have fixed names that indicate which tool the menus are intended for.

The following tools allow addition of user-defined menus, and also offer the possibility of letting the menu commands access the internal state information of the tool. This is accomplished if you use format codes that are documented separately for each tool in the Public Interface.

Tool Menu definition file name

Organizer

org-menus.ini

MSC Editor

msce-menus.ini

SDL Editor

sdle-menus.ini

OM/SC/HMSC Editor

ome-menus.ini

Text Editor

te-menus.ini

The following tools allow addition of user-defined menus, but do not offer the possibility of accessing the internal state of the tool.

Tool Menu definition file name

Preference Manager

pref-menus.ini

Type Viewer

typ-menus.ini

Coverage Viewer

cover-menus.ini

Index Viewer

xref-menus.ini

Tree Viewer

tree-menus.ini

Simulator/Explorer UI 1

simui-menus.ini

1

In Windows, the Simulator/Explorer UI's can not read menu-definition files.

Menu Definition File Location

On start-up, each tool that supports menu-definition files will search for a menu definition file with the given pre-defined name in up to three locations:

  1. First, the directory from where the SDL Suite was started is searched. If a file with the expected name is found, the tool will attempt to read it and install the menus described therein.
  2. Second, the directory named in the HOME environment variable will be searched. If a file with the expected name is found, it will be used.
  3. Last, the directory where the SDL Suite is installed will be searched (on UNIX, $telelogic/, and in Windows the top installation directory, by default C:\IBM\Rational\SDL_TTCN_Suite6.3).

If no file is found, no user-defined menus will be added on start-up.

Format of Menu Definition Files

A menu definition file is a line-oriented text file separated into sections by lines containing special section markers. Each section contains lines formatted in the same way, containing an option/value pair. Each section describes either a menu or a menu item.

The first line of a menu definition file is a format tag that identifies the file as menu definition file:

SDT-DYNAMICMENUS-6.3

Each section is started by adding a line with a section name between brackets "[ ]". Valid sections in a menu definition file are:

[MENU]
[MENUITEM]
[MENUEND]

[MENU] Section

The menu section starts a new menu. Subsequent [MENUITEM] sections will add a menu item to this menu until a [MENUEND] section is encountered. A [MENU] section should be the first line after the initial tag or follow directly after a [MENUEND] section.

After the [MENU] section tag follows the option below, using the syntax:

Name=NameOfMenu

Option Explanation/Value
Name

A string that contains the name of the menu. The name is presented in the tool's menu bar. The ampersand `&' character may be placed just in front of a letter to indicate that this letter will be underlined in the menu name and thus function as a keyboard shortcut for menu traversal. Make sure that the letter is not used as a shortcut in any other menu in the menu bar, or it may not be possible to open the menu with the keyboard.

[MENUITEM] Section

A [MENUITEM] section must occur between a [MENU] and a [MENUEND] section.

Following the [MENUITEM] section tag is a number of options and their values, using the syntax:

Option=Value

This section adds a menu choice to the specified menu. The menu choice could either perform an OS command or issue a PostMaster notification when selected. The OS command to perform or the message to broadcast could be sensitive on a selected symbol.

The exact interpretation of two of these options (ProprietaryKey and AttributeKey, described below) will depend on which tool the menu will be installed in. In particular, the ProprietaryKey option will only have significance in the Organizer and the graphical editors. The AttributeKey option will only have significance in the graphical editors. If not used these options should be set to 0.

For tools supporting access to internal state information, format codes can be used in the command string or as message parameter, providing additional context-sensitive information.

For more information on options and format codes, see Add Item to Menu.

Option Explanation/Value
ItemName

A string that contains the menu item text that appears in the menu item. Ampersand syntax is supported, as for menu names. Make sure that different letters are selected for each menu item in the menu; otherwise keyboard activation of the menu item may not work.

Separator

A boolean value (0 or 1) that indicates whether a separator (a thin line) should precede the menu item in the menu.

StatusbarText

A string that should be displayed in the tool's status bar while the menu item is selected to hint you about the function of the menu choice.

ProprietaryKey

An integer whose interpretation depends on the tool; the Organizer interprets this parameter as lastAction, and the graphical editors interpret it as ProprietaryKey. For more information, see lastAction and ProprietaryKey.

For the Organizer, you can use either an integer or a symbolic string as the value.

If not used, simply set to 0.

AttributeKey

An integer whose interpretation depends on the tool; the graphical editors interpret this parameter as AttributeKey. For more information, see AttributeKey.

If not used, simply set to 0.

Scope

An enumerated value that indicates when the menu item should be dimmed. For the valid values, see scope. You can use either an integer or a symbolic string as the value.

If not used, simply set to 0.

ConfirmText

A text string that contains a dialog box text. If not empty, this will issue a two button dialog with OK and Cancel buttons and an editable text field containing the command to be performed. You can alter the command text before pressing OK.

ActionInterpretation

An integer value indicating the desired action when a menu item is activated:

PM_MESSAGE (0) - send PostMaster message

OS_COMMAND (1) - execute OS command

BlockCommand

Only significant if Action is set to 1:

A boolean value (0 or 1) indicating whether the Organizer should wait for the execution of the command to complete (1), or allow you to perform other operations while the command executes (0).

FormattedCommand

Only significant if Action is set to 1:

The OS command to perform. Some tools evaluate specific context sensitive format codes.

MessageNumber

Only significant if Action is set to 0:

Indicates the number of the PostMaster message to send.

FormattedMessage

Only significant if Action is set to 0:

The parameters to the PostMaster message. Some tools evaluate specific context sensitive format codes.

[MENUEND] Section

The [MENUEND] section indicates that a menu definition has come to an end and that no more [MENUITEM] sections should appear until a new [MENU] section is encountered. This section has no options.

Example of a Menu Definition File

An example of a typical menu-definition file could be:

SDT-DYNAMICMENUS-3.6
[MENU]
Name=&RCS
[MENUITEM]
ItemName=Check &Out
Separator=0
StatusbarText=Check out the selected object
ProprietaryKey=1
AttributeKey=0
Scope=SELECTED_OBJECT_NOT_IN_EDITOR
ConfirmText=
ActionInterpretation=OS_COMMAND
BlockCommand=1
FormattedCommand=co %f
[MENUEND]

http://www.ibm.com/rational
Contents Index Previous Next