Command Help

Command Help (cmdhelp) is a config structure used to provide localized, human-readable names. Although initially used by the command system, it is now also used by some other systems, such as tools, while items use their own variant. This article specifically covers commands.

Contents

Overview

Command Help provides usernames, descriptions, tooltips and other human-readable strings for use in the user interface. The most common location for these strings will be in the Form View and the Command History Viewport. This also allows commands to be sorted into categories for the Command List. All commands should provide a least a bare minimum of Command Help.

Usernames and descriptions are also available for the TextValueHints options by using ArgumentType config entries, and by specifying it through on ArgumentType atom on the argument's part of the config.

Command Help Example

Command Help is stored in configs with the following structure. For commands, there is one Command hash per command. Commands also make use of the CommandCategory atom to sort themselves into one or more groups. These groups are presented in the Command List tab of the Command History viewport.

Note that many of these fields are optional. If omitted, a default will be used as necessary.

Command Hash

The Command hash is a combination of the command name and the language code. The default configs should use en_US, as this is used as the fallback in modo. Other languages can be added as desired as new Command hashes. For example, tool.set would look like this:

<hash type="Command" key="tool.set@en_US">

Help URLs

Help URLs are defined using the HelpULRs and HelpURL config entries. Below are example help URLs for the select.symmetry and select.edgeLoop commands. See the Help URLs article for for more information on adding help. Help URLs are triggered by clicking the ? button in the command's dialog, or by pressing F1 and clicking on a control in the UI.

Icons

Icons are also associated with commands through configs. Below is the icon definition for the item.alignToWorkplane command, which includes both the small (20 pixel) and large (32 pixel) versions that are used by the Form View. The Icon hash's key is the command name followed by an underscore and the pixel size of that icon. More information on the UIElement, Image and Icon tags and the general structure of icon configs can be found in the Icon Resources article.

Field Types

Any field that is not set will fall back to a default or nothing. For example, omitting the ButtonName field will cause the command system to fallback to the UserName field, and then to the command's internal name. Also note these are only used if the command's own method returns LXe_NOTIMPL, thus allowing commands to provide their own dynamic strings (which obviously should come from message tables so that they too can be localized). tool.set is a good example, as it overrides nearly all of these to provide strings specific to a particular tool.

Type

Class

Required

Description/Use

Fallback

Command Hash

UserName

atom

✔

Command name displayed as the title of the command's dialog, throughout the Command History, and as a fallback for ButtonName

Internal command name

ButtonName

atom

Command name displayed in on buttons and menus in Form Views. Generally a shorter version of the username that will fit on a button. Only really needed if the username is very long.

UserName, then the internal command name.

Desc

atom

✔

A short paragraph describing the command, including pitfalls, usage limitations and other important notes. This should explain any unintuitive or ambiguous operation or behavior of the command. Detailed help should be left to the help files.

Empty string

Tooltip

atom

Default tooltip displayed when hovering over a control derived from this command.

ButtonName, then UserName, then an empty string

Example

atom

A single line showing an example of executing the command with common arguments set. This should have valid command syntax, and it should be technically possible to execute it as it appears.

Empty string

Argument

hash

✔

The hash is the internal name of the argument. One of these hashes is required for each argument in the command.

(n/a)

Argument Hash

UserName

atom

✔

Argument name used for control labels in command dialogs.

Internal argument name

Desc

atom

✔

Short paragraph explaining how what the argument does and how it is used. If the argument is optional, this should also describe the default behavior if it is not set.

Empty string

ArgumentType

atom

✔

Only required for arguments that use text hints. This is the hash of an ArgumentType entry in the config that contains user strings for each of the hints. These are displayed in popups and in other places that text hints are presented to the user.

Internal name of text hint

Command Categories

Categories are a separate portion of the config file, and indicates how a command is sorted in the Command List. The format for the category is as follows:

Any number of these can be placed in the category section of the config. The hash type is always C. Each command can be in one category. The internal category name including any sub-categories is used as a lookup into the dictionary to obtain a message ID, which is then used to get the actual message.

Message Tables

The internal category names are looked up through message tables. The table is always named "Commands:category" with different language codes appended based on the localization. Each category should have its only message table entry.

For example, this snippet represents the categorization of two commands.

The category path will also be broken up at the slashes to find the parent category names, if necessary. This means that you should define messages for each part of the path. Lets say your path is cat/subcat. cat is just container for other categories, so it has no commands. You still need to remember to define message table entries for both cat and cat/subcat, or you'll see the internal name of cat in the Command List hierarchy.

Templates

You can copy and paste these into configs to get you started.

Full Template

This template includes every cmdhelp field. Delete the optional entries that you don't need. Copy the Argument section for each of your arguments, or remove it if your command has no arguments.