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.