6.2 Class DM_Object

This class hosts all object-oriented methods on IDM objects that are generally valid. It comprises the access methods to attributes, methods and functions as well as the handling of objects (create, delete).

For this purpose, the class remembers the DM_ID of the dialog object in the member.

DM_ID objectId

A newly created instance of this class has not yet set an object. This can happen during the definition with the help of a constructor or during the runtime through the DM_Object::id() method. Only now the subsequent class methods can be successfully applied.

6.2.1 DM_Object() (Constructor)

In addition to the default constructor this allows the direct assignment of the class instance to an IDM object.

DM_Object
(
  DM_ID newId = (DM_ID)0
)

Parameters

-> DM_ID newId

Object ID which is then influenced by further class methods.

Return value

None.

Exceptions

None.

6.2.2 id()

This function sets the mapping to another IDM object.

void id
(
  DM_ID newId
)

Parameters

-> DM_ID newId

Object ID which is then influenced by further class methods.

Return value

None.

Exceptions

None.

See also

Function DM_Object() (Constructor)

6.2.3 id()

This function returns the assignment to an IDM object.

DM_ID id
(
)

Parameters

None.

Return value

ID of the assigned IDM object. This can also be (DM_ID)0.

Exceptions

None.

See also

Function DM_Object() (Constructor)

DM_Object::id()

6.2.4 create()

This function creates a child object which is derived from a Model or a class. The object which is to be created can be a Model or an instance.

DM_ID create
(
  DM_ID      classOrModel,
  DM_Options options = 0
)

Parameters

-> DM_ID classOrModel

Object ID of the Model or a class from DM_Class*.

-> DM_Options options

Permitted values are 0, DMF_CreateModel, DMF_CreateInvisible, DMF_InheritFromModel or a combination of these values.

Return value

A DM_ID != 0 if the object could be created.

Exceptions

None.

See also

Function DM_CreateObject

6.2.5 destroy()

This method destroys an IDM object together with its children and rules. It is also possible to destroy a Model including all its instances.

void destroy
(
  DM_Options options = 0
)

Parameters

-> DM_Options options

Permitted values are 0, DMF_ForceDestroy.

Return value

None.

Exceptions

See also

Function DM_Destroy

6.2.6 parsepath()

With the help of this function the dialog ID of an object can be queried although only the identifier or the path is known. If there is an affiliation (set through DM_Object::id()) to an object this is searched for in its module. If this is not the case all modules and dialogs are searched through.

DM_ID parsepath
(
  DM_ID     root,
  DM_String path
)

Parameters

-> DM_ID root

Object ID of the root from where the path is to be searched for. A 0 here means that the entire module is to be browsed.

-> DM_String path

Identifier or path.

Return value

Searched for object ID or 0 if the object was not found.

Exceptions

None.

See also

Function DM_DialogPathToID

DM_Object::id

6.2.7 query()

A messagebox or a dialogbox is made visible and maintained until the user closes it. One then attains the number of the button which was used to end the query.

DM_Enum query
(
  DM_ID      parentId = 0,
  DM_Options options  = 0
)

Parameters

-> DM_ID parentId

A window in which the messagebox is to appear or 0.

-> DM_Options options

Not used, must be 0.

Return value

Number of the button pushed. Possible values are MB_abort, MB_cancel, MB_ignore, MB_no, MB_retry, MB_yes.

Exceptions

None.

See also

Function DM_QueryBox

6.2.8 start()

This function starts the actual dialog application and, for this reason, registers the necessary resources with the window system and executes the start rule of the dialog. This function is only to be applied to dialogs.

void start
(
  DM_Options options = 0
)

Parameters

-> DM_Options options

Not used, must be 0.

Return value

None.

Exceptions

See also

Function DM_StartDialog

6.2.9 stop()

This function stops a dialog. If it is the last one you will leave the event loop and end the program.

void stop
(
  DM_Options options = 0
)

Parameters

-> DM_Options options

Not used, must be 0.

Return value

None.

Exceptions

See also

Function DM_StopDialog

6.2.10 control()

This function allows for the changing of global settings of the Dialog Manager or the execution of actions.

void control
(
  DM_UInt    action,
  DM_Options options = 0
)

Parameters

-> DM_UInt action

An action which is to be executed or a setting which is to be changed.

-> DM_Options options

Option or new setting value.

The precise use of parameters can be found with the function DM_Control in manual “C Interface - Functions”.

Return value

None.

Exceptions

See also

Function DM_Control

6.2.11 getContent()

This function returns the current contents of an object containing a text field (listbox, poptext or tablefield) with one single call.

