Wt  3.2.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Public Types | Public Member Functions | List of all members
Wt::WBoxLayout Class Reference

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

#include <Wt/WBoxLayout>

Inheritance diagram for Wt::WBoxLayout:
Inheritance graph
[legend]

Public Types

enum  Direction { LeftToRight, RightToLeft, TopToBottom, BottomToTop }
 Enumeration of the direction in which widgets are layed out. More...

Public Member Functions

 WBoxLayout (Direction dir, WWidget *parent=0)
 Creates a new box layout.
virtual void addItem (WLayoutItem *item)
 Adds a layout item.
virtual void removeItem (WLayoutItem *item)
 Removes a layout item (widget or nested layout).
virtual WLayoutItemitemAt (int index) const
 Returns the layout item at a specific index.
virtual int count () const
 Returns the number of items in this layout.
virtual void clear ()
 Removes and deletes all child widgets and nested layouts.
void setDirection (Direction direction)
 Sets the layout direction.
Direction 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 (WWidget *widget, int stretch=0, WFlags< AlignmentFlag > alignment=0)
 Adds a widget to the layout.
void addLayout (WLayout *layout, int stretch=0, WFlags< AlignmentFlag > alignment=0)
 Adds a nested layout to the layout.
void addSpacing (const WLength &size)
 Adds extra spacing.
void addStretch (int stretch=0)
 Adds a stretch element.
void insertWidget (int index, WWidget *widget, int stretch=0, WFlags< AlignmentFlag > alignment=0)
 Inserts a widget in the layout.
void insertLayout (int index, WLayout *layout, int stretch=0, WFlags< AlignmentFlag > alignment=0)
 Inserts a nested layout in the layout.
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)
 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 addWidget (WWidget *widget)
 Adds the given widget to the layout.
bool removeWidget (WWidget *widget)
 Removes the given widget from the layout.
virtual int indexOf (WLayoutItem *item) const
 Returns the index of a given item.
virtual WWidgetItemfindWidgetItem (WWidget *widget)
 Finds the widget item associated with the given widget.
void setLayoutHint (const std::string &name, const std::string &value)
 Provides a hint to the layout implementation.
virtual WWidgetwidget ()
 Returns the widget that is held by this WLayoutItem.
virtual WLayoutlayout ()
 Returns the layout that implements this WLayoutItem.
virtual WLayoutparentLayout () const
 Returns the layout in which this item is contained.
WLayoutItemImplimpl () const
 Returns the implementation for this layout item.
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
 WObject (WObject *parent=0)
 Create a WObject with a given parent object.
virtual ~WObject ()
 Destructor.
virtual const std::string id () const
 Returns the (unique) identifier for this object.
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.
template<class T >
WStatelessSlot * implementJavaScript (void(T::*method)(), const std::string &jsCode)
 Provides a JavaScript implementation for a method.
void addChild (WObject *child)
 Adds a child object.
virtual void removeChild (WObject *child)
 Removes a child object.
const std::vector< WObject * > & children () const
 Returns the children.
WObjectparent () const
 Returns the parent object.

Additional Inherited Members

- Protected Member Functions inherited from Wt::WLayout
 WLayout ()
 Create a layout.
void update (WLayoutItem *item=0)
 Update the layout.
void updateAddItem (WLayoutItem *item)
 Update the layout, adding the given layout item.
void updateRemoveItem (WLayoutItem *item)
 Update the layout, remove the given layout item.
void setLayoutInParent (WWidget *parent)
 Set the layout in the parent.
- Static Protected Member Functions inherited from Wt::WObject
static WObjectsender ()
 Returns the sender of the current slot call.

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 widgets is given its minimum size, and remaining space is divided according to stretch factors among the widgets. The widget minimum height or width is used for sizing each widget, whose default values may be overridden using WWidget::setMinimumSize().

If you want to use the layout manager for a container which does not have a height that is constrained somehow, you need to specify AlignTop in the alignment flags of WContainerWidget::setLayout(). Otherwise the behavior is undefined (the parent container will continue to increase in size as it tries to satisfy the constraints assuming a contrained height).

You can use WContainerWidget::setOverflow(OverflowAuto) or use a WScrollArea to automatically show scrollbars on a widget inserted in the layout.

A caveat with layout managers is that you cannot reliably use a stylesheet to add borders (or margin) to a widget inserted in a layout: this is broken on Internet Explorer. To provide the layout, the layout manager needs to set sizes on the contained widget but these sizes also need to take into account the border/margin width. Since on IE, this value will be 0 if the border or margin is provided by a stylesheet (as opposed to by inline CSS by using WWidget::decorationStyle()), the result will be wrong behaviour like widgets that keep growing in size.

Another caveat with a layout manager is that the size of contained images may change when the image is being loaded (which happens in the background by the browser). This may result in a wrong layout since the layout manager should relayout. Therefore, you should avoid images inside a layout, or make sure that the image size does not change when the image is being loaded (this will also improve the user experience), by setting its size.

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()). Resize handles between rows for a vertically oriented box layout only work when the layout fills the parent vertical space (i.e. is not aligned to the top). Likewise, resize handles between columns for a horizontally oriented box layout only work when the layout fills the parent horiziontal space (i.e. is not aligned left, right or centered).

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, which thus replaces padding defined for the container. This margin defaults to 9 pixels, and can be changed using setContentsMargins(). It is not allowed to define padding for the container widget using its CSS 'padding' property or the WContainerWidget::setPadding(). 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:

