org.zkoss.zul
Class Panel

java.lang.Object
  extended by org.zkoss.zk.ui.AbstractComponent
      extended by org.zkoss.zk.ui.HtmlBasedComponent
          extended by org.zkoss.zul.impl.XulElement
              extended by org.zkoss.zul.Panel
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, Component, Scope, ComponentCtrl, Framable

public class Panel
extends XulElement
implements Framable

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
 
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
 
Fields inherited from interface org.zkoss.zk.ui.Component
APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE
 
Fields inherited from interface org.zkoss.zk.ui.sys.ComponentCtrl
CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE
 
Constructor Summary
Panel()
           
 
Method Summary
 boolean addToolbar(java.lang.String name, Toolbar toolbar)
          Adds the toolbar of the panel by these names, "tbar", "bbar", and "fbar".
 void beforeChildAdded(Component newChild, Component refChild)
          Default: does nothing.
 java.lang.Object clone()
          Clones the component.
 java.lang.String getBorder()
          Returns the border.
 Toolbar getBottomToolbar()
          Returns the bottom toolbar of this panel.
 Caption getCaption()
          Returns the caption of this panel.
 Toolbar getFootToolbar()
          Returns the foot toolbar of this panel.
 int getMinheight()
          Returns the minimum height.
 int getMinwidth()
          Returns the minimum width.
 Panelchildren getPanelchildren()
          Returns the panelchildren of this panel.
 java.lang.String getTitle()
          Returns the title.
 Toolbar getTopToolbar()
          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()
          Deprecated. As of release 5.0.6, replaced with getBorder(). Returns whether to render the panel with custom rounded borders.

Default: false.

 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.
 boolean isSizable()
          Returns whether the panel is sizable.
 void onChildRemoved(Component child)
          Default: does nothing.
 void onClose()
          Process the onClose event sent when the close button is pressed.
protected  void renderProperties(ContentRenderer renderer)
          Renders the content of this component, excluding the enclosing tags and children.
 void service(AuRequest request, boolean everError)
          Processes an AU request.
 void setBorder(boolean border)
          Enables or disables the border.
 void setBorder(java.lang.String border)
          Sets the border.
 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)
          Deprecated. As of release 5.0.6, replaced with setBorder(java.lang.String). Sets whether to render the panel with custom rounded borders.

Default: false.

 void setHflex(java.lang.String flex)
          Sets horizontal flex hint of this component.
 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 setMinheight(int minheight)
          Sets the minimum height in pixels allowed for this panel.
 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 setMinwidth(int minwidth)
          Sets the minimum width in pixels allowed for this panel.
 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 setSizable(boolean sizable)
          Sets whether the panel is sizable.
 void setTitle(java.lang.String title)
          Sets the title.
 void setVflex(java.lang.String flex)
          Sets vertical flexibility hint of this component.
 boolean setVisible(boolean visible)
          Sets whether this component is visible.
 
Methods inherited from class org.zkoss.zul.impl.XulElement
getContext, getCtrlKeys, getPopup, getTooltip, setContext, setContext, setCtrlKeys, setPopup, setPopup, setTooltip, setTooltip
 
Methods inherited from class org.zkoss.zk.ui.HtmlBasedComponent
focus, getAction, getDraggable, getDroppable, getExtraCtrl, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getStyle, getTooltiptext, getTop, getVflex, getWidth, getZindex, getZIndex, setAction, setClass, setDraggable, setDroppable, setFocus, setHeight, setHeightDirectly, setHflexDirectly, setLeft, setLeftDirectly, setRenderdefer, setSclass, setStyle, setTooltiptext, setTop, setTopDirectly, setWidth, setWidthDirectly, setZclass, setZindex, setZIndex, setZIndexDirectly
 
Methods inherited from class org.zkoss.zk.ui.AbstractComponent
addAnnotation, addAnnotation, addClientEvent, addEventHandler, addEventListener, addEventListener, addForward, addForward, addForward, addForward, addMoved, addScopeListener, addSharedEventHandlerMap, appendChild, applyProperties, beforeChildRemoved, beforeParentChanged, detach, didActivate, didActivate, didDeserialize, didDeserialize, disableClientUpdate, equals, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotation, getAnnotations, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getAutag, getChildren, getClientEvents, getDefaultMold, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getEventListenerMap, getEventListeners, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getStubonly, getTemplate, getTemplateNames, getUuid, getWidgetAttribute, getWidgetAttributeNames, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasFellow, hasFellow, invalidate, isChildable, isInvalidated, isListenerAvailable, isVisible, onChildAdded, onPageAttached, onPageDetached, onWrongValue, query, queryAll, redraw, redrawChildren, removeAttribute, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, removeScopeListener, render, render, render, replace, response, response, response, service, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setAttribute, setAuService, setAutag, setDefinition, setDefinition, setId, setMold, setPage, setPageBefore, setParent, setStubonly, setStubonly, setTemplate, setVisibleDirectly, setWidgetAttribute, setWidgetClass, setWidgetListener, setWidgetOverride, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdateWidgetListener, smartUpdateWidgetOverride, toString, updateByClient, willPassivate, willPassivate, willSerialize, willSerialize
 
Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Panel

public Panel()
Method Detail

isOpen

public boolean isOpen()
Returns whether this Panel is open.

Default: true.


setOpen

public void setOpen(boolean open)
Opens or closes this Panel.


isFramable

public boolean isFramable()
Deprecated. As of release 5.0.6, replaced with getBorder(). Returns whether to render the panel with custom rounded borders.

Default: false.


setFramable

public void setFramable(boolean framable)
Deprecated. As of release 5.0.6, replaced with setBorder(java.lang.String). Sets whether to render the panel with custom rounded borders.

Default: false.


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.


isMovable

public boolean isMovable()
Returns whether to move the panel to display it inline where it is rendered.

Default: false.


isFloatable

public boolean isFloatable()
Returns whether to float the panel to display it inline where it is rendered.

Default: false.


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.


isMaximized

public boolean isMaximized()
Returns whether the panel is maximized.

Specified by:
isMaximized in interface Framable

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.

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 Framable

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.


isMinimized

public boolean isMinimized()
Returns whether the panel is minimized.

Default: false.


setMinimized

public void setMinimized(boolean minimized)
Sets whether the panel is minimized.

Default: false.

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 Framable

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.

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 Framable

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.

Note: onOpen event will be sent when you click the toggle button


isClosable

public boolean isClosable()
Returns whether to show a close button on the title bar.

Specified by:
isClosable in interface Framable

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.


setMinheight

public void setMinheight(int minheight)
Sets the minimum height in pixels allowed for this panel. If negative, 100 is assumed.

Default: 100.

Note: Only applies when isSizable() = true.

Since:
5.0.0

getMinheight

public int getMinheight()
Returns the minimum height.

Default: 100.

Since:
5.0.0

setMinwidth

public void setMinwidth(int minwidth)
Sets the minimum width in pixels allowed for this panel. If negative, 200 is assumed.

Default: 200.

Note: Only applies when isSizable() = true.

Since:
5.0.0

getMinwidth

public int getMinwidth()
Returns the minimum width.

Default: 200.

Since:
5.0.0

setHflex

public void setHflex(java.lang.String flex)
Description copied from class: HtmlBasedComponent
Sets horizontal flex hint of this component.

Number flex indicates how this component's container distributes remaining empty space among its children horizontally. Flexible component grow and shrink to fit their given space. Flexible components with larger flex values will be made larger than components with lower flex values, at the ratio determined by all flexible components. The actual flex value is not relevant unless there are other flexible components within the same container. Once the default sizes of components in a container are calculated, the remaining space in the container is divided among the flexible components, according to their flex ratios.

Specify a flex value of negative value, 0, or "false" has the same effect as leaving the flex attribute out entirely. Specify a flex value of "true" has the same effect as a flex value of 1.

Special flex hint, "min", indicates that the minimum space shall be given to this flexible component to enclose all of its children components. That is, the flexible component grow and shrink to fit its children components.

Overrides:
setHflex in class HtmlBasedComponent
Parameters:
flex - horizontal flex hint of this component.
See Also:
HtmlBasedComponent.setVflex(java.lang.String), HtmlBasedComponent.getHflex()

setVflex

public void setVflex(java.lang.String flex)
Description copied from class: HtmlBasedComponent
Sets vertical flexibility hint of this component.

