Loading...
Searching...
No Matches
juce::ComponentBuilder Class Reference

## 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.

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

- juce_gui_basics/layout/juce_ComponentBuilder.h

Inheritance diagram for juce::ComponentBuilder:

## Classes

class | TypeHandler
| The class is a base class for objects that manage the loading of a type of component from a ValueTree. More...
class | ImageProvider
| This class is used when references to images need to be stored in ValueTrees. More...

## Public Member Functions

| ComponentBuilder (const ValueTree &state)
| Creates a ComponentBuilder that will use the given state.
| ComponentBuilder ()
| Creates a builder that doesn't have a state object.
| ~ComponentBuilder () override
| Destructor.
Component * | getManagedComponent ()
| Returns the builder's component (creating it if necessary).
Component * | createComponent ()
| Creates and returns a new instance of the component that the ValueTree represents.
void | registerTypeHandler (TypeHandler *type)
| Adds a type handler that the builder can use when trying to load components.
TypeHandler * | getHandlerForState (const ValueTree &state) const
| Tries to find a registered type handler that can load a component from the given ValueTree.
int | getNumHandlers () const noexcept
| Returns the number of registered type handlers.
TypeHandler * | getHandler (int index) const noexcept
| Returns one of the registered type handlers.
void | registerStandardComponentTypes ()
| Registers handlers for various standard juce components.
void | setImageProvider (ImageProvider *newImageProvider) noexcept
| Gives the builder an ImageProvider object that the type handlers can use when loading images from stored references.
ImageProvider * | getImageProvider () const noexcept
| Returns the current image provider that this builder is using, or nullptr if none has been set.
void | updateChildComponents (Component &parent, const ValueTree &children)
| Updates the children of a parent component by updating them from the children of a given ValueTree.

## Public Attributes

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

## 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.

## Constructors and Destructors

## 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.

References state.

## ComponentBuilder() [2/2]

juce::ComponentBuilder::ComponentBuilder | ( |  | ) |

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

## ~ComponentBuilder()

juce::ComponentBuilder::~ComponentBuilder | ( |  | ) |

override

Destructor.

## Member Functions

## 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.

## 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.

## 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()

References registerTypeHandler().

Referenced by 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.

References getHandlerForState(), and state.

Referenced by getHandlerForState().

## getNumHandlers()

int juce::ComponentBuilder::getNumHandlers | ( |  | ) | const

noexcept

Returns the number of registered type handlers.

See also
  getHandler, registerTypeHandler

References getNumHandlers().

Referenced by getNumHandlers().

## getHandler()

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

noexcept

Returns one of the registered type handlers.

See also
  getNumHandlers, registerTypeHandler

References getHandler().

Referenced by getHandler().

## registerStandardComponentTypes()

void juce::ComponentBuilder::registerStandardComponentTypes | ( |  | ) |

Registers handlers for various standard juce components.

References registerStandardComponentTypes().

Referenced by registerStandardComponentTypes().

## 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).

## getImageProvider()

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

noexcept

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

## 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.

References updateChildComponents().

Referenced by updateChildComponents().

## Member Data Documentation

## state

ValueTree juce::ComponentBuilder::state

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

Referenced by juce::ComponentBuilder::TypeHandler::addNewComponentFromState(), ComponentBuilder(), getHandlerForState(), and juce::ComponentBuilder::TypeHandler::updateComponentFromState().

## 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.

### Purchase

Get JUCE

### Discover

What's New in JUCE Features

### Learn

Documentaion Tutorials Made with JUCE Resources

### Support

JUCE Forum Newsletter Archive

### About

Contact Us JUCE Legal JUCE Licensing FAQ

### Events

Audio Developer Conference
© Raw Material Software Limited