Index

C/C++ Functions

pdPropAddAsExtCallback

DT_SWORD pdPropAddAsExtCallback(DT_PDDOC power_doc, DT_ID_SLONG obj, DT_SLONG name, DT_SLONG user_id, void* user_param)

Short Description: Add property - external callback

The pdPropAddAsExtCallback function adds a PowerDoc property to the PowerDoc object obj and is very similar to and compatible with pdPropAdd, which means that properties created by this function can be used in much the same capacity as if they were created by pdPropAdd. However, unlike pdPropAdd which copies the property value to a buffer that is managed by D-Type Power Engine, this function only adds a special flag which says that the value of this property will be obtained by calling the application's own property callback function, when actually needed. See pdDocSetPropCallback for information on how to set up and use the property callback function. Since the property value itself does not reside inside the associated Power Engine document and is always under exclusive control of the application, the newly added property occupies a very small amount of storage space in the object obj (only the amount it takes to store the flag that tells D-Type Engine to obtain its value by calling the callback function).

pdPropAddAsExtCallback is a specialized and advanced function that should be used only by applications that wish to store very large property values (e.g. large arrays or bitmap images) outside the associated Power Engine document and perform their own run-time memory management of large blocks of data. In all other cases pdPropAdd should be used instead.

Parameters

ParameterDescription

power_doc

Handle of the associated Power Engine document.

obj

Object's index in the Power Engine document.

name

A numerical value that identifies the property to be added. Can be a user-defined value or one of the predefined PowerDoc values. For a list of predefined name values, see the pdPropAdd function.

user_id

A numerical value that will be passed back to your property callback function. This value can help you identify the property for which the value is requested or provide other information useful to your application. This value is not used or modified by D-Type Engine in any way; it is simply sent back to your property callback function as supplied. You can set this value to 0 if you have no need for it.

user_param

A void pointer to your own object that will be passed back to your property callback function. This pointer can help you identify the property for which the value is requested 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 property callback function as supplied. You can set this parameter to DV_NULL if you have no need for it.

Return Value

See pdPropAdd.

Comments

See pdPropAdd.

Related Functions

pdPropAdd
pdPropGet, pdPropSet, pdPropSetAsExtCallback
pdPropDel
pdDocSetPropCallback

 

Index