Wt: Wt::WGridLayout Class Reference

Wt 4.10.4

Loading...
Searching...
No Matches
Public Member Functions | Private Member Functions | List of all members
Wt::WGridLayout Class Reference

A layout manager which arranges widgets in a grid. More...

`#include <Wt/WGridLayout.h>`

Inheritance diagram for Wt::WGridLayout:
[legend]

## Public Member Functions
| WGridLayout ()
| Create a new grid layout.
virtual void | addItem (std::unique_ptr< WLayoutItem > item) override
| Adds a layout item.
virtual std::unique_ptr< WLayoutItem > | removeItem (WLayoutItem *item) override
| Removes a layout item (widget or nested layout).
virtual WLayoutItem * | itemAt (int index) const override
| Returns the layout item at a specific index.
virtual int | count () const override
| Returns the number of items in this layout.
void | addItem (std::unique_ptr< WLayoutItem > item, int row, int column, int rowSpan=1, int columnSpan=1, WFlags< AlignmentFlag > alignment=None)
| Adds a layout item to the grid.
void | addLayout (std::unique_ptr< WLayout > layout, int row, int column, WFlags< AlignmentFlag > alignment=None)
| Adds a nested layout item to the grid.
void | addLayout (std::unique_ptr< WLayout > layout, int row, int column, int rowSpan, int columnSpan, WFlags< AlignmentFlag > alignment=None)
| Adds a nested layout item to the grid.
void | addWidget (std::unique_ptr< WWidget > widget, int row, int column, WFlags< AlignmentFlag > alignment)
| Adds a widget to the grid.
template<typename Widget >
Widget * | addWidget (std::unique_ptr< Widget > widget, int row, int column, WFlags< AlignmentFlag > alignment=None)
| Adds a widget to the grid, returning a raw pointer to the widget.
void | addWidget (std::unique_ptr< WWidget > widget, int row, int column, int rowSpan, int columnSpan, WFlags< AlignmentFlag > alignment)
| Adds a widget to the grid.
template<typename Widget >
Widget * | addWidget (std::unique_ptr< Widget > widget, int row, int column, int rowSpan, int columnSpan, WFlags< AlignmentFlag > alignment=None)
| Adds a widget to the grid, returning a raw pointer to the widget.
void | setHorizontalSpacing (int size)
| Sets the horizontal spacing.
int | horizontalSpacing () const
| Returns the horizontal spacing.
void | setVerticalSpacing (int size)
| Sets the vertical spacing.
int | verticalSpacing () const
| Returns the vertical spacing.
int | columnCount () const
| Returns the column count.
int | rowCount () const
| Returns the row count.
void | setColumnStretch (int column, int stretch)
| Sets the column stretch.
int | columnStretch (int column) const
| Returns the column stretch.
void | setRowStretch (int row, int stretch)
| Sets the row stretch.
int | rowStretch (int row) const
| Returns the column stretch.
void | setColumnResizable (int column, bool enabled=true, const WLength &initialSize=WLength::Auto)
| Sets whether the user may drag a particular column border.
bool | columnIsResizable (int column) const
| Returns whether the user may drag a particular column border.
void | setRowResizable (int row, bool enabled=true, const WLength &initialSize=WLength::Auto)
| Sets whether the user may drag a particular row border.
bool | rowIsResizable (int row) const
| Returns whether the user may drag a particular row border.
Public Member Functions inherited from Wt::WLayout
virtual | ~WLayout ()
| Destructor.
void | setPreferredImplementation (LayoutImplementation implementation)
| Set the preferred layout implementation.
void | addWidget (std::unique_ptr< WWidget > widget)
| Adds the given widget to the layout.
std::unique_ptr< WWidget > | removeWidget (WWidget *widget)
| Removes the given widget from the layout.
virtual int | indexOf (WLayoutItem *item) const
| Returns the index of a given item.
virtual WWidgetItem * | findWidgetItem (WWidget *widget) override
| Finds the widget item associated with the given widget.
virtual WWidget * | widget () override
| Returns the widget that is held by this WLayoutItem.
virtual WLayout * | layout () override
| Returns the layout that implements this WLayoutItem.
virtual WLayout * | parentLayout () const override
| Returns the layout in which this item is contained.
void | setContentsMargins (int left, int top, int right, int bottom)
| Set contents margins (in pixels).
void | getContentsMargins (int *left, int *top, int *right, int *bottom) const
| Returns the contents margins.
Public Member Functions inherited from Wt::WLayoutItem
virtual | ~WLayoutItem ()
| Destructor.
Public Member Functions inherited from Wt::WObject
void | addChild (std::unique_ptr< WObject > child)
| Add a child WObject whose lifetime is determined by this WObject.
template<typename Child >
Child * | addChild (std::unique_ptr< Child > child)
| Add a child WObject, returning a raw pointer.
std::unique_ptr< WObject > | removeChild (WObject *child)
| Remove a child WObject, so its lifetime is no longer determined by this WObject.
template<typename Child >
std::unique_ptr< Child > | removeChild (Child *child)
| Remove a child WObject, so its lifetime is no longer determined by this WObject.
virtual const std::string | id () const
| Returns the (unique) identifier for this object.
virtual void | setObjectName (const std::string &name)
| Sets an object name.
virtual std::string | objectName () const
| Returns the object name.
void | resetLearnedSlots ()
| Resets learned stateless slot implementations.
template<class T >
void | resetLearnedSlot (void(T::*method)())
| Resets a learned stateless slot implementation.
template<class T >
WStatelessSlot * | implementStateless (void(T::*method)())
| Declares a slot to be stateless and learn client-side behaviour on first invocation.
template<class T >
WStatelessSlot * | implementStateless (void(T::*method)(), void(T::*undoMethod)())
| Declares a slot to be stateless and learn client-side behaviour in advance.
void | isNotStateless ()
| Marks the current function as not stateless.
template<class T >
WStatelessSlot * | implementJavaScript (void(T::*method)(), const std::string &jsCode)
| Provides a JavaScript implementation for a method.
Public Member Functions inherited from Wt::Core::observable
| observable () noexcept
| Default constructor.
virtual | ~observable ()
| Destructor.
template<typename... Args, typename C >
auto | bindSafe (void(C::*method)(Args...)) noexcept
| Protects a method call against object destruction.
template<typename... Args, typename C >
auto | bindSafe (void(C::*method)(Args...) const) const noexcept
| Protects a const method call against object destruction.
template<typename Function >
auto | bindSafe (const Function &function) noexcept
| Protects a function against object destruction.

## Private Member Functions
virtual void | setParentWidget (WWidget *parent) override
| Internal method.

## Additional Inherited Members
Public Types inherited from Wt::WLayoutItem
Public Types inherited from Wt::WObject
typedef void(WObject::*) | Method()
| Typedef for a WObject method without arguments.
Static Public Member Functions inherited from Wt::WLayout
static void | setDefaultImplementation (LayoutImplementation implementation)
| Sets the preferred layout implementation globally.
Static Public Member Functions inherited from Wt::WObject
Protected Member Functions inherited from Wt::WLayout
| WLayout ()
| Create a layout.
void | update (WLayoutItem *item=nullptr)
| Update the layout.
Protected Member Functions inherited from Wt::WObject
virtual WStatelessSlot * | getStateless (Method method)
| On-demand stateless slot implementation.

## Detailed Description

A layout manager which arranges widgets in a grid.

This layout manager arranges widgets in a grid.

Each grid cell (row, column) may contain one widget or nested layout. Orientation::Horizontal and vertical space are divided so that each non-stretchable column/row is given its preferred size (if possible) and the remaining space is divided according to stretch factors among the columns/rows. If not all columns/rows can be given their preferred size (there is not enough room), then columns/rows are given a smaller size (down to a minimum size based on widget minimum sizes). If necessary, the container (or parent layout) of this layout is resized to meet minimum size requirements.

The preferred width/height of a column/row is based on the natural size of the widgets, where they present their contents without overflowing. WWidget::resize() or (CSS `width`, `height` properties) can be used to adjust the preferred size of a widget.

The minimum width/height of a column/row is based on the minimum dimensions of contained widgets or nested layouts. The default minimum height and width for a widget is 0. It can be specified using WWidget::setMinimumSize() or using CSS `min-width` and `min-height` properties.

You should use WContainerWidget::setOverflow(OverflowAuto) to automatically show scrollbars for widgets inserted in the layout to cope with a size set by the layout manager that is smaller than the preferred size.

When the container of a layout manager has a maximum size set using WWidget::setMaximumSize(), then the size of the container will be based on the preferred size of the contents, up to this maximum size, instead of the default behaviour of constraining the size of the children based on the size of the container.

A layout manager may provide resize handles between columns or rows which allow the user to change the automatic layout provided by the layout manager (see setRowResizable() and setColumnResizable()).

Columns and rows are separated using a constant spacing, which defaults to 6 pixels by default, and can be changed using setHorizontalSpacing() and setVerticalSpacing(). In addition, when this layout is a top-level layout (i.e. is not nested inside another layout), a margin is set around the contents. This margin defaults to 9 pixels, and can be changed using setContentsMargins().

For each column or row, a stretch factor may be defined, which controls how remaining horizontal or vertical space is used. Each column and row is stretched using the stretch factor to fill the remaining space. When the stretch factor is 0, the height of the row and its contents is set to the preferred size (if possible). When the stretch factor is 1 or higher, these widgets will be given the remaining size, limited only by their minimum size (their preferred size is ignored).

Usage example:

Wt::WContainerWidget *w = addWidget(std::make_unique<Wt::WContainerWidget>());
w->resize(WLength::Auto, 600);
auto layout = std::make_unique<Wt::WGridLayout>();
layout->addWidget(std::make_unique<Wt::WText>("Item 0 0"), 0, 0);
layout->addWidget(std::make_unique<Wt::WText>("Item 0 1"), 0, 1);
layout->addWidget(std::make_unique<Wt::WText>("Item 1 0"), 1, 0);
layout->addWidget(std::make_unique<Wt::WText>("Item 1 1"), 1, 1);
w->setLayout(std::move(layout));
Wt::WContainerWidget
A widget that holds and manages child widgets.
Definition WContainerWidget.h:135
Wt::WContainerWidget::setLayout
void setLayout(std::unique_ptr< WLayout > layout)
Sets a layout manager for the container.
Wt::WGridLayout::addWidget
void addWidget(std::unique_ptr< WWidget > widget, int row, int column, WFlags< AlignmentFlag > alignment)
Adds a widget to the grid.
Wt::WLayout::addWidget
void addWidget(std::unique_ptr< WWidget > widget)
Adds the given widget to the layout.
Wt::WLayout::layout
virtual WLayout * layout() override
Returns the layout that implements this WLayoutItem.
Definition WLayout.h:162
Wt::WLength::Auto
static WLength Auto
An 'auto' length.
Definition WLength.h:65
Wt::WWebWidget::resize
virtual void resize(const WLength &width, const WLength &height) override
Resizes the widget.

Note
  When JavaScript support is not available, not all functionality of the layout is available. In particular, vertical size management is not available.
  When a layout is used on a first page with progressive bootstrap, then the layout will progress only in a limited way to a full JavaScript-based layout. You can thus not rely on it to behave properly for example when dynamically adding or removing widgets.

## Constructor & Destructor Documentation

## ◆ WGridLayout()

Wt::WGridLayout::WGridLayout | ( |  | ) |

Create a new grid layout.

The grid will grow dynamically as items are added.

Use `parent` = `0` to create a layout manager that can be nested inside other layout managers or if you use WContainerWidget::setLayout() to add specify the container later.

## Member Function Documentation

## ◆ addItem() [1/2]

virtual void Wt::WGridLayout::addItem | ( | std::unique_ptr< WLayoutItem > | item | ) |
| overridevirtual

Adds a layout item.

The item may be a widget or nested layout.

How the item is layed out with respect to siblings is implementation specific to the layout manager. In some cases, a layout manager will overload this method with extra arguments that specify layout options.

See also
  removeItem(WLayoutItem *), addWidget(WWidget *)

Implements Wt::WLayout.

## ◆ addItem() [2/2]

void Wt::WGridLayout::addItem | ( | std::unique_ptr< WLayoutItem > | item,
|  | int | row,
|  | int | column,
|  | int | rowSpan = 1,
|  | int | columnSpan = 1,
|  | WFlags< AlignmentFlag > | alignment = None )

Adds a layout item to the grid.

Adds the item at (row, `column`). If an item was already added to that location, it is replaced.

An item may span several more rows or columns, which is controlled by rowSpan and `columnSpan`.

The `alignment` specifies the vertical and horizontal alignment of the item. The default value 0 indicates that the item is stretched to fill the entire grid cell. The alignment can be specified as a logical combination of a horizontal alignment (Wt::AlignmentFlag::Left, Wt::AlignmentFlag::Center, or Wt::AlignmentFlag::Right) and a vertical alignment (Wt::AlignmentFlag::Top, Wt::AlignmentFlag::Middle, or Wt::AlignmentFlag::Bottom).

See also
  addLayout(), addWidget()

## ◆ addLayout() [1/2]

void Wt::WGridLayout::addLayout | ( | std::unique_ptr< WLayout > | layout,
|  | int | row,
|  | int | column,
|  | int | rowSpan,
|  | int | columnSpan,
|  | WFlags< AlignmentFlag > | alignment = None )

Adds a nested layout item to the grid.

Adds the layout at (row, `column`). If an item was already added to that location, it is replaced (but not deleted).

