org.zkoss.zul
Class Box

java.lang.Object
  org.zkoss.zk.ui.AbstractComponent
      org.zkoss.zk.ui.HtmlBasedComponent
          org.zkoss.zul.impl.XulElement
              org.zkoss.zul.Box

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, HtmlBasedComponent, Component, Scope, ComponentCtrl, Box, XulElement

Direct Known Subclasses:

Hbox, Vbox

public class Box
extends XulElement
implements Box

A box.

Default getZclass(): z-vbox.(since 3.5.0)

Author:

tomyeh

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class org.zkoss.zk.ui.HtmlBasedComponent

HtmlBasedComponent.ExtraCtrl

Nested classes/interfaces inherited from class org.zkoss.zk.ui.AbstractComponent

AbstractComponent.Children

Field Summary

Fields inherited from class org.zkoss.zk.ui.HtmlBasedComponent

_zclass, RS_NO_DISPLAY, RS_NO_HEIGHT, RS_NO_WIDTH

Fields inherited from class org.zkoss.zk.ui.AbstractComponent

_visible

Fields inherited from interface org.zkoss.zk.ui.Component

APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE

Constructor Summary

Box()
Default: vertical (Vbox).

Box(Component[] children)
Constructor a box by assigning an array of children.

Box(java.lang.String orient)

Box(java.lang.String orient, Component[] children)
Constructor a box by assigning an array of children.

Method Summary

java.lang.String	getAlign() Returns the alignment of cells of a box in the 'opposite' direction (null, start, center, end).
java.lang.String	getCaveAttrs() Returns the attributes used by the 'cave' element (never null).
java.lang.String	getChildInnerAttrs(Component child) Returns the inner attributes used to wrap the children (never null).
java.lang.String	getChildOuterAttrs(Component child) Returns the outer attributes used to wrap the children (never null).
java.lang.String	getHeights() Returns the heights/widths, which is a list of numbers separated by comma to denote the height/width of each cell in a box.
java.lang.String	getOrient() Returns the orient (the same as AbstractComponent.getMold()).
java.lang.String	getOuterAttrs() Returns the exterior attributes for generating the enclosing HTML tag; never return null.
java.lang.String	getPack() Returns the alignment of cells of this box (null, start, center, end).
java.lang.String	getSpacing() Returns the spacing between adjacent children, or null if the default spacing is used.
java.lang.String	getValign() Deprecated. As of release 3.0.0, since it is not compliant to XUL. Use getAlign() and getPack() instead.
java.lang.String	getWidths() Returns the widths/heights, which is a list of numbers separated by comma to denote the width/height of each cell in a box.
java.lang.String	getZclass() Returns the ZK Cascading Style class(es) for this component.
boolean	insertBefore(Component newChild, Component refChild) Inserts a child before the reference child.
boolean	isHorizontal() Returns whether it is a horizontal box.
boolean	isVertical() Returns whether it is a vertical box.
void	onChildRemoved(Component child) Default: does nothing.
void	onDrawNewChild(Component child, java.lang.StringBuffer out) Called when a new-created child is about to render.
void	setAlign(java.lang.String align) Sets the alignment of cells of this box in the 'opposite' direction (null, start, center, end).
void	setHeights(java.lang.String heights) Sets the widths/heights, which is a list of numbers separated by comma to denote the width/height of each cell in a box.
void	setOrient(java.lang.String orient) Sets the orient.
void	setPack(java.lang.String pack) Sets the alignment of cells of this box (null, start, center, end).
void	setSpacing(java.lang.String spacing) Sets the spacing between adjacent children.
void	setValign(java.lang.String valign) Deprecated. As of release 3.0.0, since it is not compliant to XUL. Use setAlign(java.lang.String) and setPack(java.lang.String) instead.
void	setWidths(java.lang.String widths) Sets the widths/heights, which is a list of numbers separated by comma to denote the width/height of each cell in a box.

Methods inherited from class org.zkoss.zul.impl.XulElement

getAction, getActionAttrs, getAllOnClickAttrs, getContext, getCtrlKeys, getInnerAttrs, getPopup, getTooltip, setAction, setContext, setContext, setCtrlKeys, setPopup, setPopup, setTooltip, setTooltip

Methods inherited from class org.zkoss.zk.ui.HtmlBasedComponent

focus, getAllOnClickAttrs, getDraggable, getDroppable, getHeight, getLeft, getMoldSclass, getRealSclass, getRealStyle, getRealStyleFlags, getSclass, getStyle, getTooltiptext, getTop, getWidth, getZindex, getZIndex, newExtraCtrl, redraw, setClass, setDraggable, setDroppable, setFocus, setHeight, setLeft, setMoldSclass, setSclass, setStyle, setTooltiptext, setTop, setWidth, setZclass, setZindex, setZIndex

Methods inherited from class org.zkoss.zk.ui.AbstractComponent

addAnnotation, addAnnotation, addEventHandler, addEventListener, addForward, addForward, addForward, addForward, addMoved, addSharedAnnotationMap, addSharedEventHandlerMap, appendAsapAttr, appendAsapAttr, appendChild, applyProperties, clone, containsVariable, detach, equals, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotation, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttributes, getAttributes, getChildren, getCommand, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getExtraCtrl, getFellow, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getMoldURI, getNamespace, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getUuid, getVariable, hasFellow, invalidate, isAsapRequired, isChildable, isInvalidated, isListenerAvailable, isVisible, newChildren, onChildAdded, onPageAttached, onPageDetached, onWrongValue, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, response, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setComponentDefinition, setId, setMold, setPage, setPageBefore, setParent, setVariable, setVisible, smartUpdate, smartUpdate, smartUpdate, smartUpdateDeferred, smartUpdateValues, toString, unsetVariable

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.zkoss.zul.impl.api.XulElement

getAction, getContext, getCtrlKeys, getPopup, getTooltip, setAction, setContext, setContext, setCtrlKeys, setPopup, setPopup, setTooltip, setTooltip

Methods inherited from interface org.zkoss.zk.ui.api.HtmlBasedComponent

focus, getHeight, getLeft, getSclass, getStyle, getTooltiptext, getTop, getWidth, getZindex, getZIndex, setDraggable, setDroppable, setFocus, setHeight, setLeft, setSclass, setStyle, setTooltiptext, setTop, setWidth, setZclass, setZindex, setZIndex

Methods inherited from interface org.zkoss.zk.ui.Component

addEventListener, addForward, addForward, addForward, addForward, appendChild, applyProperties, clone, containsVariable, detach, getAttribute, getAttribute, getAttributes, getAttributes, getChildren, getDefinition, getDesktop, getFellow, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getNamespace, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getUuid, getVariable, invalidate, isChildable, isInvalidated, isListenerAvailable, isVisible, redraw, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, setAttribute, setAttribute, setId, setMold, setPage, setPageBefore, setParent, setVariable, setVisible, unsetVariable

Constructor Detail

Box

public Box()

Default: vertical (Vbox).

Box

public Box(java.lang.String orient)

Parameters:

orient - either "horizontal" or "vertical".

Box

public Box(Component[] children)

Constructor a box by assigning an array of children.

Parameters:

children - an array of children to be added

Since:

2.4.0

Box

public Box(java.lang.String orient,
           Component[] children)

Constructor a box by assigning an array of children.

Parameters:

children - an array of children to be added

Since:

2.4.0

Method Detail

isHorizontal

public boolean isHorizontal()

Returns whether it is a horizontal box.

Specified by:

isHorizontal in interface Box

Since:

3.0.0

isVertical

public boolean isVertical()

Returns whether it is a vertical box.

Specified by:

isVertical in interface Box

Since:

3.0.0

getOrient

public java.lang.String getOrient()

Returns the orient (the same as AbstractComponent.getMold()).

Default: "vertical".

Specified by:

getOrient in interface Box

setOrient

public void setOrient(java.lang.String orient)
               throws WrongValueException

Sets the orient.

Specified by:

setOrient in interface Box

Parameters:

orient - either "horizontal" or "vertical".

Throws:

WrongValueException

getSpacing

public java.lang.String getSpacing()

Returns the spacing between adjacent children, or null if the default spacing is used.

The default spacing depends on the definition of the style class called "xxx-sp", where xxx is

1. HtmlBasedComponent.getSclass() if it is not null.
2. hbox if HtmlBasedComponent.getSclass() is null and it is a horizontal box.
3. vbox if HtmlBasedComponent.getSclass() is null and it is a vertical box.

Default: null (means to use the default spacing).

Specified by:

getSpacing in interface Box

setSpacing

public void setSpacing(java.lang.String spacing)

Sets the spacing between adjacent children.

Specified by:

setSpacing in interface Box

Parameters:

spacing - the spacing (such as "0", "5px", "3pt" or "1em"), or null to use the default spacing

See Also:

getSpacing()

getValign

public java.lang.String getValign()

Deprecated. As of release 3.0.0, since it is not compliant to XUL. Use getAlign() and getPack() instead.

Returns the vertical alignment of the adjacent cells of a box (top, middle or bottom).

Default: null (i.e., use the browser default, usually middle).

setValign

public void setValign(java.lang.String valign)

Deprecated. As of release 3.0.0, since it is not compliant to XUL. Use setAlign(java.lang.String) and setPack(java.lang.String) instead.

Sets the vertical alignment of the adjacent cells of a box.

Parameters:

valign - the vertical alignment: top, middle and bottom.

getAlign

public java.lang.String getAlign()

Returns the alignment of cells of a box in the 'opposite' direction (null, start, center, end).

Default: start

The align attribute specifies how child elements of the box are aligned, when the size of the box is larger than the total size of the children. For boxes that have horizontal orientation, it specifies how its children will be aligned vertically. For boxes that have vertical orientation, it is used to specify how its children are algined horizontally. The pack attribute (getPack()) is related to the alignment but is used to specify the position in the opposite direction.

start

Child elements are aligned starting from the left or top edge of the box. If the box is larger than the total size of the children, the extra space is placed on the right or bottom side.

center

Extra space is split equally along each side of the child elements, resulting in the children being placed in the center of the box.

end

Child elements are placed on the right or bottom edge of the box. If the box is larger than the total size of the children, the extra space is placed on the left or top side.

Specified by:

getAlign in interface Box

Since:

3.0.0

setAlign

public void setAlign(java.lang.String align)

Sets the alignment of cells of this box in the 'opposite' direction (null, start, center, end).

Specified by:

setAlign in interface Box

Parameters:

align - the alignment in the 'opposite' direction. Allowed values: start, center, end. If empty or null, the browser's default is used (IE center and FF left, if vertical).

Since:

3.0.0

getPack

public java.lang.String getPack()

Returns the alignment of cells of this box (null, start, center, end).

Default: null.

The pack attribute specifies where child elements of the box are placed when the box is larger that the size of the children. For boxes with horizontal orientation, it is used to indicate the position of children horizontally. For boxes with vertical orientation, it is used to indicate the position of children vertically. The align attribute (getAlign())is used to specify the position in the opposite direction.

start

Child elements are aligned starting from the left or top edge of the box. If the box is larger than the total size of the children, the extra space is placed on the right or bottom side.

center

Extra space is split equally along each side of the child elements, resulting in the children being placed in the center of the box.

end

Child elements are placed on the right or bottom edge of the box. If the box is larger than the total size of the children, the extra space is placed on the left or top side.

Specified by:

getPack in interface Box

Since:

3.0.0

setPack

public void setPack(java.lang.String pack)

Sets the alignment of cells of this box (null, start, center, end).

Specified by:

setPack in interface Box

Parameters:

pack - the alignment. Allowed values: start, center, end. If empty or null, the browser's default is used.

Since:

3.0.0

getWidths

public java.lang.String getWidths()

Returns the widths/heights, which is a list of numbers separated by comma to denote the width/height of each cell in a box. If Hbox (i.e., getOrient() is horizontal), it is a list of widths. If Vbox (i.e., getOrient() is vertical), it is a list of heights.

It is the same as getHeights().

Default: empty.

Specified by:

getWidths in interface Box

getHeights

public java.lang.String getHeights()

Returns the heights/widths, which is a list of numbers separated by comma to denote the height/width of each cell in a box. If Hbox (i.e., getOrient() is horizontal), it is a list of widths. If Vbox (i.e., getOrient() is vertical), it is a list of heights.

It is the same as getWidths().

Default: empty.

Specified by:

getHeights in interface Box

setWidths

public void setWidths(java.lang.String widths)
               throws WrongValueException

Sets the widths/heights, which is a list of numbers separated by comma to denote the width/height of each cell in a box.

It is the same as setHeights(java.lang.String).

For example, "10%,20%,30%" means the second cell shall occupy 10% width, the second cell 20%, the third cell 30%, and the following cells don't specify any width.

Note: the splitters are ignored, i.e., they are not cells.

Another example, ",,30%" means the third cell shall occupy 30% width, and the rest of cells don't specify any width. Of course, the real widths depend on the interpretation of the browser.

Specified by:

setWidths in interface Box

Throws:

WrongValueException

setHeights

public void setHeights(java.lang.String heights)
                throws WrongValueException

Sets the widths/heights, which is a list of numbers separated by comma to denote the width/height of each cell in a box.

It is the same as setWidths(java.lang.String).

Specified by:

setHeights in interface Box

Throws:

WrongValueException

getChildOuterAttrs

public java.lang.String getChildOuterAttrs(Component child)

Returns the outer attributes used to wrap the children (never null). It is used only for the vertical layout.

getChildInnerAttrs

public java.lang.String getChildInnerAttrs(Component child)

Returns the inner attributes used to wrap the children (never null). Used only by component development to generate HTML tags.

getOuterAttrs

public java.lang.String getOuterAttrs()

Description copied from class: HtmlBasedComponent

Returns the exterior attributes for generating the enclosing HTML tag; never return null.

Used only by component developers.

Default: Generates the tooltip text, style, sclass, draggable and droppable attribute if necessary. In other words, the corresponding attribute is generated if HtmlBasedComponent.getTooltiptext(), HtmlBasedComponent.getRealStyle(), HtmlBasedComponent.getSclass(), HtmlBasedComponent.getDraggable(), HtmlBasedComponent.getDroppable() are defined.

You have to call both HtmlBasedComponent.getOuterAttrs() and HtmlBasedComponent.getInnerAttrs() to generate complete attributes.

For simple components that all attributes are put on the outest HTML element, all you need is as follows.

<xx id="${self.uuid}"${self.outerAttrs}${self.innerAttrs}>

If you want to put attributes in a nested HTML element, you shall use the following pattern. Notice: if HtmlBasedComponent.getInnerAttrs() in a different tag, the tag must be named with "${self.uuid}!real".

<xx id="${self.uuid}"${self.outerAttrs}>
 <yy id="${self.uuid}!real"${self.innerAttrs}>...

Note: This class handles non-deferrable event listeners automatically. However, you have to invoke AbstractComponent.appendAsapAttr(java.lang.StringBuffer, java.lang.String) for each event the component handles in HtmlBasedComponent.getOuterAttrs() as follows.

        appendAsapAttr(sb, Events.ON_OPEN);
  appendAsapAttr(sb, Events.ON_CHANGE);

Theorectically, you could put any attributes in either HtmlBasedComponent.getInnerAttrs() or HtmlBasedComponent.getOuterAttrs(). However, zkau.js assumes all attributes are put at the outer one. If you want something different, you have to provide your own setAttr (refer to how checkbox is implemented).

Overrides:

getOuterAttrs in class XulElement

