org.zkoss.zul
Class Panel

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

All Implemented Interfaces:

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

public class Panel
extends XulElement
implements Panel

Panel is a container that has specific functionality and structural components that make it the perfect building block for application-oriented user interfaces. The Panel contains bottom, top, and foot toolbars, along with separate header, footer and body sections. It also provides built-in collapsible, closable, maximizable, and minimizable behavior, along with a variety of pre-built tool buttons that can be wired up to provide other customized behavior. Panels can be easily embedded into any kind of ZUL component that is allowed to have children or layout component. Panels also provide specific features like float and move. Unlike Window, Panels can only be floated and moved inside its parent node, which is not using zk.setVParent() function at client side. In other words, if Panel's parent node is an relative position, the floated panel is only inside its parent, not the whole page. The second difference of Window is that Panel is not an independent ID space (by implementing IdSpace), so the ID of each child can be used throughout the panel.

Events:
onMove, onOpen, onZIndex, onMaximize, onMinimize, and onClose.

Default getZclass(): z-panel.

Since:

3.5.0

Author:

jumperchen

See Also:

Serialized Form

Nested Class Summary

protected class

Panel.ExtraCtrl A utility class to implement AbstractComponent.getExtraCtrl().

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

Panel()

Method Summary

protected void	addMoved(Component oldparent, Page oldpg, Page newpg) Called when this component is moved from the specified parent and/or page to the new page.
boolean	addToolbar(java.lang.String name, Toolbar toolbar) Adds the toolbar of the panel by these names, "tbar", "bbar", and "fbar".
boolean	addToolbarApi(java.lang.String name, Toolbar toolbarApi) Adds the toolbar of the panel by these names, "tbar", "bbar", and "fbar".
java.lang.Object	clone() Clones the component.
java.lang.String	getBorder() Returns the border.
Toolbar	getBottomToolbar() Returns the bottom toolbar of this panel.
Toolbar	getBottomToolbarApi() Returns the bottom toolbar of this panel.
Caption	getCaption() Returns the caption of this panel.
Caption	getCaptionApi() Returns the caption of this panel.
Toolbar	getFootToolbar() Returns the foot toolbar of this panel.
Toolbar	getFootToolbarApi() Returns the foot toolbar of this panel.
java.lang.String	getOuterAttrs() Returns the exterior attributes for generating the enclosing HTML tag; never return null.
Panelchildren	getPanelchildren() Returns the panelchildren of this panel.
Panelchildren	getPanelchildrenApi() Returns the panelchildren of this panel.
protected java.lang.String	getRealSclass() Returns the real style class that will be generated to the client (when HtmlBasedComponent.getOuterAttrs() is called).
java.lang.String	getTitle() Returns the title.
Toolbar	getTopToolbar() Returns the top toolbar of this panel.
Toolbar	getTopToolbarApi() Returns the top toolbar of this panel.
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	isClosable() Returns whether to show a close button on the title bar.
boolean	isCollapsible() Returns whether to show a toggle button on the title bar.
boolean	isFloatable() Returns whether to float the panel to display it inline where it is rendered.
boolean	isFramable() Returns whether to render the panel with custom rounded borders.
boolean	isMaximizable() Returns whether to display the maximizing button and allow the user to maximize the panel.
boolean	isMaximized() Returns whether the panel is maximized.
boolean	isMinimizable() Returns whether to display the minimizing button and allow the user to minimize the panel.
boolean	isMinimized() Returns whether the panel is minimized.
boolean	isMovable() Returns whether to move the panel to display it inline where it is rendered.
boolean	isOpen() Returns whether this Panel is open.
protected java.lang.Object	newExtraCtrl() Used by AbstractComponent.getExtraCtrl() to create a client control.
void	onChildRemoved(Component child) Default: does nothing.
void	onClose() Process the onClose event sent when the close button is pressed.
void	setBorder(java.lang.String border) Sets the border (either none or normal).
void	setClosable(boolean closable) Sets whether to show a close button on the title bar.
void	setCollapsible(boolean collapsible) Sets whether to show a toggle button on the title bar.
void	setFloatable(boolean floatable) Sets whether to float the panel to display it inline where it is rendered.
void	setFramable(boolean framable) Sets whether to render the panel with custom rounded borders.
void	setMaximizable(boolean maximizable) Sets whether to display the maximizing button and allow the user to maximize the panel, when a panel is maximized, the button will automatically change to a restore button with the appropriate behavior already built-in that will restore the panel to its previous size.
void	setMaximized(boolean maximized) Sets whether the panel is maximized, and then the size of the panel will depend on it to show a appropriate size.
void	setMinimizable(boolean minimizable) Sets whether to display the minimizing button and allow the user to minimize the panel.
void	setMinimized(boolean minimized) Sets whether the panel is minimized.
void	setMovable(boolean movable) Sets whether to move the panel to display it inline where it is rendered.
void	setOpen(boolean open) Opens or closes this Panel.
void	setTitle(java.lang.String title) Sets the title.
boolean	setVisible(boolean visible) Sets whether this component is visible.

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, getRealStyle, getRealStyleFlags, getSclass, getStyle, getTooltiptext, getTop, getWidth, getZindex, getZIndex, 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, addSharedAnnotationMap, addSharedEventHandlerMap, appendAsapAttr, appendAsapAttr, appendChild, applyProperties, 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, onDrawNewChild, onPageAttached, onPageDetached, onWrongValue, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, response, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setComponentDefinition, setId, setMold, setPage, setPageBefore, setParent, setVariable, 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, 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, unsetVariable

