Event Packet (edgPacket)
- Last UpdatedMar 28, 2023
- 7 minute read
The main controlling component of the event system, is the Event Packet. The Event Packet is used to define an event in its entirety, from the actions carried out when the object is added to the stack to the action carried out when it is removed from the stack.
The Packet should be considered as being the complete definition of the utility that requires a sequence of picks, when fully defined it can then be added to the event control system. Once the Packet is in the system, as the active event, it will then run autonomously until it has completed the pick sequence or removed from the system, forcible.
The Event Packet object can be broken down into several components, these basically are:
-
Administration data
-
Actions
-
Pick sequence definition
-
Input Data
-
Output Data
Currently the main interface into the object is via members, however, there are several methods available for defining the most common pick sequences.
Administration Data
There are several administration members available within the event object.
Currently the only members that have any relevance and are used by the system are:
|
.description |
Description of the event packet which is used when adding or removing the packet into/from the edg system. |
|
All packets relating to the same utility should have the same description. This makes the removing and maintenance of the system a lot simpler. |
|
|
.priority |
Defines the priority within in the edg system of the packet, with respects to other packets of the same description. |
|
The priority is a real number, zero being the highest priority. Where a primary packet (priority = 0) is added to the system and there is already another primary packet in the system. You will be prompted to whether you want to replace the one currently in the system with the one being added. |
|
|
Only major utilities should be flagged as being primary packets, for example, creating a section, element, and so on. Subsequent packets relating to the same utility (having the same description) should have a lower priority. |
|
|
Note: |
|
|
.remove |
Defines whether the event packet is automatically removed from the system when all the picks within the pick sequences and actions of the packet have been executed. |
|
The member is a BOOLEAN, true if the packet is to be removed, false if the packet is to be reinstated into the system. |
|
|
Note: |
|
|
.form |
Contains a pointer to the form that is to be shown when the event is added into the system. |
|
As the member is of "form" data type, the form must exist before it is assigned. |
|
|
When the event packet is added to the system, the form will automatically be shown and any initialization for the form will be run as normal. The form will be shown at the right hand side of the screen, slightly offset from the top. This allows any low level controlling forms (especially the positioning control form) to be positioned above the form. |
|
|
When the event packet is removed from the system, the form will automatically be removed from the system and any low level control forms that the packet may require. |
|
|
When another event is placed on the stack, the form will still be active, however, the event picks will relate to the event packet at the top of the stack. Any low-level forms that are not required by the new event packet, will be left on the screen, but made inactive. This shows that they are still required be a currently stacked event, but does not allow the modification of the event packet until the event has been reinstated at the top of the stack. |
Actions
All actions within the event packet object are defined as strings, however, they must represent either a standard command, PML function or PML object/form method. Old style macros must not be used within the actions of the object.
The main actions that a packet can have are:
|
.initialisation |
The action that is carried out when the event packet is initially added to the edg system. |
|
When an event packet is reinstated into the system (this is where the .remove members is false). The action will not be executed. |
|
|
.action |
An action which is carried out when all the picks within the pick sequence object (edgPickPacket) have been successfully completed. |
|
All data derived from picking in the sequence object are returned through the system via the local variable !this.return . |
|
|
.close |
An action which is carried out just prior to the event packet being removed from the edg system, whether after a successful completion of the .action, forcibly by another action of the same priority/type or using the escape key, when in the graphics canvas. |
|
The action is carried out within the event packet object, therefore, arguments that refer to !this relate to the members of the event packet object itself. |
|
|
Where a packet has a form associated with the packet (using the .form member) then the close action should not attempt to hide the form, as the system will automatically remove the form. |
|
|
.continue |
An action which is carried out after the event packet has been removed from the edg system, whether after a successful completion of the .action or forcibly by another action of the same priority. |
|
As the action is carried out external to the event packet object, it is not possible to access any data from the event packet, unless this has been stored via other means, i.e. a global variable or form. |
|
|
Note: |
|
|
.escape |
An action which works the same as the .continue member, however it is only carried out if the event has been removed from the using the <esc> key, from the Design graphic canvas. |
Pick Definition
The Pick Definition defines the number and types of picks required for the event packet. Refer to Pick Packet (edgPickPacket) for further information.
There are several predefined methods that allow the most commonly used event pick sequences to be declared without the need to define them explicitly. Where a predefined pick sequence does not exactly give the required picks, they can be used as a basis, then modified to suite the requirements.
Where there is no event packet method defined that gives the required pick sequences and pick types, then the developer will have to define the pick packet from first principles. However, it is hoped that the currently available methods for defining the pick sequences are adequate for most.
See below for a full list of the available methods.
Input Data
Where data is to be passed to an event packet, that is used either on initialization or whilst it is running, the data has to be stored in the objects .input member. This means the event packet can run autonomously without the need to access data from external variables or forms.
The input member is an ARRAY type, allowing any variable data type to be passed to the system. Setting the input data is the same as defining any other array element:
|
-- Define input data for packet !packet[1] = 'String' !packet[2] = 20 !packet[3] = !!ce.position !packet.append(10) !packet.insert(1, !!ce) . . |
When using the input data, the developer must make sure that they know the positions and data type of the element of the array they are using.
As input member can only be accessed directly from within the system by the action routines associated with the action members of the event object. The input variable must be refereed to thus !this.input:
|
-- Initialisation Action (using first element of input) !packet.initialisation = '!!form.eventInit(!this.input[1]) -- Action routine (using all input array and return pick data) !packet.action = '!!form.eventAction(!this.input, !this.return) -- Close action (using first element of input) !packet.close = '!!form.eventClose(!this.input[1]) |
Note:
Variables are passed by reference, therefore, changing the variable associated to
the input variable, will change the input variable.
Where a pick sequence requires multiple picked and the lower objects do not process the pick data, then the return array will contain multiple entries, one for each pick.
Output Data
All the objects within the event picking mechanism have a .return members, this is used to pass the data between the objects within the system. All the objects are of an ARRAY type, as this allows any data type to be assigned to the elements.
When a pick sequence has completed, all the derived data ascertained from the picking, will be returned into the .return member of the pick event object. Therefore, all .action routines requiring the pick data must use the variable.
Similar to the input variable, the return variable can only be accessed directly from within the system, and therefore must be declared in the argument list of the actions as !this.return.
|
-- Action routine _!packet.action = '!!form.eventAction(!this.return) |
In most instances, only the first element of the return array will be populated. This could be either with another array or a specific object type. In these cases, the developer may want only to pass the relevant element to the action routine:
|
-- Action routine _!packet.action = '!!form.eventAction(!this.return[1]) |
Note:
Variables are passed by reference, therefore, changing the variable associated to
the return variable, will change the input variable.