Difference between revisions of "Preset Browser Paths"
(Created page with "The Preset Browser viewport (sometimes shortened to ''PBView'' on the [http://forums.luxology.com/index.aspx forums]) is a thumbnail-based file browser for locating ''modo...")
Revision as of 17:38, 1 January 2013
The Preset Browser viewport (sometimes shortened to PBView on the forums) is a thumbnail-based file browser for locating modo-related content from a series of base paths, which can then be loaded via drag and drop or by double-clicking on the file. Originally intended for presets, it also supports image and can be extended to other file types through plug-ins.
Preset Browsers are built on two underlying interface elements: The DirBrowser, and the DirThumbBrowser (which in turn is built on a ThumbBrowser, and sometimes a tree pane). These are not themselves currently exposed to plug-ins for custom interfaces, but it can help to know how the browser is built when defining a custom Preset Browser viewport.
The DirBrowser pane is on the left of the browser. It shows a specific set of directories from the file system known as base paths. The lists of base paths can be changed at any time by the user by clicking the "X" to delete one, or the "(new path)" entry to add a new one. You can make an entire drive a base path if you like, although that isn't usually done. Instead, specific sets of directories containing modo-specific content are usually set so that you can easily jump to the relevant directories without having to wade through all the others. It's also important to note that the base paths are associated with the DirBrowser, and it is that which manages those paths in the config.
When a Preset Browser viewport is created, it tells the DirBrowser to initially use the global presetChoice set of base paths. At present there is no way to change the set of base paths from the UI, as it was intended to be an advanced feature used by developers. It can, however, be changed by modifying the config file directly.
To create a browser with a custom set of base paths, you add or change the ClientPath entries in the DirBrowser" part of a config file. You then edit a Preset Browser's config state to use that set of base paths by changing its OverrideDefaultBasePaths atom to match those ClientPath entries.
Examples of some common base path sets can be found in resrc/embeddedbrowsers.cfg. Some of the Preset Browser viewports referenced there are embedded into Form Views for use by tools, and use other properties like Hash that aren't directly applicable to more general Preset Browsers.
Preset Browsers and Base Path Sets
The Preset Browser references a specific set of base paths as part of its viewport state in the config file. This is an example for a "Meshes" browser from the standard configs.
<atom type="Frame"> <hash type="presetbrowserview" key="base.Meshes" val="1"> <atom type="Hash">Meshes</atom> <atom type="OverrideDefaultBasePaths">Meshes</atom> <atom type="FilterBy">meshLayer</atom> <atom type="MinHeader">1</atom> <atom type="ViewportTitle">Mesh Preset Browser</atom> <atom type="ViewportClass">vpdataLists</atom> </hash> </atom>
- Hash is a unique hash used for selection purposes. This creates a selection sub-type that clients can read for special purposes. An example is the Polygon Bevel tool, which uses the hash to define a selection sub-type that will remain available even if a preset is selected in another general preset browser.
- OverrideDefaultBasePaths is the name of a base path set, as described below, and determines which base paths show up in the DirBrowser pane. If empty or omitted (such as when creating a new Preset Browser viewport from the UI), the default "'presetChoice set is used.
- FilterBy allows the browser to be filtered to only show presets that match a specific server. In modo 601 and earlier, this was the GUID alias of the destination interface the preset server expected for drag and drop, but this is likely to change in the future to just the name of the preset server that recognized the file. This can be changed from the viewport's options in the UI, although in practice a directory usually only contains one kind of preset, so this usually isn't needed.
Base Path Sets
The list of base paths are stored in the DirBrowser portion of a config file. For example, here is the base paths for the default presetChoice set from the aforementioned config.
<atom type="DirBrowser"> <hash type="ClientPath" key="presetChoice@asset:">1</hash> <hash type="StateCurrentPath" key="presetChoice">asset:</hash> <hash type="StatePathExpand" key="presetChoice@asset:">1</hash> </atom>
- ClientPath is a specific path. The key is in the form of basePathSet@path, where basePathSet is the name you would use in the OverrideDefaultBasePaths portion of a Preset Browser's config entry, and path is the path on disk. The path can be an alias or an absolute path on the file system. The number 1 indicates that this entry will be shown in the browser, while a 0 indicates that it has been "deleted". This exists to work around the fact that you can only delete entries user configs; we simply mark it as deleted so that we know to ignore it on load. There can be as many ClientPath entries as you like for a given base path set.
- StateCurrentPath is the current path for a given base path set. The key is the base path set itself, while the value is the current path. This can be used to point the browser to a specific path when it is instantiated, and changes when the user changes the current directory through the UI. There is only one of these per base path set.
- StatePathExpand indicates if a given path in a base path set is expanded or collapsed in the DirBrowser tree. If the value is 1, the path is expanded, while 0 is used to collapse it. The key format is the same as for ClientPath. There can be one of these for each ClientPath entry.
The word "state" is used in those names to indicate that they are state that changes simply by interacting with the browser, in these cases by clicking on a different directory or by collapsing/expanding a parent directory. The word "client" in ClientPath is used as a synonym for "base path set", in that it indicates the intended use of this set of paths.