guiWaitEvent (Function)

This function will wait until a GUI event is raised. It has an optional timeout.

An event is a notification that something has happened in the GUI interface.

The events are normally triggered by the user, depending on the available controls.

The events are queued until appropriate action is taken as described in this table:

guiWaitEvent notifies the application of the oldest queued event.

This means that if the appropriate action is not taken, guiWaitEvent will continue to report the same event.

If no action is required, only the handle of the control is provided, and it is then recommended to manually read the wanted values of the control if needed.

Note: waiting for an event using this function will block the calling thread.

Input:

timeout : INT (-1,0..32767) (default -1)

Timeout period in milliseconds to wait.

Output:

handle : SYSHANDLE

The handle of the control that caused the event.

Returns: INT

Declaration:

FUNCTION guiWaitEvent : INT;
VAR_INPUT
  timeout  : INT := -1;
  handle   : ACCESS SYSHANDLE;
END_VAR;

Example:

INCLUDE rtcu.inc
 
VAR
  button : SYSHANDLE;
  check  : SYSHANDLE;
  menu   : SYSHANDLE;
  label  : SYSHANDLE;
  spinner: SYSHANDLE;
  textbox: SYSHANDLE;
END_VAR;
 
FUNCTION ButtonHandler
VAR
  rc     : INT;
  handle : SYSHANDLE;
  tag    : DINT := 0;
  lp     : BOOL;
END_VAR;
  rc := guiButtonClickEvent(button := handle, long_press := lp);
  IF rc = 0 THEN
    guiGetTag(handle := handle, tag := tag);
    IF lp THEN
        DebugFmt(message:="Button with tag \4 was pressed", v4 := tag);
    ELSE
        DebugFmt(message:="Button with tag \4 was clicked", v4 := tag);
        guiMenuShow(menu := menu);
    END_IF;
  END_IF;
END_FUNCTION;
 
FUNCTION CheckBoxHandler
VAR
  rc      : INT;
  handle  : SYSHANDLE;
  tag     : DINT := 0;
  checked : BOOL;
END_VAR;
  rc := guiCheckBoxChangeEvent(check_box := handle, checked := checked);
  IF rc = 0 THEN
    guiGetTag(handle := handle, tag := tag);
    IF checked THEN
        DebugFmt(message:="Check box with tag \4 was checked", v4 := tag);
    ELSE
        DebugFmt(message:="Check box with tag \4 was unchecked", v4 := tag);
    END_IF;
  END_IF;
END_FUNCTION;
 
FUNCTION MenuHandler
VAR
  rc     : INT;
  handle : SYSHANDLE;
  tag    : DINT := 0;
  index  : INT;
END_VAR;
  rc := guiMenuClickEvent(menu := handle, index := index);
  IF rc = 0 THEN
    IF BOOL(handle) THEN
        guiGetTag(handle := handle, tag := tag);
        DebugFmt(message:="Menu with tag \4, index \1 was clicked", v1 := index, v4 := tag);
    ELSE
        DebugMsg(message:="No menu was clicked");
    END_IF;
  END_IF;
END_FUNCTION;
 
FUNCTION SpinnerHandler
VAR_INPUT
  handle : SYSHANDLE;
END_VAR;
VAR
  rc     : INT;
  tag    : DINT := 0;
  value  : DINT;
END_VAR;
  rc := guiSpinnerGetValue(spinner := handle, value := value);
  IF rc = 0 THEN
    guiGetTag(handle := handle, tag := tag);
    DebugFmt(message:="Spinner with tag \4 has value " + dintToStr(v := value), v4 := tag);
  END_IF;
END_FUNCTION;
 
FUNCTION TextBoxHandler
VAR_INPUT
handle : SYSHANDLE;
END_VAR;
VAR
  rc    : INT;
  tag   : DINT := 0;
  text  : STRING;
END_VAR;
  rc := guiTextBoxGetText(text_box := handle, text := text);
  IF rc = 0 THEN
    guiGetTag(handle := handle, tag := tag);
    DebugFmt(message:="Text box with tag \4 has text '" + text + "'", v4 := tag);
  END_IF;
END_FUNCTION;
 
//-----------------------------------------------------------------------------
// THREAD_BLOCK eventMonitor
//-----------------------------------------------------------------------------
THREAD_BLOCK eventMonitor;
VAR
  event       : INT := 0;
  handle      : SYSHANDLE;
END_VAR;
 
WHILE event <> -1 DO
  event := guiWaitEvent(timeout := -1, handle := handle);
  CASE event OF
    0   : DebugFmt(message := "Timeout");
    1   : ButtonHandler();
    2   : CheckBoxHandler();
    3   : MenuHandler();
  128   : SpinnerHandler(handle := handle);
  129   : TextBoxHandler(handle := handle);
  ELSE
    DebugFmt(message := "guiWaitEvent - event=\1", v1 := event);
  END_CASE;
END_WHILE;
END_THREAD_BLOCK;
 
PROGRAM example;
// These are the local variables of the program block
VAR
  eventMon: eventMonitor;
  rc : INT;
  form : SYSHANDLE;
END_VAR;
// The next code will only be executed once after the program starts
 
  DebugFmt(message:="guiOpen: \1", v1:=guiOpen());
 
  // Create a form with 5x5 tiles
  rc := guiFormCreate(form := form, grid := 6);
  DebugFmt(message:="guiFormCreate: \1", v1:=rc);
 
  // Row 1
  // Create a label with the text "Label"
  rc := guiLabelCreate(label := label, form:=form, x:=1, y:=1, w:=2, h:=1, text := "Label", tag:=10);
  DebugFmt(message:="guiLabelCreate: \1", v1:=rc);
 
  // Row 2
  // Create a check box
  rc := guiCheckBoxCreate(check_box := check, form:=form, x:=3, y:=2, w:=1, h:=1, tag:=20, style := 1, checked := TRUE);
  DebugFmt(message:="guiCheckBoxCreate: \1", v1:=rc);
 
  // Row 3
  // Create a spinner for the range -10..10
  rc := guiSpinnerCreate(spinner := spinner, form:=form, x:=3, y:=3, w:=3, h:=1,
           tag:=30, min_value := -10, max_value := 10, value := 0);
  DebugFmt(message:="guiSpinnerCreate: \1", v1:=rc);
 
  // Row 4
  // Create a text box
  rc := guiTextBoxCreate(text_box := textbox, form:=form, x:=3, y:=4, w:=2, h:=1, tag:=40, text := "Text", max_len := 10);
  DebugFmt(message:="guiTextBoxCreate: \1", v1:=rc);
 
  // Row 6
  // Create a button with the text "Click Me"
  rc := guiButtonCreate(button := button, form:=form, x:=5, y:=6, w:=2, h:=1, text := "Click Me", tag:=50);
  DebugFmt(message:="guiButtonCreate: \1", v1:=rc);
 
  // Create the menu.
  rc := guiMenuCreate(menu := menu, tag := 60);
  DebugFmt(message:="guiMenuCreate: \1", v1:=rc);
 
  // Set the menu items.
  rc := guiMenuSetItem(menu := menu, index:=1, title := "Item");
  DebugFmt(message:="guiMenuSetItem: \1", v1:=rc);
 
  // Start event monitor
  eventMon();
 
 // Make form visible
  rc := guiFormShow(form := form);
  DebugFmt(message:="guiFormShow: \1", v1:=rc);
 
BEGIN
// Code from this point until END will be executed repeatedly
END;
END_PROGRAM;