The Thot Application Generation Language

1.1 Menus and specific commands

The EDITOR.A application schema defines the menus of the main window (if this main window exists) and those attached to the menu bar of each document window. The app application allows one to define different menus for different document types (identified by their structure names). For a specific document type, menus can differ form one view to another (the range in presentation schema identified the view when the menu is specific to one view).

The application schema associates a command with each item in these menus. Each item is located within a menu or a cascade submenu of a menu. The cascade is limited to one level.

When the user selects a menu item, the corresponding command is called, with the current document and view as parameters.

There are different menu sections in the EDITOR.A application schema:

• The Main Window section is optional. It defines the menus attached to the main window.
• The Document Windows section is mandatory. It defines the menu bar of all document windows.
• The Structure_name Windows sections are optional. They specify the menu bar for specific document types.

1.2 Events and actions

An event is raised by the editor whenever a Thot standard editing command perform some treatment that the application needs to complement or replace. For example, an event can be raised when the user selects an element, modifies a character string, creates or deletes a logical element, associates an attribute with an element, opens or closes a document view, saves a document, etc.

Only standard editing commands raise events. Specific commands associated with menu items in an application schema do not raise any event.

Each event raised by Thot is associated with the object concerned by the Thot editing command that triggers the event: element, attribute, view, document, etc.

Whenever an event is raised, Thot calls the corresponding actions that is associated with the event and the corresponding object in the application schemas in use.

The user and the programs (commands and actions) can access the same functions, but through different interfaces: standard Thot commands for the user, API for programs. The operations performed on documents by an application programs using the Thot API do not create events. However, there are some exceptions to this rule; they are mentioned below.

The Thot standard editing commands generally produce two events with the same name but with different suffixes:

• .Pre: this event is raised (and the action is executed) when the standard command is called by the user, before being processed by the editor. It allows the application to perform some processing, before the editor executes the standard command or instead of the normal processing of the editor. The action called in the application by the event returns a boolean value to indicate whether or not the performed action replaces the standard processing of the editor. If it is a replacement (True is returned by the action), the editor does not perform the normal processing.
• .Post: this event is raised (and the action is executed) after the editor has performed the standadrd command normally.

When an action performed on a .Pre event has replaced the normal processing of the standard command, there is no corresponding .Post event since the editor has not processed the command.

Each time an action of the application is called by an event, it receives a context as a parameter, which allows the application to identify the conditions in which the event has been raised. This context varies from an event to the other because it only provides information significant for the event in question.

Here is a list of all items that can be found in the context (for each event, only a subset of this list is present):

• the standard editing command which triggered the event (this information is always present because it permits the identification of the event and it determines the other items present in the context);
• the document in question;
• the element in question;
• the element type in question;
• the target element of the editing operation. It may be different from the element in question, for instance in the case of a reference;
• the type of the presentation rule in question;
• the attribute in question;
• the attribute type in question.

Section 5 lists all the events that can be raised, with the name of the event, the parameters received by the action which handles this event and the conditions in which it is raised.

2.1 Application integration

A single application can use several application schemas: one per structure schema for which specific commands or actions must be performed (for instance, Report and Paragraph) and one general application schema (the EDITOR schema). When an event is raised for a given element, the editor consults first the application schema of the structure defining this element in order to check whether an action has been attached to this event. If it is not the case, the editor consults sequentially the application schemas of the parent elements and finally the EDITOR application schema.

The EDITOR.A schema lists the names of other application schemas involved in the application, in its USES section. The A compiler uses this list to load the corresponding commands and actions.

The USES section lists also all the modules needed by the application.

SchemasAndModules = SchemaOrModule < ',' SchemaOrModule > ';' .
SchemaOrModule    = DocumentType | Module .

The Thot library provides optional modules which can be used or not by an application. As an example, a document reader application does not need editing functions. The USES section allows application developer to explicitly load the needed Thot modules. The available modules are:

