SDK:Tool Plug-in Resources
.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
Tool Definition Resource
Every tool has a TDef resource of ID 128. Each of the fields of the TDef resource are described below:
TDef
Definition
type 'TDef' {
boolean pickAndUpdate, // disablePickUpdate
disablePickUpdate;
boolean doesntNeedScreenPlane, // needsScreenPlane
needsScreenPlane;
boolean doesntNeed3DView, // needs3DView
needs3DView;
boolean use2DCursor, // uses3DCursor
use3DCursor;
boolean constrainCursor, // screenBasedCursor
screenBasedCursor;
boolean doesntNeedPerspective, // needsPerspective
needsPerspective;
boolean showScreenHints, // dontShowScreenHints
dontShowScreenHints;
boolean reservedFalse, // unused
reservedTrue;
byte; // rest of tool flags
integer; // Icon ID
integer kFingerCurs=90, // Default Cursor ID
kFourWayCurs=93,
kTextCurs=101,
kSmallCrossCurs=103,
kLargeCrossCurs=105,
kDashCrossCurs=106,
kBucketCurs=126,
kRotateCurs=133,
kHandCurs=145,
kArrowCurs=147,
kBullsEyeCurs=154,
kHorizArrowsCurs=400;
pstring[255]; // messageStr
integer; // WaitMove distance
longint; // Constraint flags
integer kNoDataBar, // barDisplay mode
kXYClLaZo=1,
kXY,
kSaAaLAXY,
kDxDyRaAXY,
kDxDyTlAXY,
kDxDyRXY,
kDxDyLAXY,
kDxDyArPeXY,
kA=9,
kDxDyLOXY,
kDxDySxSyXY,
kXYZClLaZo,
kVxVyVzYaPi=13,
kVz,
kDa,
kAzEl,
kAzElRo,
kVxVyVzLrUdIo,
kU1Aw,
kThXYZ,
kO1O2WrWhZ,
kWbWtDz,
kXYU1,
kRaRrRuXYZ,
kClLaZo;
integer; // Minimum compatible version
pstring[63]; // Title String
unsigned integer; // mode flags
unsigned longint; // product flags
unsigned integer; // version created
unsigned integer; // version modified
unsigned integer; // version retired
};
Example
resource 'TDef' (128, "Tool") {
/* pickAndUpdate, disablePickUpdate */ pickAndUpdate,
/* doesntNeedScreenPlane, needsScreenPlane */ needsScreenPlane,
/* doesntNeed3DView, needs3DView */ doesntNeed3DView,
/* use2DCursor, use3DCursor */ use2DCursor,
/* constrainCursor, screenBasedCursor */ constrainCursor,
/* doesntNeedPerspective, needsPerspective */ doesntNeedPerspective,
/* showScreenHints, dontShowScreenHints */ showScreenHints,
/* reservedFalse, reservedTrue */ reservedFalse,
/* rest of tool flags */ 0,
/* Icon ID */ 11000,
/* Default Cursor ID */ 0,
/* messageStr */ "Click to place a ...",
/* WaitMove distance */ 0,
/* Constraint flags */ 0,
/* barDisplay mode */ kXYClLaZo,
/* Minimum compatible version */ 900,
/* Title String */ "VWPluginWiz1 Tool:Tool",
/* mode flags */ 0,
/* product flags */ 0,
/* version created */ 0,
/* version modified */ 0,
/* version retired */ 0
};
Fields
disablePickUpdate
When set to true, the automatic updating of the Tool Pick Record is disabled.
Normally, as the mouse is moved over the document, VectorWorks automatically finds out what objects are near the mouse for the kToolDoPick action. This may take a significant amount of time on large documents.
Tools which do not need this functionality, such as pure creation tools, should set this flag.
needsPlan
If a tool requires the current projection to be set to plan, set this flag.
needs3DProjection
If a tool requires a non-plan projection, set this flag.
uses3DCursor
Tools that operate using 3D grid and snapping points should set this flag.
screenBasedCursor
Activating this flag disables all gridding and snapping of the mouse when functions such as GetCoords are called.
dontShowScreenHints
Tools for which the smart mouse screen hints are not useful can turn off the display of those messages by setting this flag.
iconID
The iconID field indicates the resource ID of the icon to be displayed in the tool palette, which should also be included in the resource file. (See “Tool Icon” below for information on including a PNG format icon.)
defaultCursID
If the Tool definition function returns 0 in response to a kToolDoPick message, then VectorWorks sets the cursor to the one specified by defaultCursID.
messageStr
When the tool is selected (before the kToolDoSetup message has been passed to the definition function) this string is set into the message bar.
waitMoveDist
For many tools, a good user interface allows a bit of “slop” before the tool actually takes effect.
The value of waitMoveDist is a distance in screen pixels that the mouse must move before VectorWorks calls the tool definition function. If this distance is not exceeded before the tool click is finished, then a selection tool is automatically made active.
constraintFlags
This bit-field determines which cosntraints the user has available when the tool is active.
Each bit represents one of the constraints, with 1 indicating an available constraint. For the 10 current constraints, adding together a combination of the following values will enable the appropriate constraints:
| 1 | Snap to Grid |
| 2 | Snap to Objects |
| 4 | Snap to Surface/Working Plane |
| 8 | Snap to Intersection |
| 16 | Snap to Distance |
| 32 | Constrain Parallel |
| 64 | Constrain Perpendicular |
| 128 | Constrain to Angle |
| 256 | Constrain Symmetrical |
| 512 | Constrain Tangent/to Working Plane Normal |
For example, to activate only the Snap to Grid and the Snap to Intersection constraints, set constraintFlags = 1+8 = 9.
VectorWorks tools generally fall into one of three "families" of constraint availability depending upon which type of geometry the user is setting: points (locus tool), lines (segment tool, polygon tool), or boxes (ellipse by rectangle tool and rectangle tool). One of these three sets of constraints flags often contains the correct constraintFlags for new tools.
Min Version
This field holds the earliest version of VectorWorks that will properly run a plug-in.
Each callback contains the version of VectorWorks that first supported it, put the latest callback version in the Min Version field.
Databar Mode
When the user clicks into the document, VectorWorks sets the Data Display Bar to the mode specified in this field. The file MiniCadCallbacks.h lists the available constants. If the plug-in does not need to change the Data Display Bar or needs to set a custom set of bars, set this field to 0.
Version Created
This field should contain the version number for which the tool was created. For example, 11 signifies VectorWorks 11, 13 signifies VectorWorks 2008.
This information will be used by the Workspace Editor so that a user may see at a glance all of the new tools.
Version Modified
This field should contain the version number for which an existing tool was significantly modified. For example, 11 signifies VectorWorks 11, 13 signifies VectorWorks 2008.
Although not used currently, this information could be used by the Workspace Editor so that a user may see at a glance all of the modified tools.
Version Retired
This field should contain the version number for which an existing tool was retired or replaced. For example, 11 signifies VectorWorks 11, 13 signifies VectorWorks 2008.
This information will be used by the Workspace Editor so that a user may see at a glance all of the retired tools.
Tool Icon
All Plug-in Tools should include an icon for the tool palette. For VectorWorks 2008 and later, the icon must be 26 x 20 pixels, in PNG format, and should include an alpha channel. The contents of the PNG file should be stored in a Macintosh resource with the resource type 'PNG ' (Note the ending space character). The resource ID of the icon must be in the range 11000 – 14999, inclusive, and match the corresponding field in the TDef resource.
The PNG file may be inserted into the Macintosh resource file using a resource editor. Alternatively, if you use Rez to generate your resource file from a ".r" file, use can use the following command to include the PNG file:
read 'PNG ' (11000, "Icon") "MyIcon.png";
Plug-in Tools may also include a traditional ‘ICN#’ and an ‘icl8’ resource to define the black-and-white and 8-bit color icons. These old-style icons should be 32 x 32, but only the central 26 x 20 pixels will be displayed.
Remarks
If you need to create 2D/3D tool that will remain the mode the document currently is, you need to specify 'doesntNeedPlan' and 'doesntNeed3DProjection' also to specify'use2DCursor':
resource 'TDef' (128, "Tool") {
/* pickAndUpdate, disablePickUpdate */ pickAndUpdate,
/* doesntNeedPlan, needsPlan */ doesntNeedPlan,
/* doesntNeed3DProjection, needs3DProjection */ doesntNeed3DProjection,
/* use2DCursor, use3DCursor */ use2DCursor,
/* constrainCursor, screenBasedCursor */ constrainCursor,
/* doesntNeedPerspective, needsPerspective */ doesntNeedPerspective,
/* showScreenHints, dontShowScreenHints */ showScreenHints,
/* reservedFalse, reservedTrue */ reservedFalse,
Then during setup of the tool, you have to put 3D cursor if the view is not plan view (otherwise it will be 2D cursor by default and 3D points tool API wont work)
case kToolDoSetup: {
bool bAlready2D = false;
const short nView = gSDK->GetCurrentView();
if ( nView == viewTop ) {
const short nProjection = gSDK->GetProjection( gSDK->GetCurrentLayer() );
bAlready2D = ( nProjection == plan );
}
if ( ! bAlready2D ) {
// the view is not in plan mode, so we want to use 3D cursor
Boolean use3DCursor = true;
gSDK->SetProgramVariable( varUse3DCursor, (void*) & use3DCursor );
}
See Also
Overview | SDK:Tool Plug-in Resources | SDK:Tool Plug-in Main Function | SDK:Tool Plug-in Events