Preference Forms

‘’modo’’’s Preferences Window is a combination of two viewports:

  • ‘’’The “Preferences” viewport’’’, a tree which shows the different preference categories

  • ‘’’A Form View’’’, which contains the individual preference controls themselves.

Creating New Preferences

The contents of both of these views are driven entirely through Config System. We’ll use the OBJ sample plug-in as an example to show how preferences are added to modo’s interface.

There are four config components that need to be set up to add something to the preferences:

  • ‘’’Preference Category’’’, to create a new branch in the tree.

  • ‘’’Preference Category Message Table’’’, to define a username for the new category.

  • ‘’’Preference Form’’’, which is added to the main preference form’s category and contains the preferences you want to display in the Form View.

  • ‘’Form Filter’’, which ensures that your form is only visible when your category is selected.

To define a new preference category, you add a new PreferenceCategories atom to your config with a PrefCat hash. This is the OBJ loader’s preference category.

1
2
3
        <atom type="PreferenceCategories">
                <hash type="PrefCat" key="fileio/wavefrontio"></hash>
        </atom>

This particular category’s full path is ‘’fileio/wavefrontio’’. Forward slashes indicate sub-categories, allowing for nesting and organization within the preference tree.

Each component of the path needs a username. This is done with Message Tables. The table’s key is always preferences.categories followed by the language code. The individual T entries represent the component within the category path, each of which must be individually assigned a message entry.

1
2
3
4
5
6
        <atom type="Messages">
                <hash type="Table" key="preferences.categories.en_US">
                        <hash type="T" key="fileio">File I/O</hash>
                        <hash type="T" key="fileio/wavefrontio">Wavefront I/O</hash>
                </hash>
        </atom>

Since “fileio” is already defined in the standard resources we really don’t have to redefine it here; it is only included to illustrate that you should be sure to supply messages for each component of your preference category path if you know it’s not already defined.

Forms

To add controls to your newly-created category, you simply need to associate a Form System with it. This is the OBJ loader’s preferences form.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
        <atom type="Attributes">
                <hash type="Sheet" key="940394857822:sheet">
                        <atom type="Label">Wavefront Object Export</atom>
                        <list type="Control" val="cmd user.value sceneio.obj.export.groups ?">
                                <atom type="Label">Save Meshes as Groups</atom>
                                <atom type="Tooltip">Save meshes as groups</atom>
                        </list>
                        <list type="Control" val="cmd user.value sceneio.obj.export.material.format ?">
                                <atom type="Label">Save Material File</atom>
                                <atom type="Tooltip">Save the material file (.mtl)</atom>
                        </list>

                        <atom type="Filter">prefs/fileio/wavefrontio:filterPreset</atom>
                        <hash type="InCategory" key="prefs:general#head">
                                <atom type="Ordinal">80.5</atom>
                        </hash>
                        <atom type="Group">prefs/fileio</atom>
                </hash>
        </atom>

The above form contains two controls defined through User Values. There are also five lines at the bottom that specify how this appears in a form view.

1
2
3
4
5
                        <atom type="Filter">prefs/fileio/wavefrontio:filterPreset</atom>
                        <hash type="InCategory" key="prefs:general#head">
                                <atom type="Ordinal">80.5</atom>
                        </hash>
                        <atom type="Group">prefs/fileio</atom>

  • Filter is a filter that we set up previously that displays this form when a specific selection has occurred, which in this case is that the wavefrontio preference category is selected.

  • InCategory adds the form to the generic preferences form using the Form Categories and Groups#Form Categories should be unique.

  • Group specifies the [[Form Categories and Groups#Groups neat.

Filter

Filter’s can be setup using configs, or using commands to determine if a form should be visible. Details are explained on the Form Filtering page.