Preference Forms

From The Foundry MODO SDK wiki
Jump to: navigation, search

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.

Since the preferences are really just commands in a Form View filtered by the current Preference Category selection, you can fairly easily add any commands you want to the preferences, either for one-off additions to existing forms or by defining completely new categories and their associated forms. This article focuses on the latter.

Creating New Preferences

The contents of both of these views are driven entirely through configs. 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.

Preference Categories

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. 	<atom type="PreferenceCategories">
  2. 		<hash type="PrefCat" key="fileio/wavefrontio"></hash>
  3. 	</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. 	<atom type="Messages">
  2. 		<hash type="Table" key="preferences.categories.en_US">
  3. 			<hash type="T" key="fileio">File I/O</hash>
  4. 			<hash type="T" key="fileio/wavefrontio">Wavefront I/O</hash>
  5. 		</hash>
  6. 	</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 with it. This is the OBJ loader's preferences form.

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

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

  1. 			<atom type="Filter">prefs/fileio/wavefrontio:filterPreset</atom>
  2. 			<hash type="InCategory" key="prefs:general#head">
  3.         			<atom type="Ordinal">80.5</atom>
  4. 			</hash>
  5. 			<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|form category mechanism][, which in turn is what is actually displayed in the Preference Window's Form View. Which forms are actually shown are determined by the form's filters; if not filter was set, the form would always be visible. The ordinal should be unique.
  • Group specifies the [[Form Editor group used to organize the form, and is primarily used to keep the Form Editor neat.

You can also add your form to another already in the preferences using the category mechanism, rather than adding your own category. Since that form will already be filtered, you may not need a filter of your own.

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.

See Also