VS:Parametric State Notifications

.VectorScript|VectorScript ..VS:Function Reference|Function Reference ..VS:Function_Reference_Appendix|Appendix

By Vladislav Stanev

What's that

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

For example kParametricRecalculate(5) 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 (0) -- The parametric has just been created.
  • kMovedReset (1) -- The parametric has been moved (only if reset on move flag is on).
  • kRotatedReset (2)-- The parametric has been rotated (only if reset on rotate flag is on).
  • kParameterChangedReset (3)-- Parameter has been changed.
  • kObjectChangedReset (4)-- Attributes change reset.
  • kLayerChangedReset (5) -- Layer scale or position has been changed.

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

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

In order to create custom user interface for parametric object your parametric plug-in should be event enabled.

Then you need to handle the kObjOnInitXProperties(5).

case kObjOnInitXProperties: {
BEGIN {MAIN}
  result := GetCustomObjectInfo(objectName, objectHand, recordHand, wallHand);
  vsoGetEventInfo(theEvent, message );

  CASE theEvent OF
    5: {kObjOnInitXProperties}
    BEGIN
      { 1. Enable application to send out those flags
           to the plug-ins who needs them }
      SetPrefInt( 590, 1 ); {varParametricEnableStateEventing, kParametricStateEvent_ResetStatesEvent}

      { 2. Enable the plug-in to receive states events (regular states) }
      result := SetObjPropVS(18, TRUE); {kObjXPropAcceptStates}
    END;

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(18) must be set to TRUE to enable receiving standard states for this parametric.

Receiving States: kParametricAddState (44)

During this event the user MUST only call VS:vsoStateAddCurrent nothing else!

  vsoGetEventInfo( theEvent, message );

  ...

  44: {kObjOnAddState}
  BEGIN
    message := vsoStateAddCurrent( objectHand, message );
  END;

Reset event

When kParametricRecalculate(3) event is received, the VectorScript plug-in can recognize if a state has occured by calling appropriate function according to the event:

In order to receive correct information on received states in between resets, IT IS EXTREMELY IMPORTANT to call VS:vsoStateClear at the end of the reset event:

  3: {kParametricRecalculate}
  BEGIN
    { ... }

    vsoStateClear( objectHand );
  END;

kCreatedReset

This state doesn't have data attached, so you can use the general function VS:vsoStateGet to check if this state has been sent.

IF vsoStateGet( objectHand, 0 {kCreatedReset} ) THEN BEGIN

kMovedReset

Returns TRUE if the event has been received VS:vsoStateGetPos and obtains information on the event.

FUNCTION vsoStateGetPos(
             hObj          : HANDLE;
             VAR outX      : REAL;
             VAR outY      : REAL;
             VAR outZ      : REAL;
             VAR outIs3D   : BOOLEAN) : BOOLEAN;

IF vsoStateGetPos( objectHand, x, y, z, is3D ) THEN BEGIN

kRotatedReset

Returns TRUE if the event has been received VS:vsoStateGetRot and obtains information on the event.

FUNCTION vsoStateGetRot(
             hObj             : HANDLE;
             VAR outDiffAng   : REAL;
             VAR outIs3D      : BOOLEAN) : BOOLEAN;

IF vsoStateGetRot( objectHand, diffAng, is3D ) THEN BEGIN

kParameterChangedReset

Returns TRUE if the event has been received VS:vsoStateGetParamChng and obtains information on the event.

FUNCTION vsoStateGetParamChng(
                hObj            : HANDLE;
                VAR outWidgID   : LONGINT;
                VAR outPrmIdx   : INTEGER;
                VAR outOldVal   : STRING) : BOOLEAN;

IF vsoStateGetParamChng( objectHand, widgID, prmIndex, oldValue ) THEN BEGIN

kObjectChangedReset

Returns TRUE if the event has been received VS:vsoStateGetObjChng and obtains information on the event.

FUNCTION vsoStateGetObjChng(
               hObj              : HANDLE;
               VAR outChangeID   : LONGINT) : BOOLEAN;

IF vsoStateGetObjChng( objectHand, changeID ) THEN BEGIN

kLayerChangedReset

Returns TRUE if the event has been received VS:vsoStateGetLayrChng and obtains information on the event.

FUNCTION vsoStateGetLayrChng(
               hObj               : HANDLE;
               VAR outOldScale    : REAL;
               VAR outNewScale    : REAL;
               VAR outScaleText   : BOOLEAN) : BOOLEAN;

IF vsoStateGetLayrChng( objectHand, oldScale, newScale, scaleText ) THEN BEGIN

kExitFromEditGroup

Returns TRUE if the event has been received VS:vsoStateGetExitGroup and obtains information on the event.

FUNCTION vsoStateGetExitGroup(
                hObj             : HANDLE;
                VAR outGrpType   : LONGINT) : BOOLEAN;

IF vsoStateGetExitGroup( objectHand, grpType ) THEN BEGIN

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

• kObjXPropEditGroupDefault = 0
• kObjXPropEditGroupProfile = 1
• kObjXPropEditGroupPath = 2
• kObjXPropEditGroupCustom = 3

Note: "Exit Group" doesn't send a reset event. This means that you have to explicitly reset the object upon receiving the state event:

44: {kObjOnAddState}
BEGIN
  res := vsoStateAddCurrent( objectHand, message );
  IF vsoStateGetExitGroup( objectHand, grpType ) THEN BEGIN
    {readd it so the reset could be able to get it}
    res := vsoStateAddCurrent( objectHand, message );
    ResetObject( objectHand );
  END;
END;

kObjectNameChanged

Returns TRUE if the event has been received VS:vsoStateGetNameChng and obtains information on the event.

FUNCTION vsoStateGetNameChng(
               hObj             : HANDLE;
               VAR outOldName   : STRING;
               VAR outNewName   : STRING) : BOOLEAN;

IF vsoStateGetNameChng( objecthand, oldName, newName ) THEN BEGIN

Example

Full example: Media:VSEventingObject.zip