org.zkoss.zul
Class Window

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

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, org.zkoss.zk.ui.Component, org.zkoss.zk.ui.IdSpace, org.zkoss.zk.ui.sys.ComponentCtrl

Direct Known Subclasses:

FileuploadDlg, MessageboxDlg

public class Window
extends XulElement
implements org.zkoss.zk.ui.IdSpace

A generic window.

Unlike other elements, each Window is an independent ID space (by implementing IdSpace). It means a window and all its descendants forms a ID space and the ID of each of them is unique in this space. You could retrieve any of them in this space by calling AbstractComponent.getFellow(java.lang.String).

If a window X is a descendant of another window Y, X's descendants are not visible in Y's space. To retrieve a descendant, say Z, of X, you have to invoke Y.getFellow('X').getFellow('Z').

Events:
onMove, onOpen, onClose, onOK, onCacnel and onCtrlKey.
Note: to have better performance, onOpen is sent only if a non-deferrable event listener is registered (see Deferrable).

onClose is sent when the close button is pressed (if isClosable() is true). The window has to detach or hide the window. By default, onClose() detaches the window. To prevent it from detached, you have to call Event.stopPropagation() to prevent onClose() is called.

On the other hand, onOpen is sent when a popup window (i.e., getMode() is popup) is closed due to user's activity (such as press ESC). This event is only a notification. In other words, the popup is hidden before the event is sent to the server. The application cannot prevent the window from being hidden.

Author:

tomyeh

See Also:

Serialized Form

Nested Class Summary

protected class

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

Field Summary

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

RS_NO_DISPLAY, RS_NO_HEIGHT, RS_NO_WIDTH

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

Window()

Window(java.lang.String title, java.lang.String border, boolean closable)

Method Summary

java.lang.Object	clone()
void	doEmbedded() Makes this window as embeded with other components (Default).
void	doHighlighted() Makes this window as highlited.
void	doModal() Makes this window as a modal dialog.
void	doOverlapped() Makes this window as overlapped with other components.
void	doPopup() Makes this window as popup, which is overlapped with other component and auto-hiden when user clicks outside of the window.
java.lang.String	getBorder() Returns the border.
Caption	getCaption() Returns the caption of this window.
java.lang.String	getContentSclass() Returns the style class used for the content block.
java.lang.String	getContentStyle() Returns the CSS style for the content block of the window.
java.lang.String	getCtrlKeys() Returns what keystrokes to intercept.
java.lang.String	getMode() Returns the current mode.
java.lang.String	getOuterAttrs()
java.lang.String	getPosition() Returns how to position the window at the client screen.
protected java.lang.String	getRealStyle()
java.lang.String	getSclass() Returns the style class.
java.lang.String	getTitle() Returns the title.
java.lang.String	getTitleSclass() Returns the style class used for the title.
boolean	inEmbedded() Returns whether this is embedded with other components (Default).
boolean	inHighlighted() Returns whether this is a highlighted window.
boolean	inModal() Returns whether this is a modal dialog.
boolean	inOverlapped() Returns whether this is a overlapped window.
boolean	inPopup() Returns whether this is a popup window.
boolean	insertBefore(org.zkoss.zk.ui.Component child, org.zkoss.zk.ui.Component insertBefore)
boolean	isClosable() Returns whether to show a close button on the title bar.
boolean	isSizable() Returns whether the window is sizable.
protected java.lang.Object	newExtraCtrl()
void	onChildRemoved(org.zkoss.zk.ui.Component child)
void	onClose() Process the onClose event sent when the close button is pressed.
void	onModal() Process the onModal event by making itself a modal window.
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	setContentStyle(java.lang.String style) Sets the CSS style for the content block of the window.
void	setCtrlKeys(java.lang.String ctrlKeys) Sets what keystrokes to intercept.
void	setDraggable(java.lang.String draggable)
void	setMode(int mode) Sets the mode to overlapped, popup, modal, embedded or highlighted.
void	setMode(java.lang.String name) Sets the mode to overlapped, popup, modal, embedded or highlighted.
void	setPage(org.zkoss.zk.ui.Page page)
void	setParent(org.zkoss.zk.ui.Component parent)
void	setPosition(java.lang.String pos) Sets how to position the window at the client screen.
void	setSizable(boolean sizable) Sets whether the window is sizable.
void	setTitle(java.lang.String title) Sets the title.
boolean	setVisible(boolean visible) Changes the visibility of the window.

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

