org.zkoss.zk.ui
Interface Component

All Superinterfaces:
java.lang.Cloneable, Scope, java.io.Serializable
All Known Subinterfaces:
A, Applet, Audio, Auxhead, Auxheader, Bandbox, Bandpopup, Borderlayout, Borderlayout, Box, Button, Calendar, Captcha, Caption, Cell, Center, Center, Chart, Checkbox, Colorbox, Column, Columnchildren, Columnlayout, Columns, Combobox, Comboitem, Datebox, Decimalbox, Detail, Div, Doublebox, East, East, Fileupload, Fisheye, Fisheyebar, Flash, Flashchart, Foot, Footer, FormatInputElement, Frozen, Grid, Group, Groupbox, Groupfoot, Hbox, HeaderElement, HeadersElement, Html, HtmlBasedComponent, Iframe, Image, Imagemap, Include, InputElement, Intbox, Jasperreport, Label, LabelElement, LabelImageElement, LayoutRegion, LayoutRegion, Listbox, Listcell, Listfoot, Listfooter, Listgroup, Listgroupfoot, Listhead, Listheader, Listitem, Longbox, Menu, Menubar, Menuitem, Menupopup, Menuseparator, North, North, NumberInputElement, Paging, Panel, Panelchildren, Popup, Portalchildren, Portallayout, Progressmeter, Radio, Radiogroup, Row, Rows, Separator, Slider, South, South, Space, Span, Spinner, Splitter, Tab, Tabbox, Tablechildren, Tablelayout, Tabpanel, Tabpanels, Tabs, Textbox, Timebox, Timer, Toolbar, Toolbarbutton, Tree, Treecell, Treechildren, Treecol, Treecols, Treefoot, Treefooter, Treeitem, Treerow, Vbox, West, West, Window, XulElement
All Known Implementing Classes:
A, A, Abbr, AbstractComponent, AbstractTag, Acronym, Address, Applet, Area, Area, Audio, Auxhead, Auxheader, B, Bandbox, Bandpopup, Base, Big, Blockquote, Body, Borderlayout, Borderlayout, Box, Br, Button, Button, Calendar, Captcha, Caption, Caption, Cell, Center, Center, Center, Chart, Checkbox, Cite, Code, Col, Colgroup, Colorbox, Column, Columnchildren, Columnlayout, Columns, Combobox, Comboitem, Datebox, Dd, Decimalbox, Del, Detail, Dfn, Dir, Div, Div, Dl, Doublebox, Dt, East, East, Em, Embed, Fieldset, Fileupload, Fileupload, FileuploadDlg, Fisheye, Fisheyebar, Flash, Flashchart, Font, Foot, Footer, Form, FormatInputElement, Frozen, Grid, Group, Groupbox, Groupfoot, H1, H2, H3, H4, Hbox, Head, HeaderElement, HeadersElement, Hr, Html, Html, HtmlBasedComponent, HtmlMacroComponent, HtmlNativeComponent, I, Iframe, Iframe, Image, Imagemap, Img, Include, Input, InputElement, Ins, Intbox, Isindex, Jasperreport, Kbd, Label, Label, LabelElement, LabelImageElement, LayoutRegion, LayoutRegion, Legend, Li, Link, Listbox, Listcell, Listfoot, Listfooter, Listgroup, Listgroupfoot, Listhead, Listheader, Listitem, Longbox, Map, Menu, Menu, Menubar, Menuitem, Menupopup, Menuseparator, MessageboxDlg, MessageboxDlg.Button, Meta, Nobr, North, North, NumberInputElement, Object, Ol, Optgroup, Option, P, Paging, Panel, Panelchildren, Popup, Portalchildren, Portallayout, Pre, Progressmeter, Q, Radio, Radiogroup, Raw, Row, Rows, S, Samp, Script, Script, Select, Separator, Slider, Small, South, South, Space, Span, Span, Spinner, Splitter, Strong, Style, Style, Sub, Sup, Tab, Tabbox, Table, Tablechildren, Tablelayout, Tabpanel, Tabpanels, Tabs, Tbody, Td, Text, Textarea, Textbox, Tfoot, Th, Thead, Timebox, Timer, Title, Toolbar, Toolbarbutton, Tr, Transformer, Tree, Treecell, Treechildren, Treecol, Treecols, Treefoot, Treefooter, Treeitem, Treerow, Tt, Ul, Var, Vbox, West, West, Window, XmlMacroComponent, XmlNativeComponent, XulElement, Zkhead

public interface Component
extends Scope, java.io.Serializable, java.lang.Cloneable

An UI component.

There are two kind of lifecycles: one is page creations and the other is asynchronous updates.

The Page Creation

The page creation occurs when a page is about to render at the first time. The detailed phases can be found in the devloper's guide.

The Asynchronous Update

The asynchronous update occurs when users does something on the browser, such as changing the content of input, clicking buttons and so on. Such behaviors are packed as requests, queue in the browser, and then send to the server at the proper time. The detailed phases can be found in the developer's guide.

No Synchronization Required

To simplify the development of components and applications, invocations of methods of components and event listener are all serialized. In other words, application and component developers need not worry synchronization and other thread issues (unless you are developing background thread to handle long operations).

It also implies a limitation that you cannot access components belonging to other desktops when processing an event.

Author:
tomyeh

Field Summary
static int APPLICATION_SCOPE
          Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the whole application.
static int COMPONENT_SCOPE
          Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes private to a component is searched.
static int DESKTOP_SCOPE
          Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the same desktop.
static int PAGE_SCOPE
          Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the same page.
