Form Filtering

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

Filter presets can simply be a copy of the following, replacing the prefs/fileio/wavefrontio strings with your own filter category’s strings.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
        <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 &quot;&quot;</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.

Basic Use

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 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.