• Editing: This module provides basic editing functions. It is automatically loaded when at least one standard editing command is used in the MENUS section (TtcCutSelection, etc.)
• StructEditing: This module has to be loaded explicitly. It provides restructuring functions and handles the Thot standard insertion menu.
• StructSelect: This module has to be loaded explicitly. It provides a structural selection instead of the standard one (no automatic replacement, ability to select directly structured elements, etc.)
• Search: This module provides search and replace functions. It is automatically loaded when a Thot search command is used.
• StructSearch: This module has to be loaded explicitly. It allows a combination of structural search with textual search and replace.
• Index: This module has to be loaded explicitly. It provides the Thot index capability.
• DisplayEmptyBox: This module has to be loaded explicitly. It displays empty elements as grey rectangles.
• Lookup: This module has to be loaded explicitly. It provides an XLookupString function that allows users to insert composed characters into Motif widget.
• Keyboards: This module has to be loaded explicitly. It allows Thot to display the Symbols and Greek keyboards when needed.
• Graphics: This module has to be loaded explicitly. It allows Thot to display the Graphics keyboard when needed.

2.2 Menus declaration

The MENUS section defines the menus contituting a menu bar (see example in 7):

• The Main Window section is optional. It defines the menu bar of the main window.
• The Document Windows section is mandatory. It defines the menu bar of all document windows.
• The Structure_name Windows sections are optional. They specify the menu bar for specific document types.

Menus =         [ 'Main' 'Window' ':' MenuList ]
                [ 'Document' 'Windows' ':' MenuList ]
                < DocumentType 'Windows' ':' MenuList > .
 
MenuList =      'BEGIN' NewMenu < NewMenu > 'END' ';' /
                NewMenu .
 
NewMenu =       [ 'view' ':' ViewNum ] MenuIdent
                [ '.' SubmenuIdent] [ ItemCascade ] ';' .
ItemCascade =   'Separator' / 'Button' ':' ItemAction /
                'Toggle' ':' ItemAction /
                'Dynamic' ':' ItemIdent .
ItemAction =    ItemIdent '->' ActionIdent .
 
DocumentType =  NAME .
MenuIdent =     NAME .
SubmenuIdent =  NAME .
ItemIdent =     NAME .
IdentAction =   NAME .

For each menu item, the application schema associates a specific command, except for the standard menus, composed by the Thot editor. For these menus neither items nor actions have to be specified. There are two such menus: "Attributes_" and "Selection_".

The Thot toolkit allows application designers to declare one-level cascade menus (menu and submenu).

A menu item can be:

• a simple push button: "Button",
• a toggle button: "Toggle",
• a separator: "Separator" (there is no action in this case),
• or a dynamic entry: "Dynamic" (allows dynamic extension of the dialogue).

The Thot toolkit is designed to support multilingual dialogue. Names of menus, submenus and menu items declared in the application schema are considered as generic names. When the application starts, the editor looks for a dialogue table:
config/$LANG-'name'dialogue ('name' represents the application name)
to substitute generic names by localized name adapted to the current language $LANG.

The A compiler automatically generates a EDITORdialogue file that can be used as a model to construct dialogue tables for each supported language.

2.3 Associating actions with events

Actions that must be executed when certain events are raised, are specified in sections DEFAULT, ELEMENTS and ATTRIBUTES. Association of actions with events is simply expressed by the name of the event (see the list of events in section 5) followed by an arrow (the two characters '-' and '>') and the name of the action.

The name of the event contains the suffix .Pre or .Post depending on whether the action must be performed before or after normal processing by the editor. If no suffix is present the event is assumed to have the .Pre suffix.

The name of the action is the name of the procedure written by the programmer and called by the event.

EvtAction =    EvtIdent [ '.' PostPre ] '->' ActionIdent ';' .
PostPre =      'Post' / 'Pre' .
EvtIdent =     NAME .
ActionIdent =  NAME .

2.4 Default actions

The DEFAULT section includes the event/action associations which, by default, apply to all element types and all the attributes defined in the structure schema corresponding to the application schema.

For a given element type and for a given event, when the ELEMENTS section does not contain an event/action association, the association of the DEFAULT section is taken into account if it exits. The DEFAULT section can be absent. It can also contain only a subset of the events listed in section 5. When the ELEMENTS section for a given element type and the DEFAULT section do not define any action for a given event, this event has no effect for the elements of that type.

The same principle applies to attributes: the DEFAULT section specifies the event/action associations which apply to all attributes for which the ATTRIBUTE section does not include these events.

The DEFAULT section is composed of the DEFAULT keyword followed by an event/action association, if there is a single default association, or by a sequence of associations between the keywords BEGIN and END, if there are several. The END keyword must be followed by a semicolon. The event/action associations can be either for element types (see section 2.5) or for attributes (see section 2.6).

                 'DEFAULT' EvtActionList
