DdfHyperText
This function defines a hypertext link to another panel, which is equal to a link of reftype=hd. Links to footnotes, launch links and links to external databases are not supported.
Syntax
DdfHyperText(hddf, pszText, pszReference, fReferenceType)
Parameters
- hddf (HDDF) - input
- Handle to DDF returned by DdfInitialize.
- pszText (PCSZ) - input
- Hypertext phrase.
- pszReference (PCSZ) - input
- Pointer to a string containing the link reference.
- The value of this parameter depends on the value of fReferenceType.
- If fReferenceType is REFERENCE_BY_RES, pszReference must contain a pointer to a numeric string containing the res number; otherwise it will default to a res number of zero. Valid values are 1 - 64000; all other values are reserved.
- If fReferenceType is REFERENCE_BY_ID, pszReference must contain a pointer to a string containing the alphanumeric identifier of the destination panel.
- fReferenceType (ULONG) - input
- Reference Type.
- This parameter specifies whether you are linking via a resource identifier (res number) or via an alphanumeric identifier.
- REFERENCE_BY_RES: To link via a resource identifier.
- REFERENCE_BY_ID: To link via an alphanumeric identifier.
Returns
- rc (BOOL) - returns
- Success indicator.
- TRUE: Successful completion.
- FALSE: Error occurred.
Remarks
There is a 3-byte ESC code overhead in the DDF internal buffer for each word in the text buffer. There is a 1-byte ESC code overhead for each blank and for each newline character. If fReferenceType is REFERENCE_BY_ID, then there is a (3-byte + Reference length) ESC code overhead. For a fReferenceType of REFERENCE_BY_RES, the overhead is 5 bytes. Finally, there is a 3-byte ESC code overhead that is required for ending the hypertext link.
Errors
Possible returns from WinGetLastError:
- HMERR_DDF_MEMORY (0x3001): Not enough memory is available.
- HMERR_DDF_REFTYPE (0x3006): The reference type is not valid.
Example Code
Declare:
#define INCL_DDF
#include <os2.h>
HDDF hddf; /* Handle to DDF returned by DdfInitialize. */
PCSZ pszText; /* Hypertext phrase. */
PCSZ pszReference; /* Pointer to a string containing the link reference. */
ULONG fReferenceType; /* Reference Type. */
BOOL rc; /* Success indicator. */
rc = DdfHyperText(hddf, pszText, pszReference,
fReferenceType);
After initializing a DDF buffer with DdfInitialize, the example uses DdfHyperText to create a hypertext link with another resource. 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>
PSZ Text = "This text is a HYPERTEXT message.\n"; /* hypertext string */
PSZ ResID = "1"; /* Resource identifier */
MRESULT WindowProc( HWND hwnd, ULONG ulMsg, MPARAM mp1, MPARAM mp2 )
{
HWND hwndParent;
HWND hwndInstance;
HDDF hDdf; /* DDF handle */
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;
}
/* create hypertext link with resource 1 */
if (!DdfHyperText(hDdf, (PSZ)Text, ResID, REFERENCE_BY_RES))
{
return (MRESULT)FALSE;
}
return (MRESULT)hDdf;
}
return WinDefWindowProc(hwnd, ulMsg, mp1, mp2); /* Default processing for other messages */
}