Module wdg - Widgets in Local Memory

The module wdg (widget module) is the program interface to the DataView widgets. A widget in DataView is the highest level object in the dialog object hierarchy. Widgets carry masks. Masks contain fields.

The mask alone is a »dumb« object in DataView, nothing more than a collection of fields with a number of attributes. It is the widget that gives the mask its importance in the entity-relationship-model and assures that the correct join connections are created for queries and that the referential integrity of the data model remains undamaged when the mask content is manipulated. Furthermore, the widget has the function to control the interactive mask handling on the screen (change size and position, iconify, activate, deactivate, etc.) in the central widget event loop. In order to use all the functionality a widget provides for the mask, you must activate the widget via an interactive action (with the exception of the virtual widgets - it can only be activated via a program function). In the dialog flow of your application only one widget can be active at a time. If you delete an active widget, DataView will also delete the corresponding mask.

Attention! Character pointers delivered as return codes from wdg-functions may never be changed in the calling program (copy them before with < strcpy> !), for they directly point to the addresses in the object structure.


Important functions

dal_wdg_set_vir, dal_wdg_ret_vir, dal_wdg_act_vir
Functions for programming with virtual widgets.

dal_wdg_ret_act, dal_wdg_ret_mas
Returns the ident number of the active widget or the ident number of the mask for the widget. Both are elementary functions for being used at mask triggers. You can use them to determine the path to the current mask and its fields.

dal_wdg_ret_typ
Returns the type of the widget from the include file wdgdef.h.

dal_wdg_ret_tbo
Returns the name of the original table of the widget.

dal_wdg_ret_tbj
Returns the name of the join table of the widget.

dal_wdg_ret_buf, dal_wdg_set_buf
Returns or sets the entry in the user-configurable widget buffer.

dal_wdg_chk_wdg
Checks whether a widget exists in local memory.

dal_wdg_ret_fat, dal_wdg_chk_fat, dal_wdg_nxt_son
Returns or checks the parent widget of the child widget in case of combination widgets.


Functions must be used with great care

dal_wdg_cre_wdg, dal_wdg_set...
Functions for creating widgets and for modifying widget attributes. If you create widgets from within a userexit or change widget attributes, wrong entries or absurd references can be the result so that corrupted records are transferred into the data base. Only use this function if the application requires that. Whenever possible, use the standard functions in the module iwf to create widgets. These functions can be relied on.


Widget Attributes

By modifying widget attributes you decide about properties of widgets regarding functionality and interactive handling as long as the widgets exists in local memory. It is also specified which functions you can use to change the attribute.

All widgets in DataView are described by the following attributes:

widget-Id (iwd)
The widget-Id is used to uniquely identify the widget in local memory. DataView automatically creates the widget-Id when you create a widget.

Via the function dal_wdg_ret_act you determine the Id of the active widget. This function is an elementary function for the usage in mask triggers. You need the widget-Id to set up the path to the current mask.

mask Id (idm)
The mask Id localizes the mask that belongs to the widget.

With the function dal_wdg_ret_mas you can determine the mask Id for the widget. This function is an elementary function for the usage in mask triggers. You need the widget-Id to set up the path to the fields of the mask.

widget size (wid, len)
The attributes column width and row length determine the size of the widget on the screen. A widget cannot be bigger than the size of the screen.

With the function dal_wdg_mod_siz you can change the widget size, and with dal_wdg_max_siz maximize it depending on the mask data received.

widget position (col, row)
The Attribute column and row position determine the position of the widget on the screen. The number are related to the upper left corner of the widget frame.

With the function dal_wdg_mov_wdg you can move a widget to a screen position. The function dal_wdg_map_wdg also activates the widget at the new position.

widget buffer (buf)
The widget buffer is a user-configurable memory of the widget and is used to support programming. In the widget buffer you can pass for instance status information or other object-specific information you need during the life-span of the widget. The buffer can have any size and is empty after the widget has been created.

With dal_wdg_set_buf you can write data into the buffer, with dal_wdg_ret_buf you read them.

widget type (type)
The widget type assigns the widget its significance in the entity-relationship model and marks the widget as carrier of a certain mask. The following widget types are defined in the include file wdgdef.h as constants. With the function dal_wdg_ret_typ you can determine the type of a widget.

