A Beginners Experience Building Vectorscript PIOs

[Kevin McAllister]

Yesterday I sat down with the hope of creating my first Vectorscript PIO. I had an idea for one for a while and was curious about what could be accomplished. I thought I would write a little about my experience since I have seen so many beginners asking about Vectorscript on these forums. While I am an experienced Vectorworks user, I have only dabbled with the simple scripts generated by the Custom Selection and Custom Tool dialogs. My coding experience in general is pretty limited, having done a little HTML and CSS stuff for a Continuing Education class.

So here is a bit about the process. First I looked around for some resources -

- I started with the Vectorworks help system. There is lots of information there but its written in a fairly dry, technical way.

- I then went to the Nemetschek website under Support>Vectorscript. A few more resources here. I downloaded a variety of example scripts from here and waded through them. Unfortunately many are not well commented, making them a bit overwhelming. I had chosen to open the example scripts in TextWrangler, the same editor I have been using for HTML, and had a very happy discovery. TextWrangler (which is free online) happened to have highlighting for Vectorscript documents. This made it so much easier to see what was going on. I?m not sure why it doesn?t get a mention on the Nemetschek website. I later discovered there is even a language update for it from here -

www.vectorlab.info/index.php?title=VSS_Language_Module_for_BBedit_%26_TextWrangler

Anyway, I highly recommend TextWrangler for your first Vectorscript outing, as its much more user friendly than the editor built into Vectorworks.

The one other thing I would suggest you read up on in Vectorworks help is the section on Parameters for PIOs. It proved invaluable for this process.

From there I decided to jump in and see what would happen. I started by saving one of the example files under a new name as a template for script structure. I couldn?t find a basic, blank template file anywhere. Sort of odd as that was one of the first things we built when programming HTML. I started commenting the file heavily to remind myself of what I was doing, and, unlike many of the examples, I made my variable names very clear (ie. marker instead of mkr) so there was no confusion in my mind as to what was what. I trimmed the code down so all I had was the basic structure and the beginnings of some functionality.

The next thing I did was create a new PIO in the Vectorworks Plugin Editor (Tools>Scripts> Vectorworks Plugin Editor) within Vectorworks itself. I had debated making a copy of an open source plugin as a starting point, but it turns out you can?t change the type of an existing plug in. Starting fresh was a good experience anyway as it allowed me to further learn about Parameters. Once the PIO was created I added it to my workspace. In my case I was creating a tool, so I added it to the custom palette I had created for the example tools.

Now I was able to test my script. To do this I cut and paste from TextWrangler into the Script area of my PIO. Here I would compile and look at any errors. The error system is pretty cryptic and often tends to flag the thing after the error, not the error itself. One error may appear to be many because of the way it works. I found that starting with the first error was the key. It is always easier to edit something once you have an idea of the overall structure. I must say it was very rewarding when the script drew its first line by itself!

Once I had some basic functionality, I added pieces bit by bit, testing as I went until I had the full functionality I wanted. The development and testing process involved a lot of cut and paste, something that TextWrangler is good at. It allows for multiple files to be open, so you can easily grab snippets from here and there. I discovered along the way that unfortunately there are many errors in the Vectorscript documentation. This is something we as beginners should be aware of. It often can be wise to ask someone with more experience when something looks like it should work but it doesn?t. I managed to muddle through using my troubleshooting instincts, but it did add a lot of tinkering time as I did.

In the end, my goal was to create a fully functional tool so I would have experienced the entire developmental process. I even took the time to add help notes, generate custom icons and encrypt the tools. It was a great taste into the power of Vectorscript and I ended up with two functional tools. I was surprised at what I achieved given my level of experience. I invested about a day overall and it was time well spent.

The first tool I created was Ruler Bar. In theatre, ruler bars are often placed on a light plot to aid in placing lights. I was curious to see how it could be dynamically adjusted through the use of the OIP.

The second tool I created was Artefact Label. It was inspired by another forum thread, where someone wanted to be able to label individual artefacts on a plan and include some basic information. I was curious to see if I could populate a record using data that could be entered in the OIP. I also wanted to see if I could make it maintain its size on the page when the layer scale was changed.

I would recommend that most regular users of Vectorworks take Vectorscript for a spin.

Kevin

PS. Here are the tools I created to give you an idea of how a little knowledge can turn into something cool.....

Edited August 28, 2010 by Kevin McAllister

