How to use the StartCommand method

In this article I will show how to launch almost any interactive CATIA command from your code.  I sometimes use this method when the command I need to use in my program is not exposed through an automation API.  There are also some rare situations where it might be useful to launch the actual interactive command from your program.  This allows the user to interact with the familiar CATIA dialogs to complete some task, but I will point out a potential problem that will depend on the command and your program flow.

How it works

The StartCommand method is provided by the CATIA Application object.  You simply pass the name of the command to be started as an argument and CATIA then starts it just as if you had clicked its icon or typed the command in the Power Input box.  Here is the general syntax,

CATIA.StartCommand “CommandName”

How to figure out command names

There are several ways to figure out what command names are available.  Usually, the first thing I try is to hover my mouse over the icon and look just to the left of the Power Input box.  If you aren’t familiar with this, it’s the small text box at the lower right corner of the CATIA Window.

Here you often will see the command name displayed (In the image above it is the Line command).  The command name will have a  c:  before it, but just realize this is not part of the command name and should not be used in your VB code.  The c: syntax is only used when you manually type in the power input box to tell CATIA a command is being entered.  This general technique of using the mouse to hover over commands also works for many items in the main drop down menus and contextual (right click) menus.

Another way to find command names is to select “View” then “Commands list” from the main menu.  This will display a list of all the command names that are available.  The command names listed here are usually recognized by the CATIA.StartCommand method.  Also, if you select an item in the list, it will usually (but not always) display some useful information about that command at the bottom of the dialog panel to help you understand what it does.

Consider user input requirements for the command

Some commands can be launched this way and will perform some task without any user input.  However, most commands will require some actual user input so you may have to develop a strategy to handle this.  In general, the user input requirements for a command will fall into four categories (listed in order of increasing difficulty to handle with automation):

1. No user input is required
2. A selection is required before the command is run
3. A simple keystroke is required after launching the command (possibly to just click OK)
4. Extensive user interaction is required.

Let’s dig into each of these four categories and take a look at how to approach each of them in your code.

1. No user input is required

This is obviously the easiest type of command to use in your code because all you need to do is call the command and you are done.  As an example, maybe you need to save a screen shot of some geometry but the viewer might be zoomed in so that everything won’t fit in the window.  You need to reframe to ensure all of the viewable geometry is on the screen every time the image is saved.  In this case, the command name is “Fit All In” and it does not require any user input so you just call it and it happens – nothing more to think about.

CATIA.StartCommand “Fit All In”

2. A selection is required before the command is run

Some commands that require user selections will actually allow those selections to be made before the command is launched.  This is not true in all cases though, so you just need to experiment to find out.  A great example of this situation that I have used in the past is changing a sketch support.  As you probably know, a sketch must lie on a plane, a planar face or a planar surface.  So if you need to move an existing sketch from one support to another it can actually be done via automation without any user interaction like this,

'Get the part object (Assume the part is open in it’s own window)
Set objPart = CATIA.ActiveDocument.Part

'Get the first sketch in the first geometrical set
Set objSketch = objPart.HybridBodies.Item(1).HybridSketches.Item(1)

'Get the plane called Plane.1 in the first geometrical set
Set objPlane = objPart.HybridBodies.Item(1).HybridShapes.Item(“Plane.1”)

'Select the sketch first then the new support plane
Set objSel = CATIA.ActiveDocument.Selection
objSel.Clear
objSel.Add objSketch
objSel.Add objPlane

'Call the Change Sketch Support command
CATIA.StartCommand “Change Sketch Support”

3. A simple keystroke is required after launching the command

Some commands might display a dialog box where you just need to send one simple keystroke such as pressing the ENTER key to complete the task.  Please note that to send keystrokes, you will need to run your code inside a CATIA VBA project or outside CATIA from a separate executable.  The script languages (CATScript and catvbs) cannot send keystrokes to CATIA.

A very useful example of this sort of command is Disassemble in the Generative Shape Design (GSD) workbench.  The Disassemble command actually has two options – the first will break up an element into every sub-element and the second will only break up an element into it’s non-connected domains.  There is an automation API for the Disassemble command but unfortunately, it can only do the latter option.  So if you need to split up an element into every sub-element then your program must make use of the StartCommand method.

The code would look something like this,

'Get the part object (Assume the part is open in it’s own window)
Set objPart = CATIA.ActiveDocument.Part

'Get Surface.1 from the first geometrical set so that it can be disassembled
Set objSurf = objPart.HybridBodies.Item(1).HybridShapes.Item(“Surface.1”)

'Select the surface
Set objSel = CATIA.ActiveDocument.Selection
objSel.Clear
objSel.Add objSurf

'Call the Disassemble command
CATIA.StartCommand “Disassemble”

'Make sure CATIA window is activated then send
'Enter keystroke to click the OK button
AppActivate “CATIA V5”
SendKeys “{ENTER}”, True

4. Extensive user interaction is required

If you really want to fully automate a more complicated command you will have to use the Windows API, often referred to as WinAPI.  I have to warn you that this is an advanced topic (there are entire books dedicated to it) so I will only introduce the concept here.  If you want to learn more, maybe start at the wikipedia page.  The WinAPI is enormous so to narrow things down, I am talking about the capabilities described in “Overview – User Interface” on the wikipedia page.

As you know, Windows applications are made up of various windows, toolbars, dialog panels and controls such as buttons, checkboxes, combo boxes, etc.  Windows maintains what is called a handle for every single one of these objects (you can see just how many at any given time in the Task Manager window).  So, if you want to send a mouse click to a particular button on a specific dialog box, all you need to know is it’s handle and there is a Windows API that you can use to send a click to it.  Applications really don’t know whether the click was made by the mouse or whether you sent a click through your program using the WinAPI – it will respond the same to both.  While the concept sounds simple enough, the tough part is getting the handle of the specific control you want to work with.

Understand the command execution behavior

Be aware that when you use CATIA.StartCommand to execute a command that requires some selections or interactions by the user after it is launched, CATIA does not wait for that command to complete before it continues executing the rest of your program.  For example, if you start the Line command, CATIA will simply display the Line creation dialog panel then immediately carry on with the next line of code.  Because of this, you should really think through your program flow and try to call a command like this last in your program flow.

On the other hand, CATIA does wait for many commands to finish before executing the next line of code in your program.  You will usually see this behavior when the command does not require any user input.  For example, if you call the “Fit All In” command, CATIA will wait until that operation is complete, then it continues executing the next line of code in your program.  This is good to know because if you wanted to save a screenshot as mentioned earlier it’s nice to know the command will fully complete before you attempt to capture the image.

Tips

• Test the command manually before you include it in your program.  Sometimes a command name sounds like what you want but it actually does something different.  It’s better to find this out before the program is executing and you can’t tell what happened or a more serious problem occurs.  To test any command, just type c: then the command name in the power input box and hit enter.  Once you are confident that you have the right command name and it does what you want, then add it in your code.

• Many command names display with some dots … after their name.  My experience has been that usually you don’t need to include these dots when calling the StartCommand method.  However, I have seen some cases where they are needed, so if it doesn’t work without them then try again with the dots.

• Some commands will not display a dialog when you launch them by their command name even though they do when you click their icon.  The example for changing a sketch support shown earlier is a good example of this.  The only way to find this out is to experiment!  Don’t assume that a command is going to fall into one of the more complex categories listed above just because it typically has a dialog panel to deal with.

Please take a moment to rate this article…Just click the stars up near the title.

Add to: del.icio.us, StumbleUpon, Digg, Google