Object Classes

1 Eloquence Dialog System

Object Classes

On the following pages, the different object classes of the ASCII DLG are defined. All additional Objects of the Dialog Manager are defined in the Dialog MAnager Manual.

The definition contains information on whether the objects of this object class can have the cursor focus and whether it can have children or not. Then all attributes which are available for this object class are described, together with their data types, their default values and whether the attribute values can be set and/or requested (get).

Accessing Dialog Manager Objects

Eloquence only knows about a subset of Dialog Manager objects and attributes as necessary to translate Eloquence DLG to Dialog Manager.

In order to enable access to Dialog Manager objects and attributes not available in Eloquence DLG there is a "bypass option" implemented in Eloquence.

If you use an exclamation mark ('!') instead of a dot ('.') as a separator between object path and attribute, no mapping will be performed. Instead, the native Dialog Manager objects and attributes are accessed.

Two examples of native Dialog Manager objects are menubar and menuitem. An example of a native Dialog Manager attribute is the format attribute of edittext objects:

   DLG SET "MyWindow.Edit!format","%8'3,02sf/1"

This will set the field format of the edittext object named Edit.

Dialog Object

The root object of a dialog must always be of class Dialog. All other objects have to be generated in a dialog. The dialog is an optical frame for other objects. The coordinates are interpreted as relative to the screen.

Class name:: Dialog
Focus :: No
Children :: Yes

Attributes:

Name Type G/S Default value
.class Strg G Dialog
.x Int G/S 0
.y Int G/S 0
.w Int G/S 0
.h Int G/S 0
.visible Bool G/S True
.sensitive Bool G/S False
.rule Int G/S 0
.focus Bool G/S False
.help Strg G/S
.udata Any G/S
.title Strg G/S
.border Int G/S 3
.f1 Int G/S -1
.f2 Int G/S 0
.f3 Int G/S 0
.f4 Int G/S 0
.f5 Int G/S 0
.f6 Int G/S 0
.f7 Int G/S 0
.f8 Int G/S 0
.cr Int G/S 0

Name	Type	G/S	Default value
.class	Strg	G	Dialog
.x	Int	G/S	0
.y	Int	G/S	0
.w	Int	G/S	0
.h	Int	G/S	0
.visible	Bool	G/S	True
.sensitive	Bool	G/S	False
.rule	Int	G/S	0
.focus	Bool	G/S	False
.help	Strg	G/S
.udata	Any	G/S
.title	Strg	G/S
.border	Int	G/S	3
.f1	Int	G/S	-1
.f2	Int	G/S	0
.f3	Int	G/S	0
.f4	Int	G/S	0
.f5	Int	G/S	0
.f6	Int	G/S	0
.f7	Int	G/S	0
.f8	Int	G/S	0
.cr	Int	G/S	0

The .x and .y attributes define the position of the upper left corner of the object. These values are relative to the screen for the Dialog object class.

The .border attribute defines the type of the border. The following values are supported:

0: no border
1: thin border
2: thick border
3: shadow border
4: reverse shadow border

The .f1...f8 attributes assign values to the function keys F1 .. F8. If a non-zero value is assigned to a function key, and this function key is pressed, the dialog is suspended, returning the appropriate f1 .. f8 attribute value and the object path where the focus was set. If the assigned value is -1 and the function key is pressed, the help subsystem is started.

If not specified, function keys are ignored except for f1, which calls the help subsystem.

The .cr attribute assigns a value to the Return key. If the value is non-zero and the Return key is pressed, the dialog is suspended, returning the appropriate cr attribute value and the object path where the focus was set. The default behaviour of the Return key is to move the focus to the next object.

Groupbox Object

A groupbox is used to group objects together. If you move the groupbox, all objects in this group are moved.

Class name:: GroupBox
Focus :: No
Children :: Yes

Attributes:

Name Type G/S Default value
.class Strg G GroupBox
.x Int G/S 0
.y Int G/S 0
.w Int G/S 0
.h Int G/S 0
.visible Bool G/S True
.sensitive Bool G/S False
.rule Int G/S 0
.focus Bool G/S False
.help Strg G/S
.udata Any G/S
.title Strg G/S
.border Int G/S 1