getCaveAttrs

public java.lang.String getCaveAttrs()

Returns the attributes used by the 'cave' element (never null). Used only by component development to generate HTML tags.

Since:

3.0.0

getZclass

public java.lang.String getZclass()

Description copied from class: HtmlBasedComponent

Returns the ZK Cascading Style class(es) for this component. It usually depends on the implementation of the mold (@{link #getMold}).

Default: null (the default value depends on element).

HtmlBasedComponent.setZclass(java.lang.String)) will completely replace the default style of a component. In other words, the default style of a component is associated with the default value of HtmlBasedComponent.getZclass(). Once it is changed, the default style won't be applied at all. If you want to perform small adjustments, use HtmlBasedComponent.setSclass(java.lang.String) instead.

Specified by:

getZclass in interface HtmlBasedComponent

Overrides:

getZclass in class HtmlBasedComponent

See Also:

HtmlBasedComponent.getSclass(), HtmlBasedComponent.getRealSclass()

insertBefore

public boolean insertBefore(Component newChild,
                            Component refChild)

Description copied from interface: Component

Inserts a child before the reference child.

You could use Component.setParent(org.zkoss.zk.ui.Component) or Component.appendChild(org.zkoss.zk.ui.Component) instead of this method, unless you want to control where to put the child.

Note: Component.setParent(org.zkoss.zk.ui.Component) always calls back Component.insertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component) and/or Component.removeChild(org.zkoss.zk.ui.Component), while Component.insertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component) and Component.removeChild(org.zkoss.zk.ui.Component) always calls back Component.setParent(org.zkoss.zk.ui.Component), if the parent is changed. Thus, you don't need to override both Component.insertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component) and Component.setParent(org.zkoss.zk.ui.Component), if you want to customize the behavior.

Specified by:

insertBefore in interface Component

Overrides:

insertBefore in class AbstractComponent

Parameters:

newChild - the new child to be inserted.

refChild - the child before which you want the new child being inserted. If null, the new child is append to the end.

Returns:

true if newChild is added successfully or moved; false if it already has the specified child and the order doesn't change.

onChildRemoved

public void onChildRemoved(Component child)

Description copied from class: AbstractComponent

Default: does nothing.

Specified by:

onChildRemoved in interface ComponentCtrl

Overrides:

onChildRemoved in class AbstractComponent

See Also:

ComponentCtrl.onChildRemoved(org.zkoss.zk.ui.Component)

onDrawNewChild

public void onDrawNewChild(Component child,
                           java.lang.StringBuffer out)
                    throws java.io.IOException

Description copied from interface: ComponentCtrl

Called when a new-created child is about to render. It gives the parent a chance to fine-tune the output. Note: it won't be called if the parent is rendered, too. In other words, it is called only if the child is attached dynamically.

It is called in the redrawing phase by the kernel, so it is too late to call Component.invalidate() or ComponentCtrl.smartUpdate(java.lang.String, java.lang.String) in this method.

Note: ComponentCtrl.onChildAdded(org.zkoss.zk.ui.Component) is called in the request-processing phase, while ComponentCtrl.onDrawNewChild(org.zkoss.zk.ui.Component, java.lang.StringBuffer) is called in the redrawing phase. Component developer might do one of the follows:

• Nothing, if new child can be inserted directly.
• Overwrite ComponentCtrl.onDrawNewChild(org.zkoss.zk.ui.Component, java.lang.StringBuffer) to add special tags, if new child needs to be added an exterior with some tags before insertion.
  Morever, if you shall add id="${child.uuid}!chdextr" to the added exterior.
• Redraw the parent, if it is too complicated. How: overwrite ComponentCtrl.onChildAdded(org.zkoss.zk.ui.Component) and calls Component.invalidate()

Specified by:

onDrawNewChild in interface ComponentCtrl

Overrides:

onDrawNewChild in class AbstractComponent

Parameters:

child - the child being rendered

out - the rendered result of the child.

Throws:

java.io.IOException