![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Menu Files The menus that appear on and pop up from Apex windows are the result of processing a sequence of menu files. Menu files are text files that define the layout of menus. Apex allows you to customize them.
The following topics are covered in this chapter:
- Menu Filenames
- Menu File Syntax
- Menu Components
- Menu Item Names
- Commands
- Aliases
- Action Clauses
- Creating a Graphical Menu Item
How Apex Looks for Menu FilesApex looks for menu files in the colon-separated sequence of directories specified by the APEX_MENUS_PATH session switch. By default, apexinit initializes it to:
$APEX_HOME/editor_files:$HOME/.Rational
The first directory —— usually $APEX_HOME/editor_files —— contains the standard menu files. Succeeding directories, if present, can contain menu files that incrementally change the standard menus. $HOME/.Rational is the directory in which individual users can make personal changes.
For additional information on the apexinit command, open an Apex shell (Tools > Shell) and enter:
man apexinit
Changing Menus for Personal Use
To make personal changes, create customized menu files in the .Rational subdirectory under your home directory. (Menu files are described in more detail in the remainder of this chapter.) Your changes will appear the next time you start Apex.
Note: The APEX_MENUS_PATH environment variable is automatically initialized to include $HOME/.Rational, so you do not need reset it unless you want to place menu files somewhere else.
Changing Menus for All Users
To make local changes for all users at your site:
- 1 . If you do not already have one, create a local customization directory referred to as local_dir, which is visible to all users at your site.
- 2 . Create the subdirectory local_dir/editor_files.
- 3 . Create customized menu files in local_dir/editor_files.
- 4 . Have each user set the APEX_LOCAL_DIR session switch to local_dir. Then, because local_dir contains an editor_files subdirectory, apexinit will initialize APEX_MENUS_PATH to:
Menu FilenamesMenus are associated with a particular Apex server. Thus, menu filenames are of the form server_menus, where server is one of: ada (Ada only), debugger, directory, output, or text. The C/C++ editor uses the text menus (C/C++ only).
The standard menu file associated with each server in the $APEX_HOME/editor_files directory:
- ada_menus defines the menus for Ada editor windows (Ada only).
- debugger_menus defines the menus for debugger windows, including assembly, breakpoints, exceptions, log, memory, monitors, registers, stack, tasks, and units windows.
- directory_menus defines the menus for directory-viewer windows.
- output_menus defines the menus for jobs and output windows.
- text_menus defines the menus for text editor windows and also difference, notes, and version windows. The C/C++ editor uses the text menus (C/C++ only).
Directories such as local_dir/editor_files and $HOME/.Rational can contain menu files with any or all of these names, depending on which sets of menus you want to customize.
The last directory listed on APEX_MENUS_PATH —— usually $HOME/.Rational —— can also contain a file named menus. If it is present, every server reads it. Thus, the menus file can contain commands that change the menus for all servers.
Note: A menus file in a directory that is listed anywhere other than last on APEX_MENUS_PATH is ignored by all servers.
Restarting Apex Servers
Changes to menu files take effect the next time you start the Apex servers with which they are associated. Exiting Apex quits all of your Apex servers, and starting Apex restarts all of your Apex servers.
You can also quit individual Apex servers without exiting Apex. To kill a server:
- 1 . Bring up the Servers window:
- a .
Display the Jobs window by executing the Navigate > Jobs command from most windows.- b .
Display the Servers window by executing the Navigate > Servers command from the Jobs window.- 2 . Select the server that you want to kill in the Servers window as illustrated in Figure 35.
Figure 35 Server Window
![]()
- 3 . Execute the File > Kill command.
The server that you killed restarts automatically when it is needed. Activities that restart servers are described in Table 14.
Menu File SyntaxThe standard menu files in $APEX_HOME/editor_files are written in a hierarchical nested syntax used for defining entire menus. Customized menu files that you create are written in an incremental modification syntax used for defining changes that you want to make relative to the standard menus.
In menu files, a number sign (#) begins a comment; the comment continues to the end of the line. A backslash (\) is used to continue a command on the next line. You can include commands from other menu files by inserting #include commands in your menu file:
#include filename
The included filename can be the simple name of another menu file in the same directory as your menu file, or it can be the fully qualified name of another menu file in an arbitrary location. The filename can contain UNIX environment variables.
Menu ComponentsMenu files deal with the following basic controls: cascade buttons, push buttons, toggle buttons, and separators. Their names, shown in Table 15, appear in the standard menu files and in menu-manipulation commands in customized menu files.
Menu Item NamesMenu components are grouped or nested to form menu items. The items that make up menus have unique, fully qualified names. A fully qualified menu item name consists of the following, separated by periods (.):
- The window kind:
- If the server creates only one kind of window, the window kind is the server name.
- If the server creates more than one kind of window, the window kind is the server name, followed by a period, followed by the kind of window —— for example: text.difference.
- The name of the top-level menu (or pop-up menu for the window's pop-up menu).
- The names of any submenus.
- The simple name of the menu item.
text.control.checkOut directory.imports.control.objTools.import directory.popupmenu.visit
The window kind can be represented by an asterisk (*), which is a wildcard for "any window." For example, you could put *.file.new in your $HOME/.Rational/menus file to represent File > New on any window.
These menu item names are internal names; you do not see them on the screen. Each menu item also has a label string and a mnemonic associated with it. The label string is the text that appears on the screen, for example, as the user-visible name of a menu button. The mnemonic is the underlined letter in the label string that can be used as a keyboard shortcut.
Note: Accelerators are not mentioned here because they are specified by X Window System resources, not menu files. See Mnemonics and Accelerator Keys for more details.
Internal names are usually derived from the label string by:
- Removing the trailing ellipsis and spaces between words (if any)
- Converting the first word to all lowercase letters
- Capitalizing the first letter of any subsequent words
For example, the label string Check In... is reduced to the internal name checkIn. To find the name of any existing menu item, consult the menu files in $APEX_HOME/editor_files.
CommandsCommands to manipulate existing menus consist of a keyword that starts on a new line followed by arguments on the same line. The following sections describe commands for:
- Changing a label string
- Deleting, appending, inserting, and replacing a menu item
- Moving a menu
- Changing the default behavior of a menu item so that it does not raise a dialog box
- Replicating a menu
- Creating a goto menu
Changing a Label String
The command to change a label string is:
replacecomponent name new_label_string
[mnemonic
]
- component is cascade, pushbutton, or togglebutton.
- name is a menu-item name of the form described in Menu Item Names.
- new_label_string is any string. It must have double quotes if it is not a single word —— that is, if it contains white space.
- mnemonic is a single character that occurs in the new label string. It is optional, as indicated by the brackets, which do not appear in the command.
For example, to change the label string of the directory viewer's Navigate menu from "Navigate" to "Browse," place the following command in your directory_menus file:
replace cascade directory.navigate Browse B
The label string of a menu button also appears in the button bar when that menu button is placed in the button bar (as described in Button Bars). To fit more buttons into a single row on the button bar, shorten their label strings.
For example, to change "Check In..." and "Check Out..." to "In..." and "Out..." on all Control menus, you could place the following commands in your menus file:
replace pushbutton *.control.checkIn "In..." I replace pushbutton *.control.checkOut "Out..." O
If a button on a menu or button bar also appears on a pop-up menu, you need to change the label string on the pop-up menu separately. For example:
replace pushbutton *.popupmenu.visit "vis"
Deleting a Menu Item
The command to delete a menu item is:
deletecomponent name
- component is cascade, pushbutton, togglebutton, or separator.
- name is a menu item name of the form described in Menu Item Names.
For example, users who are never responsible for controlling or uncontrolling objects could place the following commands in their menus files:
delete pushbutton *.control.objTools.control delete pushbutton *.control.objTools.uncontrol
Positional Deletions
Items can also be deleted positionally:
deleteposition name
- position is the numerical position within the menu of the item to delete. The first item is numbered 0.
- name is a menu item name of the form described in Menu Item Names.
Appending a Menu Item
The command to append a menu item is:
appendcomponent name label_string
[mnemonic
]
- component is cascade, pushbutton, togglebutton, or separator.
- name is a menu item name of the form described in Menu Item Names.
- label_string is any string, and it is required except when component is separator. It must have double quotes if it is not a single word —— that is, if it contains white space.
- mnemonic is a single character that occurs in the label string. It is optional, as indicated by the brackets (which do not appear in the command).
For example, to add your own tool to the bottom of all Tools menus:
append pushbutton *.tools.myTool "My Tool" M
Inserting a Menu Item
The command to insert a menu item is:
insertposition component name label_string
[mnemonic
]
- position is the numerical position at which to insert the item. The first menu item is numbered 0, the second menu item is numbered 1, and so on. Negative numbers specify offsets from the bottom (right for the menubar). -1, for example, means next to last. The position can be given as:
component is cascade, pushbutton, or togglebutton. name is a menu-item name of the form described in Menu Item Names. new_label_string is any string. It must have double quotes if it is not a single word —— that is, if it contains white space. mnemonic is a single character that occurs in the new label string. It is optional, as indicated by the brackets, which do not appear in the command. For example, to add your own tool to the top of all Tools menus:
insert 0 pushbutton *.tools.myTool "My Tool" M
To create a submenu containing several of your own tools:
insert 0 cascade *.tools.myTools "My Tools" M append pushbutton *.tools.myTools.tool1 "First Tool" F append pushbutton *.tools.myTools.tool2 "Second Tool" S append pushbutton *.tools.myTools.tool3 "Third Tool" T
The resulting submenu is shown in Figure 36.
Figure 36 Tools Menu with Additional Submenu
![]()
Replacing a Menu Item
The command to replace a menu item is:
replace_allcomponent name new_name label_string
[mnemonic
]
- component is cascade, pushbutton, or togglebutton.
- name is the name, in the form described in Menu Item Names, of the menu item to be replaced.
- new_name is the simple name of the new menu item.
- label_string is any string. It must have double quotes if it is not a single word —— that is, if it contains white space.
- mnemonic is a single character that occurs in the label string. It is optional, as indicated by the brackets, which do not appear in the command.
For example, to replace the directory viewer's Tools > Shell menu item with your own tool:
replace_all pushbutton directory.tools.shell myTool "My Tool" M
Moving a Menu
The command to move a menu is:
move_cascadefrom_name position
[to_name
]
- from_name is the name, in the form described in Menu Item Names, of the menu to be moved.
- position is a non-negative integer representing the menu's new place in the menu bar or target menu. The first menu item is numbered 0, the second menu item is numbered 1, and so on.
- to_name is the name —— in the form described in Menu Item Names, but without the window type —— of the target menu. It is optional, as indicated by the brackets, which do not appear in the command. If a target menu is not specified, the menu bar is used.
For example, if you frequently use the Ada editor's Control > Show menu, you could move it to the menu bar for easier access:
move_cascade ada.control.show 5
Alternatively, you could move all Show submenus so that they were the first entry on all Control menus:
move_cascade *.control.show 0 controlA cascade can be copied.
Copying a Menu
The command to copy a menu is:
copy_cascadefrom_name position
[to_name]
- from_name is the name, in the form described in Menu Item Names, of the menu to be moved.
- position is a non-negative integer representing the menu's new place in the menu bar or target menu. The first menu item is numbered 0, the second menu item is numbered 1, and so on.
- to_name is the name —— in the form described in Menu Item Names, optionally prefaced by the window type —— of the target menu. It is optional, as indicated by the brackets, which do not appear in the command. If a target menu is not specified, the menu bar is used.
copy_cascade directory.control 4 mywindowkind
Suppressing a Dialog Box
Apex commands that ordinarily display a dialog box can be changed to execute directly. The command to suppress the dialog box is:
dialog_freename
where name is the name, in the form described in Menu Item Names, of the pushbutton item to be changed. For example, you could add the following command to your text_menus file to make Control > Check Out check out the file you were editing without displaying a dialog box:
dialog_free text.control.checkOut
Replicating a Menu Bar or Pop-Up Menu
The command to replicate an entire menu bar is:
copyfrom_window_kind to_window_kind
Similarly, the command to replicate an entire pop-up menu is:
copy_popupmenufrom_window_kind to_window_kind
where from_window_kind and to_window_kind are the server name and, if the server creates more than one kind of window, a period followed by the kind of window.
These commands are used in the standard menu files as convenient steps in creating new menu bars or pop-up menus that are identical to or slight variants of some previously defined menu bars or pop-up menus. Note that for a given kind of window, its menu bar must be defined before its pop-up menu. For example:
copy text text.configuration copy_popupmenu text text.configuration
Defining a Buttonbar
The buttonbar for a given window kind can be defined in the menus file.
The command to define a buttonbar is:
buttonbar [number
] [label
] [mnemonic
]window_kind name name ...
- label must be a quoted string if present.
- mnemonic must be a single character which occurs in the label if present
- name is the simple name of the new menu item.
buttonbar directory.newkind visit enclosing close
There can be multiple buttonbars for a given window kind. They are assigned a number starting with 1. When more than one buttonbar is specified, menu items are added to the Tools > Button_Bar menu to switch between them. The label strings on those menu items can be specified here. The widget name of the menu item to switch to buttonbar N is buttonBarN.
buttonbar 1 "Text" `d' text\ edit save searchForward explain nextMessage \ previousMessage analyze syntax semanticize \ visit gotoMark comment close buttonBar2
buttonbar 2 "Debug" `b' text \ show stack searchForward breakHere nextMessage \ previousMessage propagateHere propagate catchHere \ catch visit \ gotoMark repeatStep close buttonBar1
Creating a Goto Menu
You can create a goto menu to navigate through the directory system. Clicking on a button in a goto menu visits the associated object.
To create a custom goto menu that lists your most commonly visited directories and files, place a navigate clause in your menus file. A navigate clause has the following form:
navigate [position
]menu_name
[menu_label
[mnemonic]
] [path_label
]pathname
[path_label
]pathname
... [path_label
]pathname
end_navigate
where the brackets and ellipses do not actually appear in the action clause, but rather represent optional items and the possible repetition of preceding items, respectively.
You can tailor your navigate clause to place the buttons for each object to be visited:
- On a new submenu on the Navigate menu
- On a new menu on the menu bar
- Directly on the Navigate menu
Placing Buttons on a New Navigate Submenu
For example, this navigate clause creates a Go To submenu at the top of the Navigate menu:
navigate 0 goto "Go To" G /projects/sub1.ss/my_view.wrk /projects/sub2.ss/my_view.wrk end_navigate
The position —— 0 in the example —— is a nonnegative integer representing the new submenu's place on the Navigate menu. The first menu item is numbered 0, the second menu item is numbered 1, and so on. Omit the position to place the new submenu in the last place on the menu.
The menu_name —— Goto in the example —— is the simple name of the new goto submenu.
The menu_label —— "Go To" in the example —— and path_label can be any strings. They must have double quotes if not single words —— that is, if they contain white space. If the menu_label is omitted, the menu_name is used. If a path_label is omitted (as in the example), it is derived from the pathname as shown in Figure 37.
Figure 37 Go To Submenu
![]()
The optional mnemonic —— The G in Go To in the example —— is a single character that occurs in the menu label string. Each mnemonic on a given menu must be unique —— do not specify a mnemonic that already appears on the menus.
Each pathname is the full pathname to a directory or file that you commonly visit. Table 16 described the mouse operations defined for each pathname —— that is, each button —— on a goto menu.
Placing Buttons on a New Menu-Bar Menu
To place the new goto menu directly on the menu bar, prepend an exclamation mark (!) to the menu_name. For example:
navigate 4 !goto Go G /projects/sub1.ss/my_view.wrk /projects/sub2.ss/my_view.wrk end_navigate
This adds a Go menu as the fifth item on the menu bar as illustrated in Figure 38.
Figure 38 Go Menu
![]()
Placing Buttons Directly on the Navigate Menu
To place the buttons directly on the Navigate menu instead of on a submenu, omit the position, menu_name, menu_label, and mnemonic from the navigate clause.
navigate /projects/sub1.ss/my_view.wrk /projects/sub2.ss/my_view.wrk end_navigate
This places the buttons at the bottom of the Navigate menu as illustrated in Figure 39.
Figure 39 Updated Navigate Menu
![]()
AliasesAnother mechanism for facilitating directory traversal is aliases. This mechanism allows you to specify short names which map to full pathnames. These short names can be used in the Open dialog box and in visit commands from the shell. Aliases are placed in the $HOME/.Rational/direcotry_rules file.
aliasesshort_name full_pathname
... end_aliases
- short_name is the shortcut name to use.
- full_pathname is the full UNIX pathname of the directory.
aliases 30 /sierra/products/aPEX.3.0.dev tut /project1.ss/hello.wrk end_aliases
You can use the short_name (that is, tut) in the Open dialog box or in an Apex xterm, you can enter visit tut.
Action ClausesThe commands that create new menu items —— append, insert, replace_all —— cause the new menu items to appear on your Apex windows. To associate an action with each new menu item, place action clauses anywhere after the definitions of menu items in your menu files. You can also use action clauses to override the default semantics for predefined menu items.
Note: Some of the predefined menu items on the editor windows —— for example, those for Apex/Summit commands —— actually call the directory server to display a dialog box. Changing those items in the directory server changes them for all windows.
An action clause has the following form:
action [modifiers
]action_name ...
[object_kind
] [optionsoption_specification ...
]script
end_action
where the brackets and ellipses do not actually appear in the action clause, but rather represent optional items and the possible repetition of preceding items, respectively. For example:
action myCommand1 visit /projects/sub.ss/my_view.wrk end_action
action myCommand2 options Output_Window mytool <SELECTION> end_action
action shift myCommand3 options No_Register Title ps all ps aux end_action
Action Clause Files
The action clauses can also be placed in a separate file from the menu items. This file is called server_name_rules", for example, directory_rules, and would be placed in the $HOME/.Rational directory As with the menu files, there can be a sequence of these files which are found using the APEX_RULES_PATH session switch.If this is not set, then the APEX_MENUS_PATH session switch is used.
The rules files can be reread while the server is running, allowing testing and modification of actions without killing the server. To change the structure of menus it is still necessary to restart the server.
In the Rational local directory menus there is a menu item called Navigate > rules > Reread_Rules which rereads the "directory_rules" files. The Navigate > rules > User_Rules command will visit the user's directory_rules file.
The rule's files for servers can be reread by the shell command
apex_display [-editoreditor_name
] reread_rules
If the editor option is not given, the directory editor is used.
In addition to being used for new menu items, action clauses can also be given to override the default semantics for predefined menu items.
Action Names and Modifiers
The action_name can be either a simple menu item name (for example, checkOut) or a simple menu item name qualified by the window kind (for example, directory.imports.checkOut).
The action name can be preceded by one or more of these modifiers: shift, control, and mod1. If modifiers are specified, the action clause is run only when those modifiers are pressed on the keyboard while clicking on the menu item. Thus, you can specify different semantics for menuItem, Shift-menuItem, Control-menuItem, Meta-menuItem, Shift-Control-menuItem, and so on.
You can specify more than one action name in an action clause, and the action clause will apply to each of them. For example:
action myCommand4 shift myCommand5 myCommand6 options Message_Window echo "Not implemented yet" end_action
In this case, modifiers apply only to the immediately following action name. For example, shift applies to myCommand5 but not myCommand6 above.
You can use a special action name, doubleClick, to change the semantics associated with double-clicking the mouse in directory windows.
window_kind
.finalizeWindow
can be given to define an action which will be invoked just before a window of the given kind is closed.
Object Kinds
You can further qualify actions in directory windows that redefine built-in operations by an object_kind clause, which restricts the action clause to run only when objects of the specified kind are selected in the window. An object_kind clause has the following form:
{file | directory} [access_specification
] [not]pattern
- access_specification is a percent sign (%) followed by some combination of R (readable) or ~R (not readable), W (writable) or ~W (not writable), and X (executable) or ~X (not executable).
- pattern is a naming expression with wildcards.
Object kind clauses are described in Table 17.
For example, if there is a local convention that all FrameMaker documents have the .doc extension, then a special visit action for them could be defined as:
action visit file *.doc options ... Apex_Frame_Server -f <OBJECT> end_action
Option Names and Values
If the second line of an action clause begins with the keyword options, the rest of the items on that line are taken as option specifications. An option_specification has the following form:
option_name
[option_value
]
Table 18 lists supported options. Note that case (upper versus lower) is not significant in option names.
If no output option is specified, any output produced by the action will go to the standard output of the server that started the action. This usually means that you will not see the output; it is effectively lost.
Scripts
The script in an action can be any shell script, and it can span multiple lines. By default, the C shell (csh) is used to execute the script. You can specify a different shell by inserting this command in your file:
shellshell_name
This command changes the default shell for all succeeding actions in your file to shell_name. For example, you might specify the Bourne shell with:
shell /bin/sh
You can put more than one shell shell_name command in your file, allowing you to use different shells for different actions.
If the script is a single line beginning with either visit or apex_display, the script will not be run as a separate job, but will instead be executed directly by the server. This can lead to significant performance improvements for such scripts. These scripts should not have any shell metacharacters in them.
The script can begin with one (or more) lines which start with the keyword, perform, followed by an operation name, and optionally arguments.
These perform commands will be directly interpreted by the server before the rest of the action (if any) is executed.
For example, we have a local code item on text file menus which looks like:
action textCode options ... perform save apex compile <OBJECT> end_action
The perform save line causes the file to be saved before the code action starts.
action doubleClick directory * perform expandobject <OBJECT> end_action
This redefines the double click operation in directory windows when done on subdirectory lines to expand them in place rather than creating a new window.
Prompts
The script in an action can contain prompts to refer to the objects on which the script operates. Before the script is executed, the prompts are textually replaced with filenames, and so on, depending on the particular prompt. For prompts that refer to a set of objects, the replacement string consists of a sequence of tokens, each separated by one space. The Title option can also contain prompts.
For example, an action clause for a menu item defined in directory-viewer windows could be similar to:
action someTool options Output_Window sometool <SELECTION> end_action
The <SELECTION> prompt is replaced by the full pathnames of all objects that are selected in the given window.
action strip options Title strip <FILES> set files = (<FILES>) if ($#files == 0) then echo No files selected exit endif echo stripping $files ... strip $files end_action
All occurrences of the <FILES> prompt are replaced by the full pathnames of any files that are selected in the given window.
Table 19 alphabetically lists supported prompts and the kinds of windows in which they can be used.
Creating a Graphical Menu ItemA graphical menu item only shows its graphical form when it is placed on the button bar. The menu item uses the label string provided when it is displayed a pulldown or popup menu.
The command to create a graphical menu item is:
action
pushbuttonname label
[mnemonic
|-] [pixmap
]
Assigning a Pixmap to an Existing Menu Item
You can assign a pixmap to an existing menu item with the syntax:
set_pixmapname pixmap
Note: If a menu item occurs on a popup menu, you need to assign the pixmap to the popup menu item to get the pixmap to take effect. For example, if you want to change the menu item name expand in the jobs window using
set_pixmap jobs.view.expand expand.xbm
This does not work, because the expand name also occurs on a popup menu as the name "jobs.popupmenu.expand". What you need to do for the pixmap to take effect is the following:
set_pixmap jobs.popupmenu.expand expand.xbm
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2002, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |