Index

C/C++ Functions

txTextPasteViaStream

DT_SLONG txTextPasteViaStream(DT_TXDOC text_doc, DT_ID_UBYTE paste_command, DT_ID_UBYTE text_type, const DT_STREAM_DESC* text_sd, DT_SWORD unicode_flags, const DT_STREAM_DESC* fontmap_sd)

Short Description: Paste text into current text selection - via stream

This function pastes text (i.e. a sequence of Unicode characters) into the active selection of the text document specified by text_doc, replacing any currently selected text.

Parameters

ParameterDescription

text_doc

Handle of the associated text document instance.

paste_command

Paste command. Can be one of the following:

TX_PASTE_TEXT               0    /* Paste text */ 
TX_PASTE_BACKSPACE          1    /* Paste the BAKSPACE key */ 
TX_PASTE_DELETE             2    /* Paste the DELETE key */ 
TX_PASTE_TEXT_REFORMAT      128  /* Paste text and reformat the paragraph */ 
TX_PASTE_BACKSPACE_REFORMAT 129  /* Paste the BAKSPACE key and reformat the paragraph */ 
TX_PASTE_DELETE_REFORMAT    130  /* Paste the DELETE key and reformat the paragraph */ 

These values have the following meaning:

  • TX_PASTE_TEXT indicates that the text should be inserted into the active selection of the text document, replacing any currently selected text. Does not subsequently run Unicode's implicit bidirectional reordering algorithm on the affected paragraph(s).

  • TX_PASTE_BACKSPACE indicates that the BACKSPACE key command should be applied to the active selection of the text document. In this case, buffer should be set to DV_NULL, nr_of_chars to 0 and buffer_format to 0. Does not subsequently run Unicode's implicit bidirectional reordering algorithm on the affected paragraph(s).

  • TX_PASTE_DELETE indicates that the DELETE key command should be applied to the active selection of the text document. In this case, buffer should be set to DV_NULL, nr_of_chars to 0 and buffer_format to 0. Does not subsequently run Unicode's implicit bidirectional reordering algorithm on the affected paragraph(s).

  • TX_PASTE_TEXT_REFORMAT is the same as TX_PASTE_TEXT but subsequently runs Unicode's implicit bidirectional reordering algorithm on the affected paragraph(s).

  • TX_PASTE_BACKSPACE_REFORMAT is the same as TX_PASTE_BACKSPACE but subsequently runs Unicode's implicit bidirectional reordering algorithm on the affected paragraph(s).

  • TX_PASTE_DELETE_REFORMAT is the same as TX_PASTE_DELETE but subsequently runs Unicode's implicit bidirectional reordering algorithm on the affected paragraph(s).

text_type

Encoding of the text to be pasted. 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 text that is pasted based on its first few bytes. When the first two bytes are 0xFEFF, the text is assumed to be UTF-16 Big Endian. When the first two bytes are 0xFFFE, the text is assumed to be UTF-16 Little Endian. When the first three bytes are 0xEFBBBF, the text is assumed to be UTF-8. If none of the above bytes sequences are present at the beginning of the file, the text 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 text. 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 text that is being pasted (e.g. disk, memory, 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) */ 

Additionally, when calling this function unicode_flags can be set to -1. This instructs the function to use the same Unicode flags that were used when the text document was created by calling txTextIniViaStream, txTextIniViaBuffer, txTextMakeViaStream or txTextMakeViaBuffer.

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 txTextPasteViaStream 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.

Finally, when calling this function fontmap_sd can be set to DV_NULL. This instructs the function to use the same font map that was used when the text document was created by calling txTextIniViaStream or txTextMakeViaStream. This is the fastest method of invoking this function.

Return Value

If the function was successful, the return value will be the number of pasted characters. Otherwise, the function returns -1. The function will also return -1 if there are multiple (non-contiguous) or block (rectangular) active selections in the text document.

Comments

The txTextPasteViaStream function makes it possible to paste Unicode text (i.e. a sequence of Unicode characters) into the active selection of the current text document. See the txTextSetSelect function for information on how to set the boundaries of the active text selection.

The styling/formatting attributes of the text pasted using this function will be inherited from the context (i.e. neighbouring characters).

In order to view the modified text document it is necessary to subsequently call the txTextDraw function.

 

Index