Generic FunctionPackage: cgToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 10.1
Unrevised from 10.0 to 10.1.
10.0 version


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:

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-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.

Allegro CL version 10.1
Unrevised from 10.0 to 10.1.
10.0 version