APIman-E

The Thot tool kit is a comprehensive set of editing functions that can be used for building applications that handle structured documents in the Unix / X Window environment. It is constituted by a set of C libraries that can be linked to any program. It allows application programs to perform the same kind of operations as a user working with a structured document editor. Typically, an application can use the tool kit for creating new documents, for modifying existing documents, for extracting information from documents, for displaying (parts of) documents, etc. The tool kit can be used either for automatic manipulations performed solely by a program or for allowing a human user to cooperate with a program that processes documents. In this latter case, it uses OSF/Motif for implementing the user interface.

The functions provided by the tool are based on the Thot document model. Documents produced with the tool kit can be stored as Unix files in the same standard format as documents produced by the Thot editor (pivot format indicated by the .PIV suffix). Thot editor is also able to save documents in other formats and obviously this capability is provided by the tool kit. Thot documents can be processed by all tools available in the Thot environment and by all applications developed with the tool kit. The Thot environment includes in particular flexible tools for editing, printing and translating documents.

1 Introduction to the document model

1.1 Logical structure

In the editing tool kit, a document is primarily considered as an abstract structure that assembles typed elements. Examples of elements types are titles, chapters, sections, paragraphs, lists, notes, etc. The structure itself is basically a hierarchy of such elements; it is called an abstract tree. The lowest level elements (also called basic elements) represent the actual contents of the document: character stings, mathematical symbols, pictures, and graphical elements. In addition to this tree structure, non-hierarchical links (also called references) relate elements independently of the tree structure, thus representing cross- references and other types of hypertext links.

As the type of an element is not always sufficient for completely representing the role of that element in the document logical structure, the notion of logical attribute has been introduced. A logical attribute is information associated with an element that adds semantics to that element.

The logical structure of a document is constrained by a model, called a structure schema. Several structure schemas can be used, one for each type of document. A structure schema defines a document type, by specifying all types of elements that can be used in the logical structure of a document of that type. It also specifies the attributes that can be associated with each type of element and all structural relationships that can be set between elements. Structure schemas are written in a specific declarative language, called S. A compiler for the S language is available, so that new document types can be defined, according to the requirements of applications.

1.2 Presentation

The graphical appearance of a document (also called presentation) is derived from its logical structure and is generically specified by a presentation schema. A presentation schema is associated with a structure schema and specifies the appearance of documents of the type defined by the structure schema. For each type of element defined in the structure schema, the presentation schema contains a set of presentation rules that define the style and the format of the logical elements. Using these rules, the system can then produce the graphical representation of a document, on the basis of its logical structure.

Presentation schemas are written in the language P and a compiler for that language is available. New presentation schemas can then be developed. Notice that several presentation schemas can be associated with the same structure schema, thus defining alternative presentations for the same type of document.

In addition, each presentation schema may define different views. A view is a subset of the document that can be formatted in a different way and displayed separately: each view is presented in a different window on the screen.

For balancing this rigid principle of presentation with a certain degree of flexibility, it is possible to associate with some element instances a special type of attribute, called specific presentation rule. A specific presentation rule is a presentation rule of the same kind as those of the presentation schema, but it applies only to the element instance with which it is associated, not to all elements of that type.

With that approach to document representation, documents are first specified generically, by writing structure schemas and presentation schemas. Then end-users and application programs can manipulate document instances very simply, by referring to the schemas. Most of the work consists in handling a logical structure consistent with the chosen structure schema and in handling the contents (the basic elements) of that structure. All the rest, especially formatting and displaying, is done by the tool kit. In addition, the logical structure is a very efficient help for moving across the document and for locating the parts to be modified.

2 Tool kit structure

2.1 Structure of this manual

The tool kit contains about 200 functions. For the sake of clarity, they are presented by groups, each group focusing on a different aspect of documents.

Group application (section 6) concerns the administration of the tool kit by the application.
Group interface (section 7) allows the application program to modify and extend the Thot editor.
Group document (section 10) allows the application to manage schemas and whole documents.
Group tree (section 11) handles the hierarchical logical structure of documents.
Group contents (section 12) allows the application to manipulate the contents of the leaves of the structure.
Group attribute (section 13) concerns logical attributes.
Group reference (section 14) contains functions for manipulating non hierarchical relationships (hypertext links).
Group language (section 15) concerns natural languages used in text contents.
Group presentation (section 16) handles specific presentation.
Group view (section 18) handles views.
Group selection (section 19) contains the functions that handle the selection.
Group message (section 8) allows the application program to display messages intended to the user.
Group dialogue (section 9) allows the application program to manage menus and forms intended to the user.

Each section presenting a group of functions is divided into subsections which correspond to the following four broad categories:

constructors are functions that create or generate new things. By extension, they also include reverse functions, which delete or destroy the same things.
modificators are functions that modify existing things in different ways.
accessors are the functions that allow the application program to access things.
locators are the functions that search various kind of things in document, according to different criteria.

2.2 Libraries

The Thot editing tool kit is accessed through an API that is defined in sections 6 to 9. The tool kit takes the form of two libraries for editing documents. Each library is suited to a different type of application and an application uses only one of the two editing libraries: the second library includes the first one.

2.2.1 Thot Kernel library

The first library allows an application to handle the logical structure and the contents of Thot documents in automatic mode. This subset of the tool kit, called Thot Kernel, does not produce the graphical aspect of documents. It does not provide either any service for the user interface. It is typically designed for applications performing automatic operations on the logical structure and contents of documents without direct manipulation by a user.

The last five groups of functions (those handling views, selections, and user interface to the editor) are not part of that library. Sections 18 to 9 of that document do not concern that library.

2.2.2 Thot Editor library

The second library, called Thot Editor, includes all facilities provided by the Kernel, with the same interface, and provides additional services for displaying the graphical aspect of documents. It also contains the whole Thot editor with its user interface. All editing functions of Thot can be accessed by the user and by application programs. The Thot Editor tool kit is typically intended to interactive applications that handle documents under the control of a user and that add new functions to the editor.

All groups of functions presented in this document are part of that library. Functions that are also part of the Thot Kernel have exactly the same interface when used in the context of Thot Editor. The only difference is that, in the case of Thot Kernel, they do not display anything, and that, in the case of Thot Editor, some of them (namely constructors and modificators) modify the picture displayed on the screen. As a consequence, application programs that have been developed for automatic processing can be reused in the context of an interactive application without any change: the Thot Editor automatically takes in charge all displaying problems that are not handled by the Thot Kernel.

3 Using the Thot tool kit

3.1 Errors

Almost all functions of the tool kit can detect errors. In that case the function is not performed and an error code is set. The tool kit provides the application program with the function TtaGetErrorCode for accessing the error code. That function returns the completion code of the last tool kit function called by the application. Only the completion code of the most recently called function is available. A 0 completion code means a successful operation; other values are defined in files application.h.

In addition to the error code returned to the application program by the function TtaGetErrorCode, the tool kit prints an error message on the standard error file stderr whenever an error is raised. Error messages are printed by default, but the application program can ask the tool kit to stop printing these messages, by calling the function TtaSetErrorMessages.

3.2 Include files

