S3D .

net API Commands

Smart 3D .net API Training 2008. Intergraph Corporation. All Rights Reserved. Commands - 1

Types Of Commands
Basic Commands No further Graphic / Object inputs from Graphic Views/ Workspace Explorer after command is started.
Can be Modal or Non-Modal. Can get some inputs from a Form / RibbonBar* [non-modal commands].

Graphic Commands Can use Graphic and Keyboard events.

Typically are non-modal, suspendable commands. Can get some inputs from a Form / RibbonBar*.

Step Commands Can use Graphic, KeyBoard and Object Selection events.
Allow gathering inputs (objects, points) in steps and traverse between steps. Typically are non-modal, suspendable commands. Can get some inputs from a Form / RibbonBar*.

RibbonBar functionality in S3D .net API will be available later on. Till then, we can use Forms for the same purpose.
Smart 3D .net API Training 2008. Intergraph Corporation. All Rights Reserved. Commands - 2

User Implemented Commands

Based on the purpose and functionality to implement, choose to inherit from either of
BaseModalCommand BaseGraphicCommand BaseStepCommand
BaseModalCommand
Specify Command Characteristics

Modal True/False Suspendable True/False EnableUIFlags prerequisites to run. Implement OnStart( ) OnSuspend ( ) User ModalCommand . .

OnStop ( ) OnResume ( )

Provide your implementation for the required properties and methods. Override only required Methods & Properties, leave alone others. It is as simple as that !!!

BaseGraphicCommand Specify AllowEvents True/False to indicate whether you want to receive events or not. Implement Mouse/Keyboard Event Handlers as required

User GraphicCommand . .

BaseStepCommand Setup Command Steps and Event handlers and implement as required. User StepCommand . .

Smart 3D .net API Training 2008. Intergraph Corporation. All Rights Reserved. Commands - 3

System & Users Handling of Command Types

System calls OnStart( ) when it finally decides to start a command upon users action. (more later on why system needs to decide whether to START or NOT) Modal commands All functionality is within OnStart( ). When OnStart( ) method returns, system Stops it (OnStop gets invoked). Non-Modal commands Keep running until stopped (by itself or system). Suspendable commands Suspended & Resumed based on the situation as system determines (more details on this later in this session) Most Basic commands typically show up a form (modal / non-modal) to gather inputs like dimensions etc and do the processing inside the forms logic. Form is not a necessity : eg Delete Command. Graphic Commands can get inputs (points from Graphic view) in addition to inputs from forms / RibbonBar / UI elements. Step Commands can get inputs (points/objects from Graphic Views, objects from Workspace Explorer), in addition to inputs from Forms / RibbonBar / UI elements.
Smart 3D .net API Training 2008. Intergraph Corporation. All Rights Reserved. Commands - 4

Characteristics (Properties) of Command

A commands Modal property specifies whether or not command expects more graphic/object inputs after invoked. If True, all command processing is within OnStart( ). A commands Suspendable property specifies if the command can be suspended temporarily while it is running, in response to a higher priority command being started. Can be specified as True if desired, only if its Modal property is False. A commands EnableUIFlags property specifies the conditions to qualify to run. Can choose one or more of below settings
No conditions needed. Needs ActiveView i.e. needs a Graphic View. Needs ActiveConnection i.e. defined workspace, connected to a plant. Needs ActiveDocument i.e. active session file. Needs NonEmptySelectSet i.e. some objects selected.

Command Manager checks this setting with the system state to decide whether to start the command or not.
Smart 3D .net API Training 2008. Intergraph Corporation. All Rights Reserved. Commands - 5

How System Runs a Command.

System checks if its current state satisfies the commands
EnableUISettings (View, Connection, Document, Selection)

User Invokes Command

No

Prerequisites NOT met !!! Cannot Run.

Yes
System invokes OnStart ( ) method and it runs till its logic completes and returns back to system.

Command Logic continues to run, event handlers responding to events (Mouse/KeyBoard/Selection change). OnSuspend( ) gets invoked when System (Command Mgr) suspends the command. OnResume( ) gets invoked when System (Command Mgr) resumes the command.

Manager)

