org.zkoss.zul.api
Interface Window

All Superinterfaces:
java.lang.Cloneable, Component, Framable, HtmlBasedComponent, IdSpace, Scope, java.io.Serializable, XulElement
All Known Implementing Classes:
FileuploadDlg, MessageboxDlg, Window

public interface Window
extends XulElement, Framable, IdSpace

A 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 Component.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, onMaximize, onMinimize, and onClose.
Note: to have better performance, onOpen is sent only if a non-deferrable event listener is registered (see Deferrable).

onMaximize and onMinimize are supported. (since 3.5.0)

onClose is sent when the close button is pressed (if isClosable() is true). The window has to detach or hide the window. By default, Window.onClose() detaches the window. To prevent it from detached, you have to call Event.stopPropagation() to prevent Window.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.

Default HtmlBasedComponent.getZclass(): z-window-getMode().(since 3.5.0)

Since:
3.5.2
Author:
tomyeh

Field Summary
 
Fields inherited from interface org.zkoss.zk.ui.Component
APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE
 
Method Summary
 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 getCaptionApi()
          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.
 int getMinheight()
          Returns the minimum height.
 int getMinwidth()
          Returns the minimum width.
 java.lang.String getMode()
          Returns the current mode.
 java.lang.String getPosition()
          Returns how to position the window at the client screen.
 java.lang.String getTitle()
          Returns 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 isClosable()
          Returns whether to show a close button on the title bar.
 boolean isMaximizable()
          Returns whether to display the maximizing button and allow the user to maximize the window.
 boolean isMaximized()
          Returns whether the window is maximized.
 boolean isMinimizable()
          Returns whether to display the minimizing button and allow the user to minimize the window.
 boolean isMinimized()
          Returns whether the window is minimized.
 boolean isSizable()
          Returns whether the window is sizable.
 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 setContentSclass(java.lang.String scls)
          Sets the style class used for the content block.
 void setContentStyle(java.lang.String style)
          Sets the CSS style for the content block of the window.
 void setMaximizable(boolean maximizable)
          Sets whether to display the maximizing button and allow the user to maximize the window, when a window is maximized, the button will automatically change to a restore button with the appropriate behavior already built-in that will restore the window to its previous size.
 void setMaximized(boolean maximized)
          Sets whether the window is maximized, and then the size of the window will depend on it to show a appropriate size.
 void setMinheight(int minheight)
          Sets the minimum height in pixels allowed for this window.
 void setMinimizable(boolean minimizable)
          Sets whether to display the minimizing button and allow the user to minimize the window.
 void setMinimized(boolean minimized)
          Sets whether the window is minimized.
 void setMinwidth(int minwidth)
          Sets the minimum width in pixels allowed for this window.
 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 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.
 
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, getZclass, 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, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getChildren, getDefinition, getDesktop, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getNamespace, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getUuid, getVariable, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttributeOrFellow, hasFellow, hasFellow, insertBefore, invalidate, isInvalidated, isListenerAvailable, isVisible, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, setAttribute, setAttribute, setAuService, setId, setMold, setPage, setPageBefore, setParent, setVariable, setVisible, setWidgetListener, setWidgetOverride, unsetVariable
 
Methods inherited from interface org.zkoss.zk.ui.ext.Scope
addScopeListener, getAttribute, hasAttribute, removeAttribute, removeScopeListener, setAttribute
 
Methods inherited from interface org.zkoss.zul.ext.Framable
isCollapsible
 
Methods inherited from interface org.zkoss.zk.ui.IdSpace
getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, hasFellow, hasFellow
 

Method Detail

isMaximized

boolean isMaximized()
Returns whether the window is maximized.

Specified by:
isMaximized in interface Framable

setMaximized

void setMaximized(boolean maximized)
Sets whether the window is maximized, and then the size of the window will depend on it to show a appropriate size. In other words, if true, the size of the window will count on the size of its offset parent node whose position is absolute (by not inEmbedded()) 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

