Format Functions

5.9 Format Functions

The format functions have to be defined in the application as follows:

DM_Boolean DML_default DM_CALLBACK Functionname
(
  DM_FmtRequest far * req,
  DM_FmtFormat far * fmt,
  FPTR *fmtPriv,
  DM_FmtContent far * cont,
  FPTR *contPriv,
  DM_FmtDisplay far * dpy
)

The format function is defined in the dialog script as follows:

function formatfunc Functionname;

Parameters

DM_FmtRequest far * req

This parameter passes on the actual task which is taken on by the format function. The task in the element "task" is transferred to this structure.

Task	Description
FMTK_parseformat	In this task the indicated format string is to be parsed and structures belonging to the format are to be initialized.
FMTK_cleanformat	This task is to release the filed private format information because the format is no longer needed.
FMTK_create	This task is to carry out the initialization of the private data for the actual contents string so that the contents string can be accessed after this task.
FMTK_destroy	This task is to release the private data filed in contPriv.
FMTK_setcontent	A new contents string is set. This contents string has to be transferred to cont. If required, the data has to be updated in contPriv. If a display structure is available the new contents string has to be formatted and the result is filed in the display structure.
FMTK_setselection	New positions of the cursor and of the beginning of a selection area with regard to the contents string are set. These values have to be transferred to cont. If required, the data in contPriv have to be updated. If dpy is available, the corresponding positions with regard to the formatted representation string have to be updated.
FMTK_setmaxchars	A new maximum length of the contents string is set. This has to be transferred to cont. If required, the contents string and the data in have to be updated in contPriv. If dpy is available, the new contents string has to be formatted and the result has to be filed in dpy.
FMTK_formatcontent	If the display structure is available, the new contents string has to be formatted and the result has to be filed in this structure.
FMTK_enter	This task will be called, if the editable text using this format receives the focus. The task does not have to carry out special tasks.
FMTK_leave	This task will be called, if the editable text using this format loses the focus. The task does not have to carry out special tasks.
FMTK_modify	This task is called, if the formatted display string is to be modified in the display structure. The desired modification has to be carried out so that the new formatting results in the modified display string. The display string has also to be modified accordingly.
FMTK_keynavigate	This task is called, if the positions in the representation string are to be changed relatively to the previous positions. The relevant positions in the contents string in "cont" are to be calculated so that they correspond to the new positions in the display string. The new positions in the display string have to be converted in the new positions in the contents string and have then to be filed in the display structure.
FMTK_setcursorabs	This task is called, if the positions in the display string are set to a new value. The relevant positions in the contents string are to be calculated so that they correspond to the new positions in the display string. The new positions in the display string have to be converted and be filed in the display structure.

DM_FmtFormat far * fmt

In this parameter a pointer on format-specific information is passed on.

FPTR *fmtPriv

In this parameter the format function can file format-specific, private data. This data is only known to the application and is thus not considered by Dialog Manager.

DM_FmtContent far * cont

In this parameter a pointer is transferred to a structure in which the actual contents of the field is to be saved. The relevant elements always have to be updated.

FPTR *contPriv

In this parameter contents-specific, private data can be filed by the format function. The contents of this data is only known to the application and is thus not considered by the Dialog Manager.

DM_FmtDisplay far * dpy

In this parameter a pointer is transferred to the structure in which the actual display information is saved. If required, this structure always has to be updated in order for the affiliated edittext in the window system to be displayed correctly.

Example

/* function for special handling of edittext user input */

function formatfunc My_Formatter ();

/* format resource using a format function */

format MyFormat "NN.NN.NN" My_Formatter;

The function is assigned to an input field in the following way:

/* here the date can be entered */

/* the single entered keys are checked by the formatfunc */

child edittext E1

{

.width 10;

.xleft 10;

.ytop 1;

.format MyFormat;

}

This function is realized in C as follows:

DM_Boolean DML_default DM_CALLBACK My_Formatter __6(

(DM_FmtRequest far *, req),

(DM_FmtFormat far *, fmt),

(FPTR *, fmtPriv),

(DM_FmtContent far *, cont),

(FPTR *, contPriv),

(DM_FmtDisplay far *, dpy))

{

DM_Boolean retval;

switch (req->task)

{

** implement a format for inserting a date

** like 'dd.mm.yy'

** there should be some more code for correct handling

** (especially when 'delete' or 'backspace' is pressed)

** if the input is less than max

** the input is ok and can be processed

** by the DefaultFormatter

case FMTK_modify:

{

char max = GetMax(dpy);

if ((!req->targs.modify.strlength

&& (dpy->curpos == dpy->length))

|| ((req->targs.modify.strlength == 1)

&& (req->targs.modify.string[0] >= '0')

&& (req->targs.modify.string[0] <= max)))

{

retval = DM_FmtDefaultProc(req, fmt,

(DM_FmtFormatDef **) (FPTR) fmtPriv, cont,

(DM_FmtContentDef **) (FPTR) contPriv, dpy);

}

else

retval = FALSE;

}

break;

default:

** if no special handling is neccessary

** use standard formatter

retval = DM_FmtDefaultProc(req, fmt,

(DM_FmtFormatDef **) (FPTR) fmtPriv,

cont, (DM_FmtContentDef **) (FPTR) contPriv, dpy);

break;

}

return (retval);

}