static int REQUEST_SCOPE
          Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the same request.
static int SESSION_SCOPE
          Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the same session.
static int SPACE_SCOPE
          Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the same ID space.
 
Method Summary
 boolean addEventListener(java.lang.String evtnm, EventListener listener)
          Adds an event listener to specified event for this component.
 boolean addForward(java.lang.String originalEvent, Component target, java.lang.String targetEvent)
          Adds a forward condition to forward the event received by this component to another component.
 boolean addForward(java.lang.String originalEvent, Component target, java.lang.String targetEvent, java.lang.Object eventData)
          Adds a forward condition to forward the event received by this component to another component with extra event data.
 boolean addForward(java.lang.String originalEvent, java.lang.String targetPath, java.lang.String targetEvent)
          Adds a forward condition to forward the event received by this component to another component, specified with a path.
 boolean addForward(java.lang.String originalEvent, java.lang.String targetPath, java.lang.String targetEvent, java.lang.Object eventData)
          Adds a forward condition to forward the event received by this component to another component of the specified path with extra event data.
 boolean appendChild(Component child)
          Appends a child.
 void applyProperties()
          Initializes the properties (aka. members) and custom-attributes based on what are defined in the component definition.
 java.lang.Object clone()
          Clones the component.
 boolean containsVariable(java.lang.String name, boolean local)
          Deprecated. As of release 5.0.0, replaced with hasAttributeOrFellow(java.lang.String, boolean).

Returns whether the specified variable is defined.

 void detach()
          Detaches this component such that it won't belong to any page.
 java.lang.Object getAttribute(java.lang.String name)
          Returns the custom attribute associated with this component, i.e., COMPONENT_SCOPE.
 java.lang.Object getAttribute(java.lang.String name, int scope)
          Returns the value of the specified custom attribute in the specified scope, or null if not defined.
 java.lang.Object getAttributeOrFellow(java.lang.String name, boolean recurse)
          Returns the custom attribute associated with this component, or the fellow of this component; or null if not found.
 java.util.Map getAttributes()
          Returns all custom attributes associated with this component, i.e., COMPONENT_SCOPE.
 java.util.Map getAttributes(int scope)
          Returns all custom attributes of the specified scope.
 AuService getAuService()
          Returns an AU service to process the AU request before the component's default handling.
 java.util.List getChildren()
          Returns a live list of children.
 ComponentDefinition getDefinition()
          Returns the component definition of this component (never null).
 Desktop getDesktop()
          Returns the desktop of this component, or null if this component doesn't belong to any desktop.
 Component getFellow(java.lang.String id)
          Returns a component of the specified ID in the same ID space.
 Component getFellow(java.lang.String id, boolean recurse)
          Returns a component of the specified ID in the same ID space.
 Component getFellowIfAny(java.lang.String id)
          Returns a component of the specified ID in the same ID space, or null if not found.
 Component getFellowIfAny(java.lang.String id, boolean recurse)
          Returns a component of the specified ID in the same ID space, or null if not found.
 java.util.Collection getFellows()
          Returns all fellows in the same ID space of this component.
 Component getFirstChild()
          Returns the first child component, or null if no child at all.
 java.lang.String getId()
          Returns the ID.
 Component getLastChild()
          Returns the last child component, or null if no child at all.
 java.util.Iterator getListenerIterator(java.lang.String evtnm)
          Returns an iterator for iterating listener for the specified event.
 java.lang.String getMold()
          Returns the mold used to render this component.
 Namespace getNamespace()
          Deprecated. As of release 5.0.0, the concept of namespace is replaced with attributes.

Returns the namespace to store variables and functions belonging to the ID space of this component.

Exactly one namespace is allocated for each ID space. For example, if the space owner of this component is the page, then the returned namespace is the same as Page.getNamespace(). Otherwise, it is the same as the namspace returned by the component owning this ID space.

 Component getNextSibling()
          Returns the next sibling, or null if it is the last child.
 Page getPage()
          Returns the page that this component belongs to, or null if it doesn't belong to any page.
 Component getParent()
          Returns the parent component, or null if this is the root component.
 Component getPreviousSibling()
          Returns the previous sibling, or null if it is the first child.
 Component getRoot()
          Returns the root of this component.
 IdSpace getSpaceOwner()
          Returns the owner of the ID space that this component belongs to.
 java.lang.String getUuid()
          Returns UUID (universal unique ID) which is unquie in the whole session.
 java.lang.Object getVariable(java.lang.String name, boolean local)
          Deprecated. As of release 5.0.0, replaced with getAttributeOrFellow(java.lang.String, boolean).

