ComponentGrid Class Reference

Animated grid container with drag-and-drop reordering support. More...

#include <gin_componentgrid.h>

Inherits juce::Component, and juce::Timer.

Classes
struct	DragInfo

Public Types
enum	Orientation { vertical , horizontal }
	Grid layout orientation. More...

Public Member Functions
	ComponentGrid (const juce::String &name={}, Orientation o=horizontal)
	Creates a ComponentGrid with the specified name and orientation.
	~ComponentGrid () override
	Destructor.
bool	isDragInProgress ()
	Checks if a drag operation is currently in progress.
void	setGap (int gap)
	Sets the gap/spacing between grid items.
void	setOrientation (Orientation o)
	Sets the grid layout orientation.
void	timerCallback () override
void	mouseDown (const juce::MouseEvent &e) override
void	mouseDrag (const juce::MouseEvent &e) override
void	mouseUp (const juce::MouseEvent &e) override
void	resized () override

Static Public Member Functions
static bool	isGridDrag (juce::var dragSourceDetails)
	Checks if a drag source represents a ComponentGrid drag operation.
static int	getDragIndex (juce::var dragSourceDetails)
	Gets the index of the dragged component from drag source details.

Public Attributes
std::function< bool(const juce::MouseEvent &)>	onDragStart
	Callback invoked when a drag operation starts.
std::function< void(int, int)>	onOrderChanged
	Callback invoked when items are reordered via drag-and-drop.
std::function< void(int, int)>	onDragFinished
	Callback invoked when a drag operation completes.

Protected Member Functions
void	layoutAnimated ()
int	componentIndex (juce::Component &c)
juce::Array< juce::Rectangle< int > >	getComponentRects ()

Protected Attributes
bool	dragStarted = false
bool	dragging = false
bool	dragOut = false
Orientation	orientation = horizontal
int	gap = 1
juce::Array< juce::Component * >	originalOrder
juce::ComponentAnimator	animator

Detailed Description

Animated grid container with drag-and-drop reordering support.

ComponentGrid arranges child components in a row or column with smooth animated transitions. Components can be reordered via drag-and-drop, making it ideal for customizable toolbars, tab bars, or any UI where users can rearrange elements.

Key Features:

• Automatic grid layout (horizontal or vertical)
• Smooth animations when reordering
• Drag-and-drop reordering with visual feedback
• Configurable spacing between items
• Callbacks for drag events and order changes
• Component dragging across grid boundaries

The grid handles layout and animation automatically. When children are reordered via drag-and-drop, the grid smoothly animates them to their new positions.

Usage:

ComponentGrid grid("ToolbarGrid", ComponentGrid::horizontal);
grid.setGap(5); // 5 pixel spacing
 
// Add components
grid.addAndMakeVisible(new Button("Tool 1"));
grid.addAndMakeVisible(new Button("Tool 2"));
grid.addAndMakeVisible(new Button("Tool 3"));
 
// Listen for order changes
grid.onOrderChanged = [](int oldIndex, int newIndex) {
    // Save new order to preferences
};
 
// Optional: Control when dragging can start
grid.onDragStart = [](const MouseEvent& e) {
    return e.mods.isLeftButtonDown(); // Only left-click dragging
};

See also

ComponentAnimator

Member Enumeration Documentation

Orientation

enum ComponentGrid::Orientation

Grid layout orientation.

Enumerator
vertical	Items arranged vertically (top to bottom).
horizontal	Items arranged horizontally (left to right).

Constructor & Destructor Documentation

ComponentGrid()

ComponentGrid::ComponentGrid	(	const juce::String &	name = {},
		Orientation	o = horizontal )

Creates a ComponentGrid with the specified name and orientation.

Parameters

name	Name for the grid component
o	Layout orientation (horizontal or vertical)

~ComponentGrid()

ComponentGrid::~ComponentGrid ( )

override

Destructor.

Member Function Documentation

isDragInProgress()

bool ComponentGrid::isDragInProgress

