Index

C/C++ Functions

pdDocSetDrawCallback

DT_SWORD pdDocSetDrawCallback(DT_PDDOC power_doc, DT_SWORD (*user_draw_func)(DT_PD_DOCDRAW_CANVAS* canvas, DT_SLONG fn_draw, const DT_TM3X3 tm, DT_SWORD flag))

Short Description: Set document's draw callback function

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.

Parameters

ParameterDescription

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:

  • 1 to indicate that the user-defined object was successfully drawn;
  • 0 to indicate that the user-defined object was not processed by your function;
  • -1 to indicate that the user-defined object was not drawn because it was outside the canvas;
  • -2 to indicate that the user-defined object was not properly defined;
  • -3 to indicate that there was not enough memory to process the user-defined object;
  • -99 to indicate that an unexpected or unknown error occurred.

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.

Return Value

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

Comments

Review the comments section of the pdDocDraw function.

Note 1

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.

Note 2

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