EvtActionList =  EvtAction /
                 'BEGIN' EvtAction < EvtAction > 'END' ';' .

2.5 Actions associated with elements

The actions to be called for elements of a given type are defined in the ELEMENTS section. In this section, the name of each element type requiring actions is followed by a colon and by the event/action association to be applied (if there is only one) or the list of associations (if there are several) between the keywords BEGIN and END. The END keyword is followed by a semicolon.

In the case where the element type is a mark pair, but only in this case, the type name can be preceded by the keywords First or Second. These keywords indicate whether the associations that follow apply to the first or second mark of the pair.

Each event/action association for an element type is composed in the same way as described in section 2.3.

                 'ELEMENTS' < ElemActionList >
ElemActionList = ElemActions < ElemActions > .
ElemActions =    [ FirstSec ] ElemIdent ':' EvtActionList .
FirstSec =       'First' / 'Second' .
ElemIdent =       NAME .
EvtActionList =   EvtAction /
                 'BEGIN' EvtAction < EvtAction > 'END' ';' .

2.6 Actions associated with attributes

The actions to be called for given attributes are defined in the ATTRIBUTES section. In this section, the name of each attribute requiring actions is followed by a colon and by the event/action association to be applied (if there is only one) or the list of associations (if there are several) between the keywords BEGIN and END; the END keyword is followed by a semicolon.

Each event/action association for an attribute is composed in the same way as indicated in section 2.3, but only certain events are allowed for attributes, those beginning with Attr (see section 5.1 for the definition of these events).

                 'ATTRIBUTES' < AttrActionList >
AttrActionList = AttrActions < AttrActions > .
AttrActions =    AttrIdent ':' EvtActionList .
AttrIdent =      NAME .

5.1 Events for attributes

The following events only appear in the DEFAULT section or in the ATTRIBUTES section of an application schema.

If they appear in the DEFAULT section, they are raised each time an attribute of any type is created, modified, deleted, saved or read (according to the event), whatever the element in question.

In the ATTRIBUTES section, these events are associated with an attribute type and raised by the editor when attributes of this type are created, deleted, modified, saved or read (according to the event), whatever the element in question.

Each attribute's event is accompanied with a pointer to the subsequent structure (this structure is defined in the appaction.h file):

typedef struct {
  TTEevent event;
  Document document;
  Element element;
  Attribute attribute;
  AttributeType attributeType;
} NotifyAttribute;
 

AttrCreate.Pre (NotifyAttribute):

The editor is going to create for the element element indicated an attribute of type attributeType. The attribute field is not filled since the attribute has not yet been created.
If it deals with a mandatory attribute (preceded by an exclamation mark in the structure schema), the attribute is always created by the editor, whether the action returns True or False and the editor raises the events AttrCreate.Pre (before creating the attribute) and AttrModify.Pre (before requiring the user to assign a value to the attribute).
Attributes with an imposed value (entered with the WITH keyword in the structure schema), do not raise AttrCreate.Pre event when created.

AttrCreate.Post (NotifyAttribute):

The editor has created the attribute of type attributeType for the element element.
Attributes with imposed value (entered with the WITH keyword in the structure schema) do not raise a AttrCreate.Post event.

AttrDelete.Pre (NotifyAttribute):

The editor is going to delete the attribute attribute for the element in question. The attribute is still attached to the element and its value is still accessible.

AttrDelete.Post (NotifyAttribute):

The editor has removed an attribute of type attributeType for the indicated element. The attribute field is not filled since the attribute no longer exists.

AttrExport.Pre (NotifyAttribute):

This event occurs when a document is exported in a format that is not the standard Thot format (pivot format), and even if export is required by an application through the API (exception to the rule). The editor is going to generate the translation of the attribute attribute of the element element. If the action returns True, the attribute is not exported in the output file.

AttrExport.Post (NotifyAttribute):

The editor has exported in the output file the attribute attribute of the element element.

AttrMenu.Pre (NotifyElement):

The editor is composing the ``Attributes'' menu and will add to this menu an item which allows the user to create an attribute of type attributeType for element element. The attribute field is not filled since the attribute has not yet been created.

