Index

C/C++ Functions

txTextMakeViaPowerDocAndStream

DT_SLONG txTextMakeViaPowerDocAndStream(DT_TXDOC text_doc, DT_PDDOC power_doc, DT_ID_UBYTE text_type, const DT_STREAM_DESC* text_sd, DT_SWORD unicode_flags, const DT_TX_TEXTFLOW_AREA* area, const DT_TX_DEFAULT_ATTRIBS* attribs, const DT_STREAM_DESC* fontmap_sd, DT_SWORD flags)

Short Description: Make text document - via PowerDoc and stream

The txTextMakeViaPowerDocAndStream function embeds a Unicode text flow into an existing Power Engine document (i.e. a document created using D-Type Power Engine and its API functions) by reading a plain text file stored in a stream. This function optionally performs Unicode's implicit bidirectional reordering algorithm (BiDi) and auto-detects Unicode scripts (such as Latin, Arabic, Thai etc.) so that complex scripts can be shaped properly.

This function must be called once per text document instance, and only after a successful call to txTextIni. Applications that wish to embed another Unicode text flow using this function must first destroy the existing text document instance by calling txTextExt and then create a new one by calling txTextIni.

Note: txTextMakeViaPowerDocAndStream is an advanced and specialized function. Its primary users are developers who wish to use D-Type Unicode Text Module to embed text flows into their D-Type Power Engine documents. In this use case scenario, the associated text document instance (text_doc) is usually short-lived while the Power Engine document (power_doc) is long-lived. With that in mind, the txTextMakeViaPowerDocAndStream function is rather different from, and should not be confused with txTextMakeViaStream, txTextMakeViaBuffer and txTextMakeViaPowerDoc.

Parameters

ParameterDescription

text_doc

Handle of the associated text document instance.

power_doc

See txTextMakeViaPowerDoc.

text_type

See txTextMakeViaStream.

text_sd

See txTextMakeViaStream.

unicode_flags

See txTextMakeViaStream.

area

See txTextMakeViaStream.

attribs

/* Text default parameters */
typedef struct
{
   const DT_CHAR* RGBT;
   const DT_CHAR* FontWidth;
   const DT_CHAR* FontHeight;
   const DT_CHAR* SkewHor;
   const DT_CHAR* SkewVer;
   const DT_CHAR* SpacingRow;
   const DT_CHAR* SpacingLetter;
   const DT_CHAR* Align;
   const DT_CHAR* AlignEnd;
   const DT_CHAR* Hinting;
   const DT_CHAR* FontIndex;
   const DT_CHAR* Reserved;

} DT_TX_DEFAULT_ATTRIBS;

fontmap_sd

See txTextMakeViaStream.

flags

A set of bit values that control the behavior of this function.

  • Bit 0: If set (1), the function will embed a Unicode text flow as a list of linked Text Fragments, then create its root Rich Text Area PowerDoc object along with the corresponding PowerDoc image in the supplied Power Engine document. The Rich Text Area object created in this way will not have the pdTextAreaDw, pdTextAreaDh or any other applicable PowerDoc property. The user can and should add them later, as necessary. Similarly, the corresponding PowerDoc image will always be located at coordinates X=0 and Y=0 of page 0 in the document. The user can set these later. If this bit is not set (0), then the function will only embed a Unicode text flow as a list of linked Text Fragments. In this case, all other required PowerDoc objects and/or images must be added manually by the user.
  • All remaining bits are reserved for future use and must be set to 0.

Return Value

If the Unicode text flow was embedded successfully, the return value depends on the flags parameter described above:

If the text flow could not be embedded successfully, the function returns -1.

Comments

See txTextMakeViaStream.

Note 1

See How To Use D-Type Streams And Stream Macros.

Note 2

See our notes regarding file based streams.

Note 3

See the txMakeCachedFontmap function.

Related Functions

txTextMakeViaStream, txTextMakeViaPowerDoc

 

Index