Foundry::Katana::GroupBuilder Class Reference

A factory class for constructing GroupAttribute objects. More...

#include <FnGroupBuilder.h>

List of all members.

Public Types
enum	BuilderMode { BuilderModeNormal = kFnKatGroupBuilderModeNormal, BuilderModeStrict = kFnKatGroupBuilderModeStrict }
enum	BuilderBuildMode { BuildAndFlush = kFnKatGroupBuilderBuildAndFlush, BuildAndRetain = kFnKatGroupBuilderBuildAndRetain }
Public Member Functions
	GroupBuilder ()
	GroupBuilder (BuilderMode builderMode)
GroupBuilder &	set (FnPlatform::StringView path, const Attribute &attr, bool groupInherit=true)
GroupBuilder &	setWithUniqueName (FnPlatform::StringView path, const Attribute &attr, bool groupInherit=true)
GroupBuilder &	del (FnPlatform::StringView path)
GroupBuilder &	update (const GroupAttribute &attr)
GroupBuilder &	deepUpdate (const GroupAttribute &attr)
GroupBuilder &	reserve (int64_t n)
GroupBuilder &	setGroupInherit (bool groupInherit)
GroupBuilder &	sort ()
GroupAttribute	build (BuilderBuildMode builderMode=BuildAndFlush)

---

Detailed Description

A factory class for constructing GroupAttribute objects.

Typical usage involves creating a GroupBuilder, adding attributes to it with the set() method, and, when finished, retrieving a newly constructed GroupAttribute using the GroupBuilder's build() method.

Warning:

There is currently no way to inspect the contents of the builder, other than by calling build() and inspecting the generated GroupAttribute. Note that by default build() clears the contents of the builder; to override this behaviour pass GroupBuilder::BuildAndRetain to build().

As a convenience, GroupBuilder has support for creating arbitrarily nested GroupAttribute structures by passing a dot-delimited string to set(), which is referred to as a "path". Note that this implies that the '.' character is not a valid attribute name!

Example:

 GroupBuilder gb;
 gb.set("my.nested.attribute", IntAttribute(2));
 gb.set("myTopLevelAttribute", StringAttribute("taco"));
 gb.set("myOtherTopLevelAttribute", FloatAttribute(4.0f));

 GroupAttribute groupAttribute = gb.build();

 // Following the call to build(), |gb| is empty and |groupAttribute| has
 // the following structure:
 //
 // {
 //   "my": {
 //     "nested": {
 //       "attribute": IntAttribute(2)
 //      }
 //   },
 //   "myTopLevelAttribute": StringAttribute("taco"),
 //   "myOtherTopLevelAttribute": FloatAttribute(4.0f)
 // }

---

Member Enumeration Documentation

enum Foundry::Katana::GroupBuilder::BuilderBuildMode

An enumeration of flags to control the behaviour of the build() method.

Enumerator:

BuildAndFlush	Specifies that the builder's contents are cleared following a call to build(). This is the default.
BuildAndRetain	Specifies that the builder's contents are retained following a call to build().

enum Foundry::Katana::GroupBuilder::BuilderMode

An enumeration of available modes in which GroupBuilder objects can build their resulting GroupAttribute objects.

The builder mode is set when constructing a GroupBuilder object.

Enumerator:

BuilderModeNormal	The "normal" build mode, which allows the full suite of GroupBuilder functionality. This is the default.
BuilderModeStrict	An advanced option that enables a more restrictive but higher performance mode of operation. When working in this mode: callers must not pass dot-delimited paths to the set() method callers must not make multiple calls to set() using the same path deletions are disallowed: the del() method becomes a no-op.

---

Constructor & Destructor Documentation

Foundry::Katana::GroupBuilder::GroupBuilder

(

)

[inline]

Creates a new, empty GroupBuilder object.

Remarks:

The builder is created with GroupBuilder::BuilderModeNormal.

Foundry::Katana::GroupBuilder::GroupBuilder

(

BuilderMode

builderMode

)

[inline]

Creates a new, empty GroupBuilder that uses the specified \ BuilderMode .

---

Member Function Documentation

GroupAttribute Foundry::Katana::GroupBuilder::build

(

BuilderBuildMode

builderMode = BuildAndFlush

)

[inline]

Returns a newly created group attribute with the contents of the builder.

Parameters:

builderMode

An optional argument specifying whether the builder's contents are retained.

Warning:

GroupAttribute supports up to 2^28 children. An invalid attribute will be returned if this limit is breached.

