Back to Contents

Front End Protocol

This page describes the Front End Protocol: the communication between the Runtime System and the Front End.

• Definition of the Front End Protocol
• Runtime System Commands
• Front End Events
• Communication Initialization

See also: Dynamic User Interface, Abstract User Interface tree, Front End Events

Definition of Front End Protocol

The purpose of the Front End Protocol is to synchronize the Abstract User Interface Tree maintained by the Runtime System and the corresponding copy hold by the Front End. For more details about these concepts, see the Dynamic User Interface description.

This Abstract User Interface Tree is used by the Front End to create graphical objects. The Front End and the Runtime System have the same version of the Tree. This way, communications correspond to AUI Tree synchronization operations: on one hand the Front End sends modification requests to the Runtime System (also called Front End Events); on the other hand, the Runtime System analyses and validates Front End requests, performs some codes if required, and sends back modification orders.

The following schema describes typical communication between the Runtime System and the Front End:

1. Initialization phase: The Runtime System sends the initial AUI Tree.
2. The Front End builds the Graphical User Interface according to the AUI Tree.
3. The Front End waits for a user interaction (mouse click, keyboard typing).
4. When the user performs some interaction, the Front End sends Front End Events corresponding to the modifications made by the user.
5. Front End Events are analyzed and validated by the runtime system.
6. The Runtime System sends back the result of the Front End requests, by the way of AUI Tree Modifications Commands.
7. When receiving these commands, the Front End consequently modifies its version of the AUI Tree and updates the Graphical User Interface, then it waits for new user interactions (step 3).

String Literals

In the front End Protocol, the type of all attributes is string. The value of the attributes follows the same rules as 4gl string literals:

• values are enclosed between double quotes : "
• CR character is \n
• TAB character is \t
• double quotes character is \"

Example:

01   { GroupBox 25 {  { text "this is a \"GroupBox\""} } {}} 

Runtime System Commands

The Runtime System sends several commands to the Front End in order to modify the User Interface. Then, these commands are modifications of the AUI Tree. Modifications can be:

• Adding children to a node (appendNode)
• Changing node attributes (updateNode)
• Removing a node (removeNode)

Syntax:

om command-id 
{ 
  [ { { appendNodeCommand | updateNodeCommand | removeNodeCommand } } ] [...]
}

• command-id is the number of the command. This number is automatically increased for each command sent by the current application to the Front End. The very first appendNode command used to initialize the Protocol is command 0.

Warning: There is no verification made about this order. The communication wire is supposed to be reliable and the Runner and the Front End do not perform verification about lost commands.

appendNode Command

The append Node command adds one or several children and their attributes to a specified node. Several children (and sub-children) and can be added in the same appendNode command. Typically this command is sent by the Runtime System when there are new graphical objects to display. This command is also used to initialize communication.

Syntax:

  appendNode parent-id new-node

Where new-node is :

  tagName new-id { [ attribute-list ] } { [ child-list ] } }

Where attribute-list is :

  { attribute-name "attribute-value" } [...]

  { new-node } [...]

Notes:

1. parent-id identifies the existing node.
2. tag-name identifies the type of the added child.
3. new-id is a unique id for the new node created.
4. attribute-name is the name of the attribute of the node.
5. attribute-value is the value of the attribute.

Example:

This example shows a appendNode command creating a Menu : a Menu node is added.

01 appendNode 0 Menu 356 { { active "1"} { text "MAIN"} { posY "0"} { selection "357"} }
02 {
03   { MenuAction 357 { { name "Option1"} { text "Option1"} { comment ""} } {}} 
04   { MenuAction 358 { { name "Flow"} { text "Flow"} { comment ""} } {}} 
05   { MenuAction 359 { { name "Window"} { text "Window"} { comment "OPEN WINDOW"} } {}} 
06   { MenuAction 360 { { name "Form"} { text "Form"} { comment "form: scroll, erase..."} } {}} 
07   { MenuAction 361 { { name "Dialog"} { text "Dialog"} { comment ""} } {}} 
08   { MenuAction 362 { { name "Display"} { text "Display"} { comment ""} } {}} 
09   { MenuAction 363 { { name "Options"} { text "Options"} { comment "OPTIONS"} } {}} 
10   { MenuAction 364 { { name "Exit"} { text "Exit"} { comment ""} } {}} 
11 }

removeNode Command

The removeNode command removes a specific Node. Typically this command is used when some graphical objects are no longer used and have to be removed from the User Interface.

Syntax:

  removeNode node-id

Notes:

1. node-id identifies the existing node to be deleted

Example:

This example shows a removeNode command removing an option of a Menu: the node removed is a MenuAction Node, created by the appendNode command described in the example below.

01 removeNode 357

updateNode Command

The updateNode command modifies some attributes of a specific Node. Typically, this command is used to modify the aspect of a widget, for example to validate the value entered by a user in a form field. This command is also used to confirm a focus change, with modifying the focus attribute of the UserInterface Node.

