fetch-control-value

Generic Function

Package: common-graphics

Arguments: control

Asks the operating system what the true value of dialog-item is, sets the official value property of the widget to that value, and returns the value.

Typically this function is not needed, since the operating system sends messages to Common Graphics when a control's value has changed and the value property is updated at that time. In certain unusual circumstances, however, the value property may not be out of date because the change message from the operating system either has not arrived yet or has been overridden in some way.

Here are two cases where this function may be needed:

* Example 1: The user is typing into an editable-text control. The control's delayed property is turned on, which means that the value property of the control is updated only when the keyboard focus moves from the control. But while the focus is still in the control, the user presses the main ENTER key, which invokes the on-change handler of the default-button on the same dialog. This on-change handler reads the current value of the editable-text control, but this value is not up to date because the control still has the focus. To prevent this problem, the default-button's on-change handler could call fetch-control-value on the editable-text before it reads its value.

* Example 2: An on-click event handler that calls drag-and-drop is added to an item-list control. Normally the operating system sends a message that the value of an item-list control has changed only when the mouse button is released, but in this case drag-and-drop will grab the mouse-left-up event to determine when to stop dragging and so Common Graphics is never told that the value has changed. Calling fetch-control-value on the item-list just before calling drag-and-drop will prevent this problem. (Actually drag-and-drop now will always call fetch-control-value internally. So this case does not need to be handled by an application, though it is still an example of situations where fetch-control-value may be needed.)

Currently fetch-control-value is implemented for these controls where a need has arisen at some point: editable-text, multi-line-editable-text, single-item-list, multi-item-list, and combo-box. If fetch-control-value is called on any other control, it is assumed that the current value property of the control is up-to-date and this value is simply returned.

Common Graphics and IDE documentation is described in About Common Graphics and IDE documentation in cgide.htm.

The documentation is described in introduction.htm and the index is in index.htm.

Created 2000.10.5.