utilities

Files
file	gin_varianthelpers.h
	Utility functions for working with JUCE var objects and their properties.

Namespaces
namespace	macOS
	macOS-specific image conversion utilities.
namespace	juce

Classes
class	Transition
	Duration and easing of an animated change, CSS transition style. More...
struct	Interpolator< T >
	How Animated blends and compares values of a type. More...
struct	Interpolator< float >
	Floats cover any scalar, a font height or a corner radius alike. More...
struct	Interpolator< juce::Colour >
struct	Interpolator< juce::Rectangle< float > >
	Blends the edges, so a rectangle moving and resizing keeps its edges steady. More...
struct	Interpolator< juce::Rectangle< int > >
struct	Interpolator< juce::Font >
	Blends the height; the other attributes are the target's. More...
struct	Interpolator< juce::ColourGradient >
	Resamples both gradients onto the union of their stop positions and blends the colours there, and the end points. More...
class	AnimationDriver
	Ticks all running Animated and Crossfade values on the vertical blank of the window they show in. More...
class	AnimatedBase
	The non-template part of Animated and Crossfade: the owner, the property name, the running transition and the registration with the shared AnimationDriver. More...
class	Animated< T >
	A value that eases to a new target over a Transition and repaints its owner on every step. More...
class	AnimatedScale
	An Animated<float> scale applied to its owner with juce::Component::setTransform, about an origin relative to the owner's bounds (its centre by default), so it zooms from the centre instead of towards the bottom right. More...
class	Crossfade< T >
	A discrete value that can't blend, like a text or an icon: on a change the previous value fades out while the new one fades in, over a Transition found exactly like Animated's (layout "transition" by property name, preset, inline spec). More...
class	ImageFilter
	A chain of image filters (as CSS filter), applied in order with Gin's applyX functions, parsed from a spec string of names, each followed by its value where it takes one. More...
class	AnimatedImageFilter
	An image and an ImageFilter version of it, blended by an Animated<float> amount: 0 shows the image, 1 the filtered one, e.g. More...
class	LambdaTimer
	Timer that calls a std::function callback instead of requiring virtual override. More...
class	LambdaAsyncUpdater
	Async updater that calls a std::function callback instead of requiring virtual override. More...
class	LambdaMouseListener
	Mouse listener that uses std::function callbacks instead of virtual overrides. More...
class	CoalescedTimer
	An efficient timer that shares a single juce::Timer between multiple instances. More...
class	ComponentMap
	Internal class for mapping component paths to component pointers. More...
class	ElevatedFileCopy
	Copies files, creating folders where required requesting admin access only if required. More...
class	ElevatedSession
	Keeps one elevated worker process alive so the admin password prompt is only shown once per app run, rather than once per operation. More...
class	ConstantsStack
class	ConstantsStack::ScopedSave
class	Parser
class	LayoutSupport
	JSON-based layout system for JUCE components. More...
struct	LayoutSupport::Bounds
struct	LayoutSupport::JsonFile
class	OpenStreetMaps
	Fetches map files from OSM servers. More...
