Adding or modifying window manager menus

You can create completely new window manager menus that you can call to the screen by pressing a mouse button or a key on the keyboard, or by selecting it from an existing menu. You can also modify the existing window manager menus (the Root and Window menus) to include additional menu items or submenus.

To create a new window manager menu, perform the following steps.

1. Open the desired window manager configuration file for editing.

   • pmwm mode:
     
     /usr/lib/X11/system.pmwmrc for system-wide changes

     $HOME/.pmwmrc for individual changes

   • mwm mode:
     
     /usr/lib/X11/system.mwmrc for system-wide changes

     $HOME/.mwmrc for individual changes

2. Within the section of the configuration file that contains menu definitions, begin the new menu with the section type and section title, using the following syntax:
   
   Menu menu_name

3. Enter your menu items, using the following syntax:
   
   {
       label   [mnemonic]   [accelerator]   function
       label   [mnemonic]   [accelerator]   function
       .
       .
       label   [mnemonic]   [accelerator]   function
   }

4. Define the method by which you want to access the new menu:

   • To access the menu as a submenu, add a new menu_item clause to the parent menu's definition section, referencing your new menu's menu_name with the f.menu function:
     
     label [mnemonic] [accelerator] f.menu "menu_name"

   • To use the menu through a mouse button or key sequence, define the mouse button or keystroke that you want to use in the key and button bindings sections of the configuration file:
     
     button_event context f.menu menu_name

     or

     key_event context f.menu menu_name

     See ``Configuring window manager button bindings'' and ``Configuring window manager key bindings'' for more information on button and key bindings.

   When you have finished, save and exit the configuration file.

5. Restart the window manager.

Step 1: Editing a window manager configuration file

The default operation of the window manager is largely controlled by a system-wide file, called system.pmwmrc if you are using pmwm mode or system.mwmrc if you are using mwm mode. This file's functions include defining the contents of the Root and Window menus and how menu functions are invoked. Individual users can also have a version of this file, located in their home directories, called .pmwmrc (for pmwm mode) or .mwmrc (for mwm mode). This file can be used to customize window manager menus for an individual user without affecting other users on the system.

Open one of the following files for editing:

• the system-wide configuration file (/usr/lib/X11/system.pmwmrc or /usr/lib/X11/system.mwmrc) if you want to create a new menu or modify an existing menu so that all users are exposed to these customizations. You must have root permissions to edit this file.
  

• the local configuration file ($HOME/.pmwmrc or $HOME/.mwmrc) if you want to customize window manager menus for an individual user.

  The $HOME/.pmwmrc and $HOME/.mwmrc files do not exist by default. If a local configuration file does not already exist in your home directory, copy the appropriate system-wide window manager configuration file to $HOME and rename the file either .pmwmrc or .mwmrc.

  ---

  NOTE: Once the .pmwmrc or .mwmrc file exists in $HOME, it completely overrides the system-wide window manager configuration file. Therefore, make sure you copy the entire system file to your home directory, to avoid losing critical functionality.

  ---

See also:

• ``Customizing the window manager'' for more information on the system-wide and local window manager configuration files

Step 2: Starting a new menu

The first section of the window manager configuration file defines the contents of the Root and Window menus. If you want to create a new widow manager menu, add the menu definition to the end of this section.

A menu definition starts with the Menu section type and a title for the section, designated by the menu_name specification:

Menu menu_name

The menu_name specification is an internal reference and does not appear as the title of the menu. The string value that you assign to menu_name is often referenced elsewhere in the window manager configuration file. In particular, menu_name can be paired with a button action (in the button bindings section of the configuration file) so you can press a particular mouse button to display the menu. This concept is covered in greater detail in Step 4.

The following example shows the section type and title for the default Root menu:

   Menu RootMenu

Step 3: Creating menu items

The syntax for defining items on a window manager menu is very simple. Each item is defined by a line that uses the following format:

{
label [mnemonic] [accelerator] function
}

The syntax for items on the Root menu is slightly different because mnemonics and accelerators are not available.

When creating menu options, note the following:

• The label specification is used as the text for the menu option, and has the following syntax:
  
  label  =  character_strings  or  bitmap_file

  label can consist of a character string or a graphic representation (bitmap file). A character string must be compatible with the menu font that is used. Character strings must be typed precisely, using one of the following approaches:

  • strings containing a space must be enclosed in quotation marks ``" "''. For example: "Menu Name."

  • single-word strings do not have to be enclosed in quotation marks. However, it is preferable to do so for consistency. For example: "MenuName."

  If you are using a bitmap file instead of a character string, you need to tell the window manager the full path of the file. There are several methods for indicating a file's path:

  Character	Function	Example
  @	the following string is a pathname	@/u/tammyr/bitmaps/root_weave
  ~	the user's home directory	~/bitmaps/root_weave

  ---

  NOTE: You can also set the bitmapDirectory resource to the path of the directory containing the bitmaps. For example, if you set bitmapDirectory to /u/tammyr/bitmaps, the bitmap file could be specified as: @root_weave. For more information on setting resources, see ``Understanding resources''.

  ---

• The mnemonic specification indicates the character, or mnemonic, that can be used to select a menu item once the menu is open and displayed on the screen. A mnemonic specification has the following syntax:
  
  mnemonic  =  _character

  The first character in the label specification that matches the designated mnemonic is underlined on the menu. Note that the mnemonic specification is case sensitive.

  If there is no matching character in label, no mnemonic is registered. The character must match a character in label exactly; the mnemonic cannot execute if any modifier (such as the <Shift> key) is pressed with the character.

  This specification is optional, and is not available on the Root menu.

