jive_layouts

JIVE Layouts

• JIVE Layouts
  • The Interpreter
  • GUI Items
    • Properties
      • Common
      • Block Items
      • Buttons
      • Combo Boxes
      • Flex Containers
      • Flex Items
      • Grid Containers
      • Grid Items
      • Hyperlinks
      • Images
      • Progress Bars
      • Sliders
      • Spinners
      • Text
      • Windows

The jive_layouts module provides tools for creating GUIs by describing them using declarative markup in the form of juce::ValueTrees.

The Interpreter

The interpreter encapsulates the required logic to properly construct the required hierarchy of jive::GuiItems from a given juce::ValueTree.

The interpreter can be customised in a few ways:

• Custom Components - by adding entries to the interpreter's jive::ComponentFactory, it can be made to construct custom component types for a given juce::ValueTree type name.

• Custom GUI Items - the interpreter will decorate items wrapping juce::ValueTree elements of the specified type with the specified decorators.

• Aliases - when the interpreter encounters an element in the given juce::ValueTree with the name of one of its aliases, it will replace it with a replacement juce::ValueTree. This can be useful for reusing complex elements, for example:

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

GUI Items

The core of JIVE Layouts is the jive::GuiItem class which wraps a juce::Component and applies the required properties from the corresponding juce::ValueTree.

jive::GuiItem itself is a base class from which other classes should derive to implement more specific behaviour for a particular type of component. These derived types are applied using the Decorator Pattern meaning that they should not only derive from jive::GuiItem (or more specifically, jive::GuiItemDecorator) but should also hold a jive::GuiItem (which jive::GuiItemDecorator manages for you). This approach means that different behaviour can be added to a GUI item at runtime.

There are two main categories of GUI item:

• Container Items - implement a particular layout pattern such as Flex or Grid.
• Widget Items - implement the behaviour of a specific type of widget such as a button or slider.

There likely won't be much need to write custom jive::GuiItem derivatives, but if there is a need they should be implemented by the following rules:

• Prefer to derive from jive::GuiItemDecorator rather than jive::GuiItem itself.
• When overriding virtual methods from the base class, be sure to always call the same method on the base class so other decorators managing the same component can properly implement their behaviour.
• Don't rely on the order in which decorators are added.

Avoid constructing GUI items manually, always prefer to use the jive::Interpreter.

Properties

Changing the properties of the juce::ValueTree markup source will change the behaviour of the created components.

Properties can either be set directly on a juce::ValueTree using their stringified forms:

window.setProperty("display", "grid", nullptr);

Or by using a juce::VariantConverter specialisation, implemented by JIVE:

window.setProperty("cursor",
                   juce::VariantConverter<juce::MouseCursor::StandardCursorType>::toVar(juce::MouseCursor::PointingHandCursor),
                   nullptr);

However the best approach is to use a jive::Property, which is similar to juce::Value in that it represents a property on a juce::ValueTree except it's type safe, encapsulates the conversions to/from juce::var, and has a handy listener mechanism:

jive::Property<jive::Display> display{ window, "display" };
display.onValueChange = [](){
    // Do something when the "display" property is changed...
};

display = jive::Display::grid;

The tables below each property will tell you what C++ type to use with jive::Property for that property.

Where possible, property names and their accepted values should match their equivalents from CSS. This helps keep a consistent terminology across teams and may even let you copy-paste properties from tools like Figma.

Common

The following properties will apply to all GUI items.

Identifier	JUCE Property	CSS Property	Type
"always-on-top"	juce::Component::setAlwaysOnTop()	N/A	bool
"border-width"	N/A	"border-width"	juce::BorderSize<float>
"buffered-to-image"	juce::Component::setBufferedToImage()	N/A	bool
"clicking-grabs-focus"	juce::Component::setMouseClickGrabsKeyboardFocus()	"cursor"	juce::MouseCursor::StandardCursorType
"description"	juce::Component::setDescription()	N/A	juce::String
"display"	N/A	"display"	jive::Display
"enabled"	juce::Component::setEnabled()	N/A	bool
"focus-order"	juce::Component::setExplicitFocusOrder()	N/A	int
"focus-outline"	juce::Component::setHasFocusOutline()	N/A	bool
"focusable"	juce::Component::setWantsKeyboardFocus()	N/A	bool
"height"	juce::Component::setSize()	N/A	jive::Length
"id"	juce::Component::setComponentID()	N/A	juce::String
"margin"	N/A	"margin"	juce::BorderSize<float>
"min-height"	N/A	"min-height"	jive::Length
"min-width"	N/A	"min-width"	jive::Length
"name"	juce::Component::setName()	N/A	juce::String
"opacity"	juce::Component::setAlpha()	"opacity"	float
"opaque"	juce::Component::setOpaque()	N/A	bool
"padding"	N/A	"padding"	juce::BorderSize<float>
"title"	juce::Component::setTitle()	N/A	juce::String
"tooltip"	juce::Component::setHelpText()	N/A	juce::String
"transition"	N/A	transition	jive::Transitions
"visible"	juce::Component::setVisible()	"visibility"	bool
"width"	juce::Component::setSize()	N/A	jive::Length

