Loads and maintains a tree of Components from a ValueTree that represents them. More...

#include <juce_ComponentBuilder.h>

Inheritance diagram for juce::ComponentBuilder:

Collaboration diagram for juce::ComponentBuilder:

[legend]

Classes
class	ImageProvider
	This class is used when references to images need to be stored in ValueTrees. More...

class	TypeHandler
	The class is a base class for objects that manage the loading of a type of component from a ValueTree. More...

Public Member Functions
	ComponentBuilder ()
	Creates a builder that doesn't have a state object. More...

	ComponentBuilder (const ValueTree &state)
	Creates a ComponentBuilder that will use the given state. More...

	~ComponentBuilder () override
	Destructor. More...

Component *	createComponent ()
	Creates and returns a new instance of the component that the ValueTree represents. More...

TypeHandler *	getHandler (int index) const noexcept
	Returns one of the registered type handlers. More...

TypeHandler *	getHandlerForState (const ValueTree &state) const
	Tries to find a registered type handler that can load a component from the given ValueTree. More...

ImageProvider *	getImageProvider () const noexcept
	Returns the current image provider that this builder is using, or nullptr if none has been set. More...

Component *	getManagedComponent ()
	Returns the builder's component (creating it if necessary). More...

int	getNumHandlers () const noexcept
	Returns the number of registered type handlers. More...

void	registerStandardComponentTypes ()
	Registers handlers for various standard juce components. More...

void	registerTypeHandler (TypeHandler *type)
	Adds a type handler that the builder can use when trying to load components. More...

void	setImageProvider (ImageProvider *newImageProvider) noexcept
	Gives the builder an ImageProvider object that the type handlers can use when loading images from stored references. More...

void	updateChildComponents (Component &parent, const ValueTree &children)
	Updates the children of a parent component by updating them from the children of a given ValueTree. More...

Public Attributes
ValueTree	state
	This is the ValueTree data object that the builder is working with. More...

Static Public Attributes
static const Identifier	idProperty
	An identifier for the property of the ValueTrees that is used to store a unique ID for that component. More...

Private Member Functions
void	valueTreeChildAdded (ValueTree &, ValueTree &) override
	This method is called when a child sub-tree is added. More...

void	valueTreeChildOrderChanged (ValueTree &, int, int) override
	This method is called when a tree's children have been re-shuffled. More...

void	valueTreeChildRemoved (ValueTree &, ValueTree &, int) override
	This method is called when a child sub-tree is removed. More...

void	valueTreeParentChanged (ValueTree &) override
	This method is called when a tree has been added or removed from a parent. More...

void	valueTreePropertyChanged (ValueTree &, const Identifier &) override
	This method is called when a property of this tree (or of one of its sub-trees) is changed. More...

virtual void	valueTreeRedirected (ValueTree &treeWhichHasBeenChanged)
	This method is called when a tree is made to point to a different internal shared object. More...

Private Attributes
std::unique_ptr< Component >	component

WeakReference< Component >	componentRef

ImageProvider *	imageProvider

OwnedArray< TypeHandler >	types

Detailed Description

Loads and maintains a tree of Components from a ValueTree that represents them.

To allow the state of a tree of components to be saved as a ValueTree and re-loaded, this class lets you register a set of type-handlers for the different components that are involved, and then uses these types to re-create a set of components from its stored state.

Essentially, to use this, you need to create a ComponentBuilder with your ValueTree, then use registerTypeHandler() to give it a set of type handlers that can cope with all the items in your tree. Then you can call getComponent() to build the component. Once you've got the component you can either take it and delete the ComponentBuilder object, or if you keep the ComponentBuilder around, it'll monitor any changes in the ValueTree and automatically update the component to reflect these changes.

@tags{GUI}

Constructor & Destructor Documentation

◆ ComponentBuilder() [1/2]

juce::ComponentBuilder::ComponentBuilder ( const ValueTree & state )

explicit

Creates a ComponentBuilder that will use the given state.

