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:
Event#
|
Event
|
Action
required
|
Action
|
1
|
A button has been clicked.
|
Yes
|
Call guiButtonClickEvent.
|
2
|
A check box has changed state.
|
Yes
|
Call guiCheckBoxChangeEvent.
|
3
|
A menu has been clicked.
|
Yes
|
Call guiMenuClickEvent.
|
128
|
A numeric spinner has changed state.
|
No
|
Call guiSpinnerGetValue to get the current value of the spinner
|
129
|
A text box has changed value.
|
No
|
Call guiTextBoxGetText to get the current text of the text box.
|
130
|
The selection has changed in a List control.
|
No
|
Call guiListGetSelected to get the current index of the selection.
|
131
|
Login to the system menu failed.
|
No
|
Optional: Disable login with guiSysMenuSetPassword in case of brute-force attack.
|
132
|
Login to the system menu has succeeded.
|
No
|
None
|
133
|
A radio button has been selected.
|
No
|
The handle contains the selected radio button.
|
134
|
The system menu has been logged out.
|
No
|
None
|
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.
0
|
-
|
Disable timeout. The function will return immediately.
|
-1
|
-
|
Wait forever. The function will only return when data is received.
|
Output:
handle : SYSHANDLE
The handle of the control that caused the event.
Returns: INT
129
|
-
|
A text box has changed value
|
128
|
-
|
A numeric spinner has changed value.
|
3
|
-
|
A menu item has been clicked.
|
2
|
-
|
A check box has changed state.
|
1
|
-
|
A button has been clicked.
|
0
|
-
|
Timeout.
|
-1
|
-
|
Interface is not open (see guiOpen).
|
-3
|
-
|
Timeout is outside valid range.
|
-6
|
-
|
Event is no longer valid.
|
-11
|
-
|
GUI API is not supported.
|
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;
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;
VAR
eventMon: eventMonitor;
rc : INT;
form : SYSHANDLE;
END_VAR;
DebugFmt(message:="guiOpen: \1", v1:=guiOpen());
rc := guiFormCreate(form := form, grid := 6);
DebugFmt(message:="guiFormCreate: \1", v1:=rc);
rc := guiLabelCreate(label := label, form:=form, x:=1, y:=1, w:=2, h:=1, text := "Label", tag:=10);
DebugFmt(message:="guiLabelCreate: \1", v1:=rc);
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);
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);
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);
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);
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);
eventMon();
rc := guiFormShow(form := form);
DebugFmt(message:="guiFormShow: \1", v1:=rc);
BEGIN
END;
END_PROGRAM;
|
