GUI Object Callbacks

A callback is a function that is called by Gsharp whenever something happens to a GUI object. This could include a menu option being selected, an icon being clicked on or the canvas repainting.

• Defining a callback
• Callback Data
• Callback Reasons
• Built-in Callbacks
• GSL Callback examples

Defining a callback

Any GSL function can be used as a callback, but they normally look something like this:

function touppercaseCB(string o, string d, float r)
  string tmp;
  if r<>XuCR_ACTIVATE return;
  tmp = GuiGetString(o);
  GuiSetString(o,toupper(tmp),false);
endfunction

Each callback is passed three arguments:

The callback for an object is specified in exactly the same way as any other resource:

create Text gsharp_1.mydialog.namefield
 ( XuNguiCallback = "touppercaseCB",
   XuNguiPosition = (0,0),
   XuNguiWidth = 100
 );

It is also possible to use callback functions from within your own code, but you must add the three arguments yourself. For example:

GuiFileExit("gsharp_1","",0);

Callback Data

When you create an object you can specify a value that should be passed to the callback function. This value is called the callback data and is passed in the second argument of the callback.

This allows you to use one callback for many objects and to use the callback data to distinguish between them.

For example, if you wanted to create three menu buttons which run GSL scripts you could create one callback function to run the script and pass the name of the script in the callback data:

create gsharp_1.menubar.examples.example1
 ( XuNguiLabel = "Script 1",
   XuNguiCallback = "ExecCB",
   XuNguiCallbackData = "'script1.gsl'"
 );
create gsharp_1.menubar.examples.example2
 ( XuNguiLabel = "Script 2",
   XuNguiCallback = "ExecCB",
   XuNguiCallbackData = "'script2.gsl'"
 );
create gsharp_1.menubar.examples.example3
 ( XuNguiLabel = "Script 3",
   XuNguiCallback = "ExecCB",
   XuNguiCallbackData = "'script3.gsl'"
 );
function ExecCB(string o, string d, float r)
  exec(d);
endfunction

The callback data can either be a string, as above, or a number e.g. "4". If numbers are used then the arguments of the callback function become:

function myfuncCB(string o, float d, float r)

The name of the object is also passed to the callback and this can also be used to control the actions of the callback.

N.B. The value of the callback data (not including the quotes) must be a valid dataset or expression e.g.

"WORK.T1", "'a string'" or "3.2"

Skip straight to Callback Reasons if you don't want to know why this is!

This is because when an object, OBJ, has an event XuCR_ACTIVATE, then Gsharp will try and execute the following:

eval( $OBJ.XuNguiCallback + "('" + OBJ + "'," +
                 $OBJ.XuNguiCallbackData + ",XuCR_ACTIVATE);" );

If $OBJ.XuNguiCallbackData was "a string" rather than "'a string'" then the following would be evaluated:

"TheObjectCB" + "('" + "gsharp_1.dialog.button" +
                        "'," + "a string" + ",XuCR_ACTIVATE);"

which is the same as:

"TheObjectCB('gsharp_1.dialog.button',a string,XuCR_ACTIVATE);"

when it really needs to be:

"TheObjectCB('gsharp_1.dialog.button','a string',XuCR_ACTIVATE);"

This also explains why a callback data of "4" means that the callback expects a float rather than a string. e.g.

"TheObjectCB" + "('" + "gsharp_1.dialog.button" +
                         "'," + "4" + ",XuCR_ACTIVATE);"

which is the same as:

"TheObjectCB('gsharp_1.dialog.button',4,XuCR_ACTIVATE);"
         

Callback Reasons

Each object has a fixed set of possible reasons why a callback might be called. For example a dialog has three buttons OK, Apply and Cancel. When one of these buttons is clicked on the callback for the dialog is called with the reason set to one of: XuCR_OK, XuCR_APPLY or XuCR_CANCEL.

The possible reasons for each object are documented with the object.

As an example of how this information could be used here is a callback for a dialog.

function mydialogCB(string o, string d, float r)
  if r<>XuCR_APPLY GuiPopdownDialog(o);
  if r<>XuCR_CANCEL ApplyMyDialog();
endfunction

Built-in Callbacks

There are several callback functions built into Gsharp, which can also be included in your own application.

The most popular built-in callbacks are:

This callback pops up a dialog for confirmation and then Gsharp exits

This dialog is used to control which printer to use, the paper size and the position of the plot on the paper. The GSL function print can be used to make the print.

The callback data to GuiFileOpen must contain an array of strings specifying the file-types which the dialog will support: Possible options are "report", "ascii", "binary", "field", "folder" and "script". e.g.

gsharp_1.menubar.file.open.XuNguiCallbackData = '"script"//"folder"';

These callbacks bring up the three Gsharp tools. The are no callbacks to pop them down again.

A full list of built-in callbacks can be found in the Gsharp Applications Reference Manual.

GSL Callback Examples

function PopupDialogCB(string o, string d, float r)
  GuiPopupDialog(d);
endfunction

function PopdownDialogCB(string o, string d, float r)
  o = tokenize(o,".");
  GuiPopdownDialog(o[1]+"."+o[2]);
endfunction

function DestroyDialogCB(string o, string d, float r)
  o = tokenize(o,".");
  o = o[1]+"."+o[2];
  destroy $o;
endfunction

function ExecFileCB(string o, string d, float r)
  exec(d);
endfunction

function StandardToggleCB(string o, string d, float r)
  $o.XuNguiLabel = if(GuiSwitchGetState(o), "On", "Off");
endfunction

Return to Gsharp Applications User Guide