getAction, getAllOnClickAttrs, getContext, getInnerAttrs, getPopup, getTooltip, setAction, setContext, setPopup, setTooltip

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

addEventListener, appendAsapAttr, focus, getDraggable, getDroppable, getHeight, getLeft, getRealStyleFlags, getStyle, getTooltiptext, getTop, getWidth, getZIndex, isAsapRequired, removeEventListener, setClass, setDroppable, setHeight, setLeft, setSclass, setStyle, setTooltiptext, setTop, setWidth, setZIndex

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

addAnnotation, addAnnotation, addEventHandler, addSharedAnnotationMap, addSharedEventHandlerMap, appendChild, applyProperties, containsVariable, detach, equals, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotation, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttributes, getAttributes, getChildren, getDefinition, getDesktop, getEventHandler, getExtraCtrl, getFellow, getFellowIfAny, getId, getListenerIterator, getMold, getMoldURI, getNamespace, getPage, getParent, getPropagatee, getRoot, getSpaceOwner, getUuid, getVariable, invalidate, isChildable, isListenerAvailable, isVisible, onChildAdded, onDrawNewChild, onWrongValue, redraw, removeAttribute, removeAttribute, removeChild, response, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setComponentDefinition, setId, setMold, setVariable, smartUpdate, smartUpdate, smartUpdate, toString, unsetVariable

Methods inherited from class java.lang.Object

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

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

getFellow, getFellowIfAny

Constructor Detail

Window

public Window()

Window

public Window(java.lang.String title,
              java.lang.String border,
              boolean closable)

Parameters:

title - the window title (see setTitle(java.lang.String)).

border - the border (see setBorder(java.lang.String)).

closable - whether it is closable (see setClosable(boolean)).

Method Detail

getCaption

public Caption getCaption()

Returns the caption of this window.

getBorder

public java.lang.String getBorder()

Returns the border.

The border actually controls what CSS class to use: If border is null, it implies "none". If border is "normal", the class called "window" is used. If not, the class called "window-border" (e.g., "window-none").

If you also specify the CSS class (HtmlBasedComponent.setClass(java.lang.String)), it overwrites whatever border you specify here.

Default: "none".

setBorder

public void setBorder(java.lang.String border)

Sets the border (either none or normal).

Parameters:

border - the border. If null or "0", "none" is assumed. Since 2.4.1, We assume "0" to be "none".

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.

setTitle

public void setTitle(java.lang.String title)

Sets the title.

getCtrlKeys

public java.lang.String getCtrlKeys()

Returns what keystrokes to intercept.

Default: null.

setCtrlKeys

public void setCtrlKeys(java.lang.String ctrlKeys)
                 throws org.zkoss.zk.ui.UiException

Sets what keystrokes to intercept.

The string could be a combination of the following:

^k

A control key, i.e., Ctrl+k, where k could be a~z, 0~9, #n

@k

A alt key, i.e., Alt+k, where k could be a~z, 0~9, #n

$k

A shift key, i.e., Shift+k, where k could be #n

#home

Home

#end

End

#ins

Insert

#del

Delete

#left

Left arrow

#right

Right arrow

#up

Up arrow

#down

Down arrow

#pgup

PageUp

#pgdn

PageDn

#f1 #f2 ... #f12

Function keys representing F1, F2, ... F12

For example,

^a^d@c#f10#left#right

It means you want to intercept Ctrl+A, Ctrl+D, Alt+C, F10, Left and Right.

^#left

It means Ctrl+Left.

^#f1

It means Ctrl+F1.

@#f3

It means Alt+F3.

Note: it doesn't support Ctrl+Alt, Shift+Ctrl, Shift+Alt or Shift+Ctrl+Alt.

