pop-up-menu

Generic Function

Package: common-graphics

Arguments: menu &optional stream 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.

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

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

Common Graphics and IDE documentation is described in About Common Graphics and IDE documentation in cgide.htm.

The documentation is described in introduction.htm and the index is in index.htm.

Created 2000.10.5.