SDK:Tutorial

From Vectorworks Developer
Jump to: navigation, search

.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

Next: Module Main

Basics

The Vectorworks SDK is available for free download at http://www.vectorworks.net/support/custom/sdk

The Vectorworks SDK uses C++ language to develop extension functionality. To compile SDK plug-in you need VisualStudio 2005 for Windows, and XCode 3.2 for Mac.

A Vectorworks plug-in developer has to be familiar with Object Oriented Programming using C++ in order to understand the concepts used in the Vectorworks SDK.

What is a Vectorworks SDK Plug-in

A Vectorworks SDK plug-in is a dynamic library with separate resources.

On Windows the plug-in is a Dynamic-Link Library File (http://msdn.microsoft.com/en-us/library/ms682589(VS.85).aspx) that has its file extension changed to '.VLB'. The resources associated with this plug-ins are inside a '.QTR' file with the same name as the name of the Dynamic-Link Library file. The resource file is produced by the 'Rez.exe' tool, part of the Quick Time SDK. This tool can compile '.r' files into a '.qtr' file. This file could be also edited on Mac using Rezilla tool.

On Mac the plug-in is a bundle containing a dynamic library and the resource file again as '.qtr' file. The XCode has a compiler that compiles '.r' files into this file automatically. The bundle defining the plug-in should have an extension '.vwlibrary'

A plug-in is recognized as such by Vectorworks if it exist inside the 'Plug-ins' folder found at the same level as the Vectorworks executable.

  • On Windows a plug-in is composed of two files: <PluginName>.vlb and <PluginName>.qtr
  • On Mac a plug-in is one bundle: <PluginName>.vwlibrary

Also, plug-ins can be placed inside the users folder:

  • On Windows: C:\Users\developer\AppData\Roaming\Nemetschek\Vectorworks\2011\Plug-ins
  • ON Mac: /Users/developer/Library/Application Support/Vectorworks/2011/Plug-ins

When Vectorworks is searching for plug-ins, it will enumerate the plug-ins folder and all short-cuts (aliases) inside.

I will be using the 'TesterModule' sample provided inside 'Source' folder of the Vectorworks SDK.

Resources

Resources are localizable content for a plug-in. They can be strings, text, or images. There should always be a resource file along with a plug-in.

The resources in Vectorworks are QuickTime resource files .qtr. They are binary files files containing list of resources. Each resource has a type (Four Character Chode) and an ID (a number).

resource 'TEXT' (128, "some localizable text")
{
   "this is a resource text"
};

The resource .qtr files are produced by compiling source .r files. On Windows the tools 'Rez.exe' is used to compile them, and on Mac the XCode compiler can compile these files.

SDK developer have only three types of resources:

  • 'STR#' -- define a list of 255 character strings;
  • 'TEXT' -- resource containing unlimited length string;
  • 'PNG ' -- a PNG image resource used for icons;

More detailed information about those resource types can be found on SDK:Plug-in_Resources page.

For simplicity on Windows a custom build step is added for the main resource file. See the 'TesterModule' provided in the SDK. Right click on the 'Plugin Resource.r' file and select Preferences.

Tutorial ResourcePrefs Excluded.jpg

As you notice the samples have this file excluded from the build on windows. This is because the 'Rez.exe' utility is not redistributed with the Vectorworks' SDK. If you obtain this tool from the Quick Time SDK then you can include this file and produce the qtr resource dynamically.

On the custom tab, you can see the actual command used to compile this .r file into the .qtr files using the 'Rez.exe':

Tutorial ResourcePrefs Compile.jpg

Note: Again, this file has been excluded from the build because the Rez.exe tool is not redistributed with the Vectorworks SDK. There is a '.qtr' file already compiled provided in the sample's folder. To make the plug-in work the resource has to be present along with the Dynamic Library. To accomplish this, the samples have a post-build event that will copy this qtr into the output folder for this project:

Tutorial ResourcePrefs Copy.jpg

On XCode, the same resource .r file is added in the target in the build resource step. Since this project uses the SDK build configurations (xcconfig files) it will create the bungle and embed the resource file inside.

Tutorial ResourcePrefs Mac.jpg

Code

Output Settings

The sample project is setup so it uses relative paths. Also, the project will create all output files according to the main settings.

Tutorial CompileOutputWin.jpg

To debug under Windows, add Vectorworks.exe as the command in the 'Debug' pane.

Tutorial CompileOutputMac.jpg

To debug under Mac, add Vectorwrosk as an executable.

Note to debug on Win and Mac you have to have your output from the Visual Studio or XCode be used by Vectorworks (be inside the Plug-ins folder). Don't forget that you can put a short cut (or aliaces) in the Plug-ins folder to your output folder.

Precompiled Header File

The sample project uses Prefix (Precompiled Header) files on Win and Mac to optimize compiler speed and include dependency.

The prefix file on windows is called 'StdAfx.h' and has to be the first '#include' of each CPP file. On Mac there are two prefix files for debug and release complies. To make the prefix file OS independent there is a common header file (CommonPrefix.h) that is the actual prefix file for both platforms that is just included from the specific prefix files. This file (CommonPrefix.h) contains all the necessary SDK includes so the entire SDK API will be available in every CPP file of the project.

For example if you need more STL sclasses (like vector, or map) you should inlucd those in the prefix file, and thus have them available in the entire project.

Tutorial PrefixWin.jpg

Tutorial PrefixMac.jpg

Next Chapter

Next: Module Main

Personal tools
NamespacesFFFF

Variants
Actions
Advanced Search
See Also
Navigation
Toolbox