If the action called by the event returns True, the corresponding item is not included in the menu; if it returns False, the item is normally included in the menu.
There is no AttrMenu.Post event.

AttrModify.Pre (NotifyAttribute):

The editor is going to change the value of the indicated attribute attribute for the element element.
If this is a mandatory attribute (i.e. an attribute preceded by an exclamation mark in the structure schema) and if the action gives a value to the attribute and returns True, the editor will not require the user to give a value.

AttrModify.Post (NotifyAttribute):

The editor has changed the value of the attribute attribute for the element element. The attribute then has the new value.

AttrRead.Pre (NotifyAttribute):

This event occurs when a document file is read and even if this is required by the API (exception to the rule). The editor starts reading an attribute of type attributeType. The attribute field is not significant. If the action returns True, the attribute is not included in the abstract tree.

AttrRead.Post (NotifyAttribute):

The editor has read the attribute attribute of the element element and has inserted it into the abstract tree.

AttrSave.Pre (NotifyAttribute):

This event occurs when a document is saved to a file and even if the backup is required by the API (exception to the rule). The editor writes the attribute attribute of the element element. If the action returns True, the attribute is not written in the file.

AttrSave.Post (NotifyAttribute):

The editor has written in the file the attribute attribute of the element element.

5.2 Events for elements

The following events only appear in the DEFAULT or ELEMENTS section of an application schema.

In the DEFAULT section, they are raised as soon as any element is affected by the relevant event.

In the ELEMENTS section, they are associated with an element type and raised as soon as an element of this type is affected by the relevant event.

Three different structures can accompany the events on elements (see the structure specified for each event. These structures are defined in the appaction.h file):

typedef struct {
  TTEevent event;
  Document document;
  Element element;
  ElementType elementType;
  int position;
} NotifyElement;
 
typedef struct {
  TTEevent event;
  Document document;
  Element element;
  ElementType elementType;
  ElementType targetElementType;
} NotifyOnElementType;
 
typedef struct {
  TTEevent event;
  Document document;
  Element element;
  Element target;
  Document targetdocument;
} NotifyOnTarget;
 
typedef struct {
  TTEevent event;
  Document document;
  Element element;
  Element target;
  int value;
} NotifyOnValue;
 

ElemActivate.Pre (NotifyElement):

The user has just double-clicked on the element element. The selection has not already changed. This event is accepted for all elements (references or not). The position field has no meaning.

ElemActivate.Post (NotifyElement):

The selection has been moved once the user has double-clicked on the element element. You can ask the API where the new selection is if is the ElemSelect event has not been retrieved. The position field has no meaning.

ElemChange.Pre (NotifyElement):

The user is going to change the type of element element. The element has still its old type. The elementType field indicates the new type that will be given to the element. The position field has no meaning.

ElemChange.Post (NotifyElement):

The element element has just changed type. The elementType field indicates the previous type of the element. The position field has no meaning.

ElemLClick.Pre (NotifyElement):

The user has just clicked (Left button down) on the element element. The selection was not changed. This event is accepted for all elements (references or not). The position field has no meaning.

ElemMClick.Pre (NotifyElement):

The user has just clicked (Middle button down) on the element element. The selection was not changed. This event is accepted for all elements (references or not). The position field has no meaning.

ElemRClick.Pre (NotifyElement):

The user has just clicked (Middle button down) on the element element. The selection was not changed. This event is accepted for all elements (references or not). The position field has no meaning.

ElemClick.Pre (NotifyElement):

The user has just clicked (button up) on the element element. The selection was changed. This event is accepted for all elements (references or not). The position field has no meaning.

ElemClick.Post (NotifyElement):

The selection has just clicked on the element element. It's similar to the Pre event because Thot doesn't do anything for this event.

ElemCopy.Pre (NotifyElement):

The user is going to copy the element element contained in the abstract tree. The position field has no meaning.
When the event must copy a whole subtree, this event can only be raised for the root of the subtree to be copied or to each element of the subtree, depending on the notification mode in which the document is placed (see the TtaSetNotificationMode function of the API). However, even when the document is in the full notification mode, the event is only raised for the elements which require it.

ElemCopy.Post (NotifyElement):

The element element has just been copied. It is placed in the abstract tree. The position field has no meaning.
When the event has copied a subtree, this event can only be raised for the root of the copied subtree or on the contrary to each element of the subtree, depending on the notification mode of the document (see the TtaSetNotificationMode function of the API). However, even when the document is in the full notification mode, the event is only raised for the elements which have required it.

