RunTempTool Guide

[FMA]

 

All I know about the RunTempTool Procedure:

 

This procedure is being used to draw temporary lines as a preview before placing an object. I use it quite extensively but I have not seen a great deal of explanation and examples here or at other places which made me think it might be helpful to share what I know about it.

 

 

GENERAL

 

Examples:

Callback Function: This example is taken from the function reference. VS:RunTempTool - Vectorworks Developer

 

FUNCTION TempToolCallback(action, msg1, msg2 : LONGINT) : LONGINT;

    BEGIN

         TempToolCallback:= 0;

         CASE action OF

             3:       vstSetHelpString ( 'Just click once.' );

             103 :    BEGIN

                      vstGetCurrPt2D( pt.x, pt.y );

                      vstDrawCoordLine( pt.x, pt.y, pt1.x, pt1.y );

                      vstDrawCoordLine( pt.x, pt.y, pt2.x, pt2.y );

                      END;

         END;

    END;

 

 

Within the main script: RunTempTool is called with two parameters, the first one being the aforementioned TempToolCallback function.

 

PROCEDURE RunTempTool(TempToolCallback: PROCEDURE; initialScroll :BOOLEAN);

 

The function generally works like this: If called upon the function body will be executed in a loop, until a mouse click is detected. The Loop will only run if mouse movement is detected. If no movement is detected, then the function body will run until its end and then rest there, everything drawn will remain until the next run of the loop.

The main purpose of the function is to use Tool event commands that draw temporary lines like:

vstDrawCoordLine, vstDrawCoordArcN

 

And most importantly vstGetCurrPt2D which allows You to pick up the current Point.

Though it should be noted that You can also use most other Commands within the function, such as GetMouse or complex calculations. You can also use message(), although you should be careful not to place the little scriptmessage window into the interface because that will make the program refresh the whole interface every time the loop is being run.

 

 

 

 

 

PARAMETERS

 

As You can see the Callback Function has 3 parameters declared within the function head. The last two, msg1 and msg2 are as far as I know irrelevant. The action parameter can return the following values:

 

3:            This is being returned once during the first Run of the Loop. That means it can be used to make a statement that is only executed one time at the start of the function.

 

103:        This value is being returned when the mouse is panning over the drawing plane. Thats where the main body of your script with the temporary drawing commands should lie.

 

5:            This is being returned every 5th time instead of 103.

 

105:        This is being returned when the mouse is panning over the interface.

 

104:        For the penultimate run of the loop.

 

4:            For the last run of the loop.

 

The way this is implemented in the example is via a CASE statement. 3 is used to set a one time help string. 103 is where the mouse input and drawing takes place.

 

 

 

 

 

RETURN VALUE

 

The return value oft he function (TempToolCallback in the example) can be set to either 0 or 1.

 

0:            Means that the function is only executed once and ends with the first click. Normal use.

 

1:             Means that the function will not end with the first click. In order to end the function You’ll first have to set the Return Value to 0.

 

Now, changing the Return Value within the script is kind of tricky. Of course You can just set an arbitrary condition, like executing the loop 100 times.

But optimally You’ll of course want to set the condition through some kind of user input, though this is a little problematic. That gets us to our next subject.

 

Note:

(The action parameter is also influenced when the Return Value is set to 1:  

If the mouse is clicked then it will return 103 or 105 (randomly). For the first run after the click it will then return 5. I don’t know how this can be made any use of though.)

 

 

 

 

USER INPUT

 

It is possible to use commands like KeyDown(Key) or MouseDown(x,y), but these will trigger very unreliably and don’t seem to pick up every input.

One way that works fairly reliably is to use the modifier-key commands, mainly OPTION and COMMAND.

 

Example:

 

IF KeyDown(Key) = TRUE THEN BEGIN

END;
            
IF OPTION = TRUE THEN             

        TempToolCallback:= 0

ELSE            

        TempToolCallback:= 1;       

 

Note, the Option input has to be preceded by a KeyDown(Key) command, otherwise it won’t trigger, I believe this is a general VS issue.

Note also, I believe using the AutoKey command here will crash the program.

 

 

The given example tries to alter TempToolCallback Return Value by pressing the Option key. This works only unreliably.

But I have been able to use that routine to alter the temporary line routine fairly reliably for example:

 

 

IF KeyDown(Key) = TRUE THEN BEGIN

END;

IF COMMAND = TRUE THEN BEGIN                     

        IF LineVariant = 'A' THEN              

                LineVariant:= 'B'

        ELSE IF LineVariant = 'B' THEN           

               LineVariant:= 'A';


        WHILE KeyDown(Key) = TRUE DO

               Wait(0.1);

END;


