The txTextSetScriptCallback function registers a callback function to be called during Unicode text processing performed by txTextMakeViaStream, txTextMakeViaBuffer and, depending on the UnicodeFlags, txTextPasteViaStream and txTextPasteViaBuffer.
Parameter | Description |
---|---|
text_doc |
Handle of the associated text document instance. |
user_script_func |
A pointer to your own callback function that will be called as D-Type Unicode Text Module processes plain text and determines the script of each character. This function is responsible for telling D-Type Unicode Text Module what script a certain Unicode character is associated with. It must be declared as follows: DT_ID_SLONG your_user_script_func(DT_SLONG index, DT_ID_ULONG char_code, DT_ID_SLONG script_code, DT_ULONG* flag, void* user_param) where your_user_script_func is the name of your own C function, index represents the index of the character in the plain text for which a callback is triggered, char_code is its Unicode character code and script_code is the script code assigned to this character based on the Unicode standard. See the list of defined scripts for a list of currently supported codes. The flag parameter is an output parameter that your function can set, as explained below. The user_param parameter is a pointer to your own data type that you will receive during the callback. Your function is passed the script code assigned to a particular character based on Unicode. Your function can accept Unicode's assignment by returning the same script code, or change it by returning a different script code. Either way, the fontmap.inf file will respect the returned script code. This means that the script code you return will determine the font, text shaping and relative orientation that D-Type Unicode Text Module will apply to the character in question. When the returned script code is different (see Note 1 below) from the script code of the previous character, your function can also set the flag output parameter to specify the line breaking preference for this point in text (i.e. between the previous and current character). You can set flag to one of the following:
If you do not set the flag parameter, value 0 is assumed. Note that the value of the flag parameter is irrelevant and ignored when the returned script code is the same as the script code of the previous character. In that case line breaking is always performed as normal (i.e. using D-Type's default line breaking algorithm). This means that unless there is a change of script, your function will not be able to impact the way D-Type Unicode Text Module performs line breaking. Setting the user_script_func parameter to DV_NULL when calling txTextSetScriptCallback will permanently unregister a previously registered callback function. Once this is done, D-Type Unicode Text Module will no longer initiate any callbacks during Unicode text processing. In that case, the script code assigned to a particular character is based solely on Unicode. |
user_param |
A void pointer to your own data type that you will receive during the callback. This pointer is passed back to your function during the callback to help you track the state of execution or provide other information useful to your application. This pointer is not accessed or modified by D-Type Engine in any way; it is simply sent back to your function as supplied. You can set this parameter to DV_NULL if you have no need for it. |
If the function was successful, the return value is 1. Otherwise, the function returns 0 (bad input).
The callback mechanism makes it possible to override the Unicode script associated with a particular character. The callbacks are triggered when D-Type Unicode Text Module processes plain text and determines the script of each character. This happens when a user calls txTextMakeViaStream, txTextMakeViaBuffer and, depending on the UnicodeFlags, txTextPasteViaStream and txTextPasteViaBuffer.
The char-to-script callback mechanism is very useful when used in conjunction with the capabilities of the fontmap.inf file. By associating different script codes with different fonts and/or relative orientation in the fontmap.inf file, applications can have a fine level of control over automatic text layout of different scripts and/or character groups. Examples include: a) controlling the height of the carriage return in vertical writing mode, b) precise control over vertical alternatives of certain non-CJK characters, c) controlling the rotation of 2 byte Roman characters in vertical writing mode.
"Common" (0 or zyyyScriptCode) and "Inherited" (1 or qaaiScriptCode or zinhScriptCode) are not considered to be different scrips, when compared with the script of the previous character.
Regardless of the value of the flag parameter, line breaks are always allowed after white space characters.
Important Note for MS Windows Users: When passing D-Type a pointer to your own callback function, beware of the calling convention of your C/C++ environment. On MS Windows, all D-Type API functions that accept a pointer to your own callback function assume that your function uses the _cdecl convention. For example, in dtype.h on MS Windows the dtFontSetErrorCallback function is defined as follows:
DT_SWORD _stdcall dtFontSetErrorCallback(DT_DTENGINE engine, void (_cdecl *font_error_func)(const DT_CHAR* error_message, void* user_param), void* user_param);
Therefore, your own callback function must be defined as follows:
void _cdecl your_font_error_function(const DT_CHAR* error_message, void* your_param)
This note applies to any D-Type functions that expect a pointer to your own callback function (e.g. dtFontSetErrorCallback, pdDocSetDrawCallback, pdDocSetGlyphCallback, pdDocSetVectorCallback, txTextSetScriptCallback and possibly others in the future). Failing to add the _cdecl keyword may result in crashes and other undefined behavior, or your code may simply fail to compile.
txTextMakeViaStream, txTextMakeViaBuffer, txTextPasteViaStream, txTextPasteViaBuffer
The following example shows a simple implementation of a callback function.
This function returns a private script code (p001ScriptCode) which allows the application to implement custom text layout operations (e.g. font assignment and character rotation) using the fontmap.inf file.
DT_ID_SLONG MyUserScriptFunc(DT_SLONG index, DT_ID_ULONG char_code, DT_ID_SLONG script_code, DT_ULONG* flag, void* user_param) { *flag = 1; /* use D-Type's default line breaking algorithm to determine if line breaking is allowed between the previous and current character */ if (char_code >= 0xFF10 && char_code <= 0xFF19) || (char_code >= 0xFF21 && char_code <= 0xFF3A) || (char_code >= 0xFF41 && char_code <= 0xFF5A) { return p001ScriptCode; /* full width alpha-numerical characters in CJK range*/ } /* otherwise return the script as per Unicode Standard */ return script_code; }
Then, in the fontmap.inf file, an entry such as this one could be added:
SCRIPTCODE:p001|ATTRIBS:ro=8|FONTNAME:Arial Unicode MS
This now means "when plain text is processed, do not rotate full width alpha-numerical characters in CJK range and use the Arial Unicode MS font to display them".