Callback Functions

When the user interacts with the GUI, for example by pressing a GUI button, the application is notified of the interactive event using a mechanism called a callback. A callback is handled by a callback function which is associated with the GUI object. The callback function performs an operation in response to an event. Callback functions are typically written in GSL and included in the application, but they may also be built­in convenience functions which are part of Gsharp, as is the case with the use of GuiFileExit in the example gui_lesson1.gsa.

All callback functions must be defined with the following arguments:

function <name>( string <object>, string <calldata>, float <reason>) 

Where:
object is set to the full path name of the object which generated the callback.
calldata is the data passed by the object to the callback function.
reason is an enumerated value identifying the event which caused the callback.

The callback function responds to the callback event by executing a sequence of GSL statements, and perhaps by operating on any data passed to it in the calldata argument. If you need to pass more data to the callback function than the single XuNguiCallData resource allows, you can use the XuNuserData resource which is available for all objects, as a way to pass additional information.

You can associate a callback function with an object using the resource XuNguiCallback. A single callback function handles all events for an object, with the callback reason code identifying which event has occurred. The same callback function can serve multiple objects. The object parameter to the callback function makes it possible to identify the object which generated the callback.

The example gui_lesson1.gsa can be extended with additional GUI objects to introduce more functionality in the application. In the next example, a popup menu is added to the canvas, and the popup menu items are handled by a GSL callback function:

Example: gui_lesson2.gsa ­ callback functions

function canvas_popupCB(string object, string calldata, float reason) 
  if $object.XuNguiLabel = "Repaint" then 
    repaint; 
  else 
    GuiFilePrintSetup(object,calldata,reason); 
  endif 
endfunction 
/*************************************************************** 
* Main Program 
***************************************************************/ 
include "$UNIDIR/example/GsharpApp/gui_lesson1.gsa"; 
create Popup gsharp_1.canvas.popup; 
create Button gsharp_1.canvas.popup.button_1 
  ( XuNguiLabel = "Repaint", 
    XuNguiCallback = "canvas_popupCB"
  ); 
create Button gsharp_1.canvas.popup.button_2 
  ( XuNguiLabel = "Print...", 
    XuNguiCallback = "canvas_popupCB" 
  ); 

The popup menu created in this example appears when MB3 is pressed with the pointer over the canvas, and is shown in the figure below.

The popup callback identifies which operation it must perform by examining the label of the calling object. The callback reason is also used for this purpose, particularly for dialogs which generate a unique callback reason for each button. In this example, the reason code for each popup button is the same, XuCR_ACTIVATE, which indicates that a button has been pressed, or "activated''.

In addition to being called by the Gsharp event handler, callback functions can also be called by any GSL function. You achieve the affect of having a single event generate multiple callbacks by having the specified callback function call a sequence of other callback functions.

Carry on to Canvas Callback Handling