VS:Parametric State Notifications
.VectorScript|VectorScript ..VS:Function Reference|Function Reference ..VS:Function_Reference_Appendix|Appendix
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
