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: |
Example
For an example, refer to L_VecSetEventCallback.