L_VecEvent

#include "lvkrn.h"

L_LVKRN_API L_INT L_VecEvent(pVector, pEvent)

pVECTORHANDLE pVector;	/* pointer to a vector handle */
pVECTOREVENT pEvent;	/* pointer to a structure */

Implements a user-defined event.

Parameter	Description
pVector	Pointer to a vector handle.
pEvent	Pointer to a VECTOREVENT structure that describes the event that has occurred inside the vector handle.

Returns

SUCCESS	The function was successful.
< 1	An error occurred. Refer to Return Codes.

Comments

This function provides a means of grouping numerous operations into one event. This function must be called twice. In the first call to this function the Status member of the VECTOREVENT structure must be set to VECTOR_EVENT_STATUS_BEFORE. This allows any callback currently installed to cancel the operation. The return value for this function will be the return value of the callback function.

The second call to this function is made after the operation(s) has(have) been completed. The Status member of the VECTOREVENT structure must be set to VECTOR_EVENT_STATUS_AFTER to notify the vector toolkit that the operation(s) has(have) been completed successfully.

For information on the types of events the vector handle can generate, refer to the VECTOREVENT structure.

This function generates a call to the VECTOREVENTPROC callback function.

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
Topics:	Vector Handle Events

Example

This example will wrap multiple operations on a vector handle with a single user-defined event.

#define MY_CUSTOM_EVENT (VECTOR_EVENT_USER+1)

L_INT VecEventExample(pVECTORHANDLE pVector)
{
   L_INT       nRet;
   VECTOREVENT Event;
   VECTORPOINT Point;

   /* Fire our new event, giving all event callbacks in the vector handle a chance to cancel our operation */
   memset( &Event, 0, sizeof( Event ) );
   Event.nSize    = sizeof( Event );
   Event.uType    = MY_CUSTOM_EVENT;
   Event.Status   = VECTOR_EVENT_STATUS_BEFORE;

   nRet = L_VecEvent( pVector, &Event );
   if( nRet != SUCCESS )
      /* a callback has returned something other than success, we should cancel */
      return nRet;

   /* do the operation, for example, rotate, translate and scale */
   Point.x = 10.0;
   Point.y = 20.0;
   Point.z = 30.0;
   nRet = L_VecSetRotation( pVector, &Point, NULL, NULL, 0L );
   if (nRet != SUCCESS)
      return nRet;

   Point.x = 4.0;
   Point.y = 4.0;
   Point.z = 4.0;
   nRet = L_VecSetTranslation( pVector, &Point, NULL, 0L );
   if (nRet != SUCCESS)
      return nRet;

   Point.x = 0.5;
   Point.y = 0.5;
   Point.z = 0.5;
   nRet = L_VecSetScale( pVector, &Point, NULL, NULL, 0L );
   if (nRet != SUCCESS)
      return nRet;

   /* notify the vector handle that the operation is done */
   Event.Status = VECTOR_EVENT_STATUS_AFTER;
   nRet = L_VecEvent( pVector, &Event );

   return nRet;
}