on-click

Arguments:
dialog-item-or-menu

Returns (or sets with setf) the value of the on-click event property
of dialog-item-or-menu.

on-click on dialog items

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.

on-click on menu items

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: