KNOWLEDGE BASE
Log In    |    Knowledge Base    |    4D Home
Tech Tip: Creating and using Private data in a Plug-in Area
PRODUCT: 4D | VERSION: 6.7 | PLATFORM: Mac & Win
Published On: October 5, 2001
Your current browser may not allow you to download the asset. We recommend Mozilla Firefox or Google Chrome.
Log In

There are times when it may be necessary to maintain a set of Private Data that can be accessed from the Plug-in Area. An example may be how many times a user has clicked on the Plug-in Area, or perhaps the user has selected the Plug-in object to be an active object. There are two API calls that are used to help save and retrieve the Private Data PA_SetAreaReference and PA_GetAreaReference. PA_SetAreaReference is used to store a pointer to the Private Data that the plug-in can then retrieve with a call to PA_GetAreaReference.

PA_SetAreaReference(PA_PluginParameters, void*);

PA_PluginParameters: These are the parameters received in the main Plug-in routine. Normally this parameter would simply be "params" as we shall see in our example.

Void*: This is a Handle/Pointer to the Private Data

PA_GetAreaReference(PA_PluginParameters) -> void*

PA_PluginParameters: These are the parameters received in the main Plug-in routine. Normally this parameter would simply be "params" as we shall see in our example.

Void*: This is a Handle/Pointer to the Private Data. Note that this command returns the pointer.


Usually you would want to initialize the Private data during the eAE_AreaInit event. You would fill your Private Data with its initial information and then call PA_SetAreaReference, passing a pointer to the allocated memory of the Private Data. This pointer will then "link" to the Plug-in Area. To reference the Private Data simply call PA_GetAreaReference to return a pointer to the data.

Here is a sample. The area stores the number of times it has been called with an eAE_Idle event and an eAE_Update event. When the user clicks in the area, the area displays an alert showing those numbers. An area can use whatever it wants as private data; just remember that this data is stored in RAM.

typedef struct
{
long idleCount;
long updateCount;
}AREA;


void DoMyArea (PA_PluginParameters params)
{
AREA *privateData; // the pointer to our data
PA_AreaEvent event;
event = PA_GetAreaEvent(params);

switch(event)
{

case eAE_AreaInit:

// So, we allocate our data
privateData = (AREA *) malloc(sizeof(AREA));
// we initialize it (no error check here)
privateData->idle = 0;
privateData-> updateCount = 0;

// Then, we link it to the area
PA_SetAreaReference(params, privateData, sizeof(AREA));
break;


// =========================================================
// From now, each time we call PA_GetAreaReference, we get
// our pointer to the AREA private structure allocated
// =========================================================

case kAE_AreaDeinit: // Free the memory used
privateData = (AREA *) PA_GetAreaReference(params);
free(privateData);
break;

case kAE_Idle:
privateData = (AREA *) PA_GetAreaReference(params);
privateData-> idleCount ++
break;

case kAE_Update:
privateData = (AREA *) PA_GetAreaReference(params);
privateData-> updateCount ++;
break;

case kAE_MouseDown:
DisplayData(params);
break;

default:
PA_DontTakeEvent();
break;
}
}


NOTE
Although the private data is usually allocated at eAE_AreaInit event, it can be allocated at anytime, provided that the previously allocated data is disposed before.