Form Categories and Groups

Introduced in ‘’modo 401’’, categories and groups provide an easy way to add a form to any other form, and to organize forms in the Form Editor.

Form Categories

‘’Form Categories’’ are an extremely powerful mechanism. It allows you to insert a new form at the beginning or end of any other form simply by having the Kits directory. They need never touch the ‘’Form Editor’’ themselves; the controls will simply appear in the correct place when they run ‘’modo’’. This radically simplifies distributing scripts to users.

The Origin of Categories

Categories got their name from the idea of grouping common forms together. For example, ‘’Tool Properties’’ might be a category, ‘’Item Properties’’ another category, and Preferences yet another category. The goal was to allow new forms to be easily added to an existing form, without being constrained by limits of the normal parent/child relationship that requires the parent form to maintain a list of its children. Categories were quickly expanded beyond a few special cases to include all forms.

Categories invert the normal parent/child relationship used in the forms hierarchy. Normally, a form maintains a list of all of its children. While this makes sense when building a self-contained form, it makes it difficult to add features to an existing form without changing that form as well. This is further complicated when multiple scripts would like to be added to the same existing form. Furthermore, since the config system has exactly two layers – the user config, and all imported configs, with the import order of imported configs being undefined and arbitrary – simply replacing the existing form with the new form doesn’t really work. When upgrading to a new version of the application, a manually-edited form will supersede the new form included with the application, unintentionally hiding new functionality from the user.

Head and Tail Categories

Starting with ‘’modo 401’’, each form has two implicit categories, a ‘’’head category’’’ and a ‘’’tail category’’’. Instead of requiring the parent to keep track of all of its children as in a normal parenting hierarchy, the category system makes the “children” responsible for stating which categories they belong to. Any form added to another form’s ‘’head category’’ will appear before all other controls in that form, while one added to the ‘’tail category’’ will be inserted after all other controls in the form.

Since every form has its own head and tail categories, you can effectively insert a new form at the beginning or end of any other form simply by adding it to the appropriate category. The categorization is completely self contained within your new form.

A single form can be in as many categories as you like. This effectively allows it to replace instancing of forms in most cases (form instances were removed in ‘’modo 401’’ due to their complexity and limited usefulness). It is very common for forms to have no parents, and thus they are often collected into Groups to keep the ‘’Form Editor’’ clean.

Sorting within Categories

Forms can also be sorted within categories through the use of ‘’’ordinals’’’. You only need to worry about the ordinal format if you plan on hand editing your configs, or want a very specific position relative to the other forms in the category. An ordinal is simply a series of numbers between 2 and 255 separated by periods. 0 is never legal and should not be used, as it is used internally to mark the end of the ordinal. 1 is legal in rare cases, but never in the terminal position. Lower numbers appear earlier in the category. If two numbers conflict, the period-separated number is used. You can have as many period-separated numbers as you like, thus ensuring that two ordinals will be unlikely to ever conflict.

This simple ordinal inserts the form in the middle of the category.

1
 128

If there is another form with same ordinal of 128 in that category, then the sort order is undefined. Adding more numbers after a period can be used to position a form between neighboring ordinals. For example, this ordinal will position its form before 128 but after ‘’’127’’’.

1
 127.2

If all of the components of the ordinal are the same, the sort order is undefined, but you can always add more components to resolve any conflicts. Just remember that the numbers must range from 2-255, 0 is invalid, and 1 cannot appear at the end. This ordinal contains a 1 in the second position which allows it to sort between 127 and the 127.2 example above. That’s the only valid use of 1 in an ordinal.

1
  127.1.233.12

Manually specifying an ordinal is most useful when you are providing multiple forms and want to ensure that one comes before the other. It is often not possible to specifically sort your form relative to other third party forms as you don’t have any way of knowing the ordinals of the other forms.

Categories in the Form Editor

To access the categories of a form, simply unfold the +/- disclosure widget to left of the form’s name in the Form Editor. The ‘’Head Category’’ and ‘’Tail Category’’ will be the first two entries.

To add a form to a category, simply drag and drop it into that category. You can also use drag and drop to re-order categories (and thus implicitly change their ordinals), and remove them from the category via a context menu. Once a form is in a category, it will automatically appear in the correct place in its parent form.

