SDK:Custom Tool Highlighting

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

The tools may provide visual feedback to the user of graphical elements involved in the tool behavior.

For example the "Fillet" tool will highlight the segment that can be used as reference which moving the mouse over it:

When the "Fillet" tool is activated the tool sets the cursor according to what object and what object part lies below the mouse location.

When the cursor is over linear segment of an object that can be used for fillet tool, the tool provides small arrow like cursor to indicate that and also provides visual feedback (highlighting) geometry to visualize where this linear segment is.

This way the user can visually be sure what will happen when he or she clicks.

Providing Highlighting

The visual feedback highlight could be considered as additional to the cursor providing mechanism.

The recognition of the situation where visual feedback should be shown is up to the tool to determine the same way as it determines what cursor to be set.

Highlighting is provided during kToolGetCursor tool event using the following VCOM:VectorWorks:ISDK functions:

• ISDK::EmptyToolHighlightingList - Clears current highlighting visual feedback.
• ISDK::AddToolHighlighting - Adds existing object's handle as a highlighting visual feedback.
• ISDK::AddToolHighlightingSegment - Adds 2D linear segment as highlighting visual feedbac.
• ISDK::AddToolHighlightingPolyCreate - Creates 2D polygon definition for highlighting visual feedback.
• ISDK::AddToolHighlightingPoly - Adds previously created and initialized 2D polygon definition as highlighting visual feed back.
• ISDK::AddToolHighlightingPolyAddVertex - Adds a point to 2D polygon definition for highlighting visual feed back.
• ISDK::AddToolHighlightingSegment3D - Adds 3D linear segment as highlighting visual feed back.
• ISDK::AddToolHighlightingPoly3DCreate - Creates 3D polygon definition for highlighting visual feed back.
• ISDK::AddToolHighlightingPoly3D - Add previously created and initialized 3D polygon definition as highlighting visual feed back.
• ISDK::AddToolHighlightingPoly3DAddVertex - Adds point to 3D polygon definition for highlighting visual feed back.

The first thing to do in kToolGetCursor event handler is to clear the highlight list. Also you must clear the list at the end of kToolDoSetDown too.

Also the tool should check if the option for showing tool highlighting is on.

case kToolGetCursor: {
        // cleanup the highlighting list for interactive tool behavior interaction
        gSDK->EmptyToolHighlightingList();

	// we want tool behaviour interaction if it is enabled by the settings
	Boolean  bUseToolHighlighting = false;
	gSDK->GetProgramVariable( varToolHighlighting, & bUseToolHighlighting );

	short            overPart;
	long             code;
	MCObjectHandle   hOverObj; 
	gSDK->TrackTool( hOverObj, overPart, code);

        // do highlighting 
        if ( bUseToolHighlighting  && hOverObj ) {
            // ... in this case we just highlight
            // the underlying object for visual feedback
            gSDK->AddToolHighlightingObject( hOverObj );
        }

        // return appropriate cursor
        retVal = hOverObj ? kPickObjCURSID : kNoObjCURSID;
    } break;

case kToolDoSetDown: {

        // ...

        // clear tool behavior indication highlighting
        gSDK->EmptyToolHighlightingList();

    } break;

Highlighting Geometry

There are several ways for providing geometry for the highlighting visual feed back:

Existing Objects

Using ISDK::AddToolHighlighting you can pass in SDK:MCObjectHandle so that object will be used to create the highlighting geometry.

gSDK->AddToolHighlightingObject( hMyObject );

Line Segments

For 2D segments use ISDK::AddToolHighlightingSegment.

gSDK->AddToolHighlightingSegment( WorldPt(0,0), WorldPt(100,100) );

For 3D segments use ISDK::AddToolHighlightingSegment3D.

gSDK->AddToolHighlightingSegment3D( WorldPt3(0,0,10), WorldPt3(100,100,20) );

Poly Geometry

For 2D polys first create the poly ISDK::AddToolHighlightingPolyCreate, add the points to it ISDK::AddToolHighlightingPolyAddVertex and then add the poly as visual feedback ISDK::AddToolHighlightingPoly.

long	polyID	= gSDK->AddToolHighlightingPolyCreate();
for(...) {
    gSDK->AddToolHighlightingPolyAddVertex( polyID, vertex.pt, vertex.type, vertex.dRadius );
}

// Add the polygon as highlight visual feed back
gSDK->AddToolHighlightingPoly( polyID, true );

For 3D polygons first create the polygon ISDK::AddToolHighlightingPoly3DCreate, add the points to it ISDK::AddToolHighlightingPoly3DAddVertex and then add the polygon as visual feedback ISDK::AddToolHighlightingPoly3D.

long	poly3DID	= gSDK->AddToolHighlightingPoly3DCreate();
for(...) {
    gSDK->AddToolHighlightingPoly3DAddVertex( poly3DID, vertex.pt3 );
}

// Add the polygon as highlight visual feed back
gSDK->AddToolHighlightingPoly3D( poly3DID, true );