eu.webtoolkit.jwt
Class WBoxLayout

java.lang.Object
  eu.webtoolkit.jwt.WObject
      eu.webtoolkit.jwt.WLayout
          eu.webtoolkit.jwt.WBoxLayout

All Implemented Interfaces:

WLayoutItem

Direct Known Subclasses:

WHBoxLayout, WVBoxLayout

public class WBoxLayout
extends WLayout

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#getDecorationStyle()), 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 WLayout#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.

Note: 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 WLayout#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.

Nested Class Summary

static class

WBoxLayout.Direction Enumeration of the direction in which widgets are layed out.

Constructor Summary

WBoxLayout(WBoxLayout.Direction dir)
Creates a new box layout.

WBoxLayout(WBoxLayout.Direction dir, WWidget parent)
Creates a new box layout.

Method Summary

void	addItem(WLayoutItem item) Adds a layout item.
void	addLayout(WLayout layout) Adds a nested layout to the layout.
void	addLayout(WLayout layout, int stretch) Adds a nested layout to the layout.
void	addLayout(WLayout layout, int stretch, AlignmentFlag alignmen, AlignmentFlag... alignment) Adds a nested layout to the layout.
void	addLayout(WLayout layout, int stretch, java.util.EnumSet<AlignmentFlag> alignment) Adds a nested layout to the layout.
void	addSpacing(WLength size) Adds extra spacing.
void	addStretch() Adds a stretch element.
void	addStretch(int stretch) Adds a stretch element.
void	addWidget(WWidget widget) Adds a widget to the layout.
void	addWidget(WWidget widget, int stretch) Adds a widget to the layout.
void	addWidget(WWidget widget, int stretch, AlignmentFlag alignmen, AlignmentFlag... alignment) Adds a widget to the layout.
void	addWidget(WWidget widget, int stretch, java.util.EnumSet<AlignmentFlag> alignment) Adds a widget to the layout.
void	clear() Removes and deletes all child widgets and nested layouts.
int	getCount() Returns the number of items in this layout.
WBoxLayout.Direction	getDirection() Returns the layout direction.
WLayoutItem	getItemAt(int index) Returns the layout item at a specific index.
int	getSpacing() Returns the spacing between each item.
protected void	insertItem(int index, WLayoutItem item, int stretch, AlignmentFlag alignmen, AlignmentFlag... alignment)
protected void	insertItem(int index, WLayoutItem item, int stretch, java.util.EnumSet<AlignmentFlag> alignment)
void	insertLayout(int index, WLayout layout) Inserts a nested layout in the layout.
void	insertLayout(int index, WLayout layout, int stretch) Inserts a nested layout in the layout.
void	insertLayout(int index, WLayout layout, int stretch, AlignmentFlag alignmen, AlignmentFlag... alignment) Inserts a nested layout in the layout.
void	insertLayout(int index, WLayout layout, int stretch, java.util.EnumSet<AlignmentFlag> alignment) Inserts a nested layout in the layout.
void	insertSpacing(int index, WLength size) Inserts extra spacing in the layout.
void	insertStretch(int index) Inserts a stretch element in the layout.
void	insertStretch(int index, int stretch) Inserts a stretch element in the layout.
void	insertWidget(int index, WWidget widget) Inserts a widget in the layout.
void	insertWidget(int index, WWidget widget, int stretch) Inserts a widget in the layout.
void	insertWidget(int index, WWidget widget, int stretch, AlignmentFlag alignmen, AlignmentFlag... alignment) Inserts a widget in the layout.
void	insertWidget(int index, WWidget widget, int stretch, java.util.EnumSet<AlignmentFlag> alignment) Inserts a widget in the layout.
boolean	isResizable(int index) Returns whether the user may drag a particular border.
void	removeItem(WLayoutItem item) Removes a layout item (widget or nested layout).
void	setDirection(WBoxLayout.Direction direction) Sets the layout direction.
void	setResizable(int index) Sets whether the use may drag a particular border.
void	setResizable(int index, boolean enabled) Sets whether the use may drag a particular border.
void	setSpacing(int size) Sets spacing between each item.
boolean	setStretchFactor(WLayout layout, int stretch) Sets the stretch factor for a nested layout.
boolean	setStretchFactor(WWidget widget, int stretch) Sets the stretch factor for a widget.

Methods inherited from class eu.webtoolkit.jwt.WLayout

clearLayoutItem, findWidgetItem, getContentsMargin, getImpl, getLayout, getParentLayout, getWidget, indexOf, removeWidget, setContentsMargins, setLayoutHint, setLayoutInParent, setParentLayout, setParentWidget, update, update, updateAddItem, updateRemoveItem

Methods inherited from class eu.webtoolkit.jwt.WObject

addChild, getId, getObjectName, remove, setObjectName, tr

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

WBoxLayout

public WBoxLayout(WBoxLayout.Direction dir,
                  WWidget parent)

Creates a new box layout.

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

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

WBoxLayout

public WBoxLayout(WBoxLayout.Direction dir)

Creates a new box layout.

Calls this(dir, (WWidget)null)

Method Detail

addItem

public void addItem(WLayoutItem item)

Description copied from class: WLayout

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.

Specified by:

addItem in class WLayout

See Also:

WLayout.removeItem(WLayoutItem item), WLayout.addWidget(WWidget w)

removeItem

public void removeItem(WLayoutItem item)

Description copied from class: WLayout

Removes a layout item (widget or nested layout).

Specified by:

removeItem in class WLayout

See Also:

WLayout.addItem(WLayoutItem item), WLayout.removeWidget(WWidget w)

getItemAt

public WLayoutItem getItemAt(int index)

Description copied from class: WLayout

Returns the layout item at a specific index.

If there is no item at the index, null is returned.

Specified by:

getItemAt in class WLayout

See Also:

WLayout.indexOf(WLayoutItem item), WLayout.getCount()

getCount

public int getCount()

Description copied from class: WLayout

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 getItemAt().

Specified by:

getCount in class WLayout

clear

public void clear()

Description copied from class: WLayout

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.

Specified by:

clear in class WLayout

setDirection

public void setDirection(WBoxLayout.Direction direction)

Sets the layout direction.

See Also:

getDirection()

getDirection

public WBoxLayout.Direction getDirection()

Returns the layout direction.

See Also:

setDirection(WBoxLayout.Direction direction)

setSpacing

public void setSpacing(int size)

Sets spacing between each item.

The default spacing is 6 pixels.

getSpacing

public int getSpacing()

Returns the spacing between each item.

See Also:

setSpacing(int size)

addWidget

public void addWidget(WWidget widget,
                      int stretch,
                      java.util.EnumSet<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). 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 ( AlignmentFlag.AlignLeft, AlignmentFlag.AlignCenter, or AlignmentFlag.AlignRight) and a vertical alignment ( AlignmentFlag.AlignTop, AlignmentFlag.AlignMiddle, or AlignmentFlag.AlignBottom).

See Also:

addLayout(WLayout layout, int stretch, EnumSet alignment), insertWidget(int index, WWidget widget, int stretch, EnumSet alignment)

addWidget

public final void addWidget(WWidget widget,
                            int stretch,
                            AlignmentFlag alignmen,
                            AlignmentFlag... alignment)

Adds a widget to the layout.

Calls addWidget(widget, stretch, EnumSet.of(alignmen, alignment))

addWidget

public final void addWidget(WWidget widget)

Adds a widget to the layout.

Calls addWidget(widget, 0, EnumSet.noneOf(AlignmentFlag.class))

Overrides:

addWidget in class WLayout

See Also:

WLayout.removeWidget(WWidget w), WLayout.addItem(WLayoutItem item)

addWidget

public final void addWidget(WWidget widget,
                            int stretch)

Adds a widget to the layout.

Calls addWidget(widget, stretch, EnumSet.noneOf(AlignmentFlag.class))

addLayout

public void addLayout(WLayout layout,
                      int stretch,
                      java.util.EnumSet<AlignmentFlag> alignment)

Adds a nested layout to the layout.

Adds a nested layout, with given stretch factor.

See Also:

addWidget(WWidget widget, int stretch, EnumSet alignment), insertLayout(int index, WLayout layout, int stretch, EnumSet alignment)

addLayout

public final void addLayout(WLayout layout,
                            int stretch,
                            AlignmentFlag alignmen,
                            AlignmentFlag... alignment)

Adds a nested layout to the layout.

Calls addLayout(layout, stretch, EnumSet.of(alignmen, alignment))

addLayout

public final void addLayout(WLayout layout)

Adds a nested layout to the layout.

Calls addLayout(layout, 0, EnumSet.noneOf(AlignmentFlag.class))

addLayout

public final void addLayout(WLayout layout,
                            int stretch)

Adds a nested layout to the layout.

Calls addLayout(layout, stretch, EnumSet.noneOf(AlignmentFlag.class))

addSpacing

public void addSpacing(WLength size)

Adds extra spacing.

Adds extra spacing to the layout.

See Also:

addStretch(int stretch), insertStretch(int index, int stretch)

addStretch

public void addStretch(int stretch)

Adds a stretch element.

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

See Also:

addSpacing(WLength size), insertStretch(int index, int stretch)

addStretch

public final void addStretch()

Adds a stretch element.

Calls addStretch(0)

insertWidget

public void insertWidget(int index,
                         WWidget widget,
                         int stretch,
                         java.util.EnumSet<AlignmentFlag> alignment)

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

See Also:

insertLayout(int index, WLayout layout, int stretch, EnumSet alignment), addWidget(WWidget widget, int stretch, EnumSet alignment)

insertWidget

public final void insertWidget(int index,
                               WWidget widget,
                               int stretch,
                               AlignmentFlag alignmen,
                               AlignmentFlag... alignment)

Inserts a widget in the layout.

Calls insertWidget(index, widget, stretch, EnumSet.of(alignmen, alignment))

insertWidget

public final void insertWidget(int index,
                               WWidget widget)

Inserts a widget in the layout.

Calls insertWidget(index, widget, 0, EnumSet.noneOf(AlignmentFlag.class))

insertWidget

public final void insertWidget(int index,
                               WWidget widget,
                               int stretch)

Inserts a widget in the layout.

Calls insertWidget(index, widget, stretch, EnumSet.noneOf(AlignmentFlag.class))

insertLayout

public void insertLayout(int index,
                         WLayout layout,
                         int stretch,
                         java.util.EnumSet<AlignmentFlag> alignment)

Inserts a nested layout in the layout.

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

See Also:

insertWidget(int index, WWidget widget, int stretch, EnumSet alignment), addLayout(WLayout layout, int stretch, EnumSet alignment)

insertLayout

public final void insertLayout(int index,
                               WLayout layout,
                               int stretch,
                               AlignmentFlag alignmen,
                               AlignmentFlag... alignment)

Inserts a nested layout in the layout.

Calls insertLayout(index, layout, stretch, EnumSet.of(alignmen, alignment))

insertLayout

public final void insertLayout(int index,
                               WLayout layout)

Inserts a nested layout in the layout.

Calls insertLayout(index, layout, 0, EnumSet.noneOf(AlignmentFlag.class))

insertLayout

public final void insertLayout(int index,
                               WLayout layout,
                               int stretch)

Inserts a nested layout in the layout.

Calls insertLayout(index, layout, stretch, EnumSet.noneOf(AlignmentFlag.class))

insertSpacing

public void insertSpacing(int index,
                          WLength size)

Inserts extra spacing in the layout.

Inserts extra spacing in the layout at position index.

See Also:

insertStretch(int index, int stretch), addSpacing(WLength size)

insertStretch

public void insertStretch(int index,
                          int stretch)

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(int index, WLength size), addStretch(int stretch)

insertStretch

public final void insertStretch(int index)

Inserts a stretch element in the layout.

Calls insertStretch(index, 0)

setStretchFactor

public boolean 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

public boolean 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.

setResizable

public void setResizable(int index,
                         boolean enabled)

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.

setResizable

public final void setResizable(int index)

Sets whether the use may drag a particular border.

Calls setResizable(index, true)

isResizable

public boolean isResizable(int index)

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(int index, boolean enabled)

insertItem

protected void insertItem(int index,
                          WLayoutItem item,
                          int stretch,
                          java.util.EnumSet<AlignmentFlag> alignment)

insertItem

protected final void insertItem(int index,
                                WLayoutItem item,
                                int stretch,
                                AlignmentFlag alignmen,
                                AlignmentFlag... alignment)