OnEvent
Sets an event callback function for an event type. The callback function is called when the event occurs.
Using callback functions removes the need for polling or checking for events. Callback functions have no arguments and needs to return an integer. They also need to be non-blocking.
CitectSCADA starts running the function immediately, without reading any data from the I/O devices. Any I/O device variable that you use will contain either 0 (zero) or bad quality. Only local variables are supported.
The return value of the callback will depend on the type of the event. Set the Fn argument to 0 (zero) to disable the event.
Notes
Syntax
OnEvent(Type, Fn)
Type:
The type of event:
0 - The mouse has moved. When the mouse moves the callback function is called. The return value must be 0.
1 - A key has been pressed. When the user presses a key, the callback function is called after CitectSCADA checks for hot keys. If the return value is 0, CitectSCADA checks for key sequences. If the return value is not 0, CitectSCADA assumes that you will process the key and does not check the key sequence. It is up to you to remove the key from the key command line.
If you are using a right mouse button click as an event, you should read about the ButtonOnlyLeftClick parameter.
2 - Error event. This event is called if an error is detected in Cicode, so you can write a single error function to check for your errors. If the return value is 0, CitectSCADA continues to process the error and generates a hardware error - it may then halt the Cicode task. If the return value is not 0, CitectSCADA assumes that you will process the error, and continues the Cicode without generating a hardware error.
3 - Page user communication error. A communication error has been detected in the data required for this page. If the return value is 0 (zero), CitectSCADA still animates the page. If the return value is not zero, it does not update the page.
4 - Page user open. A new page is being opened. This event allows you to define a single function that is called when all pages are opened. The return value must be 0.
5 - Page user close. The current page is being closed. This event allows you to define a single function that is called when all pages are closed. The return value must be 0.
6 - Page user always. The page is active. This event allows you to define a single function that is called when all pages are active. The return value must be 0.
7 - Page communication error. A communication error has been detected in the data required for this page. Reserved for use by CitectSCADA.
8 - Page open. This event is called each time a page is opened. Reserved for use by CitectSCADA.
9 - Page close. This event is called each time a page is closed. Reserved for use by CitectSCADA.
10 - Page always. This event is called while a page is active. Reserved for use by CitectSCADA.
11..17 - Undefined.
18 - Report start. The report server is about to start a new report. This event is called on the report server. The return value must be 0.
19 - Device history. A device history has just completed. The return value must be 0.
20 - Login. A user has just logged in.
21 - Logout. A user has just logged out.
22 - Trend needs repainting. This event is called each time CitectSCADA re-animates a real-time trend or scrolls an historical trend. You should use this event to add additional animation to a trend, because CitectSCADA deletes all existing animation when a trend is re-drawn. (For example, if you want to display extra markers, you must use this event.)
23 - Hardware error has been detected.
24 - Keyboard cursor moved. This event is called each time the keyboard command cursor moves. The cursor can be moved by the cursor keys, the mouse, or the Cicode function KeySetCursor(). Note that you can find where the keyboard command cursor is located by calling the function KeyGetCursor().
25 - Network shutdown. A Shutdown network command has been issued.
26 - Runtime system shutdown and restart. (Required because of configuration changes.)
27 - Event. An event has occurred.
28 - Accumulator. An accumulator has logged a value.
29 - Slider. A slider has been selected.
30 - Slider. A slider has moved.
31 - Slider. A slider has been released (that is stopped moving).
While responding to slider events 29, 30, and 31, you can set any variables but you cannot call functions that cause immediate changes to animations on the page (for example, DspText() and DspSym()). Types 29, 30, & 31 relate only to V3.xx and V4.xx animations, and will be superseded in future releases.
32 - Shutdown. CitectSCADA is being shutdown.
33 - Reserved for CitectSCADA internal use.
34 - 41 - CitectSCADA Confirmation Events. Reserved for CitectSCADA internal use. For the confirmation events, two sets of event type code are defined. The runtime calls the CitectSCADA event handler first, and conditionally proceed to the user's event handler depending on the return value of the CitectSCADA event handler.
34 -CitectSCADA Event: Child Window Close Confirmation.
35 - CitectSCADA Event: Main Window Close Confirmation.
36 - CitectSCADA Event: Maximize Window Confirmation.
37 - CitectSCADA Event: Minimize Window Confirmation.
38 - CitectSCADA Event: Restore Window Confirmation.
39 - CitectSCADA Event: Move Window Confirmation.
40 - CitectSCADA Event: Size Window Confirmation.
41 - CitectSCADA Event: Shutdown Confirmation Confirmation.
42 to 49 - User Confirmation Events. These functions are called when a specific event (mainly from Window title bar) occur and before the runtime performs the intended action. This gives a chance for the user to decide what to do with the event. If the return value is 0, the event will be passed on to the default handler so the intended action will be performed. If the return value is not 0, the event will be ignored and no further action will be taken.
42 - Child Window Close Confirmation, when the close button of the windows' title bar is clicked or an equivalent Windows' message is received.
43 - Main Window Close Confirmation, when close button of the windows' title bar is clicked which will cause the process to shutdown.
44 - Maximize Window Confirmation, when the maximize button of the windows' title bar is clicked or an equivalent Windows' message is received.
45- Minimize Window Confirmation, when the minimize button of the windows' title bar is licked or an equivalent Windows' message is received.
46 - Restore Window Confirmation, when the restore button of the windows' title bar is clicked or an equivalent Windows' message is received.
47 - Move Window Confirmation, when the window is being dragged or an equivalent Windows' message is received.
48 - Size Window Confirmation, when the windows is being resized or an equivalent Windows' message is received.
49 - Shutdown Confirmation, when shutdown() function is called.
50 - 127 - Reserved for future CitectSCADA use.
128 - 256 - User-defined events. These events are for your own use.
Fn:
The function to call when the event occurs. This callback function needs to have no arguments, so you specify the function with no parentheses (). The callback function needs to return INT as its return data type. You cannot specify a CitectSCADA built-in function as a callback function.
Set Fn to 0 to disable the event.
Return Value
0 (zero) if successful, otherwise an error is returned.
Related Functions
GetEvent, CallEvent, ChainEvent
Examples
Example 1 - Calls a function called KeyFn to determine if the ESC key has been pressed on a key press event.
OnEvent(1,KeyFn);
INT
FUNCTION KeyFn()
INT Key;
Key=KeyPeek(0);
IF Key=27 THEN
Prompt("ESC pressed");
RETURN 1;
ELSE
RETURN 0;
END
END
Example 2 - Calls a function called MouseFn to display the position of the mouse whenever it is moved.
OnEvent(0,MouseFn);
INT
FUNCTION MouseFn()
INT X,Y;
DspGetMouse(X,Y);
RETURN 0;
END
Example 3 - Presents a user with a confirmation dialog box when the main window close button is pressed.
sFUNCTION XyZStartup()
OnEvent(43, ConfirmShutdown);
END
INT FUNCTION ConfirmShutdown()
TaskNew("_ShutdownDlg", "", 2+8);
RETURN 1;
END
FUNCTION _ShutdownDlg()
STRING sMsg = "Are you sure ?";
INT nRC;
nRC = Message("Close this window and shutdown", sMsg, 1+32);
IF nRC = 0 THEN
Shutdown("","",1,"",0);
END
END
See Also