An Asset Shelf provides fast and convenient access to assets from specific editors, without having to open an Asset Browser. It is optimized for using assets for a specific task (for example animating with pose assets, or painting with brush assets), and as such is more limited in functionality than the Asset Browser, but more efficient for certain contexts of use.
The asset shelf uses the All asset library, and makes use of asset catalogs for efficient navigation within it.
Not all editors support asset shelves. Enabling them for a new editor requires some work, as explained below.
Source Code Locations¶
Most asset shelf code can be found in:
|Main asset shelf source files.
|API to integrate asset shelves in editors.
|DNA type declarations (supporting file read/write):
|RNA integration (the Python API is generated from this).
|Generic asset shelf UI elements.
Custom Asset Shelves¶
To display an asset shelf in a specific context, and for specific kinds of assets, a new asset shelf type can be registered. In Python this works like this:
This will display an asset shelf in sculpt mode, for assets that are of ID type
A template for this can be found in the Text Editor under Templates > Python > Ui Asset Shelf.
Custom Activation Behavior¶
When clicking on an asset, it becomes active in the UI. For the asset shelf you'd often want this to apply some asset, e.g. to apply the clicked on pose asset or activate the clicked on brush asset. This can be done by overriding the keymap item for clicking in the asset shelf.
register() function of a script/add-on (using the pose library as an example here):
The asset shelf provides context that the operator of the keymap item can use, see Context.
Custom Drag & Drop Behavior¶
The behavior for dragging can be overridden in a similar fashion. However, the default asset dragging has to be disabled in the asset shelf type definition first:
And then override the keymap item for dragging in the asset shelf:
Custom Context Menu¶
Customizing the context menu for the asset shelf and a specific asset is trivial too:
Asset Shelf Management¶
Available Asset Shelf Types¶
Note that the asset shelf type is registered for a specific editor type, 3D View in the example above. When an editor of this type is shown, its registered asset shelf types are polled on every redraw. Once the
poll() of an asset shelf type returns
True, that indicates that this asset shelf type is available. The system can then try to restore a previously instanced asset shelf of this type, or create a new one if needed.
Multiple Available Asset Shelf Types¶
It is possible that multiple asset shelf types are available (i.e. multiple shelf types return
True in their
poll() in a given context). To keep the system simple, only one shelf can be visible in an editor at a time. This is considered to be the active shelf. The user could be presented with a selector to choose from one of the available asset shelf types when necessary, but this isn't implemented yet.
Previously active shelves are kept in memory. When the active shelf becomes unavailable, these previously active ones get polled in order from most recently to least recently activated. So as context changes, the most recently used asset shelves get priority in determining the new shelf to activate. Otherwise, the first registered asset shelf type that is available will be used to create a new asset shelf to activate from.
The alternative would be merging settings from multiple asset shelves into a runtime asset shelf. When writing the asset shelves to a file, they could all be written with the same settings (or somehow be split?). This could be done but doesn't seem necessary for now.
The asset shelf is split in two regions:
- Main Region
- The region displaying the assets in a grid-view (see views documentation).
- This region uses paginated scrolling and strict region size snapping, so that it always 1 or more full row of assets, never a partial asset row.
- Region types:
- Footer Region
- Contains display options, filter controls and the catalog tabs.
- Region type:
The main region displays assets in a grid-view using the UI view system for its layout. It defines default drag controllers, and calls the necessary callbacks of the asset shelf type, such as the
draw_context_menu() method. The asset view uses the asset list API to fetch the asset library.
Asset Catalog Selector¶
The asset catalog selector uses a tree-view for its layout. Its main purpose is to enable or disable asset catalogs in the settings of the asset shelf (
AssetShelfSettings.enabled_catalog_paths). The displayed tree is the merged tree, so multiple catalogs with the same path show up as a single element in the tree. To be able to display the catalog tree, it loads the asset library using the asset list API (although it should already be loaded by the Asset View).
Asset shelves broadcast data to context while one of the asset shelf regions is active in context (e.g. while the mouse hovers one and nothing overrides it).
The following data members are added:
- The active shelf, if any (
- The asset library reference currently visible in the active shelf (
- The file representing the asset. Temporary workaround, should be replaced by a proper asset representation or handle (
View3D --> "1" AssetShelfHook
AssetShelfHook --> "*" AssetShelf
AssetShelf --* AssetShelfSettings: Contains
AssetShelf --* AssetShelfType: Contains
Asset shelves store their data mostly through the following structs:
- Container for spaces to embed all permanent asset shelf data. This contains a list of
AssetShelfinstances (the storage of previously active asset shelves) and information on the active shelf. Availability of the active shelf is queried on redraws, so the active shelf may change on context changes.
- Data of a single shelf, created by activating a shelf of a given
AssetShelfType. Holds type information and settings, whereby settings are stored in a nested
- The settings for an
AssetShelfinstance such as the enabled asset catalogs and other display options.
- Runtime type information like the identifier and callbacks of the asset shelf.
Except of the runtime-only
AssetShelfType, these structs are part of SDNA so they can be written to .blend files.
Adding Asset Shelf Support to an Editor Type¶
Making Asset Shelves available in an editor is not too hard, but requires some work still. The
ED_asset_shelf.h header contains most public functions required for this. The following is a rough checklist to follow (not too specific since this can get outdated quickly).
AssetShelfHookto the space data of the editor, and call the duplicate, file read and file write functions from the necessary places.
- Theme options?
- Is it one asset shelf or multiple?
For the user, it is usually enough to refer to the two regions at the bottom with their contents as asset shelf. In more precise language, these can be considered the asset shelf regions, with contents defined by the active asset shelf data and the asset shelf type it was instantiated from. So multiple asset shelves are kept in storage (each of a different type), but only one is active (as in: visible) at a time.