Throws:

org.zkoss.zk.ui.UiException

getMode

public java.lang.String getMode()

Returns the current mode. One of "modal", "embedded", "overlapped", "popup", and "highlighted".

setMode

public void setMode(java.lang.String name)
             throws java.lang.InterruptedException

Sets the mode to overlapped, popup, modal, embedded or highlighted.

Notice: Events.ON_MODAL is posted if you specify "modal" to this method and in a thread other than an event listener (Events.inEventListener()). In other words, if this method is called with modal and not in any event listener, the mode won't be changed immediately (until Events.ON_MODAL is processed later).

Parameters:

name - the mode which could be one of "embedded", "overlapped", "popup", "modal", "highlighted". Note: it cannot be "modal". Use doModal() instead.

Throws:

java.lang.InterruptedException - thrown if "modal" is specified, and one of the following conditions occurs: 1) the desktop or the Web application is being destroyed, or 2) DesktopCtrl.ceaseSuspendedThread(org.zkoss.zk.ui.sys.EventProcessingThread, java.lang.String). To tell the difference, check the getMessage method of InterruptedException.

setMode

public void setMode(int mode)
             throws java.lang.InterruptedException

Sets the mode to overlapped, popup, modal, embedded or highlighted.

Throws:

java.lang.InterruptedException

See Also:

setMode(String)

inModal

public boolean inModal()

Returns whether this is a modal dialog.

inEmbedded

public boolean inEmbedded()

Returns whether this is embedded with other components (Default).

See Also:

doEmbedded()

inOverlapped

public boolean inOverlapped()

Returns whether this is a overlapped window.

inPopup

public boolean inPopup()

Returns whether this is a popup window.

inHighlighted

public boolean inHighlighted()

Returns whether this is a highlighted window.

doModal

public void doModal()
             throws java.lang.InterruptedException,
                    org.zkoss.zk.ui.SuspendNotAllowedException

Makes this window as a modal dialog. It will automatically center the window (ignoring HtmlBasedComponent.getLeft() and HtmlBasedComponent.getTop()).

Notice: Events.ON_MODAL is posted if you specify "modal" to this method and in a thread other than an event listener (Events.inEventListener()). In other words, if this method is called with modal and not in any event listener, the mode won't be changed immediately (until Events.ON_MODAL is processed later).

Throws:

org.zkoss.zk.ui.SuspendNotAllowedException - if there are too many suspended processing thread than the deployer allows. By default, there is no limit of # of suspended threads.

java.lang.InterruptedException - thrown if the desktop or the Web application is being destroyed, or DesktopCtrl.ceaseSuspendedThread(org.zkoss.zk.ui.sys.EventProcessingThread, java.lang.String). To tell the difference, check the getMessage method of InterruptedException.

doOverlapped

public void doOverlapped()

Makes this window as overlapped with other components.

doPopup

public void doPopup()

Makes this window as popup, which is overlapped with other component and auto-hiden when user clicks outside of the window.

doHighlighted

public void doHighlighted()

Makes this window as highlited. The visual effect is the similar to the modal window, but, like overlapped, it doesn't suspend (block) the execution at the server. In other words, it is more like an overlapped window from the server side's viewpoint.

doEmbedded

public void doEmbedded()

Makes this window as embeded with other components (Default).

isClosable

public boolean isClosable()

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

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.

isSizable

public boolean isSizable()

Returns whether the window is sizable.

setSizable

public void setSizable(boolean sizable)

Sets whether the window is sizable. If true, an user can drag the border to change the window width.

Default: false.

getPosition

public java.lang.String getPosition()

Returns how to position the window at the client screen. It is meaningless if the embedded mode is used.

Default: null which depends on getMode(): If overlapped or popup, HtmlBasedComponent.setLeft(java.lang.String) and HtmlBasedComponent.setTop(java.lang.String) are assumed. If modal or highlighted, it is centered.

setPosition

public void setPosition(java.lang.String pos)

Sets how to position the window at the client screen. It is meaningless if the embedded mode is used.

Parameters:

