| Allegro CL version 9.0 Unrevised from 8.2 to 9.0. 8.2 version | ||||||||||
Arguments: dialog-item-or-menu
Returns (or sets with setf) the value of the on-click event property of dialog-item-or-menu.
For dialog items, the value of the on-click property should be a
function object or a function name (a symbol naming a function). This
function is called when the left mouse button is clicked down while the
mouse cursor is over the dialog-item. This function should accept two
arguments, the dialog holding dialog-item and dialog-item itself. The
value may be nil if no function needs to be
run.
on-click is
distinct from on-change. For example, if the user
clicks an item-list control (a single-item-list control, for
example) on the value that is already selected, then the on-click function will be
called but not the on-change function (assuming
on-change-test
has its default value eql). On the other hand, if the value of a
control is changed programmatically by application code, then the
on-change
function will be called but not the on-click function.
It is usually more appropriate to use an on-change function rather than an on-click function, even for a button
widget. If the user presses a button widget by pressing the spacebar when the
button widget has the keyboard focus, then the on-change function is called but the on-click function is not called. And
if the user clicks the mouse button down over a button widget but then drags off of the
widget before releasing the mouse button (to abort pressing the button
widget), then the on-click
function is called but the on-change function is not. Successfully
pressing a button widget arbitrarily toggles the widget's value
between t and nil to
cause the on-change function
to be called.
Note that the on-click function of a Windows
tab-control
will be called only when clicking on its tabs, not when clicking in
the tab-control body.
The on-click event handler is also defined for menus, where it works differently than on dialog-items. It is called by the default handle-menu-selection method, and should take the three required arguments menu, menu-item, and stream.
The menu argument is the menu that contains the chosen menu-item. The menu-item argument is the menu-item that was chosen. The stream argument is either the window on which the menu was invoked with pop-up-menu, or else the window on which the menu was defined. If the menu was invoked by calling pop-up-menu, then any values returned by the on-click handler will then be returned from the call to pop-up-menu.
The default on-click handler for menus is default-menu-on-click, which simply returns the value of the chosen menu-item. This default handler may be used when using pop-up-menu to invoke the menu, where the code that called pop-up-menu then proceeds to process the returned value in some way. A menu on a menu-bar, on the other hand, needs to use some other on-click handler that processes the chosen menu-item itself in some way before returning, since menus on menu-bars do not return anything to the application. A few standard alternate on-click handlers for menus are supplied by Common Graphics; these are:
Any given menu may use one of these built-in choices if appropriate, or else use a custom on-click handler.
See cg-events.htm for information about event handling in Common Graphics.
Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.2 page.
Created 2012.5.30.
| Allegro CL version 9.0 Unrevised from 8.2 to 9.0. 8.2 version | ||||||||||