• The accelerator specification is an accelerator key event, with the same syntax as the window manager key bindings. By default, an accelerator key sequence is a Meta key, usually the <Alt> key, plus a function key.

  The accelerator specification has the following syntax:
  
  accelerator  =  Meta<key>funct_key

  The accelerator sequence works whether or not the menu is displayed. Because of this, you should be careful not to use key actions that are already defined in the key bindings section of the window manager configuration file. Key bindings are discussed in greater detail in ``Configuring window manager key bindings''.

  Because the key-action combination must be unique, accelerators use modifiers to provide more key-action combinations. Modifiers are keys that users must press simultaneously with the existing key event. All modifiers specified are exclusive; that is, only the specified modifiers can be present when the key event occurs.

  The following list indicates the keys that can be used for modifiers:

  modifier_name	Description
  Ctrl	Control Key
  Shift	Shift Key
  Alt	Alt/Meta Key
  Meta	Meta/Alt Key
  Lock	Lock Key
  Mod1	Modifier1
  Mod2	Modifier2
  Mod3	Modifier3
  Mod4	Modifier4
  Mod5	Modifier5

  This accelerator specification is optional, and is not available on the Root menu.

• The function specification defines the action to be performed when a menu item is selected. The syntax for naming a function is:
  
  function  =  function_name [function_args]

  where function_name is one of the defined window manager functions, and function_args is a valid argument to the function.

  There are a number of predefined window manager functions that you can use for the function_name clause. Each of the window manager functions has a name beginning with ``f.''. These functions define behavior, such as resizing windows (f.resize), moving a window (f.move), and iconifying a window (f.minimize). For a complete list of the available window manager functions and a description of their behavior, see ``Using window manager functions''.

  There are several window manager functions that are particularly relevant to the task of creating menus. These functions include:

  Function	Behavior
  f.menu	associates a submenu entry with a menu definition
  f.title	inserts a title in the menu at the specified location
  f.separator	inserts a dividing line in the menu at the specified location. An f.separator is automatically inserted after an f.title.

  
  Several of the window manager functions can accept arguments. The nature of function_args depends on the specific function. In some cases, you can define the context in which the action should happen (for example, perform the action only on icons, or on windows and icons). Sometimes the argument is a specific client name, or a menu name, as with the f.menu function. ``Function contexts'' discusses the issue of context and arguments for window manager functions in detail.

  If a function_args contains any spaces, the argument must be contained within double quotations ``" "''.

   "Restore"       _R   Alt<key>F5         f.normalize
   "Move"          _M   Alt<key>F7         f.move
   "Size"          _S   Alt<key>F8         f.resize
   "Minimize"      _n   Alt<key>F9         f.minimize
   "Lower"         _L   Alt<key>F3         f.lower
   "Raise"         _a   Alt Shift<key>F3   f.raise
   "Toggle Nail"   _a   Alt Shift<key>F2   f.nail
   "Hide"                                  f.hide_panner

Step 4: Specifying how to access the new menu

Before you can use your new menu, you must specify the method by which it can be accessed. You can attach the menu to an existing menu so it is available as a ``cascading'' or submenu. You can also configure the menu so a mouse button or key event displays the menu. These approaches are discussed here. You can also replace the default Window menu with your new menu, so it is automatically available by clicking on the window menu button. This approach is discussed in ``Changing the menu associated with the window menu button''.

• To make your menu a submenu of an existing menu (perhaps the Root or Window menus), locate the intended parent menu's definition section in the local or system-wide window manager configuration file and add an f.menu function. This function must be coupled with the menu_name you used in your menu's definition section:
  
  label [mnemonic] [accelerator] f.menu "menu_name"

  For example, if you created a menu that you defined as ``GamesMenu'', and you want to access it from the Root menu, you would enter the following line within the Root menu definition section:

     "Games Menu"      f.menu "GamesMenu"
  

• To access your new menu directly through a mouse button or key sequence, you must add an f.menu function to the button or key binding section of the window manager configuration file. The f.menu function must be coupled with the menu_name you used in your menu's definition section. You also need to specify the context in which the menu is available.
  
  [modifier_key]button_event context f.menu "menu_name"

  or

  [modifier_keys]<Key>key_name context f.menu "menu_name"

  For example, if you created a menu that you defined as ``GamesMenu'', and you want to access it by pressing the second mouse button on the Root window, enter the following line within the button binding section of the window manager configuration file:

     <Btn2Down>   root   f.menu "GamesMenu"
  

  You can also use the f.post_wmenu function if you want to post the currently defined Window menu with a mouse button or key event. This function automatically displays the menu that is defined by the window manager windowMenu resource. If you intend to configure your new menu so it functions as the Window menu, use the f.post_wmenu function.

  For detailed information on the button and key binding sections, see ``Configuring window manager button bindings'', and ``Configuring window manager key bindings''.

Step 5: Restarting the window manager

After you have added your new menu information to either the local window manager configuration file ($HOME/.pmwmrc or $HOME/.mwmrc) or the system-wide file (/usr/lib/X11/system.pmwmrc or system.mwmrc), you must restart the window manager before your changes can take effect and your new menu can be displayed.

Restart the window manager by selecting the Restart Window Manager option on the Root menu. The Root menu is accessed by pressing and holding mouse button 1 anywhere on the Desktop background or, if the Desktop is not running, in the Root window. After the window manager restarts, you can use your new menu.