Number flex indicates how this component's container distributes remaining empty space among its children vertically. Flexible component grow and shrink to fit their given space. Flexible components with larger flex values will be made larger than components with lower flex values, at the ratio determined by all flexible components. The actual flex value is not relevant unless there are other flexible components within the same container. Once the default sizes of components in a container are calculated, the remaining space in the container is divided among the flexible components, according to their flex ratios.

Specify a flex value of negative value, 0, or "false" has the same effect as leaving the flex attribute out entirely. Specify a flex value of "true" has the same effect as a flex value of 1.

Special flex hint, "min", indicates that the minimum space shall be given to this flexible component to enclose all of its children components. That is, the flexible component grow and shrink to fit its children components.

Overrides:
setVflex in class HtmlBasedComponent
Parameters:
flex - the vertical flex hint.
See Also:
HtmlBasedComponent.setHflex(java.lang.String), HtmlBasedComponent.getVflex()

isSizable

public boolean isSizable()
Returns whether the panel is sizable.

Since:
5.0.0

setSizable

public void setSizable(boolean sizable)
Sets whether the panel is sizable. If true, an user can drag the border to change the panel width.

Default: false.

Since:
5.0.0

getCaption

public Caption getCaption()
Returns the caption of this panel.


getBorder

public java.lang.String getBorder()
Returns the border.

Default: "none".


setBorder

public void setBorder(java.lang.String border)
Sets the border. Allowed values include none (default), normal, rounded and rounded+. For more information, please refer to ZK Component Reference: Panel.

Parameters:
border - the border. If null, "0" or "false", "none" is assumed. If "true", "normal" is assumed (since 5.0.8).

setBorder

public void setBorder(boolean border)
Enables or disables the border.

Parameters:
border - whether to have a border. If true is specified, it is the same as setBorder("normal").
Since:
5.0.8

getTitle

public java.lang.String getTitle()
Returns the title. Besides this attribute, you could use Caption to define a more sophisticated caption (a.k.a., title).

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

Default: empty.

Specified by:
getTitle in interface Framable

setTitle

public void setTitle(java.lang.String title)
Sets the title.


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".

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.


getBottomToolbar

public Toolbar getBottomToolbar()
Returns the bottom toolbar of this panel.


getFootToolbar

public Toolbar getFootToolbar()
Returns the foot toolbar of this panel.


getPanelchildren

public Panelchildren getPanelchildren()
Returns the panelchildren of this panel.


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 (AbstractComponent.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.

Overrides:
getZclass in class HtmlBasedComponent
See Also:
HtmlBasedComponent.getSclass()

beforeChildAdded

public void beforeChildAdded(Component newChild,
                             Component refChild)
Description copied from class: AbstractComponent
Default: does nothing.

Specified by:
beforeChildAdded in interface ComponentCtrl
Overrides:
beforeChildAdded in class AbstractComponent
Parameters:
newChild - the child to be added (never null).
refChild - another child component that the new child will be inserted before it. If null, the new child will be the last child.
See Also:
ComponentCtrl.beforeChildAdded(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component)

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.

If you would like to monitor if a component is attached or detached from a page, you could register a desktop listener implementing UiLifeCycle.

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 and descendants are cloned. Also, ID are preserved.

Specified by:
clone in interface Component
Overrides:
clone in class XulElement
Returns:
the new component. Notice that it doesn't belong to any page, nor desktop. It doesn't have a parent, either.

renderProperties

protected void renderProperties(ContentRenderer renderer)
                         throws java.io.IOException
Description copied from class: HtmlBasedComponent
Renders the content of this component, excluding the enclosing tags and children.

See also ZK Client-side Reference: Property Rendering

Overrides:
renderProperties in class XulElement
Throws:
java.io.IOException

service

public void service(AuRequest request,
                    boolean everError)
Processes an AU request.

Default: in addition to what are handled by HtmlBasedComponent.service(org.zkoss.zk.au.AuRequest, boolean), it also handles onOpen.

Specified by:
service in interface ComponentCtrl
Overrides:
service in class HtmlBasedComponent
everError - whether any error ever occurred before processing this request.
Since:
5.0.0
See Also:
AbstractComponent.setAuService(org.zkoss.zk.au.AuService)


Copyright © 2005-2011 Potix Corporation. All Rights Reserved. SourceForge.net Logo