boolean isMaximizable()
Returns whether to display the maximizing button and allow the user to maximize the window.

Default: false.

Specified by:
isMaximizable in interface Framable

setMaximizable

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

Default: false.

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


isMinimized

boolean isMinimized()
Returns whether the window is minimized.

Default: false.


setMinimized

void setMinimized(boolean minimized)
Sets whether the window is minimized.

Default: false.

Throws:
UiException - if isMinimizable() is false.

isMinimizable

boolean isMinimizable()
Returns whether to display the minimizing button and allow the user to minimize the window.

Default: false.

Specified by:
isMinimizable in interface Framable

setMinimizable

void setMinimizable(boolean minimizable)
Sets whether to display the minimizing button and allow the user to minimize the window. Note that this button provides no implementation -- the behavior of minimizing a window 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

setMinheight

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

Default: 100.

Note: Only applies when isSizable() = true.


getMinheight

int getMinheight()
Returns the minimum height.

Default: 100.


setMinwidth

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

Default: 200.

Note: Only applies when isSizable() = true.


getMinwidth

int getMinwidth()
Returns the minimum width.

Default: 200.


getCaptionApi

Caption getCaptionApi()
Returns the caption of this window.


getBorder

java.lang.String getBorder()
Returns the border. The border actually controls what the content style class is is used. In fact, the name of the border (except "normal") is generate as part of the style class used for the content block. Refer to getContentSclass() for more details.

Default: "none".


setBorder

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

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 Framable

setTitle

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


getMode

java.lang.String getMode()
Returns the current mode. One of "modal", "embedded", "overlapped", "popup", and "highlighted".


setMode

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. Unlike doModal(), Events.ON_MODAL is posted, so the window will become modal later (since 3.0.4). In other words, setMode("modal") never suspends the execution of the current thread. On the other hand, doModal() will suspends the execution if executed in an event listener, or throws an exception if not executed in an event listener.

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

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

boolean inModal()
Returns whether this is a modal dialog.


inEmbedded

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

See Also:
doEmbedded()

inOverlapped

boolean inOverlapped()
Returns whether this is a overlapped window.


inPopup

boolean inPopup()
Returns whether this is a popup window.


inHighlighted

boolean inHighlighted()
Returns whether this is a highlighted window.


doModal

void doModal()
             throws java.lang.InterruptedException,
                    SuspendNotAllowedException
Makes this window as a modal dialog. It will automatically center the window (ignoring HtmlBasedComponent.getLeft() and HtmlBasedComponent.getTop()).

Notice: though both setMode("modal") and doModal() both causes the window to become modal, they are a bit different. doModal causes the event listener to suspend immediately, while setMode("modal") posts an event ( Events.ON_MODAL). That is, setMode(java.lang.String) won't suspend the execution immediately, but doModal() will. doModal() can be called only in an event listener, while setMode(java.lang.String) can be called anytime.

Throws:
SuspendNotAllowedException - if 1) not in an event listener;
2) the event thread is disabled.
3) 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

void doOverlapped()
Makes this window as overlapped with other components.


doPopup

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


doHighlighted

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

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


isClosable

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

Specified by:
isClosable in interface Framable

setClosable

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 Window.onClose(), or listening the onClose event.

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


isSizable

boolean isSizable()
Returns whether the window is sizable.


setSizable

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

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

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.
parent
Position the window relative to its parent. That is, the left and top (HtmlBasedComponent.getTop() and HtmlBasedComponent.getLeft()) is an offset to his parent's let-top corner. (since 3.0.2)

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


getContentStyle

java.lang.String getContentStyle()
Returns the CSS style for the content block of the window.


setContentStyle

void setContentStyle(java.lang.String style)
Sets the CSS style for the content block of the window.

Default: null.


getContentSclass

java.lang.String getContentSclass()
Returns the style class used for the content block.

See Also:
setContentSclass(java.lang.String)

setContentSclass

void setContentSclass(java.lang.String scls)
Sets the style class used for the content block.

See Also:
getContentSclass()


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