Name	Type	G/S	Default value
.class	Strg	G	GroupBox
.x	Int	G/S	0
.y	Int	G/S	0
.w	Int	G/S	0
.h	Int	G/S	0
.visible	Bool	G/S	True
.sensitive	Bool	G/S	False
.rule	Int	G/S	0
.focus	Bool	G/S	False
.help	Strg	G/S
.udata	Any	G/S
.title	Strg	G/S
.border	Int	G/S	1

The .title attribute provides a text, which is placed in the top line of the groupbox object.

If a GroupBox is not sensitive, all of its child-objects are insensitive, too (they can not get the keyboard focus). A GroupBox is sensitive by default.

The .border attribute defines the type of the border. The following values are supported:

0: no border
1: thin border
2: thick border
3: shadow border
4: reverse shadow border

StaticText Object

A statictext is used to place text in the dialog.

Class name:: StaticText
Focus :: No
Children :: No

Attributes:

Name Type G/S Default value
.class Strg G StaticText
.x Int G/S 0
.y Int G/S 0
.w Int G/S length of text
.h Int G/S 1
.visible Bool G/S True
.sensitive Bool G/S False
.rule Int G/S 0
.focus Bool G/S False
.help Strg G/S
.udata Any G/S
.text Strg G/S

Name	Type	G/S	Default value
.class	Strg	G	StaticText
.x	Int	G/S	0
.y	Int	G/S	0
.w	Int	G/S	length of text
.h	Int	G/S	1
.visible	Bool	G/S	True
.sensitive	Bool	G/S	False
.rule	Int	G/S	0
.focus	Bool	G/S	False
.help	Strg	G/S
.udata	Any	G/S
.text	Strg	G/S

The .text attribute contains the displayed string.

If the .w attribute is not specified, it will default to the text length set initially.

PushButton Object

A pushbutton is used for making decisions. Dialogs are generally suspended (terminated) and the control returned to the application by pressing a pushbutton.

Class name :: PushButton
Focus :: Yes
Children :: No

Keyboard usage:

Use Spacebar or Return to "execute" a pushbutton.

Attributes:

Name Type G/S Default value
.class Strg G PushButton
.x Int G/S 0
.y Int G/S 0
.w Int G/S length of text
.h Int G/S 1
.visible Bool G/S True
.sensitive Bool G/S True
.rule Int G/S 0
.focus Bool G/S False
.help Strg G/S
.udata Any G/S
.text Strg G/S
.border Int G/S 1

Name	Type	G/S	Default value
.class	Strg	G	PushButton
.x	Int	G/S	0
.y	Int	G/S	0
.w	Int	G/S	length of text
.h	Int	G/S	1
.visible	Bool	G/S	True
.sensitive	Bool	G/S	True
.rule	Int	G/S	0
.focus	Bool	G/S	False
.help	Strg	G/S
.udata	Any	G/S
.text	Strg	G/S
.border	Int	G/S	1

The .text attribute contains the string.

If .w attribute is not specified, it will default to the text length set initially.

If the .h attribute is equal to or greater than 3, the pushbutton is framed.

If the .rule attribute is set to -1, the pushbutton acts as a HELP button. The help subsystem is called with the text defined in the .help attribute as indicator to the helpfile.

CheckBox Object

A checkbox is an object with the activation states "on" or "off".

Class name:: CheckBox
Focus :: Yes
Children :: No

If the object is active, an 'X' will be displayed in front of its text, when working with ASCII DLG.

Keyboard usage:

Use Spacebar to switch the state.

Attributes:

Name Type G/S Default value
.class Strg G CheckBox
.x Int G/S 0
.y Int G/S 0
.w Int G/S length of text
.h Int G/S 1
.visible Bool G/S True
.sensitive Bool G/S True
.rule Int G/S 0
.focus Bool G/S False
.help Strg G/S
.udata Any G/S
.text Strg G/S
.active Bool G/S False