DM_Content * getContent
(
  DM_Value  *firstIdx,
  DM_Value  *lastIdx,
  DM_UInt   *count,
  DM_Options options = 0
)

Parameters

-> DM_Value *firstIdx
-> DM_Value *lastIdx

Start and end index when only a part of the content vector is to be queried. Otherwise (DM_Value *)0 can be entered here to indicate the normal start or end point.

<- DM_UInt count

The actual length of the delivered vectors is stored here.

-> DM_Options options

Not used, must be 0.

Return value

Vector with the text contents of the object.

Exceptions

See also

Functions DM_GetContent, DM_SetContent

DM_Object::getContent()

6.2.12 get()

This function queries the value of an object attribute and is applicable with or without an index.

DM_Value get
(
  DM_Attribute attr,
  DM_Value    *index   = &DM_ValueVoid,
  DM_Options   options = 0
)

Parameters

-> DM_Attribute attr

Attribute whose value is to be queried.

-> DM_Value *index

Index value for non- scalar attributes which can be given optionally.

-> DM_Options options

Permitted values are 0, DMF_GetMasterString, DMF_GetLocalString, DMF_GetTextID, DMF_DontFreeLastStrings.

Return value

Value of the attribute.

Exceptions

See also

Functions DM_GetValue, DM_GetValueIndex

DM_Object::get…()

Manuals “Attribute Reference”, “Object Reference”

6.2.13 get…()

The collection of functions queries the attribute value while at the same time securing the return type. An exception is triggered when a wrong type is returned.

DM_Attribute getAttribute(DM_Attribute attr, DM_Value *index = &DM_ValueVoid,
                          DM_Options options = 0);

DM_Boolean getBoolean(DM_Attribute attr, DM_Value *index = &DM_ValueVoid,
                      DM_Options options = 0);

DM_Class getClass(DM_Attribute attr, DM_Value *index = &DM_ValueVoid,
                  DM_Options options = 0);

DM_Enum getEnum(DM_Attribute attr, DM_Value *index = &DM_ValueVoid,
                DM_Options options = 0);

DM_Event getEvent(DM_Attribute attr, DM_Value *index = &DM_ValueVoid,
                  DM_Options options = 0);

DM_ID getId(DM_Attribute attr, DM_Value *index = &DM_ValueVoid,
            DM_Options options = 0);

DM_Integer getInteger(DM_Attribute attr, DM_Value *index = &DM_ValueVoid,
                      DM_Options options = 0);

DM_Index getIndex(DM_Attribute attr, DM_Value *index = &DM_ValueVoid,
                  DM_Options options = 0);

DM_Type getType(DM_Attribute attr, DM_Value *index = &DM_ValueVoid,
                DM_Options options = 0);
 
DM_Method getMethod(DM_Attribute attr, DM_Value *index = &DM_ValueVoid,
                    DM_Options options = 0);

DM_Pointer getPointer(DM_Attribute attr, DM_Value *index = &DM_ValueVoid,
                      DM_Options options = 0);

DM_Scope getScope(DM_Attribute attr, DM_Value *index = &DM_ValueVoid,
                  DM_Options options = 0);

DM_String getString(DM_Attribute attr, DM_Value *index = &DM_ValueVoid,
                    DM_Options options = 0);

Parameters

-> DM_Attribute attr

Attribute whose value is to be queried.

-> DM_Value *index

Index value for non-scalar attributes which can be given optionally.

-> DM_Options options

Permitted values are 0, DMF_GetMasterString, DMF_GetLocalString, DMF_GetTextID, DMF_DontFreeLastStrings.

Return value

Attribute value with the corresponding return type for the function.

Exceptions

See also

Functions DM_GetValue, DM_GetValueIndex

DM_Object::get()

Manuals “Attribute Reference”, “Object Reference”

6.2.14 getVector()

This function allows one to query all or a continuous section of values of a vector attribute in one step.

DM_VectorValue *getVector
(
  DM_Attribute attr,
  DM_Value    *firstIdx = &DM_ValueVoid,
  DM_Value    *lastIdx  = &DM_ValueVoid,
  DM_Options   options  = 0
)

Parameters

-> DM_Attribute attr

Vector attribute whose values are to be queried.

-> DM_Value *firstIdx
-> DM_Value *lastIdx

Index range (inclusive) from which the attribute values are queried. If no entry is given, then the minimum and maximum indexes of the visible field are used.

-> DM_Options options

Permitted values are 0, DMF_GetMasterString, DMF_GetLocalString, DMF_GetTextID, DMF_DontFreeLastStrings.

Return value

Vector containing the attribute values.

