3.11 Structures and Definitions for the Formatting of Input

For the formatting of entries in edittexts, a number of structures have been defined which will be introduced in the following chapters. These structures directly or indirectly are all parameters of a format function defined in the application.

3.11.1 Definitions for the Formatting

The different tasks of the format function are available via the definition in the include file IDMuser.h. The individual tasks denote the following:

Task Definition

Task

FMTK_parseformat

The indicated format string is to be parsed and the corresponding structures are to be established.

FMTK_cleanformat

The allocated structures belonging to the format are to be released.

FMTK_create

The format function is informed that the format is used for a valid object. If it is necessary, the structures belonging to the format are allocated and initialized.

FMTK_destroy

The object belonging to format is destroyed. The format-specific structures can thus be released again.

FMTK_setcontent

The format function is informed that a new contents has been set in the object via the program. The format function has to check the contents against the format and to correct the corresponding format information.

FMTK_setselection

The format function is to set the new positions of the cursor and of the beginning of the selection area with regard to the contents string.

FMTK_setmaxchars

The format function is informed that the attribute .maxchars is set for the object. The function has to carry out the relevant actions.

FMTK_formatcontent

The format function is informed that the contents is to be formatted so that the contents in the window system can be set.

FMTK_enter

This task is called if the input field belonging to this format has lost the input focus. The format function can then carry out the necessary actions on contacting the input field.

FMTK_leave

This task is called if the input field belonging to this format has lost the input focus. The format function can carry out the necessary actions on leaving the input field.

FMTK_modify

The task is called if the user has made an input in the text. The function has to process the entry and the corresponding action in the displayed text.

FMTK_keynavigate

The task is called if the user has moved the cursor in the text. The function has to process the navigation and has to carry out the corresponding action in the displayed text.

FMTK_setcursorabs

The task is called if the user has positioned the cursor absolutely in the displayed text. The function then has to carry out the corresponding actions on the internal structures.

3.11.2 Structure DM_FmtContent

By means of this structure the actual contents is saved. This structure also has to be updated on the corresponding calls to the format function.

typedef struct {

  DM_String        string;

  DM_UInt2         size;

  DM_UInt2         length;

  DM_UInt2         curpos;

  DM_UInt2         selpos;

  DM_UInt2         maxchars;

} DM_FmtContent

Meaning of Elements

DM_String string

In this element the actual contents is stored.

DM_UInt2 size

In this element the size of the memory allocated in the element string is stored.

DM_UInt2 length

In this element the actual length of the contents string is stored.

DM_UInt2 curpos

In this element the cursor position is stored in the contents string.

DM_UInt2 selpos

In this element the selection position is stored in the contents string.

DM_UInt2 maxchars

In this element the maximal length of the contents string is stored.

3.11.3 Structure DM_FmtRequest

By means of this structure the data is exchanged between Dialog Mananger and the format function. The union contained in the structure is allocated according to the task.

typedef struct {

  DM_UInt1 task;

  

  union {

  struct { /* FMTK_parseformat */

  DM_UInt1 codepage;

  DM_String formatstr;

  } parseformat;

  

  struct { /* FMTK_setcontent */

  DM_UInt1 codepage;

  DM_String string;

  } setcontent;

  

    struct { /* FMTK_setselection */

      DM_UInt2 contcurpos;

      DM_UInt2 contselpos;

    } setselection;

  

  struct { /* FMTK_setmaxchars */

  DM_UInt2 maxchars;

  } setmaxchars;

  

  struct { /* FMTK_modify */

  DM_String string;

  DM_UInt2 strlength;

  DM_UInt2 dpycurpos;

  DM_UInt2 dpyselpos;

    } modify;

  

  struct { /* FMTK_keynavigate */

  DM_Int2 yoffset;

  DM_Int2 xoffset;

  DM_Boolean movecur;

  DM_Boolean movesel;

    } keynavigate;

  

  struct { /* FMTK_setcursorabs */

  DM_UInt2 dpycurpos;

  DM_UInt2 dpyselpos;

  } setcursorabs;

  

  } targs;

  

  DM_ID object;

  

} DM_FmtRequest;

