5 Special Objects and Object Referencing

In the following chapters you will find the description of how objects can be referenced in the interior of rules. Furthermore, two special objects will be introduced which facilitate the access to objects considerably.

5.1 this

In the this object available in every rule always the current object which has triggered the rule processing will be saved. In doing so, rules can be bound to models which only affect the current instance of the model. This is why normally all rules defined for models access the current object by this and start the relevant actions from there. The model will be accessed directly in the rules only very seldom. The same applies to changes to the rules.

Example

A model of a pushbutton will be defined as follows:

model pushbutton OK {}

The window is to be accessed in a rule. This would look as follows:

!! Rule is defined at the model

on OK select

{

!! Rule accesses the corresponding window

!! via the instance

this.window.visible := false;

}

If the rule accessed the window via the object name, the reaction would be undefined because the instances are usually made visible individually and they would not inherit the visibility from the model any more.

5.2 Object Referencing

There are two ways to reference objects.

By unambiguous names, i.e. the object has a clear name or a full path:

Example

END_Button

MyWindow.OKButton
By parent specification, i.e. relating the object to a parent or child.

Examples
- Object.parent
  
  addresses the parent of the object;
- Object.window
  
  addresses the window in which the object is located.
- Object.groupbox
  
  addresses the groupbox in which the object is located.

The two possibilities of object referencing described above can be used in the event, condition and action lines, i.e., an object can be referred to with an ambiguous name or with relations.

The term "relations" summarizes the possibilities of referencing the objects among each other. The following keywords are available to form a relation:

child[i]

Sets the child "i" of an object (window, groupbox, menubox).
firstchild

Sets the first child of an object.
firstmenu

Indicates the first menu of an object.
groupbox

Indicates the groupbox in which the object is located.
lastchild

Sets the last child of an object.
lastmenu

Indicates the last menu of an object.
menu[i]

Requests child "i" in the menu hierarchy of an object.
parent

Indicates the parent object.
this

Refers to the object which has triggered the relevant event.
window

Indicates the next (parent) window higher in the hierarchy.

Figure 21-3: Reference Options

To refer to a certain object in the hierarchy, several of the keywords named above can be strung together. At the end of such a referencing action, the attributes of the thus found object can be specified.

<Object>::=
  <Objectpath>{<Relation>}[<Attribute>]

<Objectpath>::=
  <Objectidentifier>{.<Objectidentifier>}|
  <Variable>|
  this

Example

{

MainWindow.ytop := this.window.ytop + this.window.height;

}

Here the window "MainWindow" is positioned at the bottom edge of the window in which the object this is located.

Note

Use of relations is appropriate only if the general relationships of objects to each other are already known.

If dynamic objects are generated, this way of object referencing is often the best in order to indicate an object.

Forward Referencing

Apart from referencing already defined objects, it is possible at certain positions to define objects after referencing:

in rules (expressions) and
in attributes of objects.

5.3 null Object

The null object is an object with a special identifier, the IDM ID 0. This object can be used to reset resource attributes. It can be returned by DM_SetValue, and can be used for DM_GetValue, or for function arguments.

The null object is type-independent, which means that there is only one null object for all resources. The null object can be used for all data types which are >= DT_instance. In DM_GetValue, the real type of the null object depends on the attribute type.

Implications

object.text := object.accelerator

False is returned even if no accelerator is linked to the object, since the text is the type DT_text and the accelerator is of the type DT_accel.
object.text := null

Eliminates the text in the object.
Definition:

default pushbutton

{

}

model pushbutton PBM

{

  .fgc RED;

}

pushbutton PB1

{

}

pushbutton PB2

{

  .model PBM;

}

pushbutton PB3

{

  .model PBM;

  .fgc null;

}

In this definition, the pushbuttons PB1 and PB3 do not have a color, PB2 has the foreground color RED.

The assignment explicitly prohibits that PB3 inherits the color from its model.

5.4 Event Object thisevent

Apart from the other special objects setup and this, there is the special object thisevent.

With the help of the keyword thisevent you can obtain information on a current event that has occurred. It returns the (virtual) event which possesses various attributes. These attributes can be read.

Attributes of Event Object thisevent

Attribute	Type	Significance	Valid for
.accelerator	object	accelerator identifier	key
.attribute	attribute	changed attribute	changed
.count	integer	number of timer events that occurred	select in timer
.event_code	integer	code of external event	extevent
.eventcount	integer	number of events	all events
.event[EV]	boolean	true if EV is included	all events
.event[I]	event	type of event I	all events
.index	integer	selected item	select, cut, paste in listbox, poptext, treeview
.index	index	selected field	select, cut, paste in tablefield
.type	enum	kind of object affected by Drag-and-Drop operation	paste
.value	anyvalue	data that has been moved by an Drag-and-Drop operation	paste
.x	integer	x-coordinate of mouse (in pixels)*	select in window, groupbox
.y	integer	y-coordinate of mouse (in pixels)*	select in window, groupbox

* Mouse coordinates are available only in the objects window and groupbox, and are relative to the object to which the event refers.

If an attribute is not valid, it contains void data. The existence of such data can be inquired with the built-in function: typeof.

A rule can be triggered by several events at the same time. All events are contained in the (indexed) attribute .event[I].

The number of events can be requested with .eventcount.

If .event is indexed with an integer value, an event is returned that occurred at the same time.

If .event is indexed with a value of type event, the return value is boolean true if the indexed event is one of the events that occurred.

You can enter an arbitrary event for EV; you can e.g. query if there is a special event: .event[select].