Block Items

The following properties will only apply elements that are children of an element with a display type of block.

Identifier	JUCE Property	CSS Property	Type
"centre-x"	juce::Component::setBounds()	N/A	jive::Length
"centre-y"	juce::Component::setBounds()	N/A	jive::Length
"x"	juce::Component::setBounds()	N/A	jive::Length
"y"	juce::Component::setBounds()	N/A	jive::Length

Buttons

The following properties apply only to <Button> elements.

Identifier	JUCE Property	CSS Property	Type
"on-click"	N/A	N/A	jive::Event
"radio-group"	juce::Button::setRadioGroupId()	N/A	int
"toggle-on-click"	juce::Button::setClickingTogglesState()	N/A	bool
"toggleable"	juce::Button::setToggleable()	N/A	bool
"toggled"	juce::Button::setToggleState()	N/A	bool
"trigger-event"	juce::Button::setTriggeredOnMouseDown()	N/A	jive::Button::TriggerEvent

Combo Boxes

The following properties apply only to <ComboBox> elements.

Identifier	JUCE Property	CSS Property	Type
"editable"	juce::ComboBox::setEditableText()	N/A	bool
"on-change"	N/A	N/A	jive::Event
"selected"	juce::ComboBox::setSelectedItemIndex()	N/A	int

Flex Containers

The following properties will apply to any element with a display value of flex.

Identifier	JUCE Property	CSS Property	Type
"align-content"	juce::FlexBox::alignContent	"align-content"	juce::FlexBox::AlignContent
"align-items"	juce::FlexBox::alignItems	"align-items"	juce::FlexBox::AlignItems
"flex-direction"	juce::FlexBox::direction	"flex-direction"	juce::FlexBox::Direction
"flex-wrap"	juce::FlexBox::flexWrap	"flex-wrap"	juce::FlexBox::Wrap
"justify-content"	juce::FlexBox::justifyContent	"justify-content"	juce::FlexBox::JustifyContent

Flex Items

The following properties will only apply to the children of components with a display property of flex.

Identifier	JUCE Property	CSS Property	Type
"align-self"	juce::FlexItem::alignSelf	"align-self"	juce::FlexItem::AlignSelf
"flex-basis"	juce::FlexItem::flexBasis	"flex-basis"	float
"flex-grow"	juce::FlexItem::flexGrow	"flex-grow"	float
"flex-shrink"	juce::FlexItem::flexShrink	"flex-shrink"	float
"order"	juce::FlexItem::order	"order"	int

Grid Containers

The following properties will apply to any element with a display value of grid.

Identifier	JUCE Property	CSS Property	Type
"align-content"	juce::Grid::alignContent	"align-content"	juce::Grid::AlignContent
"align-items"	juce::Grid::alignItems	"align-items"	juce::Grid::AlignItems
"gap"	juce::Grid::columnGap, juce::Grid::rowGap	"gap"	juce::Grid::Px
"grid-auto-columns"	juce::Grid::autoColumns	"grid-auto-columns"	juce::Grid::TrackInfo
"grid-auto-flow"	juce::Grid::autoFlow	"grid-auto-flow"	juce::Grid::AutoFlow
"grid-auto-rows"	juce::Grid::autoRows	"grid-auto-rows"	juce::Grid::TrackInfo
"grid-template-areas"	juce::Grid::templateAreas	"grid-template-areas"	juce::StringArray
"grid-template-columns"	juce::Grid::templateColumns	"grid-template-columns"	juce::Array<juce::Grid::TrackInfo>
"grid-template-rows"	juce::Grid::templateRows	"grid-template-rows"	juce::Array<juce::Grid::TrackInfo>
"justify-content"	juce::Grid::justifyContent	"justify-content"	juce::Grid::JustifyContent
"justify-items"	juce::Grid::justifyItems	"justify-items"	juce::Grid::JustifyItems

