DdfListItem
This function inserts a definition list entry in the DDF buffer, corresponding to a combination of the `:dt.` (definition term) and `:dd.` (definition define) tags.
Syntax
DdfListItem(hddf, pszTerm, pszDescription)
Parameters
- hddf (HDDF) - input
- Handle to DDF returned by DdfInitialize.
- pszTerm (PCSZ) - input
- Term portion of the definition list entry.
- pszDescription (PCSZ) - input
- Description portion of the definition list entry.
- Note: There is a 3-byte ESC code overhead in the DDF internal buffer for each word in both the term and the description. There is a 1-byte ESC code overhead for each blank and for each new-line character. For each list item, there is a 5-byte ESC code overhead for the margin alignment.
Returns
- rc (BOOL) - returns
- Success indicator.
- TRUE Successful completion
- FALSE Error occurred
Remarks
The handle to the presentation space in which the bit map was created cannot be freed by the application while the panel is displayed.
Note: There is a (3-byte + size of HBITMAP structure) ESC code overhead in the DDF internal buffer for this function. There is a 1-byte ESC code overhead required for the Align flag.
Possible errors include:
- HMERR_DDF_MEMORY (0x3001) Not enough memory is available.
- HMERR_DDF_LIST_UNINITIALIZED (0x3008) No definition list has been initialized by DdfBeginList.
Example Code
Declaration:
#define INCL_DDF #include <os2.h> HDDF hddf; /* Handle to DDF returned by DdfInitialize. */ PCSZ pszTerm; /* Term portion of the definition list entry. */ PCSZ pszDescription; /* Description portion of the definition list entry. */ BOOL rc; /* Success indicator. */ rc = DdfListItem(hddf, pszTerm, pszDescription);
After initializing a DDF buffer with DdfInitialize, this example uses `DdfBeginList` to indicate the beginning of a definition list in the DDF buffer (corresponding to the IPF `dl` tag), then adds list items using `DdfListItem`.
For a more detailed example and discussion of initializing DDF, see the DdfInitialize sample.
#define INCL_WINWINDOWMGR /* General window management */
#define INCL_WINMESSAGEMGR /* Message management */
#define INCL_DDF /* Dynamic Data Facility */
#include <os2.h>
#include <pmhelp.h>
struct _LISTITEM /* definition list */
{
PSZ Term;
PSZ Desc;
} Definition[2] = {{"MVS", "Multiple Virtual System"},
{"VM", "Virtual Machine"}};
MRESULT WindowProc( HWND hwnd, ULONG ulMsg, MPARAM mp1, MPARAM mp2)
{
HWND hwndParent;
HWND hwndInstance;
HDDF hDdf; /* DDF handle */
SHORT i; /* loop index */
switch( ulMsg )
{
case HM_QUERY_DDF_DATA:
/* get the help instance */
hwndParent = WinQueryWindow( hwnd, QW_PARENT );
hwndParent = WinQueryWindow( hwndParent, QW_PARENT );
hwndInstance = (HWND)WinSendMsg( hwndParent, HM_QUERY,
MPFROMSHORT( HMQW_INSTANCE ), NULL );
/* Allocate 1K Buffer (default) */
hDdf = DdfInitialize(
hwndInstance, /* Handle of help instance */
0L, /* Default buffer size */
0L /* Default increment */
);
if (hDdf == NULLHANDLE) /* Check return code */
{
return (MRESULT)FALSE;
}
/* begin definition list */
if (!DdfBeginList(hDdf, 3L, HMBT_ALL, HMLS_SINGLELINE))
{
return (MRESULT)FALSE;
}
/* insert 2 entries into definition list */
for (i=0; i < 2; i++)
{
if (!DdfListItem(hDdf, Definition[i].Term,
Definition[i].Desc))
{
return (MRESULT)FALSE;
}
}
/* terminate definition list */
if (!DdfEndList(hDdf))
{
return (MRESULT)FALSE;
}
return (MRESULT)hDdf;
}
}