EVENTREGISTER

8.1, PLBCMP GUI Only

The EVENTREGISTER instruction (which may be abbreviated as EVENTREG) associates an object event with a program execution label. This program execution label is the entry point to a {routine} that is called upon occurrence of {event}. The instruction uses the following format:

Where:

label

Optional. A Program Execution Label.

object

Required. A previously defined and created object, pointer to an object, COLLECTION, or the keyword *CLIENT.

event

Required. A previously defined Numeric Variable, Literal, decimal number, or Expression that specifies the event type registered.

routine

Optional. A Program Execution Label called if the object event occurs.

keyword

Optional. One of the EVENTINFO keywords from the table below.

dest

Optional. A previously defined Character String Variable, Numeric Variable, or VARIANT that receives the result of the operation.

netobject

Required. A previously defined NETOBJECT variable.

name

Required. A previously defined Character String Variable or literal defining a valid event for the NETOBJECT.

Flags Affected: none

Note the following:

1. The {object} must have been previously CREATEd.

2. The {routine} is CALLed when the event action occurs. The LABEL execution pointer variable cannot be used in an EVENTREGISTER instruction or a compiler error occurs.

3. If no {routine} is specified, the event action is cleared.

4. {event} is a decimal number, a Numeric Variable, an Expression, or a keyword as defined in PLBEQU.INC. The supported values and keywords are:

 

Value	Keyword	Event	Notes
0	$LOAD	Load	WINDOW objects only
1	$ACTIVATE	Activate	WINDOW objects only
2	$DEACTIVATE	Deactivate
3	$CHANGE	Change
4	$CLICK	Click
5	$CLOSE	Close	WINDOW objects only
6	$DBLCLICK	DoubleClick
7	$DRAGDROP	DragDrop
8	$DRAGOVER	DragOver
9	$GOTFOCUS	GotFocus
10	$KEYPRESS	KeyPress
11	$LOSTFOCUS	LostFocus
12	$MOVE	Move
13	$MOUSEDOWN	MouseDown
14	$MOUSEUP	MouseUp
15	$MOUSEMOVE	MouseMove
16	$PAINT	Paint	WINDOW objects only
17	$RESIZE	Resize	WINDOW objects only
18	$TIMER	Timer	TIMER objects only
19	$OLDEVENT	OldEvent
20	$FORMINIT	FormInit	WINDOW objects only
21	$OBJMOVE	ObjMove	CONTAINER objects only
22	$UPDATED	Updated	Only AUTOMATION, DATATABLE and LISTVIEW (when using the SetEditColumn method).
23	$COLCLICK	ColClick	LISTVIEW objects with SORTHEADER property enabled
24	$VALIDATE	Validate
25	$ITEMACTIVATE	ItemActivate	LISTVIEW objects only
26	$BUTTONCLICK	ButtonClick	Same as $ITEMCLICK
26	$ITEMCLICK	ItemClick	Same as $BUTTONCLICK
27	$MOUSEWHEEL	MouseWheel	LISTVIEW objects only
28	$HSCROLL	HScroll	LISTVIEW objects only
29	$VSCROLL	VScroll	LISTVIEW objects only
30	$SELCHANGE	SelChange	RICHEDITTEXT objects only
31	$LINKCLICK	LinkClick	RICHEDITTEXT objects only
33	$CHILDSIG	ChildSignal	PL/B Web Server only
34	$RUNSUSPEND		RUNTIME object only
35	$RUNRESUME		RUNTIME object only
36	$RUNIDLE		RUNTIME object only
37	$ANSWER		AIOBJECT only
200	$JQueryEvent		HTMLCONTROL and PL/B Web objects

 

5. Any event number used other than a predefined {event} numbers is considered a user-defined event. User-defined events can be generated by an EventSend method of a PL/B Automation Server program object or by the EVENTSEND instruction.

6. The optional {keyword} operand defines the type of information that is retrieved. It must be from the following table:

 

Keyword	Use
ARGx=<var>	Retrieves the specified argument for the event. ARGx may be a value of ARG1 to ARG10 indicating the respective argument.
CHAR=<svar>	Retrieves the character that caused the event.
MODIFIER=<nvar>	Retrieves the Event Modifier.
OBJECTID=<nvar>	Retrieves the object identification number.
RESULT=<nvar>	Retrieves the expected result value.
TYPE=<nvar>	Retrieves the Event Type.
FASTEVENT	Dispatches an event for an object immediately. This should be used when an event from an Automation or ActiveX control requires the change of one of the parameters. As an example, the BeforeNavigate2 event for Internet Explorer requires a FASTEVENT.

 

7. The Event Modifier is a value accumulated from any combination of the following values:

 

Value	Modifier
0	No modifier provided
1	Alt Key
2	Ctl Key
4	Shift Key
8	Left mouse button down
16	Right mouse button down
32	Double click

 

8. The optional information {keyword=dest} requires that {routine} be specified.

9. Multiple {keyword=dest} pairs may be specified, separated by commas.

10. {object}, {event}, and {routine} are parameters passed to EVENTREGISTER. {dest} is a value that is returned.