ElemDelete.Pre (NotifyElement):

The element element will be removed from its abstract tree if a « Delete » or « Cut » command is issued by the user, or if the Thot kernel has detected two Text elements that may be merged. This element is still included in the abstract tree when the event is raised.

The position field may take different values depending on the three following cases:

Case 1: « Delete » or « Cut »

This event signals the deletion of an item of a delete sequence that depends on the selection. This functionnality allows the application, if such treatment is requested, to postpone its treatment until the full delete sequence is obtained.

Values of the position field maty be the following:

TTE_STANDARD_DELETE_FIRST_ITEMS: the element is among the first items of the delete sequence: the event delete sequence is not complete, and next event(s) will follow this one.

TTE_STANDARD_DELETE_LAST_ITEM: this is the last item of the delete sequence.

Case 2: Two Text units may be merged

Two Text elements own the same caracteristics, and may be merged. The content of the second element will be merged into the first one, and this element will be deleted from the abstract tree if the application authorizes this deletion. Otherwise, these two elements will come apart.

The position field value is: TTE_MERGE_DELETE_ITEM

Case 3: Requested deleting (must be suppressed)

The element will be necessarily deleted independent of the value returned by the event treatment. This event goal is simply indicative.

Value of the position field is: TTE_TOOLKIT_DELETE

When the event must remove a whole subtree, this event can only be raised for the root of the subtree to be removed or on the contrary, to each element of this subtree, depending on which notification mode the document is in (see the TtaSetNotificationMode function of the API). However, even when the document is in the full notification mode, the event is only raised for the elements which require it.

ElemDelete.Post (NotifyElement):

An element of type elementType, child of element, has been removed from the abstract tree. The position field gives the position of the removed element in the list of the children of element (0 for the first child, 1 for the second, etc.). If a subtree has been deleted, the event is only raised for the root of this subtree and not to each element of the subtree, even if the document is included in the full notification mode.

ElemExport.Pre (NotifyElement):

This event occurs when a document is exported, and even if export is required by the API (exception to the rule). The editor is going to generate the translation of the element element. The position field has no meaning. If the action returns True, the subtree is not exported in the output file.

ElemExport.Post (NotifyElement):

The editor has exported the element element. The position field has no meaning.

ElemExtendSelect.Pre (NotifyElement):

The user wants to extend the selection to the element element. This event is only raised when the selection implies at least two elements. The position field has no meaning.

ElemExtendSelect.Post (NotifyElement):

The selection has just been extended to the element element. The position field has no meaning.

ElemInclude.Pre (NotifyElement):

The user is going to include a new element of type elementType as the child of the element element. The position field gives the position of the element which will be included in the list of the children of element (0 before the first child, 1 after the first child, 2 after the second one, etc.).
If a whole subtree is to be included, the event is only raised for the root of the subtree.

ElemFetchInclude.Pre (NotifyOnTarget)

The user requires that the copy element element be up to date with the value of its source element.

In any case the source element are not accessible (for example when this is placed in a non loaded document), so the element target and targetdocument components are equal to NULL. Otherwise, the element target and targetdocument point to the source element and document where this is placed, respectively.

ElemFetchInclude.Post (NotifyOnTarget)

If the document where the source element is placed is accessible, the copy element element was up to dated with the value of element target.

ElemInclude.Post (NotifyElement):

The element element has just been included. The position field has no meaning.
If a whole subtree has been included, the event is only raised for the root of this subtree.

ElemMenu.Pre (NotifyElement):

The editor is composing the ``Insert'' or the ``Paste'' menu and will add to this menu an item which allows the user to create or paste an element of type elementType (with its descent) as the child of the element element. The position field gives the position of the element that will be created or pasted (when the user chooses the item of the menu) in the list of the children of element (0 before the first child or as the first child if element has no child, 1 after the first child, 2 after the second one, etc.).
If the event is in the ELEMENTS section, it is only raised when the editor includes in the menu the item regarding an element of the corresponding type.
If the event is in the DEFAULT section, it is raised as soon as the editor includes an item in the ``Insert'' menu, whatever the element type in question.
If the action called by the event returns True, the corresponding item is not included in the menu; if it returns False, the item is normally included in the menu.
There is no ElemMenu.Post event.