Syntax:

  updateNode node-id { [ attribute-list ] }

Where attribute-list is :

  { attribute-name "attribute-value" } [...]

Notes:

1. node-id identifies the modified node.
2. attribute-name is the name of the attribute of the node.
3. attribute-value is the value of the attribute.

Example:

This example shows an updateNode command confirming a focus change: the focus now goes to the Menu option identified by id "358", created by the appendNode command described in the example below. The UserInterface Node has always an id equal to 0 (zero).

01 updateNode 0 { focus "358" }

Front End Events

The Front End sends some "modification requests" represented as "Front End Events" to the Runtime system. A group of modification requests can be sent in the same event _om command.

These events can be:

• events associated to any defined Action (ActionEvent). This type of event is sent if a user invokes an enabled Action : Action within Dialog, MenuAction within Menu or StartMenuCommand within StartMenu.

• events associated to closing the current window (CloseWindowEvent). This type of event is sent if a user wants to close the current Window.
• events associated to modifications of the User Interface (ConfigureEvent). This type of event is sent if a user modifies something in the User Interface. Typically, this is used for focus changes or when data is entered in a form field.
• events associated to Keyboard action which can not be handled by any other event (KeyEvent). This type of event is sent to notify the Runtime System that a user has pressed one of the following keys : tab, shift+tab, key_up, key_down, page_up, page_down. 
• events associated to local functions (FunctionCallEvent). This type of event is sent when a local function is over, to sent back the result of this function. Typically, local functions are DDE Functions, winexec.
• events sent by the Front End to terminate an application (DestroyEvent). This type of event is sent when there is an error on the Front End side that needs that the application stops.

In fact, a very basic Front End needs only to handle KeyEvent event, and can send all keys pressed by the user to the Runtime System. For performance and more enhancements, most of the key pressed events are handled locally by the Front End. Only the keys mentioned below are sent. 

Syntax:

event _om command-id {} 
{ 
  { { ConfigureEvent 0 { { idRef "object-id" } attribute-list  } }
  | { KeyEvent 0 { { keyName "key-value" } } }
  | { ActionEvent 0 { { idRef  "object-id" } } }
  | { FunctionCallEvent 0 { { result "result-value" } } }
  | { DestroyEvent 0 { { status "status-value" } { message "message-value" } } }
  } [...]
}

{ attribute-name "attribute-value" } [...]

Notes:

1. command-id is the number of the event. This number is increased automatically for each event _om command sent by the Front End to Runtime System. 
2. object-id is the id of the node which is concerned by the event. Typically, this is the id of the object which has been changed by the user, by example a form field.
3. attribute-name is the name of the attribute of the node. See Front-End Events description for attribute list.
4. attribute-value is the value of the attribute.
5. key-value is the value of the key pressed.
6. result-value is the value returned by the local function executed.
7. status-value is the error identifier that causes the DestroyEvent.
8. message-value is the error message explaining the reason of the DestroyEvent.

Example:

This example shows an event _om command corresponding to the following interaction:

• the user enters a value into a field. A ConfigureEvent with the new value is sent.
• the user click with the mouse in another field. A ConfigureEvent with the position of the cursor in the new field is sent.

01 event _om 3 {} 
02  { 
03    { ConfigureEvent 0 { { idRef "35" } { value "someText" } { cursor "4" } } }
04    { ConfigureEvent 0 { { idRef "32" } { cursor "6" } } } 
05  }           

Communication Initialization

Communication is initiated by the Runtime System, which sends some meta information to the Front End. The meta information sent is "encoding". The Front End replies by some information, used to get the version of the Front End. Then the Runtime System sends the first version of the AUI Tree generated according to the interactive elements used in the program (Menus, Windows and Forms).

The root node of the Tree is the User Interface Node. This node is sent once to the Front End. The keyword appendNode is used there to create the root node (with id equals to 0), and to add all the children needed by the Front End to build the initial Graphical User Interface.

Syntax:

DVM :   meta ClientInfo { { encoding 'character-set' } { version 'interface-version' } }

FE :    client client-type client-host client-version connections: connection-id

DVM :   om 0 { 
      	       { appendNode 0 UserInterface 0 { [ attribute-list ] } { [ children-list ] } }
             }

{ attribute-name "attribute-value" } [...]

{ child-type child-id { [ attribute-list ] } { [ children-list ] } } [...]

Notes:

1. character-set defines the encoding character code set used in the protocol.
2. interface-version defines the version of the user interface (nodes and attributes).
3. client-type is the type of the front end. Can be GDC, GJC, and so on.
4. client-host is the network address (alphanumeric value) of the computer hosting the Front End.
5. client-version is the version of the Front End.
6. connection-id is the number of application already launched on the Front End.
7. attribute-name is the name of the attribute of the node.
8. attribute-value is the value of the attribute.
9. child-type is the node type of the child.
10. child-id is a unique identifier for each children.