Plug-in definition

The parameters that define the appearance of a scripted command, tool, or object plug-in are stored in a parameter record, which is associated with each object instance placed in the file. These records store persistent data between uses and provide default parameter values. A menu command that displays a dialog box, for example, might need to store values entered by a user for later use. A tool might provide several mode options in a popup list. Should the user wish to select a different mode for the tool, the new setting can be saved and reused on a subsequent use of the tool item. These values can be stored in the parameter record of the menu command or tool and retrieved later when the command or tool is selected again. Switching files will display stored values associated with the new files or, if no parameter record exists, will display the default values of the parameter record as created by the plug-in item.

The parameters for each object instance can be modified by using the Object Info palette to access the values in the object parameter record. A default parameter record is also created when the first instance of an object (or tool) is created in the file. This default parameter record, which is distinct from the parameter records associated with object instances, stores the object default settings with the file. It is used when placing subsequent object instances to define the defaults for each new object instance.

To define the custom plug-in:

From the Plug-in Manager Custom Plug-ins tab, select the plug-in to define or edit.

Click Edit Definition.

The Edit Plug-in Definition dialog box opens.

Click to show/hide the parameters.Click to show/hide the parameters.

Parameter

Description

General

 

Type

Displays the type of plug-in being created (menu command, tool, object, or include file)

Language

Displays either Python or VectorScript, depending on the language used for the script portion of the plug-in (see Specifying the plug-in script)

Name

Specifies the name of the new plug-in; this is also the name of the plug-in file, automatically appended with the appropriate extension (.px.vsm, .vst, or .vso). If renaming a plug-in, update the workspace afterwards to update the plug-in name.

Category

Assigns a plug-in to a heading category, to easily find the plug-in in the Workspace Editor

Parameters

Specifies the default parameters for the plug-in. Default parameters are applied to the plug-in at insertion. Parameters are listed in the specified order for the plug-in; change the parameter order by dragging within the # column.

Parameters list

Lists the default object parameters, alternate (localized) name if applicable, format, and default value. For linear objects, the LineLength parameter displays, which contains the axis length of the linear object. For rectangular objects, both the LineLength (the initial length of the object instance) and BoxWidth (the initial width of the object instance) parameters display. New default values can be specified for these parameters, but they cannot be deleted.

New

Opens the Edit Parameter dialog box to create a new parameter for the plug-in.

Specify the parameter name, alternate (localized) name if applicable, type, and default value.

To create a pop-up list of pre-defined parameter options, select the Pop-up Type. The Edit Choices dialog box opens. List the options. Each line in the list represents a choice in the pop-up; do not leave blank lines. To edit the pop-up choices later, click Choices.

Edit

Opens the Edit Parameter dialog box to edit the selected plug-in parameter. Certain third-party and built-in plug-ins allow parameter editing.

Delete

Deletes the selected plug-in parameter

Strings

Specifies text strings used by a plug-in

String categories list

Lists the string categories used by the plug-in (for example, parameter and button names for a dialog box, or help text strings). Within each category specify the strings (for example, color selector values that specify a certain color to be used by the plug-in).

Add

Opens the Add Category dialog box to add a text string category to the plug-in definition.

The next available Resource ID number is assigned automatically; specify the category name. After you add a category, select it and click Edit to add strings to it.

Edit

Opens the Edit Strings dialog box to edit the currently selected string category. Click Add to add a new string, or select a string and click Edit or Remove.

The string value depends on the category; for information, see developer.vectorworks.net.

Delete

Deletes the currently selected category and all its strings

Properties

Property settings allow plug-ins to behave like standard Vectorworks menu commands, tools, and objects. These settings control behavior of the plug-in with respect to the state of the file (selection status, view orientation) as well as define the help text to display.

The properties available depend on the plug-in type. Only custom plug-in properties can be specified.

Command

 

Availability Options

For each drawing state, specify whether the condition is required (the drawing state condition is necessary for the command to be active), prohibited (the command is deactivated if the drawing state condition exists), or can be ignored (the drawing state does not affect the command activation)

Tooltip Help

Specifies the menu command help text; help text describing the menu command displays when the cursor pauses over the command (currently, this is only available on Mac)

Contextual Help Override

Enter a URL (starting with http:) to specify a web page containing help information. To specify a file relative to the Vectorworks program folder, indicate the path starting with . / (period and forward slash).

Version Created

Specifies the version number of Vectorworks when the plug-in was created. For example, for Vectorworks 2022, 2023, and 2024 use 27, 28, and 29 respectively.

Version Modified

Specifies the version number of Vectorworks when the plug-in was last modified. For example, for Vectorworks 2022, 2023, and 2024 use 27, 28, and 29 respectively.

Version Retired

Specifies the version number of Vectorworks when the plug-in was retired. For example, for Vectorworks 2022, 2023, and 2024 use 27, 28, and 29 respectively.

Tool

 

Tool Bar String

Specifies the descriptive text to display in the Tool bar; usually this includes the name of the object, and it can include text indicating an action for the user to perform

Icon

