BasicLayout
BasicLayout is one of the fundamental building blocks of JDance. It provides a flexible way to arrange components horizontally or vertically, create responsive interfaces, and control the size, spacing, and appearance of individual cells.
Layouts can be nested inside other layouts, making it possible to build complete user interfaces using Java alone.
The examples below demonstrate some of the most important capabilities of BasicLayout.
For complete documentation and the full API reference, visit https://doc.jdance.org.
Building complete interfaces
BasicLayout is more than a simple horizontal or vertical container. By combining multiple layouts, you can build entire application interfaces with headers, navigation areas, content sections, cards, and other visual elements.
Each layout controls how its immediate child cells are arranged. Those cells can contain ordinary components or additional layouts.
The following example combines several BasicLayouts to create a styled dashboard. It demonstrates nesting, backgrounds, spacing, sizing, and responsive behavior.
Resize your browser to see how the interface adapts to smaller screens.
CODE
Media mobile = new Media(0,1300);
BasicLayout layout = new BasicLayout(BasicLayout.Direction.VERTICAL);
layout.setRelativeWidth(100);
layout.setGap(12);
layout.setPadding(16);
layout.setBackground(new Color("#F4F7FB"));
layout.setBorder(new Border());
BasicLayout heading = new BasicLayout(BasicLayout.Direction.VERTICAL);
heading.setGap(6);
heading.add(new Text("JDance Dashboard")).setPadding(10).setBackground(new Color("#DCEEFF"));
heading.add(new Text("A responsive interface built entirely with BasicLayout.")).setPadding(8);
layout.add(heading).setRelativeWidth(100);
BasicLayout summary = new BasicLayout(BasicLayout.Direction.HORIZONTAL);
summary.setDirection(mobile,BasicLayout.Direction.VERTICAL);
summary.setGap(10);
summary.add(new Text("Projects: 12")).setPadding(16).setBackground(new Color("#DCEEFF"));
summary.add(new Text("Active tasks: 28")).setPadding(16).setBackground(new Color("#E4F5E9"));
summary.add(new Text("Messages: 5")).setPadding(16).setBackground(new Color("#FFF0D8"));
layout.add(summary).setRelativeWidth(100);
BasicLayout content = new BasicLayout(BasicLayout.Direction.HORIZONTAL);
content.setDirection(mobile,BasicLayout.Direction.VERTICAL);
content.setGap(10);
BasicLayout activity = new BasicLayout(BasicLayout.Direction.VERTICAL);
activity.setGap(5);
activity.add(new Text("Recent activity")).setPadding(10).setBackground(new Color("#DCEEFF"));
activity.add(new Text("Website documentation updated")).setPadding(10).setBackground(new Color("#FFFFFF"));
activity.add(new Text("New layout examples published")).setPadding(10).setBackground(new Color("#FFFFFF"));
activity.add(new Text("Responsive design reviewed")).setPadding(10).setBackground(new Color("#FFFFFF"));
content.add(activity).setRelativeWidth(65).setRelativeWidth(mobile,100);
BasicLayout status = new BasicLayout(BasicLayout.Direction.VERTICAL);
status.setGap(5);
status.add(new Text("Project status")).setPadding(10).setBackground(new Color("#E4F5E9"));
status.add(new Text("Documentation: ready")).setPadding(10).setBackground(new Color("#FFFFFF"));
status.add(new Text("Examples: in progress")).setPadding(10).setBackground(new Color("#FFFFFF"));
content.add(status).setRelativeWidth(35).setRelativeWidth(mobile,100);
layout.add(content).setRelativeWidth(100);
layout.add(new Text("BasicLayout controls direction, spacing, sizing, padding and cell styling.")).setPadding(10).setBackground(new Color("#E8EDF4"));RESULT
A responsive interface built entirely with BasicLayout.
Website documentation updated
New layout examples published
Responsive design reviewed
BasicLayout controls direction, spacing, sizing, padding and cell styling.
Direction and responsive layouts
A BasicLayout can arrange its cells in two directions: HORIZONTAL or VERTICAL.
With HORIZONTAL, cells are placed next to each other. With VERTICAL, they are stacked from top to bottom.
You can also change the direction depending on the available screen width using Media. This allows a single layout to adapt to desktop and mobile screens without creating separate interfaces.
In this example, the three cells appear next to each other on larger screens. When the screen width reaches 700px or less, the layout automatically changes direction and stacks the cells vertically.
The same components are used in both layouts. Only their arrangement changes.
CODE
Media mobile = new Media(0,700);
BasicLayout layout = new BasicLayout(BasicLayout.Direction.HORIZONTAL);
layout.setDirection(mobile,BasicLayout.Direction.VERTICAL);
layout.setRelativeWidth(100);
layout.setGap(8);
layout.add(new Text("Navigation")).setPadding(16).setBackground(new Color("#DCEEFF"));
layout.add(new Text("Main content")).setPadding(16).setBackground(new Color("#E4F5E9"));
layout.add(new Text("Details")).setPadding(16).setBackground(new Color("#F5E5F8"));Sizing cells
BasicLayout gives you control over the dimensions of individual cells.
Cells can have fixed widths and heights in pixels, or relative dimensions expressed as percentages of the available space.
Relative dimensions are useful for building flexible interfaces that adapt to their container. Fixed dimensions are useful when a component needs a predictable size.
You can also configure minimum and maximum dimensions to control how individual cells behave when space becomes limited.
The following example compares three different widths: a cell occupying 100% of the available space, a cell occupying 60%, and a cell with a fixed width of 220 pixels.
CODE
BasicLayout layout = new BasicLayout(BasicLayout.Direction.VERTICAL);
layout.setRelativeWidth(100);
layout.setGap(8);
layout.add(new Text("100% width")).setRelativeWidth(100).setPadding(12).setBackground(new Color("#DCEEFF"));
layout.add(new Text("60% width")).setRelativeWidth(60).setPadding(12).setBackground(new Color("#E4F5E9"));
layout.add(new Text("220px width")).setWidth(220).setPadding(12).setBackground(new Color("#FFF0D8"));Spacing and styling
BasicLayout provides several ways to control the appearance and spacing of a layout.
Padding creates space inside a layout or cell, while gap controls the distance between neighboring cells.
You can configure padding on the entire layout, apply common padding to all its cells, or customize individual cells independently.
Background colors can also be assigned to both layouts and cells, allowing them to form distinct visual sections.
In this example, the layout has 16px of outer padding, 12px of padding inside every cell, and a 12px gap between neighboring cells.
Each cell also has its own background color, creating a simple card-based interface.
CODE
BasicLayout layout = new BasicLayout(BasicLayout.Direction.VERTICAL);
layout.setRelativeWidth(100);
layout.setPadding(16);
layout.setCellPadding(12);
layout.setGap(12);
layout.setBackground(new Color("#F1F3F5"));
layout.add(new Text("First card - blue")).setBackground(new Color("#DCEEFF"));
layout.add(new Text("Second card - green")).setBackground(new Color("#E4F5E9"));
layout.add(new Text("Third card - violet")).setBackground(new Color("#F5E5F8"));Borders, outlines and shadows
BasicLayout supports several visual properties that help distinguish elements and create structure within an interface.
Borders appear around layouts or individual cells and are part of their dimensions. When adjacent cells have borders, border collapsing can be used to avoid doubled lines between them.
Outlines surround an element without taking up additional layout space. They are useful for emphasis, highlighting, and indicating focus.
Shadows add visual depth and can help distinguish cards and panels from their surroundings.
The example below combines all three techniques.
First, it creates a group of cells with collapsing borders. Next, it creates a layout with a blue outline. Finally, it creates a white panel with a border and a soft shadow.
These features can be combined with padding, backgrounds, and nested layouts to create visually structured interfaces.
CODE
BasicLayout layout = new BasicLayout(BasicLayout.Direction.VERTICAL);
layout.setRelativeWidth(100);
layout.setGap(22);
layout.setPadding(16);
layout.setBackground(new Color("#F4F7FB"));
BasicLayout borders = new BasicLayout(BasicLayout.Direction.VERTICAL);
borders.setRelativeWidth(100);
borders.setCellPadding(12);
borders.setCellBorder(new Border(1,Border.Style.SOLID,new Color("#B7C5D5")));
borders.setBorderCollapse(true);
borders.add(new Text("Profile")).setBackground(new Color("#FFFFFF"));
borders.add(new Text("Settings")).setBackground(new Color("#EAF3FF"));
borders.add(new Text("Notifications")).setBackground(new Color("#FFFFFF"));
layout.add(new Text("Collapsing cell borders"));
layout.add(borders).setRelativeWidth(100);
BasicLayout outline = new BasicLayout(BasicLayout.Direction.VERTICAL);
outline.setRelativeWidth(100);
outline.setPadding(14);
outline.setBackground(new Color("#FFFFFF"));
outline.addExplicitStyle("outline","3px solid #0783C5");
outline.add(new Text("Outline surrounds the layout without affecting its size."));
layout.add(new Text("Outline"));
layout.add(outline).setRelativeWidth(100);
BasicLayout shadow = new BasicLayout(BasicLayout.Direction.VERTICAL);
shadow.setRelativeWidth(100);
shadow.setPadding(16);
shadow.setBackground(new Color("#FFFFFF"));
shadow.setBorder(new Border(1,Border.Style.SOLID,new Color("#E1E7EF")));
shadow.setShadow(new Shadow(3,3,8,new Color("#B7C5D5")));
shadow.add(new Text("Shadows add depth without changing the layout spacing."));
layout.add(new Text("Shadow"));
layout.add(shadow).setRelativeWidth(100);RESULT
Outline surrounds the layout without affecting its size.
Shadows add depth without changing the layout spacing.
Learn more
These examples demonstrate only a small part of what BasicLayout can do.
BasicLayout also supports alignment, overflow, minimum and maximum dimensions, media-specific properties, and event handling.
For detailed explanations, additional examples, and the complete API reference, visit https://doc.jdance.org.