11. Events are registered in an event table. Each object and event combination may be set to a single label. Upon the occurrence of the object event, the {routine} is called. This process is similar to a TRAP NORESET instruction.

12. Event registration need only be done once per event per object. Subsequent registrations of the same event for the same object will replace current registrations. The latest registration specifies the action of the runtime when {event} occurs.

13. Sunbelt's PL/B Form Designer allows the specification of code for a particular object and event. The Designer's code generator automatically adds event registration statements to the form if code is specified. The registration statements are executed during the FORMLOAD instruction. Events without user specified code are not registered. User-defined events are not available to the designer's code generation. A user program must explicitly register any user-defined events used in a PL/B program. The code added by the Designer to register the event is as follows:

 

	EVENTREGISTER	{object},{event},{routine}:
		CHAR=#EventChar:
		MODIFIER=#EventMod:
		OBJECTID=#EventObjId:
		RESULT=#EventResult:
		TYPE=#EventType:
		ARG1=#Argument1:
		...
		ARG10=#Argument10

14. When {object} is the keyword '*CLIENT', the event being registered is expected to arrive from a client program by using the EventSend method of a PL/B Automation Server program object. The EVENTREGISTER ARG1 to ARG10 parameters receives data for the EventSend method's arg1 to arg10 parameters.

Example:

EVENTREG

*CLIENT,121,MyRtn,ARG1=DIM20

 

Item	Specifies...
*CLIENT	that the event is registered for a PL/B Automation Server program object.
121	the user event being used.
MyRtn	the PL/B label of routine executed when the event is returned.
ARG1=DIM20	that one argument is expected with data stored into the DIM20 variable when the event is received. The data received for ARG1 is the data as provided by the PL/B Automation Server program object EventSend method's 'arg1' parameter.

15. Any events available for a NETOBJECT are found in the class library description as specified by the CLASS identification string.

16. The NETOBJECT {event} is specified using an event name that is documented for a .NET object in the class library. The event operand in this case is a data variable or literal.

17. When EVENTREG is executed for a NETOBJECT to register a .NET event as documented in the class library, the {event} operand MUST be a <svarslit> PLB variable with the event name exactly as documented.

18. When a numeric {event} type is registered for a NETOBJECT, the registered event in this case is always a user-defined event. In this case, the user-defined event is only generated by executing an EVENTSEND instruction with the same {event} type that was registered. Native .NET events as documented in the class library cannot be registered using a numeric {event} type.

19. All of the numeric predefined runtime event types are only applicable for the runtime internal native GUI objects. These predefined runtime event types do not apply to the .NET objects.

20. The .NET object events are specified by name and not by number.

21. Internal events using EVENTSEND are still specified using event numbers defined by the end user application.

22. The optional {keyword} operands for the EVENTREGISTER of a .NET object are described as follows:

 

Keyword	Use with .Net Objects
ARG1	NETOBJECT that receives a reference to the instance of the class that caused the event. The ARG1 NETOBJECT gets or sets properties as needed.
ARG2	NETOBJECT that receives a reference to the event data for the ARG1 NETOBJECT. The ARG2 NETOBJECT gets specific event data is as described by the .NET eventhandler for the ARG1 NETOBJECT class.
OBJECTID	Retrieves the object identification number for the .NET object.
ARGxx	All other ARGxx keywords contain no data for the .NET object.
CHAR	This keyword is not used by the .NET object.
MODIFIER	This keyword is not used by the .NET object.
RESULT	This keyword is not used by the .NET object.
TYPE	This keyword is not used by the .NET object.
FASTEVENT	Dispatches an event for a .NET object immediately.

 

23. Specialized events for the PL/B Web Server runtime can be registered where the {event} is a decimal number, a Numeric Variable, an Expression, or a keyword as defined in PLBEQU.INC. The supported values and keywords are:

 

Value	Keyword	Event	Notes
301	$ClientEventOrient	Orient	PL/B Web Server Only.
302	$ClientEventPostMessage	PostMessage	PL/B Web Server Only.

 

24. When registering the $jQueryEvent for a HTMLCONTROL object, the EVENTREGISTER {routine} replaces a previously registered {routine} including the {routine} of an ACTIVATE for the HTMLCONTROL.

25. After EVENTREG is executed for a PLBOBJECT object, the expected {event} can be generated using the EVENTSEND instruction which is executed from the CLASSMODULE load module code. The generation of {event} is done using an 'EVENTSEND *CLASS...'instruction from code executing in a CLASSMODULE load module which was loaded using a 'CREATE PLBOBJECT' instruction. The 'EVENTREG {plbobject}..." instruction is only supported by a Windows Runtime.

Example of 'TestProgram.plc':

.

            INCLUDE plbequ.inc

.

TestClass PLBOBJECT CLASS="MyClass.plc"

.

            ...

.

           CREATE TestClass

.

           EVENTREG TestClass, $CHANGE, ChangeFunc

           ...

           SETPROP TestClass, *PROP1="10" //Change property!

See Also: CREATE, Object Instructions