3.29 DM_GetContent

With this function you can query the actual object contents (listbox, poptext, tablefield) from the application in one function call. In doing so, you can query the actual state (contents and selected items) by one access.

DM_Boolean DML_default DM_EXPORT DM_GetContent
(
  DM_ID object,
  DM_Value *firstindex,
  DM_Value *lastindex,
  DM_Content **contentvec,
  DM_UInt *count,
  DM_Options options
)

Parameters

-> DM_ID object

Indicates the object which is to be filled with the new contents.

-> DM_Value *firstindex

Controls which range of the contents is queried by this function. This parameter defines the starting point of the range. On querying the contents of a listbox or a poptext the type in the DM_Value structure is always set to DT_integer and the integer value in the union is assigned the starting value. In a tablefield, however, the type in the DM_Value structure is set to DT_index and the index value in the union is assigned the starting value. Here the row is specified in index.first, the column is specified in index.second.

Note

If this parameter is a NULL pointer, the starting point has the following defaults:

listbox

integer = 1

poptext

integer = 1

tablefield

index.first = 1, index.second = 1

-> DM_Value *lastindex

Controls which range of the contents is queried by this function. This parameter then defines the ending point of the range. On querying the contents of a listbox or a poptext the type in the DM_Value structure is always set to DT_integer and the integer value in the union is assigned the starting value. In a tablefield, however, the type in the DM_Value structure is set to DT_index and the index value in the union is assigned the starting value. Here the row is specified in index.first, the column is specified in index.second.

Note

If this parameter is a NULL pointer, the ending point has the following defaults:

listbox:

integer = object.itemcount

poptext:

integer = object.itemcount

tablefield:

index.first = object.rowcount, index.second = object.colcount

<- DM_Content **contentvec

The pointer to the structure filled by the DM is returned. This structure must not be changed by the application.

<- DM_UInt *count

DM specifies how many items are indexed and therefore the size of the returned structure contentvec is returned.

-> DM_Options options

This parameter controls which information the Dialog Manager is to return. To do so, you have the following possibilities which may also be combined ("or" in bits).

Option

Meaning

DMF_OmitActive

This option specifies that the attribute .active in the vector is not to be provided with values, since the application is not interested in this attribute.

DMF_OmitSensitive

This option specifies that the attribute .sensitive in the vector is not to be provided with values.

DMF_OmitStrings

This option specifies that the attribute .content in the vector is not to be provided with values, since the application is not interested in this attribute. If the strings are not really needed, setting this option will bring along considerable advantages of performance.

DMF_OmitUserData

This option specifies that the attribute .userdata in the vector is not to be provided with values, since the application is not interested in this attribute. If the userdata are not really needed, setting this option will bring along considerable advantages of performance.

Note

The contents vector which you receive in the contentvec parameter is allocated by DM and has to be released by means of DM_FreeContent.

Example

Querying rows 2 to 5 in a listbox.

void DML_default DM_ENTRY GetContent  __1((DM_ID, lb))

{

  int i;

  DM_Integer count;

  DM_Value first, last;

  DM_Content *vec;

 

  first.type = DT_integer;

  first.value.integer = 2;

 

  last.type = DT_integer;

  last.value.integer  = 5;

 

  DM_GetContent(lb, &first, &last, &vec, &count, 0);

 

  for (i = 0; i < count; i++)

  {

    printf("vec[%d].sensitive = %d\n",i, vec[i].sensitive);

    printf("vec[%d].active    = %d\n",i, vec[i].active);

    printf("vec[%d].string    = %s\n",i, vec[i].string);

  }

 

  DM_FreeContent(vec, 0);

}