System(Command Stops the Command.

True

OnStop ( ) method gets invoked.

System checks commands Modal property value

False

OnStop( ) gets invoked when System (Command Mgr) stops the command. Command calls StopCommand ( ) to stop itself when appropriate. This results in OnStop( ) getting invoked.

Smart 3D .net API Training 2008. Intergraph Corporation. All Rights Reserved. Commands - 6

Command Implementation
User just provides an override implementation for those properties/methods which he needs to do something. Doesnt need to implement all methods/properties. Modal Property Return True / False as appropriate Suspendable Property Return True / False as appropriate EnableUISettings property Specify prerequisite conditions required for the command to run. See EnableUIFlagSettings flags.
Specify any combination of ActiveView / ActiveConnection / ActiveDocument / NonEmptySelectSet flags. Leaving it alone implies No Conditions required

Default Property values

Command Property Modal Suspendable EnableUISettings

Modal True False None

Graphic False True None

Step False True None

Smart 3D .net API Training 2008. Intergraph Corporation. All Rights Reserved. Commands - 7

Command Implementation
OnStart ( ) Invoked by system when your command is started
for Modal Commands, this typically may do all the action, or show a form which has all logic. for Graphic / Step Commands, this typically does the initial setup and the event handlers have the functionality.

OnStop ( ) Invoked by system when it determines your command needs to be stopped.

Write your cleanup logic if any unload forms / UI etc.

OnSuspend ( ) Invoked by system when it determines your command needs to be suspended

Here typically, the command must hide its UI form(s) etc and unsubscribe to events.

OnResume ( ) Invoked by system when it determines your command needs to be resumed

Here typically, the command must unhide its UI form(s) etc and resubscribe to events.

Smart 3D .net API Training 2008. Intergraph Corporation. All Rights Reserved. Commands - 8

Command Implementation
OnIdle( ) Invoked by system when it determines some idle time
Rarely commands have some implementation here, but you can do something like quick background processing of things without interfering with the main running functionality. For Graphic Commands, user implements required Graphic View Manager / Keyboard event handling (details in a later session) For Step Commands, user does Step Definition setup and implements Step / Graphic View Manager / Keyboard event handling (details in a later session)

Smart 3D .net API Training 2008. Intergraph Corporation. All Rights Reserved. Commands - 9

Command Priority
Commands are started with a preset priority, determined and requested by the starter (menuitem / toolbar icon / Custom commands dialog). Can be NormalPriority or HighPriority. HighPriority commands CANNOT commit/abort Transactions. Typically used for View manipulation, or any non-transacting non-dialog watch windows. Normal Priority used for most cases. Note : LowPriority has been deprecated and not to be used. May appear in the available options in the UI and the API enums, but still should not be used.
Smart 3D .net API Training 2008. Intergraph Corporation. All Rights Reserved. Commands - 10

Command Suspension (stacking)

Only one command is active at a time. Only one command could be stacked (i.e. put to suspended state) by System For this reason, A command cannot suspend itself - When a new command is invoked

If
CurrentCmd.Suspendable = True, and NewCmd.Priority > CurrentCmd.Priority

making a High Priority command suspendable doesnt make any sense.

Then
Current Command is Suspended (OnSuspend( ) is invoked), and later resumed (OnResume( ) is invoked) when New Command stops.

All other cases, Current Command is stopped (OnStop( ) is invoked) when a new Command is started.

Smart 3D .net API Training 2008. Intergraph Corporation. All Rights Reserved. Commands - 11

Command Suspension (stacking)

A running non-suspendable command gets stopped by system when any another command is invoked. A running suspendable command gets suspended by system when any High priority command is invoked. System resumes the suspended command when the high priority command stops.
Cmd-1, Non-Modal, Suspendable Running Cmd-2, High Priority Started Cmd-2 Ends Cmd-1 Resumed Cmd-1, non-suspendable Running Cmd-2 started

Cmd-1 gets stopped by system

Cmd-1 gets resumed by system

Cmd-1 gets suspended by system. Its internal data still maintained

Smart 3D .net API Training 2008. Intergraph Corporation. All Rights Reserved. Commands - 12

Command Suspension (stacking)

A suspended command gets stopped by system when any Normal priority command is invoked.

Cmd-1, Non-Modal, Suspendable Running

Cmd-2, High Priority Started

Cmd-3, Normal Priority Started

Cmd-1 gets suspended by system. Its internal data still maintained

Cmd-2 stopped by System

Cmd-1 gets stopped by system

Smart 3D .net API Training 2008. Intergraph Corporation. All Rights Reserved. Commands - 13

Implementation Expectations
Commands should not generally leave their modifications on the table, i.e. just modify things and leave them there for next command to commit to the database. i.e. either abort or commit the transaction (more on transactions later) before they are completely ended. Command should not generally inherit uncommitted changes done by other commands. Most cases, this can be simply handled by performing a TransactionMgr Abort in the initialization of the command. If it is a Helper command or a non-transaction based command, eg view manipulation etc, then it should not do an abort. There are few exceptions to above. In case of commands which do not perform any changes to business objects, or commands which do the changes and intentionally delegate the commit / abort responsibility to other commands (which they can start) Commands must withdraw their UI when they are suspended / stopped. There may be very rare exceptions to this. For example, the View Todo list command shows its form and the Form can be active after the Todo list command has exited. One can use other commands while the TODO list form is up. Wherever possible, all errors happening within the command logic must be handled internally in the command logic itself and not be propagated outward.
Smart 3D .net API Training 2008. Intergraph Corporation. All Rights Reserved. Commands - 14

What is running at any time in the System ???

At any time, a Command is always running in the system. There is never a state when there is no running command in the system. Yes, it is True !!! Such command is called the Default command, defined by the active Task (the Environment). It always runs when no command is running. Of course, it cannot be a Modal command. Most of the cases it is the Select Command. When Select Command senses something is selected, it starts off a Modify Command which runs in parallel with it
A modify command is a special type of command (internally started by system). An applications logic at runtime tells the system what is the Modify Command for the selection state. This usually posts a special ribbon bar which allows to modify currently selected object(s)

When a command ends itself and there is no command in suspended state, the system starts the Default Command.
There exists an internal mechanism called Command Continuation which a Task can use to change this process as needed so as to restart the previously running command this mechanism is not yet available for End Users Automation as it is quite complex to use by end users. Eg : Route Pipe Insert Component & Finish notice the Route Pipe command continue

It is important to know this details because this knowledge helps to know the systems behavior and write better automation.
Smart 3D .net API Training 2008. Intergraph Corporation. All Rights Reserved. Commands - 15