| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |
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.
| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |