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.
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 |
|
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). |
|
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 2023, 2024, and 2025 use 28, 29, and 30 respectively. |
|
Version Retired |
Specifies the version number of Vectorworks when the plug-in was retired. For example, for Vectorworks 2023, 2024, and 2025 use 28, 29, and 30 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 2023, 2024, and 2025 use 28, 29, and 30 respectively. |
|
Version Modified |
Specifies the version number of Vectorworks when the plug-in was last modified. For example, for Vectorworks 2023, 2024, and 2025 use 28, 29, and 30 respectively. |
|
Version Retired |
Specifies the version number of Vectorworks when the plug-in was retired. For example, for Vectorworks 2023, 2024, and 2025 use 28, 29, and 30 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 2023, 2024, and 2025 use 28, 29, and 30 respectively. |
|
Version Modified |
Specifies the version number of Vectorworks when the plug-in was last modified. For example, for Vectorworks 2023, 2024, and 2025 use 28, 29, and 30 respectively. |
|
Version Retired |
Specifies the version number of Vectorworks when the plug-in was retired. For example, for Vectorworks 2023, 2024, and 2025 use 28, 29, and 30 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. |
|
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.