WDG_TYP_ENT
entity widget - carries the master mask of an entity
WDG_TYP_REF
refine relation widget - carries the refine relation mask of a DataView relation and shows all child elements of the related child entity for a selected parent element of a parent entity and the corresponding relation data.
WDG_TYP_AGG
aggregate relation widget - carries the aggregate relation mask of a DataView relation and shows for a selected child element of a child entity all parent elements of the related parent entity and the corresponding relation data.
WDG_TYP_TYP
type relation widget - carries the type mask and shows the master elements of the entity belonging to the type and the corresponding additional attributes of the related type table.
WDG_TYP_FIL
file widget - carries a mask with one or several fields, whose field contents can be read from a file or from runtime variables and have no relation to the database.

For all widgets pointing to tables in the DataView format all following attributes are specified depending on the widget type. The values these attributes take directly point to the objects in the data model and to the elements in the corresponding data base tables, whose data are to be displayed in the widget mask. If you use the standard functions of the module iwf to create mask widgets, as for instance an entity widget with dal_iwf_lis_ent, DataView will automatically set the attributes. But if you "manually" create widgets with the function dal_wdg_cre_wdg or change widgets with the functions dal_wdg_set_..., you have to specify the attributes as input parameters:

entity-1-Id (en1)
The function dal_wdg_set_en1 sets, dal_wdg_ret_en1 returns the Id.

entity-2-Id (en2)
The function dal_wdg_set_en2 sets, dal_wdg_ret_en2 returns the Id.

relation Id (rel)
The function dal_wdg_set_rel sets, dal_wdg_ret_rel returns the Id.

parent element Id (ide)
The function dal_wdg_set_ide sets, dal_wdg_ret_ide returns the Id.

parent element name (elm)
The function dal_wdg_set_elm sets, dal_wdg_ret_elm returns the name.

original table name (origin table) (tbo)
The function dal_wdg_set_tbo sets, dal_wdg_ret_tbo returns the name.

join-table name (join table) (tbj)
The function dal_wdg_set_tbj sets, dal_wdg_ret_tbj returns the name.

Two invisible system internal ident number fields in the mask of the widget are in direct connection with these type dependent attributes. They are automatically created by DataView and set according to the widget type. They do not appear in the mask. For them, the following rule applies:

The table shows the assignment of the type dependent attributes mentioned above and the system internal invisible ident number fields:

Widget Type from wdgdef.h Attribute Value
entity Widgt
WDG_TYP_ENT
en1 C_ID of the entity from T_ENTITY
en2 C_ID of the entity from T_ENTITY
rel 0
ide 0
elm 0
tbo name of the master table for the entity from T_TABLE
tbj name of the master table for the entity from T_TABLE
idn1 C_ID of the record in the master table
idn2 C_ID of the record in the master table
refine relation
widget of an n:m
relation,
WDG_TYP_REF
en1 C_ID of the parent entity (entity-1) from T_ENTITY
en2 C_ID of the child entity (entity-2) from T_ENTITY
rel C_ID of the relation from T_ENT_REL
ide C_ID of the parent element of the relation in the master table of the parent entity (entity-1)
elm name of the parent element of the relation in the master table of the parent entity (entity-1)
tbo name of the relation table from T_TABLE
tbj name of the master table of the child entity from T_TABLE
idn1 C_ID of the records in the relation table
idn2 C_ID of the records in the master table of the child entity
aggregate relation
widget of an n:m
relation,
WDG_TYP_AGG
en1 C_ID of the child entity (entity-2) from T_ENTITY
en2 C_ID of the parent entity (entity-1) from T_ENTITY
rel C_ID the relation from T_ENT_REL
ide C_ID of the child element of the relation in the master table of the child entity (entity-2)
elm name of the child element of the relation in the master table of the child entity (entity-2)
tbo name of the relation table from T_TABLE
tbj name of the master table the parent entity from T_TABLE
idn1 C_ID of the record in the relation table
idn2 C_ID of the record in the master table of the parent entity
relation widget
of an 1:n relation
to the NULL entity,
WDG_TYP_REF
en1 C_ID of the parent entity (entity-1) from T_ENTITY
en2 C_ID of the NULL entity (entity-2) from T_ENTITY
rel C_ID of the relation from T_ENT_TYP
ide C_ID of the parent element of the relation in the master table of the parent entity (entity-1)
elm name of the parent element of the relation in the master table of the parent entity (entity-1)
tbo name of the relation table from T_TABLE
tbj 0
idn1 C_ID of the record in the relation table
idn2 0
type-relation
widget,
WDG_TYP_TYP
en1 C_ID of the entity from T_ENTITY
en2 C_ID of the entity from T_ENTITY
rel C_ID of the type relation from T_ENT_TYP
ide 0
elm 0
tbo name of the type table from T_TABLE
tbj name of the master table of the entity from T_TABLE
idn1 C_ID of the record in the type table
idn2 C_ID of the record in the master table of the entity