An item may span several more rows or columns, which is controlled by rowSpan and `columnSpan`.

The `alignment` specifies the vertical and horizontal alignment of the item. The default value 0 indicates that the item is stretched to fill the entire grid cell. The alignment can be specified as a logical combination of a horizontal alignment (Wt::AlignmentFlag::Left, Wt::AlignmentFlag::Center, or Wt::AlignmentFlag::Right) and a vertical alignment (Wt::AlignmentFlag::Top, Wt::AlignmentFlag::Middle, or Wt::AlignmentFlag::Bottom).

See also
  addLayout(WLayout *, int, int, WFlags<AlignmentFlag>)

## ◆ addLayout() [2/2]

void Wt::WGridLayout::addLayout | ( | std::unique_ptr< WLayout > | layout,
|  | int | row,
|  | int | column,
|  | WFlags< AlignmentFlag > | alignment = None )

Adds a nested layout item to the grid.

Adds the layout at (row, `column`). If an item was already added to that location, it is replaced (but not deleted).

The `alignment` specifies the vertical and horizontal alignment of the item. The default value 0 indicates that the item is stretched to fill the entire grid cell. The alignment can be specified as a logical combination of a horizontal alignment (Wt::AlignmentFlag::Left, Wt::AlignmentFlag::Center, or Wt::AlignmentFlag::Right) and a vertical alignment (Wt::AlignmentFlag::Top, Wt::AlignmentFlag::Middle, or Wt::AlignmentFlag::Bottom).

See also
  addLayout(WLayout *, int, int, int, int, WFlags<AlignmentFlag>)

## ◆ addWidget() [1/4]

template<typename Widget >

Widget * Wt::WGridLayout::addWidget | ( | std::unique_ptr< Widget > | widget,
|  | int | row,
|  | int | column,
|  | int | rowSpan,
|  | int | columnSpan,
|  | WFlags< AlignmentFlag > | alignment = None )

Adds a widget to the grid, returning a raw pointer to the widget.

This is implemented as:

Widget *result = widget.get();
addWidget(std::unique_ptr<WWidget>(std::move(widget)), row, column,
rowSpan, columnSpan, alignment);
return result;
Wt::WLayout::widget
virtual WWidget * widget() override
Returns the widget that is held by this WLayoutItem.
Definition WLayout.h:161

## ◆ addWidget() [2/4]

template<typename Widget >

Widget * Wt::WGridLayout::addWidget | ( | std::unique_ptr< Widget > | widget,
|  | int | row,
|  | int | column,
|  | WFlags< AlignmentFlag > | alignment = None )

Adds a widget to the grid, returning a raw pointer to the widget.

This is implemented as:

Widget *result = widget.get();
addWidget(std::unique_ptr<WWidget>(std::move(widget)), row, column, alignment);
return result;

## ◆ addWidget() [3/4]

void Wt::WGridLayout::addWidget | ( | std::unique_ptr< WWidget > | widget,
|  | int | row,
|  | int | column,
|  | int | rowSpan,
|  | int | columnSpan,
|  | WFlags< AlignmentFlag > | alignment )

Adds a widget to the grid.

Adds the widget at (row, `column`). If an item was already added to that location, it is replaced (but not deleted).

The widget may span several more rows or columns, which is controlled by rowSpan and `columnSpan`.

The `alignment` specifies the vertical and horizontal alignment of the item. The default value 0 indicates that the item is stretched to fill the entire grid cell. The alignment can be specified as a logical combination of a horizontal alignment (Wt::AlignmentFlag::Left, Wt::AlignmentFlag::Center, or Wt::AlignmentFlag::Right) and a vertical alignment (Wt::AlignmentFlag::Top, Wt::AlignmentFlag::Middle, or Wt::AlignmentFlag::Bottom).

See also
  addWidget(WWidget *, int, int, WFlags<AlignmentFlag>)

## ◆ addWidget() [4/4]

void Wt::WGridLayout::addWidget | ( | std::unique_ptr< WWidget > | widget,
|  | int | row,
|  | int | column,
|  | WFlags< AlignmentFlag > | alignment )

Adds a widget to the grid.

Adds the widget at (row, `column`). If an item was already added to that location, it is replaced (but not deleted).

The `alignment` specifies the vertical and horizontal alignment of the item. The default value 0 indicates that the item is stretched to fill the entire grid cell. The alignment can be specified as a logical combination of a horizontal alignment (Wt::AlignmentFlag::Left, Wt::AlignmentFlag::Center, or Wt::AlignmentFlag::Right) and a vertical alignment (Wt::AlignmentFlag::Top, Wt::AlignmentFlag::Middle, or Wt::AlignmentFlag::Bottom).

See also
  addWidget(WWidget *, int, int, int, int, WFlags<AlignmentFlag>)

## ◆ columnCount()

int Wt::WGridLayout::columnCount | ( |  | ) | const

Returns the column count.

The grid dimensions change dynamically when adding contents to the grid.

See also
  rowCount()

## ◆ columnIsResizable()

bool Wt::WGridLayout::columnIsResizable | ( | int | column | ) | const

Returns whether the user may drag a particular column border.

This method returns whether the border that separates column column from the next column may be resized by the user.

See also
  setColumnResizable()

## ◆ columnStretch()

int Wt::WGridLayout::columnStretch | ( | int | column | ) | const

Returns the column stretch.

See also
  setColumnStretch(int, int)

## ◆ count()

virtual int Wt::WGridLayout::count | ( |  | ) | const
| overridevirtual

Returns the number of items in this layout.

This may be a theoretical number, which is greater than the actual number of items. It can be used to iterate over the items in the layout, in conjunction with itemAt().

Implements Wt::WLayout.

## ◆ horizontalSpacing()

int Wt::WGridLayout::horizontalSpacing | ( |  | ) | const

Returns the horizontal spacing.

See also
  setHorizontalSpacing(int)

## ◆ itemAt()

virtual WLayoutItem * Wt::WGridLayout::itemAt | ( | int | index | ) | const
| overridevirtual

Returns the layout item at a specific index.

If there is no item at the `index`, `0` is returned.

See also
  indexOf(WLayoutItem *) const, count()

Implements Wt::WLayout.

## ◆ removeItem()

virtual std::unique_ptr< WLayoutItem > Wt::WGridLayout::removeItem | ( | WLayoutItem * | item | ) |
| overridevirtual

Removes a layout item (widget or nested layout).

See also
  addItem(WLayoutItem *), removeWidget(WWidget *)

Implements Wt::WLayout.

## ◆ rowCount()

int Wt::WGridLayout::rowCount | ( |  | ) | const

Returns the row count.

The grid dimensions change dynamically when adding contents to the grid.

See also
  columnCount()

## ◆ rowIsResizable()

bool Wt::WGridLayout::rowIsResizable | ( | int | row | ) | const

Returns whether the user may drag a particular row border.

This method returns whether the border that separates row row from the next row may be resized by the user.

See also
  setRowResizable()

## ◆ rowStretch()

int Wt::WGridLayout::rowStretch | ( | int | row | ) | const

Returns the column stretch.

See also
  setRowStretch(int, int)

## ◆ setColumnResizable()

void Wt::WGridLayout::setColumnResizable | ( | int | column,
|  | bool | enabled = true,
|  | const WLength & | initialSize = WLength::Auto )

Sets whether the user may drag a particular column border.

This method sets whether the border that separates column column from the next column may be resized by the user, depending on the value of enabled.

The default value is false.

If an `initialSize` is given (that is not WLength::Auto), then this size is used for the width of the column, overriding the width it would be given by the layout manager.

## ◆ setColumnStretch()

void Wt::WGridLayout::setColumnStretch | ( | int | column,
|  | int | stretch )

Sets the column stretch.

Sets the stretch factor for column `column`.

See also
  columnStretch()

## ◆ setHorizontalSpacing()

void Wt::WGridLayout::setHorizontalSpacing | ( | int | size | ) |

Sets the horizontal spacing.

The default horizontal spacing is 9 pixels.

See also
  setVerticalSpacing(int)

## ◆ setRowResizable()

void Wt::WGridLayout::setRowResizable | ( | int | row,
|  | bool | enabled = true,
|  | const WLength & | initialSize = WLength::Auto )

Sets whether the user may drag a particular row border.

This method sets whether the border that separates row row from the next row may be resized by the user, depending on the value of enabled.

The default value is false.

If an `initialSize` is given (that is not WLength::Auto), then this size is used for the height of the row, overriding the height it would be given by the layout manager.

## ◆ setRowStretch()

void Wt::WGridLayout::setRowStretch | ( | int | row,
|  | int | stretch )

Sets the row stretch.

Sets the stretch factor for row `row`.

See also
  rowStretch()

## ◆ setVerticalSpacing()

void Wt::WGridLayout::setVerticalSpacing | ( | int | size | ) |

Sets the vertical spacing.

The default vertical spacing is 9 pixels.

See also
  setHorizontalSpacing(int)

## ◆ verticalSpacing()

int Wt::WGridLayout::verticalSpacing | ( |  | ) | const

Returns the vertical spacing.

See also
  setVerticalSpacing(int)