DdfBeginList
This function begins a definition list in the DDF buffer; it corresponds to the :dl. (definition list) tag.
Syntax
DdfBeginList(hddf, ulWidthDT, fBreakType, fSpacing)
Parameters
- hddf (HDDF) - input
- Handle to DDF returned by DdfInitialize.
- ulWidthDT (ULONG) - input
- Width of the definition term.
- fBreakType (ULONG) - input
- Type of line break to use.
- The following constants may be specified:
- HMBT_ALL: Start all definition descriptions on the next line, regardless of the actual lengths of definition terms.
- HMBT_FIT: Start definition description on the next line only when the definition term is longer than the width specified.
- HMBT_NONE: Do not start the definition description on the next line, even when the definition term is longer than the width specified.
- fSpacing (ULONG) - input
- Spacing between definitions.
- Only the following constants may be specified:
- HMLS_SINGLELINE: Do not insert a blank line between each definition description and the next definition term.
- HMLS_DOUBLELINE: Insert a blank line between each definition description and the next definition term.
Returns
- rc (BOOL) - returns
- Success indicator.
- TRUE indicates successful completion.
- FALSE indicates an error occurred.
Remarks
Once this function has been called, use of any DDF function other than DdfListItem, DdfSetColor, and DdfEndList may produce unpredictable results.
Errors
Possible returns from WinGetLastError:
- HMERR_DDF_MEMORY (0x3001): Not enough memory is available.
- HMERR_DDF_LIST_UNCLOSED (0x3007): An attempt was made to nest a list.
- HMERR_DDF_LIST_BREAKTYPE (0x3009): The value of BreakType is not valid.
- HMERR_DDF_LIST_SPACING (0x300A): The value for Spacing is not valid.
Example Code
Declare:
#define INCL_DDF #include <os2.h> HDDF hddf; /* Handle to DDF returned by DdfInitialize. */ ULONG ulWidthDT; /* Width of the definition term. */ ULONG fBreakType; /* Type of line break to use. */ ULONG fSpacing; /* Spacing between definitions. */ BOOL rc; /* Success indicator. */ rc = DdfBeginList(hddf, ulWidthDT, fBreakType, fSpacing);
This example uses DdfBeginList to indicate the beginning of a definition list in the DDF buffer after initializing a DDF buffer with DdfInitialize.
#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;
}
}