ElemMove.Pre (NotifyElement):

The user is going to create a surrounding element for element element. The position field has no meaning.

ElemMove.Post (NotifyElement):

The element element has just been surrounded by a new element. The position field has no meaning.

ElemMouseOut.Pre (NotifyElement):

Not supported yet.

ElemMouseOut.Post (NotifyElement):

Not supported yet.

ElemMouseOver.Pre (NotifyElement):

Not supported yet.

ElemMouseOver.Post (NotifyElement):

Not supported yet.

ElemNew.Pre (NotifyElement):

The user is going to create a new element of type elementType (with its descent) as the child of the element element. The position field gives the position of the element which will be created in the list of the children of element (0 before the first child or as the first child if the element has no child, 1 after the first child, 2 after the second one, etc.).
If the event is in the ELEMENTS section, it is raised only when the user wants to create an element of the corresponding type.
If the event is in the DEFAULT section, it is raised as soon as the user creates a new element, whatever its type.
In all cases, this event is only raised for the root of a subtree that will be created and not for each element of this subtree.

ElemNew.Post (NotifyElement):

The element element has just been created and placed into the abstract tree of its document. The position field has no meaning.
If the event is in the ELEMENTS section, it is only raised when the user has created an element of the corresponding type.
If the event is in the DEFAULT section, it is raised each time the user creates a new element, whatever its type.
When the event has created a subtree, this event can only be raised for the root of the subtree newly created or on the contrary to each element of this subtree, depending on the notification mode in which the document can be found (see the TtaSetNotificationMode of the API). However, even when the document is included in the full notification mode, the event is only raised for the elements which require it.

ElemPaste.Pre (NotifyOnValue):

The user is going to paste the element target as the descendant of the element element. The element target is not already pasted at the position required by the user. The value field gives the position of the element to be pasted in the list of the children of element (0 before the first child, 1 after the first child, 2 after the second child, etc.).
In all cases, this event is only raised for the root of a subtree which will be pasted and not to each element of the subtree.

ElemPaste.Post (NotifyElement):

The element element has just been pasted. It is placed into the abstract tree. The position field contains the document from which the element has been copied or cut.
When the event has pasted a subtree, this event can only be raised for the root of the pasted subtree or on the contrary to each element of the subtree, depending on the notification mode of the document (see the TtaSetNotificationMode function of the API). However, even when the document is in the full notification mode, the event is only raised for the elements which have required it.

ElemGraphModify.Pre (NotifyOnValue):

The user wants to replace by value the contents of the graphic or symbol leaf target which has an ascendant element. Element is the element of the type with which the event is associated. If the event is defined in the DEFAULT section then element is equal to target.

ElemGraphModify.Post (NotifyOnValue):

The user has just replaced the contents of the graphic or symbol leaf target which has an ascendant element.

ElemRead.Pre (NotifyElement):

This event occurs when a document file is read and even if this is required by the API (exception to the rule). The editor starts reading an element of type elementType which must be the last child of element. The position field has no meaning. If the action returns True, the element (and the whole subtree) is not included in the abstract tree.

ElemRead.Post (NotifyElement):

The editor has read the element element and the whole subtree and has inserted it into the abstract tree. The position field has no meaning.

ElemReturn.Pre (NotifyElement):

The user hits the key Enter (or Return) when the target element was selected. Element is the element of the type with which the event is associated.

ElemReturn.Post (NotifyElement):

The thotlib has finished to handle the key Enter (or Return) on the target element. Element is the element of the type with which the event is associated.

ElemSave.Pre (NotifyElement):

This event occurs when a document is saved to a file and even if the backup is required by the API (exception to the rule). The editor is going to write the element element. The position field has no meaning. If the action returns True, the subtree is not written in the file.

ElemSave.Post (NotifyElement):

The editor has written the element element. The position field has no meaning.

ElemSelect.Pre (NotifyElement):

The user wants to select the element element. The selection has not been already made. This event is also raised before a double-click and when the editor follows a hypertext link. The position field has no meaning.

ElemSelect.Post (NotifyElement):

The element element has just been selected by the user. The position field has no meaning.

ElemSetReference.Pre (NotifyOnTarget):

