Index

C/C++ Functions

pdDocSetGlyphCallback

DT_SWORD pdDocSetGlyphCallback(DT_PDDOC power_doc, DT_SWORD (*user_glyph_func)(DT_ID_ULONG glyph_index, const DT_PD_ORIGIN_L* glyph_origin, const DT_PD_FLOW* glyph_flow, void* user_param), void* user_param)

Short Description: Set document's glyph callback function - L

The pdDocSetGlyphCallback function registers a callback function to be called during the text layout operations performed by pdDocDraw.

Parameters

ParameterDescription

power_doc

Handle of the associated Power Engine document.

user_glyph_func

A pointer to your own callback function that will be called as pdDocDraw performs its text layout operations. Your function must be declared as follows:

DT_SWORD your_user_glyph_func(DT_ID_ULONG glyph_index, const DT_PD_ORIGIN* glyph_origin, const DT_PD_FLOW* glyph_flow, void* user_param)

where your_user_glyph_func is the name of your own C function, glyph_index an index of the glyph generated during the text layout process, glyph_origin is a pointer to a structure that provides its position in pixels (in 24.8 signed fractional format) and some other optional information (e.g. typographical attributes), and glyph_flow is a pointer to a structure that provides all the available information about the glyph's text flow and frame. The user_param parameter is a pointer to your own data type that you will receive during the callback.

Your function is called once for each glyph that is generated during the text layout process. Therefore, there will be as many callbacks as there are glyphs to be rendered. The glyph_flow parameter can be used to identify the glyph's text flow and obtain its frame. Since each glyph triggers one callback, your callback function receives one frame at a time. Consequently, the frames_len parameter of the DT_PD_FLOW structure is always set to 1.

Your function receives information about the glyph's text flow and frame via the glyph_flow pointer only when the Flows member of the DT_PD_DOCDRAW_PARAMS structure that you pass to the pdDocDraw function is set to 1, 2, 10 or 20. Depending on how you set the value of the Flows member, the glyph's frame will be supplied to you in either DT_PD_FRAME_FORMAT1 or DT_PD_FRAME_FORMAT2 format. If, however, you set the Flows member to 0 or do not pass the pdDocDraw function a pointer to the DT_PD_DOCDRAW_PARAMS structure, then glyph_flow will be supplied to you as DV_NULL. Also, glyph_flow can be supplied to you as DV_NULL if out-of-memory conditions occur or if your callback function instructs pdDocDraw to stop generating text flows and frames. Thus, your callback function should always check the glyph_flow value for DV_NULL and handle this situation gracefully.

See the Text Flows and Frames document in the D-Type Workshop section for more information on how to set the members of the DT_PD_DOCDRAW_PARAMS structure before calling pdDocDraw.

Note that both the DT_PD_FRAME_FORMAT1 and DT_PD_FRAME_FORMAT2 structures provide two important indexes:

  • Idx which is the index of the corresponding character in the text (i.e. this index maps the glyph back to the input text), and
  • Row which is the index of the row in which this glyph will appear when the text is rendered.

Your function should return one of the following values:

  • -2 = to instruct pdDocDraw not to render this glyph;
  • -1 = to instruct pdDocDraw to render this glyph but stop generating text flows and frames until the current text layout process is over;
  • 1 = to instruct pdDocDraw to render this glyph.

The consequence of returning -2 is that the glyph will not be rendered (leaving a gap in the output) without any effect on the text layout process. The consequence of returning -1 is that glyph_flow will be supplied to you as DV_NULL in any subsequent callbacks resulting from the same pdDocDraw call.

Regardless of the return value, the text layout process continues; there is no way for your callback function to immediately terminate or alter the text layout process.

Setting the user_glyph_func parameter to DV_NULL when calling pdDocSetGlyphCallback will permanently unregister a previously registered callback function. Once this is done, any subsequent calls to pdDocDraw will no longer initiate any callbacks during their text layout operations.

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.

Return Value

If the function was successful, the return value is 1. Otherwise, the function returns 0 (bad input).

Note

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.

Related Functions

pdDocDraw

 

Index