Meaning of Elements

DM_UInt1 task

In this element the task to be carried out by the format function is stored. The value stored here controls the allocation of the following union.

Structure parseformat for Task FMTK_parseformat

DM_UInt1 codepage

In this element the codepage in which the formatted string is to be output is passed on. The necessary constants are defined in the include file "IDMuser.h" and they all begin with the prefix "CP_".

DM_String formatstr

In this element the actual format string is passed on.

Structure setselection for Task FMTK_setcontent

DM_UInt1 codepage

In this element the codepage in which the formatted string is to be output is passed on. The necessary constants are defined in the include file "IDMuser.h" and they all begin with the prefix "CP_".

DM_String string

In this element the new contents of the object to be formatted is passed on.

Structure setselection for Task FMTK_setselection

DM_UInt2 contcurpos

In this element the actual cursor position with regard to the contents is passed on.

DM_UInt2 contselpos

In this element the actual selection position with regard to the actual contents is passed on.

Structure setmaxchars for Task FMTK_setmaxchars

DM_UInt2 maxchars

In this element the new maximum number of characters is passed on.

Structure modify for Task FMTK_modify

DM_String string

In this element the string without terminating null byte is passed on. The string is to be inserted at the actual cursor position in the present contents.

DM_UInt2 strlength

In this element the length of the string to be inserted is passed on.

DM_UInt2 dpycurpos

In this element the actual cursor position in the displayed string is passed on. At this position the indicated string is to be inserted.

DM_UInt2 dpyselpos

In this element the actual selection position in the displayed string is passed on. If this value equals the value in dpycurpos, the indicated string will be inserted at the corresponding position; if this value does not equal the value in dpycurpos, the string enclosed by dpycurpos and dpyselpos will be replaced by the indicated string.

Structure keynavigate for Task FMTK_keynavigate

DM_Int2 yoffset

This element contains information on the navigation in y-direction. A positive value here means a downward navigation, a negative value denotes an upward navigation.

DM_Int2 xoffset

This element contains information on the navigation in x-direction. A positive value here means a navigation to the right, a negative value denotes a navigation to the left.

DM_Boolean movecur

This element contains information on whether the cursor position is to be changed by a cursor movement (TRUE) or not (FALSE).

DM_Boolean movesel

This element contains information on whether the selection position is to be changed by a cursor movement (TRUE) or not (FALSE).

Structure setcursorabs bei Task FMTK_setcursorabs

DM_UInt2 dpycurpos

In this element the new absolute cursor position with regard to the indicated string is passed on.

DM_UInt2 dpyselpos

In this element the new absolute selection position with regard to the indicated string is passed on.

3.11.4 Structure DM_FmtFormat

This structure contains data which is only accessible to the Dialog Manager-internal format function and which represents internal information about the current format independently of the contents string.

typedef struct {

  DM_UInt2        maxchars;

  char            secretChar;

} DM_FmtFormat;

Meaning of Elements

DM_UInt2 maxchars

In this element the maximum length of the contents string defined by the format string is indicated.

char secretChar

In this element the character used during the covered formatting is saved.

3.11.5 Structure DM_FmtDisplay

This structure is needed to display formatted strings. It informs the window system on the text to be displayed. This structure contains also information on the position in the string at which the cursor is to be set and on the position at which the selection mark is to be set.

typedef struct {

  DM_Boolean         overwritemode : 1;

  DM_UInt1           codepage;

  DM_UInt2           curpos;

  DM_UInt2           selpos;

  DM_UInt2           length;

  DM_UInt2           size;

  DM_String          string;

} DM_FmtDisplay;

Meaning of Elements

DM_Boolean overwritemode

This element contains information on whether the window system is in the overwrite or insert mode.

DM_UInt1 codepage

This element contains information on the codepage of the display string.

DM_UInt2 curpos

In this element the current cursor position in the display string is stored.

DM_UInt2 selpos

In this element the current selection position in the display string is stored.

DM_UInt2 length

In this element the length of the current display string is stored.

DM_UInt2 size

In this element the length of the allocated memory of the element "string" is stored.

DM_String string

In this element the current display string is stored.