| Allegro CL version 6.2 Minimally revised from 6.1 |
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
.
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.
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-2002, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 6.2. This page has had minimal revisions compared to the 6.1 page.
Created 2002.2.26.
| Allegro CL version 6.2 Minimally revised from 6.1 |