Your Extension can define many commands to extend the Loupe Desktop user interface.  There are three types of commands you can create:

• Global Commands:  These run at the Loupe Desktop level and display in the main menu.  They are not associated with a specific repository.
• Session Commands:  These are associated with a specific repository and are displayed where there are sets of sessions that can be worked with, like on folders and session grids.
• Log Message Commands:  These are associated with a specific session (and by extension repository) and are displayed where there are sets of log messages that can be worked with.

While they have different scopes which provide the context they can operate within the basic design of commands is the same.  Each command must:

1. Register all of the individual commands it wants to potentially display to the user.  Each is given a unique name (within the extension).
2. May chose to update the individual commands just prior to a menu or command list being displayed based on the current context.
3. When invoked to process a specific command (because it was selected in the user interface) it can then process it with or without a user interface.

How Commands are Displayed

The primary way that commands are displayed is in menus - either context menus or the main menu of the application.  They are displayed in a predictable order based on the order they are registered in.  Hierarchal menus can be created by using periods (.) in the command name to separate the name of each menu level and backslash (\) in the label.

Displaying Icons

You can add visual distinction to your commands by providing an icon for them.  The icon will automatically be sized to the available space; for best results provide a 16x16 and 32x32 pixel, 32-bit optimized image in your icons. 

Grouping Commands

Frequently you'll want to group like commands together and separate them from the rest of the commands with a divider.  All of the commands you register are automatically placed in a single group when displayed and divided from other commands in the same menu.  In addition, each command you register can optionally specify a command group.  All of the commands without a group will be displayed first then the groups, in the order they were provided.  In other words, commands are sorted first by group registration order then command registration order.

User Interactive Commands

If your command should be run on the main UI thread of the Loupe Desktop and can display its own user interface then specify the isUserInteractive=true option when registering it.  In this mode you should implement normal best practices to keep the UI responsive while your command is executing, particularly if you are performing a long running task.

If you do not need to display a user interface (beyond a MessageBox which is safe from any thread) then you should specify the isUserInteractive=false option when registering.  In this mode you will be called on a background thread and a general marquee progress bar will be displayed to let the user know your command is executing. 

Displaying Errors

If you want to display an error during command execution, often the best thing to do is simply throw an exception back to Loupe.  This will cause it to be logged and the Loupe Error Manager will be displayed to the user so they can decide what to do next.