Index

C/C++ Functions

pdDocSetPropCallback

DT_SWORD pdDocSetPropCallback(DT_PDDOC power_doc, DT_UBYTE* (*user_prop_func)(DT_ID_SLONG obj, DT_SLONG name, DT_SLONG* len, DT_SLONG user_id, void* user_param))

Short Description: Set document's property callback function

The pdDocSetPropCallback function registers a callback function to be called whenever the value of a PowerDoc property added by pdPropAddAsExtCallback or set by pdPropSetAsExtCallback needs to be obtained.

Parameters

ParameterDescription

power_doc

Handle of the associated Power Engine document.

user_prop_func

A pointer to your own callback function that will be called whenever the value of a PowerDoc property added by pdPropAddAsExtCallback or set by pdPropSetAsExtCallback needs to be obtained. Your function must be declared as follows:

DT_UBYTE* user_prop_func(DT_ID_SLONG obj, DT_SLONG name, DT_SLONG* len, DT_SLONG user_id, void* user_param)

where user_prop_func is the name of your own C function, obj object's index in the Power Engine document and name a numerical value that identifies the property for which the value is requested. The user_id parameter is your own numerical value and user_param a pointer to your own data type that you will receive during the callback. See pdPropAddAsExtCallback for more information on these parameters.

The len parameter is an output parameter that must be set by your application and specifies the length of the property value, in bytes. It must not be negative.

Your function is called any time D-Type Power Engine needs to obtain the value of the property added by the pdPropAddAsExtCallback function or set by the pdPropSetAsExtCallback function. Your function must return a pointer to a buffer that holds the value of the property and set len accordingly. Within the buffer, the value must be stored as native binary data (i.e. in the same format as if it was created by calling pdMakeBinary). Whether you fetch the binary data to the buffer before or during the callback is entirely up to your application. As far as D-Type Power Engine is concerned, the binary data must remain in the buffer at least until the next callback for the same value is made or until this property is removed from the associated PowerDoc object. Note that your application is responsible for managing and destroying the buffer. If this is not done properly, you could experience crashes, memory leaks and other similar problems.

Your function may also return DV_NULL to indicate that the property value is not available. This however will not prevent D-Type Power Engine from requesting the the same property value again at a later time.

Setting the user_prop_func parameter to DV_NULL when calling pdDocSetPropCallback will permanently unregister a previously registered property callback function. Once this is done, D-Type Power Engine will no longer initiate property value callbacks. In this case, any PowerDoc properties added by pdPropAddAsExtCallback or set by pdPropSetAsExtCallback will be valueless.

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.

 

Index