pop-up-menu

Arguments: menu &optional window-or-screen position horizontal-justification vertical-justification button

This function returns two values after displaying a pop-up-menu at the mouse cursor or at an arbitrary position. If a menu-item is chosen by the user, it then calls handle-menu-selection on the chosen menu-item and returns the value returned by handle-menu-selection. (By default the return value will be the value of the selected menu-item, since the default handle-menu-selection method returns the value returned by the menu's on-click function, and the default on-click function of a menu simply returns the menu's value.) This function returns nil if the user cancels from the menu by clicking outside the menu or pressing the ESCAPE key. A second returned value is t if the user chose an item or nil if the user canceled the menu.

menu is the menu to display. Menus are created by calling open-menu.

window-or-screen is a window or the screen. The default value is the screen. This argument is relevant only when the position argument is passed, in which case the position is in this stream's coordinate system. In an application with multiple Common Graphics threads, this argument should not be a window in a thread other than the thread that is calling pop-up-menu, because that would prevent keystrokes from alternately being used to select a menu item or exit the menu.

position may be either nil to place the menu at the current mouse cursor position or a position (see make-position) to place the menu at an explicit position. The default is nil. The position should be in the device coordinates of stream; that is, relative to the upper-left interior corner of the window or screen.

horizontal-justification may be either nil, :left, :center, or :right to indicate which edge or center of the menu should horizontally align with the specified menu position. (If position is nil, this aligns the specified part of the menu with the mouse cursor.) The default is :left, and nil is interpreted as :left.

vertical-justification may be either nil, :top, :center, or :bottom to indicate which edge or center of the menu should vertically align with the specified menu position. (If position is nil, this aligns the specified part of the menu with the mouse cursor.) The default is :top, and nil is interpreted as :top.

button may be either :left or :right to indicate which buttons may be used to select an item from the menu. :left indicates that only the left button may be used. :right indicates that either the left or right button may be used. Passing :right may be particularly useful for menus that were invoked by a right click (typically in a custom mouse-right-down method), since this allows the user to optionally hold the button down while dragging to the desired item and then to release the mouse button to select the item and exit the menu with a single click. The default is :left. On GTK, this argument is ignored, and the user always must use the left button to select a menu-item.

See also the more specialized functions pop-up-lettered-menu and pop-up-shortcut-menu. Also, an alternative way to ask the user for a choice from a list is to call ask-user-for-choice-from-list. This function may be better when the list of choices is large, as it uses a scrolling single-item-list or multi-item-list. For four choices or fewer, ask-user-for-choice may be used.

Microsoft Windows note: to make it easy for the user to select a choice or to cancel a pop-up menu, you may want to ensure that a window from the same process has the keyboard focus, or at least that such a window is present on the screen. In Microsoft Windows, keypresses will apply to a pop-up menu only if the window that currently has the keyboard focus was created in the process that popped up the menu. Otherwise the Escape key will not dismiss the menu, and a choice cannot be made with the keyboard. Clicking the mouse outside a pop-up menu will dismiss the menu only if the click is on a window that either was created in the process that is calling pop-up-menu, or is in a window hierarchy that contains such as window).

Example: Here is a simple example where either clicking the right mouse button or pressing the spacebar will create a pop-up menu on the fly and call pop-up-menu to display it, and then close the menu afterwards to free up the operating system resource for the menu.

(defclass my-frame (frame-window)())

(defmethod mouse-right-down ((window my-frame) buttons cursor-pos)
  (declare (ignore buttons cursor-pos))
  (show-my-menu window))

(defmethod virtual-key-down ((window my-frame) buttons
                             (key-code (eql vk-space)))
  (declare (ignore buttons))
  (show-my-menu window))

(defun show-my-menu (window)
  (let* ((menu (open-menu (list (make-instance 'menu-item
                                  :title "~Yellow"
                                  :value 'yellow)
                                (make-instance 'menu-item
                                  :title "~Green"
                                  :value 'green)
                                (make-instance 'menu-item
                                  :title "~Cyan"
                                  :value 'cyan))
                          'pop-up-menu (screen *system*)))
         answer)
    (unwind-protect
        (progn
          (setq answer (pop-up-menu menu (screen *system*) nil
                                    :left :center :right))
          (when answer
            (setf (background-color window)(symbol-value answer))
            (invalidate window))) ;; redraw in new color
      (close menu))))

(make-window :color-test
  :class 'my-frame
  :title "Right-Click or Press the Spacebar to Change Color")

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.