pos - how to position. It can be null (the default), or a combination of the following values (by separating with comma).

center

Position the window at the center. HtmlBasedComponent.setTop(java.lang.String) and HtmlBasedComponent.setLeft(java.lang.String) are both ignored.

left

Position the window at the left edge. HtmlBasedComponent.setLeft(java.lang.String) is ignored.

right

Position the window at the right edge. HtmlBasedComponent.setLeft(java.lang.String) is ignored.

top

Position the window at the top edge. HtmlBasedComponent.setTop(java.lang.String) is ignored.

bottom

Position the window at the bottom edge. HtmlBasedComponent.setTop(java.lang.String) is ignored.

For example, "left,center" means to position it at the center of the left edge.

onClose

public void onClose()

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

Default: detach itself.

onModal

public void onModal()
             throws java.lang.InterruptedException

Process the onModal event by making itself a modal window.

Throws:

java.lang.InterruptedException

getContentStyle

public java.lang.String getContentStyle()

Returns the CSS style for the content block of the window.

setContentStyle

public void setContentStyle(java.lang.String style)

Sets the CSS style for the content block of the window.

Default: null.

getContentSclass

public java.lang.String getContentSclass()

Returns the style class used for the content block.

If getBorder() is "normal", "wc-sclass" is returned, where sclass is the value returned by getSclass(). Otherwise, "wc-mode-border", where border is the value returned by getBorder().

getTitleSclass

public java.lang.String getTitleSclass()

Returns the style class used for the title.

It returns "wt-sclass" is returned, where sclass is the value returned by getSclass().

getSclass

public java.lang.String getSclass()

Returns the style class. If the style class is not defined (HtmlBasedComponent.setSclass(java.lang.String) is not called or called with null or empty), it returns getMode(). In other words, the style class is, by default, the same as the mode name.

Overrides:

getSclass in class org.zkoss.zk.ui.HtmlBasedComponent

insertBefore

public boolean insertBefore(org.zkoss.zk.ui.Component child,
                            org.zkoss.zk.ui.Component insertBefore)

Specified by:

insertBefore in interface org.zkoss.zk.ui.Component

Overrides:

insertBefore in class org.zkoss.zk.ui.AbstractComponent

onChildRemoved

public void onChildRemoved(org.zkoss.zk.ui.Component child)

Specified by:

onChildRemoved in interface org.zkoss.zk.ui.Component

Overrides:

onChildRemoved in class org.zkoss.zk.ui.AbstractComponent

setPage

public void setPage(org.zkoss.zk.ui.Page page)

Specified by:

setPage in interface org.zkoss.zk.ui.Component

Overrides:

setPage in class org.zkoss.zk.ui.AbstractComponent

setParent

public void setParent(org.zkoss.zk.ui.Component parent)

Specified by:

setParent in interface org.zkoss.zk.ui.Component

Overrides:

setParent in class org.zkoss.zk.ui.AbstractComponent

setVisible

public boolean setVisible(boolean visible)

Changes the visibility of the window.

Note: If a modal dialog becomes invisible, the modal state will be ended automatically. In other words, the mode (getMode()) will become OVERLAPPED and the suspending thread is resumed.

Specified by:

setVisible in interface org.zkoss.zk.ui.Component

Overrides:

setVisible in class org.zkoss.zk.ui.AbstractComponent

setDraggable

public void setDraggable(java.lang.String draggable)

Overrides:

setDraggable in class org.zkoss.zk.ui.HtmlBasedComponent

getRealStyle

protected java.lang.String getRealStyle()

Overrides:

getRealStyle in class org.zkoss.zk.ui.HtmlBasedComponent

getOuterAttrs

public java.lang.String getOuterAttrs()

Overrides:

getOuterAttrs in class XulElement

clone

public java.lang.Object clone()

Specified by:

clone in interface org.zkoss.zk.ui.Component

Overrides:

clone in class org.zkoss.zk.ui.AbstractComponent

newExtraCtrl

protected java.lang.Object newExtraCtrl()

Overrides:

newExtraCtrl in class org.zkoss.zk.ui.HtmlBasedComponent