SDK:Parametric State Notifications: Difference between revisions

From Vectorworks Developer
Jump to navigation Jump to search
 
Line 27: Line 27:
**<i>kObjectNameChanged</i> -- Parametric object name changed – send when the object name changes.
**<i>kObjectNameChanged</i> -- Parametric object name changed – send when the object name changes.


 
Note: Do not use <i>kObjectUndoRestore</i> and <i>kObjectUndoRemove</i>. They are still defined for legacy purposes, and they will be removed in the future version.
* Undo related states (needs [[SDK:Parametric State Notifications#Advanced Control|Advanced Control]] over the mechanism described below)
**<i>kObjectUndoRestore</i> -- Undo events for undo restoring an object. The parametric will be notified when the undo restore (create so to say) an parametric object instance;
**<i>kObjectUndoRemove</i> --Undo events for undo removing an object. The parametric will be notified when the undo remove (delete so to say) an parametric object instance.





Latest revision as of 14:28, 30 January 2019

.SDK|SDK ..SDK:Types|SDK Types ..SDK:Using the SDK|Using the SDK ..VCOM:VCOM (Vectorworks Component Object Model)|VCOM Basics ..VCOM:Class Reference|VCOM Class Reference

By Vladislav Stanev

What's that

State Notification mechanizm allows the plug-in to receive notifications for changes that happen to the parametric object.

For example kParametricRecalculate event is sent to the plug-in to update the parametric object, but there is no information of what exactly happened that needs update.

Currently the following states are supported:

  • Pre-reset states -- giving information of what happened before the reset
    • kCreatedReset -- The parametric has just been created.
    • kMovedReset -- The parametric has been moved (only if reset on move flag is on).
    • kRotatedReset -- The parametric has been rotated (only if reset on rotate flag is on).
    • kParameterChangedReset -- Parameter has been changed.
    • kObjectChangedReset -- Attributes change reset.
    • kLayerChangedReset -- Layer scale or position has been changed.


  • States that doesn't cause automatic reset
    • kExitFromEditGroup -- The parametric profile or other special group has been changed.
    • kObjectNameChanged -- Parametric object name changed – send when the object name changes.

Note: Do not use kObjectUndoRestore and kObjectUndoRemove. They are still defined for legacy purposes, and they will be removed in the future version.


Note The states event is informative. This means that when receiving non-reset states a plug-in should not cause reset or call other VectorWorks functions.

Setting up: kObjOnInitXProperties

In order to create custom user interface for parametric object your parametric plug-in should have SDK:Parametric Extended Properties enabled through the resources Enabling Extended Properties.

Then you need to handle the kObjOnInitXProperties event inside your SDK:Plug-in Object Main Function.

Note that the extended properties are manipulated though a VCOM (VectorWorks Component Object Model) interface IExtendedProps part of Category:VCOM:VectorWorks:PluginSupport.

case kObjOnInitXProperties: {
  // obtain the interfact for accessing the extended properties
  using namespace VectorWorks::PluginSupport;
  VCOMPtr<IExtendedProps>	pExtProps( IID_ExtendedProps );

  // 1. Enable application to send out those flags
  //    to the plug-ins who needs them
  short		stateEventFlags	= kParametricStateEvent_ResetStatesEvent;
  gSDK->SetProgramVariable( varParametricEnableStateEventing, & stateEventFlags );

  // 2. Enable the plug-in to receive states events (regular states)
  pExtProps->SetObjectProperty( objectID, kObjXPropAcceptStates, true );

1. Enable events in the application

Using program flags you should enable the application to send out those events to the plug-ins.

This is intended to optimize performance if there are no plug-ins that are interested in those events.

2. Enable extended standard states property

Property kObjXPropAcceptStates must be set to true to enable receiving standard states for this parametric.

Receiving States: kParametricAddState

The user will handle kParametricAddState event in his SDK:Plug-in Object Main Function function. Along with the event a pointer to a data structure will be sent: (this is extension of the already existing system of notification data structures in the SDK)

struct ObjectEventCall 
{	
  long   fSpecifier;
  void*  fData;
};

struct ObjectState : public ObjectEventCall
{
  enum EStateType {
    kCreatedReset,
    kMovedReset,
    kRotatedReset,
    kParameterChangedReset,
    kObjectChangedReset,
    kLayerChangedReset,
    kExitFromEditGroup,
    kObjectNameChanged,
    kObjectUndoRestore,
    kObjectUndoRemove,
  };
};

By recognizing ObjectEventCall::fSpecifier as one of the ObjectState::EStateType the user will recognize the event type.

case kObjOnAddState: {
  ObjectState*	pObjState  = (ObjectState*) message;
  if ( pObjState ) {
    ObjectState::EStateType   objState	= (ObjectState::EStateType) pObjState->fSpecifier;
    switch( objState ) {
      case ObjectState::kMovedReset: {
            ObjectStateData_Position* pPosData = (ObjectStateData_Position*) pObjState->fData;
            // ...
        } break;

      case ObjectState::kParameterChangedReset: {
            ObjectStateData_ParamChanged* pPrmData = (ObjectStateData_ParamChanged*) pObjState->fData;
            // ...
        } break;

      // ...
    }
  }
  break;
}

ObjectEventCall::fData will be cast by the user to the appropriate data struct which holds the additional data to the event. Some of the events will not have additional data:

kMovedReset and kRotatedReset

struct ObjectStateData_Position
{
  Boolean         fbIs3DMove;
  TransformMatrix fTransformOffset;
};

Provides transformation matrix for the offset (the difference) between the current and old position and rotation.

kParameterChangedReset

struct ObjectStateData_ParamChanged
{
  Sint32         fWidgetID;
  Sint32         fParameterIndex;
  Boolean        fParameterValidOldValue;
  TVariableBlock fParameterOldValue;
};

Provides changed widget ID, data record field (parameter) index and the old value of that parameter. The new value is already in the record when this event is send.

kObjectChangedReset

struct ObjectStateData_ObjectChanged
{
  Sint32         fChangeID;
};

Provides change identifier. The identifiers are provided as constants for different situations: back color changed, fill color changed, pen changed and so on.

kLayerChangedReset

struct ObjectStateData_LayerChanged
{
  double    fdOldLayerScale;
  double    fdLayerScale;
  Boolean   fbScaleText;
  double    fdOldZElevation;
  double    fdNewZElevation;
  double    fdOldZDelta;
  double    fdNewZDelta;
};

Provides information of the old scale, elevation and delta of the layer and the new values.

kExitFromEditGroup

struct ObjectStateData_ExitFromEditGroup
{
  unsigned char  fGroupType;
};

Provides group type of the group that the user just exited. The types are one of the following:

  • kObjXPropEditGroupDefault
  • kObjXPropEditGroupProfile
  • kObjXPropEditGroupPath
  • kObjXPropEditGroupCustom

kObjectNameChanged

struct ObjectStateData_ObjectNameChanged
{
  TXString	oldName;
};

Provides the old name of the object.

See also

SDK:Plug-in Object Events | SDK:Parametric Object Plug-in