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:
- field idn1 -> record-Id of the record in the original table
- field idn2 -> record-Id of the record in the join table
The table shows the assignment of the type dependent attributes mentioned above and the system internal invisible ident number fields:
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.