PA_SetAreaReference

version 2003

PA_SetAreaReference (params; ref)

Parameter	Type		Description
params	PA_PluginParameters		Parameters received in PluginMain
ref	void*		Handle/Pointer to private data

The routine PA_SetAreaReference sets the area reference to ref. ref is a pointer to any kind of private data needed by the area. Each time the area is called, it can get its private data by calling PA_GetAreaReference.

This is especially useful when more that one area exists at Runtime (ie., when several processes use 4D Write). In this case it would be more difficult for the plug-in to retrieve the specific data attached to a particular area. This could be done by using a global reference system (such as an array or anything else), but using PA_Set/PA_GetAreaReference is far easier.

You can change the area reference to your private data at any time, it does not depend on a particular event, but it usually is called at initialization time. When the data points to data in the heap, be sure to disposing it before allocating a new one.

Initialize data and retrieve it. Once 10 mouse clicks occur, an alert is displayed.

   typedef struct {
      long   aField;
      short   anotherField;
      /* . . . */
      short   mouseClickCount;
   } AREA, *LPAREA;

   void PluginMain(selector, PA_PluginParameters params)
   {
      switch (selector)
      {
      /* . . . usual dispatch of the selector . . . */
         case kAREA:
            DoArea(params);
            break;
      }
   }

   void DoArea (PA_PluginParameters params)
   {
      AE_Event   event = PA_GetAreaEvent(params);
      LPAREA      privateData;
      
      switch(event)
      {
         case eAE_Init:
      // initialize our private data
            privateData = malloc( sizeof(AREA) );
            if(privateData)
            {
               privateData->aField = GetTickCount();
               /* . . . */
               privateData->mouseClickCount = 0;
         // Once initialized, "save" it in the area
               PA_SetAreaReference(params, privateData);
            }
            break;
         
         case eAE_Deinit;
      // Get back our private data...
            params = (LPAREA) PA_GetAreaReference(params);
            if(params)
            {
         // ... and release it
               free(params);
            }
            break;

   /* other events, get the reference and use it */
         case eAE_Mouse down:
            params = (LPAREA) PA_GetAreaReference(params);
            if(params)
            {
               if( (++(params->mouseClickCount)) > 10 )
               {
                  PA_Alert("10 clicks occurred");
                  params->mouseClickCount = 0;
               }
            }
            break;
      }
   }

Create and use an external area, PA_GetAreaReference.

PA_GetLastError keeps the last error that occurred before calling the routine.