GNU Info

(sawfish.info)Popup Menus

---

Next: Events Prev: Workspaces Up: Top

---

Enter node , (file) or (file)node

Popup Menus
***********

   Popup menus are one of the two main methods through which the user
may invoke Lisp code (the other is via keymaps, Note: 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'.

 - Function: popup-menu spec
     Displays a menu defined by the list of item definitions SPEC.

 - Function: popup-window-menu
     Display the menu listing all window operations.

 - Function: popup-root-menu
     Display the main menu.

 - Function: popup-apps-menu
     Displau the applications menu.

 - Variable: root-menu
     Contains the root menu definition.

 - Variable: apps-menu
     The variable containing the definition of the applications submenu
     of the root menu.

   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-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).