Wt: Wt::WBoxLayout Class Reference

Wt 4.10.4

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

A layout manager which arranges widgets horizontally or vertically. More...

`#include <Wt/WBoxLayout.h>`

Inheritance diagram for Wt::WBoxLayout:
[legend]

## Public Member Functions
| WBoxLayout (LayoutDirection dir)
| Creates a new box 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 | setDirection (LayoutDirection direction)
| Sets the layout direction.
LayoutDirection | direction () const
| Returns the layout direction.
void | setSpacing (int size)
| Sets spacing between each item.
int | spacing () const
| Returns the spacing between each item.
void | addWidget (std::unique_ptr< WWidget > widget, int stretch, WFlags< AlignmentFlag > alignment)
| Adds a widget to the layout.
template<typename Widget >
Widget * | addWidget (std::unique_ptr< Widget > widget, int stretch=0, WFlags< AlignmentFlag > alignment=None)
| Adds a widget to the layout, returning a raw pointer.
void | addLayout (std::unique_ptr< WLayout > layout, int stretch, WFlags< AlignmentFlag > alignment)
| Adds a nested layout to the layout.
template<typename Layout >
Layout * | addLayout (std::unique_ptr< Layout > layout, int stretch=0, WFlags< AlignmentFlag > alignment=None)
void | addSpacing (const WLength &size)
| Adds extra spacing.
void | addStretch (int stretch=0)
| Adds a stretch element.
void | insertWidget (int index, std::unique_ptr< WWidget > widget, int stretch=0, WFlags< AlignmentFlag > alignment=None)
| Inserts a widget in the layout.
template<typename Widget >
Widget * | insertWidget (int index, std::unique_ptr< Widget > widget, int stretch=0, WFlags< AlignmentFlag > alignment=None)
| Inserts a widget in the layout, returning a raw pointer.
void | insertLayout (int index, std::unique_ptr< WLayout > layout, int stretch=0, WFlags< AlignmentFlag > alignment=None)
| Inserts a nested layout in the layout.
template<typename Layout >
Layout * | insertLayout (int index, std::unique_ptr< Layout > layout, int stretch=0, WFlags< AlignmentFlag > alignment=None)
void | insertSpacing (int index, const WLength &size)
| Inserts extra spacing in the layout.
void | insertStretch (int index, int stretch=0)
| Inserts a stretch element in the layout.
bool | setStretchFactor (WLayout *layout, int stretch)
| Sets the stretch factor for a nested layout.
bool | setStretchFactor (WWidget *widget, int stretch)
| Sets the stretch factor for a widget.
void | setResizable (int index, bool enabled=true, const WLength &initialSize=WLength::Auto)
| Sets whether the use may drag a particular border.
bool | isResizable (int index) const
| Returns whether the user may drag a particular 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 horizontally or vertically.

This layout manager arranges widgets horizontally or vertically inside the parent container.

The space is divided so that each widget is given its preferred size, and remaining space is divided according to stretch factors among widgets. If not all widgets can be given their preferred size (there is not enough room), then widgets are given a smaller size (down to their minimum size). If necessary, the container (or parent layout) of this layout is resized to meet minimum size requirements.

The preferred width or height of a widget is based on its natural size, where it presents its contents without overflowing. WWidget::resize() or (CSS `width`, `height` properties) can be used to adjust the preferred size of a widget.