Name	Type	G/S	Default value
.class	Strg	G	CheckBox
.x	Int	G/S	0
.y	Int	G/S	0
.w	Int	G/S	length of text
.h	Int	G/S	1
.visible	Bool	G/S	True
.sensitive	Bool	G/S	True
.rule	Int	G/S	0
.focus	Bool	G/S	False
.help	Strg	G/S
.udata	Any	G/S
.text	Strg	G/S
.active	Bool	G/S	False

The .text attribute contains the string.

If .w attribute is not specified, it will default to the text length set initially.

The .active attribute contains the state of the checkbox.

If the .rule attribute is non-zero and the object state has been changed, the dialog is suspended and the rule value will be returned. If the .rule attribute is -1, the help subsystem will be called instead.

RadioButton Object

A radiobutton is an object with the activation states "on" or "off". In contrast to the checkbox, a radiobutton is used to make a single selection from a group of options. If the object is active and the ASCII DLG system is used, a '*' will be displayed.

Class name:: Radiobutton
Focus :: Yes
Children :: No

Keyboard usage:

The Spacebar is used to set the current radiobutton. All other radiobuttons in the same hierarchy level are switched off.

Attributes:

Name Type G/S Default value
.class Strg G RadioButton
.x Int G/S 0
.y Int G/S 0
.w Int G/S length of text
.h Int G/S 1
.visible Bool G/S True
.sensitive Bool G/S True
.rule Int G/S 0
.focus Bool G/S False
.help Strg G/S
.udata Any G/S
.text Strg G/S
.active Bool G/S False

Name	Type	G/S	Default value
.class	Strg	G	RadioButton
.x	Int	G/S	0
.y	Int	G/S	0
.w	Int	G/S	length of text
.h	Int	G/S	1
.visible	Bool	G/S	True
.sensitive	Bool	G/S	True
.rule	Int	G/S	0
.focus	Bool	G/S	False
.help	Strg	G/S
.udata	Any	G/S
.text	Strg	G/S
.active	Bool	G/S	False

The .text attribute contains the string.

If .w attribute is not specified, it will default to the text length set initially.

The .active attribute contains the state of the radiobutton. If a radiobutton becomes active, all other radiobuttons in the same hierarchy level will become inactive. If you have more than one group of radiobuttons, you have to put each group into a groupbox.

If the .rule attribute is non-zero and the object state has been changed, the dialog is suspended and the rule value will be returned. If the .rule attribute is -1, the help sub-system will be called instead.

EditText Object

An edittext is a text which can be modified interactively. It can be single-line or multi-line. It can be scrolled horizontally, and vertically if multi-line.

Class name:: EditText
Focus :: Yes
Children :: No

Keyboard usage:

Home, Shift + Home, Cursor Left, Cursor Right can be used for editing within a single-line edittext. ,

Additionally, in a multi-line edittext or a listbox object, the following keys can be used: Page Up, Page Down, Cursor Up, Cursor Down.

EditText is set to overwrite mode by default. You may toggle overwrite/insert mode using the INSERT key. The cursor form will change to indicate insert/overwrite mode.

Attributes:

Name Type G/S Default value
.class Strg G EditText
.x Int G/S 0
.y Int G/S 0
.w Int G/S 0
.h Int G/S 1
.visible Bool G/S True
.sensitive Bool G/S True
.rule Int G/S 0
.focus Bool G/S False
.help Strg G/S
.udata Any G/S
.length Int G
.content Strg G/S
.editable Bool G/S True
.multiline Bool G/S False
.border Int G/S 1
.title Strg G/S
.hsb Bool G/S True
.vsb Bool G/S True
.maxchars Int G/S
.maxlines Int G/S
.vheight Int G
.vwidth Int G
.cx Int G/S
.cy Int G/S
.line Strg G/S
.file Strg S
.clear Any S
.add Strg S
.topitem Int S
.writefile Strg S
.ins Strg S
.delln Int S