Once you've created your builder, you should use registerTypeHandler() to register some type handlers for it, and then you can call createComponent() or getManagedComponent() to get the actual component.

◆ ComponentBuilder() [2/2]

juce::ComponentBuilder::ComponentBuilder ( )

Creates a builder that doesn't have a state object.

◆ ~ComponentBuilder()

juce::ComponentBuilder::~ComponentBuilder ( )

override

Destructor.

Member Function Documentation

◆ createComponent()

Component* juce::ComponentBuilder::createComponent ( )

Creates and returns a new instance of the component that the ValueTree represents.

The caller is responsible for using and deleting the object that is returned. Unlike getManagedComponent(), the component that is returned will not be updated by the builder.

◆ getHandler()

TypeHandler* juce::ComponentBuilder::getHandler ( int index ) const

noexcept

Returns one of the registered type handlers.

See also: getNumHandlers, registerTypeHandler

◆ getHandlerForState()

TypeHandler* juce::ComponentBuilder::getHandlerForState ( const ValueTree & state ) const

Tries to find a registered type handler that can load a component from the given ValueTree.

◆ getImageProvider()

ImageProvider* juce::ComponentBuilder::getImageProvider ( ) const

noexcept

Returns the current image provider that this builder is using, or nullptr if none has been set.

◆ getManagedComponent()

Component* juce::ComponentBuilder::getManagedComponent ( )

Returns the builder's component (creating it if necessary).

The first time that this method is called, the builder will attempt to create a component from the ValueTree, so you must have registered some suitable type handlers before calling this. If there's a problem and the component can't be created, this method returns nullptr.

The component that is returned is owned by this ComponentBuilder, so you can put it inside your own parent components, but don't delete it! The ComponentBuilder will delete it automatically when the builder is destroyed. If you want to get a component that you can delete yourself, call createComponent() instead.

The ComponentBuilder will update this component if any changes are made to the ValueTree, so if there's a chance that the tree might change, be careful not to keep any pointers to sub-components, as they may be changed or removed.

◆ getNumHandlers()

int juce::ComponentBuilder::getNumHandlers ( ) const

noexcept

Returns the number of registered type handlers.

See also: getHandler, registerTypeHandler

◆ registerStandardComponentTypes()

void juce::ComponentBuilder::registerStandardComponentTypes ( )

Registers handlers for various standard juce components.

◆ registerTypeHandler()

void juce::ComponentBuilder::registerTypeHandler ( TypeHandler * type )

Adds a type handler that the builder can use when trying to load components.

See also: Drawable::registerDrawableTypeHandlers()

◆ setImageProvider()

void juce::ComponentBuilder::setImageProvider ( ImageProvider * newImageProvider )

noexcept

Gives the builder an ImageProvider object that the type handlers can use when loading images from stored references.

The object that is passed in is not owned by the builder, so the caller must delete it when it is no longer needed, but not while the builder may still be using it. To clear the image provider, just call setImageProvider (nullptr).

◆ updateChildComponents()

void juce::ComponentBuilder::updateChildComponents	(	Component &	parent,
		const ValueTree &	children
	)

Updates the children of a parent component by updating them from the children of a given ValueTree.

◆ valueTreeChildAdded()

void juce::ComponentBuilder::valueTreeChildAdded	(	ValueTree &	parentTree,
		ValueTree &	childWhichHasBeenAdded
	)

overrideprivatevirtual

This method is called when a child sub-tree is added.

Note that when you register a listener to a tree, it will receive this callback for child changes in both that tree and any of its children, (recursively, at any depth). If your tree has sub-trees but you only want to know about changes to the top level tree, just check the parentTree parameter to make sure it's the one that you're interested in.

Reimplemented from juce::ValueTree::Listener.

◆ valueTreeChildOrderChanged()

void juce::ComponentBuilder::valueTreeChildOrderChanged	(	ValueTree &	parentTreeWhoseChildrenHaveMoved,
		int	oldIndex,
		int	newIndex
	)

overrideprivatevirtual

This method is called when a tree's children have been re-shuffled.

Note that when you register a listener to a tree, it will receive this callback for child changes in both that tree and any of its children, (recursively, at any depth). If your tree has sub-trees but you only want to know about changes to the top level tree, just check the parameter to make sure it's the tree that you're interested in.

Reimplemented from juce::ValueTree::Listener.

◆ valueTreeChildRemoved()

void juce::ComponentBuilder::valueTreeChildRemoved	(	ValueTree &	parentTree,
		ValueTree &	childWhichHasBeenRemoved,
		int	indexFromWhichChildWasRemoved
	)

overrideprivatevirtual

This method is called when a child sub-tree is removed.

Note that when you register a listener to a tree, it will receive this callback for child changes in both that tree and any of its children, (recursively, at any depth). If your tree has sub-trees but you only want to know about changes to the top level tree, just check the parentTree parameter to make sure it's the one that you're interested in.

Reimplemented from juce::ValueTree::Listener.

◆ valueTreeParentChanged()

void juce::ComponentBuilder::valueTreeParentChanged ( ValueTree & treeWhoseParentHasChanged )

overrideprivatevirtual

This method is called when a tree has been added or removed from a parent.

This callback happens when the tree to which the listener was registered is added or removed from a parent. Unlike the other callbacks, it applies only to the tree to which the listener is registered, and not to any of its children.

Reimplemented from juce::ValueTree::Listener.

◆ valueTreePropertyChanged()

void juce::ComponentBuilder::valueTreePropertyChanged	(	ValueTree &	treeWhosePropertyHasChanged,
		const Identifier &	property
	)

overrideprivatevirtual

This method is called when a property of this tree (or of one of its sub-trees) is changed.

Note that when you register a listener to a tree, it will receive this callback for property changes in that tree, and also for any of its children, (recursively, at any depth). If your tree has sub-trees but you only want to know about changes to the top level tree, simply check the tree parameter in this callback to make sure it's the tree you're interested in.

Reimplemented from juce::ValueTree::Listener.

◆ valueTreeRedirected()

virtual void juce::ValueTree::Listener::valueTreeRedirected ( ValueTree & treeWhichHasBeenChanged )

virtualinherited

This method is called when a tree is made to point to a different internal shared object.

When operator= is used to make a ValueTree refer to a different object, this callback will be made.

Reimplemented in juce::AudioProcessorValueTreeState.

Member Data Documentation

◆ component

std::unique_ptr<Component> juce::ComponentBuilder::component

private

◆ componentRef

WeakReference<Component> juce::ComponentBuilder::componentRef

private

◆ idProperty

const Identifier juce::ComponentBuilder::idProperty

static

An identifier for the property of the ValueTrees that is used to store a unique ID for that component.

◆ imageProvider

ImageProvider* juce::ComponentBuilder::imageProvider

private

◆ state

ValueTree juce::ComponentBuilder::state

This is the ValueTree data object that the builder is working with.

◆ types

OwnedArray<TypeHandler> juce::ComponentBuilder::types

private

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

juce_ComponentBuilder.h

Classes

Public Member Functions

Public Attributes

Static Public Attributes

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ComponentBuilder() [1/2]

◆ ComponentBuilder() [2/2]

◆ ~ComponentBuilder()

Member Function Documentation

◆ createComponent()

◆ getHandler()

◆ getHandlerForState()

◆ getImageProvider()

◆ getManagedComponent()

◆ getNumHandlers()

◆ registerStandardComponentTypes()

◆ registerTypeHandler()

◆ setImageProvider()

◆ updateChildComponents()

◆ valueTreeChildAdded()

◆ valueTreeChildOrderChanged()

◆ valueTreeChildRemoved()

◆ valueTreeParentChanged()

◆ valueTreePropertyChanged()

◆ valueTreeRedirected()

Member Data Documentation

◆ component

◆ componentRef

◆ idProperty

◆ imageProvider

◆ state

◆ types