For widgets referring to tables in a foreign format the attributes en1 to tbj in Table 0-2 are unassigned. For compatibility reasons the widget masks also contains the two invisible system internal ident number fields idn1 and idn2 in these cases, too. However, they are unassigned.

In the trash-basket widget the first two system internal ident number fields of the mask of the trash-basket widget, idn1 and idn2, always contain the same record ident number like the first two fields of the mask from which the record has been deleted.

For widgets displaying data from linked tables DataView automatically supports all operations like read, write, or delete, without expecting you to apply userexits or special additional definitions. The valid widget attributes already mentioned are not changed when defining fields from linked tables.

Combination widgets consisting of a combination of header form and any number of sub-lists, are interactively treated as a unit in DataView, but from the programmer's point of view they are single components. Thus there is no special widget type for combination widgets. For the widget of the header form the master list type defined for the relation applies, while for the sub-lists the corresponding relation list type for DataView relations or the master list type for constraints are used.

For combination widgets the function dal_wdg_ret_fat returns the Id of the parent widget, dal_wdg_chk_fat checks for existing child widgets, and dal_wdg_nxt_son returns the Id of the next child widget from the widget stack of the combination widget. The last function is only useful if you placed several sub-lists in the header form.


Widget States

By modifying widget states you decide about properties of widgets regarding functionality and interactive handling as long as the widgets exists in local memory. It is also specified which functions you can use to change the state.

In DataView, a widget can be set into different states. This is your method to release or restrict the special functionality at the widget. The widget states can be controlled using the widget mode flags or via entering the widget event loop. With regard to the widget states DataView knows the following widgets:

event widget (widget event mode active):
The event widget is a widget which can be interactively activated or deactivated via cursor or mouse actions.

If the widget is active, all the functionality at the widget is available to you (change size and position , iconify, deactivate, open widget menus, etc.). an active widget is represented on the screen with a dark widget frame.

If the widget is inactive, you can only activate it. An inactive widget is displayed with a bright widget frame on the screen. The data in the widget remain visible in the inactive widget.

An event widget is created after calling the widget via the first entrance into the widget event loop with the function dal_evt_get_nxt. The widget will then be active immediately. Virtual widgets can only be activated with the function dal_wdg_act_vir.

recursive widget (widget event mode inactive):
The recursive widget is a so-called »obligatory widget«. You can edit the widget and its data. It is not possible to leave the widget via cursor or mouse actions or switch into another widget. You only leave the recursive widget when you finish the widget action.

You create a recursive widget entering a widget sub-event loop (second or n-th call of the function dal_evt_get_nxt)

virtual widget (widget virtual mode active):
A virtual widget is a widget which is invisible on the screen. You can apply it to use the widget functionality installed in DataView for background batch operation. An interactive dialog on the screen is not possible.

The virtual debug mode allows you to trace virtual widgets on the screen during program development.

You create a virtual widget before calling the widget by setting widget virtual mode with the function dal_wdg_set_vir. Virtual widgets can only be activated with the function dal_wdg_act_vir.

With the help of the function dal_wdg_ret_mod you can detect the current widget state for the active widget or the widget ident number.


Widget Trigger

Using the function dal_wdg_fnc_drp you can now install a trigger at the DRAG & DROP function. In this way, the dialog flow of DataView can be controlled when DRAG & DROP operations are used. The trigger responds only after the mouse button has been released at the target position after a DRAG & a DROP operation.