vcCommand
vcCommand is the object type for commands that can be executed using Python API and made available in user interface of application.
Hierarchy
Some commands have specific implementations.
Properties
| Name | Type | Access | Description |
| Application | vcApplication | R | Gets the application object. |
| Checked | Boolean | RW | Defines if command is checked or visually indicated as active in the GUI, which is only for Python commands. |
| Enabled | Boolean | RW | Defines if command is enabled/disabled, which is only for Python commands.
A False value means the command will be greyed out in the GUI. |
| ExecutionType | Enumeration | RW | Defines how other active commands are managed when executing this command.
See Command Constants for more information. |
| Icon | vcBitmap | RW | Defines the icon of command in the GUI. |
| IgnoreEvents | Boolean | RW | Defines if event passing is ignored when executing command.
This flag is used in situations where events could create cyclic calls. |
| IsActive | Boolean | R | Gets the current state of command.
A True value means the command is active. |
| IsModelingCommand | Boolean | RW | Defines if command is used for manipulating geometry and related properties. |
| Name | String | RW | Defines the name of command. |
| Properties | List of vcProperty | R | Gets a list containing all properties of command.
Generally, properties are used to pass information to and from the command implementation for execution. |
| Simulation | vcSimulation | R | Gets the simulation object. |
| SupportsOverrideActivation | Boolean | RW | Defines if command is restarted after the execution of an override command, which is only for Python commands. |
Methods
| Name | Return Type | Parameters | Description |
| addState | None | Function state_func | Adds a command state function to Python command.
The first added command state is the function called when command is executed. This method is only available for user-defined Python commands. |
| cancelNextClick | None | None | Cancels a next click event.
This prevents a mouse click from being detected during the next mouse up event. This is only useful when called from an event processing handler function. Generally, this is used to prevent the activation of the Select command in response to a mouse click. This method is only available for user-defined Python commands and can only be called from within the command script itself. |
| createProperty | vcProperty | Enumeration type, String name, [enumeration constraints] | Adds a new property of a given type and name to command object.
An optional constraints argument can be used to define constraints for property, which must be done at time of creation. See Property Constants for more information. This method is only available for user-defined Python commands. |
| deleteProperty | None | vcProperty property
or String name |
Removes a given property or one matching a given name from command.
This method is only available for user-defined Python commands. |
| execute | None | [arg . . .]
or [name=arg . . .] |
Executes the command, and then waits for the execution of first command state to be completed. If this method is called with no arguments, the arguments used are those currently set in the command object. If this method is called with positional arguments, each value is assigned to command properties in the order they were created before command execution. If the method is called with keyword arguments, the corresponding command parameter property is looked up and assigned the argument value. If a parameter cannot be found, the function fails. |
| executeAsTool | None | [arg . . .]
or [name=arg . . .] |
Executes the command as if its execution type is VC_COMMAND_TOOL.
This method overrides the command's ExecutionType property. |
| executeInActionPanel | None | None | Executes a command using a task pane.
Generally, you would use a task pane to display the options of a registered Python or .NET command and to further control its execution. For more information, see Command Task Pane in Creating a Python Add-on topic. |
| getApplication | vcApplication | None | Returns the application object. |
| getCommand | vcCommand | None | Returns the command object. |
| getCommandPath | String | None | Returns the URI used by application to load the Python file of command.
This method returns an empty string if the command is not a Python command. |
| getProperty | vcProperty | String name | Returns a property matching a given name in command; otherwise returns None. |
| getSimulation | vcSimulation | None | Returns the simulation object. |
| genVarSpaceDialog | None | String command_name, String dialog_title, String first_tab_caption | Shows a modal property dialog containing the properties of a registered command matching a given command_name.
Note: The command_name is specific to Python, so COM or other programming commands cannot be used as an argument. The title of the dialog window is set to dialog_title. The first_tab_caption parameter determines whether a tabbed dialog is used. If first_tab_caption is an empty string, the properties are displayed in a single pane. Otherwise, the properties are displayed in separate tabs. In that case, property names are parsed as "tabName::propertyName" and distributed into tabs according to tabName; and properties without a double colon "::" in the name are displayed in the first tab, which will have the caption set to first_tab_caption. After the command is executed, the Param_4 property of the command object contains the result of the dialog, as an integer. A value of 1 means a user clicked OK, whereas a value of 2 means a user clicked Cancel. |
| recompile | None | None | Recompiles the command. |
| setNextState | None | Function state_func | Sets the next command state function. This is a function which is called with no parameters in order to execute the next state. If None is passed as a parameter, the command will exit after the current state function or event processing function returns.
Calling this method will also cause the command to leave event processing mode. This method is only available in Python commands, and can only be called from within the command script itself. For more information, see an example for setting the next state of a snap command. |
Events
Note that command events need to be executed in the following order:
- OnStart
- OnPreExecute
- first_state (Added with addState)
- OnPostExecute
OnStart & OnStop
OnStart and OnStop event handlers will automatically be called if they are defined in the Python command script.
| Name | Parameters | Description |
| OnStart | None | Triggered at the start of command execution. |
| OnStop | None | Triggered at the end of command execution, regardless if the command exited properly or was aborted. |
OnPreExecute & OnPostExecute
The command object can be given as an argument in OnPreExecute and OnPostExecute event handlers defined in the Python command script.
| Name | Parameters | Description |
| OnPreExecute | vcCommand command | Triggered immediately before the start of command execution. See an example below. |
| OnPostExecute | vcCommand command | Triggered immediately after the end of command execution. See an example below. |
Available Standard Commands
| Name | Parameters | Description |
| centerView | None | Centers the view of the 3D world. |
| clearWorld | None | Clears the simulation world. |
| (Deprecated) countData | None | Counts the amount of items in the current simulation. |
| dialogOpen | String uri, Boolean defined, String filter | Opens a dialog box for opening a file in the application.
A uri argument defines the initial directory for the dialog box. A filter argument defines file extension filter(s) using a standard Windows filter format. A defined property will have a true value if a file was selected, and then the uri property is set as the output. |
| dialogSave | String uri, Boolean defined | Opens a dialog box for saving a file.
A uri property defines the initial directory for the dialog box. A defined property will have a true value if a path is defined, and then the uri property is set as the output. |
| dialogSaveFile | String uri, Boolean defined, String filter, String title | Same as dialogSave() method with additional arguments for filtering file types and the title of the dialog box. |
| exportLayoutAsGeometry | None | Opens a dialog box for saving the current layout as a supported file type. |
| fillView | None | Adjusts the camera in order to center and fill the 3D world view with all components in the current layout |
| (Deprecated) genPropertyDialog | String Param_1, String Param_2 | Displays a modal property dialog that allows a user to edit the property values of a Python command.
The first argument given must be the registered name of the Python command whose properties you want to list in the dialog. The second argument defines the title of the dialog. In order to be listed in the dialog, a command property must have been created using Python API, for example using the command object with the createProperty() method. |
| (Deprecated) getUniqueComponentName | String seed | Generates a unique name based on the given seed name. |
| (Deprecated) interactiveBoolValue | None | Opens a Yes/No dialog box in which the result can be read from the first parameter. |
| (Deprecated) interactiveCenterView | None | Allows a user to center the 3D world view by picking a type of geometry in the current layout. |
| interactiveClearWorld | None | Removes all components from the current layout in the 3D world.
If a layout contains one or more components, a prompt is given to confirm command execution. |
| interactiveComponentSelect | None | Allows a user to select a component in the 3D world. |
| (Deprecated) interactiveCreatePackage | None | Opens a dialog box for creating a package of components. |
| (Deprecated) interactiveDoubleValue | None | Opens a dialog box for entering a real number in which the result can be read from the first parameter. |
| (Deprecated) interactiveImportModel | None | Opens a dialog box for importing a supported file as a component in the current layout. |
| interactiveJogJoints | None | Allows a user to interact with joints and other objects in the 3D world. |
| interactiveLoadModel | None | Opens a dialog box for opening a supported file as a new layout, thereby closing the current layout in the 3D world. |
| interactiveMeasureDistance | None | Allows a user to take measurements in a simulated environment. |
| (Deprecated) interactiveOrbitView | None | Allows a user to orbit/rotate the camera of the 3D world by using a mouse. |
| (Deprecated) interactivePanView | None | Allows a user to pan the camera of the 3D world by using a mouse. |
| (Deprecated) interactivePickPosition | None | Allows a user to pick a location in the 3D world by using a mouse. |
| interactivePlugPlay | None | Enables Plug and Play mode in the 3D world. |
| interactiveRotate | None |
Allows a user to rotate a selection in the 3D world. |
| interactiveRotateTCP | None | Allows a user to rotate the active tool frame for a selected robot in the 3D world. |
| interactiveSaveBitmap | None | Opens a dialog box for saving the current 3D view or drawing as an image. |
| interactiveSaveComponent | None | Opens a dialog box for saving a selected component. |
| interactiveSaveComponentAs | None | Opens a dialog box for saving a selected component as a new component. |
| interactiveSaveLayout | None | Saves the current layout. |
| interactiveSaveLayoutAs | None | Saves the current layout as a new layout. |
| interactiveSnap | None | Allows a user to snap a selection to a location picked in the 3D world by using a mouse. |
| interactiveToggleCollisionTesting | None | Turns on/off collision testing globally in the 3D world. |
| interactiveTopologyPick | None | Allows a user to pick geometric topology elements in the 3D world.
See vcTopologyPickCommand for more information. |
| interactiveTranslate | None | Allows a user to move a selection in the 3D world by using a mouse. |
| interactiveTranslateTCP | None | Allows a user to move the active tool frame for a selected robot in the 3D world. |
| (Deprecated) interactiveZoomView | None | Allow a user to zoom the camera of a simulated environment by using a mouse. |
| loadGeometryAsComponent | String uri, vcVector position | Opens a supported CAD file from a given uri as a new component in the 3D world at a given position. |
| loadLayout | String uri | Opens a component or layout from a given uri at the 3D world origin. |
| loadLayoutToPosition | String uri,
vcVector position |
Opens a component from a given uri to a given position in the 3D world. You can open a layout, but the layout would be opened at the 3D world origin. |
| netCommand | String command_name, [args*] | Allows a .NET command to be executed using Python.
The command_name argument specifies a .NET command by id. You would then need to pass arguments for executing that command. For example, the SetLocalizationCommand takes five arguments. For more information and example, see Executing a NET Command. |
| (Deprecated) readLicenseData | String product_name, String product_key, String product_activation_code | Gets license information for a given product and its key. |
| (Deprecated) rebuildECatalog | None | Rebuilds all mappings in the product's eCatalog library. |
| resetSimulation | None | Resets a simulation. |
| saveBitmap | String uri, String filter, Integer xres, Integer yres | Saves the current 3D world view as a supported image type with a given resolution.
The filter argument allows you to write to a specific format. bmp or rbmp writes to BMP. jpeg, rjpegstd or rjpegnstd writes to JPEG. png or rpng writes to PNG. tga or rtargareader writes to TGA. See vcBitmap for more information. |
| saveComponentToUri | String uri, vcComponent component, Boolean new_vcid | Saves a given component at the given uri.
The component will be given a new VCID if its VCID property is an empty string or a False value is passed as a third argument with this method. Warning: Do not pass an empty string in the first argument. |
| saveLayoutToUri | String uri | Saves the current layout at the given uri. |
| (Deprecated) saveScreen | String uri | Saves the current view and screen size of the 3D world as a bitmap image at the given uri. |
| saveState | None | Saves the current state of a simulation, which affects all components in the current layout.
Generally, this is used to save the joint configurations of robots and other types of equipment when collisions occur or at the end of a simulated process. |
| (Deprecated) setNotesVisibility | Boolean flag | Turns on/off the global visibility of notes in the 3D world. |
| (Deprecated) simLimitTest | None | Defines if a simulation is stopped when a joint in a component exceeds its limits. |
| (Deprecated) writeLicenseData | String product_name, String product_key, String product_activation_code | Sets license information for a given product and its key. |
Examples
Example. Set next state for Python command
|
#command file for Python add-on from vcCommand import * def testSet(cmd): if cmd.TargetAvailable: print "##------------SET--------------" print cmd.TargetGeoset p = cmd.TargetPosition print p.X, p.Y, p.Z #continue if target was selected setNextState(pick) else: #stop if no target selected print "Command exit" setNextState(None) def pick(): print "pick!" cmd.execute() app = getApplication() cmd = app.findCommand("interactiveSnap") cmd.SnapOnCurve = True cmd.SnapOnEdge = True cmd.SnapOnSurface = True cmd.OnTargetSet = testSet addState(pick) |
Example. Use OnPreExecute and OnPostExecute events
|
from vcCommand import * def first_state(): print "Hello World!" def before_handler(arg): print 'Starting', arg.Name def after_handler(arg): print arg.Name, 'execution finished.' cmd = getCommand() cmd.OnPreExecute = before_handler cmd.OnPostExecute = after_handler addState(first_state) |