SDK:Tool General Info

.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 Extensions

The Vectorworks SDK can be used to develop Custom Tools. These tools will be driven by the tool extension implementation, they will not run their own event loop.

This enables Vectorworks to provide some standard behaviors across all tools, for example:

• auto zoom
• double-click switching to cursor
• deleting the most recent segment of a polygon, wall or other multiple point tool
• escaping a tool to start over without finishing current actions
• other view changes during a tool such as scroll bar keys

Register Tool Extension

Registering the extension is done in the module main function. See SDK:Plug-in Module#The Plug-in Module Environment.

This code registers a tool extension implementation class 'CExtTool' as such in the 'GROUPID_ExtensionTool' VCOM grouping (groups are used to improve the performance of Vectorworks when enumerating the available extensions):

REGISTER_Extension<TesterModule::CExtTool>( GROUPID_ExtensionTool, action, pInfo, ioData, cbp, reply );

Extension Class Definition

namespace TesterModule
{
    using namespace VWFC::PluginSupport;

Note #1, see after the code block.
    // ------------------------------------------------------------------------------------------------------
    class CTool_EventSink : public VWTool_EventSink
    {
    public:
                    CTool_EventSink(IVWUnknown* parent);
        virtual     ~CTool_EventSink();

    public:
        // Whenever tool needs to draw
        virtual void      Draw(IToolDrawProvider* pDrawProvider);
        // When tool is done getting points
        virtual void      HandleComplete();
    };

Note #2, see after the code block.
    // ------------------------------------------------------------------------------------------------------
    class CExtTool : public VWExtensionTool
    {
        DEFINE_VWExtension;
    public:
                    CExtTool(CallBackPtr cbp);
        virtual     ~CExtTool();

    };
}

• Note #1 - The class 'CTool_EventSink' is the implementation of the sink that will receive the events for the menu command. A default menu event sink is implementation of the class VWFC:PluginSupport:VWTool_EventSink
• Note #2 - The 'CExtTool' is the menu extension definition class. It is subclass of VWFC:PluginSupport:VWExtensionTool.

Extension Class Implementation

using namespace TesterModule;

namespace TesterModule
{
Note #1, see after the code block.
// --------------------------------------------------------------------------------------------------------
static SToolDef        gToolDef = {
        /*ToolType*/                    eExtensionToolType_Normal,
        /*ParametricName*/              "",
        /*PickAndUpdate*/               ToolDef::pickAndUpdate,
        /*NeedScreenPlane*/             ToolDef::doesntNeedScreenPlane,
        /*Need3DProjection*/            ToolDef::doesntNeed3DView,
        /*Use2DCursor*/                 ToolDef::use2DCursor,
        /*ConstrainCursor*/             ToolDef::constrainCursor,
        /*NeedPerspective*/             ToolDef::doesntNeedPerspective,
        /*ShowScreenHints*/             ToolDef::showScreenHints,
        /*NeedsPlanarContext*/          ToolDef::needsPlanarContext,
        /*Reserved1*/                   false,
        /*Reserved2*/                   0,
        /*IconID*/                      11300,
        /*DefaultCursorID*/             0, 
        /*Message*/                     {11300, 3},
        /*WaitMoveDistance*/            0,
        /*ConstraintFlags*/             0,
        /*BarDisplay*/                  kToolBarDisplay_XYClLaZo,
        /*MinimumCompatibleVersion*/    900,
        /*Title*/                       {11300, 1},
        /*Category*/                    {11300, 2},
        /*HelpText*/                    {11300},
        /*VersionCreated*/              16,
        /*VersoinModified*/             0,
        /*VersoinRetired*/              0,
        /*fContextualHelpID*/           ""
    };
}

Note #2, see after the code block.
// --------------------------------------------------------------------------------------------------------
// {34E91E01-64B3-4DF9-8437-6B8874C31273}
IMPLEMENT_VWExtension(
    /*Extension class*/   CExtTool,
    /*Event sink*/        CTool_EventSink,
    /*Universal name*/    "MyCustomTool",
    /*Version*/           1,
    /*UUID*/              0x34e91e01, 0x64b3, 0x4df9, 0x84, 0x37, 0x6b, 0x88, 0x74, 0xc3, 0x12, 0x73 );

Note #3, see after the code block.
// --------------------------------------------------------------------------------------------------------
// --------------------------------------------------------------------------------------------------------
CExtTool::CExtTool(CallBackPtr cbp)
    : VWExtensionTool( cbp, gToolDef )
{
}

CExtTool::~CExtTool()
{
}

Note #4, see after the code block.
// --------------------------------------------------------------------------------------------------------
// --------------------------------------------------------------------------------------------------------
CTool_EventSink::CTool_EventSink(IVWUnknown* parent)
    : VWTool_EventSink( parent )
{
}

CTool_EventSink::~CTool_EventSink()
{
}

void CTool_EventSink::Draw(IToolDrawProvider* pDrawProvider)
{
Note #5, see after the code block.
}

void CTool_EventSink::HandleComplete()
{
Note #6, see after the code block.
    VWPoint3D    pt    = this->GetToolPt3D( 0 );

    VWParametricObj    paramObj( "CExtObj", VWPoint2D(pt.x,pt.y) );
}

• Note #1 - Implementing VWFC:PluginSupport:VWExtensionTool requires use of that structure to define the menu extension. Note that that structure contains localizable strings, which are referenced by their resource IDs.
• Note #2 - A macro that identifies the sink for the extension, the universal name, and the VCOM UUID.
• Note #3 - Implementation of the custom menu extension.
• Note #4 - Implementation of the custom menu event sink.
• Note #5 - This event is used for the tool to provide custom drawing.
• Note #6 - This event is used when the tool finishes execution. In this example it creates a parametric object at the first mouse click.