Plug-In Modules in SDK 2015

From Vectorworks Developer
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

.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

This document explain the changes for Plug-in Modules in the SDK 2015. It uses comparison with existing plug-in to demonstrate the changes required for existing plug-in to be converted to SDK 2015.

This document presumes that the reader is familiar with VCOM and plug-in module extensions.

All these changes are driven by the need for the SDK 2015 to be 64-bit compatible.

Plug-Ins 64-Bit - Transition Guide

The plug-in module main function

Existing plug-ins have the following main function: 

extern "C" long GS_EXTERNAL_ENTRY plugin_main(long action, void* pInfo, long& ioData, CallBackPtr cbp)

New plug-ins must have the main function defined like this: 

extern "C" Sint32 GS_EXTERNAL_ENTRY plugin_module_main(Sint32 action, void* moduleInfo, const VWIID& iid, IVWUnknown*& inOutInterface, CallBackPtr cbp)

The changes to the main function are:

  • The name has changed. This will ensure old plug-ins, compiled with main function with different parameters, not working in Vectorworks 2015.
  • action parameter have the same meaning and it only changed type to be safe for 64-bit.
  • moduleInfo parameter is the equivalent of the pInfo parameter during the kVCOMRegisterInterfaces action event. Now it always identifiers the current plug-in module being executed.
  • iid parameter was represented as pInfo parameter during kVCOMQueryInterface and kVCOMReleaseInterface action events. Now it always identifiers Interface Identifier when needed.
  • inOutInterface parameter is the equivalent of the ioData parameter. It is used for input and output of interface instances during kVCOMQueryInterface and kVCOMReleaseInterface action events.
  • cbp parameter is a callback pointer for the plug-in to communicate with Vectorworks. There is no changes in the meaning of this parameter.

All the macros used to register and manage VCOM interfaces have been updated to support the changes. Here is an example of a plug-in main function for SDK 2015: 

//------------------------------------------------------------------
// Entry point of the module plug-in for Vectorworks
// More info at: http://developer.vectorworks.net/index.php?title=SDK:Module_Plug-in
//
extern "C" Sint32 GS_EXTERNAL_ENTRY plugin_module_main(Sint32 action, void* moduleInfo, const VWIID& iid, IVWUnknown*& inOutInterface, CallBackPtr cbp)
{
       // initialize VCOM mechanizm
       ::GS_InitializeVCOM( cbp );
 
       // init legacy Global Callback Pointer
       // for support of legacy GS_ functions
       gCBP   = cbp;
 
       { // Init gSDK
              usingnamespace VectorWorks;
              VCOMPtr<ISDK> localSDK( IID_SDK );
              gSDK   = localSDK;
       }
 
       Sint32 reply  = 0L;
 
       usingnamespace VWFC::PluginSupport;
 
       REGISTER_Extension<TesterModule::CExtTool>( GROUPID_ExtensionTool, action, moduleInfo, iid, inOutInterface, cbp, reply );
       REGISTER_Extension<TesterModule::CExtMenu>( GROUPID_ExtensionMenu, action, moduleInfo, iid, inOutInterface, cbp, reply );
       REGISTER_Extension<TesterModule::CExtObj>( GROUPID_ExtensionParametric, action, moduleInfo, iid, inOutInterface, cbp, reply );
       REGISTER_Extension<TesterModule::CExtVSFuncs>( GROUPID_ExtensionVSFunctions, action, moduleInfo, iid, inOutInterface, cbp, reply );
 
       return reply; 
}

Extension eventing

The ILegacyEventSink interface has been removed. This was the interface that contained the main event function, which looked like that: 

virtual long VCOM_CALLTYPE LegacyMain(long action, long message1, long message2) = 0;

There are two changes that were made for the extension eventing:

  • The ILegacyEventSink was removed and substituted with four interfaces for each type of extension: IMenuEventSink, IParametricEventSink, IToolEventSink, and IVSFunctionsEventSink
  • There is still one main function for the events inside the new interfaces, but its parameters are strictly typed for each extension type.

These change is implemented inside VWFC, so if your extensions use VWFC classes VWMenu_EventSink, VWParametric_EventSink, VWTool_EventSink, and VWVSFunctions_EventSink, there should not be any changes needed for your plugins as they are reflected internally.

IMenuEventSink

virtual Sint32 VCOM_CALLTYPE Execute(MenuMessage* message) = 0;

IParametricEventSink

virtual Sint32 VCOM_CALLTYPE Execute(ParametricMessage* message) = 0;

IToolEventSink

virtual Sint32 VCOM_CALLTYPE Execute(ToolMessage* message) = 0;

IVSFunctionsEventSink

virtual Sint32 VCOM_CALLTYPE Execute(Sint32 action, PluginLibraryArgTable* argumentTable) = 0;

The new Execute functions accept a base structure type that represents the message and this structure carries the action identifier. Then for each message there is a separate structure type that carries information about the message. For comparison older event handlers must recognize the event by action and they cast generic long numbers into appropriate data for the message.

Migrating you code to the new event sinks

Event though there are new structures representing the messages, there is a direct relation between the old constants and the new data structures, so for the most part translation requires just change of types.

Here is a very simple example of ILegacyEventSink of a menu command that will be translated over to SDK 2015.


The old code: 

class CMyMenuCommand_EventSink : public ILegacyEventSink
{
public:
       virtual long VCOM_CALLTYPE LegacyMain(long action, long message1, long message2)
       {
              long result = 0;
              switch ( action )
              {
                     case kMenuDoInterface:
                     {
                           MenuChunkInfo*            chunkInfo = (MenuChunkInfo*) message;
 
                           RunMyMenuCode( chunkInfo->chunkIndex );
 
                     } break;
              }
 
              return result;
       }
};

And here is the new converted code. Note that it uses action again, but this time the constant for the action is inside the data structure associated with this event. At the end of this document is a table with all events and their corresponding structures. 

class CMyMenuCommand_EventSink : public IMenuEventSink
{
public:
       virtual Sint32 VCOM_CALLTYPE Execute(MenuMessage* message)
       {
              long result = 0;
              switch ( message->fAction )
              {
                     case MenuDoInterfaceMessage::kAction:
                     {
                           MenuDoInterfaceMessage*  chunkInfo = dynamic_cast<MenuDoInterfaceMessage*>( message );
 
                           RunMyMenuCode( chunkInfo->chunkIndex );
 
                     } break;
              }
 
              return result;
       }
 

};

Note that in this example the type MenuDoInterfaceMessage that corresponds to the constant is actually deriving from MenuChunkInfo so it can be safely cast to that too. This means that if less code change is required, in this case you can also cast like this: 

MenuChunkInfo* chunkInfo = dynamic_cast<MenuChunkInfo*>( message );

Table of Message Correspondence

These are three tables displaying the correspondence between the old action constants and the data they carry in the messages, and the new data structures.

Menu Event Sink Messages

Old Constant Old Message 1 Old Message 2 New Message Structure New Message Constant
kMenuDoInterface MenuChunkInfo* MenuDoInterfaceMessage MenuDoInterfaceMessage::kAction
kMenuAddItems MenuChunkInfo* MenuAddItemsMessage MenuAddItemsMessage::kAction
kMenuChunkHilite MenuChunkInfo* MenuCheckHiliteMessage MenuCheckHiliteMessage::kAction
kMenuNotify status id MenuNotifyMessage MenuNotifyMessage::kAction
kMenuHandleToolAction MenuToolActionHandlerParams* MenuToolActionHandlerParams MenuToolActionHandlerParams::kAction
kMenuItemDisplayContextualHelp MenuChunkInfo* MenuItemDisplayContextualHelpMessage MenuItemDisplayContextualHelpMessage::kAction
kMenuItemEnabled chunk index MenuItemEnabledMessage MenuItemEnabledMessage::kAction
kMenuItemCheck MenuItemSpec* MenuItemSpec MenuItemSpec::kAction

Note that MenuChunkInfo is the base structure of the new message structures for the messages that used to have Message 1 as MenuChunkInfo.

Parametric Object Event Sink Messages

Old Constant Old Message 1 Old Message 2 New Message Structure New Message Constant
kParametricRecalculate Parametric Handle ParametricRecalculate ParametricRecalculate::kAction
kParametricPreference Parametric Handle Format Handle ParametricPreferencesMessage ParametricPreferencesMessage::kAction
kObjOnInitXProperties Parametric Handle CodeRefID ParametricInitXPropsMessage ParametricInitXPropsMessage::kAction
kObjOnSpecialEditID Parametric Handle TObjectEditReason* ParametricSpecialEditMessage ParametricSpecialEditMessage::kAction
kObjOnDM_Select Parametric Handle ParametricDMMessage ParametricDMMessage::kAction_Select
kObjOnDM_Cancel Parametric Handle pick index ParametricDMMessage ParametricDMMessage::kAction_Cancel
kObjOnDM_MouseDown Parametric Handle ParametricDMMessage ParametricDMMessage::kAction_MouseDown
kObjOnDM_Draw Parametric Handle pick index ParametricDMMessage ParametricDMMessage::kAction_Draw
kObjOnDM_Complete Parametric Handle pick index ParametricDMMessage ParametricDMMessage::kAction_Complete
kObjOnDM_GetCursor Parametric Handle pick index ParametricOnDM_GetCursorMessage ParametricOnDM_GetCursorMessage::kAction
kObjOnDM_ModeEvent Parametric Handle mode group ParametricOnDM_ModeEvent ParametricOnDM_ModeEvent::kAction
kObjOnDM_GetStatus Parametric Handle ParametricDMMessage ParametricDMMessage::kAction_GetStatus
kObjOnDM_CustomBarEvent Parametric Handle CustomBarEventData* ParametricCustomBarMessage ParametricCustomBarMessage::kAction_OnDM
kObjOnDM_BeginPauseEvent Parametric Handle ParametricDMMessage ParametricDMMessage::kAction_BeginPauseEvent
kObjOnDM_EndPauseEvent Parametric Handle ParametricDMMessage ParametricDMMessage::kAction_EndPauseEvent
kObjOnDM_MouseMove Parametric Handle pick index ParametricDMMessage ParametricDMMessage::kAction_MouseMove
kObjOnObjectUIButtonHit Parametric Handle button id ParametricUIButtonHitMessage ParametricUIButtonHitMessage::kAction
kObjOnCursor_MouseDown Parametric Handle pick index ParametricCurosrMessage ParametricCurosrMessage::kAction_MouseDown
kObjOnCursor_Complete Parametric Handle pick index ParametricCurosrMessage ParametricCurosrMessage::kAction_Complete
kObjOnCursor_MouseMove Parametric Handle pick index ParametricCurosrMessage ParametricCurosrMessage::kAction_MouseMove
kObjOnCursor_Draw Parametric Handle pick index ParametricCurosrMessage ParametricCurosrMessage::kAction_Draw
kObjOnCursor_Cancel Parametric Handle pick index ParametricCurosrMessage ParametricCurosrMessage::kAction_Cancel
kObjOnCursor_CustomBarEvent Parametric Handle CustomBarEventData* ParametricCustomBarMessage ParametricCustomBarMessage::kAction_OnCursor
kObjOnWidgetPrep Parametric Handle OnObjectWidgetPrepCall* OnObjectWidgetPrepCall OnObjectWidgetPrepCall::kAction
kObjOnCommand Parametric Handle ObjectCommand* ObjectCommand ObjectCommand::kAction
kObjOnGetToolName Parametric Handle TXString* toolName ParametricGetToolNameMessage ParametricGetToolNameMessage::kAction
kObjOnAddState Parametric Handle ObjectState* ObjectState ObjectState::kAction
kObjOnContextMenuInit Parametric Handle ObjectContextMenuEvent* ObjectContextMenuEvent ObjectContextMenuEvent::kAction_Init
kObjOnContextMenuEvent Parametric Handle ObjectContextMenuEvent* ObjectContextMenuEvent ObjectContextMenuEvent::kAction_Event
kObjOnWidgetValueUpdate Parametric Handle OnObjectWidgetValueCall* OnObjectWidgetValueCall OnObjectWidgetValueCall::kAction
kObjOnEyedropperPrepareCopy Parametric Handle Record Handle ParametricEyeDropperMessage ParametricEyeDropperMessage::kAction_PrepareCopy
kObjOnEyedropperAfterCopy Parametric Handle Source PIO Handle ParametricEyeDropperMessage ParametricEyeDropperMessage::kAction_AfterCopy
kObjOnGetSpecificGeometry Parametric Handle ObjctGetSpecificGeometryCall* ObjectGetSpecificGeometryCall ObjectGetSpecificGeometryCall::kAction
kToolCustomSubtypeInsert MenuToolActionHandlerParams* ParametricCustomToolMessage ParametricCustomToolMessage::kAction
kObjOnGetObjInCurtainWall Parametric Handle bool (is object in wall) ParametricGetInCurtainWallMessage ParametricGetInCurtainWallMessage::kAction
kObjOnAttributeSelect ParametricAtributeMessage ParametricAtributeMessage::kAction_Select
kObjOnAttributeCancel ParametricAtributeMessage ParametricAtributeMessage::kAction_Cancel
kObjOnAttributeMouseDown ParametricAtributeMessage ParametricAtributeMessage::kAction_MouseDown
kObjOnAttributeDraw ParametricAtributeMessage ParametricAtributeMessage::kAction_Draw
kObjOnAttributeMouseMove ParametricAtributeMessage ParametricAtributeMessage::kAction_MouseMove
kObjOnAttributeComplete ParametricAtributeMessage ParametricAtributeMessage::kAction_Complete
kObjOnAttributeGetCursor ParametricAtributeMessage ParametricAtributeMessage::kAction_GetCursor
kObjOnAttributeMove2D ParametricAtributeMove2DMessage ParametricAtributeMove2DMessage::kAction
kObjOnAttributeGetStatus ParametricAtributeMessage ParametricAtributeMessage::kAction_GetStatus
kObjOnAttributeModeEvent ParametricAtributeModeMessage ParametricAtributeModeMessage::kAction
54 ParametricAtributeModeMessage ParametricAtributeMessage::kAction_ToolSetDown
56 ParametricAtributeModeMessage ParametricAtributeMessage::kAction_ToolSelectionChange
57 ParametricAtributeModeMessage ParametricAtributeMessage::kAction_ToolPlanarSnapFiltering

Tool Event Sink Messages

Old Constant Old Message 1 Old Message 2 New Message Structure New Message Constant
kToolDoSetup kSetupSetdownPauseRestoreFlag ToolSetupMessage ToolSetupMessage::kAction_SetUp
kToolDoSetDown kSetupSetdownPauseRestoreFlag ToolSetupMessage ToolSetupMessage::kAction_DetDown
kToolGetCursor TXString* cursorImageSpec kMouseCursorManagerSpecifierRequest ToolGetCursorMessage ToolGetCursorMessage::kAction
kToolDoInterface
kToolDoModeEvent mode group mode button ToolModeMessage ToolModeMessage::kAction
kToolDoDoubleClick ToolMessage ToolMessage::kAction_DoDoubleClick
kToolPointAdded WorldPt* ViewPt* ToolPointAddedMessage ToolPointAddedMessage::kAction
kToolMouseMove ToolMessage ToolMessage::kAction_MouseMove
kToolDrawingDoubleClick ToolMessage ToolMessage::kAction_DrawingDoubleClick
kToolDraw ToolMessage ToolMessage::kAction_Draw
kToolHandleComplete handle, sometimes? ToolCompleteMessage ToolCompleteMessage::kAction
kToolGetStatus ToolMessage ToolMessage::kAction_GetStatus
kToolPointRemoved kClearingAllToolPoints ToolPointRemovedMessage ToolPointRemovedMessage::kAction
kToolGenericStateChange kTool GenericStateChangeKey or kToolGenericStateChangeView ToolGenericStateChangeMessage ToolGenericStateChangeMessage::kAction
kToolOnInitXProperties tool index ToolInitXPropsMessage ToolInitXPropsMessage::kAction
kToolOnSelectionChange ToolMessage ToolMessage::kAction_OnSelectionChange
kToolOnMoveSelection2D WorldPt* offset Boolean nudging ToolMoveSel2DMessage ToolMoveSel2DMessage::kAction
kToolOnIdleEvent ToolMessage ToolMessage::kAction_OnIdle
kToolOnCustomBarEvent CustomBarEventData* CustomBarEventData CustomBarEventData::kAction
kToolProvideObjectGrips Boolean* isMultiSel ToolProvideObjGripsMessage ToolProvideObjGripsMessage::kAction
kToolInitByObject object Handle ToolInitByObjectMessage ToolInitByObjectMessage::kAction
kToolOnViewChange ToolMessage ToolMessage::kAction_OnViewChange
kOnUpdate2D3DCursor ToolMessage ToolMessage::kAction_OnUpdate2D3DCursor
kOnGetWantsAutoPlane ToolMessage ToolMessage::kAction_OnGetWantsAutoPlane
kOnGetWantsPlanarSnapFiltering ToolMessage ToolMessage::kAction_OnGetWantsPlanarSnapFiltering
kToolGetCursorSpecifier TXString* cursorImageSpec ToolMessage ToolMessage::kAction_GetCursor
kToolPreventsSnapLoupe ToolMessage ToolMessage::kAction_PreventsSnapLoupe
kToolSupportsScreenPlane ToolMessage ToolMessage::kAction_SupportsScreenPlane
kToolOnDeleteKeyWithNoToolPts ToolMessage ToolMessage::kAction_OnDeleteKeyWithNoToolPts
kToolOnEscapeKeyWithNoToolPts ToolMessage ToolMessage::kAction_OnEscapeKeyWithNoToolPts
kDefaultTool_UpdatePreviewObject object Handle ToolDefaultPreviewUpdateMessage ToolDefaultPreviewUpdateMessage::kAction
kToolDoDrawScrMod ToolMessage ToolMessage::kAction_DoDrawScrMod
kToolDoUndrawScrMod ToolMessage ToolMessage::kAction_DoUndrawScrMod