Returns the value of a variable defined in the namespace, or null if not defined or the value is null.

 java.lang.String getWidgetClass()
          Returns the widget class (aka., the widget type), or null if not available.
 java.lang.String getWidgetListener(java.lang.String evtnm)
          Returns the script of the client event, or null if not found.
 java.util.Set getWidgetListenerNames()
          Returns a readonly collection of event names (String) that the listener of the peer widget are assigned, or an empty collection if none is registered.
 java.lang.String getWidgetOverride(java.lang.String name)
          Returns the script of the method definition to override widget's method, or null if not found.
 java.util.Set getWidgetOverrideNames()
          Returns a readonly collection of the property names (String) that shall be overriden, or an empty collection if none is registered.
 boolean hasAttribute(java.lang.String name)
          Returns if the custom attribute is associate with this component.
 boolean hasAttribute(java.lang.String name, int scope)
          Returns if the custom attribute is associate with this component.
 boolean hasAttributeOrFellow(java.lang.String name, boolean recurse)
          Returns if a custom attribute is associated with this component, or the fellow of this component.
 boolean hasFellow(java.lang.String compId)
          Returns whether a fellow exists in the same ID space of this component.
 boolean hasFellow(java.lang.String id, boolean recurse)
          Returns whether there is a fellow named with the specified component ID in the same ID space as this component.
 boolean insertBefore(Component newChild, Component refChild)
          Inserts a child before the reference child.
 void invalidate()
          Invalidates this component by setting the dirty flag such that it will be redraw the whole content of this component and its decendances later.
 boolean isInvalidated()
          Returns if this component needs to be redrawn at the client.
 boolean isListenerAvailable(java.lang.String evtnm, boolean asap)
          Returns whether the event listener is available.
 boolean isVisible()
          Returns whether this component is visible.
 java.lang.Object removeAttribute(java.lang.String name)
          Removes the custom attribute associated with this component, i.e., COMPONENT_SCOPE.
 java.lang.Object removeAttribute(java.lang.String name, int scope)
          Removes the specified custom attribute in the specified scope.
 boolean removeChild(Component child)
          Removes a child.
 boolean removeEventListener(java.lang.String evtnm, EventListener listener)
          Removes an event listener.
 boolean removeForward(java.lang.String originalEvent, Component target, java.lang.String targetEvent)
          Removes a forward condition that was added by addForward(String, Component, String).
 boolean removeForward(java.lang.String originalEvent, java.lang.String targetPath, java.lang.String targetEvent)
          Removes a forward condition that was added by addForward(String, String, String).
 java.lang.Object setAttribute(java.lang.String name, java.lang.Object value)
          Sets the custom attribute associated with this component, i.e., COMPONENT_SCOPE.
 java.lang.Object setAttribute(java.lang.String name, java.lang.Object value, int scope)
          Sets the value of the specified custom attribute in the specified scope.
 void setAuService(AuService service)
          Sets an AU service to process the AU request before the component's default handling.
 void setId(java.lang.String id)
          Sets the ID.
 void setMold(java.lang.String mold)
          Sets the mold to render this component.
 void setPage(Page page)
          Sets what page this component belongs to.
 void setPageBefore(Page page, Component refRoot)
          Sets what page this component belongs to, and insert this component right before the reference component.
 void setParent(Component parent)
          Sets the parent component.
 void setVariable(java.lang.String name, java.lang.Object val, boolean local)
          Deprecated. As of release 5.0.0, replaced with setAttribute(java.lang.String, java.lang.Object, int).

Sets a variable to the namespace.

Once a variable is set thru this method, it is visible to both the interpreter and EL.

Note: Exactly one namespace is allocated for each ID space. For example, if the space owner of this component is the page, then the returned namespace is the same as Page.getNamespace(). Otherwise, it is the same as the namspace returned by the component owning this ID space.

 boolean setVisible(boolean visible)
          Sets whether this component is visible.
 java.lang.String setWidgetListener(java.lang.String evtnm, java.lang.String script)
          Sets or removes an event listener of the peer widget.
 java.lang.String setWidgetOverride(java.lang.String name, java.lang.String script)
          Sets or removes the script of the method definition to override widget's method.
 void unsetVariable(java.lang.String name, boolean local)
          Deprecated. As of release 5.0.0, replaced with removeAttribute(java.lang.String, int).

Unsets a variable defined in the namespace.

 
Methods inherited from interface org.zkoss.zk.ui.ext.Scope
addScopeListener, getAttribute, hasAttribute, removeAttribute, removeScopeListener, setAttribute
 

Field Detail

COMPONENT_SCOPE

static final int COMPONENT_SCOPE
Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes private to a component is searched.

It is also known as the component attributes.

It is the same as getAttributes(int).

See Also:
Constant Field Values

SPACE_SCOPE

static final int SPACE_SCOPE
Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the same ID space.

It is also known as the ID space attributes.

See Also:
Constant Field Values

PAGE_SCOPE

static final int PAGE_SCOPE
Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the same page.

It is also known as the page attributes.

It is the same as Page.getAttributes(int).

See Also:
Constant Field Values

DESKTOP_SCOPE

static final int DESKTOP_SCOPE
Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the same desktop.

It is also known as the desktop attributes.

It is the same as Desktop.getAttributes().

See Also:
Constant Field Values

SESSION_SCOPE

static final int SESSION_SCOPE
Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the same session.

It is also known as the session attributes.

It is the same as Session.getAttributes().

See Also:
Constant Field Values

APPLICATION_SCOPE

static final int APPLICATION_SCOPE
Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the whole application.

It is also known as the application attributes.

It is the same as WebApp.getAttributes().

See Also:
Constant Field Values

REQUEST_SCOPE

static final int REQUEST_SCOPE
Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the same request.

It is also known as the request attributes.

It is the same as Execution.getAttributes().

See Also:
Constant Field Values
Method Detail

getWidgetClass

java.lang.String getWidgetClass()
Returns the widget class (aka., the widget type), or null if not available. The widget class is a JavaScript class, including the package name. For example, "zul.wnd.Window".

Note: for Ajax devices, the widget class must be non-null.

Since:
5.0.0

getDefinition

ComponentDefinition getDefinition()
Returns the component definition of this component (never null).


getSpaceOwner

IdSpace getSpaceOwner()
Returns the owner of the ID space that this component belongs to. The returned value could be a component, a page or null. If this component itself implements IdSpace, this method returns itself. If it has an ancestor that implements IdSpace, the ancestor is returned. Otherwise, the page it belongs to is returned