w->resize(WLength(), 600);
layout->addWidget(new Wt::WText("One"));
layout->addWidget(new Wt::WText("Two"));
layout->addWidget(new Wt::WText("Three"));
layout->addWidget(new Wt::WText("Four"));
w->setLayout(layout);
Note
This layout manager is applicable only to WContainerWidget container widgets. You may use it within an Ext::Container indirectly by first setting a WContainerWidget using a WFitLayout.
When JavaScript support is not available, only Safari and Firefox properly implement this box layout. For other browsers, only the horizontal layout is properly implemented, while vertically all widgets use their minimum size.
When set on a WContainerWidget, this layout manager accepts the following hints (see setLayoutHint()):
  • "table-layout" with possible values "auto" (default) or "fixed".
    Use "fixed" to prevent nested tables from overflowing the layout. In that case, you will need to specify a width (in CSS or otherwise) for at least one item in every column that has no stretch factor.

Member Enumeration Documentation

Enumeration of the direction in which widgets are layed out.

Enumerator:
LeftToRight 

Horizontal layout, widgets are arranged from left to right.

RightToLeft 

Horizontal layout, widgets are arranged from right to left.

TopToBottom 

Vertical layout, widgets are arranged from top to bottom.

BottomToTop 

Vertical layout, widgets are arranged from bottom to top.

Constructor & Destructor Documentation

Wt::WBoxLayout::WBoxLayout ( Direction  dir,
WWidget parent = 0 
)

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

void Wt::WBoxLayout::addItem ( WLayoutItem item)
virtual

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.

void Wt::WBoxLayout::addLayout ( WLayout layout,
int  stretch = 0,
WFlags< AlignmentFlag alignment = 0 
)

Adds a nested layout to the layout.

Adds a nested layout, with given stretch factor.

See Also
addWidget(WWidget *, int, WFlags<AlignmentFlag>), insertLayout()
void Wt::WBoxLayout::addSpacing ( const WLength size)

Adds extra spacing.

Adds extra spacing to the layout.

See Also
addStretch(), insertStretch()
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()
void Wt::WBoxLayout::addWidget ( WWidget widget,
int  stretch = 0,
WFlags< AlignmentFlag alignment = 0 
)

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). You may use a special stretch factor of -1 to indicate that the widget should not take excess space but the contents height should still be actively managed. This may make sense for example if the widget is layout size aware).

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::AlignLeft, Wt::AlignCenter, or Wt::AlignRight) and a vertical alignment (Wt::AlignTop, Wt::AlignMiddle, or Wt::AlignBottom).

See Also
addLayout(), insertWidget()
void Wt::WBoxLayout::clear ( )
virtual

Removes and deletes all child widgets and nested layouts.

This is similar to WContainerWidget::clear(), with the exception that the layout itself is not deleted.

Implements Wt::WLayout.

int Wt::WBoxLayout::count ( ) const
virtual

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 Wt::WBoxLayout::direction ( ) const

Returns the layout direction.

See Also
setDirection()
void Wt::WBoxLayout::insertLayout ( int  index,
WLayout layout,
int  stretch = 0,
WFlags< AlignmentFlag alignment = 0 
)

Inserts a nested layout in the layout.

Inserts a nested layout in the layout at positionindex, with given stretch factor.

See Also
insertWidget(), addLayout()
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()
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()
void Wt::WBoxLayout::insertWidget ( int  index,
WWidget widget,
int  stretch = 0,
WFlags< AlignmentFlag alignment = 0 
)

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). You may use a special stretch factor of -1 to indicate that the widget should not take excess space but the contents height should still be actively managed. This may make sense for example if the widget is layout size aware).

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::AlignLeft, Wt::AlignCenter, or Wt::AlignRight) and a vertical alignment (Wt::AlignTop, Wt::AlignMiddle, or Wt::AlignBottom).

See Also
insertLayout(), addWidget(WWidget *, int, WFlags<AlignmentFlag>)
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()
WLayoutItem * Wt::WBoxLayout::itemAt ( int  index) const
virtual

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.

void Wt::WBoxLayout::removeItem ( WLayoutItem item)
virtual

Removes a layout item (widget or nested layout).

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

Implements Wt::WLayout.

void Wt::WBoxLayout::setDirection ( Direction  direction)

Sets the layout direction.

See Also
direction()
void Wt::WBoxLayout::setResizable ( int  index,
bool  enabled = true 
)

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.

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

Sets spacing between each item.

The default spacing is 6 pixels.

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.

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.

int Wt::WBoxLayout::spacing ( ) const

Returns the spacing between each item.

See Also
setSpacing()

Generated on Wed Oct 22 2014 for the C++ Web Toolkit (Wt) by doxygen 1.8.1.2