The txTextMakeViaStream function builds a Unicode text document 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 rebuild their Unicode text using this function must first destroy the existing text document instance by calling txTextExt and then create a new one by calling txTextIni.
Parameter | Description |
---|---|
text_doc |
Handle of the associated text document instance. |
engine |
Handle of the previously created D-Type Power Engine instance. See the pdEngineIniViaStream function for details on how to initialize D-Type Power Engine. |
text_type |
Encoding of the plain text file. Can be one of the following: TX_AUTO 0 /* Auto-detect */ TX_ANSI 1 /* ANSI */ TX_UCS2_LE 2 /* UCS-2 Little Endian */ TX_UCS2_BE 3 /* UCS-2 Big Endian */ TX_UTF8 4 /* UTF-8 */ TX_UCS4_LE 5 /* UCS-4 Little Endian */ TX_UCS4_BE 6 /* UCS-4 Big Endian */ TX_UTF16_LE 7 /* UTF-16 Little Endian */ TX_UTF16_BE 8 /* UTF-16 Big Endian */ TX_UTF32_LE 9 /* UTF-32 Little Endian */ TX_UTF32_BE 10 /* UTF-32 Big Endian */ When text_type = TX_AUTO, the function attempts to detect the encoding of the plain text file based on its first few bytes. When the first two bytes are 0xFEFF, the text file is assumed to be UTF-16 Big Endian. When the first two bytes are 0xFFFE, the text file is assumed to be UTF-16 Little Endian. When the first three bytes are 0xEFBBBF, the text file is assumed to be UTF-8. If none of the above bytes sequences are present at the beginning of the file, the text file is assumed to be ANSI. When text_type is set to TX_ANSI, TX_UCS2_LE, TX_UCS2_BE, TX_UTF8, TX_UCS4_LE, TX_UCS4_BE, TX_UTF16_LE, TX_UTF16_BE, TX_UTF32_LE or TX_UTF32_BE, the encoding is known and, therefore, no special bytes sequences should be present at the beginning of the plain text file. As indicated above, TX_ANSI is used for ANSI, TX_UCS2_LE for UCS-2 Little Endian, TX_UCS2_BE for UCS-2 Big Endian, TX_UTF8 for UTF-8, TX_UCS4_LE for UCS-4 Little Endian, TX_UCS4_BE for UCS-4 Big Endian, TX_UTF16_LE for UTF-16 Little Endian, TX_UTF16_BE for UTF-16 Big Endian, TX_UTF32_LE for UTF-32 Little Endian and TX_UTF32_BE for UTF-32 Big Endian encoding. |
text_sd |
A valid pointer to the DT_STREAM_DESC structure which supplies the location of the plain text file that is being read (e.g. file on disk, file in memory, file on a remote server). |
unicode_flags |
Unicode flags to specify how to process the text. Can be a combination of the following values: TX_IMPORT_UNICODE_BIDI 1 /* Apply Unicode Bidirectional Algorithm */ TX_IMPORT_UNICODE_SCRIPT 2 /* Auto-detect Unicode scripts and use complex shapings */ TX_IMPORT_OPENTYPE_CJK_VALT 4 /* Assume text is used in vertical layout and apply vertical OpenType glyph forms to 'hani' and 'kana' scripts (when available in font) */ TX_IMPORT_UNICODE_OPTIMIZE 16 /* Optimize Unicode text */ TX_IMPORT_UNICODE_COMPRESS 32 /* Compress Unicode text */ Note that unicode_flags is a bitmask. Use the OR ("|") operator to combine several bit values. Alternatively, use one of the following predefined values: TX_IMPORT_BASIC 0 /* No special processing */ TX_IMPORT_FULL 3 /* Same as (TX_IMPORT_UNICODE_BIDI | TX_IMPORT_UNICODE_SCRIPT) */ TX_IMPORT_FULL_COMPACT 51 /* Same as (TX_IMPORT_UNICODE_BIDI | TX_IMPORT_UNICODE_SCRIPT | TX_IMPORT_UNICODE_OPTIMIZE | TX_IMPORT_UNICODE_COMPRESS) */ |
area |
Either DV_NULL or a valid pointer to the DT_TX_TEXTFLOW_AREA structure that supplies the attributes of the textflow area to hold the text. If DV_NULL, the following default textflow area will be used: DT_TX_TEXTFLOW_AREA default_area; default_area.X = 0; default_area.Y = 0; default_area.W = 1000; default_area.H = 1000; default_area.Type = TX_RECT; default_area.RowType = TX_MATHROW; default_area.WrapType = 0; default_area.GlobalDirection = TX_DIR_ROW_LR_TB; default_area.TargetDeviceID = TX_LAY_DEVICE_B; default_area.TransformAndExtras = TX_TM_NULL; default_area.TransformArray = DV_NULL; The texflow area created by this function is always placed on the first page (page with index 0) of the text document. |
text_attribs |
Either DV_NULL or an array of DT_TX_ATTRIBS structures that supply initial text styling/formatting attributes. If DV_NULL, the following default array of styling/formatting attributes will be used: const DT_TX_ATTRIBS default_attributes[] = { {TX_ATTR_FONT_WIDTH, "36" /* in document units */ }, {TX_ATTR_FONT_HEIGHT, "36" /* in document units */ }, {TX_ATTR_SPACING_ROW, "10" /* in document units */ }, {TX_ATTR_SPACING_LETTER, "0" /* in document units */ }, {TX_ATTR_KERNING, "1" /* kerning is on */ }, {TX_ATTR_ALING, "0" /* left justified */ }, {TX_ATTR_ALIGNEND, "0" /* left justified */ }, {TX_ATTR_BODY_RGBT, "00000000"}, {TX_ATTR_END, "" /* mandatory end-of-array */ } }; |
fontmap_sd |
A valid pointer to the DT_STREAM_DESC structure which supplies the location of the font map file. The font map file tells the function what fonts to use for different Unicode scripts. Typically, this is fontmap.inf. When appropriate, your application can provide its own (i.e. altered) version of the fontmap.inf file. Additionally, your application can create a cached font map file using the txMakeCachedFontmap function and pass it here. This will make the txTextMakeViaStream function run noticeably faster. For details, see the txMakeCachedFontmap function. For best performance, the font map file should reside in memory. The DT_STREAM_DESC structure then describes a memory based stream. Memory based streams can be processed more quickly than file based streams. See the DT_STREAM_MEMORY macro and the How To Use D-Type Streams And Stream Macros section for more information on memory based streams. |
If the Unicode text document was built successfully, the return value will be the number of its characters. Otherwise, the function returns -1.
Before this function can be used it is necessary to initialize D-Type Power Engine by calling the pdEngineIniViaStream function. This is usually done only once, at the beginning of the application's initialization routine. For example:
DT_STREAM_FILE(sd, "dtype.inf"); if (pdEngineIniViaStream(&Engine, &sd, DV_NULL) != 1) return;
Most applications will use the same engine variable in every call to txTextMakeViaStream. Exceptions are certain types of multi-threaded applications in which a number of text documents must be accessed and rendered simultaneously. In those cases, each thread could initialize its own engine instance. This approach allows multiple threads to use and access D-Type Unicode Text Module's functions simultaneously (without using mutexes or other synchronization or blocking code). However, depending on the font cache, number of fonts and other resources in memory, a large number of engine instances may require a significant amount of RAM.
Each engine instance is created dynamically and must be destroyed by calling the pdEngineExt function before the application terminates. The code snippet to do this is shown below:
pdEngineExt(Engine);
See How To Use D-Type Streams And Stream Macros.
See our notes regarding file based streams.
See the txMakeCachedFontmap function.
txTextIniViaStream
txTextMakeViaBuffer, txTextMakeViaPowerDoc