The default icon for the plug-in can be replaced by a custom icon, if desired. With a third-party icon editor, create two versions of the icon: one for a standard-resolution display and one for a high-resolution display:

Standard-resolution: an image centered in an area 26 pixels wide by 20 pixels high. Save the icon in .png format.

High-resolution: an image centered in an area 52 pixels wide by 40 pixels high. Save the icon in .png format with the same name as the standard-resolution image with “@2x” appended to the end of the file name. For instance, if the standard-resolution icon is named 3DModelingToolSet.png, the high-resolution icon must be named 3DModelingToolSet@2x.png; otherwise the program will be unable to locate the icon.

Click Import PNG Icon to import the standard-resolution icon; if a high-resolution icon is also present with the @2x designation, the software automatically imports it as well. The Vectorworks program automatically displays the appropriate image for the device’s resolution.

Projection

Determines what view projection must be active. If 3D projection is required, the view is changed. If 2D projection is required, the layer plane is activated for the tool. Hybrid projection does not affect the view projection.

Execute Script

Tools are set by default to execute immediately when selected. In some cases, however, it may be desirable to have the script execution wait for mouse movement (such as a tool which draws interactively based on user mouse movement).

Contextual Help Override

Enter a URL (starting with http:) to specify a web page containing help information. To specify a file relative to the Vectorworks program folder, indicate the path starting with . / (period and forward slash).

Version Created

Specifies the version number of Vectorworks when the plug-in was created. For example, for Vectorworks 2022, 2023, and 2024 use 27, 28, and 29 respectively.

Version Modified

Specifies the version number of Vectorworks when the plug-in was last modified. For example, for Vectorworks 2022, 2023, and 2024 use 27, 28, and 29 respectively.

Version Retired

Specifies the version number of Vectorworks when the plug-in was retired. For example, for Vectorworks 2022, 2023, and 2024 use 27, 28, and 29 respectively.

Tooltip Help

Specifies the help text to display when the cursor pauses over the object icon in a palette

Object

 

Icon

The default icon can be replaced by a custom icon, if desired. With a third-party icon editor, create an 8-bit image, centered in an area 26 pixels wide by 20 pixels high. Save the icon in .png format, and click Import PNG Icon to import it.

Projection

Determines what view projection must be active. If 3D projection is required, the view is changed. If 2D projection is required, the layer plane is activated for the tool. Hybrid projection does not affect the view projection.

Execute Script

Objects are set by default to execute immediately when selected. In some cases, however, it may be desirable to have the script execution wait for mouse movement (such as an object which draws interactively based on user mouse movement).

Default Class

Specifies the default class for the object upon insertion; if the class does not exist when the object is placed, the class is automatically created

Contextual Help Override

Enter a URL (starting with http:) to specify a web page containing help information. To specify a file relative to the Vectorworks program folder, indicate the path starting with . / (period and forward slash).

Version Created

Specifies the version number of Vectorworks when the plug-in was created. For example, for Vectorworks 2022, 2023, and 2024 use 27, 28, and 29 respectively.

Version Modified

Specifies the version number of Vectorworks when the plug-in was last modified. For example, for Vectorworks 2022, 2023, and 2024 use 27, 28, and 29 respectively.

Version Retired

Specifies the version number of Vectorworks when the plug-in was retired. For example, for Vectorworks 2022, 2023, and 2024 use 27, 28, and 29 respectively.

Tooltip Help

Specifies the help text to display when the cursor pauses over the object icon in a palette

Subparts

Specifies the subparts used in the plug-in

Subparts list

Lists each subpart and its alternate (localized) name if applicable.

New

Adds a new subpart name for the plug-in. The Add Subpart Name dialog box opens.

Specify the parameter name and an alternate (localized) name if applicable.

Edit

Edits the selected subpart name

Delete

Deletes the selected subpart name

Options

(custom parametric object types only)

 

Execution Options

Objects, like symbols, can be assigned predefined insertion options for document placement. These options allow objects to properly interact with walls or other advanced Vectorworks object types. Command and tool plug-ins do not have insertion option settings.

By default, object geometry will only be recalculated if the object parameters or control points are edited. When object geometry is recalculated, file default settings for attributes such as font, text size, or line color will be reapplied to the object. If any of these settings have been modified since the object was placed or last edited, changes in the appearance of the object may occur.

The script is called whenever the object parameters have changed. Additionally, for instances where it is important for the object to recalculate (for example, windows placed in a wall), the script can cause geometry to be recalculated when the object is rotated (Reset on Rotate) or moved (Reset on Move).

Alternatively, the plug-in script can become an event handler (Event-Based); scripts must then respond to a small set of application events. For samples and documentation on event handling scripts, access the Support area at vectorworks.net.

Insert in Walls

Select the wall insertion option settings for the object. See Creating symbol definitions.

For objects that do not require insertion options, leave the options at the default settings.

When the plug-in has been defined, click OK to return to the Plug-in Manager.

Specifying the plug-in script

Specifying the plug-in definition

Concept: Scripted plug-ins

 

Was this page helpful?