The minimum width or height of a widget is based on the minimum dimensions of the widget or the nested layout. The default minimum height or width for a widget is 0. It can be specified using WWidget::setMinimumSize() or using CSS `min-width` or `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 does not have a defined size (by having an explicit size, or by being inside a layout manager), or has has only 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. Note that because of the CSS defaults, a WContainer has by default no height, but inherits the width of its parent widget. The width is thus by default defined.

A layout manager may provide resize handles between items which allow the user to change the automatic layout provided by the layout manager (see setResizable()).

Each item is separated using a constant spacing, which defaults to 6 pixels, and can be changed using setSpacing(). 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(). You can add more space between two widgets using addSpacing().

For each item a stretch factor may be defined, which controls how remaining space is used. Each item is stretched using the stretch factor to fill the remaining space.

Usage example:

Wt::WContainerWidget *w = addWidget(std::make_unique<Wt::WContainerWidget>());
w->resize(Wt::WLength(), 600);
auto layout = std::make_unique<Wt::WBoxLayout>(Wt::LayoutDirection::TopToBottom);
layout->addWidget(std::make_unique<Wt::WText>("One"));
layout->addWidget(std::make_unique<Wt::WText>("Two"));
layout->addWidget(std::make_unique<Wt::WText>("Three"));
layout->addWidget(std::make_unique<Wt::WText>("Four"));
w->setLayout(std::move(layout));
Wt::WBoxLayout::addWidget
void addWidget(std::unique_ptr< WWidget > widget, int stretch, WFlags< AlignmentFlag > alignment)
Adds a widget to the 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::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
A value class that describes a CSS length.
Definition WLength.h:56
Wt::WWebWidget::resize
virtual void resize(const WLength &width, const WLength &height) override
Resizes the widget.
Wt::LayoutDirection::TopToBottom
@ TopToBottom
Top-to-bottom layout.

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

## ◆ WBoxLayout()

Wt::WBoxLayout::WBoxLayout | ( | LayoutDirection | dir | ) |

Creates a new box layout.

This constructor is rarely used. Instead, use the convenient constructors of the specialized WHBoxLayout or WVBoxLayout classes.

Use `parent` = `0` to created a layout manager that can be nested inside other layout managers.

## Member Function Documentation

## ◆ addItem()

virtual void Wt::WBoxLayout::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.

## ◆ addLayout() [1/2]

template<typename Layout >

Layout * Wt::WBoxLayout::addLayout | ( | std::unique_ptr< Layout > | layout,
|  | int | stretch = 0,
|  | WFlags< AlignmentFlag > | alignment = None )

\briefs Adds a nested layout to the layout, returning a raw pointer.

This is implemented as:

Layout *result = layout.get();
addLayout(std::unique_ptr<WLayout>(std::move(layout)), stretch, alignment);
return result;
Wt::WBoxLayout::addLayout
void addLayout(std::unique_ptr< WLayout > layout, int stretch, WFlags< AlignmentFlag > alignment)
Adds a nested layout to the layout.

## ◆ addLayout() [2/2]

void Wt::WBoxLayout::addLayout | ( | std::unique_ptr< WLayout > | layout,
|  | int | stretch,
|  | WFlags< AlignmentFlag > | alignment )

Adds a nested layout to the layout.

Adds a nested layout, with given `stretch` factor.

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

## ◆ addSpacing()

void Wt::WBoxLayout::addSpacing | ( | const WLength & | size | ) |

Adds extra spacing.

Adds extra spacing to the layout.

See also
  addStretch(), insertStretch()

## ◆ addStretch()

void Wt::WBoxLayout::addStretch | ( | int | stretch = 0 | ) |

Adds a stretch element.

Adds a stretch element to the layout. This adds an empty space that stretches as needed.

See also
  addSpacing(), insertStretch()

## ◆ addWidget() [1/2]

template<typename Widget >

Widget * Wt::WBoxLayout::addWidget | ( | std::unique_ptr< Widget > | widget,
|  | int | stretch = 0,
|  | WFlags< AlignmentFlag > | alignment = None )

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

This is implemented as:

Widget *result = widget.get();
addWidget(std::unique_ptr<WWidget>(std::move(widget)), stretch, 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/2]

void Wt::WBoxLayout::addWidget | ( | std::unique_ptr< WWidget > | widget,
|  | int | stretch,
|  | WFlags< AlignmentFlag > | alignment )

Adds a widget to the layout.

Adds a widget to the layout, with given `stretch` factor. When the stretch factor is 0, the widget will not be resized by the layout manager (stretched to take excess space).

The `alignment` parameter is a combination of a horizontal and/or a vertical AlignmentFlag OR'ed together.

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 column or row. 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(), insertWidget()

## ◆ count()

virtual int Wt::WBoxLayout::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.

## ◆ direction()

LayoutDirection Wt::WBoxLayout::direction | ( |  | ) | const

Returns the layout direction.

See also
  setDirection()

## ◆ insertLayout() [1/2]

template<typename Layout >

Layout * Wt::WBoxLayout::insertLayout | ( | int | index,
|  | std::unique_ptr< Layout > | layout,
|  | int | stretch = 0,
|  | WFlags< AlignmentFlag > | alignment = None )

\briefs Inserts a nested layout in the layout, returning a raw pointer.

This is implemented as:

Layout *result = layout.get();
addLayout(index, std::unique_ptr<WLayout>(std::move(layout)), stretch, alignment);
return result;

## ◆ insertLayout() [2/2]

void Wt::WBoxLayout::insertLayout | ( | int | index,
|  | std::unique_ptr< WLayout > | layout,
|  | int | stretch = 0,
|  | WFlags< AlignmentFlag > | alignment = None )

Inserts a nested layout in the layout.

Inserts a nested layout in the layout at position`index`, with given `stretch` factor.

See also
  insertWidget(), addLayout()

## ◆ insertSpacing()

void Wt::WBoxLayout::insertSpacing | ( | int | index,
|  | const WLength & | size )

Inserts extra spacing in the layout.

Inserts extra spacing in the layout at position `index`.

See also
  insertStretch(), addSpacing()

## ◆ insertStretch()

void Wt::WBoxLayout::insertStretch | ( | int | index,
|  | int | stretch = 0 )

Inserts a stretch element in the layout.

Inserts a stretch element in the layout at position `index`. This adds an empty space that stretches as needed.

See also
  insertSpacing(), addStretch()

## ◆ insertWidget() [1/2]

template<typename Widget >

Widget * Wt::WBoxLayout::insertWidget | ( | int | index,
|  | std::unique_ptr< Widget > | widget,
|  | int | stretch = 0,
|  | WFlags< AlignmentFlag > | alignment = None )

Inserts a widget in the layout, returning a raw pointer.

This is implemented as:

Widget *result = widget.get();
insertWidget(index, std::unique_ptr<WWidget>(std::move(widget)), stretch, alignment);
return result;
Wt::WBoxLayout::insertWidget
void insertWidget(int index, std::unique_ptr< WWidget > widget, int stretch=0, WFlags< AlignmentFlag > alignment=None)
Inserts a widget in the layout.

## ◆ insertWidget() [2/2]

void Wt::WBoxLayout::insertWidget | ( | int | index,
|  | std::unique_ptr< WWidget > | widget,
|  | int | stretch = 0,
|  | WFlags< AlignmentFlag > | alignment = None )

Inserts a widget in the layout.

Inserts a widget in the layout at position `index`, with given `stretch` factor. When the stretch factor is 0, the widget will not be resized by the layout manager (stretched to take excess space).

The `alignment` specifies the vertical and horizontal alignment of the item. The default value None indicates that the item is stretched to fill the entire column or row. 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::AlignBottom).

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

## ◆ isResizable()

bool Wt::WBoxLayout::isResizable | ( | int | index | ) | const

Returns whether the user may drag a particular border.

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

See also
  setResizable()

## ◆ itemAt()

virtual WLayoutItem * Wt::WBoxLayout::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::WBoxLayout::removeItem | ( | WLayoutItem * | item | ) |
| overridevirtual

Removes a layout item (widget or nested layout).

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

Implements Wt::WLayout.

## ◆ setDirection()

void Wt::WBoxLayout::setDirection | ( | LayoutDirection | direction | ) |

Sets the layout direction.

Note
  Changing the layout direction after something (a widget or nested layout) has been added is not supported.

See also
  direction()

## ◆ setResizable()

void Wt::WBoxLayout::setResizable | ( | int | index,
|  | bool | enabled = true,
|  | const WLength & | initialSize = WLength::Auto )

Sets whether the use may drag a particular border.

This method sets whether the border that separates item index from the next item 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 size of the item, overriding the size it would be given by the layout manager.

## ◆ setSpacing()

void Wt::WBoxLayout::setSpacing | ( | int | size | ) |

Sets spacing between each item.

The default spacing is 6 pixels.

## ◆ setStretchFactor() [1/2]

bool Wt::WBoxLayout::setStretchFactor | ( | WLayout * | layout,
|  | int | stretch )

Sets the stretch factor for a nested layout.

The `layout` must have previously been added to this layout using insertLayout() or addLayout().

Returns whether the `stretch` could be set.

## ◆ setStretchFactor() [2/2]

bool Wt::WBoxLayout::setStretchFactor | ( | WWidget * | widget,
|  | int | stretch )

Sets the stretch factor for a widget.

The `widget` must have previously been added to this layout using insertWidget() or addWidget().

Returns whether the `stretch` could be set.

## ◆ spacing()

int Wt::WBoxLayout::spacing | ( |  | ) | const

Returns the spacing between each item.

See also
  setSpacing()