Name	Type	G/S	Default value
.class	Strg	G	EditText
.x	Int	G/S	0
.y	Int	G/S	0
.w	Int	G/S	0
.h	Int	G/S	1
.visible	Bool	G/S	True
.sensitive	Bool	G/S	True
.rule	Int	G/S	0
.focus	Bool	G/S	False
.help	Strg	G/S
.udata	Any	G/S
.length	Int	G
.content	Strg	G/S
.editable	Bool	G/S	True
.multiline	Bool	G/S	False
.border	Int	G/S	1
.title	Strg	G/S
.hsb	Bool	G/S	True
.vsb	Bool	G/S	True
.maxchars	Int	G/S
.maxlines	Int	G/S
.vheight	Int	G
.vwidth	Int	G
.cx	Int	G/S
.cy	Int	G/S
.line	Strg	G/S
.file	Strg	S
.clear	Any	S
.add	Strg	S
.topitem	Int	S
.writefile	Strg	S
.ins	Strg	S
.delln	Int	S

The .editable attribute specifies if the object may be edited. You can change this attribute at any time.

The EditText object class distinguishes two different modes.

single-line mode
multi-line mode

This is defined by the .multiline attribute.

Single-Line

The following attributes have no effect in single-line mode.

border and title
hsb and vsb (horizontal and vertical scrollbar)
maxlines

The EditText object class provides a single line which can be scrolled horizontally. With ASCII DLG a '<' or '>' mark indicates that the text is scrolled to the left or right side out of view.

Multi-Line

If the .multiline attribute is non-zero, a window with horizontal/vertical scrollbars is displayed.

The .maxlines and .maxchars attributes specifiy how many characters or lines are accepted.

The .hsb and .vsb attributes indicate whether a horizontal or vertical scrollbar should be provided to indicate the position and the relation of the visible part of the text to the whole.

Without an index, the .line attribute will get or set the line as indicated by the cy attribute. If an index is specified, the specified line is get or set. The first line is specified by 1.

The .title attribute provides a text which is placed in the top line of the object.

NOTE: The title attribute is not available with Dialog Manager

The .border attribute specifies whether a border should be placed around the object. The following values are supported:

0: no border
1: thin border
2: thick border
3: shadow border
4: reverse shadow border

The .content attribute contains the text. Lines are separated by a (newline, lf) character. They can also be set or requested using a string array.

The .length attribute returns the number of characters of the text.

The .vwidth and .vheight attributes return the number of lines and the length of the widest line of the text.

The .cx and .cy attributes define the cursor position.

The .line attribute contains the text of the line where the cursor is positioned.

For example:

   DLG SET "Edit.line[12]","Text"

The .clear, .file and .add attributes are not regular attributes. They perform a specific operation on the object:

The .clear attribute accepts any kind of value and clears the whole text.
The .add attribute adds a line of text to the object.
The .file attribute reads the specified file into the object.

NOTE: When the Dialog Manager runtime is running on a remote machine, the file has to be accessible on that machine.

The writefile attribute is of type string. It specifies a file name, where the contents of the EditText are written to.

Using this attribute, you can write your own Text Editor very simply:

	DLG SET "dialog.edit.file","/tmp/text"	! read file
	DLG DO "dialog",R	! handle dialog
	DLG SET "dialog.edit.writefile","/tmp/text.new"	! write file

NOTE: When the Dialog Manager runtime is running on a remote machine, the file will be created on that machine.

If the .rule attribute is non-zero, and if the focus has changed, the dialog is suspended and the rule value is returned.

The .topitem attribute indicates the first visible line in an EditText. When set, the EditText is scrolled appropriately.

NOTE: The topitem attribute is not available with Dialog Manager

The .ins attribute is of type string. It inserts the given string at the current cursor position.

The .delln attribute is of type integer. It deletes the given number of lines starting at the cursor line.

ListBox Object

A listbox contains a dynamic list of text elements from which one text element can be selected.

Class name:: ListBox
Focus :: Yes
Children :: No

Keyboard usage:

The Spacebar is used to select/deselect a listbox entry which is then displayed reversed if selected. You may use the cursor keys to navigate inside the listbox.

Attributes:

