Command Help

‘’’Command Help’’’ (‘’cmdhelp’’) is a Configs. This article specifically covers commands.

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 History Viewport#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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
 <?xml version="1.0"?>
 <configuration>

   <atom type="CommandHelp">

    <hash type="Command" key="some.command@en_US">
      <atom type="UserName">Full User Name</atom>
      <atom type="ButtonName">Button Name</atom>
      <atom type="Tooltip">Tooltip string</atom>
      <atom type="Desc">The description for the command.</atom>
      <atom type="Example">some.command argValue</atom>

      <hash type="Argument" key="arg">
        <atom type="UserName">Argument Name</atom>
        <atom type="Desc">Argument Description</atom>
        <atom type="ArgumentType">some.command-argtype</atom>
      </hash>
    </hash>

   </atom>

   <atom type="Categories">
     <hash type="Category" key="Commands">
       <hash type="C" key="{cmdcategory} catmsgtable@cat/subcat:some.command"/>
     </hash>
   </atom>
 </configuration>

Command Hash

The Command hash is a combination of the command name and the Language Codes. 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:

1
    <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 Dialogs, or by pressing F1 and clicking on a control in the UI.

1
2
3
4
5
6
7
8
9
 <?xml version="1.0"?>
 <configuration>

   <atom type="HelpURLs">
     <hash type="HelpURL" key="command:select.symmetry">pages/modotoolbox/Symmetry.html</hash>
     <hash type="HelpURL" key="command:select.edgeLoop">pages/modotoolbox/SelectionModifiers.html#selectloop</hash>
   </atom>

 </configuration>

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
 <?xml version="1.0"?>
 <configuration>

   <atom type="UIElements">

    <!-- The image containing the individual icons -->
    <hash type="Image" key="icons601_med">icons601_med.png</hash>

    <!-- The 20 and 32 pixel icons -->
    <hash type="Icon" key="item.alignToWorkplane_20">
      <atom type="Source">icons601_med</atom>
      <atom type="Location">80 40 20 20</atom>
    </hash>
    <hash type="Icon" key="item.alignToWorkplane_32">
      <atom type="Source">icons601_lge</atom>
      <atom type="Location">128 64 32 32</atom>
    </hash>

   </atom>

 </configuration>

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.

Command Hash

Type

Class

Required

Description/Use

Fallback

‘’UserName’’

atom

Yes

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

No

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

Yes

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

No

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

‘’ButtonName’’, then ‘’UserName’’, then an empty string

‘’Example’’

atom

No

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

Yes

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

Type

Class

Required

Description/Use

Fallback

‘’UserName’’

atom

Yes

Argument name used for control labels in command dialogs.

Internal argument name

‘’Desc’’

atom

Yes

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

Yes

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:

1
2
3
4
5
6
   <atom type="Categories">
     <hash type="Category" key="Commands">
       <hash type="C" key="command.name1">category</hash>
       <hash type="C" key="command.name2">category/subcategory</hash>
     </hash>
   </atom>

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.

1
2
3
4
5
6
   <atom type="Categories">
     <hash type="Category" key="Commands">
       <hash type="C" key="viewport.3dView">viewport</hash>
       <hash type="C" key="layout.lockDividers">viewport/layout</hash>
     </hash>
   </atom>

Here is the matching message table itself, which provides usernames for both viewport and ‘’viewport/layout’’.

1
2
3
4
5
6
  <atom type="Messages">
    <hash type="Table" key="Commands:category.en_US">
      <hash type="T" key="viewport">Viewports</hash>
      <hash type="T" key="viewport/layout">Layouts</hash>
    </hash>
  </atom>

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
  <atom type="CommandHelp">

    <hash type="Command" key="@en_US">
      <atom type="UserName"></atom>
      <atom type="ButtonName"></atom>
      <atom type="Tooltip"></atom>
      <atom type="Desc"></atom>
      <atom type="Example"></atom>

      <hash type="Argument" key="">
        <atom type="UserName"></atom>
        <atom type="Desc"></atom>
        <atom type="ArgumentType"></atom>
      </hash>

      <!-- Insert more arguments here -->
    </hash>

    <!-- Insert more commands here -->
  </atom>

  <atom type="Categories">
    <hash type="Category" key="Commands">
      <hash type="C" key=""></hash>

      <!-- Insert categorizations for other commands here -->
    </hash>
  </atom>

  <atom type="Messages">
    <hash type="Table" key="Commands:category.en_US">
      <hash type="T" key=""></hash>

      <!-- Insert localizations for other categories and sub-categories here -->
    </hash>
  </atom>

Minimum Template

This template is the very minimum that you need to specify for every command.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
  <atom type="CommandHelp">

    <hash type="Command" key="@en_US">
      <atom type="UserName"></atom>
      <atom type="Desc"></atom>
      <hash type="Argument" key="">
        <atom type="UserName"></atom>
        <atom type="Desc"></atom>
        <atom type="ArgumentType"></atom>
      </hash>

      <!-- Insert more arguments here -->
    </hash>

    <!-- Insert more commands here -->
  </atom>

  <atom type="Categories">
    <hash type="Category" key="Commands">
      <hash type="C" key=""></hash>

      <!-- Insert categorizations for other commands here -->
    </hash>
  </atom>

  <atom type="Messages">
    <hash type="Table" key="Commands:category.en_US">
      <hash type="T" key=""></hash>

      <!-- Insert localizations for other categories and sub-categories here -->
    </hash>
  </atom>

‘’ArgumentType’’ is only necessary for arguments with text hints. See the ArgumentType article for more information.

More Information