If you save a form to disk from the ‘’Form Editor’’, or export its config fragment, all of the categories it contains will be included with it. This means that once you have finished with your script or plug-in’s interface, you can distribute it or add it to your kit simply by choosing it and selecting the Save Form button. Your users can just drop your kit, or your script and its config, into the user scripts and/or configs directories, run modo and immediately start using your scripts with no other setup required.

Common Categories

There are a few forms that commonly have other forms added to their categories:

  • ‘’’modo Modes Tail’’’ (hash: ‘’modoModesTail’’, previously ‘’26077270201:sheet’’), originally known as simply ‘’modo Modes’’. ‘’modo Modes’’ is the name of the toolbar along the top of many of the standard modo main window layouts. Kits needed a way to add themselves to those layouts, so they tried adding themselves directly to the ‘’modo Modes’’ tail category. They also needed to add themselves to the ‘’Animate Modes’’ form’s category for the Animate layout. Since it was very likely that even more “modes” forms would be added in the future, the ‘’26077270201:sheet ‘’hash was re-assigned to the ‘’modo Modes Tail (legacy)’’ form in order to maintain backwards compatibility. ‘’modo Modes Tail (legacy)’’ was then added to the end of all of the other “modes” forms. From 701 onwards a kit should add itself to the tail of modoModesTail and it will correctly appear in all of the main window toolbars.

  • ‘’’Item Properties’’’ (hash: ‘’itemprops:general’’). This form contains all of the item properties forms as entries into its categories. Each such form is displayed as a vertical tab. Forms usually have filters applied so that they only appear when a specific item type is selected.

  • ‘’’Item Properties: Textures’’’ (hash: ‘’itemprops:textures’’). Similar to the ‘’Item Properties’’, but is limited to textures items. It is itself included in the tail category of the ‘’Item Properties’’ form, so any forms added here will show up there as well.

  • ‘’’Tool Properties’’’ (hash: ‘’toolprops:general’’). This contains all of the tool properties forms. Forms are usually filtered to only appear when an given tool is active.

  • ‘’’Menu Bar’’’ (hash: ‘’menubar’’). This is the main menu bar at the top of the window/screen. New menus can be added by inserting forms into its categories.

Prior to ‘’modo 401’’, forms would often be grouped together by parenting them to other forms purely to keep the ‘’Form Editor’’ clean. While this worked in a limited sense, it wasn’t very elegant. ‘’modo 401’’ introduces ‘’’groups’’’.

As with ‘’categories’’, the form itself defines the groups that it belongs to. A form can be in only one group, or in no group at all. Groups are especially useful when dealing with forms in ‘’categories’’, as they often do not have a parent and would otherwise clutter up the root of the ‘’Form Editor’’.

Using Groups

New groups can easily be created from within the ‘’Form Editor’’. A group is not defined solely by its name, but rather by its complete path. For this reason, groups cannot be moved or renamed from the ‘’Form Editor’’, as this would affect all other forms in those groups and cause them to be moved into the user config (since all config changes are written only to the user config; see the Config Files article for more information). Adding a form to a group is a simple matter of drag and drop. Forms inside a group are always sorted alphabetically.

User Readable Group Names and Message Tables

If you are editing a config by hand and want to create groups there, the format is ‘’basegroup/subgroup’’, where forward slashes are used to define the group hierarchy. The names can be user-readable, but it is often desirable to specify them as internal strings and use Message Tables instead. This example config snippet shows how such a message table might be constructed for a group hierarchy named ‘’myGroup’’, and its child ‘’myGroup/mySubGroup’’. Note that myGroup has its own separate message table entry. The key must always start with ‘’attrgroup:’’, with message index 1 being used as the group’s name. Also remember that keys and group names are case sensitive.

1
2
3
 <?xml version="1.0"?>
 <configuration>
      <atom type="Messages">

1
2
3
          <hash type="Table" key="attrgroup:myGroup.en_US">
              <hash type="T" key="1">My Group</hash>
          </hash>

1
2
3
         <hash type="Table" key="attrgroup:myGroup/mySubGroup.en_US">
              <hash type="T" key="1">My Sub-Group</hash>
          </hash>

1
2
    </atom>
 </configuration>

More Information