Next: , Previous: Window Placement, Up: Top

15 Popup Menus

Popup menus are one of the two main methods through which the user may invoke Lisp code (the other is via keymaps, see Keymaps). The popup-menu function is invoked with a list of menu item definitions and the associated Lisp function to call for each item. This starts a subprocess to display the menu, then at a later date the chosen menu item is received and evaluated.

Each menu item is specified by a list, the first element of which is a string providing the label for the menu item, the second element is a function to be called if that item is selected by the user. If this function has an interactive specification it will be invoked using the call-command function, otherwise funcall will be used. Alternatively the second element may be a lisp form to evaluate. So, for example, a single-level menu could be defined by: 

     (("Item 1" function-1)
      ("Item 2" function-2)
      ()
      ("Item 3" function-3))

The null item will create a separator line in the displayed menu.

If the cdr of first element of any item is a symbol, then the rest of the item is defined by the value of the named variable. If this value is functional then the definition is found by calling the function.

Consider the following definition: 

     (("Workspaces" . workspace-menu)
      ("Windows" . window-menu)
      ("Programs" . apps-menu)
      ("Customize" . custom-menu)
      ("About..." (customize 'about))
      ()
      ("Restart" restart)
      ("Quit" quit))

This is the definition of Sawfish's root menu. We can see that four submenus are created dynamically by dereferencing variables (in fact, three of this variables contain functions) (workspace-menu, window-menu, apps-menu and custom-menu). Note that these must be special variables, i.e. initially declared using the defvar special form.

The apps-menu variable can thus be used to redefine the applications menu. The default definition is as follows: 

     (("xterm" (system "xterm &"))
      ("Emacs" (system "emacs &"))
      ("Netscape" (system "netscape &"))
      ("The GIMP" (system "gimp &"))
      ("XFIG" (system "xfig &"))
      ("GV" (system "gv &"))
      ("xcalc" (system "xcalc &")))

The system function simply executes its single argument using /bin/sh.

When displaying a menu item, it is possible to also display the corresponding keyboard shortcut in the menu.

— Variable: menus-include-shortcuts

When true, menu items also display key-binding information. Defaults to false.

The actual creation of a menu is performed by an auxiliary process, distributed with Sawfish. Since the overhead of starting the menu subprocess may be noticeable on some systems, it is possible to leave it running between menu requests.

— Variable: menu-program

Location of the program implementing Sawfish's menu interface.

— Variable: menu-program-stays-running

This variable defines if, and for how long, the menu subprocess is allowed to remain executing for after the last menu has completed. If nil, the program is terminated immediately, if t it is left running indefinitely, if an integer then the program will run for that many seconds (unless another menu is displayed).

The actual interface to invoke the external menu program is hidden in the popup-menu function.

— Function: popup-menu spec

Displays a menu defined by the list of item definitions spec.

In addition, Sawfish provides various canned menus, and functions to display those menus.

— Variable: root-menu

Contains the root menu definition.

— Function: popup-root-menu

Display the main menu. By default, this is bound to Button2-click on the root window.

— Variable: apps-menu

The variable containing the definition of the applications submenu of the root menu. The default root menu includes this as a child menu.

— Function: popup-apps-menu

Display the applications menu.

— Function: window-ops-menu

The variable containing the definition of all window operations.

— Function: popup-window-menu

Display the menu listing all window operations. This has several bindings by default. In particular, clicking on a window's menu button displays this menu.

— Variable: window-ops-toggle-menu

A list of flags describing windows, e.g., “sticky” or “shaded”. This list is displayed in a menu, and by selecting items in this menu a user can turn the flags on and off for a given window.

— Function: add-window-menu-toggle label command &optional predicate

Add additional flags to window-ops-toggle-menu. The command is a function (or a symbol pointing to a function) that gets run when the menu item is selected. If predicate is non-nil, it must be a function taking a window as argument. If predicate return true, the menu item will have a check mark next to it.