Resource Related Changes

More details can be found here Vectorworks VWR Resources.

Since Vectorworks 2015 no longer supports qtr files, the SDK has been updated to reflect that.

First of all, the numeric system of accessing resources has been declared legacy and new APIs were added to support transition of old plug-ins.

The biggest change is that the TXString(short,short) constructor for reading resources was removed. Instead, a new class was added to allow for reading legacy resources (based on numbers) 

TXString title = TXLegacyResource( 11000, 1 )

This legacy class can be used to read String and TEXT resources. This is purely to help transition old plug-ins, and its use should be avoided for future code.

This works because plugins with SDK 2015 must specify a DefaultPluginVWRIdentifier function that returns the resource file for this plug-in. Typically, this function is defined in your main function right above the plugin_module_main function.

Note, that your plug-in will not link if you don't provide this function.

Similarly, there is TXResource class to read resources identified by path. 

TXString title = TXResource( "Sample Plugin/Strings/DlgSettings", "title" );

However, it could be very tedious to specify full paths for every string use. The SDK provides a simpler approach: 

TXString title = TXResStr( "DlgSettings", "title" );

This will work because of the DefaultPluginVWRIdentifier function.

Retrieved from "http://developer.vectorworks.net/index.php?title=Plug-In_Modules_in_SDK_2015&oldid=19554"