Constructor Detail

Panel

public Panel()

Method Detail

isOpen

public boolean isOpen()

Returns whether this Panel is open.

Default: true.

Specified by:

isOpen in interface Panel

setOpen

public void setOpen(boolean open)

Opens or closes this Panel.

Specified by:

setOpen in interface Panel

isFramable

public boolean isFramable()

Returns whether to render the panel with custom rounded borders.

Default: false.

Specified by:

isFramable in interface Panel

setFramable

public void setFramable(boolean framable)

Sets whether to render the panel with custom rounded borders.

Default: false.

Specified by:

setFramable in interface Panel

setMovable

public void setMovable(boolean movable)

Sets whether to move the panel to display it inline where it is rendered.

Default: false;

Note that this method only applied when isFloatable() is true.

Specified by:

setMovable in interface Panel

isMovable

public boolean isMovable()

Returns whether to move the panel to display it inline where it is rendered.

Default: false.

Specified by:

isMovable in interface Panel

isFloatable

public boolean isFloatable()

Returns whether to float the panel to display it inline where it is rendered.

Default: false.

Specified by:

isFloatable in interface Panel

setVisible

public boolean setVisible(boolean visible)

Description copied from interface: Component

Sets whether this component is visible.

Specified by:

setVisible in interface Component

Overrides:

setVisible in class AbstractComponent

Returns:

the previous visibility

setFloatable

public void setFloatable(boolean floatable)

Sets whether to float the panel to display it inline where it is rendered.

Note that by default, setting floatable to true will cause the panel to display at default offsets, which depend on the offsets of the embedded panel from its element to document.body -- because the panel is absolute positioned, the position must be set explicitly by HtmlBasedComponent.setTop(String) and HtmlBasedComponent.setLeft(String). Also, when floatable a panel you should always assign a fixed width, otherwise it will be auto width and will expand to fill to the right edge of the viewport.

Specified by:

setFloatable in interface Panel

isMaximized

public boolean isMaximized()

Returns whether the panel is maximized.

Specified by:

isMaximized in interface Panel

setMaximized

public void setMaximized(boolean maximized)

Sets whether the panel is maximized, and then the size of the panel will depend on it to show a appropriate size. In other words, if true, the size of the panel will count on the size of its offset parent node whose position is absolute (by isFloatable()) or its parent node. Otherwise, its size will be original size. Note that the maximized effect will run at client's sizing phase not initial phase.