(

)

Checks if a drag operation is currently in progress.

Returns

true if an item is being dragged

setGap()

void ComponentGrid::setGap

(

int

gap

)

Sets the gap/spacing between grid items.

Parameters

gap	Spacing in pixels between items

References gap.

setOrientation()

void ComponentGrid::setOrientation

(

Orientation

o

)

Sets the grid layout orientation.

Parameters

o	New orientation (horizontal or vertical)

isGridDrag()

bool ComponentGrid::isGridDrag ( juce::var dragSourceDetails )

static

Checks if a drag source represents a ComponentGrid drag operation.

Parameters

dragSourceDetails

Drag source information from JUCE drag-and-drop

Returns

true if this is a grid drag operation

getDragIndex()

int ComponentGrid::getDragIndex ( juce::var dragSourceDetails )

static

Gets the index of the dragged component from drag source details.

Parameters

dragSourceDetails

Drag source information from JUCE drag-and-drop

Returns

The index of the component being dragged, or -1 if not a grid drag

timerCallback()

void ComponentGrid::timerCallback ( )

override

Timer callback for animations

mouseDown()

void ComponentGrid::mouseDown ( const juce::MouseEvent & e )

override

Mouse down handler for drag initiation

mouseDrag()

void ComponentGrid::mouseDrag ( const juce::MouseEvent & e )

override

Mouse drag handler for reordering

mouseUp()

void ComponentGrid::mouseUp ( const juce::MouseEvent & e )

override

Mouse up handler for drag completion

resized()

void ComponentGrid::resized ( )

override

Resized handler for layout updates

layoutAnimated()

void ComponentGrid::layoutAnimated ( )

protected

Performs animated layout of all child components

componentIndex()

int ComponentGrid::componentIndex ( juce::Component & c )

protected

Gets the index of a component in the grid

Parameters

c	The component to find

Returns

The component's index, or -1 if not found

getComponentRects()

juce::Array< juce::Rectangle< int > > ComponentGrid::getComponentRects ( )

protected

Calculates the target rectangles for all components

Returns

Array of rectangles for each component in order

Member Data Documentation

onDragStart

std::function<bool(const juce::MouseEvent&)> ComponentGrid::onDragStart

Callback invoked when a drag operation starts.

Return false to prevent dragging. Default behavior allows all drags.

Example:

grid.onDragStart = [](const MouseEvent& e) {
    return e.mods.isLeftButtonDown(); // Only left-click dragging
};

Parameters

MouseEvent

The mouse event that initiated the drag

Returns

true to allow dragging, false to prevent it

onOrderChanged

std::function<void (int, int)> ComponentGrid::onOrderChanged

Callback invoked when items are reordered via drag-and-drop.

Called after the drag completes and items have been reordered.

Example:

grid.onOrderChanged = [](int oldIndex, int newIndex) {
    DBG("Item moved from " << oldIndex << " to " << newIndex);
};

Parameters

oldIndex	Original position of the dragged item
newIndex	New position after reordering

onDragFinished

std::function<void (int, int)> ComponentGrid::onDragFinished

Callback invoked when a drag operation completes.

Called when the mouse is released, whether or not reordering occurred.

Parameters

oldIndex	Original position of the dragged item
newIndex	Final position (may be same as oldIndex if no reorder)

dragStarted

bool ComponentGrid::dragStarted = false

protected

True if drag gesture started

dragging

bool ComponentGrid::dragging = false

protected

True during active drag

dragOut

bool ComponentGrid::dragOut = false

protected

True if dragged outside grid

orientation

Orientation ComponentGrid::orientation = horizontal

protected

Current layout orientation

gap

int ComponentGrid::gap = 1

protected

Spacing between items in pixels

Referenced by setGap().

originalOrder

juce::Array<juce::Component*> ComponentGrid::originalOrder

protected

Original order before drag

animator

juce::ComponentAnimator ComponentGrid::animator

protected

Handles smooth animations

---

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

• gin_componentgrid.h