CASE action OF

        103:  CASE LineVariant OF  

               'A':   vstDrawCoordLine( Pt1.x, Pt1.y, Pt2.x, Pt2.y );

               'B':   vstDrawCoordLine( Pt3.x, Pt3.y, Pt4.x, Pt4.y );   

        END;

END;    

                                             

               

This will allow the user to shift between different temporary line routines by pressing a button.

 

 

 

 

 

ABORTING

 

There is one problem with this function, atleast on my system (Windows, VW 23), this might have been fixed on other systems.

When the Script/Tool is being aborted within the execution of the Callback function loop, the next time the Tool is called the Callback function won’t work. Atleast until You restart VW or open and close the Script code.

 

I don’t know exactly why this is, but it seems that if the last returned action value is not 4, then the next function can’t start up properly. This will be true for all Callback functions within the Script that use the same parameter action. If another Calback function uses say action2 then that one will continue to run normally.

 

A possible work around for this is to register the last output of the action parameter (In a separate file). If the last saved value is not 4, then the Callback function should be skipped and replaced by another one. A way this can be done is to write the main body of the Callback function into a separate procedure, with action and temptoolcallback as parameters. This way only the rump of the function has to be multiplied:

 

FUNCTION TempToolCallback_2(action_2, msg1, msg2 : LONGINT) : LONGINT;     

BEGIN

        TempToolPROCEDURE(action_2, TempToolCallback_2);         

END;

 

 

At any rate this is a very cumbersome work around. If somebody knows an alternative fix to this problem it would be very much appreciated.

 

 

 

 

 

You may have noted that there is an additional parameter to the RunTempTool Procedure, initialScroll. I have not really looked into that one much, if somebody can explain it it would be again appreciated.

 

So far I have not used the TempTool Procedure in Python, I am not sure if that is possible because of the different way Python handles Tool events.

 

 

I made this post because I think it might be helpful, but also because someone might know more than me, so please feel free to share if You do! Also tell me if this isn't the correct place to share guides and tutorials.

 

[Pat Stanford]

@FMA Thank you very much for this.

 

Do I have your permission (with credit of course) to add this to the Developer Wiki page about Run Temp Tool?

[FMA]

@Pat Stanford Yes of course! Maybe some sections should be verified by another user/setup.

[michaelk]

@FMA Very cool! I'll have to find a reason to use this :-).

[Elite Exhibits]

@FMA is it possible to make / post a video of this in action ...

 

¿ Does it work when placing Symbols ?

 

Please and Thank You

 

Peter

[FMA]

@Elite Exhibits That certainly would be possible. For example, if your Symbol is a circular object and You want to draw a temporary circle while you are determining its scale factor graphically.

First you input the CenterPt, then you start up the RunTempTool procedure, which gathers the EdgePt of the circle, uses it to draw the temporary circle and then transfers the radius to the main script to calculate the diameter of your symbol.

 

 

PROCEDURE CircleSymbol;

VAR

	radius,diameter: REAL;

	Edge,Center: POINT;
	
	SymbolHandle: HANDLE;
	
	SymbolName: STRING;
	

    FUNCTION TempToolCallback(action, msg1, msg2 : LONGINT) : LONGINT;
    
	VAR 
		
	uppleft, bottomright: POINT;
			
	BEGIN
			
		TempToolCallback := 0;
				
		CASE action OF
		
			103 : BEGIN 
						
					vstGetCurrPt2D( Edge.x, Edge.y );
					
					radius:= Distance( Center.x,Center.y, Edge.x,Edge.y );	
							
					uppleft.X:= Center.X - radius; 		
					uppleft.Y:=	Center.Y + radius;
					bottomright.X:= Center.X + radius;
					bottomright.Y:= Center.Y - radius;
							
					vstDrawCoordArcN(uppleft.X, uppleft.Y, bottomright.X, bottomright.Y, 0, 360);		{ Draws Circle }

				END;
				
		END;
		
	END;


BEGIN

	GetPt(Center.X,Center.Y);

	RunTempTool( TempToolCallback, FALSE );		
      
	
	diameter:= radius * 2;
	
	SymbolName:= 'nameofthesymbol';

	Symbol(SymbolName, Center.X, Center.Y, 0); 

	SymbolHandle := LNewObj;								

	SetObjectVariableInt(SymbolHandle, 101, 2);             { 3rd Var: ScaleMode: 1=None, 2=Symmetric, 3=Asymmetric }

	SetObjectVariableReal(SymbolHandle, 102, diameter);		{ 3rd Var: Scale Factor }
    
    ReDrawAll;

END;

RUN(CircleSymbol);

 

 

There is a lot more to be said about this procedure, I do have a few more examples and maybe I can come back to cover some more aspects of it.