By default, the contents of the builder are cleared following a call to build(). To reuse the builder while retaining its contents, pass GroupBuilder::BuildAndRetain for the optional builderMode argument.

Referenced by GLTranslateManipulator::getTags(), GLScaleManipulator::getTags(), GLRotateManipulator::getTags(), GLCoiManipulator::getTags(), and Foundry::Katana::ViewerAPI::PickedAttrsMap::toGroupAttribute().

GroupBuilder& Foundry::Katana::GroupBuilder::deepUpdate

(

const GroupAttribute &

attr

)

[inline]

Recursively updates the contents of the builder with the attributes held within the provided group attribute.

Groups are traversed until set operations can be applied at the leaves which are not GroupAttribute objects themselves.

If setGroupInherit() has not been previously called, the builder will also adopt the incoming GroupAttribute's groupInherit flag.

References Foundry::Katana::Attribute::isValid().

GroupBuilder& Foundry::Katana::GroupBuilder::del

(

FnPlatform::StringView

path

)

[inline]

Deletes the attribute of the builder specified with the given path.

Remarks:

This has no effect if the builder was created with GroupBuilder::BuilderModeStrict.

GroupBuilder& Foundry::Katana::GroupBuilder::reserve

(

int64_t

n

)

[inline]

Reserves space for n attributes.

This is an optimisation only. Calling reserve() before adding attributes will avoid having to reallocate internal data structures.

Parameters:

n	The number of attributes the group attribute is to have.

GroupBuilder& Foundry::Katana::GroupBuilder::set	(	FnPlatform::StringView	path,
		const Attribute &	attr,
		bool	groupInherit = true
	)		[inline]

Sets the value for the attribute identified by the given path.

If path refers to an existing attribute in the builder and the builder was created with GroupBuilder::BuilderModeNormal, the attribute is replaced.

Parameters:

path	The path of the attribute whose value to set.
attr	The attribute object to set for the given path.
groupInherit	If path is a dot-delimited path, specifies the groupInherit flag for any new groups added by this set() call.

Remarks:

If the builder was created with GroupBuilder::BuilderModeStrict, note the caveats (documented above) for working in this mode.

The empty string ("") is not a valid path component.

Referenced by GLTranslateManipulator::getTags(), GLScaleManipulator::getTags(), GLRotateManipulator::getTags(), GLCoiManipulator::getTags(), and Foundry::Katana::ViewerAPI::PickedAttrsMap::toGroupAttribute().

GroupBuilder& Foundry::Katana::GroupBuilder::setGroupInherit

(

bool

groupInherit

)

[inline]

Sets a special flag on the builder that determines the value returned by GroupAttribute::getGroupInherit() for the top-level GroupAttribute returned by build().

This groupInherit flag is sticky, so once it's been set -- either through an explicit call to setGroupInherit(), or indirectly via a call to update()/deepUpdate() -- further calls to setGroupInherit() will have no effect.

GroupBuilder& Foundry::Katana::GroupBuilder::setWithUniqueName	(	FnPlatform::StringView	path,
		const Attribute &	attr,
		bool	groupInherit = true
	)		[inline]

Sets the value for an attribute identified using a unique name derived from the given path.

If no attribute exists for the given path, this is equivalent to calling set(). Otherwise, setWithUniqueName() chooses a new path by suffixing the given path with an integer.

Parameters:

path	The base path of the attribute whose value to set.
attr	The attribute object to set for the resulting path.
groupInherit	If path is a dot-delimited path, specifies the groupInherit flag for any new groups added by this set() call.

GroupBuilder& Foundry::Katana::GroupBuilder::sort

(

)

[inline]

Sorts the top-level attributes of the builder by name.

Remarks:

sort() uses bytewise lexicographic ordering.

GroupBuilder& Foundry::Katana::GroupBuilder::update

(

const GroupAttribute &

attr

)

[inline]

Updates the contents of the builder with the attributes from the given GroupAttribute.

Any new attributes with the same names as existing attributes replace the old ones. Existing attributes not matching new attributes are left intact. (This is analogous to the Python dictionary's update method.)

If setGroupInherit() has not been previously called, the builder will also adopt the incoming GroupAttribute's groupInherit flag.

Parameters:

attr	A GroupAttribute containing new attributes to add

References Foundry::Katana::Attribute::isValid().

---

The documentation for this class was generated from the following file:

• FnGroupBuilder.h