VS:CallTool

.VectorScript|VectorScript ..VS:Function Reference|Function Reference ..VS:Function_Reference_Appendix|Appendix

Description

Activates the specified VectorWorks tool for a single use. After the tool has been used VectorWorks will revert back to the previously active tool.

Note: Please refer to the Appendix for specific tool ID values.

PROCEDURE CallTool(
          toolID   :INTEGER);

def vs.CallTool(toolID):
    return None

Parameters

toolID

INTEGER

VectorWorks tool constant.

Remarks

(_c_, 2022.01.19) Tested in VW 2021 and 2022: In Python VS:CallTool needs a dummy second parameter. This is probably a regression.

vs.CallTool( -221 ) # error
vs.CallTool( -221, any ) # 'Any' is and does absolutely nothing

Older comments whose authors are lost:

Changes the active tool to that specified by toolID. Waits until the user has executed the functionality of that tool, then switches back to the previously active tool & returns.

I found that if you have a plug-in that uses the CallTool procedure to create an object (specifically a freehand poly) while you are in a group or editing a symbol definition, you cannot get the handle to the poly using the standard functions LNewObj, LSActLayer, LObject or any other I can think of.

I think I found a foolproof (?) solution:

1. Create a dummy object and get its handle (dummyH.)
2. Implement the CallTool procedure and create the poly.
3. Use "polyH := NextObj (dummyH)" to get the handle to the poly.
4. Delete the dummy object.

This works in nested groups as well as groups within symbols. If anyone knows of a simpler solution, please let me know.

Another method is to do a DSelectAll at the beginning of the program, and then you should be able to find the last created entity by searching for selected items (ForEachObject(MyProcedure, (SEL=TRUE))), assuming that the object created by the tool is still selected. Depending on what you're doing, this may be simpler, but it's certainly a bit scarier.

If the user drops the tool then no object will be created and NextObj(DummyObj) will be NIL.

Example

VectorScript

PROCEDURE Example;
VAR
h1, h2, h3 :HANDLE;
int :INTEGER;
BEGIN
DSelectAll; BeginXtrd(0, 1); CallTool(-203); h1 := FSActLayer; EndXtrd;
DSelectAll; BeginXtrd(0, 1); CallTool(-203); h2 := FSActLayer; EndXtrd;
int := AddSolid(h1, h2, h3);
END;
RUN(Example);

VectorScript

PROCEDURE AddSurfaceExample;
VAR
	h1, h2, h3 :HANDLE;
BEGIN
	DSelectAll;
	CallTool(-203);
	h1 := FSActLayer;
	DSelectAll;
	CallTool(-203);
	h2 := FSActLayer;
	h3 := AddSurface(h1, h2);
	IF h3 <> nil THEN SetFPat(h3, 5);
END;
RUN(AddSurfaceExample);

Python

The python code will not pause for the execution of CallTool, that's why it uses a callback mechanism for the script to know when the temp tool has finished.

# this will not be called prior Vectorworks 2022 SP3
# as the calback functions will not be executed prior to that version
def Example():
	vs.DSelectAll()

	def resultCallback1():
		h1 = vs.FSActLayer()
		vs.DSelectAll()
		
		def resultCallback2():
			h2 = vs.FSActLayer()
			h3 = vs.AddSurface(h1, h2)
			if h3 != None :  
				vs.SetFPat(h3, 5)
		
		
		vs.CallTool(-203, resultCallback2)
			
	vs.CallTool(-203, resultCallback1)

Example()

PushAttrs;
PenFore(16);
PenBack(0);
PenPat(-2);
CallTool(-201);
PopAttrs;

Version

Availability: from MiniCAD 4.0

See Also

VS Functions:

• VS:CallToolByIndex
• VS:CallToolByName

VS Functions:

• [[VS:CallToolByIndex]]
• [[VS:CallToolByName]]