Default: false.

Specified by:

setMaximized in interface Panel

Throws:

UiException - if isMaximizable() is false.

isMaximizable

public boolean isMaximizable()

Returns whether to display the maximizing button and allow the user to maximize the panel.

Default: false.

Specified by:

isMaximizable in interface Panel

setMaximizable

public void setMaximizable(boolean maximizable)

Sets whether to display the maximizing button and allow the user to maximize the panel, when a panel is maximized, the button will automatically change to a restore button with the appropriate behavior already built-in that will restore the panel to its previous size.

Default: false.

Note: the maximize button won't be displayed if no title or caption at all.

Specified by:

setMaximizable in interface Panel

isMinimized

public boolean isMinimized()

Returns whether the panel is minimized.

Default: false.

Specified by:

isMinimized in interface Panel

setMinimized

public void setMinimized(boolean minimized)

Sets whether the panel is minimized.

Default: false.

Specified by:

setMinimized in interface Panel

Throws:

UiException - if isMinimizable() is false.

isMinimizable

public boolean isMinimizable()

Returns whether to display the minimizing button and allow the user to minimize the panel.

Default: false.

Specified by:

isMinimizable in interface Panel

setMinimizable

public void setMinimizable(boolean minimizable)

Sets whether to display the minimizing button and allow the user to minimize the panel. Note that this button provides no implementation -- the behavior of minimizing a panel is implementation-specific, so the MinimizeEvent event must be handled and a custom minimize behavior implemented for this option to be useful.

Default: false.

Note: the maximize button won't be displayed if no title or caption at all.

Specified by:

setMinimizable in interface Panel

See Also:

MinimizeEvent

isCollapsible

public boolean isCollapsible()

Returns whether to show a toggle button on the title bar.

Default: false.

Specified by:

isCollapsible in interface Panel

setCollapsible

public void setCollapsible(boolean collapsible)

Sets whether to show a toggle button on the title bar.

Default: false.

Note: the toggle button won't be displayed if no title or caption at all.

Specified by:

setCollapsible in interface Panel

isClosable

public boolean isClosable()

Returns whether to show a close button on the title bar.

Specified by:

isClosable in interface Panel

setClosable

public void setClosable(boolean closable)

Sets whether to show a close button on the title bar. If closable, a button is displayed and the onClose event is sent if an user clicks the button.

Default: false.

You can intercept the default behavior by either overriding onClose(), or listening the onClose event.

Note: the close button won't be displayed if no title or caption at all.

Specified by:

setClosable in interface Panel

getCaption

public Caption getCaption()

Returns the caption of this panel.

getCaptionApi

public Caption getCaptionApi()

Returns the caption of this panel.

Specified by:

getCaptionApi in interface Panel

Since:

3.5.2

getBorder

public java.lang.String getBorder()

Returns the border. The border actually controls via Panelchildren.getRealSclass(). In fact, the name of the border (except "normal") is generate as part of the style class used for the content block. Refer to Panelchildren.getRealSclass() for more details.

Default: "none".

Specified by:

getBorder in interface Panel

setBorder

public void setBorder(java.lang.String border)

Sets the border (either none or normal).

Specified by:

setBorder in interface Panel

Parameters:

border - the border. If null or "0", "none" is assumed.

getTitle

public java.lang.String getTitle()

Returns the title. Besides this attribute, you could use Caption to define a more sophiscated caption (aka., title).

If a window has a caption whose label (LabelElement.getLabel()) is not empty, then this attribute is ignored.

Default: empty.

Specified by:

getTitle in interface Panel

setTitle

public void setTitle(java.lang.String title)

Sets the title.

Specified by:

setTitle in interface Panel

addToolbar

public boolean addToolbar(java.lang.String name,
                          Toolbar toolbar)

Adds the toolbar of the panel by these names, "tbar", "bbar", and "fbar". "tbar" is the name of top toolbar, and "bbar" the name of bottom toolbar, and "fbar" the name of foot toolbar.

