L_INT pEXT_CALLBACK YourFunction (pVector, uLevel, pEvent, pUserData)
Processes each event that occurs inside the vector handle.
Pointer to the vector handle in which the event occurred.
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.
Pointer to a VECTOREVENT structure that describes the event that occurred in the vector handle.
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.
The return value is valid only when pEvent->Status is EVENT_STATUS_BEFORE.
Value | Meaning |
---|---|
SUCCESS | Continue with the operation. |
SUCCESS_ABORT | Abort this operation only. |
< 1 | An error occurred. Refer to Return Codes. |
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