LayoutSupport Class Reference

JSON-based layout system for JUCE components. More...

#include <gin_layoutsupport.h>

Inherits gin::FileSystemWatcher::Listener.

Classes
struct	Bounds
struct	JsonFile

Public Member Functions
	LayoutSupport (juce::Component &parent_, std::function< std::pair< juce::Component *, bool >(const juce::String &)> factory_=nullptr)
	Construct a LayoutSupport instance for the given parent component.
	~LayoutSupport () override
bool	isLayoutSet ()
	Returns true if a layout has been set.
void	setLayout (const juce::Array< juce::File > &files)
	Load layout from JSON files.
void	setLayout (const juce::StringArray &resourceNames)
	Load layout from binary resources (BinaryData).
void	setLayout (const juce::String &rawJson)
	Load layout from raw JSON string.
void	setConstant (const juce::String &name, int value)
	Set or update a constant value.

Static Public Member Functions
static void	dumpComponents (juce::Component &c)
	Generate JSON layout from existing component hierarchy.

Public Attributes
std::function< void()>	layoutChanged
	Callback invoked when layout is loaded or reloaded.

Protected Member Functions
juce::String	findContent (const juce::String &name)
juce::Component *	getComp (const juce::String &cid)
void	setLayoutInternal (const juce::Array< JsonFile > &files)
int	parse (const juce::var &equation, int equationIndex)
void	setComponentsLayout (const juce::String &currentPath, const juce::var &components)
void	loadConstants (juce::var &j)
void	loadMacros (juce::var &j)
Bounds	getBounds (int idIdx, const juce::var &component)
juce::Component *	setPosition (const juce::String &currentPath, const juce::String &id, int idIdx, const juce::var &component)
juce::var	expandMacro (const juce::var &component)
void	setGridPositions (const juce::String &currentPath, const juce::var &component)
void	fileChanged (const juce::File &, gin::FileSystemWatcher::FileSystemEvent) override

Protected Attributes
juce::Component &	parent
ConstantsStack	constants
std::map< juce::String, juce::var >	macros
juce::Array< juce::File >	layoutFiles
bool	layoutSet = false
juce::Component *	curComponent = nullptr
juce::OwnedArray< juce::Component >	createdComponents
ComponentMap	compMap
std::function< std::pair< juce::Component *, bool >(const juce::String &)>	componentFactory

Static Protected Attributes
static int	refCount = 0
static std::unique_ptr< FileSystemWatcher >	watcher

Detailed Description

JSON-based layout system for JUCE components.

Allows declarative component positioning with expressions, constants, macros, and live reloading.

Usage Example

class MyComponent : public juce::Component
{
public:
    MyComponent() : layoutSupport (*this)
    {
        addAndMakeVisible (button);
        button.setComponentID ("myButton");
        layoutSupport.setLayout ({ juce::File ("layout.json") });
    }
private:
    LayoutSupport layoutSupport;
    juce::TextButton button;
};

JSON Format

Top-level properties:

• w, h - Set parent component size
• constants - Define reusable constant values
• macros - Define reusable component templates
• components - Array of component definitions

Component Properties

Identification:**

• id - Component identifier (supports comma-separated list or range syntax like "button[0..9]")
• factory - Factory name to create component on demand
• optional - Boolean, won't assert if component not found

• if - Conditional expression to include/exclude component

  Position (absolute):**

• x, y - Absolute position
• xy - Comma-separated "x,y"
• r, b - Right/bottom edges

• cx, cy - Center position (requires size)

  Position (relative):**

• xd - Horizontal delta from previous (or "delta,refID" for specific component)
• yd - Vertical delta from previous (or "delta,refID")

• cxd, cyd - Center delta from previous

  Position (special):**

• bounds - "parent", "prev", "reduced,N", "reduced,H,V", "reduced,L,T,R,B", or "x,y,w,h"
• inset - Component ID to inset from

• border - Border amount for inset (default 0)

  Size:**

• w, h - Width and height

• size - Reference to size constant (e.g., "buttonSize" references constants.buttonSize.w/h)

  Display:**

• visible - Boolean or expression

• zorder - Z-order index

  Accessibility:**

• title - Accessibility title

• tip - Tooltip text

  Focus:**

• order - Component focus order

• parentOrder - Parent component focus order

  Custom:**

• properties - Object with custom properties to set on component
• constants - Local constants scoped to this component
• macro - Macro name with parameters

• components - Nested child components

  Grid Layout:**

• grid - Component IDs for grid (supports range syntax)
• cols, rows - Grid dimensions (default 1)
• colGap, rowGap - Grid spacing (default 0)

Constants

Built-in constants:

• mac, win, linux - Platform flags (1.0 or 0.0)
• parX, parY, parW, parH, parR, parB - Parent bounds
• prevX, prevY, prevW, prevH, prevR, prevB, prevCX, prevCY - Previous component
• i - Current child index
• idIdx - Current iteration index (when using multiple IDs or ranges)

Custom constants can be defined at top-level or per-component:

{
  "constants": [
    { "margin": 10 },
    { "buttonSize": { "w": 100, "h", 25 } }
  ],
  "components": [
    { "id": "button", "x": "margin", "w": 100, "h": 30 }
  ]
}

Expressions

All numeric properties support mathematical expressions:

• Operators: +, -, *, /, %, (, )
• Constants: Any defined constant name
• Functions: getX(id), getY(id), getW(id), getH(id), getR(id), getB(id), getCX(id), getCY(id)

