Generic FunctionPackage: cgToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 8.1
Unrevised from 8.0 to 8.1.
8.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-2009, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 8.1. This page was not revised from the 8.0 page.
Created 2009.7.29.

Allegro CL version 8.1
Unrevised from 8.0 to 8.1.
8.0 version