Custom Bookmarks

Introduction

Gaffer's file browsers all support user-defined bookmarks to help users in their day-to-day navigation. In addition to users creating their own bookmarks via the UI, you can also create bookmarks via Gaffer's configuration files, making it very easy to create standard bookmarks for shared use across a facility.

Making a config file

The config file is pretty easy to make, following the example provided by startup/gui/bookmarks.py in the main gaffer distribution.

import GafferUI
import MyJobEnvironment

# bookmarks are associated with an application, so we must first acquire the right set
# of bookmarks for this particular application.
bookmarks = GafferUI.Bookmarks.acquire( application )

# now we can go about adding some bookmarks for our current job, sequence and shot,
# assuming we have a handy custom module for getting them.
bookmarks.add( "Job", MyJobEnvironment.currentJobPath() )
bookmarks.add( "Sequence", MyJobEnvironment.currentSequencePath() )
bookmarks.add( "Shot", MyJobEnvironment.currentShotPath() )

# we might want some bookmarks to only appear in certain contexts related to the
# sort of file we're interested in. these are stored in a category-specific set
# of bookmarks which we must acquire on its own.
bookmarks = GafferUI.Bookmarks.acquire( application, category="image" )
bookmarks.add( "Output", MyJobEnvironment.currentShotPath() + "/outputImages" )
bookmarks.add( "Input", MyJobEnvironment.currentShotPath() + "/inputImages" )

# we can also define default locations to be used as the starting point for
# file browsers when the path being edited is empty.
bookmarks = GafferUI.Bookmarks.acquire( application, category="plateImport" )
bookmarks.setDefault( MyJobEnvironment.currentJobPath() + "/fromClient/plates" )

Assigning categories to Op parameters

In the config file we created above, we made different categories of file each with their own bookmarks. That's all well and good, but we need a way of telling the UI which category to use and when. When writing Ops, this is achieved easily enough by specifying the category with a piece of user data.

FileNameParameter(
	name = "myLovelyParameter",
	description = "Put an image here please.",
	defaultValue = "",
	userData = CompoundObject( {
		"UI" : CompoundObject( {
			"bookmarksCategory" : StringData( "image" ),
		} )
	} )
)

The category userData is supported by all PathParameter and PathVectorParameter types.