The pdDocSetDrawCallback function registers a callback function for rendering user-defined PowerDoc objects. This function will be called by D-Type Engine automatically any time user-defined rendering functions are encoutered on the page that is drawn by calling pdDocDraw. A user-defined rendering function is any rendering function (i.e. any custom numerical value) that is not on the list of Basic PowerDoc Rendering Functions or PowerDoc Rendering Functions To Render Form Controls.
Parameter | Description |
---|---|
power_doc |
Handle of the associated Power Engine document. |
user_draw_func |
A pointer to your own callback function that will be called during execution. Your function must be declared as follows: DT_SWORD your_user_draw_func(DT_PD_DOCDRAW_CANVAS* canvas, DT_SLONG fn_draw, const DT_TM3X3 transform, DT_SWORD flag) where your_user_draw_func is the name of your own C function, canvas a pointer to the DT_PD_DOCDRAW_CANVAS structure that will supply all the information necessary to render a PowerDoc image of the encountered user-defined PowerDoc object, fn_draw a numerical value of the rendering function associated with this PowerDoc image and transform the final transformation matrix that you must apply to the rendered PowerDoc image. The flag parameter is a special flag reserved for future use and is curently set to 0. Your function should return one of the following values:
Setting the user_draw_func parameter to DV_NULL when calling pdDocSetDrawCallback will permanently unregister a previously registered callback function. Once this is done, pdDocDraw will no longer initiate any callbacks for rendering user-defined PowerDoc objects. |
If the function was successful, the return value is 1. Otherwise, the function returns 0 (bad input).
Review the comments section of the pdDocDraw function.
This is an advanced function that can be used to extend the functionality of D-Type Power Engine. Additional technical information about this function is available to customers with a support contract.
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.