Each ID space defines an independent set of IDs. No component in the same ID space could have the same ID. To get any component in the same ID space, you could use getFellow(java.lang.String). See IdSpace for more details.

The ID space relevant methods include getFellow(java.lang.String), getAttribute(java.lang.String, int) and getAttributeOrFellow(java.lang.String, boolean).

See Also:
getNamespace()

getId

java.lang.String getId()
Returns the ID. If it is a root component (i.e., without parent), its ID must be unquie among root components of the same page.

If a component belongs to an ID space (see IdSpace), the ID must also be unique in the ID space it belongs. any its parent and ancestor implements IdSpace.

A page itself is also an ID space, so you could retrieve compnents in a page by use of IdSpace.getFellow(java.lang.String), unless the component is a descendant of another component that implements IdSpace. In this case, you have to retrieve the parent first (by use of IdSpace.getFellow(java.lang.String) and then use getFellow(java.lang.String) against the owner of the ID space.

In zscript and EL, a component with explicit ID can be accessed directly by the ID. In other word, a variable named by the ID is created automatically.

See Also:
Page

setId

void setId(java.lang.String id)
Sets the ID. The scope of uniqunes depends on whether this component is a root component. Refer to getId() for more details.

When a component is constructed, an ID is generated automatically. Thus, calling this method only you need to identify a component.

Parameters:
id - the identifier. It cannot be empty. If null, it means the previous ID is removed (aka., reset) and an anonymous ID is assigned.
See Also:
Page

getDesktop

Desktop getDesktop()
Returns the desktop of this component, or null if this component doesn't belong to any desktop.

When a component is created in an event listener, it is assigned to the current desktop automatically. If a component is created not in any event listener, it doesn't belong to any desktop and this method returns null. Once a component is attached to a desktop (thru setPage(org.zkoss.zk.ui.Page) or setParent(org.zkoss.zk.ui.Component)), it belongs to the desktop.

Notice: there is no way to detach a component from a desktop, once it is attached as described above. In other words, you cannot move a component (or page) from one desktop to another.

In summary, there are only two ways to handle components.

  1. Handle them all in event listeners and don't access any components from other desktops. This is simplest and clearest.
  2. Creates components in another thread (other than event listener) and attach them to a page (and then desktop) upon an event is received.


getPage

Page getPage()
Returns the page that this component belongs to, or null if it doesn't belong to any page.

When a component is created (aka., constructed), it doesn't belong to any page. And, if a component doesn't belong to any page, they won't be displayed at the client.

When changing parent (setParent(org.zkoss.zk.ui.Component)), the child component's page will become the same as parent's. In other words, a component is added to a page automatically if it becomes a child of another component (who belongs to a page).

For root components, you have to invoke setPage(org.zkoss.zk.ui.Page) explicityly.

See Also:
setParent(org.zkoss.zk.ui.Component), setPage(org.zkoss.zk.ui.Page)

setPage

void setPage(Page page)
Sets what page this component belongs to. If this component already belongs to the same page, nothing is changed.

For child components, the page they belong is maintained automatically. You need to invoke this method only for root components.

Note: a component might be attached to a page due invocations other than this method. For example, a component is attached if its parent is attached. To know whether it is attached, override ComponentCtrl.onPageAttached(org.zkoss.zk.ui.Page, org.zkoss.zk.ui.Page) rather than this method.

See Also:
ComponentCtrl.onPageAttached(org.zkoss.zk.ui.Page, org.zkoss.zk.ui.Page), ComponentCtrl.onPageDetached(org.zkoss.zk.ui.Page)

setPageBefore

void setPageBefore(Page page,
                   Component refRoot)
Sets what page this component belongs to, and insert this component right before the reference component.

For child components, the page they belong is maintained automatically. You need to invoke this method only for root components.

It is similar to setPage(org.zkoss.zk.ui.Page), except this component will be placed before the reference component. If the reference component is null, this component is placed at the end of all root components.

Parameters:
refRoot - another root component used as a reference which this component will be placed before. If null, this component will be placed at the end of all root components (no matter whether it already belongs to the same page).
Since:
3.0.0
See Also:
setPage(org.zkoss.zk.ui.Page)

getUuid

java.lang.String getUuid()
Returns UUID (universal unique ID) which is unquie in the whole session. The UUID is generated automatically and immutable, unless RawId is also implemented.

It is mainly used for communication between client and server and you rarely need to access it.

If RawId is implemented as part of a component, UUID is the same as getId() if setId(java.lang.String) is ever called. It is designed to migrate HTML pages to ZK, such that the element ID could remain the same.


getFellow

Component getFellow(java.lang.String id)
Returns a component of the specified ID in the same ID space. Components in the same ID space are called fellows.

Unlike getFellowIfAny(java.lang.String), it throws an exception if not found.

Throws:
ComponentNotFoundException - is thrown if fellow not found

getFellowIfAny

Component getFellowIfAny(java.lang.String id)
Returns a component of the specified ID in the same ID space, or null if not found.

Unlike getFellow(java.lang.String), it returns null if not found.


getFellows

java.util.Collection getFellows()
Returns all fellows in the same ID space of this component. The returned collection is readonly.

Since:
3.0.6

hasFellow

boolean hasFellow(java.lang.String compId)
Returns whether a fellow exists in the same ID space of this component.

Since:
5.0.0

getFellow

Component getFellow(java.lang.String id,
                    boolean recurse)
                    throws ComponentNotFoundException
Returns a component of the specified ID in the same ID space. It is the same as getSpaceOwner().getFellow(id, recurse);

Unlike getFellowIfAny(String, boolean), it throws ComponentNotFoundException if not found.

Parameters:
recurse - whether to look up the parent ID space for the existence of the fellow
Throws:
ComponentNotFoundException - is thrown if this component doesn't belong to any ID space
Since:
5.0.0

getFellowIfAny

Component getFellowIfAny(java.lang.String id,
                         boolean recurse)
Returns a component of the specified ID in the same ID space, or null if not found. It is the same as getSpaceOwner().getFellowIfAny(id, recurse);

Unlike getFellow(String, boolean), it returns null if not found.

Parameters:
recurse - whether to look up the parent ID space for the existence of the fellow
Since:
5.0.0

hasFellow

boolean hasFellow(java.lang.String id,
                  boolean recurse)
Returns whether there is a fellow named with the specified component ID in the same ID space as this component. It is the same as getSpaceOwner().hasFellow(id, recurse);

Parameters:
recurse - whether to look up the parent ID space for the existence of the fellow
Since:
5.0.0

getNextSibling

Component getNextSibling()
Returns the next sibling, or null if it is the last child.

Since:
3.0.0

getPreviousSibling

Component getPreviousSibling()
Returns the previous sibling, or null if it is the first child.

Since:
3.0.0

getFirstChild

Component getFirstChild()
Returns the first child component, or null if no child at all.

Since:
3.0.0

getLastChild

Component getLastChild()
Returns the last child component, or null if no child at all.

Since:
3.0.0

getAttributes

java.util.Map getAttributes(int scope)
Returns all custom attributes of the specified scope. You could reference them thru componentScope, spaceScope, pageScope, requestScope and desktopScope in zscript and EL.

If scope is COMPONENT_SCOPE, it means custom attributes private to this component.

If scope is SPACE_SCOPE, it means custom attributes shared by components from the same ID space as this one's.

If scope is PAGE_SCOPE, it means custom attributes shared by components from the same page as this one's.

If scope is DESKTOP_SCOPE, it means custom attributes shared by components from the same desktopas this one's.

Parameters:
scope - COMPONENT_SCOPE, SPACE_SCOPE, PAGE_SCOPE, DESKTOP_SCOPE, SESSION_SCOPE, REQUEST_SCOPE or APPLICATION_SCOPE,

getAttribute

java.lang.Object getAttribute(java.lang.String name,
                              int scope)
Returns the value of the specified custom attribute in the specified scope, or null if not defined.

If scope is COMPONENT_SCOPE, it means attributes private to this component.

If scope is SPACE_SCOPE, it means custom attributes shared by components from the same ID space as this one's.

If scope is PAGE_SCOPE, it means custom attributes shared by components from the same page as this one's.

If scope is DESKTOP_SCOPE, it means custom attributes shared by components from the same desktopas this one's.

Parameters:
scope - COMPONENT_SCOPE, SPACE_SCOPE, PAGE_SCOPE, DESKTOP_SCOPE, SESSION_SCOPE, REQUEST_SCOPE or APPLICATION_SCOPE,

hasAttribute

boolean hasAttribute(java.lang.String name,
                     int scope)
Returns if the custom attribute is associate with this component.

If scope is COMPONENT_SCOPE, it means attributes private to this component.

If scope is SPACE_SCOPE, it means custom attributes shared by components from the same ID space as this one's.

If scope is PAGE_SCOPE, it means custom attributes shared by components from the same page as this one's.

If scope is DESKTOP_SCOPE, it means custom attributes shared by components from the same desktopas this one's.

Notice that null is a valid value, so you can tell if an attribute is assoicated by examining the return value of getAttribute(java.lang.String, int).

Parameters:
scope - COMPONENT_SCOPE, SPACE_SCOPE, PAGE_SCOPE, DESKTOP_SCOPE, SESSION_SCOPE, REQUEST_SCOPE or APPLICATION_SCOPE,
Since:
5.0.0

setAttribute

java.lang.Object setAttribute(java.lang.String name,
                              java.lang.Object value,
                              int scope)
Sets the value of the specified custom attribute in the specified scope.

Note: The attribute is removed (by removeAttribute(java.lang.String, int) if value is null, while setVariable(java.lang.String, java.lang.Object, boolean) considers null as a legal value.

If scope is COMPONENT_SCOPE, it means custom attributes private to this component.

If scope is SPACE_SCOPE, it means custom attributes shared by components from the same ID space as this one's.

If scope is PAGE_SCOPE, it means custom attributes shared by components from the same page as this one's.

If scope is DESKTOP_SCOPE, it means custom attributes shared by components from the same desktopas this one's.

Parameters:
scope - COMPONENT_SCOPE, SPACE_SCOPE, PAGE_SCOPE, DESKTOP_SCOPE, SESSION_SCOPE, REQUEST_SCOPE or APPLICATION_SCOPE,
value - the value. If null, the attribute is removed.

removeAttribute

java.lang.Object removeAttribute(java.lang.String name,
                                 int scope)
Removes the specified custom attribute in the specified scope.

If scope is COMPONENT_SCOPE, it means attributes private to this component.

If scope is SPACE_SCOPE, it means custom attributes shared by components from the same ID space as this one's.

If scope is PAGE_SCOPE, it means custom attributes shared by components from the same page as this one's.

If scope is DESKTOP_SCOPE, it means custom attributes shared by components from the same desktopas this one's.

Parameters:
scope - COMPONENT_SCOPE, SPACE_SCOPE, PAGE_SCOPE, DESKTOP_SCOPE, SESSION_SCOPE, REQUEST_SCOPE or APPLICATION_SCOPE,

getAttributes

java.util.Map getAttributes()
Returns all custom attributes associated with this component, i.e., COMPONENT_SCOPE.

Specified by:
getAttributes in interface Scope

getAttribute

java.lang.Object getAttribute(java.lang.String name)
Returns the custom attribute associated with this component, i.e., COMPONENT_SCOPE.

Specified by:
getAttribute in interface Scope

hasAttribute

boolean hasAttribute(java.lang.String name)
Returns if the custom attribute is associate with this component.

Notice that null is a valid value, so you can tell if an attribute is assoicated by examining the return value of getAttribute(java.lang.String, int).

Specified by:
hasAttribute in interface Scope
Since:
5.0.0

setAttribute

java.lang.Object setAttribute(java.lang.String name,
                              java.lang.Object value)
Sets the custom attribute associated with this component, i.e., COMPONENT_SCOPE.

Specified by:
setAttribute in interface Scope
Returns:
the previous value associated with the attribute, if any

removeAttribute

java.lang.Object removeAttribute(java.lang.String name)
Removes the custom attribute associated with this component, i.e., COMPONENT_SCOPE.

Specified by:
removeAttribute in interface Scope
Returns:
the previous value associated with the attribute, if any,

getAttributeOrFellow

java.lang.Object getAttributeOrFellow(java.lang.String name,
                                      boolean recurse)
Returns the custom attribute associated with this component, or the fellow of this component; or null if not found.

Notice that it doesn't check any variable defined in VariableResolver (of Page.addVariableResolver(org.zkoss.xel.VariableResolver)).

Parameters:
recurse - whether to look up the parent component for the existence of the attribute.
Notice that, if recurse is false and this component is not an ID space owner, it won't look at the fellow.
If recurse is true, it will look up all parents, page, desktop, session and application until found. If any of them is a space owner, the fellows will be searched.
Since:
5.0.0

hasAttributeOrFellow

boolean hasAttributeOrFellow(java.lang.String name,
                             boolean recurse)
Returns if a custom attribute is associated with this component, or the fellow of this component.

Notice that it doesn't check any variable defined in VariableResolver (of Page.addVariableResolver(org.zkoss.xel.VariableResolver)).

Parameters:
recurse - whether to look up the parent component for the existence of the attribute.
Notice that, if recurse is false and this component is not an ID space owner, it won't look at the fellow.
If recurse is true, it will look up all parents, page, desktop, session and application until found. If any of them is a space owner, the fellows will be searched.
Since:
5.0.0

setVariable

void setVariable(java.lang.String name,
                 java.lang.Object val,
                 boolean local)
Deprecated. As of release 5.0.0, replaced with setAttribute(java.lang.String, java.lang.Object, int).

Sets a variable to the namespace.

Once a variable is set thru this method, it is visible to both the interpreter and EL.

Note: Exactly one namespace is allocated for each ID space. For example, if the space owner of this component is the page, then the returned namespace is the same as Page.getNamespace(). Otherwise, it is the same as the namspace returned by the component owning this ID space.

Parameters:
local - whether not to search any of the ancestor namespace defines the variable. If local is false and an ancesotor has defined a variable with the same name, the variable in the ancestor is changed directly. Otherwise, a new variable is created in the namespace containing this component.

containsVariable

boolean containsVariable(java.lang.String name,
                         boolean local)
Deprecated. As of release 5.0.0, replaced with hasAttributeOrFellow(java.lang.String, boolean).

Returns whether the specified variable is defined.

Parameters:
local - whether not to search its ancestor. If false and the current namespace doen't define the variable, it searches up its ancestor (via getParent()) to see any of them has defined the specified variable.

getVariable

java.lang.Object getVariable(java.lang.String name,
                             boolean local)
Deprecated. As of release 5.0.0, replaced with getAttributeOrFellow(java.lang.String, boolean).

Returns the value of a variable defined in the namespace, or null if not defined or the value is null.

Parameters:
local - whether not to search its ancestor. If false and the current namespace doen't define the variable, it searches up its ancestor (via getParent()) to see any of them has defined the specified variable.

unsetVariable

void unsetVariable(java.lang.String name,
                   boolean local)
Deprecated. As of release 5.0.0, replaced with removeAttribute(java.lang.String, int).

Unsets a variable defined in the namespace.

Parameters:
local - whether not to search its ancestor. If false and the current namespace doen't define the variable, it searches up its ancestor (via getParent()) to see any of them has defined the specified variable.

getParent

Component getParent()
Returns the parent component, or null if this is the root component.


setParent

void setParent(Component parent)
Sets the parent component.

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


getChildren

java.util.List getChildren()
Returns a live list of children. You could add or remove a child by manipulating the returned list directly.


getRoot

Component getRoot()
Returns the root of this component.


isVisible

boolean isVisible()
Returns whether this component is visible.

See Also:
Components.isRealVisible(org.zkoss.zk.ui.Component)

setVisible

boolean setVisible(boolean visible)
Sets whether this component is visible.

Returns:
the previous visibility

insertBefore

boolean insertBefore(Component newChild,
                     Component refChild)
Inserts a child before the reference child.

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

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

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.

appendChild

boolean appendChild(Component child)
Appends a child. A shortcut to insertBefore(child, null).

See Also:
insertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component)

removeChild

boolean removeChild(Component child)
Removes a child. The child is not actually removed. Rather, it is detached (see detach()) and it will be removed if it is no longer used.

You could use setParent(org.zkoss.zk.ui.Component) with null instead of this method.

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

Returns:
true if child is removed successfully; false if it doesn't have the specified child

detach

void detach()
Detaches this component such that it won't belong to any page. If you don't call setParent(org.zkoss.zk.ui.Component) or setPage(org.zkoss.zk.ui.Page) to attach it to any page, it will be removed automatically (from the client) after the current event is processed.


getMold

java.lang.String getMold()
Returns the mold used to render this component.

Default: "default"

Since 5.0, the default can be overriden by specify a library property. For example, if the component's class name is org.zkoss.zul.Button, then you can override the default mold by specifying the property called "org.zkoss.zul.Button.mold" with the mold you want in zk.xml. For example,

<library-property>
  <name>org.zkoss.zul.Button.mold</name>
  <value>trendy</value>
</library-property>

Notice that it doesn't affect the deriving classes. If you want to change the deriving class's default mold, you have to specify them explicity, too.

See Also:
ComponentDefinition

setMold

void setMold(java.lang.String mold)
Sets the mold to render this component.

Parameters:
mold - the mold. If null or empty, "default" is assumed.
See Also:
ComponentDefinition

addEventListener

boolean addEventListener(java.lang.String evtnm,
                         EventListener listener)
Adds an event listener to specified event for this component. The second registration is ignored and false is returned.

You could register listener to all components in the same page by use of Page.addEventListener(java.lang.String, org.zkoss.zk.ui.event.EventListener).

Parameters:
evtnm - what event to listen (never null)
Returns:
whether the listener is added; false if it was added before
See Also:
Page.addEventListener(java.lang.String, org.zkoss.zk.ui.event.EventListener)

removeEventListener

boolean removeEventListener(java.lang.String evtnm,
                            EventListener listener)
Removes an event listener.

Returns:
whether the listener is removed; false if it was never added.

isListenerAvailable

boolean isListenerAvailable(java.lang.String evtnm,
                            boolean asap)
Returns whether the event listener is available.

Unlike Events.isListened(org.zkoss.zk.ui.Component, java.lang.String, boolean), this method checks only the event listener registered by addEventListener(java.lang.String, org.zkoss.zk.ui.event.EventListener).

Parameters:
asap - whether to check only non-deferrable listener, i.e., not implementing Deferrable, or Deferrable.isDeferrable() is false.
See Also:
Deferrable, Events.isListened(org.zkoss.zk.ui.Component, java.lang.String, boolean), addEventListener(java.lang.String, org.zkoss.zk.ui.event.EventListener)

getListenerIterator

java.util.Iterator getListenerIterator(java.lang.String evtnm)
Returns an iterator for iterating listener for the specified event.

Since 3.6.3, the listener can be removed directly by invoking Iterator.remove().


addForward

boolean addForward(java.lang.String originalEvent,
                   Component target,
                   java.lang.String targetEvent)
Adds a forward condition to forward the event received by this component to another component.

Default: no forward condition at all.

Once the condition is added, a event called targetEvent is posted to the target compoennt, when this component receives the orginalEvent event.

Parameters:
originalEvent - the original event that was received by this component. If null, "onClick" is assumed.
target - the target component to receive the event. If null, the space owner getSpaceOwner() is assumed. If null and the space owner is the page, the root component is assumed.
targetEvent - the target event that the target component will receive. If null, it is the same as the original event.
Returns:
whether it is added successfully. It returns false if the conditioin was always added before.
Since:
3.0.0
See Also:
removeForward(String, Component, String), addForward(String, Component, String, Object)

addForward

boolean addForward(java.lang.String originalEvent,
                   java.lang.String targetPath,
                   java.lang.String targetEvent)
Adds a forward condition to forward the event received by this component to another component, specified with a path.

Note: the target component is retrieved from the path, each time the event is received. Thus, you can reference to a component that is created later.

Parameters:
originalEvent - the original event that was received by this component. If null, "onClick" is assumed.
targetPath - the target component's path related to this component. If ".", this component is assumed. If null, the space owner is assumed. If null and the space owner is the page, the root component is assumed.
targetEvent - the target event that the target component will receive. If null, it is the same as the original event.
Returns:
whether it is added successfully. It returns false if the conditioin was always added before.
Since:
3.0.0
See Also:
addForward(String, Component, String), removeForward(String, String, String)

addForward

boolean addForward(java.lang.String originalEvent,
                   Component target,
                   java.lang.String targetEvent,
                   java.lang.Object eventData)
Adds a forward condition to forward the event received by this component to another component with extra event data.

Parameters:
eventData - the extra data that can be retrieve by Event.getData().
Since:
3.0.6
See Also:
addForward(String, Component, String)

addForward

boolean addForward(java.lang.String originalEvent,
                   java.lang.String targetPath,
                   java.lang.String targetEvent,
                   java.lang.Object eventData)
Adds a forward condition to forward the event received by this component to another component of the specified path with extra event data.

Parameters:
eventData - the extra data that can be retrieve by Event.getData().
Since:
3.0.6
See Also:
addForward(String, String, String)

removeForward

boolean removeForward(java.lang.String originalEvent,
                      Component target,
                      java.lang.String targetEvent)
Removes a forward condition that was added by addForward(String, Component, String). If no such forward condition exists, nothing happens but return false.

Parameters:
originalEvent - the oringal event that was received by this component. It must be the same as the one passed to addForward(String, Component, String).
target - the target component to receive the event. It must be the same as the one passed to addForward(String, Component, String).
targetEvent - the target event that the target component will receive. It must be the same as the one passed to addForward(String, Component, String).
Returns:
whether the forward is removed successfully. It returns false if the forward condition is not found
Since:
3.0.0
See Also:
addForward(String, Component, String)

removeForward

boolean removeForward(java.lang.String originalEvent,
                      java.lang.String targetPath,
                      java.lang.String targetEvent)
Removes a forward condition that was added by addForward(String, String, String). If no such forward condition exists, nothing happens but return false.

Parameters:
originalEvent - the oringal event that was received by this component. It must be the same as the one passed to addForward(String, Component, String).
targetPath - the target component's path related to this component. If ".", this component is assumed. If null, the space owner is assumed. If null and the space owner is the page, the root component is assumed.
targetEvent - the target event that the target component will receive. It must be the same as the one passed to addForward(String, Component, String).
Returns:
whether the forward is removed successfully. It returns false if the forward condition is not found
Since:
3.0.0
See Also:
addForward(String, String, String)

isInvalidated

boolean isInvalidated()
Returns if this component needs to be redrawn at the client.

Application developers rarely need to call this method.

Note:

  1. It always returns true if it doesn't belong to any page (since redraw is required if it is attached to a page later).
  2. It always returns true if the current execution is not an asynchroous update (so redrawn is always required).
  3. If its parent is invalidated, this component will be redrawn too, but this method returns false if invalidate() was not called against this component.

Since:
3.0.5

invalidate

void invalidate()
Invalidates this component by setting the dirty flag such that it will be redraw the whole content of this component and its decendances later. And, the widget associated with this component and all its descendant at the client will be deleted and recreated, too.

If the application is totally controlled by the server side (i.e., you don't write client codes), you rarely need to access this method.

It can be called only in the request-processing and event-processing phases. However, it is NOT allowed in the rendering phase.


getNamespace

Namespace getNamespace()
Deprecated. As of release 5.0.0, the concept of namespace is replaced with attributes.

Returns the namespace to store variables and functions belonging to the ID space of this component.

Exactly one namespace is allocated for each ID space. For example, if the space owner of this component is the page, then the returned namespace is the same as Page.getNamespace(). Otherwise, it is the same as the namspace returned by the component owning this ID space.


applyProperties

void applyProperties()
Initializes the properties (aka. members) and custom-attributes based on what are defined in the component definition.

This method is invoked automatically if a component is created by evaluating a ZUML page, i.e., if it is specified as an elemnt of a ZUML page.

On the other hand, if it is created manually (by program), developer might choose to invoke this method or not, depending whether he wants to initializes the component with the properties and custom-attributes defined in the ZUML page (PageDefinition) and the language definition (LanguageDefinition).


setWidgetListener

java.lang.String setWidgetListener(java.lang.String evtnm,
                                   java.lang.String script)
Sets or removes an event listener of the peer widget. If there is an event listener associated with the same event, the previous one will be replaced and returned.

Parameters:
evtnm - the event name, such as onClick
script - the script to handle the event. If null, the event handler is removed.
Returns:
the previous script if any
Since:
5.0.0

getWidgetListener

java.lang.String getWidgetListener(java.lang.String evtnm)
Returns the script of the client event, or null if not found.

Since:
5.0.0

getWidgetListenerNames

java.util.Set getWidgetListenerNames()
Returns a readonly collection of event names (String) that the listener of the peer widget are assigned, or an empty collection if none is registered.

Since:
5.0.0

setWidgetOverride

java.lang.String setWidgetOverride(java.lang.String name,
                                   java.lang.String script)
Sets or removes the script of the method definition to override widget's method. If there is a method associated with the same name, the previous one will be replaced and returned.

Notice that, unlike setWidgetListener(java.lang.String, java.lang.String), if the method has been sent to the client for update, it cannot be removed by calling this method with a null script. In other words, invoking this method with a null script only removes the method overrides if it has not YET been to sent to the client.

The previous method can be accessed by this.$xxx. For example

function (value, fromServer) {
  this.$setValue(value, fromServer);
  if (this.desktop) {
    this._cnt = !this._cnt;
    this.setStyle('background:'+(this._cnt ? 'red':'green'));
  }
}

Notice that, since it is not extending, so this.$super references the superclass's method, rather than the old method.

Parameters:
name - the property name to override, such as setValue and miles.
script - the method definition, such as function (arg) {...}, or a value, such as 123 and new Date(). If not null, this method will be added to the peer widget. If there was a method with the same name, it will be renamed to $name so can you call it back.
<label w:setValue="function (value) {
  this.$setValue(value); //old method
}"/>
If null, the previous method, if any, will be stored.
Returns:
the previous script if any
Since:
5.0.0

getWidgetOverride

java.lang.String getWidgetOverride(java.lang.String name)
Returns the script of the method definition to override widget's method, or null if not found.

Since:
5.0.0

getWidgetOverrideNames

java.util.Set getWidgetOverrideNames()
Returns a readonly collection of the property names (String) that shall be overriden, or an empty collection if none is registered.

Since:
5.0.0

setAuService

void setAuService(AuService service)
Sets an AU service to process the AU request before the component's default handling. This method is used if you want to send some custom request from client (by your application).

Default: null.

If you want to provide an AU service for the AU requests targeting the desktop. Use Desktop.addListener(java.lang.Object).

See also how to process data with JSON.

Since:
5.0.0

getAuService

AuService getAuService()
Returns an AU service to process the AU request before the component's default handling.

Default: null

Since:
5.0.0

clone

java.lang.Object clone()
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.



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