Grid Items

The following properties will only apply to the children of components with a display property of flex.

Identifier	JUCE Property	CSS Property	Type
"align-self"	juce::GridItem::alignSelf	"align-self"	juce::GridItem::AlignSelf
"grid-area"	juce::GridItem::area	"grid-area"	juce::String
"grid-column"	juce::GridItem::column	"grid-column"	juce::GridItem::StartAndEndProperty
"grid-row"	juce::GridItem::row	"grid-row"	juce::GridItem::StartAndEndProperty
"justify-self"	juce::GridItem::justifySelf	"justify-self"	juce::GridItem::JustifySelf
"max-height"	juce::GridItem::maxHeight	"max-height"	float
"max-width"	juce::GridItem::maxWidth	"max-width"	float
"order"	juce::GridItem::order	"order"	int

Hyperlinks

The following properties apply only to <Hyperlink> elements.

Identifier	JUCE Property	CSS Property	Type
"url"	juce::HyperlinkButton::setURL()	N/A	juce::URL

Images

The following properties apply only to <Image> elements.

Identifier	JUCE Property	CSS Property	Type
"placement"	juce::ImageComponent::setImagePlacement()	N/A	juce::RectanglePlacement
"source"	N/A	N/A	jive::Drawable

Progress Bars

The following properties apply only to <ProgressBar> elements.

Identifier	JUCE Property	CSS Property	Type
"value"	N/A	N/A	double

Sliders

The following properties apply only to <Knob>, <Slider>, and <Spinner> elements.

Identifier	JUCE Property	CSS Property	Type
"interval"	juce::NormalisableRange<>::interval	N/A	juce::String
"max"	juce::NormalisableRange<>::end	N/A	juce::String
"mid"	juce::NormalisableRange<>::setSkewForCentre()	N/A	juce::String
"min"	juce::NormalisableRange<>::start	N/A	juce::String
"on-change"	N/A	N/A	jive::Event
"orientation"	juce::Slider::setSliderStyle()	N/A	jive::Orientation
"sensitivity"	juce::Slider::setMouseDragSensitivity()	N/A	double
"snap-to-mouse"	juce::Slider::setSliderSnapsToMousePosition()	N/A	bool
"velocity-mode"	juce::Slider::setVelocityBasedMode()	N/A	bool
"velocity-offset"	juce::Slider::setVelocityModeParameters()	N/A	double
"velocity-sensitivity"	juce::Slider::setVelocityModeParameters()	N/A	double
"velocity-threshold"	juce::Slider::setVelocityModeParameters()	N/A	int

Spinners

The following properties apply only to <Spinner> elements.

Identifier	JUCE Property	CSS Property	Type
"draggable"	juce::Slider::setIncDecButtonsMode()	N/A	bool

Text

The following properties apply only to <Text> elements.

Identifier	JUCE Property	CSS Property	Type
"direction"	juce::AttributedString::setReadingDirection()	"direction"	juce::AttributedString::ReadingDirection
"justification"	juce::AttributedString::setJustification()	N/A	juce::Justification
"line-spacing"	juce::AttributedString::setLineSpacing()	N/A	float
"text"	juce::AttributedString::setText()	N/A	juce::String
"word-wrap"	juce::AttributedString::setWordWrap()	"word-wrap"	juce::AttributedString::WordWrap

Windows

The following properties apply only to <Window> elements.

Identifier	JUCE Property	CSS Property	Type
"corner-resizer"	juce::ResizableWindow::setResizable()	N/A	bool
"draggable"	juce::ResizableWindow::setDraggable	N/A	bool
"full-screen"	juce::ResizableWindow::setFullScreen()	N/A	bool
"minimised"	juce::ResizableWindow::setMinimised()	N/A	bool
"native"	juce::TopLevelWindow::setUsingNativeTitleBar()	N/A	bool
"resizable"	juce::ResizableWindow::setResizable()	N/A	bool
"shadow"	juce::TopLevelWindow::setDropShadowEnabled()	N/A	bool
"title-bar-buttons"	juce::DocumentWindow::setTitleBarButtonsRequired()	N/A	juce::DocumentWindow::TitleBarButtons
"title-bar-height"	juce::DocumentWindow::setTitleBarHeight()	N/A	float