Preset Browser Filtering

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

As of modo 801, the Preset Browser supports two kinds of filtering, simple string filtering and advanced filtering.

Simple String Filter

The Simple String Filter is commonly used in modo, such as in the Form Editor, Item List, Shader Tree and Command History, and is revealed with the "F" button. In the Preset Browser, this is applied to all of the files in the thumb browser or the flat list (directories are not filtered).

The filter searches both the files name (without the path or extension) and the "tags" markup in the user or shared markups. The tags are split into separate strings at commas, with leading spaces ignored. The filter is then applied to the file name and each tag individually, and if any match the file remains visible. Only if none match the filter is the file hidden.

Advanced Filtering

This should be considered a prototype. While it is powerful, it is somewhat arcane.

In the Viewport Options, there's a simple multi-line edit field labeled Filter String. This allows you to limit what is displayed in the view by testing the markup and metadata. This filter affects the currently visible files in the thumb browser or flat list, and can be set to filter only files or both files and directories.

The format is explicit, but can feel a bit contrived:

(NOT class:attribute(options)={value}..{value}) COMBINER

Parentheses

You can optionally wrap multiple tests in parentheses for grouping purposes. The COMBINER (described below) determines how this test is handled relative against the next test.

NOT

The optional NOT prefix inverts the following test

class

The class is one of intrinsic, metadata, user or shared, and determines where the attribute is pulled from.

attribute

The attribute is the internal name of the attribute to test. Attributes are case sensitive, and are fairly arbitrary (beyond the fact that they obey internal string naming rules).

The intrinsic class supports the following special properties:

  • path: (filepath) The full local path to the file.
  • name: (string) The name portion of the path, including the extension.
  • ext: (string) The extension of the file, if any.
  • size: (memory) The file size on disk. Directories currently return a size of 0.
  • isFile: (boolean) True if this is a file, false if it is a directory.
  • numFiles: (integer) The total number of recognized files in a directory.
  • numDirs: (integer) The total number of subdirectories in a directory.
  • numChildren: (integer) The total number of recognized files and subdirectories in a directory.
  • modTime: (string) When this file or directory was last modified or created (whichever is more recent).

Some examples of common user and shared markup include:

  • isFavorite: (boolean) True if this entry is flagged as a favorite.
  • starRating: (integer) 0-5 indicating the star rating assigned by the user.
  • tags: (string) Arbitrary strings provided by the user for tagging purposes.
  • author: (string) Author of the file.
  • copyright: (string) Copyright information.
  • desc: (string) Description of the file.

The markup is extensible by the user, and can contain arbitrary attributes.

(options)

(options): These is optional, but if present must be in parentheses, and follows the attribute name. The available options depend on the datatype: The list of options are space-delimited.

For strings:

  • substring: Search the attribute for the test value as a substring. This is the default.
  • pattern: Do pattern matching.
  • case: Make the comparison case sensitive. The default is case insensitive.
  • exact: The string must exactly match the test value. This can be used with case to enforce a case-sensitive compare.

Operator

The operator is a standard mathematical test, although the behavior is a bit different depending on the datatype.

  • = (Equal); the value must match exactly. When used with strings, this will do pattern matching, a substring search or an exact match depending on which options are set.
  • < (Less Than), > (Greater Than), <= (Less Than or Equal), >= (Greater Than or Equal); basic logic tests.
    • On numeric types, this works as you would expect.
    • On float numbers, this compares against a very small threshold (epsilon), since you can't directly compare floats for technical reasons.
    • On strings, this does the C function strcmp (or the case insensitive version, depending on if the case option is set) and tests the result. This is most useful when comparing the modTime attribute against another time to find files newer or older than that time.

If no operator is provided, then the filter matches as long as class:attribute exists on the file or directory.

Note that if the attribute does not exist on the file or directory and an operator is present (meaning, you're not just doing an existence test), the test will be considered a failure irrespective of the value being tested against.

Value

The value to test against. It must be wrapped in in one of the following ways:

  • Curly braces {...}: The value string is parsed as a "raw" format value.
  • Square braces [...]: The value string is parsed as a "nice" format value.
  • Less than/greater than bracing <...>: The string is in the form class:attribute path and represents another attribute to be tested against. The path is optional; if present, it is the full local path to another file or directory in the dir cache; if omitted, then the attribute is pulled form the current entry.

These braces are allowed to nest, in case you need braces inside the search string. if there is an unbalanced curly brace inside of that string, it must be escaped with backtick (`). If you actually have to search for a back tick, that needs to be escaped with another backtick (i.e.: ``)

Testing Against Non-Existent Attributes

It is also important to note that a value test will only happen if the attribute actually exists on the item. This means that if you wanted to check for everything that has the isFavorite attribute set to false and you did this:

user:isFavorite={false}

It would only match entries which have been previously flagged as favorites and then turned off again (since turning it off just reset the attribute to false; it didn't remove it from the markup). Thus you would need to do this for your filter:

user:isFavorite={false} OR NOT user:isFavorite

Which would match if the isFavorite attribute is false, or if the isFavorite attribute does not exist.

Range Testing

The .. (two period) syntax can be used to do a range test between the value described above and a second value. The second value after the .. follows the same formatting rules as the first value. This is only valid with the '=' (equal) operator, since it doesn't make sense with any of the others.

When comparing numbers, value from class:attribute must by greater than or equal to the first value and less than or equal to the second value.

When comparing strings, they are both tested against class:attribute's value with strcmp() (or a case-insensitive version, if case is set; other string options are ignored). For those who don't know, strcmp() returns if a string is "less than" (which can generally be thought of as meaning "comes before in sort order") or "greater than" another string. The class:attribute value string must test greater than or equal to the first value string, and less than or equal to the second test string. This is primarily useful when testing file times with the intrinsic:modTime attribute, allowing you to see if a file was created in between two time ranges.

Combiner

When performing multiple tests, the AND and OR combiners can be used to decide if they all must match or only some must match. AND is optional and is inferred if not provided. This is most useful when combined with parentheses.

For example, this matches if a Favorite flag is set in the user markup, or if the user markup Star Rating does not exist, or it does exist and is less than 1.

user:isFavorite={true} AND (NOT user:starRating OR user:starRating<{1})

Directory Filters

Directories support advanced filters stored in user and shared markup. These filters are always applied to the directory's contents when the filter is enabled. You can access the filter via the F badge in the top-right corner. They otherwise work just like the viewport-level filter. It's not as good as Smart Folders, but it's something, I guess.