Example: ‘"x": "parW / 2 - getW('button’) / 2"`

Macros

Reusable component templates with parameters:

{
  "macros": [
    { "id": "standardButton", "w": 100, "h": 30, "tip": "P1" }
  ],
  "components": [
    { "id": "saveBtn", "macro": "standardButton('Save')", "x": 10, "y": 10 }
  ]
}

Parameters are referenced as P1, P2, P3, etc.

Examples

Simple layout:

{
  "components": [
    { "id": "header", "bounds": "parent" },
    { "id": "button", "x": 10, "y": 10, "w": 100, "h": 30 }
  ]
}

Relative positioning:

{
  "components": [
    { "id": "button1", "x": 10, "y": 10, "w": 100, "h": 30 },
    { "id": "button2", "xd": 10, "y": 10 },
    { "id": "button3", "xd": 10, "y": 10 }
  ]
}

Grid layout:

{
  "grid": "cell[0..8]",
  "bounds": "10,10,300,300",
  "cols": 3,
  "rows": 3,
  "colGap": 5,
  "rowGap": 5
}

Range syntax and expressions:

{
  "id": "knob[0..7]",
  "x": "10 + i * 50",
  "y": 10,
  "w": 40,
  "h": 40
}

Constructor & Destructor Documentation

LayoutSupport()

LayoutSupport::LayoutSupport	(	juce::Component &	parent_,
		std::function< std::pair< juce::Component *, bool >(const juce::String &)>	factory_ = nullptr
	)

Construct a LayoutSupport instance for the given parent component.

Parameters

parent_	The parent component whose children will be positioned
factory_	Optional factory function to create components on demand. Function signature: (factoryName) -> (Component*, sendToBack) Return nullptr if factory name not recognized.

~LayoutSupport()

LayoutSupport::~LayoutSupport ( )

override

Member Function Documentation

dumpComponents()

static void LayoutSupport::dumpComponents ( juce::Component &  c )

static

Generate JSON layout from existing component hierarchy.

Outputs JSON to debug console and copies to clipboard. Useful for migrating existing layouts to JSON format.

Parameters

c	Root component to dump

isLayoutSet()

bool LayoutSupport::isLayoutSet

(

)

Returns true if a layout has been set.

setLayout() [1/3]

void LayoutSupport::setLayout

(

const juce::Array< juce::File > &

files

)

Load layout from JSON files.

Watches files for changes and auto-reloads.

Parameters

files

Array of JSON files to load

setLayout() [2/3]

void LayoutSupport::setLayout

(

const juce::StringArray &

resourceNames

)

Load layout from binary resources (BinaryData).

Parameters

resourceNames

Array of resource names to load

setLayout() [3/3]

void LayoutSupport::setLayout

(

const juce::String &

rawJson

)

Load layout from raw JSON string.

Parameters

rawJson

JSON string containing layout definition

setConstant()

void LayoutSupport::setConstant	(	const juce::String &	name,
		int	value
	)

Set or update a constant value.

Parameters

name	Constant name
value	Constant value

findContent()

juce::String LayoutSupport::findContent ( const juce::String &  name )

protected

getComp()

juce::Component * LayoutSupport::getComp ( const juce::String &  cid )

protected

setLayoutInternal()

void LayoutSupport::setLayoutInternal ( const juce::Array< JsonFile > &  files )

protected

parse()

int LayoutSupport::parse ( const juce::var &  equation, int  equationIndex  )

protected

setComponentsLayout()

void LayoutSupport::setComponentsLayout ( const juce::String &  currentPath, const juce::var &  components  )

protected

loadConstants()

void LayoutSupport::loadConstants ( juce::var &  j )

protected

loadMacros()

void LayoutSupport::loadMacros ( juce::var &  j )

protected

getBounds()

Bounds LayoutSupport::getBounds ( int  idIdx, const juce::var &  component  )

protected

setPosition()

juce::Component * LayoutSupport::setPosition ( const juce::String &  currentPath, const juce::String &  id, int  idIdx, const juce::var &  component  )

protected

expandMacro()

juce::var LayoutSupport::expandMacro ( const juce::var &  component )

protected

setGridPositions()

void LayoutSupport::setGridPositions ( const juce::String &  currentPath, const juce::var &  component  )

protected

fileChanged()

void LayoutSupport::fileChanged ( const juce::File &  , gin::FileSystemWatcher::FileSystemEvent    )

overrideprotected

Member Data Documentation

layoutChanged

std::function<void()> LayoutSupport::layoutChanged

Callback invoked when layout is loaded or reloaded.

parent

juce::Component& LayoutSupport::parent

protected

refCount

int LayoutSupport::refCount = 0

staticprotected

watcher

std::unique_ptr<FileSystemWatcher> LayoutSupport::watcher

staticprotected

constants

ConstantsStack LayoutSupport::constants

protected

macros

std::map<juce::String, juce::var> LayoutSupport::macros

protected

layoutFiles

juce::Array<juce::File> LayoutSupport::layoutFiles

protected

layoutSet

bool LayoutSupport::layoutSet = false

protected

curComponent

juce::Component* LayoutSupport::curComponent = nullptr

protected

createdComponents

juce::OwnedArray<juce::Component> LayoutSupport::createdComponents

protected

compMap

ComponentMap LayoutSupport::compMap

protected

componentFactory

std::function<std::pair<juce::Component*, bool>(const juce::String&)> LayoutSupport::componentFactory

protected

---

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

• gin_layoutsupport.h