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.
Parameter | Description |
---|---|
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:
|
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. |
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.
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.