Call-back functions

In this section:

A ClearWin+ call-back function takes no arguments and returns an integer result. As a result, such functions may be coded in C, C++, or Fortran.

When a call-back function returns, it indicates what is to happen next by its return value. A negative or zero value signals an exit and closes the parent format window. The corresponding call to winio@ will return the absolute value of this quantity. A return value of 1 will cause a full update of the format window so that any changes are made visible. This should be used sparingly because if a call-back is used repeatedly, then the whole display area may flicker due to the frequent screen updates. A more efficient approach is to use a return value of 2. This will not cause the format window to close nor will it update the window. In order to refresh any part of the display that needs to be refreshed, a call to WINDOW_UPDATE@ will suffice. This will also improve the response since only small sections of the display will be redrawn.

In summary return values can be:

< 0

Closes associated window.


Returns from call-back with display refresh.


Returns from call-back with no refresh.


Used with %mg (Message Callback) only.


Used with %bv (Branch View) and %lv (List View) only.

> 5

Reserved for future use.



Returning a negative value can be very convenient. Consider a window with a list box and OK and CANCEL buttons. Typically it is required that a double click on a list box item will select that item and close the window as if the OK button had been pressed. To achieve this the list box call-back function should return -1, so that winio@ will return 1 as if the OK button had been pressed - thus saving a flag and more complex program logic.

It is often convenient to use one call-back function for a variety of reasons. Whenever a call-back function is invoked, ClearWin+ defines a string that specifies the reason for the call. This string is obtained by calling clearwin_string@('CALLBACK_REASON'). Testing the string makes it easy to determine the reason for the call. See CLEARWIN_STRING@ for further details.



Copyright © 1999-2024 Silverfrost Limited