Each group of functions has an associated include file. Available include files are: application.h, document.h, tree.h, content.h, attribute.h, reference.h, language.h, presentation.h, view.h, selection.h, interface.h. These files must be included in each module of the application program that calls at least one function of the corresponding group. They contain the interface definition of the functions and the types and constants (#define) used by these functions.

3.3 Buffers

Whenever a function may return a long character string (20 characters or more), the buffer must be provided by the application when calling the function. If the buffer is too small, the tool kit raises an error. But the size of the character string can generally be asked before calling such functions, by using another function.

3.4 Naming conventions

Functions in the Thot API belong to different categories regarding their arguments and return value. The naming scheme follows these categories:

TtaGet* are functions that return a single value as the value of the function itself. Their arguments do not return any value.
TtaNext* or TtaPrevious* are void functions that return a single value through an argument. You set that argument with an object before calling the function and, when returning, this argument has a new value, which is the next or previous object. These functions are mainly used in loops to access objects sequentially.
TtaGive* are void functions that return at least two values through their arguments.
Functions that do not return any value just start with Tta.

4 Types used by the Thot editing tool kit

The tool kit performs operations on various entities, such as schemas, documents, elements, attributes, views, etc. Each entity is identified by a unique identifier which is assigned by Thot. Therefore, an application program must get that identifier before manipulating any entity. An identifier can be obtained by constructors, accessors and locators.

The following types are used by the editing tool kit:

SSchema: a structure schema loaded by the tool kit.
Document: a document loaded or created by the tool kit.
Element: an element in the logical structure of a document.
Attribute: a logical attribute.
PRule: a specific presentation rule.
TypeUnit: UnRelative, UnXHeight, UnPoint, UnPixel, UnPercent
View: a view created by the editor (Thot Editor only).
ElementType: the type of an element.
AttributeType: the type of an attribute.
Language: the identifier of a natural language.

SSchemas, Elements, Attributes, and PRules are pointers (addresses), whereas Documents and Views are integers. Language is an unsigned character. Both ElementType and AttributeType are structures containing a SSchema (the schema that defines the corresponding element type or attribute type) and an integer which is the number of the element type or attribute type in that structure schema. Structure ElementType is defined in file tree.h:

typedef struct _ElementType
    {
    SSchema ElSSchema;
    int ElTypeNum;
    } ElementType;

Structure AttributeType is defined in file attribute.h:

typedef struct _AttributeType
    {
    SSchema AttrSSchema;
    int AttrTypeNum;
    } AttributeType;

In addition some integers are used for exchanging parameters between the application program and the tool kit. Available parameters with their possible values are:

Search domain: SearchForward, SearchBackward, SearchInTree.
Access rights: ReadWrite, ReadOnly, Hidden, Inherited.
Construct: ConstructIdentity, ConstructList, ConstructChoice, ConstructOrderedAggregate, ConstructUnorderedAggregate, ConstructConstant, ConstructReference, ConstructBasicType, ConstructNature, ConstructPair.
Presentation rules: PRSize, PRStyle, PRFont, PRUnderline, PRThickness, PRIndent, PRLineSpacing, PRDepth, PRAdjust, PRJustify, PRLineStyle, PRLineWeight, PRFillPattern, PRBackground, PRForeground, PRHyphenate.
Display modes: DisplayImmediately, DeferredDisplay, NoComputedDisplay.

5 Initialization

Group application contains the functions for managing the tool kit API. These functions require that file application.h be included in the module that calls them.

Applications generated by an interface schema EDITOR.A don't have to call these functions.

5.1 Constructors

5.1.1 TtaInitialize

Initializes the Thot editing tool kit for an application. This function must be called before any other function of the tool kit.

void TtaInitialize(char *applicationName)

Parameter:: applicationName: name of the application that requires services from the tool kit. This name is used for accessing the ressources defined in the Registry.

5.1.2 TtaQuit

Quits the Thot tool kit. No other function of the tool kit can then be called by the application.

void TtaQuit()

5.1.3 TtaInitializeAppRegistry

Initialize the Thot Registry. This is done by default by TtaInitialize. On Unix platforms the Registry is physically stored in the Thot.ini file, on Windows platforms the native Registry is used.

void TtaInitializeAppRegistry(char *applicationName)

Parameter:: applicationName: name of the application.

5.1.4 TtaSaveAppRegistry

Commit the changes made to the Thot Registry. This is done by default by TtaQuit.

void TtaSaveAppRegistry()

5.2 Modificators

5.2.1 TtaSetApplicationQuit

void TtaSetApplicationQuit (Proc procedure)

Parameter:: procedure: the procedure that must be called just before the application

6 Application

Group application contains the functions for managing the tool kit API. These functions require that file application.h be included in the module that calls them.

6.1 Constructors

6.1.1 TtaGetMemory

Allocates dynamically a buffer of a specific size.

char *TtaGetMemory(int size)

Parameter:: size: size in bytes (like using malloc) of the desired allocated buffer.

Return value:: the address of the allocated buffer.

See also:: TtaFreeMemory.

6.1.2 TtaFreeMemory

Frees the memory allocated to a buffer by TtaGetMemory.

void TtaFreeMemory(char *buffer)

Parameter:: buffer: the address of the buffer.

See also:: TtaGetMemory.

6.1.3 TtaGetEnvString

Reads an entry from the Thot Registry. It returns a non-modifiable string associated to the name given as parameter. Thot first looks for a specific value associated to the current application, and if not found try to find one in the "thot" section. Hence settings saved in the "thot" section are shared by all applications based on the Thot library, but can be refined to fit each application specific needs. If no value is found for the requested entry, the function returns NULL.

char *TtaGetEnvString(const char *name)

Parameters:: name: name of the entry.

6.1.4 TtaGetDefEnvString

Reads an entry from the Thot Registry. It returns a non-modifiabledefault string associated to the name given as parameter. Thot first looks for a specific value associated to the current application, and if not found try to find one in the "thot" section. Hence settings saved in the "thot" section are shared by all applications based on the Thot library, but can be refined to fit each application specific needs. If no value is found for the requested entry, the function returns NULL.

char *TtaGetDefEnvString(const char *name)

Parameters:: name: name of the entry.

6.1.5 TtaGetEnvInt

Reads an entry from the Thot Registry. It returns the integer value associated with the name given as a parameter. Thot first looks for a specific value associated to the current application, and if not found try to find one in the "thot" section. Hence settings saved in the "thot" section are shared by all applications based on the Thot library, but can be refined to fit each application specific needs. The function returns either TRUE or FALSE, depending on whether the the registry entry exists or not.

ThotBoolTtaGetEnvInt(const char *name, int *value)

Parameters:: name: name of the entry.
value: value of the entry.

6.1.6 TtaGetDefEnvInt

Reads an entry from the Thot Registry. It returns the default integer value associated with the name given as a parameter. Thot first looks for a specific value associated to the current application, and if not found try to find one in the "thot" section. Hence settings saved in the "thot" section are shared by all applications based on the Thot library, but can be refined to fit each application specific needs. The function returns either TRUE or FALSE, depending on whether the the registry entry exists or not.

ThotBoolTtaGetDefEnvInt(const char *name, int *value)

Parameters:: name: name of the entry.
value: value of the entry.

6.1.7 TtaGetEnvBoolean

Reads an entry from the Thot Registry. It returns the ThotBool value associated with the name given as a parameter. Thot first looks for a specific value associated to the current application, and if not found try to find one in the "thot" section. Hence settings saved in the "thot" section are shared by all applications based on the Thot library, but can be refined to fit each application specific needs. The function returns either TRUE or FALSE, depending on whether the the registry entry exists or not.

ThotBoolTtaGetEnvBoolean(const char *name, ThotBool *value)

Parameters:: name: name of the entry.
value: value of the entry.

6.1.8 TtaGetDefEnvBoolean

Reads an entry from the Thot Registry. It returns the default ThotBool value associated with the name given as a parameter. Thot first looks for a specific value associated to the current application, and if not found try to find one in the "thot" section. Hence settings saved in the "thot" section are shared by all applications based on the Thot library, but can be refined to fit each application specific needs. The function returns either TRUE or FALSE, depending on whether the the registry entry exists or not.

ThotBoolTtaGetDefEnvBoolean(const char *name, ThotBool *value)

Parameters:: name: name of the entry.
value: value of the entry.

6.1.9 TtaIsBlank

TtaSkipBlanks skips all spaces, tabs, linefeeds and newlines at the beginning of the string and returns the pointer to the new position.

ThotBool TtaIsBlank (char *ptr);

Parameters:: ptr: the source string.

6.1.10 TtaSkipBlanks

TtaSkipBlanks skips all spaces, tabs, linefeeds and newlines at the beginning of the string and returns the pointer to the new position.

char *TtaSkipBlanks (char *ptr)

Parameters:: ptr: the source string.

Return value:: the pointer to the new position in the source string.

6.2 Modificators

6.2.1 TtaSetErrorMessages

Indicates to the tool kit whether error messages must be printed or not.

void TtaSetErrorMessages(int on)

Parameters:: on: 1 if error messages must be printed, 0 if not.

6.2.2 TtaSetEnvString

Set an entry in the Thot Registry for the current application.

void TtaSetEnvString(const char *name, const char *value, int overwrite)

Parameters:

name: name of the entry.

value: value associated to the entry.

overwrite: should we overwrite an existing entry ?

6.2.3 TtaSetDefEnvString

Sets the default value of an entry in the Thot Registry for the current application.

void TtaSetDefEnvString(const char *name, const char *value, int overwrite)

Parameters:

name: name of the entry.

value: value associated to the entry.

overwrite: should we overwrite an existing entry ?

6.2.4 TtaSetEnvInt

Set an entry in the Thot Registry for the current application.

void TtaSetEnvInt(const char *name, const int value, int overwrite)

Parameters:

name: name of the entry.

value: value associated to the entry.

overwrite: should we overwrite an existing entry ?

6.2.5 TtaSetEnvBoolean

Set an entry in the Thot Registry for the current application.

void TtaSetEnvBoolean(const char *name, const ThotBool value, int overwrite)

Parameters:

name: name of the entry.

value: value associated to the entry.

overwrite: should we overwrite an existing entry ?

6.3 Accessors

6.3.1 TtaGetVersion

Returns the identifier of the current version of the Thot eRediting tool kit.

char *TtaGetVersion()

Return value:: identifier of the current version.

6.3.2 TtaGetErrorCode

Returns the error code set by the last call to the Thot editing tool kit. See file application.h for the possible values.

int TtaGetErrorCode()

Return value:: last error code, 0 if the last call was successful.

6.3.3 TtaGetStrError

Returns a pointer to the message text for a given error code.

char *TtaGetStrError(int errorCode)

Parameter:: errorCode: an error code.

Return value:: pointer to the message text of the error.

See also:: TtaGetErrorCode

7 Interface

The functions described in this section require that file interface.h be included in the module that calls them. They are available only in the Thot Editor library.

7.1 Constructors

7.1.1 TtaSetCallback

This function reserves a set of reference for creating dialogue elements (forms, menus, submenus, labels, etc.) and specifies the procedure that is called back when the user activates these dialogue elements.

Dialogue elements have to be created by the application using references between the "base" value returned by this function and the value "base+numberOfRef-1". So, this function must be called first.

It is possible to define different sets of dialogue elements by calling this function more than one time with different callbackProcedure procedure in the same application.

The callbackProcedure procedure declared is called for each event concerning these specific dialogue items. It receives three parameters: the dialogue item reference, the data type, and the data value:

void callbakProcedure(reference, datatype, data)
     int reference;
     int datatype;
     char *data;

int TtaSetCallback(void (*callbackProcedure) (), int numberOfRef)

Parameter:: callbakProcedure: the application callback procedure.
numberOfRef: the nmber of reference reserved.

Return value:: the "base" value for the numberOfRef specific dialogue elements to be created.

7.1.2 TtaHandlePendingEvents

This function manages all Thot and Motif pending events. The application have to call this function to allow user's interactions and display updates to be managed during long treatments.

void TtaHandlePendingEvents()

7.1.3 TtaHandleOneEvent

This function processes one event within Thot and Motif. The application which controls a local loop of events have to call this function to allow managment of specific Thot and Motif events.

void TtaHandlePendingEvents(XEvent *event)

Parameter:: event: the X event to be managed.

7.1.4 TtaAddButton

Adds a new button into the document view button bar. This function must specify a valid view of a valid document. The procedure parameter gives the call back procedure that will be run when user select the button. This procedure will receive two parametrers: the document and the view concerned.

An example of callback procedure is.

void callback_procedure (document, view)
Document document;
View view;
{
....
}

If the icon parameter in None, a space button is generated and the callback procedure is ignored. The parameters type and state are only used by on Windows platforms.

int TtaAddButton(Document document, View view, ThotIcon icon, STRING functionName, STRING info, void (*procedure) (), BYTE type, ThotBool state)

Parameters:

document: the concerned document.

view: the concerned view.

icon: the pixmap of the new button or None,.

functionName: the internal name of the function used to connect shortcuts,.

info the text displayed when the cursor stays on the button,.

procedure: procedure to be executed when the button is selected by the user or NULL.

type: it could be TBSTYLE_BUTTON or TBSTYLE_CHECK.

state: is TRUE if the button is in an active state,.

Return value:: The button index.

7.1.5 TtaAddTextZone

Adds a new text-zone into the document view commands. This function must specify a valid view of a valid document. The editable parameter indicates that user can edit this text-zone. The procedure parameter gives the call back procedure that will be run when user changes the text-zone: the user press the Return key. This procedure will receive two parametrers: the document and the view concerned.

An example of callback procedure is.

void callback_procedure (document, view)
Document document;
View view;
{
....
}

If the text-zone is not editable the procedure have to be NULL.

int TtaAddTextZone(Document document, View view, char *label, ThotBool editable, void (*procedure) ())

Parameters:

document: the concerned document.

view: the concerned view.

label: the label of the text-zone.

editable: True is user can edit the text-zone.

procedure: procedure to be executed when the text is modified by the user.

Return value:: The text-zone index.

7.2 Accessors

7.2.1 TtaGetCurrentDisplay

Returns the current display descriptor.

Display *TtaGetCurrentDisplay()

7.2.2 TtaGetScreenDepth

Returns the screen depth of the display.

int TtaGetScreenDepth()

7.2.3 TtaClickAnElement

Waits for a click from end-user and returns the element and document selected. If the user clicks out of any document view, the returned values are null.

void TtaClickAnElement(Document document, Element element)

Parameters: document: the document selected by the user or 0.
element: the element selected by the user or 0.

7.3 Modificators

7.3.1 TtaChangeButton

This function changes the button icon. This function must specify a valid view of a valid document and a valid button index.

void TtaChangeButton(Document document, View view, int buttonIndex, ThotIcon icon, ThotBool state)

Parameters:

document: the concerned document.

view: the concerned view.

buttonIndex: the button index, numbered from 1 to n.

icon: the pixmap of the new button or None.

state: TRUE if the button is an active button..

7.3.2 TtaSetTextZone

This function gets the text to be displayed in the text-zone. This function must specify a valid view of a valid document and a valid text-zone index.

void TtaSetTextZone(Document document, View view, int textIndex, char *text)

Parameters:

document: the concerned document.

view: the concerned view.

textIndex: the button index, numbered from 1 to n.

text: the text to be displayed into the text-zone.

7.3.3 TtaSetMenuOff

Sets inactive a menu in the menu bar of the view of the document. If the document and view parameters are null, the menu is a application window menu.

void TtaSetMenuOff(Document document, View view, int menuID)

Parameters:

document: the document concerned or 0.

view: the view concerned or 0.

menuID: the menu identification in the EDITOR.h file.

7.3.4 TtaSetMenuOn

Sets active a menu in the menu bar of the view of the document. If the document and view parameters are null, the menu is a application window menu.

void TtaSetMenuOn(Document document, View view, int menuID)

Parameters:

document: the document concerned or 0.

view: the view concerned or 0.

menuID: the menu identification in the EDITOR.h file.

7.3.5 TtaSetActionOff

Sets inactive a menu action in the menu bar of the view of the document. If the document and view parameters are null, the menu is a application window menu.

void TtaSetActionOff(Document document, View view, int menuID, int itemID)

Parameters:

document: the document concerned or 0.

view: the view concerned or 0.

menuID: the main menu (even if the item is located into a submenu) identification in the EDITOR.h file.

itemID: the item identification in the EDITOR.h file.

7.3.6 TtaSetActionOn

Sets active a menu action in the menu bar of the view of the document. If the document and view parameters are null, the menu is a application window menu.

void TtaSetActionOn(Document document, View view, int menuID, int itemID)

Parameters:

document: the document concerned or 0.

view: the view concerned or 0.

menuID: the main menu (even if the item is located into a submenu) identification in the EDITOR.h file.

itemID: the item identification in the EDITOR.h file.

7.3.7 TtaSetToggleItem

Sets on/off the toggle of an item in the menu bar of the view of the document. If the document and view parameters are null, the menu is a application window menu.

void TtaSetActionOn(Document document, View view, int menuID, int itemID, ThotBool on)

Parameters:

document: the document concerned or 0.

view: the view concerned or 0.

menuID: the main menu (even if the item is located into a submenu) identification in the EDITOR.h file.

itemID: the item identification in the EDITOR.h file.

on: the value True or False to be set.

7.3.8 TtaSetCursorWatch

Displays the cursor watch within the view of the document. If the document and view parameters are NULL, displays the cursor watch within all views of documents.

void TtaSetCursorWatch (Document document, View view)

Parameters:: document: the document concerned or 0.
view: the view concerned or 0.

7.3.9 TtaResetCursor

Resets the standard cursor within the view of the document. If the document and view parameters are NULL, resets the standard cursor within all views of documents.

void TtaResetCursor(Document document, View view)

Parameters:: dument: the documen or 0.
view: the view or 0.

8 Messages

The functions described in this section require that file message.h be included in the modules that call them.

The following functions are available in both the Thot Editor library and the ThotKernel library. They allow an application program to manage messages and dialogue text, as Thot tool kits do. Text of dialogue boxes and error messages is defined out of the application code and is dynamically loaded when the application is executed. This method allows application to adapt its interface to the current user (English text for English user, French text for French user, etc.). Each message is numbered, code referencing the message by its number and an external file associating this number with its corresponding text. An environment variable is used to reach the correct file that contains text of messages at the execution time. If this file is not reachable, a warning message is sent to the standard output, but the execution is not automatically stopped. Nevertheless, the Thot Editor library stops execution when its text file is not reachable because it cannot work without.

We give an example of an application that needs four messages. The applicationMSG.h file is used to address correct message in source code and the en-applicationTXT gives the English version of messages text:

#define APP_start 0

#define APP_abort 1

#define APP_no_file 2

#define APP_complete 3

#define APP_MSG_MAX 4

applicationMSG.h

0 Application

1 Application aborted

2 Unreachable file %s

3 End of application

en-applicationTXT

The application has to load the rigth message table:

errorTable = TtaGetMessageTable("applicationTXT", APP_MSG_MAX);

and displays the third error message using one of available display function (for example the TtaDisplayMessage function and TtaGetMessage):

TtaDisplayMessage(FATAL, TtaGetMessage(errorTable, APP_no_file), filename);

8.1 Constructors

8.1.1 TtaGetMessageTable

Loads text of application messages in a dynamically allocated table and returns the identifcation of this messages table. The msgFile is the generic name of the message file to be loaded. The msgNumber parameter denotes the number of messages to be read in the file.The full name of the loaded file is $THOTDIR/config/$LANG-msgFile, where $THOTDIR represents the root path of Thot hierarchy and $LANG represents the current language (for example en). $THOTDIR is computed by the Thot toolkit and $LANG can be set in the user registry thot.ini.

int TtaGetMessageTable(char *msgFile, int msgNumber)

Parameters:: msgFile: the generic name of the message file.
msgNumber: the number of messages.

Return value:: The messages table identifier or -1 if the table is not allocated and loaded.

8.2 Accessors

8.2.1 TtaGetMessage

Returns the text of the corresponding message.

char *TtaGetMessage(int msgTableID, int msgIndex)

Parameters:: msgTableID: identifier of the messages table.
msgIndex: index of the message.

Return value:: Text of the message (an empty text if the table or the message is not found).

8.2.2 TtaDisplaySimpleMessage

Displays the text of a simple message. This message is often displayed in the message area of the main application window ľ if it exists ľ or directed to the standard output for batch applications.

The msgType parameter defines the importance of the message:

INFO: the message is displayed in the message area of the main application window just as an information.
OVERHEAD: the message replaces the previous message in the message area of the main application window.
FATAL: the message stops the application with an error code.
CONFIRM: the message pops a message box to display the message within and waits for until the end user confirms the message has been read.

void TtaDisplaySimpleMessage(int msgType, int msgTableID, int msgIndex)

Parameters:

msgType: the message type (INFO, OVERHEAD, FATAL, CONFIRM).

msgTableID: identifier of the messages table (LIB for the standard Thot messages).

msgIndex: index of the message.

8.2.3 TtaDisplayMessage

Displays a message mixing static text (the text of the message) with a variable number of parameters. The static text plays the role of a format (like the prinf format) and may include necessary format commandes for each parameter: a %s for a string, a %d for an integer. Number and type of variable parameters depend on format commands included in the message text.

void TtaDisplayMessage(int msgType, msgTableID, int msgIndex, ...)

Parameters:

msgType: the message type (INFO, OVERHEAD, FATAL, CONFIRM).

msgTableID: identifier of the messages table (LIB for the standard Thot messages).

msgIndex: index of the message.

...: variable parameters.

9 Dialogue

The Thot editing tool kit provides dialogue functions. There are high level functions that hide most of the complex aspects of OSF/Motif and thus allows an application to use OSF/Motif very easily and dynamically (all dialogue entities such as menus, buttons, forms, etc. can be created and modified at any time). As these dialogue functions are already used internally by the editing tool kit, another reason for an application to use it, is to present the user with a homogeneous and consistent look and feel for the whole application.

The functions described in this section require that file dialogue.h be included in the module that calls them. They are available only in the Thot Editor library.

Each dialogue element is identified by a unique reference. This reference is associated to the dialogue element at the creation time and will be used all along the time it exists to perform any action on it (intialization, display, undisplay and destruction).

The application receives dialogue callbacks from created and displayed dialogue elements through predefined specific callback procedures. The application can define several callback procedures (at least one) and each callback procedure can manage callbacks from several dialogue elements. Each callback identifies the concerned element dialogue and allows the procedure to switch on the correct management.

9.1 Constructors

9.1.1 TtaSetCallback

This function defines a callback procedure for a set of dialogue elements (menus. forms, etc.). The function returns the current base value of concerned dialogue elements and reserves the set of references contained between "base" and "base+set-1". After that declaration dialogue elements can be created.

When the user acts on these dialogue elements, the callback procedure is called with three parameters:

the reference of the concerned dialogue element,
the type of the returned value (INTEGER_DATA or STRING_DATA) depending of the dialogue element type (menu, form, text-form, etc.),
the returned data.

int TtaSetCallback (Proc callbakProcedure, int set)

Parameters:: callbakProcedure: the callback procedure to be called . That procedure has to be previously declared like that:
void Proc (int reference, int typeData, char *data)
set: the number of concerned dialogue elements.

Return value:: the base of dialogue element references.

9.1.2 TtaSetBackup

This function defines a backup procedure . If the application crashes for any reason and almost one document is modified that procedure Backup is called. That procedure has no parameter.

void TtaSetBackup (Proc Backup)

Parameters:: Backup: the procedure to be called. That procedure has to be previously declared like that:
void Proc ()

9.1.3 TtaSetDocStatusUpdate

This function defines a procedure which updates the application context each time the document of a document changes.

When the status of a document changes (it becomes modified or unmodified) the procedure DocStatusUpdate is called with two parameters:

the document identifier,
the new status status: TRUE if it's now modified, otherwise FALSE.

void TtaSetDocStatusUpdate (Proc DocStatusUpdate)

Parameters:: DocStatusUpdate: the procedure to be called That procedure has to be previously declared like that:
void Proc (Document doc, ThotBool modifed)

9.1.4 TtaNewForm

This function creates a form element attached to the ThotWidget parent. When the parent ThotWidget is distroyed, the ThotWidget that realizes this form is automatically destroyed. Usually the parent is the document view frame returned by the API function TtaGetViewFrame (document, view)and the form has to be destroyed before closing the document view.

As seen in the example below, the fonction automatically generates two buttons on the bottom of the form:

a "confirm" button
and a "cancel/done" button.

The parameter dbutton controls the choice of the "cancel/done" button. Two values are available: D_CANCEL or D_DONE.

void TtaNewForm (int ref, ThotWidget parent, char *title, ThotBool horizontal, int packet, char button, int dbutton)

Parameters:

ref: the unique reference attached to the dialogue element.

parent: the ThotWidget parent (usually TtaGetViewFrame (document, view)).

title the title or NULL.

horizontal is TRUE if dialogue elements included into the form are arranged horizontally.

packet number of dialogue elements in the same line if arranged horizontally or in the same column is arranged vertically.

button the mouse button used to select the element dialogue:

'L' for left button,
'M' for middle button,
'R' for right button.

dbutton the type of "cancel/done" button: D_CANCEL or D_DONE.

9.1.5 TtaNewSheet

This function creates a sheet element attached to the ThotWidget parent. When the parent ThotWidget is destroyed, the ThotWidget that realizes this sheet is automatically destroyed. Usually the parent is the document view frame returned by the API function TtaGetViewFrame (document, view) and the sheet has to be destroyed before closing the document view.

A sheet is similar to a form element, but only the "cancel/done" button is automatically generated and other extra buttons are explicitly declared. The parameter dbutton controls the choice of the "cancel/done" button. Two values are available: D_CANCEL or D_DONE. In the example below, four extra buttons had been declared: "Skip and next", "Skip (+dic)", "Replace and next" and "Replace (+dic)".

void TtaNewSheet (int ref, ThotWidget parent, char *title, int number, char *text, ThotBool horizontal, int packet, char button, int dbutton)

Parameters:

ref: the unique reference attached to the dialogue element.

parent: the ThotWidget parent (usually TtaGetViewFrame (document, view)).

title the title or NULL.

number: number of extra buttons declared in the sheet.

text: the list of strings declaring extra buttons ("A\0B\0" for two extra buttons A and B).

horizontal is TRUE if dialogue elements included into the form are arranged horizontally.

packet number of dialogue elements in the same line if arranged horizontally or in the same column is arranged vertically.

button the mouse button used to select the element dialogue:

'L' for left button,
'M' for middle button,
'R' for right button.

dbutton the type of "cancel/done" button: D_CANCEL or D_DONE.

9.1.6 TtaNewDialogSheet

This function creates a dialog sheet element attached to the ThotWidget parent. When the parent ThotWidget is distroyed, the ThotWidget that realizes this sheet is automatically destroyed. Usually the parent is the document view frame returned by the API function TtaGetViewFrame (document, view) and the sheet has to be destroyed before closing the document view.

A dialog sheet is similar to a sheet element, but no "cancel/done" button is automatically generated.

void TtaNewDialogSheet (int ref, ThotWidget parent, char *title, int number, char *text, ThotBool horizontal, int packet, char button)

Parameters:

ref: the unique reference attached to the dialogue element.

parent: the ThotWidget parent (usually TtaGetViewFrame (document, view)).

title the title or NULL.

number: number of extra buttons declared in the sheet.

text: the list of strings declaring extra buttons ("A\0B\0" for two extra buttons "A" and "B").

horizontal is TRUE if dialogue elements included into the form are arranged horizontally.

packet number of dialogue elements in the same line if arranged horizontally or in the same column is arranged vertically.

button the mouse button used to select the element dialogue:

'L' for left button,
'M' for middle button,
'R' for right button.

9.1.7 TtaNewSubmenu

This function creates a submenu element attached to a menu entry or a form (form, sheet or dialog sheet). In a form, a submenu is displayed as a radio menu (see the menu "Paper Format" in the example presented in 9.1.5). Only one entry of this menu can be selected at the same time.

Each entry is typed:

a simple button,
a link towards a form,
a link towards a submenu,
toggle button,
a separator.

void TtaNewSubmenu (int ref, int ref_parent, int entry, char *title, int number, char *text, char *equiv, ThotBool react)

Parameters:

ref: the unique reference attached to the dialogue element.

ref_parent: the reference of parent element (a menu or a form).

entry: the entry index (0 to n) in the parent menu which the submenu is attached to. For a submenu attached to a form this paramameter is not treated.

title the title or NULL.

number: number of entries declared in the submenu.

text: the list of strings declaring entries. Each entry starts with a special character that fixes the entry function:

'B' the entry is a simple button,
'F' the entry calls a form,
'M' the entry calls a submenu,
'T' the entry is a toggle.
'S" the entry is a separator (the entry string is limited to this character).

For example the text value "TA\0B" declares a toggle entry "A" and a button entry "B".

equiv: the list of strings declaring shortcuts attached to each entry. This parameter can be NULL if no shortcut is declared.

react: TRUE if the application wants to be informed as soon as the user selects in this submenu in a form. FALSE if the application prefers to wait for the confirmation of the form to receive the selected value.

9.1.8 TtaNewIconMenu

This function creates a submenu element attached to a menu entry or a form (form, sheet or dialog sheet). This submenu is composed of icons. Only one entry of this menu can be selected at the same time. This menu is always reactive.

void TtaNewIconMenu (int ref, int ref_parent, int entry, char *title, int number, Pixmap * icons, ThotBool horizontal)

Parameters:

ref: the unique reference attached to the dialogue element.

ref_parent: the reference of parent element (a menu or a form).

entry: the entry index (0 to n) in the parent menu which the submenu is attached to. For a submenu attached to a form this paramameter is not treated.

title the title or NULL.

number: number of entries declared in the menu.

icons: the list of pixmaps.

horizontal is TRUE if entries are arranged horizontally.

9.1.9 TtaNewToggleMenu

This function creates a toggle menu element attached to a form (form, sheet or dialog sheet). This menu is displayed as a toggle menu (see the menu "Options" in the example presented in 9.1.5). Only or more entries of this menu can be selected at the same time.

Each entry is typed:

a toggle,
a separator.

void TtaNewToggleMenu (int ref, int ref_parent, char *title, int number, char *text, char *equiv, ThotBool react)

Parameters:

ref: the unique reference attached to the dialogue element.

ref_parent: the reference of parent element (a form).

title the title or NULL.

number: number of entries declared in the menu.

text: the list of strings declaring entries. Each entry starts with a special character that fixes the entry function:

'B' or 'T' the entry is a simple button,
'S" the entry is a separator (the entry string is limited to this character).

For example the text value "TA\0S\0BC" declares an entry "A", a separator and an entry "C".

equiv: the list of strings declaring shortcuts attached to each entry. This parameter can be NULL if no shortcut is declared.

9.1.10 TtaNewSelector

This function creates a selector element attached to a form (form, sheet or dialog sheet).

The selector can be displayed with or without a text input zone (controled by the parameter withText) that allows user to choose a predefined string into the selector or to insert directly a free text. The selector can be displayed with or without a label (controled by the parameter label) that allow user to select this fixed.

In the previous example presented in 9.1.5, a selector is displayed with the title "Spell checking ...", a text zone and the label "W3C".

void TtaNewSelector (int ref, int ref_parent, char *title, int number, char *text, int height, char *label, ThotBool withText, ThotBool react)

Parameters:

ref: the unique reference attached to the dialogue element.

ref_parent: the reference of parent element (a form).

title the title or NULL.

number: number of entries declared in the submenu.

text: the list of strings declaring entries. For example the text value "A\0B\0C" declares an entrries "A", "B" and "C".

height: the height of the selector (number of entries displayed).

label: the label string of the extra entry or NULL.

withText: TRUE if the application wants to display a text zone at the selector bottom.

react: TRUE if the application wants to be informed as soon as the user selects in this selector. FALSE if the application prefers to wait for the confirmation of the form to receive the selected value.

9.1.11 TtaNewLabel

This function creates a label element attached to a form (form, sheet or dialog sheet). In the previous example presented in 9.1.5, there is a label element "Language: English".

void TtaNewLabel (int ref, int ref_parent, char *text)

Parameters:

ref: the unique reference attached to the dialogue element.

ref_parent: the reference of parent element (a form).

text: the text of the label.

9.1.12 TtaNewTextForm

This function creates a text input zone attached to a form (form, sheet or dialog sheet). In the previous example presented in 9.1.5, there is a text input zone without title.

TtaNewTextForm (int ref, int ref_parent, char *title, int width, int height, ThotBool react)

Parameters:

ref: the unique reference attached to the dialogue element.

ref_parent: the reference of parent element (a form).

title the title or NULL.

width: number of charaters displayed.

height: tnumber of lines displayed.

react: TRUE if the application wants to be informed as soon as the user inserts characters. FALSE if the application prefers to wait for the confirmation of the form to receive the final string.

9.1.13 TtaNewNumberForm

This function creates an input zone for integer values attached to a form (form, sheet or dialog sheet). In the previous example presented in 9.1.5, there is an input zone for integer values (from 1 to 10) displayed with the title "Number of proposals".

void TtaNewNumberForm (int ref, int ref_parent, char *title, int min, int max, ThotBool react)

Parameters:

ref: the unique reference attached to the dialogue element.

ref_parent: the reference of parent element (a form).

title the title or NULL.

min: the minimum integer value.

max: the maximum integer value.

react: TRUE if the application wants to be informed as soon as the user inserts characters. FALSE if the application prefers to wait for the confirmation of the form to receive the final string.

9.1.14 TtaDestroyDialogue

This function destroys an existing dialogue element.

void TtaDestroyDialogue (int ref)

Parameters:: ref: the unique reference attached to the dialogue element.

9.1.15 TtaListDirectory

Creates one or two selectors that allow end-user to select a directory and/or a file included within the current specified directory. This function supposes that the application had first created a form where selectors have to be inserted. The application is able to create either only the directory selector or only the file selector. A suffix can be specified if the application wants to filter a specific class of files. It is the responsibility of the application to receive and handle the selectors callback.

void TtaListDirectory(char *aDirectory, int formRef, char *dirTitle, int dirRef, char *suffix, char *fileTitle, int fileRef)

Parameters:

aDirectory: the current designated directory.

formRef: the form identification.

dirTitle: the title of the directory selector.

dirRef: the directory selector identification or -1 if this selector is not desired.

suffix: the suffix used for filtering files (for example ".PIV")

fileTitle: the title of the file selector.

fileRef: the file selector identification or -1 if this selector is not desired.

9.1.16 TtaIsSuffixFileIn

Returns True if the specified directory contains files with the specified suffix.

ThotBool TtaIsSuffixFileIn(char *aDirectory, char *suffix)

Parameters:: aDirectory: the current designated directory.
suffix: the suffix used for filtering files (for example ".PIV")

Return value:: True or False.

9.2 Modificators

9.2.1 TtaSetMenuForm

Selects an entry in a radio menu (submenu) of a form.

void TtaSetMenuForm (int ref, int entry)

Parameters:

ref: the unique reference attached to the dialogue element.

entry: the selected entry (0 to n).

9.2.2 TtaSetToggleMenu

Changes the status of a toggle entry of a menu (submenu or toggle menu) in a form.

void TtaSetToggleMenu (int ref, int value, ThotBool on)

Parameters:

ref: the unique reference attached to the dialogue element.

entry: the selected entry (0 to n).

on: fixes the status of the toggle; TRUE if the toggle is selected.

9.2.3 TtaSetTextForm

Changes the current value of the text form.

void TtaSetTextForm (int ref, STRING text)

Parameters:

ref: the unique reference attached to the dialogue element.

text: the new string.

9.2.4 TtaShowDialogue

This function displays an existing dialogue (form, sheet, dialog sheet).

void TtaShowDialogue (int ref, ThotBool remanent)

Parameters:

ref: the unique reference attached to the dialogue element.

remanent: TRUE if the dialogue element is not automatically unmapped.

9.2.5 TtaUnmapDialogue

This function undisplays an existing dialogue (form, sheet, dialog sheet).

void TtaUnmapDialogue (int ref)

Parameter:: ref: the unique reference attached to the dialogue element.

10 Documents and schemas

The functions described in this section require that file document.h be included in the module that calls them.

Document identification: An application program using the Thot editing tool kit can handle several documents at the same time. These documents can be defined by the same structure schema or by different structure schemas as well. Before any other operation can be performed, a document must be either created (TtaNewDocument), if it does not exist yet, or opened (TtaOpenDocument), if it exists in a file. These two functions return a value of type Document that is then used for identifying the document to which subsequent operations apply. The only exception is the function TtaGiveSchemasOfDocument which accesses a document by its name.
The name of a document is a character string (maximum length is 19 characters, not including the extension) that is used for naming the file containing the document and that appears in the user dialogue (Thot Editor only).

Document files

Documents are stored in Unix files. Actually, a single document is represented by several files. All these files have the same name as the document, with different extensions:

The .PIV file contains the last version of the document (logical structure, contents, logical attributes and specific presentation rules). A .PIV file is created each time the document is saved, either by the user or by the application program (function TtaSaveDocument). The .PIV file is the file read by the TtaOpenDocument function.
The .OLD file contains the previous version of the document. It is a copy of the .PIV file before the last save operation.
The .BAK file contains a version of the document that is written periodically for allowing recovery from crashes. It is removed each time the document is saved successfully, but if the system or the application crashes, it must be renamed .PIV and can be used as an ordinary document file.
The .SAV file is also a backup file. It is created by the tool kit when an internal error occurs and when it can save the document. This file contains the state of the document at the very moment of the crash. It can be used in the same way as the .BAK file.
The .EXT and .REF files contain the representation of the links that relate the document with other documents. These files do not exist if the document has no relations (references) with other documents. If they exist, they must be in the same directory as the .PIV file. They are read by the function TtaOpenDocument.

Directories: A list of directories, called the document path, is used for searching the files needed when opening a document (.PIV, .REF and .EXT files). This path is initially set by the environment variable THOTDOC and it can be changed at any time by the function TtaSetDocumentPath. When a document is created (TtaNewDocument), all corresponding files are created in the first directory of the document path.
Another list of directories is used when searching the schemas needed by a document that is created (TtaNewDocument) or opened (TtaOpenDocument). The schema path is initially set by the environment variable THOTSCH and it can be changed at any time by the function TtaSetSchemaPath. This path is also used by the function TtaNewNature.

Access mode: When using Thot Editor, the application program may ask the tool kit to prevent the user from modifying the document: an access mode (allowed values are read/write and read only) is associated with the whole document. The functions of the editing tool kit are not affected by the access mode; an application program can modify a document even if it is in read only mode. The access mode only applies to the operations performed by the user, who cannot modify a document that is in read only mode. When creating or opening a document, the access mode is set to read/write, but it can be changed at any time by the function TtaSetDocumentAccessMode.
An application program can more precisely control the operations that the user is allowed to perform, by associating an access mode with each element in a document. This is explained in section 11.

Natures: Many structured documents contain objects of different natures, such as tables, equations, drawings, bibliographic items, etc. which are themselves logically structured. For avoiding to define the structure of these objects in the structure schemas of all document types, these objects are defined in separate structure schemas, one for each nature of objects, and they can be dynamically linked to document structure schemas. This can be repeated recursively: if an object of a given nature includes objects of other natures, its structure schema must include the structure schemas of the included natures.
When the first object of a given nature is created in a document or in an object of another nature, the structure schema that defines the new nature must be linked to the structure schema that defines the document or object in which it is included. This is achieved by calling the function TtaNewNature.

Schema extensions: Documents produced by Thot may be processed by other applications, which are either independent from the editor or included in it. Examples of such applications are the comparison of two versions of a document (independent from the editor) or the electronic index (included in the editor). Many of these applications make use of their own structural elements or attributes, which are related to the application itself and which are necessary for the application, whatever the document type. A structure schema extension is a special type of structure schema that defines attributes and elements of that kind and that can be associated to the main structure schema of any document for allowing an application to create in the document its own attributes and elements, which are not defined in the document structure schema. When several applications have to work on the same document, several schema extensions can be associated to the main structure schema of that document.

10.1 Constructors

10.1.1 TtaNewDocument

Creates the internal representation of a new document according to a given structure schema. No file is created immediately, but the backup files (.BAK and .SAV) and the document file (.PIV, see TtaNewDocument) will be created in the first directory of the document path (see TtaSetDocumentPath).

Document TtaNewDocument(char *structureSchema, char *documentName)

Parameters:: structureSchema: name of the structure schema that defines the type of document to be created.
documentName: name of the document to be created (maximum length 19 characters). The directory name is not part of this parameter (see TtaSetDocumentPath).

Return value:: the document that has been created or 0 if the document has not been created.

10.1.2 TtaOpenDocument

Opens an existing document for subsequent operations.

Document TtaOpenDocument(char *documentName, int accessMode)

Document TtaOpenDocument(documentName, accessMode)
char *documentName;
int accessMode;

Parameters:: documentName: name of the file containing the document to be open. (maximum length 19 characters). The directory name is not part of this parameter (see TtaSetDocumentPath).
accessMode: 0 = read only, 1 = read-write.

Return value:: the opened document, or 0 if the document cannot be open.

10.1.3 TtaSaveDocument

Saves a document into a file in Thot format (.PIV). The document is not closed by the function and can still be accessed by the application program.

void TtaSaveDocument(Document document, char *documentName)

Parameters:: document: the document to be saved.
documentName: name of the file in which the document must be saved. (maximum length 19 characters). The directory name is not part of this parameter (see TtaSetDocumentPath). If the documentName is not the same as the one used when opening (see TtaOpenDocument) or creating (see TtaNewDocument) the document, a new file is created and the file with the old name is unchanged, i. e. a new version is created. If necessary, the old file can be removed by the function TtaRemoveDocument.

10.1.4 TtaExportDocument

Saves a document into a file in a particular format. The output format is specified by a translation schema. The document is not closed by the function and it can still be accessed by the application program.

ThotBool TtaExportDocument(Document document, char *fileName, char *TSchemaName)

Parameters:

document: the document to be exported.

fileName: name of the file in which the document must be saved, including the directory name.

TSchemaName: name of the translation schema to be used. The directory name must not be specified in parameter TSchemaName. See function TtaSetSchemaPath.

Return value:: TRUE if the document has not saved.

10.1.5 TtaCloseDocument

Closes a document that is no longer needed and releases all ressources allocated to the document. This function does not save the document.

void TtaCloseDocument(Document document)

Parameter:: document: the document to be closed.

10.1.6 TtaRemoveDocument

Closes a document, releases all ressources allocated to that document, removes all files related to the document and updates all links connecting the removed document with other documents.

void TtaRemoveDocument(Document document)

Parameter:: document: the document to be removed.

10.1.7 TtaSetDocumentPath

Sets a new list of document directories. This list replaces the existing one. It is used for searching a document when it is open either by the user or by the application program (see TtaOpenDocument). The first directory in the list is used when a new document is created (see TtaNewDocument).

void TtaSetDocumentPath(char *path)

Parameter:: path: the directory list, where directory names are separated by the character ':'.

10.1.8 TtaAppendDocumentPath

Appends a new directory in the list of document directories. The function controls that the parameter is the name of an existing directory and sets an error if it is not. If the new directory is within the list of document directories yet, the function has no effect.

void TtaAppendDocumentPath(aDirectory)

Parameter:: aDirectory: the new directory name.

10.1.9 TtaSetSchemaPath

Sets a new list of schema directories. This list replaces the existing one. It is used for searching schemas.

void TtaSetSchemaPath(char *path)

Parameter:: path: the directory list, where directory names are separated by the character ':'.

10.2 Modificators

10.2.1 TtaNewNature

Adds a new nature in a structure schema and returns the structure schema of the new nature. If the nature already exists in that structure schema, the function simply returns the structure schema of that nature.

SSchema TtaNewNature(SSchema schema, char *natureName, char *presentationName)

Parameters:

schema: the structure schema to which the nature is added.

natureName: name of the nature to be added in the structure schema.

presentationName: name of the presentation schema to be associated with the extension schema. If presentationName is an empty string, the default presentation schema is associated. If the nature already exists, presentationName is ignored.

Return value:: the structure schema of the new nature; NULL if the structure schema has not been loaded.

10.2.2 TtaNewSchemaExtension

Loads a structure schema extension and associates it with a given document.

SSchema TtaNewSchemaExtension(Document document, char *extensionName, char *presentationName)

Parameters:

document: the document whose structure schema must be extended.

extensionName: name of the extension schema.

presentationName: name of the presentation schema to be associated with the extension schema. If presentationName is an empty string, the default presentation schema is associated.

Return value:: the extension schema, NULL if the extension schema has not been loaded.

10.2.3 TtaRemoveSchemaExtension

Removes a structure schema extension from a given document. Removes also from the document all attributes and elements defined in that structure schema extension.

void TtaRemoveSchemaExtension(Document document, SSchema extension, int *removedElements, int *removedAttributes)

Parameters:: document: the document.
extension: the structure schema extension to be removed.

Return parameters:: removedElements: number of elements actually removed.
removedAttributes: number of attributes actually removed.

10.2.4 TtaSetPSchema

Sets or changes the main presentation schema of a document. The document must be open, but no view must be open for that document.

void TtaSetPSchema(Document document, char *presentationName)

Parameters:: document: the document.
presentationName: Name of the presentation schema to be associated with the document.

10.2.5 TtaSetDocumentDirectory

Sets the directory to which the document will be saved when calling TtaSaveDocument.

void TtaSetDocumentDirectory(Document document, char *directory)

Parameters:: document: the document whose directory is set.
directory: new document directory.

10.2.6 TtaSetDocumentName

Sets or changes the name of a document. The document must be loaded.

void TtaSetDocumentName(Document document, char *documentName)

Parameters:: document: the document whose name is set.
documentName: new document name. This is only the name, without any suffix, without directory name. See function TtaSetDocumentDirectory for changing the directory of a document.
The name must not exceed 31 characters.

10.2.7 TtaSetDocumentAccessMode

Sets the access mode for a document.

void TtaSetDocumentAccessMode(Document document, int accessMode)

Parameters:: document: the document whose access mode is changed.
accessMode: 0 = read only, 1 = read-write.

10.2.8 TtaSetDocumentBackUpInterval

Sets the backup interval for a document.

void TtaSetDocumentBackUpInterval(Document document, int interval)

Parameters:: document: the document whose backup interval is changed.
interval: 0 : the backup mechanism must be disabled
positive integer : number of characters typed which triggers automatic save of the document into a .BAK file.

10.2.9 TtaSetNotificationMode

Sets the ECF notification mode for a document.

void TtaSetNotificationMode(Document document, int notificationMode)

Parameters:: document: the document whose notification mode is changed.
notificationMode: 0 = only roots of created, copied and deleted subtrees must be notified, 1 = all elements of created, copied and deleted subtrees must be notified.

10.2.10 TtaSetDocumentModified

Notifies the tool kit that a document has been modified by the application. As a consequence, the user will be asked to save the document when closing it.

void TtaSetDocumentModified(Document document)

Parameter:: document: the document.

10.2.11 TtaSetDocumentUnmodified

Notifies the tool kit that a document must be considered as not modified. As a consequence, if no further modification is made to that document, the user will not be asked to save the document when closing it.

void TtaSetDocumentUnmodified(Document document)

Parameter :: document : the document.

10.2.12 TtaSetDocumentUnupdated

Notifies the tool kit that a document must be considered as not updated by the application or by the user. That will allow the application to detect if any change will be made on the document (see TtaIsDocumentUpdated).

void TtaSetDocumentUnupdated(Document document)

Parameter :: document : the document.

10.3 Accessors

10.3.1 TtaGetSchemaExtension

Returns the extension structure schema associated with the given document.

SSchema TtaGetSchemaExtension(Document document, char *ExtensionName)

Parameter :

document : the document for which the extension structure schema is asked.

ExtensionName : the extension name.

10.3.2 TtaGetDocumentName

Returns the name of a document.

char *TtaGetDocumentName(Document document)

Parameter:: document: the document whose name is asked.

Return value:: name of that document.

10.3.3 TtaGetDocumentFromName

Returns the document having a given name.

Document TtaGetDocumentFromName(char *documentName)

Parameter:: documentName: the document name.

Return value:: the document having that name.

10.3.4 TtaGetDocumentSSchema

Returns the main structure schema of a document.

SSchema TtaGetDocumentSSchema(Document document)

Parameter:: document: the document for which the structure schema is asked.

Return value:: the structure schema of that document.

10.3.5 TtaGetSSchemaName

Returns the name of a structure schema.

char *TtaGetSSchemaName(SSchema schema)

Parameter:: schema: the structure schema of interest.

Return value:: name of that structure schema.

10.3.6 TtaGetPSchemaName

Returns the name of the presentation schema currently associated with a given structure schema.

char *TtaGetPSchemaName(SSchema schema)

Parameter:: schema: the structure schema of interest.

Return value:: name of the associated presentation schema.

10.3.7 TtaGetDocumentDirectory

Returns the directory to which the document is supposed to be saved.

void TtaGetDocumentDirectory(Document document, char *buffer, int bufferLength)

Parameters:

document: the document whose directory is asked.

buffer: a buffer provided by the caller.

bufferLength: the length of that buffer.

Return parameter:: buffer: the document directory.

10.3.8 TtaGetSSchema

Returns a structure schema whose name is known and that is used in a given document.

SSchema TtaGetSSchema(char *name, Document document)

Parameter:: name: the name of the structure schema of interest.
document: the document that uses this structure schema.

Return value:: the structure schema having this name, or NULL if this structure schema is not loaded or not used by the document.

10.3.9 TtaSameSSchemas

Compares two structure schemas.

int TtaSameSSchemas(SSchema schema1, SSchema schema2)

Parameters:: schema1: first structure schema.
schema2: second structure schema.

Return value:: 0 if both schemas are different, 1 if they are identical.

10.3.10 TtaGiveSchemasOfDocument

Returns the names of the main structure schema and presentation schema associated with a given document. The document does not need to be open and the schemas are not loaded by this function.

void TtaGiveSchemasOfDocument(char *documentName, char *structureName, char *presentationName)

Parameters:

documentName: Name of the document to be checked (maximum length 19 characters).

structureName: buffer.

presentationName: buffer.

Return value:: structureName: Name of the document structure schema.
presentationName: Name of the document presentation schema.

10.3.11 TtaNextSchemaExtension

Returns a structure schema extension associated with a given document.

void TtaNextSchemaExtension(Document document, SSchema *extension)

Parameters:: document: the document of interest.
extension: a schema extension of that document. NULL for accessing the first schema extension.

Return parameter:: extension: the schema extension that follows or the first schema extension of the document if parameter extension is NULL. NULL if there is no more schema extension.

10.3.12 TtaNextNature

Returns the structure schema of a nature used in a given document.

void TtaNextNature(Document document, SSchema *nature)

Parameters:: document: the document of interest.
nature: the structure schema of a nature for that document. NULL for accessing the first nature.

Return parameter:: nature: the structure schema of the next nature, or the structure schema of the first nature of the document if parameter nature was NULL when calling. NULL if there is no more nature for the document.

10.3.13 TtaIsDocumentModified

Indicates whether a document has been modified by the user or not. Modifications made by the application program are not considered, except when explicitly notified by TtaSetDocumentModified.

int TtaIsDocumentModified(Document document)

Parameter:: document: the document.

Return value:: 1 if the document has been modified by the user since it has been saved, loaded or created, 0 if it has not been modified.

10.3.14 TtaIsDocumentUpdated

Indicates whether a document has been updated by the user or not since the last TtaSetDocumentUnupdated or TtaSetDocumentUnmodified. Modifications made by the application program are not considered, except when explicitly notified by TtaSetDocumentModified.

int TtaIsDocumentUpdated(Document document)

Parameter:: document: the document.

Return value:: 1 if the document has been modified by the user since it has been saved, loaded or created, 0 if it has not been modified.

10.3.15 TtaGetDocumentBackUpInterval

Returns the backup interval for a document.

int TtaGetDocumentBackUpInterval(Document document)

Parameter:: document: the document whose backup interval is asked.

Return value:: 0 : the backup mechanism is disabled
positive integer : number of typed characters which trigger an autamatic save of the document into a .BAK file.

10.3.16 TtaGetDocumentAccessMode

Returns the access mode for a document.

int TtaGetDocumentAccessMode(Document document)

Parameter:: document: the document whose access mode is asked.

Return value:: 0 if access mode is read only, 1 if access mode is read-write.

10.3.17 TtaGetNotificationMode

Returns the ECF notification mode for a document.

int TtaGetNotificationMode(Document document)

Parameters:: document: the document whose notification mode is asked.

Return value:: 0 = if only roots of created and deleted subtrees must be notified,
1 = all elements of created and deleted subtrees must be notified.

10.3.18 TtaGetDocumentPath

Returns the current list of the directories used when a document is open (see TtaOpenDocument).

void TtaGetDocumentPath(char *buffer, int bufferLength)

Parameters:: buffer: a buffer provided by the caller.
bufferLength: the length of that buffer.

Return parameter:: buffer: the list of directories. Directory names are separated by the character ':'.

10.3.19 TtaGetSchemaPath

Returns the current list of directories used for accessing schemas.

void TtaGetSchemaPath(char *buffer, int bufferLength)

Parameters:: buffer: a buffer provided by the caller.
bufferLength: the length of that buffer.

Return parameter:: buffer: the list of directories. Directory names are separated by the character ':'.

10.3.20 TtaGetDocumentOfSavedElements

Returns the document for which the last Copy or Cut command has been issued.

Document TtaGetDocumentOfSavedElements()

Parameters:: no parameter

Return value:: the document for which the last Copy or Cut command has been issued. 0 if the clipboard is empty.

11 Tree structures

The largest group of functions in the editing tool kit handles the tree structures that represent the logical organization of a document.

The functions described in this section require that file tree.h be included in the module that calls them.

Main tree and associated trees: A document is in fact represented by a forest, as several trees may be necessary for representing its abstract structure. The main tree represents the main stream of information in a document. In addition to that tree, there may exist some associated trees, which represent other streams of information, such as notes, illustrations, comments, etc. These associated trees are specified in the structure schema of the document.

Structure of abstract trees

Several functions in this group allow to build or modify the structure of an abstract tree. As stated above, the structure of these trees is constrained by structure schemas. Therefore the programmer must be careful when handling abstract trees. All functions that change a tree structure check that the result will be consistent with the structure schema and they raise an error in case of inconsistency.

Checking can be made in two modes, a strict mode and a relaxed mode. In strict mode, all mandatory elements must always be present. In relaxed mode, even elements that are not stated optional in their structure schema can be omitted. The checking mode apply to the operations made by the application program, but also to the editing commands issued by the end-user, when using ThotEditor. The function TtaSetCheckingMode (see section 11.2.8) changes checking mode.

For building a correct tree, the programmer must follow the structure schema. He or she can also consider existing Thot documents as examples. For that purpose, the function TtaListAbstractTree (see section 11.5.1) can produce a human-readable form of an abstract tree.

Element types: When creating or searching elements in an abstract tree, the type of the concerned elements must be given. As presented in section 4, an element type contains a type number, but this number does not appear explicitly in a structure schema: it is generated by the schema compiler. For obtaining all type numbers of a structure schema, use the command:
printsch -h SchemaName
which lists on the standard output a file that can be included into a C program. This file also contains all attribute numbers of the schema

Order of operations: As a general rule, as soon as an element or a tree has been created (by functions TtaNewElement, TtaNewTree, or TtaCopyTree), it must be included into the main tree or an associated tree of a document (by functions TtaInsertSibling, TtaInsertFirstChild, or TtaAttachNewTree), prior any other function can be performed.

Labels: Each element in a document has a unique identifier called a label. Labels are automatically assigned to elements by all functions that create new elements (TtaNewElement, TtaNewTree, or TtaCopyTree). Labels can be accessed by functions TtaSearchElementByLabel and TtaGetElementLabel.

Access rights

An access right can be associated with each element. Three access rights are defined:

Read/write: The element can be seen and modified by the user.
Read only: The element can be seen by the user, but no changes are allowed.
Hidden: The element is not displayed and cannot be changed by the user.

These rights only apply to the end user who manipulates a document interactively with the commands provided by the Thot editor. They do not apply to the application program that manipulate the document through the editing tool kit.

11.1 Constructors

11.1.1 TtaNewElement

Creates a new element of a given type.

Element TtaNewElement(Document document, ElementType elementType)

Parameters:: document: the document for which the element is created.
elementType: type of the element to be created.

Return value:: the created element.

11.1.2 TtaNewTree

Creates a new element of a given type and all its descendants, according to the structure schema.

Element TtaNewTree(Document document, ElementType elementType , char *label)

Parameters:

document: the document for which the tree is created.

elementType: type of the root element of the tree to be created.

label: label of the root element to be created. Empty string if the value of the label is undefined.

Return value:: the root element of the created tree.

11.1.3 TtaCopyTree

Creates a copy of a tree.

Element TtaCopyTree(Element sourceElement, Document sourceDocument, Document destinationDocument, Element parent)

Parameters:

sourceElement: element to be copied.

sourceDocument: the document containing the element to be copied.

destinationDocument: the document for which the copy must be created.

parent: element that will become the parent of the created tree.

Return value:: the root element of the created tree.

11.1.4 TtaCreateDescent

Creates a new element of a given type and inserts it in the tree as a descendant of a given element. All elements of the descent required by the structure schema are also created.

Element TtaCreateDescent(Document document, Element element, ElementType elementType)

Parameters:

document: the document for which the tree is created.

element: the element for which a descent will be created.

elementType: type of the element to be created as the last descendant.

Return value:: the last descendant created or NULL if the element cannot be created. This element is empty.

11.1.5 TtaCreateDescentWithContent

Creates a new element of a given type and inserts it in the tree as a descendant of a given element. All elements of the descent required by the structure schema are created, as well as the content of the requested element.

Element TtaCreateDescentWithContent(Document document, Element element, ElementType elementType)

Parameters:

document: the document for which the tree is created.

element: the element for which a descent will be created.

elementType: type of the element to be created as the last descendant.

Return value:: the last descendant created or NULL if the element cannot be created. If not NULL, the minimum content of that element has been created.

11.1.6 TtaDeleteTree

Deletes a tree (or a single element) and frees it. All references that points at any element of that tree are cancelled. The deleted element must not be used later.

void TtaDeleteTree(Element element, Document document)

Parameters:: element: the element (or root of the tree) to be deleted.
document: the document containing the element to be deleted.

11.1.7 TtaAttachNewTree

Attaches an entire tree (main tree or associated tree) to a document.

void TtaAttachNewTree(Element tree, Document document)

Parameters:: tree: root of the tree to be attached. This tree must be a valid main tree or associated tree according to the document structure schema.
document: the document to which the tree is to be attached.

11.1.8 TtaExportTree

Saves an abstract tree into a file in a particular format. The output format is specified by a translation schema.

void TtaExportTree (Element element, Document document, char *fileName, char *TSchemaName)

Parameters:

element: the root of the tree to be exported

document: the document containing the tree to be exported.

fileName: name of the file in which the tree must be saved, including the directory name.

TSchemaName: name of the translation schema to be used. The directory name must not be specified in parameter TSchemaName. See function TtaSetSchemaPath.

11.2 Modificators

11.2.1 TtaInsertSibling

Inserts an element in a tree, as an immediate sibling of a given element. The element to be inserted must not yet be part of a document. You can call TtaCanInsertSibling before to check whether that insertion is allowed or not (see section 11.3.33).

void TtaInsertSibling(Element newElement, Element sibling, ThotBool before, Document document)

Parameters:

newElement: the element (or root of the tree) to be inserted.

sibling: an element belonging to a tree. This element must not be the root of a tree.

before: if True, inserts newElement as previous sibling of sibling, if False, inserts newElement as next sibling of sibling.

document: the document to which both elements belong.

11.2.2 TtaInsertFirstChild

Inserts an element in a tree, as the first child of a given element. The element to be inserted must not yet be part of a document. This function can also be used for attaching an option to a choice. You can call TtaCanInsertFirstChild before to check whether that insertion is allowed or not (see section 11.3.34).

void TtaInsertFirstChild(Element *newElement, Element parent, Document document)

Parameters:

newElement: the element (or root of the tree) to be inserted.

parent: an element belonging to a tree.

document: the document to which both elements belong.

Return parameter:: If newElement is an option that replaces the choice, newElement takes
the value of parent.

11.2.3 TtaCreateElement

Creates an element of a given type and insert it at the current position within a given document. The current position is defined by the current selection. If the current position is a single position (insertion point) the new element is simply inserted at that position. If one or several characters and/or elements are selected, the new element is created at that position and the selected characters/elements become the content of the new element, provided the structure schema allows it.

void TtaCreateElement(ElementType elementType, Document document)

Parameters:: elementType: type of the element to be created.
document: the document for which the element is created.

11.2.4 TtaInsertElement

Creates an element of a given type and insert it at the current position within a given document. The current position is defined by the current selection. If the current position is a single position (insertion point) the new element is simply inserted at that position. If one or several characters and/or elements are selected, the new element is created before the first selected character/element and the selected characters/elements are not changed.

void TtaInsertElement(ElementType elementType, Document document)

Parameters:: elementType: type of the element to be created.
document: the document for which the element is created.

11.2.5 TtaRemoveTree

Removes a tree (or a single element) from its tree, without freeing it.

void TtaRemoveTree(Element element, Document document)

Parameters:: element: the element (or root of the tree) to be removed.
document: the document containing the element to be removed.

11.2.6 TtaSetAccessRight

Sets the access rights for a given element. Access rights apply only during the current editing session; they are not saved with the document. They must be set each time the document is loaded.

void TtaSetAccessRight(Element element, AccessRight right, Document document)

Parameters:

element: the element.

right: access right for that element (ReadOnly, ReadWrite, Hidden, Inherited).

document: the document to which the element belongs.

11.2.7 TtaHolophrastElement

Changes the holophrasting status of a given element.

void TtaHolophrastElement(Element element, ThotBool holophrast, Document document)

Parameters:

element: the element.

holophrast: True: the element gets holophrasted if it is not, False: if the element is holphrasted, it gets expanded.

document: the document to which the element belongs.

11.2.8 TtaSetCheckingMode

Changes checking mode.

void TtaSetCheckingMode(ThotBool strict)

Parameter:: strict: if True, the presence of all mandatory elements is checked.

11.3 Accessors

11.3.1 TtaGetMainRoot

Returns the root element of the main abstract tree representing a document.

Element TtaGetMainRoot(Document document)

Parameter:: document: the document.

Return value:: the root element of the main abstract tree.

11.3.2 TtaNextAssociatedRoot

Returns the root element of the associated tree that follows the tree to which a given element belongs.

void TtaNextAssociatedRoot(Document document, Element *root)

Parameters:: document: the document.
root: the element for which the next associated tree is searched. That element does not need to be the root of a tree. If root is NULL or if root is an element in the main tree, the root of the first associated tree is returned.

Return parameter:: root: the root element of the next associated tree. NULL if there is no next associated tree for the document.

11.3.3 TtaGetFirstChild

Returns the first child element of a given element.

Element TtaGetFirstChild(Element parent)

Parameter:: parent: the element for which the first child element is asked.

Return value:: the first child element of parent; NULL if parent has no child.

11.3.4 TtaGetLastChild

Returns the last child element of a given element.

Element TtaGetLastChild(Element parent)

Parameter:: parent: the element for which the last child element is asked.

Return value:: the last child element of parent; NULL if parent has no child.

11.3.5 TtaGetFirstLeaf

Returns the first leaf element of a given element.

Element TtaGetFirstLeaf(Element parent)

Parameter:: parent: the element for which the first leaf element is asked.

Return value:: the first leaf element of parent; parent itself if it has no leaf.

11.3.6 TtaGetLastLeaf

Returns the last leaf element of a given element.

Element TtaGetLastLeaf(Element parent)

Parameter:: parent: the element for which the last leaf element is asked.

Return value:: the last leaf element of parent; parent itself if it has no leaf.

11.3.7 TtaPreviousSibling

Returns the previous sibling element of a given element.

void TtaPreviousSibling(Element *element)

Parameter:: element: the element whose previous sibling is asked.

Return parameter:: element: the previous sibling element, or NULL if there is no previous sibling.

11.3.8 TtaNextSibling

Returns the next sibling element of a given element.

void TtaNextSibling(Element *element)

Parameter:: element: the element whose next sibling is asked.

Return parameter:: element: the next sibling element, or NULL if there is no next sibling.

11.3.9 TtaGetSuccessor

Returns the element that follows a given element at the same level or at the first upper level where there is a following element.

Element TtaGetSuccessor(Element element)

Parameter:: element: the element whose successor is asked.

Return value:: the successor, or NULL if there is no successor.

11.3.10 TtaGetPredecessor

Returns the element that precedes a given element at the same level or at the first upper level where there is a preceding element.

Element TtaGetPredecessor(Element element)

Parameter:: element: the element whose predecessor is asked.

Return value:: the predecessor, or NULL if there is no predecessor.

11.3.11 TtaGetParent

Returns the parent element (i.e. first ancestor) of a given element.

Element TtaGetParent(Element element)

Parameter:: element: the element whose the parent is asked.

Return value:: the parent element, or NULL if there is no parent (root).

11.3.12 TtaGetCommonAncestor

Returns the common ancestor element of two given elements.

Element TtaGetCommonAncestor(Element element1, Element element2)

Parameters:: element1: the first element whose ancestor is asked.
element2: the second element whose ancestor is asked.

Return value:: the common ancestor, or NULL if there is no common ancestor.

11.3.13 TtaGetTypedAncestor

Returns the first ancestor of a given type for a given element.

Element TtaGetTypedAncestor(Element element, ElementType ancestorType)

Parameters:: element: the element whose ancestor is asked.
ancestorType: type of the asked ancestor.

Return value:: the ancestor, or NULL if there is no ancestor of that type.

11.3.14 TtaGetElementType

Returns the type of a given element.

ElementType TtaGetElementType(Element element)

Parameter:: element: the element.

Return value:: type of the element.

11.3.15 TtaGetElementTypeName

Returns the name of an element type.

char *TtaGetElementTypeName(ElementType elementType)

Parameter:: elementType: element type.

Return value:: name of that type.

11.3.16 TtaGetElementTypeOriginalName

Returns the original name of an element type, as it is defined in the structure schema.

char *TtaGetElementTypeOriginalName(ElementType elementType)

Parameter:: elementType: element type.

Return value:: original name of that type.

11.3.17 TtaGiveTypeFromName

Gives an element type whose name is known (the structure schema that defines that type must be loaded). That type is searched in a given structure schema (elementType.ElSSchema) and in all structure schemas that are extensions of that structure schema or natures used in that structure schema.

void TtaGiveTypeFromName(ElementType *elementType, char *name)

Parameter

The Thot Tool Kit API

1 Introduction to the document model

1.1 Logical structure

1.2 Presentation

2 Tool kit structure

2.1 Structure of this manual

2.2 Libraries

2.2.1 Thot Kernel library

2.2.2 Thot Editor library

3 Using the Thot tool kit

3.1 Errors

3.2 Include files

3.3 Buffers

3.4 Naming conventions

5 Initialization

5.1 Constructors

5.1.1 TtaInitialize

5.1.2 TtaQuit

5.1.3 TtaInitializeAppRegistry

5.1.4 TtaSaveAppRegistry

5.2 Modificators

5.2.1 TtaSetApplicationQuit

6.1 Constructors

6.1.1 TtaGetMemory

6.1.2 TtaFreeMemory

6.1.3 TtaGetEnvString

6.1.4 TtaGetDefEnvString

6.1.5 TtaGetEnvInt

6.1.6 TtaGetDefEnvInt

6.1.7 TtaGetEnvBoolean

6.1.8 TtaGetDefEnvBoolean

6.1.9 TtaIsBlank

6.1.10 TtaSkipBlanks

6.2 Modificators

6.2.1 TtaSetErrorMessages

6.2.2 TtaSetEnvString

6.2.3 TtaSetDefEnvString

6.2.4 TtaSetEnvInt

6.2.5 TtaSetEnvBoolean

6.3 Accessors

6.3.1 TtaGetVersion

6.3.2 TtaGetErrorCode

6.3.3 TtaGetStrError

7.1 Constructors

7.1.1 TtaSetCallback

7.1.2 TtaHandlePendingEvents

7.1.3 TtaHandleOneEvent

7.1.4 TtaAddButton

7.1.5 TtaAddTextZone

7.2 Accessors

7.2.1 TtaGetCurrentDisplay

7.2.2 TtaGetScreenDepth

7.2.3 TtaClickAnElement

7.3 Modificators

7.3.1 TtaChangeButton

7.3.2 TtaSetTextZone

7.3.3 TtaSetMenuOff

7.3.4 TtaSetMenuOn

7.3.5 TtaSetActionOff

7.3.6 TtaSetActionOn

7.3.7 TtaSetToggleItem

7.3.8 TtaSetCursorWatch

7.3.9 TtaResetCursor

8.1 Constructors

8.1.1 TtaGetMessageTable

8.2 Accessors

8.2.1 TtaGetMessage

8.2.2 TtaDisplaySimpleMessage

8.2.3 TtaDisplayMessage

9.1 Constructors

9.1.1 TtaSetCallback

9.1.2 TtaSetBackup

9.1.3 TtaSetDocStatusUpdate

9.1.4 TtaNewForm

9.1.6 TtaNewDialogSheet

9.1.7 TtaNewSubmenu

9.1.8 TtaNewIconMenu

9.1.9 TtaNewToggleMenu

9.1.10 TtaNewSelector

9.1.11 TtaNewLabel