CompoundTextAddTextExt

Function : Compound Text

CompoundTextAddTextExt - Writes text to a CompoundText context.

#include <easycd.h>
STATUS LNPUBLIC CompoundTextAddTextExt(

    DHANDLE  hCompound,
    DWORD  dwStyleID,
    FONTID  FontID,
    char far *pchText,
    DWORD  dwTextLen,
    char far *pszLineDelim,
    DWORD  dwFlags,
    NLS_PINFO  pInfo);

Description :

NOTE: This function replaces the deprecated function CompoundTextAddText.

This routine writes text to a CompoundText context.  This accepts text

from a buffer or from a file. The text may contain newline characters and/or other line delimiters.

This routine is most appropriate when you do not know the format of the text you want written to the CompoundText context (for example, you read the text from a file and want to turn it into CD records). The text is parsed into lines and/or paragraphs before it is written to the context.

CompoundTextAddTextExt can convert up to approximately 5 megabytes of text.
Each line of text, identified by a line delimiter, is stored as one CDTEXT record. If a line of text is longer than approximately 16k with no line delimiter, a new CDTEXT record is written. The creation of CDPARAGRAPH records is controlled by the COMP_PARA_LINE and COMP_PARA_BLANK_LINE flags; see COMP_xxx for a description of these flags. A CDPARAGRAPH record can only be inserted when a line delimiter is found. If the input text contains more than 64k of text with no line delimiter, the paragraph generated by CompoundTextAddTextExt cannot be read by the Notes editor.

If the pInfo parameter is specified, the text will be translated (imported) into Domino format (LMBCS) using the specified character set. Specify NULL for pInfo if the text is in LMBCS format already.

To specify a character set, call NLS_load_charset first, specifying the file name of the appropriate character set. NLS_load_charset returns a pointer to use as the pInfo parameter value.

Parameters : Input : hCompound - Handle of the CompoundText context.

dwStyleID - CompoundText style ID as defined by a previous call to CompoundTextDefineStyle, or STYLE_ID_SAMEASPREV to use the same style as the last call.

FontID - Specifies the FONTID.

pchText - When the COMP_FROM_FILE flag is not specified, this parameter points to a buffer in memory containing the text. When the COMP_FROM_FILE flag is specified, this parameter points to a null-terminated file pathname.

dwTextLen - Length of text contained in the buffer when the COMP_FROM_FILE flag is not specified. This parameter is ignored when the COMP_FROM_FILE flag is specified.

pszLineDelim - Pointer to a null-terminated string of line delimiter(s).

A text line ends at the matching delimiter string location, or at the end of the text buffer/file if not match is encountered.

When the "special" line delimiter "\r\n" is specified, CompoundTextAddTextExt will correctly handle text lines delimited by "\n", "\r", "\n\r" and "\r\n". This provides platform independence.

When a multi character line delimeter is specified other than "\r\n" (such as "\v\f\r\n"), the routine will break the line only if the exact character sequence is found in the text string.

When a single character line delimiter is specified (such as "\n"), the routine is able to make use of faster LNL routines to break the text into lines.

dwFlags - (Optional) Compound text conversion flags - may be 0 or a combination of flags; see COMP_xxx for compound text flags.

pInfo - (Optional) Pointer to an NLS_INFO structure.

Output : (routine) - Return status from this call:

NOERROR - Successfully added text to compound text context.

ERR_xxx - Errors returned by lower level functions. Call to OSLoadString to translate the error to a string for display.

Sample Usage :

COMPOUNDSTYLE  Style;
STATUS         Status;
DHANDLE         hCompound;
DWORD          dwNormalStyle;
char  *pszTree = "They cannot see the forest \nfor the trees.";
char  *pszDogs = "It was for \nthe dogs.";


Status = CompoundTextCreate(NULLHANDLE, NULL, &hCompound);
if (Status != NOERROR)
 return Status;

CompoundTextInitStyle(&Style);
Status = CompoundTextDefineStyle( hCompound
                                  "Normal",
                                  &Style,
                                  &dwNormalStyle);

Status = CompoundTextAddTextExt(hCompound,
                                dwNormalStyle,
                                DEFAULT_FONT_ID,
                                pszTree,
                                (DWORD)strlen(pszTree),
                                "\r\n",
                                COMP_PRESERVE_LINES,
                                NULL);
if (Status != NOERROR)
{
CompoundTextDiscard(hCompound);
return Status;
}

Status = CompoundTextAddTextExt(hCompound,
                                dwNormalStyle,
                                DEFAULT_FONT_ID,
                                pszDogs,
                                (DWORD)strlen(pszDogs),
                                "\r\n",
                                COMP_PRESERVE_LINES,
                                NULL);
if (Status != NOERROR)
{
CompoundTextDiscard(hCompound);
return Status;
}
...