class	OpenStreetMaps::Listener
struct	ShadowSpec
	One layer of a CSS-style box shadow: an offset, a blur radius, a spread and a colour (its alpha the shadow's opacity). More...
struct	Interpolator< ShadowList >
	Blends layer by layer; a missing layer blends from or to a clear copy of the other one. More...
class	BoxShadow
	CSS-style box shadows, painted by the PARENT under its children, because a shadow lies outside the component and would be clipped by it. More...
class	AnimatedProperties
	The animated values of one component that the layout and its States share, so a base value (the layout's "alpha" and "scale" entries) and a state's value (e.g. More...
class	States
	Declarative states, like CSS pseudo-classes: values a component takes while the mouse is over it or presses it, eased there and back with its transitions. More...
class	SystemClipboard
	Utilities for reading and writing images to the system clipboard. More...
class	AsyncDownload
	Async Download. More...
struct	Property
	Simple key-value pair structure for representing a property. More...
struct	juce::VarIterator
	Iterator for a var. More...
struct	juce::VarIterator::NamedValue

Typedefs
using	ShadowList = std::vector<ShadowSpec>
	A box shadow's layers, painted in order.
using	juce::VarIterator::difference_type = std::ptrdiff_t
using	juce::VarIterator::value_type = NamedValue
using	juce::VarIterator::reference = NamedValue&
using	juce::VarIterator::pointer = NamedValue*
using	juce::VarIterator::iterator_category = std::forward_iterator_tag

Functions
std::optional< juce::Point< float > >	parseTransformOrigin (const juce::String &origin)
	Parses a CSS transform-origin style string into a point relative to a component's bounds, (0, 0) its top left, (1, 1) its bottom right:
juce::AffineTransform	scaleTransform (juce::Rectangle< int > bounds, float s, juce::Point< float > origin={ 0.5f, 0.5f })
	The transform that scales a component by s about a point relative to its bounds (see parseTransformOrigin), in its parent's coordinates as juce::Component::setTransform takes it.
void	callOnMainThreadBlocking (std::function< void()> func)
juce::Colour	goldenRatioColor (int idx)
	Returns the next colour in a set where the hues differ by the golden ratio.
void	asyncDownload (const juce::URL &, std::function< void(const juce::String &)>)
void	asyncDownload (const juce::URL &, std::function< void(const juce::MemoryBlock &)>)
juce::Image	createDesktopSnapshot ()
juce::Image	createSnapshotOfNativeWindow (juce::Component &c)
juce::var	jsonObject ()
	Creates an empty JSON object (DynamicObject wrapped in a var).
std::string	toStdString (const juce::var &v)
	Convert a var to a std::string.
	Property::Property ()=default
	Property::Property (const juce::String &k, const juce::var v)
	Construct a Property with a key and value.
juce::var	getPropertyWithDefault (const juce::var &v, const juce::Identifier &i, const juce::var &defaultValue)
	Get a property value with a default fallback.
void	setProperty (juce::var &v, const juce::Identifier &i, const juce::var &value)
	Set a property on a var object.
void	removeProperty (juce::var &v, const juce::Identifier &i)
	Remove a property from a var object.
bool	setJSONPointer (juce::var &v, juce::String pointer, const juce::var &newValue)
	Given a JSON array/object 'v', a string representing a JSON pointer, and a new property value 'newValue', updates 'v' where the property or array index referenced by the pointer has been set to 'newValue'.
juce::var	getJSONPointer (const juce::var &v, juce::String pointer, const juce::var &defaultValue)
	Given a JSON array/object 'v', a string representing a JSON pointer, returns the value of the property or array index referenced by the pointer If the pointer cannot be followed, due to referencing missing array indices or fields, then this returns defaultValue.
bool	hasJSONPointer (const juce::var &v, juce::String pointer)
	Check if a JSON Pointer path exists in a var.
juce::String	removeJsonComments (const juce::String &input)
	Remove C-style and C++-style comments from a JSON string.
	juce::VarIterator::VarIterator (const juce::var &, bool isEnd)
VarIterator &	juce::VarIterator::operator++ ()
bool	juce::VarIterator::operator== (const VarIterator &) const
bool	juce::VarIterator::operator!= (const VarIterator &) const
NamedValue	juce::VarIterator::operator* () const
VarIterator	juce::begin (const juce::var &)
VarIterator	juce::end (const juce::var &)

Variables
juce::String	Property::key
	Property name/key.
juce::var	Property::value
	Property value.
juce::var	juce::VarIterator::NamedValue::name
juce::var	juce::VarIterator::NamedValue::value

Paint helpers
They take plain values, so Animated<T> members pass straight in through their implicit conversion; the Crossfade overloads draw both sides of a fade. class Card : public juce::Component { public: void paint (juce::Graphics& g) override { auto rc = getLocalBounds().toFloat(); gin::fillGradient (g, rc, 12.0f, fill); gin::drawIcon (g, icon, rc.removeFromLeft (rc.getHeight()).reduced (8.0f), ink); gin::drawText (g, title, rc, juce::Font (juce::FontOptions (20.0f)), ink, juce::Justification::centredLeft); } gin::Animated<juce::ColourGradient> fill { *this, "fill" }; // relative points, see fillGradient gin::Animated<juce::Colour> ink { *this, "ink", juce::Colours::white }; gin::Crossfade<juce::Path> icon { *this, "icon" }; // relative paths, see drawIcon gin::Crossfade<juce::String> title { *this, "title" }; };
void	fillGradient (juce::Graphics &g, juce::Rectangle< float > area, float cornerRadius, const juce::ColourGradient &relativeGradient)
	Fills a rectangle, rounded when cornerRadius > 0, with a gradient whose points are relative to it: (0, 0) is its top left, (1, 1) its bottom right.
void	drawText (juce::Graphics &g, const Crossfade< juce::String > &text, juce::Rectangle< float > area, const juce::Font &font, juce::Colour colour, juce::Justification justification)
	Draws a Crossfade<juce::String> with juce::Graphics::drawText (ellipsis on overflow): the previous text at the colour's alpha times 1 - progress, the current one times progress.
void	drawIcon (juce::Graphics &g, const juce::Path &relativePath, juce::Rectangle< float > area, juce::Colour colour)
	Fills a path whose coordinates are relative: (0, 0)..(1, 1) maps onto the largest square centred in the area.
void	drawIcon (juce::Graphics &g, const Crossfade< juce::Path > &icon, juce::Rectangle< float > area, juce::Colour colour)
	Draws a Crossfade<juce::Path> of relative paths (see the other drawIcon), the previous icon fading out as the current one fades in.
void	drawImage (juce::Graphics &g, const Crossfade< MipMap > &image, juce::Rectangle< float > area, juce::RectanglePlacement placement=0)
	Draws a Crossfade<MipMap> with drawBlend: the previous image at full opacity, the current one on top at the fade's progress, so an opaque image never shows through to the background mid-fade.

Detailed Description

Typedef Documentation

ShadowList

using ShadowList = std::vector<ShadowSpec>

A box shadow's layers, painted in order.

difference_type

using juce::VarIterator::difference_type = std::ptrdiff_t

value_type

using juce::VarIterator::value_type = NamedValue

reference

using juce::VarIterator::reference = NamedValue&

pointer

using juce::VarIterator::pointer = NamedValue*

iterator_category

using juce::VarIterator::iterator_category = std::forward_iterator_tag

Function Documentation

parseTransformOrigin()

std::optional< juce::Point< float > > parseTransformOrigin

(

const juce::String &

origin

)

Parses a CSS transform-origin style string into a point relative to a component's bounds, (0, 0) its top left, (1, 1) its bottom right:

• keywords "center" (or "centre"), "left", "right", "top", "bottom", one or two in any order: "top left", "right", "bottom" (the other axis centred)
• numbers as fractions or percentages, x then y: "0.5 0", "25% 100%"; a single number applies to both axes

  Returns

  std::nullopt for anything else

scaleTransform()

juce::AffineTransform scaleTransform	(	juce::Rectangle< int >	bounds,
		float	s,
		juce::Point< float >	origin = { 0.5f, 0.5f } )

The transform that scales a component by s about a point relative to its bounds (see parseTransformOrigin), in its parent's coordinates as juce::Component::setTransform takes it.

Identity for s == 1.

fillGradient()

void fillGradient	(	juce::Graphics &	g,
		juce::Rectangle< float >	area,
		float	cornerRadius,
		const juce::ColourGradient &	relativeGradient )

Fills a rectangle, rounded when cornerRadius > 0, with a gradient whose points are relative to it: (0, 0) is its top left, (1, 1) its bottom right.

Relative points keep an Animated<juce::ColourGradient> independent of the component's size. A gradient without colours draws nothing.

drawText()

void drawText	(	juce::Graphics &	g,
		const Crossfade< juce::String > &	text,
		juce::Rectangle< float >	area,
		const juce::Font &	font,
		juce::Colour	colour,
		juce::Justification	justification )

Draws a Crossfade<juce::String> with juce::Graphics::drawText (ellipsis on overflow): the previous text at the colour's alpha times 1 - progress, the current one times progress.

Empty texts are skipped.

drawIcon() [1/2]

void drawIcon	(	juce::Graphics &	g,
		const juce::Path &	relativePath,
		juce::Rectangle< float >	area,
		juce::Colour	colour )

Fills a path whose coordinates are relative: (0, 0)..(1, 1) maps onto the largest square centred in the area.

Make a relative path from an SVG or a Drawable by fitting it into the rectangle 0, 0, 1, 1 once.

drawIcon() [2/2]

void drawIcon	(	juce::Graphics &	g,
		const Crossfade< juce::Path > &	icon,
		juce::Rectangle< float >	area,
		juce::Colour	colour )

Draws a Crossfade<juce::Path> of relative paths (see the other drawIcon), the previous icon fading out as the current one fades in.

drawImage()

void drawImage	(	juce::Graphics &	g,
		const Crossfade< MipMap > &	image,
		juce::Rectangle< float >	area,
		juce::RectanglePlacement	placement = 0 )

Draws a Crossfade<MipMap> with drawBlend: the previous image at full opacity, the current one on top at the fade's progress, so an opaque image never shows through to the background mid-fade.

callOnMainThreadBlocking()

void callOnMainThreadBlocking

(

std::function< void()>

func

)

goldenRatioColor()

juce::Colour goldenRatioColor

(

int

idx

)

Returns the next colour in a set where the hues differ by the golden ratio.

Good for coming up with a random set of colours

asyncDownload() [1/2]

void asyncDownload	(	const juce::URL &	,
		std::function< void(const juce::String &)>	)

asyncDownload() [2/2]

void asyncDownload	(	const juce::URL &	,
		std::function< void(const juce::MemoryBlock &)>	)

createDesktopSnapshot()

juce::Image createDesktopSnapshot

(

)

createSnapshotOfNativeWindow()

juce::Image createSnapshotOfNativeWindow

(

juce::Component &

c

)

jsonObject()

juce::var jsonObject

(

)

Creates an empty JSON object (DynamicObject wrapped in a var).

This is a convenience function that's cleaner than writing juce::var (new juce::DynamicObject()) repeatedly.

Returns

A new empty var containing a DynamicObject

auto config = jsonObject();
setProperty (config, "width", 800);
setProperty (config, "height", 600);

toStdString()

std::string toStdString

(

const juce::var &

v

)

Convert a var to a std::string.

This is a convenience function equivalent to v.toString().toStdString().

Parameters

v	The var to convert

Returns

The var's string representation as a std::string

juce::var name = "John";
std::string stdName = toStdString (name);  // "John"
 
juce::var num = 42;
std::string stdNum = toStdString (num);    // "42"

Property() [1/2]

Property::Property ( )

default

Property() [2/2]

Property::Property	(	const juce::String &	k,
		const juce::var	v )

Construct a Property with a key and value.

Parameters

k	Property key/name
v	Property value

References key, and value.

getPropertyWithDefault()

juce::var getPropertyWithDefault	(	const juce::var &	v,
		const juce::Identifier &	i,
		const juce::var &	defaultValue )

Get a property value with a default fallback.

Returns the property value if it exists, otherwise returns the default value. This is a safer alternative to direct property access when the property might not exist.

Parameters

v	The var object to get the property from
i	Property name identifier
defaultValue	Value to return if property doesn't exist

Returns

Property value if it exists, otherwise defaultValue

auto obj = jsonObject();
setProperty (obj, "width", 100);
 
auto w = getPropertyWithDefault (obj, "width", 50);   // Returns 100
auto h = getPropertyWithDefault (obj, "height", 50);  // Returns 50 (default)

setProperty()

void setProperty	(	juce::var &	v,
		const juce::Identifier &	i,
		const juce::var &	value )

Set a property on a var object.

If the var contains a DynamicObject, sets the property on it. If the var is not a DynamicObject, this function does nothing.

Parameters

v	The var object to set the property on (passed by reference)
i	Property name identifier
value	Value to set for the property

auto obj = jsonObject();
setProperty (obj, "width", 100);
setProperty (obj, "height", 200);
// obj now has properties: width=100, height=200

removeProperty()

void removeProperty	(	juce::var &	v,
		const juce::Identifier &	i )

Remove a property from a var object.

If the var contains a DynamicObject, removes the specified property from it. If the var is not a DynamicObject, this function does nothing.

Parameters

v	The var object to remove the property from (passed by reference)
i	Property name identifier to remove

auto obj = jsonObject();
setProperty (obj, "width", 100);
setProperty (obj, "height", 200);
 
removeProperty (obj, "width");
// obj now only has height property

setJSONPointer()

bool setJSONPointer	(	juce::var &	v,
		juce::String	pointer,
		const juce::var &	newValue )

Given a JSON array/object 'v', a string representing a JSON pointer, and a new property value 'newValue', updates 'v' where the property or array index referenced by the pointer has been set to 'newValue'.

If intermediate objects in the path don't exist, they will be automatically created as empty DynamicObjects. However, intermediate arrays are NOT automatically created - the array must already exist.

If the pointer cannot be followed due to referencing missing array indices, this returns false.

Parameters

v	The var object to modify (passed by reference)
pointer	JSON Pointer string (e.g., "/user/name")
newValue	The value to set at the pointer location

Returns

true if successful, false if pointer path is invalid

juce::var obj = jsonObject();
 
// Simple property
setJSONPointer (obj, "/name", "John");
 
// Nested - automatically creates "user" object if it doesn't exist
setJSONPointer (obj, "/user/age", 30);
setJSONPointer (obj, "/user/address/city", "London");  // Creates address too

For more details, check the JSON Pointer RFC 6901: https://datatracker.ietf.org/doc/html/rfc6901

getJSONPointer()

juce::var getJSONPointer	(	const juce::var &	v,
		juce::String	pointer,
		const juce::var &	defaultValue )

Given a JSON array/object 'v', a string representing a JSON pointer, returns the value of the property or array index referenced by the pointer If the pointer cannot be followed, due to referencing missing array indices or fields, then this returns defaultValue.

For more details, check the JSON Pointer RFC 6901: https://datatracker.ietf.org/doc/html/rfc6901

hasJSONPointer()

bool hasJSONPointer	(	const juce::var &	v,
		juce::String	pointer )

Check if a JSON Pointer path exists in a var.

Given a JSON array/object 'v' and a JSON pointer string, returns true if the property or array index referenced by the pointer exists.

This is useful for checking existence before calling getJSONPointer to distinguish between "property doesn't exist" and "property exists but is null/void".

Parameters

v	The var object to check
pointer	JSON Pointer string (e.g., "/user/name")

Returns

true if the pointer path exists, false otherwise

auto obj = jsonObject();
setProperty (obj, "width", 100);
 
hasJSONPointer (obj, "/width");   // true
hasJSONPointer (obj, "/height");  // false
 
// Check nested paths
setJSONPointer (obj, "/user/name", "John");
hasJSONPointer (obj, "/user/name");  // true
hasJSONPointer (obj, "/user/age");   // false

For more details, check the JSON Pointer RFC 6901: https://datatracker.ietf.org/doc/html/rfc6901

removeJsonComments()

juce::String removeJsonComments

(

const juce::String &

input

)

Remove C-style and C++-style comments from a JSON string.

This function strips both line comments and block comments from JSON text, allowing you to use commented JSON files. Comments within string literals are preserved.

Supported comment styles:

• Line comments (until end of line)
• Block comments (can span multiple lines)

String handling:

• Comments inside quoted strings are NOT removed
• Escaped quotes (") are properly handled
• Backslashes within strings are preserved

Parameters

input

The JSON string potentially containing comments

Returns

The JSON string with all comments removed

Note

This allows you to use more readable, documented JSON configuration files while still being able to parse them with standard JSON parsers.

See also

https://jsonc.org/ for more about JSON with Comments (JSONC) format

VarIterator()

juce::VarIterator::VarIterator	(	const juce::var &	,
		bool	isEnd )

Referenced by operator!=(), operator++(), and operator==().

operator++()

VarIterator & juce::VarIterator::operator++

(

)

References VarIterator().

operator==()

bool juce::VarIterator::operator==

(

const VarIterator &

)

const

References VarIterator().

operator!=()

bool juce::VarIterator::operator!=

(

const VarIterator &

)

const

References VarIterator().

operator*()

NamedValue juce::VarIterator::operator*

(

)

const

begin()

VarIterator juce::begin

(

const juce::var &

)

end()

VarIterator juce::end

(

const juce::var &

)

Variable Documentation

key

juce::String Property::key

Property name/key.

Referenced by Property().

value [1/2]

juce::var Property::value

Property value.

Referenced by Property().

name

juce::var juce::VarIterator::NamedValue::name

value [2/2]

juce::var juce::VarIterator::NamedValue::value