[michaelk]

Congratulations, Kevin.

I've often wished that some of the VS gurus in the forum would annotate those example scripts or their own scripts. Or even just provide audio/screencast comments and examples for us struggling mortals. The more information and examples, the better.

It's never clear (to me) what the arguments should be for some of the functions, or when to use one function instead of another...

It's a tough hurdle to jump over. Well done.

I'll have to give Ruler Bar a try...

mk

[_c_]

Ciao Kevin,

So here is a bit about the process. First I looked around for some resources

Kevin, please also look at the Developer Wiki. It reproduces the shipped VS documentation but is more actual. Fixes are reproduced faster there. There are comments.

there are many errors in the Vectorscript documentation.

I would be careful, if I was you, in stating this. It is not true. There aren't many errors in the Vectorscript documentation. I won't exclude some errors, but wait until you have some more experience in Vectorscript before stating such a thing.

If you have the feeling that something is erroneusly described, please file a bug report or write a warning in the VS list. Someone will take care that the error will be fixed.

ciao

Orso of Vectorlab

[Kevin McAllister]

Hello Orso,

Thanks for taking the time to read my post.

Kevin, please also look at the Developer Wiki. It reproduces the shipped VS documentation but is more actual. Fixes are reproduced faster there. There are comments.

I appreciate the link to this new resource. It looks like a valuable addition to the others.

I would be careful, if I was you, in stating this. It is not true. There aren't many errors in the Vectorscript documentation. I won't exclude some errors, but wait until you have some more experience in Vectorscript before stating such a thing.

If you have the feeling that something is erroneusly described, please file a bug report or write a warning in the VS list. Someone will take care that the error will be fixed.

I would never state this lightly, but it is an accurate account of my experience. All have the errors I found were forwarded on to tech support as I found them.

They were -

The icon size for PIOs is incorrectly labelled as 24 x 18 in the Adobe Air manual. The correct size is 26 x 20. I know this because Vectorworks gave me an error message when I tried using one at the first size.

The Num2StrF function does not return "1'-11 1/2"" as shown in the example in the Vectorscript Function Reference (the HTML file found in the Vectorworks 2010 folder). It actually returns "1'11.45" that has no dash between the feet and inches and a decimal value. I know this because I built a script using only this information and the text function and that is what it returned.

In this example from the Adobe Air manual below entitled "Setting Parameter Values from Scripts", the second 'Space Width' actually needs to be 'Space_Width' or the value does not get passed. This was discovered by trial and error.

BEGIN

resultStatus:= GetCustomObjectInfo(objName,objHd,recHd,wallHd);

IF resultStatus THEN BEGIN

sp_width:= PSPACE_WIDTH;

...

...

sp_width:= 5 * sp_width;

...

...

SetRField(objHd,GetName(recHd),?Space Width?, Num2StrF(sp_width));

END;

END;

This last one is not necessarily an error, but more incomplete information. Some types of PIOs generate a Parameter base on user input (ie. LineLength for a Linear Object). The manual is clear that these cannot be deleted. I was experimenting and accidentally changed its name. Because I was consistent in both the Parameter definition box and my script, the script worked, but it had lost the initial value generated by user input and instead was defaulting to the default value in the Parameter box. So by changing the original Parameter's name, I had essentially created a new Parameter. The original one still existed behind the scenes, but no longer showed up in the Parameter box. When I changed the name back in the Parameter box, it reassumed the original Parameter information.

I guess I was just having a day of discovery....

Kevin

[Miguel Barrera]

BEGIN
resultStatus:= GetCustomObjectInfo(objName,objHd,recHd,wallHd);

IF resultStatus THEN BEGIN
sp_width:= PSPACE_WIDTH;
...
...
sp_width:= 5 * sp_width;
...
...
SetRField(objHd,GetName(recHd),?Space Width?, Num2StrF(sp_width));
END;
END;

For clarification, the parameter name passed to SetRField must be the same as the one defined in the paramater list. You can access these from the pull down menu in the VS editor under "Parameters...".

If the parameter name is 'Space Width', then it must include the space in SetRField but the "constant" to access the value will always need an underscore instead of a space as in PSPACE_WIDTH.

Personally, I name parameters with spaces in order to set them apart from variable names which cannot have spaces.

Tip note: the record name is the same as the pio name, so you can simplify your call as:

SetRField(objHd,objName,?Space Width?, Num2StrF(sp_width));

