Scribd
Upload
1K views8 pages

02 - SP3DNetAPI - Commands

This document discusses different types of commands in the S3D .net API including basic commands, graphic commands, and step commands. It covers how to implement user commands by inheriting from base command classes and overriding required properties and methods. It also discusses command characteristics, how the system runs commands, and command suspension.

Uploaded by

Senthilkumar Balu
Copyright
© Attribution Non-Commercial (BY-NC)
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
1K views8 pages

02 - SP3DNetAPI - Commands

This document discusses different types of commands in the S3D .net API including basic commands, graphic commands, and step commands. It covers how to implement user commands by inheriting from base command classes and overriding required properties and methods. It also discusses command characteristics, how the system runs commands, and command suspension.

Uploaded by

Senthilkumar Balu
Copyright
© Attribution Non-Commercial (BY-NC)
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd

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
[Link] = True, and [Link] > [Link]

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

Common questions

Powered by AI

Commands must manage errors internally, avoiding outward propagation, ensuring localized issue resolution without affecting broader system functions. The built-in mechanisms, such as encapsulated error-handling logic, ensure isolated error management, leading to stable and resilient system operations. These mechanisms highlight the importance of self-contained command functionalities .

The Smart 3D .net API uses a combination of the Modal and Suspendable properties to manage command execution and ensure stability. Only one command is active at a time, and commands are prioritized to prevent unintended states. High-priority commands cannot suspend other commands and terminate processes like transactions, ensuring stability. Additionally, every command has a default setting or checks in place—such as EnableUISettings—to verify system prerequisites, preventing execution in inappropriate states .

Command priority dictates execution flow; high-priority commands can suspend running commands marked as Suspendable. Suspended commands preserve their state to resume seamlessly. Commands of lower or equal priority trigger OnStop() for current commands. High-priority commands should not initiate transactions or set dialogs, emphasizing immediate action like view manipulations. Effective prioritization maintains command execution order and system stability .

Modal commands perform all processing within the OnStart() method and expect no further inputs post-invocation, as indicated by the Modal property being True. Graphic commands are non-modal, suspendable, and utilize graphic and keyboard events; they perform initial setups in the OnStart() while relying on event handlers for functionality. Step commands, similar to Graphic commands, are also non-modal and suspendable, gathering inputs at multiple steps. The OnSuspend() method hides UI and unsubscribes event handlers, whereas OnResume() reinstates them .

The API’s architecture allows users to implement custom commands by inheriting from base command classes and overriding necessary methods like OnStart(), OnStop(), and event handlers. This promotes flexibility, as users tailor commands for specific tasks without altering foundational methods, maintaining system integrity while enhancing functionality. The use of flags and conditions in EnableUISettings further fine-tunes command applicability, merging systematic control with user-defined customizations .

A command can be suspended if it is non-modal and marked as Suspendable, and when a higher priority command is invoked. During suspension, the system invokes OnSuspend(), unsubscribes events, and hides UI elements. The system state maintains internal data, allowing resumption once the high-priority command concludes. This mechanism prevents system state disruption and ensures functional continuity upon resumption .

State management enables structured task execution by maintaining a single active command and allowing only one suspended command via stacking. Commands manage their UI state transitions through OnSuspend() and OnResume() methods, preserving system integrity. Efficient stacking, coupled with systematic priority handling, ensures task continuity and precise execution under varying operational demands. This structured management enables complex operations while preserving overall system cohesion .

EnableUISettings defines prerequisites essential for command execution, such as ActiveView, ActiveConnection, ActiveDocument, or NonEmptySelectSet flags. They guide the Command Manager in assessing system readiness, ensuring that commands run under appropriate conditions. If these settings aren't met, the system will not invoke OnStart(), thereby inhibiting command execution to maintain optimal operation .

Commands in the API must commit or abort transactions before ending, as leaving uncommitted changes could lead to inconsistencies. Implementing a TransactionMgr Abort ensures clean command initialization. Transactions self-manage alterations, re-affirming consistency. Exceptions occur primarily in commands that manipulate views or delegate transaction closures to others, highlighting the system's robust transaction control .

The Default Command, typically non-modal and non-transactional, ensures system operation continuity when no commands are actively running. It inherently maintains system readiness by operating basic tasks like object selection. When selections trigger actions, it may spawn Modify Commands to adjust objects. This architecture ensures there's always a background task maintaining application stability .

You might also like