Parameters:

name - "tbar", "bbar", and "fbar".

addToolbarApi

public boolean addToolbarApi(java.lang.String name,
                             Toolbar toolbarApi)

Adds the toolbar of the panel by these names, "tbar", "bbar", and "fbar". "tbar" is the name of top toolbar, and "bbar" the name of bottom toolbar, and "fbar" the name of foot toolbar.

Specified by:

addToolbarApi in interface Panel

Parameters:

toolbarApi - assume as a Toolbar

name - "tbar", "bbar", and "fbar".

Since:

3.5.2

onClose

public void onClose()

Process the onClose event sent when the close button is pressed.

Default: detach itself.

getTopToolbar

public Toolbar getTopToolbar()

Returns the top toolbar of this panel.

getTopToolbarApi

public Toolbar getTopToolbarApi()

Returns the top toolbar of this panel.

Specified by:

getTopToolbarApi in interface Panel

Since:

3.5.2

getBottomToolbar

public Toolbar getBottomToolbar()

Returns the bottom toolbar of this panel.

getBottomToolbarApi

public Toolbar getBottomToolbarApi()

Returns the bottom toolbar of this panel.

Specified by:

getBottomToolbarApi in interface Panel

Since:

3.5.2

getFootToolbar

public Toolbar getFootToolbar()

Returns the foot toolbar of this panel.

getFootToolbarApi

public Toolbar getFootToolbarApi()

Returns the foot toolbar of this panel.

Specified by:

getFootToolbarApi in interface Panel

Since:

3.5.2

getPanelchildren

public Panelchildren getPanelchildren()

Returns the panelchildren of this panel.

getPanelchildrenApi

public Panelchildren getPanelchildrenApi()

Returns the panelchildren of this panel.

Specified by:

getPanelchildrenApi in interface Panel

Since:

3.5.2

getRealSclass

protected java.lang.String getRealSclass()

Description copied from class: HtmlBasedComponent

Returns the real style class that will be generated to the client (when HtmlBasedComponent.getOuterAttrs() is called).

Default: it simply returns the catenation of HtmlBasedComponent.getSclass() and HtmlBasedComponent.getZclass() (since 3.5.0).

Derived classes might override it to provide, say, dual style classes. For example,

final String sclass = getSclass();
return sclass != null ? sclass + " my-addon": "myaddon";

Overrides:

getRealSclass in class HtmlBasedComponent

See Also:

HtmlBasedComponent.getZclass()

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

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

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)

clone

public java.lang.Object clone()

Description copied from interface: Component

Clones the component. All of its children is cloned. Notice that the cloned component doesn't belong to any page, nor desktop. It doesn't have parent, either.

Specified by:

clone in interface Component

Overrides:

clone in class AbstractComponent

newExtraCtrl

protected java.lang.Object newExtraCtrl()

Description copied from class: HtmlBasedComponent

Used by AbstractComponent.getExtraCtrl() to create a client control. It is used only by component developers.

Defaut: creates an instance of HtmlBasedComponent.ExtraCtrl.

Overrides:

newExtraCtrl in class HtmlBasedComponent

addMoved

protected void addMoved(Component oldparent,
                        Page oldpg,
                        Page newpg)

Description copied from class: AbstractComponent

Called when this component is moved from the specified parent and/or page to the new page.

Default: it notifies UiEngine to update the component at the client (usually remove-and-add).

It is designed to let derived classes overriding this method to disable this update. However, you rarely need to override it. One possible but rare case: the component's visual part at the client updates the visual representation at the client and then notify the component at the server to update its children accordingly. In this case, it is redudant if we ask UI Engine to send the updates to client.

Overrides:

addMoved in class AbstractComponent

Parameters:

oldparent - the parent before moved. The new parent can be found by calling AbstractComponent.getParent().

oldpg - the parent before moved.

newpg - the new page. AbstractComponent.getPage() might return the old page.