The user requires that the reference element element points to the element target belonging to the targetdocument document. The link is not already established and the reference element still points its old target (or nothing at all). In the ELEMENTS section, this event is only valid for the elements of type reference (this is checked by the compiler). If this event is included in the DEFAULT section, it will only apply to the reference elements. This event is not accepted in the ATTRIBUTES section even for reference attributes (see the AttrModify event).

ElemSetReference.Post (NotifyOnTarget):

The reference element element has just changed its target upon the user's request. It now points to the element target belonging to the targetdocument document.

ElemTab.Pre (NotifyElement):

The user hits the key Tab when the target element was selected. Element is the element of the type with which the event is associated.

ElemTab.Post (NotifyElement):

The thotlib has finished to handle the key Tab on the target element. Element is the element of the type with which the event is associated.

ElemTextModify.Pre (NotifyOnTarget):

The user starts modifying the contents of the text or image leaf (modification of the name of the image file) target in the element element. The element parameter is the element of the type which has requested the event and which is an ascendant of the target leaf. The text leaf still has its previous contents.
If this event is in the ELEMENTS section, it is only raised if one of the ascendants (at any level) of the text leaf in question has the type with which the event is associated. If several ascendants require the event, it is raised for each one and first to the ones at the lowest level.
If this event is in the DEFAULT section, it is raised as soon as any text leaf is affected. In this case, both parameters element and target have the same value: the affected text leaf.
The return of the function called in the application is indifferent: whether it returns True or False, the behaviour of the editor is not modified.

ElemTextModify.Post (NotifyOnTarget):

The user has finished modifying the contents of the text or image leaf (modification of the name of the image file) target within element element. Several changes can have been made since the corresponding ElemTextModify.Pre event has been raised: inserted, pasted, deleted characters, etc. When the event is raised, the text leaf has its new contents. This event is raised in the same way as the ElemTextModify.Pre event.

ElemTransform.Pre (NotifyOnElementType):

The editor is changing the type of selected elements. The event is raised if the editor could not transform the whole selection into targetElementType, and before it tries to change individually each selected element.

If the event is in the ELEMENTS section, it is raised only if all the selected elements belong to the corresponding type.

If the event is in the section DEFAULT, it is sent whatever the type of selected elements is.

If the action called by the event returns True, the editor will not try to change individually the type of selected elements, if it returns False, the editor will try.

There is no ElemTransorm.Post event.

5.3 Events for the specific presentation

The following events can only appear in the DEFAULT or ELEMENTS section of an application schema.

In the DEFAULT section, they are raised each time a specific presentation rule is created, modified or deleted (depending on the event), whatever the element in question.

In the ELEMENTS section, they are associated with an element type and raised by the editor when the specific rule concerns an element of the type in question.

A single type of context is associated with the events for the specific presentation (this structure is defined in the appaction.h file):

typedef struct {
  TTEevent event;
  Document document;
  Element element;
  PRule pRule;
  int pRuleType;
} NotifyPresentation;
 

PRuleCreate.Pre (NotifyPresentation):

The user requires a specific presentation rule of type typePRule to be added for the element element. The rule is not already added. The pRule field has no significant value.

PRuleCreate.Post (NotifyPresentation):

The pRule rule has just been added to the element element.

PRuleModify.Pre (NotifyPresentation):

The user wants to change the value of the pRule specific presentation rule associated with the element element.

PRuleModify.Post (NotifyPresentation):

The user has just changed the value of the pRule specific presentation rule associated with the element element.

PRuleDelete.Pre (NotifyPresentation):

The user wants to remove a pRule specific presentation rule associated with the element element.

PRuleDelete.Post (NotifyPresentation):

The user has removed a specific presentation rule of type pRuleType associated with the element element. The pRule field has no significant value.

5.4 Events for documents

The following events are intended for documents. They can only appear in the DEFAULT section of an application schema. If it is an application schema associated with a type of document, they are raised each time a document of this type is (respectively) opened, created, closed or saved. If they are included in the DEFAULT section of the EDITOR.A schema, these events are raised whatever the type of document.

Only one type of context accompanies the events for documents. The view field is not significant for any event on documents (this structure is defined in the appaction.h file):

typedef struct {
  TTEevent event;
  Document document;
  View view;
} NotifyDialog;

DocOpen.Pre (NotifyDialog):

The user requires a document to be opened. The document is not already opened but the document field already contains the identifier to be associated with the document if the application accepts to open it.