Name Type G/S Default value
.class Strg G ListBox
.x Int G/S 0
.y Int G/S 0
.w Int G/S 0
.h Int G/S 0
.visible Bool G/S True
.sensitive Bool G/S True
.rule Int G/S 0
.focus Bool G/S False
.help Strg G/S
.udata Any G/S
.length Int G
.content Strg G/S
.multiline Bool G/S True
.border Int G/S 1
.title Strg G/S
.hsb Bool G/S True
.vsb Bool G/S True
.vheight Int G
.vwidth Int G
.cy Int G/S
.line Strg G/S
.activeline Int G/S
.file Strg S
.clear Any S
.add Strg S
.topitem Int S
.ins Strg S
.delln Int S

Name	Type	G/S	Default value
.class	Strg	G	ListBox
.x	Int	G/S	0
.y	Int	G/S	0
.w	Int	G/S	0
.h	Int	G/S	0
.visible	Bool	G/S	True
.sensitive	Bool	G/S	True
.rule	Int	G/S	0
.focus	Bool	G/S	False
.help	Strg	G/S
.udata	Any	G/S
.length	Int	G
.content	Strg	G/S
.multiline	Bool	G/S	True
.border	Int	G/S	1
.title	Strg	G/S
.hsb	Bool	G/S	True
.vsb	Bool	G/S	True
.vheight	Int	G
.vwidth	Int	G
.cy	Int	G/S
.line	Strg	G/S
.activeline	Int	G/S
.file	Strg	S
.clear	Any	S
.add	Strg	S
.topitem	Int	S
.ins	Strg	S
.delln	Int	S

The ListBox object class allows you to display and select a single value.

The .activeline attribute contains the number of the selected line. A zero means that no line has been selected.

If the .rule attribute is non-zero and the focus attribute has been changed, the dialog is suspended and the rule value is returned. If the rule value is set to -1, the help subsystem will be called instead.

The .topitem attribute indicates the first visible line in a ListBox.

When set, the ListBox is scrolled appropriately.

NOTE: This attribute is not available with Dialog Manager.

The ins attribute is of type string. It inserts the given string before the current line.

NOTE: ListBox always inserts complete lines.

The delln attribute is of type integer. It deletes the given number of lines starting at the cursor line.

The ListBox object type supports an additional index specified for the line attribute.

Without an index, the line attribute will get or set the line as indicated by the cy attribute. If an index is specified, the specified line is got or set. The first line is specified by 1.

For example:

   DLG SET "List.line[12]","Text"

NOTE: This attribute is not available with Dialog Manager

All other attributes are the same as for the EditText object class.

HelpText Object

The helptext object class is used to realize the online help system. It is similar to the EditText object class, but has some special properties.

NOTE: This object is not available with Dialog Manager.

Class name:: HelpText
Focus :: Yes
Children :: No

Attributes:

Name Type G/S Default value
.class Strg G Helptext
.x Int G/S 0
.y Int G/S 0
.w Int G/S 0
.h Int G/S 0
.visible Bool G/S True
.sensitive Bool G/S True
.rule Int G/S 0
.focus Bool G/S False
.help Strg G/S
.udata Any G/S
.border Int G/S 1
.title Strg G/S
.hsb Bool G/S True
.vsb Bool G/S True
.file Strg G/S
.topic Strg G/S
.forw Strg G
.backw Strg G
.link Strg G

Name	Type	G/S	Default value
.class	Strg	G	Helptext
.x	Int	G/S	0
.y	Int	G/S	0
.w	Int	G/S	0
.h	Int	G/S	0
.visible	Bool	G/S	True
.sensitive	Bool	G/S	True
.rule	Int	G/S	0
.focus	Bool	G/S	False
.help	Strg	G/S
.udata	Any	G/S
.border	Int	G/S	1
.title	Strg	G/S
.hsb	Bool	G/S	True
.vsb	Bool	G/S	True
.file	Strg	G/S
.topic	Strg	G/S
.forw	Strg	G
.backw	Strg	G
.link	Strg	G

The .file attribute specifies the help file to use.

The .topic attribute specifies the current help tag.

The .forw and .backw attributes specify the next/previous help tags.

The .link attribute specifies the currently selected text reference.

This object will be maintained automatically by the DLG HELP statement and the help subsystem.

See Discussion on help below.

Eloquence Dialog Manual - 19 DEC 2002