SDK:Tutorial An Extension Implementation
.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
Prev: Tutorial Module Main | Next: A Menu Command
An Extension
An extension is a specific VCOM interface implementation that Vectorworks can work with. It is specific because all extension interfaces inherit on IExtension common interface. The IExtension inherits IVWUnknown which makes it a VCOM interface.
The only purpose of the extension is to provide the necessary information to Vectorworks that will identify this extension. There are four different types of extensions but they all share common data:
- Universal Name -- unique name used by Vectorworks to recognize this extension. For the different types of extensions this name is used differently. For example the menu command extension universal name is used by the workspace file definition. The parametric universal name is the string you use when a new instance of that parametric is created.
- Version -- currently this is not used.
- Event Sink -- eventing mechanism explained later.
Then each extension requires more information. It is recommended to use the SDK wrapper classes of the extension. Each wrapper class receives a specific data used to initialize the extension. A common parameter could be of type 'SSTRResource' which are two numbers identifying STR# string resource. This is used in the cases where the string needs to be localizable.
Menu Extension
This extension is represented by the SDK class VWExtensionMenu. It defines a menu command that can be put into the Vectorworks workspace.
Some of the menu command specific data is:
- Title -- the localized name of the menu. This is the name that will be displayed in the workspace.
- Category -- the name of the category which will contain the menu command in the workspace editor.
- Help text -- a short description of what the command does.
- Contextual help ID -- an identifier to the page in the Vectorworks help system.
- Needs flags -- flags determining the state of the menu command. For example you can define the command to be disabled if nothing is selected in the document.
- Version info -- information about when the menu command was created or removed. This will help the workspace editor to place the menu command in the proper version group.
This data is defined by creating an instance of structure SMenuDef and passing it to the constructor of VWExtensionMenu.
Parametric Extension
This extension is represented by the SDK class VWExtensionParametric. It defines a parametric object that can be created in the Vectorworks document. Note, this is not the tool used to create the object, this is the object itself.
Some of the parametric specific data is:
- Localized name -- the name that shows up on the Object Info Pane (OIP) when the object is selected.
- Object type -- is this a point parametric object, or a more complex one: line, rectangle, 2D polyline, or 3D polyline.
- Reset properties -- when the object is regenerated.
- Wall insertion options
This data is defined by creating an instance of structure SParametricDef and passing it to the constructor of VWExtensionParametric.
Tool Extension
This extension is represented by the SDK class VWExtensionTool. It defines a tool that can be put into the Vectorworks workspace.
Some of the tool specific data is:
- Type --
- Title -- the localized name of the menu. This is the name that will be displayed in the workspace.
- Category -- the name of the category which will contain this tool in the workspace editor.
- Help text -- a short description of what the command does. This description can contain two new lines symbols ('\n\n') to specify a longer description of the tool.
- Message -- a message that shows up on the data bar when the tool is active.
- Contextual help ID -- an identifier to the page in the Vectorworks help system.
- Version info -- information about when the tool was created or removed. This will help the workspace editor to place the tool in the proper version group.
This data is defined by creating an instance of the structure SToolDef and passing it to the constructor of VWExtensionTool.
VectorScript Functions Extension
This extension is represented by the SDK class VWExtensionVSFunctions. It allows adding functions to the VectorScript engine to use.
The class uses an array of structures SDK:SFunctionDef which defines each function provided by this extension:
An Event Sink
An menu extension instance will define a menu command, for example. But when Vectorworks needs to send events (what happened) to that extension it uses the event sinking mechanism. For example, the most primitive event is 'DoInterface' that is sent out when a menu command is executed.
Another way of thinking about event sinks is that they define an 'ability' for the extension. So, a menu command is 'able' to be executed and that event sink instance is what will run.
So, an extension can have many 'abilities' each of which is identified by its own TSinkIID universal unique identifier. When ever Vectorworks needs to send an event to the extension, first it checks if that extension supports this event sink by requesting an instance of a sink with the specified TSinkIID. If the extension doesn't support it, then it returns NULL. Otherwise it will return a pointer to an instance of the corresponding sink implementation.
Each extension have specific sinks dedicated for working with it.
Menu Command
The menu commands main sink is VWMenu_EventSink. A client will create a class inheriting this sink to define what happens when the menu command is executed.
Another less common event sink is the IMenuChunkProvider sink that is encapsulated inside the extension class VWExtensionMenu for simplicity. This event sink defines the menu command to be a group of menu items that show up together in the workspace. The constructor of the extension receives an instance of SMenuChunkDef.
Parametric Object
The main event sink for a parametric is VWParametric_EventSink. It responds to a variety of events associated with the parametric object. The most important being 'Recalculate' which is called when the parametric needs to update its visual appearance.
Another important event sink is the IParametricParamsProvider that is encapsulated inside the extension class VWExtensionParametric for simplicity. This event sink defines the parameters of the parametric object and for that the extension constructor of the extension receives an array of SParametricParamDef.
Tool
The main event sink for a tool is VWTool_EventSink. It responds to a variety of events associated with a tool.
VectorScript Function
The main event sink for VectorScript functions provider is VWVSFunctions_EventSink. It responds to the event when a function is being called from the VectorScript engine.