Also from experience, I do not embed functions within other procedures because you do not know the value returned by the function when debugging. This is specially important if the returned value is a NIL handle which in most cases it will crash the program.

[_c_]

Dear moderators, please move us to the VS forum, we'll get into boring details now.

Well done, Kevin.

Now, considering the largeness of the VS documentation, would you call this "many errors"?. Not.

1- not error, lack of updating documentation, please see old versions of VW

2- not error, just inconsistent value in example file

3- not error, see Miguel

Stay fair. Error is something else.

Something more. What you actually wish is to work by includes. Easiest configuration:

* save a textwrangler file with your script in you User/Plug-Ins folder. Use file suffix ".px" or ".vss". Please read the documentation about "Includes" for the difference. I advise you to name your text files with a suffix such as "z" because they will list in the script editor, which is boring.

* in the plug-in editor select your tool/command, edit it

* remove all code there, add this line {$INCLUDE z_myScript.px}. This tells the compiler to search for an include file in the same folder as the plug-in. For the compiler this could mean any of the three folders: application, user, workgroup.

* save and close

* now activate the compiler mode: Tools > Scripts > VS Compiler mode.

Use your tool/command and it will load the script from the text file. You don't need to copy-paste between TW and script editor any longer.

This is very very easy. It will only get complicated when you need to cover different paths, platforms, with the same include file or aliases thereof. I mention this, because you might land there.

Next step: find out how to use a common folder for ALL your include files.

orso

[_c_]

provide audio/screencast comments and examples for us struggling mortals.

That would take huge movies. It takes very very long to develop a well thought script. Months, if you do it in your spare time. We all have scripts being developed since years.

It is really not possible to do what you ask. The things you must know are so volatile according to the script's target and area of influence, that you simply can't document all.

The basic is described in the official documentation, in the developer list you'll find comments about the quirks (BTW, the current developer list reproduces a previous list from Charles Chandler, state of 2008, with authors and time of the comments removed, so if you wish to know when a quirk was valid and if this is creditable as info, please see VSFR by Charles (archived, or so it seems), there you find the missing infos ).

On Vectorlab we tried to offer advanced advise over some hard-to-learn topics. You'll find many good advises. Is purest VS-freak only.

The problem is that

* the scripters/programmers capable of writing such articles are very very few

* of those, really few see any advantage in the selfless sharing that a wiki implies, or don't mind it.

I can count these few on one hand. By name.

Mind, most scripters are a proud selfish egocentric lot searching for the immediate kick of public acknowledgement. This isn't given in a wiki. A wiki is give-only. It takes that kind of mind, to write there, to wish to share. No return no thank-you back.

And BTW did you ever think of a second of acknowledgment to the -for you- nameless engineers writing and developing examples, thousands routines. How come this is all taken for granted.

Most of the old scripters didn't have that documentation, the overflow of documentation that you have now.

Please try it out, you'll see that you have all you need to get going, it will be nice. Even if not without moments of frustration. But this is why we love scripting, easy to achieve things aren't as nice.

orso

[Kevin McAllister]

Something more. What you actually wish is to work by includes. Easiest configuration:

* save a textwrangler file with your script in you User/Plug-Ins folder. Use file suffix ".px" or ".vss". Please read the documentation about "Includes" for the difference. I advise you to name your text files with a suffix such as "z" because they will list in the script editor, which is boring.

* in the plug-in editor select your tool/command, edit it

* remove all code there, add this line {$INCLUDE z_myScript.px}. This tells the compiler to search for an include file in the same folder as the plug-in. For the compiler this could mean any of the three folders: application, user, workgroup.

* save and close

* now activate the compiler mode: Tools > Scripts > VS Compiler mode.

Orso,

Thanks for this! It greatly improves the workflow and testing.

I am looking forward to learning more about Vectorscript as I work with it.

Kevin

[_c_]

You'll love it, Kevin.

VS is great power. It allows you to work less while producing like you were a team.

Login in the VS-list (not the forum here, which is too basic), you'll find many advises and many friends. Nearly all questions have been asked there before. Someone will always help you. Read all, read the history.

welcome, Kevin...

o

[C. Andrew Dunning]

Kevin -

Congratulations on your tools! I know that getting there had its challenges, but you are to be commended for not giving up. We'll be interested to see what you create next...now that you've gotten through the hardest part: just getting started.

Hats off to you...