Layout — building blocks for organizing your application as a tree of widgets

Layout Managers

Usually, CSS is a sufficient and convenient way to indicate how to layout widgets within a container widget, and we recommend to get accustomed with CSS for basic layout and styling.

There are however several situations when CSS is not effective to create a layout, especially for complex web applications. In particular, when placing contents within a dialog it is often necessary to adjust its contents to available vertical space, and it is often desirable to distribute excess space to a particular widget while keeping other widgets to their preferred size. It is for these reasons that Wt has a comprehensive set of layout managers that use JavaScript to compute and apply layout managent to children of a WContainerWidget.

Wt provides the typical box, grid or border layout management options and layout managers and CSS can safely be intermixed.

Box Layout

WVBoxLayout and WHBoxLayout provide respectively vertical and horizontal layout of widgets inside a WContainerWidget.

In a horizontal box layout, widgets are given an appropriate width based on available space in the container and layout rules, while all widgets get the same height. Similarly, in a vertical box layout, widgets are given appropriate heights based on available space in the container and layout rules, while all widgets get the same width.

In the example below, a WHBoxLayout with default padding (9 pixels) and spacing (6 pixels) is used to manage two child widgets. If no stretch factors have been specified, space is evenly distributed to all widgets.

Example
Item 1
Item 2
source
#include <Wt/WContainerWidget>
#include <Wt/WHBoxLayout>
#include <Wt/WText>

Wt::WContainerWidget *container = new Wt::WContainerWidget();
container->setStyleClass("yellow-box");

Wt::WHBoxLayout *hbox = new Wt::WHBoxLayout();
container->setLayout(hbox);

Wt::WText *item = new Wt::WText("Item 1");
item->setStyleClass("green-box");
hbox->addWidget(item);
  
item = new Wt::WText("Item 2");
item->setStyleClass("blue-box");
hbox->addWidget(item);

The coloring for this and the following examples are provided by a stylesheet that you need to load using WApplication::useStyleSheet():

CSS
.yellow-box {
    background-color: #ffffb4;
    border: 1px solid black;
    margin-top: 1ex;
    margin-bottom: 1ex;
}

.green-box {
    background-color: #c4ffb4;
    min-height: 30px;
    text-align: center;
    padding: 3px;
}

.blue-box {
    background-color: #65dae8;
    min-height: 30px;
    text-align: center;
    padding: 3px;
}

By giving Item 1 a non-zero stretch factor value of 1, Item 2 will only use its preferred width, and Item 1 consumes all excess space, as illustrated below.

Example
Item 1
Item 2
source
#include <Wt/WContainerWidget>
#include <Wt/WHBoxLayout>
#include <Wt/WText>

Wt::WContainerWidget *container = new Wt::WContainerWidget();
container->setStyleClass("yellow-box");

Wt::WHBoxLayout *hbox = new Wt::WHBoxLayout();
container->setLayout(hbox);

Wt::WText *item = new Wt::WText("Item 1");
item->setStyleClass("green-box");
hbox->addWidget(item, 1);
  
item = new Wt::WText("Item 2");
item->setStyleClass("blue-box");
hbox->addWidget(item);

The preferred width of a widget is either based on its contents (which for text is the in some cases inpractical assumption of putting all text on a single line), but can be further controlled using widget->setWidth() or CSS width settings.

The WVBoxLayout works in exactly the same way, but stacks children vertically.

Example
Item 1
Item 2
source
#include <Wt/WContainerWidget>
#include <Wt/WText>
#include <Wt/WVBoxLayout>

Wt::WContainerWidget *container = new Wt::WContainerWidget();
container->resize(150, 150);
container->setStyleClass("yellow-box centered");

Wt::WVBoxLayout *vbox = new Wt::WVBoxLayout();
container->setLayout(vbox);

Wt::WText *item = new Wt::WText("Item 1");
item->setStyleClass("green-box");
vbox->addWidget(item);
  
item = new Wt::WText("Item 2");
item->setStyleClass("blue-box");
vbox->addWidget(item);
Example
Item 1
Item 2
source
#include <Wt/WContainerWidget>
#include <Wt/WText>
#include <Wt/WVBoxLayout>

Wt::WContainerWidget *container = new Wt::WContainerWidget();
container->resize(150, 150);
container->setStyleClass("yellow-box centered");

Wt::WVBoxLayout *vbox = new Wt::WVBoxLayout();
container->setLayout(vbox);

Wt::WText *item = new Wt::WText("Item 1");
item->setStyleClass("green-box");
vbox->addWidget(item, 1);
  
item = new Wt::WText("Item 2");
item->setStyleClass("blue-box");
vbox->addWidget(item);

Layout managers may be arbitrarily nested, either directly, or indirectly through widget composition, to create complex layouts. Layout managers fully cooperate with CSS, honoring the CSS margins and paddings of children, but also those of intermediate widgets in complex layouts.

In the example below we nest a WHBoxLayout containing two items in a WVBoxLayout containing one other item.

Example
Item 1
Item 2
Item 3
source
#include <Wt/WContainerWidget>
#include <Wt/WHBoxLayout>
#include <Wt/WText>
#include <Wt/WVBoxLayout>

Wt::WContainerWidget *container = new Wt::WContainerWidget();
container->resize(200, 200);
container->setStyleClass("yellow-box centered");

Wt::WVBoxLayout *vbox = new Wt::WVBoxLayout();
container->setLayout(vbox);

Wt::WText *item = new Wt::WText("Item 1");
item->setStyleClass("green-box");
vbox->addWidget(item, 1);

Wt::WHBoxLayout *hbox = new Wt::WHBoxLayout();
vbox->addLayout(hbox);

item = new Wt::WText("Item 2");
item->setStyleClass("green-box");
hbox->addWidget(item);

item = new Wt::WText("Item 3");
item->setStyleClass("blue-box");
hbox->addWidget(item);

Top

Grid Layout

This layout manager organizes the contents of a WContainerWidget in a grid.

Like WBoxLayout, a stretch factor defined for rows or columns is used to distribute excess space. In the example below, row 1 and columns 1 and 2 are given a non-zero stretch factor.

Example
Item (0, 0)
Item (0, 1)
Item (0, 2)
Item (0, 3)
Item (1, 0)
Item (1, 1)
Item (1, 2)
Item (1, 3)
Item (2, 0)
Item (2, 1)
Item (2, 2)
Item (2, 3)
source
#include <Wt/WContainerWidget>
#include <Wt/WGridLayout>
#include <Wt/WText>

Wt::WContainerWidget *container = new Wt::WContainerWidget();
container->setHeight(400);
container->setStyleClass("yellow-box");

Wt::WGridLayout *grid = new Wt::WGridLayout();
container->setLayout(grid);

for (int row = 0; row < 3; ++row) {
    for (int column = 0; column < 4; ++column) {
	Wt::WString cell = Wt::WString("Item ({1}, {2})").arg(row).arg(column);

	Wt::WText *t = new Wt::WText(cell);
	if (row == 1 || column == 1 || column == 2)
	    t->setStyleClass("blue-box");
	else
	    t->setStyleClass("green-box");

	grid->addWidget(t, row, column);
    }
}

grid->setRowStretch(1, 1);
grid->setColumnStretch(1, 1);
grid->setColumnStretch(2, 1);

Top

Border Layout

This is a layout manager that organizes the container space in up to 5 regions, with a central region consuming any excess space.

Any of the regions can be omitted.

Example
North item
West item
Center item
East item
South item
source
#include <Wt/WContainerWidget>
#include <Wt/WBorderLayout>
#include <Wt/WText>

Wt::WContainerWidget *container = new Wt::WContainerWidget();
container->setHeight(400);
container->setStyleClass("yellow-box");

Wt::WBorderLayout *layout = new Wt::WBorderLayout();
container->setLayout(layout);

const char *cell = "{1} item";

Wt::WText *item = new Wt::WText(Wt::WString(cell).arg("North"));
item->setStyleClass("green-box");
layout->addWidget(item, Wt::WBorderLayout::North);

item = new Wt::WText(Wt::WString(cell).arg("West"));
item->setStyleClass("green-box");
layout->addWidget(item, Wt::WBorderLayout::West);

item = new Wt::WText(Wt::WString(cell).arg("East"));
item->setStyleClass("green-box");
layout->addWidget(item, Wt::WBorderLayout::East);

item = new Wt::WText(Wt::WString(cell).arg("South"));
item->setStyleClass("green-box");
layout->addWidget(item, Wt::WBorderLayout::South);

item = new Wt::WText(Wt::WString(cell).arg("Center"));
item->setStyleClass("green-box");
layout->addWidget(item, Wt::WBorderLayout::Center);

Top