on-double-click

Arguments: dialog-item

Returns the value of the on-double-click event property of dialog-item. The value of the on-double-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 double-clicked while the mouse cursor is over 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 need be run.

The value may also be the special keyword :push-again. This value causes the second click of a double-click to call the on-change function of the control, if any. Since the first click of a double-click always calls the on-change function (if any), this special value means that every click of a rapid series of clicks will call the on-change function. By contrast, when on-double-click is nil, nothing is done on the second click of a double-click. This default behavior prevents the user from accidentally calling the on-change function twice on an accidental double-click, and so :push-again must be specified explicitly when rapid-fire clicking to invoke the on-change function for every click is desired instead. (A small limitation of :push-again is that the control will not visibly depress a second time for the second click of a double-click, despite the name.)

Consider a use of on-change to change the value displayed in a static text widget. If only two values are possible, suppressing an immediate second click (as is done when on-double-click is nil) may be useful as the second click is probably unintended. But if on-change cycles through a longer list of values, rapid multiple clicks are likely intentional and the :push-again for on-double-click would be appropriate.

See cg-events.htm for information about event handling in Common Graphics.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.