Exceptions

See also

Functions DM_FreeVectorValue, DM_GetVectorValue

DM_Interface::freeValues()

6.2.15 setContent()

This function sets the contents of an object in one call, and allows to set either a part of or the entire contents of the listbox, tablefield and treeview.

The given index area must correspond to the size of the content field.

void setContent
(
  DM_Value   *firstIdx,
  DM_Value   *lastIdx,
  DM_Content *content,
  DM_UInt     count,
  DM_Options  options = 0
)

Parameters

-> DM_Value *firstIdx
-> DM_Value *lastIdx

The first and last index for the index range which is to be set. The entry of a NULL pointer brings about the use of one of the resulting minimal or maximal limits from the object content. If a NULL pointer is given as the lastIdx, the new size of the attribute vector is taken from the size of the content field.

-> DM_Content *content

Vector with the values which are to be set.

-> DM_UInt count

Length of the content vector.

-> DM_Options options

Permitted values are 0, DMF_Inhibit, DMF_ShipEvent, DMF_UseUserData, DMF_OmitActive, DMF_OmitStrings, DMF_OmitSensitive.

Return value

None.

Exceptions

See also

Functions DM_GetContent, DM_SetContent

DM_Object::getContent()

6.2.16 set()

This function sets the value of an attribute.

void set
(
  DM_Attribute attr,
  DM_Value    *index,
  DM_Value    *data,
  DM_Options   options = 0
)

void set
(
  DM_Attribute attr,
  DM_Value    *data,
  DM_Options   options = 0
)

Parameters

-> DM_Attribute attr

Attribute whose value is to be set.

-> DM_Value *index

Optional index for setting a single value in a vector attribute or an associative field.

-> DM_Value *data

Value which the attribute is to take on.

-> DM_Options options

Permitted is a combination of the values 0, DMF_Inhibit, DMF_ShipEvent, DMF_XlateString.

Return value

None.

Exceptions

See also

Functions DM_SetValue, DM_SetValueIndex

DM_Object::set…()

Manuals “Attribute Reference”, “Object Reference”

6.2.17 set…()

This collection of functions sets an attribute value. The value is transferred type-dependent. Therefore, the user is not obliged to deal with the DM_Value structure.

void setAttribute(DM_Attribute attr, DM_Value *index = &DM_ValueVoid,
                  DM_Attribute data, DM_Options options = 0);
 
void setBoolean(DM_Attribute attr, DM_Value *index = &DM_ValueVoid,
                DM_Boolean data, DM_Options options = 0);
 
void setClass(DM_Attribute attr, DM_Value *index = &DM_ValueVoid,
              DM_Class data, DM_Options options = 0);
 
void setEnum(DM_Attribute attr, DM_Value *index = &DM_ValueVoid,
             DM_Enum data, DM_Options options = 0);
 
void setEvent(DM_Attribute attr, DM_Value *index = &DM_ValueVoid,
              DM_Event data, DM_Options options = 0);
 
void setId(DM_Attribute attr, DM_Value *index = &DM_ValueVoid,
           DM_ID data, DM_Options options = 0);
 
void setInteger(DM_Attribute attr, DM_Value *index = &DM_ValueVoid,
                DM_Integer data, DM_Options options = 0);
 
void setIndex(DM_Attribute attr, DM_Value *index = &DM_ValueVoid,
              DM_Index data, DM_Options options = 0);
 
void setType(DM_Attribute attr , DM_Value *index = &DM_ValueVoid,
             DM_Type data, DM_Options options = 0);
 
void setMethod(DM_Attribute attr, DM_Value *index = &DM_ValueVoid,
               DM_Method data, DM_Options options = 0);
 
void setPointer(DM_Attribute attr, DM_Value *index = &DM_ValueVoid,
                DM_Pointer data, DM_Options options = 0);
 
void setScope(DM_Attribute attr, DM_Value *index = &DM_ValueVoid,
              DM_Scope data, DM_Options options = 0);
 
void setString(DM_Attribute attr, DM_Value *index = &DM_ValueVoid,
               DM_String data, DM_Options options = 0);

Parameters

-> DM_Attribute attr

List of attributes and objects whose values are to be queried.

-> DM_Value *index

Here an optional index can be given to access the fields.

-> DM_… data

Value which the attribute is to take on.

-> DM_Options options

Permitted is a combination of the values 0, DMF_Inhibit, DMF_ShipEvent, DMF_XlateString.

Return value

None.

Exceptions

See also

Functions DM_SetValue, DM_SetValueIndex

DM_Object::set()

Manuals “Attribute Reference”, “Object Reference”

