JIVE JUCE Modules

The jive_layouts module handles the hierarchy and layout of your GUI. Instead of writing imperative JUCE Component code to position elements, you describe the UI structure using a juce::ValueTree. This allows you to define what components exist (e.g., Windows, Components, Buttons, Text) and their properties (e.g., id, align-items, display) in a declarative way.

<Window width="640" height="400" align-items="centre">
    <Component id="header" align-items="centre">
        <Text id="title">Welcome to JIVE!</Text>
        <Text id="subtitle">The ultimate JUCE extension for building GUIs.</Text>
    </Component>

    <Component id="nav" display="grid" template-columns="1fr 1fr 1fr" template-rows="1fr">
        <Button>
            <Text>Home</Text>
        </Button>

        <Button>
            <Text>About</Text>
        </Button>

        <Button>
            <Text>Contact</Text>
        </Button>
    </Component>
</Window>

The core of JIVE Layouts is the jive::GuiItem class. It acts as a wrapper around a juce::Component and automatically applies properties defined in a corresponding juce::ValueTree.

Categories of GUI Items

• Container Items: Implement layout patterns like Flex or Grid.
• Widget Items: Implement specific widget behaviors (e.g., buttons, sliders).

Implementation Rules for Custom Items

If you need to create custom jive::GuiItem derivatives, follow these rules:

1. Use the Decorator Pattern: Prefer deriving from jive::GuiItemDecorator rather than jive::GuiItem directly. A decorator should both derive from the decorator base class and hold a jive::GuiItem.
2. Chain Virtual Method Calls: When overriding virtual methods, always call the same method on the base class to ensure other decorators in the chain can execute their logic.
3. Avoid Order Dependency: Do not rely on the specific order in which decorators are added.

Important: Avoid constructing GUI items manually; always use the jive::Interpreter to create them.

// Concept: Decorator Pattern for custom items
class MyCustomDecorator : public jive::GuiItemDecorator {
    // ... implementation
};

The Interpreter is the core engine that converts a juce::ValueTree hierarchy into a hierarchy of jive::GuiItem objects.

To customize how the interpreter behaves, you can use the following mechanisms:

1. Custom Components: Register new component types by adding entries to the interpreter's jive::ComponentFactory. This allows the interpreter to construct specific custom component types based on a juce::ValueTree type name.
2. Custom GUI Items: You can specify decorators that the interpreter will apply to items wrapping juce::ValueTree elements of a specific type.
3. Aliases: You can define aliases to reuse complex UI structures. When the interpreter encounters a juce::ValueTree element with an alias name, it replaces that element with a predefined replacement juce::ValueTree structure.

<!-- Example of an Alias expansion -->
<SearchGroup/>

<!-- expands to... -->

<Component id="search-group">
    <Text id="search-label" margin="0 0 5 0">Search:</Text>

    <Component display="flex" flex-direction="row">
        <TextBox id="search-box" flex-grow="1"></TextBox>
        <Button id="search-submit"><Text>Go</Text></Button>
    </Component>
</Component>

JIVE containers use a FlexBox layout by default with a column direction (top-to-bottom). You can control positioning and spacing by adding properties to the juce::ValueTree representing your container.

Common layout properties include:

• justify-content: Controls alignment on the main axis (e.g., centre).
• align-items: Controls alignment on the cross axis (e.g., centre).
• margin: Sets spacing around an item using CSS-style syntax: "top right bottom left" (e.g., "0 0 20 0").
• padding: Sets internal spacing around an item (e.g., "7 20").

juce::ValueTree topLevel(const juce::String &greeting) {
    return juce::ValueTree{
        "Window",
        {
            { "justify-content", "centre" }, // Centre on the main-axis (vertically)
            { "align-items", "centre" },     // Centre on the cross-axis (horizontally)
        },
        // ...
    };
}

While JIVE can use pure juce::ValueTree objects to define a UI, jive::View allows you to attach additional behavior to a view without losing control or needing to manually pass pointers/references.

To create a custom view, inherit from jive::View and override the initialise() method to return the juce::ValueTree that defines the view's initial state. You can then use jive::makeView<T>() to convert your custom view type into a juce::ValueTree that the jive::Interpreter can process.

class MyView : public jive::View
{
protected:
    juce::ValueTree initialise() final
    {
        return juce::ValueTree{
            "Component",
            {
                { "width", 300 },
                { "height", 200 },
            },
        };
    }
};

// Construct a ValueTree from our custom View type
const juce::ValueTree view = jive::makeView<MyView>();

jive::Interpreter interpreter;
const auto guiItem = interpreter.interpret(view);