VECTOREVENTPROC Function

#include "lvkrn.h"

L_INT pEXT_CALLBACK YourFunction (pVector, uLevel, pEvent, pUserData)

pVECTORHANDLE pVector;

/* pointer to a vector handle */

L_UINT uLevel;

/* event level */

pVECTOREVENT pEvent;

/* pointer to a vector event */

L_VOID * pUserData;

/* pointer to additional parameters */

Processes each event that occurs inside the vector handle.

Parameter

Description

pVector

Pointer to the vector handle in which the event occurred.

uLevel

Level of the event that occurred. For a top-level event, this value is 0. For a second level event this value is 1, etc. For an example, refer to the Comments section below.

pEvent

Pointer to a VECTOREVENT structure that describes the event that occurred in the vector handle.

pUserData

A void pointer that you can use to access a variable or structure containing data that your callback function needs. This gives you a way to receive data indirectly from the function that uses this callback function. (This is the same pointer that you passed in L_VecSetEventCallback.)

 

Keep in mind that this is a void pointer, which must be cast to the appropriate data type within your callback function.

Returns

The return value is valid only when pEvent->Status is EVENT_STATUS_BEFORE.

SUCCESS

Continue with the operation.

SUCCESS_ABORT

Abort this operation only.

< 1

An error occurred. Refer to Return Codes.

Comments

To understand event levels, consider this example:

Assume the clipboard contains a vector handle with 1 layer and 2 objects inside this layer.

Now you execute L_VecCopyFromClipboard, the toolkit may fire these events in the following sequence:

pEvent->uType

pEvent->Status

uLevel

Comment

VECTOR_EVENT_COPYFROMCLIPBOARD

VECTOR_EVENT_BEFORE

0

L_VecCopyFromClipboard is about to execute.

VECTOR_EVENT_ADDLAYER

VECTOR_EVENT_BEFORE

1

L_VecAddLayer is about to execute.

VECTOR_EVENT_ADDOBJECT

VECTOR_EVENT_BEFORE

2

L_VecAddObject for first object is about to execute.

VECTOR_EVENT_ADDOBJECT

VECTOR_EVENT_AFTER

2

L_VecAddObject for first object has been completed.

VECTOR_EVENT_ADDOBJECT

VECTOR_EVENT_BEFORE

2

L_VecAddObject for second object is about to execute.

VECTOR_EVENT_ADDOBJECT

VECTOR_EVENT_AFTER

2

L_VecAddObject for second object has been completed.

VECTOR_EVENT_ADDLAYER

VECTOR_EVENT_AFTER

1

L_VecAddLayer has been completed.

VECTOR_EVENT_COPYFROMCLIPBOARD

VECTOR_EVENT_AFTER

0

L_VecCoptFromClipboard has been completed.

Your callback can monitor all these operations and cancel whatever operation you want.

Returning SUCCESS_ABORT will abort a single operation. For example, to delete objects and not the layers of a vector when L_VecEmpty is called, the callback can be written like this:

 

L_INT VectorEventCallback( pVECTOREVENT pEvent )
{
   switch( pEvent->uType )
   {
      case VECTOR_EVENT_DELETEOBJECT:
         if( pEvent->Status == VECTOR_EVENT_STATUS_BEFORE ) // a chance to cancel
         {
            return SUCCESS_ABORT; // cancel this operation only, continue with the rest
         }
         break;

      default:
         break;
   }

   return SUCCESS;
}

Required DLLs and Libraries

LVKRN

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application.

See Also

Functions:

L_VecSetEventCallback, L_VecEvent

Example

For an example, refer to L_VecSetEventCallback.