6.2.18 setVector()

This function simultaneously sets several values with one vector attribute.

void setVector
(
  DM_Attribute    attr,
  DM_Value       *firstIdx,
  DM_Value       *lastIdx,
  DM_VectorValue *values,
  DM_Options      options = 0
)

Parameters

-> DM_Attribute attr

Attribute whose values are to be set.

-> DM_Value *firstIdx
-> DM_Value *lastIdx

The index section, for which the attribute values are to be set, is established with these parameters. This area must correspond with the number of elements in the values vector. If a NULL pointer is entered as a start index, the first index of the attribute is taken. If a NULL pointer is entered for the end index, the size of the vector field results from the content in the values parameter.

-> DM_VectorValue *values

Field of values which is to be set.

-> DM_Options options

Permitted is a combination of the values Werte 0, DMF_Inhibit, DMF_ShipEvent, DMF_XlateString.

Return value

None.

Exceptions

See also

Functions DM_GetVectorValue, DM_SetVectorValue

DM Object::getVector()

6.2.19 reset()

This function resets the value of an attribute to its inherited value.

void reset
(
  DM_Attribute attr,
  DM_Value    *index,
  DM_Options   options = 0
)

Parameters

-> DM_Attribute attr

Attribute whose value is to be reset.

-> DM_Value *index

Index parameter for resetting a single value in a field.

-> DM_Options options

Allows for a combination of the values 0, DMF_Inhibit, DMF_ShipEvent.

Return value

None.

Exceptions

See also

DM_Object::get(), DM_Object::set()

6.2.20 call()

This function calls a rule or a function.

DM_Value call
(
  DM_ID      rule    = 0,
  DM_UInt    argc    = 0,
  DM_Value  *argvec  = &DM_ValueVoid,
  DM_Options options = 0
)

Parameters

-> DM_ID rule

Object ID of the rule or the function which is to be called.

-> DM_UInt argc

Number of parameter values which are provided in the argvec field. The highest permitted value is 16.

-> DM_Value *argvec

The parameter vector to be passed to the call.

-> DM_Options options

Not used, must be 0.

Return value

Return value of the rule or function.

Exceptions

See also

Functions DM_CallFunction, DM_CallMethod, DM_CallRule

DM_Object::callMethod()

6.2.21 callMethod()

This function invokes an object method.

DM_Value callMethod
(
  DM_Method  method,
  DM_UInt    argc,
  DM_Value  *argvec  = (DM_Value *)0,
  DM_Options options = 0
)

Parameters

-> DM_Method method

Method which is to be invoked.

-> DM_UInt argc

Number of the parameter values which are provided in the argvec field. The highest permitted value is 16.

-> DM_Value *argvec

Parameters that are passed to the method.

-> DM_Options options

Not used, must be 0.

Return value

Return value of the method.

Exceptions

See also

Function DM_CallMethod

DM_Object::call()

6.2.22 sendevent()

This function sends an external event to an object. This event is listed in a queue and called up according to the event processing. Likewise, the distribution of parameters is also permitted.

void sendevent
(
  DM_Value  *data,
  DM_UInt    argc    = 0,
  DM_Value  *argv    = &DM_ValueVoid,
  DM_Options options = 0
)

Parameters

-> DM_Value *data

This parameter defines the external event which is to be triggered.

-> DM_UInt argc

Number of parameter values which are provided in the argv field. The highest permitted value is 16.

-> DM_Value *argv

The Parameter the event rule is provided with. They must be identical with the definition of the event rule.

-> DM_Options options

Permitted is a combination of the values 0, DMF_DontTrace and DMF_Synchronous.

Return value

None.

Exceptions

See also

Functions DM_QueueExtEvent, DM_SendEvent

Chapter “External Events” in manual “Rule Language”

6.2.23 getToolkitData()

This function inquires window system specific data of an object

FPTR getToolkitData
(
  DM_Attribute attr
)

Parameters

-> DM_Attribute attr

Window system attribute which is to be queried.

Return value

Depending on the type of the queried attribute the function returns the value converted to FPTR.

Exceptions

None.

See also

Function DM_GetToolkitData

6.2.24 setToolkitData()

This function offers direct access to the window system. Data which are not supported by IDM, but rather by the window system, can be set here.

void setToolkitData
(
  DM_Attribute attr,
  FPTR         value,
  DM_Options   options = 0
)

Parameters

-> DM_Attribute attr

Window system attribute which is to be set.

-> FPTR value

Value which is to be set.

-> DM_Options options

Not used, must be 0.

Return value

None.

Exceptions

See also

Function DM_SetToolkitData