DocOpen.Post (NotifyDialog):

The user has opened the document designated by the document field.

DocCreate.Pre (NotifyDialog):

The user requires a new document to be created. The document is not already created but the document field already contains the identifier to be associated with the document if the application accepts its creation.

DocCreate.Post (NotifyDialog):

The user has created the document designated by the document field.

DocClose.Pre (NotifyDialog):

The user requires the document designated by the document field to be closed. The document is still open.

DocClose.Post (NotifyDialog):

The user has closed the document designated by the document field. This document identifier is no longer used.

DocSave.Pre (NotifyDialog):

The user requires the document designated by the document field to be saved. The document is not saved yet.

DocSave.Post (NotifyDialog):

The user has saved the document designated by the document field.

DocExport.Pre (NotifyDialog):

The user requires the document designated by the document field to be exported. The document is not exported yet.

DocExport.Post (NotifyDialog):

The user has exported the document designated by the document field.

5.5 Events for views

The following events are intended for views. They can only appear in the DEFAULT section of an application schema and concern all views of a given document (if they are in an application schema associated with this type of document) or all views of all types of documents (if they are in the EDITOR.A schema).

Two types of context can accompany the events for views (these structures are defined in the appaction.h file):

typedef struct {
  TTEevent event;
  Document document;
  View view;
} NotifyDialog;
 
typedef struct {
  TTEevent event;
  Document document;
  int verticalValue;
  int horizontalValue;
} NotifyWindow;

ViewOpen.Pre (NotifyDialog):

The editor is going to open a view for the document designated by the document field. The view field is the view which will open.

ViewOpen.Post (NotifyDialog):

The editor has just opened the view for the document document. The view field is the view which is opened.

ViewClose.Pre (NotifyDialog):

The editor is going to close the view view for the document document.

ViewClose.Post (NotifyDialog):

The editor has just closed the view view for the document document.

ViewResize.Pre (NotifyWindow):

The editor is going to resize the view view for the document document. The parameters verticalValue and horizontalValue give the vertical and horizontal variations of the window. These values are expressed in pixels and can be positive or negative numbers. A negative value expresses a shrinking of the window.

ViewResize.Post (NotifyWindow):

The editor has just resized the view view for the document document.. The parameters verticalValue and horizontalValue give the vertical and horizontal variations of the window. These values are expressed in pixels and can be positive or negative numbers. A negative value expresses a shrinking of the window.

ViewScroll.Pre (NotifyWindow):

The editor is going to scroll the view view for the document document. The parameters verticalValue and horizontalValue give the vertical or horizontal scrolling value (one of them is nul). The scrolling value is expressed in pixels and can be a positive or negative number. When the scroll is done by a jump to a specific point within the document, the editor cannot compute the scrolling value; the value 65535 is returned in that case.

ViewScroll.Post (NotifyWindow):

The editor has just scrolled the view view for the document document. The parameters verticalValue and horizontalValue give the vertical or horizontal scrolling value (one of them is nul). The scrolling value is expressed in pixels and can be a positive or negative number. When the scroll is done by a jump to a specific point within the document, the editor cannot compute the scrolling value; the value 65535 is returned in that case.

5.6 Events for the application

The events described in this section do not concern a particular object but the whole application. They appear when the editor is launched and closed.

As they are not intended for a particular type of document, these events can only appear in the EDITOR.A schema. They are independent of any element or attribute. As a result, they can only appear in the DEFAULT section of this schema.

Each event for the application is accompanied with a pointer to the subsequent structure (this structure is defined in the appaction.h file):

typedef struct {
  TTEevent event;
} NotifyEvent;

Init.Pre (NotifyEvent):

The editor is going to start. This event (and the next one) allows the application to carry out initializations. If the action triggered off by the event returns True, the editor does not start and the application immediately ends.

Init.Post (NotifyEvent):

The editor has just started. It can now receive the events issued by the user and the calls made by the application through the API.

Exit.Pre (NotifyEvent):

The editor is going to stop once the ``Quit'' command has been issued by the user. No operation has been already performed. In particular, all opened documents and views are still opened. If the action triggered off by this event returns True, the editor does not do anything and the editing session carries on.

Exit.Post (NotifyEvent):

The editor stops. The application can still use the API but all the documents which were opened at the end of the session are already closed.