Filters make sure that our form is visible only when a specific action occurs, such as an item type being selected, a tool being active, or a command being enabled. For instance, selecting a specific item type can allow a form of properties for that item type to show as a sub-form in the standard "Item Properties" form, but be hidden anytime an item of that type is not selected.
Filter presets can simply be a copy of the following, replacing the prefs/fileio/wavefrontio strings with your own filter category's strings.
<atom type="Filters"> <hash type="Preset" key="prefs/fileio/wavefrontio:filterPreset"> <atom type="Name">Wavefront I/O</atom> <atom type="Category">20385740002:filterCat</atom> <atom type="Enable">1</atom> <list type="Node">1 .group 0 ""</list> <list type="Node">1 prefType fileio/wavefrontio</list> <list type="Node">-1 .endgroup </list> </hash> </atom>
Most of this is fairly esoteric; the filter system is an older, limited mechanism that is not well documented and is only used in special circumstances. It's primary use is to limit which forms are visible in Preferences, Item Properties, Tool Properties and similar Form Views.
- Preset is your preset's hash. This can be anything you want, as long as it is unique and matches that of the Filter atom in your form.
- Name is the name of the preset. Although this isn't generally shown, it's good to have.
- Category is used to group forms in the legacy Filter Editor. The hash 0385740002:filterCat represents the Preferences group, so you can just use that.
- Enable is set to 1 if the filter is enabled, which it should be.
- Node entries are used to build a hierarchy of filter criteria. The important part here is to change the "fileio/wavefrontio" bit to match the Preference Category you created earlier, which will cause the prefType filter to test true when that Preference Category is selected. Everything else should remain the same.
In addition to using filter presets, a form's visibility can be determined by a command's enable state. Commands-as-filters provide much more flexibility, as the ancient filter preset system isn't (and won't be) exposed through the SDK, and often commands already exist for toggling a set of controls on and off.
Commands-as-filters are set up from the Filter Command on the form in Form Ed. It is stored in the form's config state as a FilterCommand atom.
If the command is enabled, the form is visible; otherwise, it is hidden. Any command can be used as the filter, but if the command has a notifier then the form will automatically show and hide as the command's state changes.
Boolean Query Arguments
The command can also have a boolean argument marked for query. In that case, both:
- The command must both be enabled, and
- One of the queried values returned must be true
If both of those conditions are true, the form is shown.
If the command is disabled or all of the queried values are false, the form is hidden. This only works with boolean-style arguments; if any other kind of argument is marked then only the enable state will be used.
As of 14.0 (I think), more complex tests can be done on integers, strings and text hits by prefixing the command with a key character, the value to compare against, and a space followed by the command string.
- Equals (=): The queried value from the command must exactly match the value after the equal sign. For example, "=20" means the queried command value must be 20. "=raytrace" means the string or text hint queried must be "raytrace"
- Equals Equals (==): One equals does a case-sensitive string compare, while double-equals does a case-insensitive string compare.
- Less Than (<) or Greater Than (>): The queried numeric value must be less than or greater than the queried value.
- Less Than Equals (<=) or Greater Than Equals (>=): Self explanatory.
- List (=a|b|c): Text hints and strings support testing multiple values by separating them with vertical bars. ==a|b|c does a case-insensitive compare, while =a|b|c is case-sensitive. Note that spaces are not supported.
- Not (!): This can prefix the other values, and inverts the test. For example, "!=raytrace" would match all values but raytrace.
A simple example would command would be "=MyItem item.name ?", where the filter would only be considered a match if the item was named "MyItem". Note that the prefix condition cannot have any spaces, so "My Item" would not be a vlid string, even if quotes or braces are used.