org.zkoss.zk.ui
Class AbstractComponent

java.lang.Object
  org.zkoss.zk.ui.AbstractComponent

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Component, ComponentCtrl

Direct Known Subclasses:

HtmlBasedComponent, HtmlNativeComponent

public class AbstractComponent
extends java.lang.Object
implements Component, ComponentCtrl, java.io.Serializable

A skeletal implementation of Component. Though it is OK to implement Component from scratch, this class simplifies some of the chores.

Author:

tomyeh

See Also:

Serialized Form

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

Constructor Summary

protected

AbstractComponent() Constructs a component with auto-generated ID.

Method Summary

void	addAnnotation(java.lang.String annotName, java.util.Map annotAttrs) Associates an annotation to this component.
void	addAnnotation(java.lang.String propName, java.lang.String annotName, java.util.Map annotAttrs) Adds an annotation to the specified proeprty of this component.
void	addEventHandler(java.lang.String name, EventHandler evthd) Adds an event handler.
boolean	addEventListener(java.lang.String evtnm, EventListener listener) Adds an event listener to specified event for this component.
boolean	addForward(java.lang.String orgEvent, 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 orgEvent, 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.
protected void	addMoved(Component oldparent, Page oldpg, Page newpg) Called when this component is moved from the specified parent and/or page to the new page.
void	addSharedAnnotationMap(AnnotationMap annots) Add a map of annotations which is shared by other components.
void	addSharedEventHandlerMap(EventHandlerMap evthds) Adds a map of event handlers which is shared by other components.
protected java.lang.StringBuffer	appendAsapAttr(java.lang.StringBuffer sb, java.lang.String evtnm) Appends an attribute for the specified event name, say, onChange, if a non-deferrable listener is registered.
boolean	appendChild(Component child) Appends a child to the end of all children.
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) Returns whether the specified variable is defined.
void	detach() Detaches this component such that it won't belong to any page.
boolean	equals(java.lang.Object o)
java.util.List	getAnnotatedProperties() Returns a read-only list of the name (String) of properties that are associated at least one annotation (never null).
java.util.List	getAnnotatedPropertiesBy(java.lang.String annotName) Returns a read-only list of the names (String) of the properties that are associated with the specified annotation (never null).
Annotation	getAnnotation(java.lang.String annotName) Returns the annotation associated with the component, or null if not available.
Annotation	getAnnotation(java.lang.String propName, java.lang.String annotName) Returns the annotation associated with the definition of the specified property, or null if not available.
java.util.Collection	getAnnotations() Returns a read-only collection of all annotations associated with this component (never null).
java.util.Collection	getAnnotations(java.lang.String propName) Returns a read-only collection of all annotations associated with the specified property (never null).
java.lang.Object	getAttribute(java.lang.String name) Returns the custom attribute associated with this component, i.e., Component.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.util.Map	getAttributes() Returns all custom attributes associated with this component, i.e., Component.COMPONENT_SCOPE.
java.util.Map	getAttributes(int scope) Returns all custom attributes of the specified scope.
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.
ZScript	getEventHandler(java.lang.String evtnm) Returns the event handler of the specified name, or null if not found.
java.lang.Object	getExtraCtrl() Returns the extra controls that tell ZK how to handle this component specially.
Component	getFellow(java.lang.String compId) Returns a component of the specified ID in the same ID space.
Component	getFellowIfAny(java.lang.String compId) Returns a component of the specified ID in the same ID space, or null if not found.
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.
protected java.lang.Object	getMoldURI() Returns the mold URI based on getMold() and the molds defined in the component definition (ComponentDefinition).
Namespace	getNamespace() Returns the namespace to store variables and functions belonging to the ID space of this component.
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	getPropagatee(java.lang.String evtnm) Default: null (no propagation at all).
Component	getRoot() Returns the root of the specified 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) Returns the value of a variable defined in the namespace, or null if not defined or the value is null.
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 later.
protected boolean	isAsapRequired(java.lang.String evtnm) Returns whether to send back the request of the specified event immediately -- i.e., non-deferrable.
boolean	isChildable() Default: return true (allows to have children).
boolean	isListenerAvailable(java.lang.String evtnm, boolean asap) Returns whether the event listener is available.
boolean	isVisible() Returns whether this component is visible.
protected java.lang.Object	newExtraCtrl() Used by getExtraCtrl() to create a client control.
void	onChildAdded(Component child) Default: does nothing.
void	onChildRemoved(Component child) Default: does nothing.
void	onDrawNewChild(Component child, java.lang.StringBuffer out) Called when a new-created child is about to render.
void	onPageAttached(Page newpage, Page oldpage) Default: handles special event listeners.
void	onPageDetached(Page page) Default: handles special event listeners.
WrongValueException	onWrongValue(WrongValueException ex) Notifies that an WrongValueException instance is thrown, and WrongValueException.getComponent() is this component.
void	redraw(java.io.Writer out) Redraws this component.
java.lang.Object	removeAttribute(java.lang.String name) Removes the custom attribute associated with this component, i.e., Component.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 orgEvent, Component target, java.lang.String targetEvent) Removes a forward condition that was added by Component.addForward(String, Component, String).
boolean	removeForward(java.lang.String orgEvent, java.lang.String targetPath, java.lang.String targetEvent) Removes a forward condition that was added by Component.addForward(String, String, String).
void	response(java.lang.String key, AuResponse response) Causes a response (aka., a command) to be sent to the client.
void	sessionDidActivate(Page page) Notification that the session, which owns this component, has just been activated (aka., deserialized).
void	sessionWillPassivate(Page page) Notification that the session, which owns this component, is about to be passivated (aka., serialized).
java.lang.Object	setAttribute(java.lang.String name, java.lang.Object value) Sets the custom attribute associated with this component, i.e., Component.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	setComponentDefinition(ComponentDefinition compdef) Sets the component definition.
void	setId(java.lang.String id) Sets the ID.
void	setMold(java.lang.String mold) Sets the mold for 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) Sets a variable to the namespace.
boolean	setVisible(boolean visible) Sets whether this component is visible.
void	smartUpdate(java.lang.String attr, boolean value) A special smart-update that update a value in boolean.
void	smartUpdate(java.lang.String attr, int value) A special smart-update that update a value in int.
void	smartUpdate(java.lang.String attr, java.lang.String value) Smart-updates a property with the specified value.
java.lang.String	toString()
void	unsetVariable(java.lang.String name, boolean local) Unsets a variable defined in the namespace.

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractComponent

protected AbstractComponent()

Constructs a component with auto-generated ID.

Method Detail

getMoldURI

protected java.lang.Object getMoldURI()

Returns the mold URI based on getMold() and the molds defined in the component definition (ComponentDefinition).

As of release 3.0.0, it may return a String instance representing the URI, or a ComponentRenderer instance responsible for redrawing.

Used only for component implementation.

getPage

public final Page getPage()

Description copied from interface: Component

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 (Component.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 Component.setPage(org.zkoss.zk.ui.Page) explicityly.

Specified by:

getPage in interface Component

See Also:

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

getDesktop

public final Desktop getDesktop()

Description copied from interface: Component

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 Component.setPage(org.zkoss.zk.ui.Page) or Component.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.

Specified by:

getDesktop in interface Component

setPage

public void setPage(Page page)

Description copied from interface: Component

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.

Specified by:

setPage in interface Component

setPageBefore

public void setPageBefore(Page page,
                          Component refRoot)

Description copied from interface: Component

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

Specified by:

setPageBefore in interface Component

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

addMoved

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

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

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

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

Parameters:

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

oldpg - the parent before moved.

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

getId

public java.lang.String getId()

Description copied from interface: Component

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

Specified by:

getId in interface Component

See Also:

Page

setId

public void setId(java.lang.String id)

Description copied from interface: Component

Sets the ID. The scope of uniqunes depends on whether this component is a root component. Refer to Component.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.

Specified by:

setId in interface Component

See Also:

Page

getUuid

public final java.lang.String getUuid()

Description copied from interface: Component

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 Component.getId() if Component.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.

Specified by:

getUuid in interface Component

getSpaceOwner

public final IdSpace getSpaceOwner()

Description copied from interface: Component

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 Component.getFellow(java.lang.String). See IdSpace for more details.

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

Specified by:

getSpaceOwner in interface Component

See Also:

Component.getNamespace()

getFellow

public Component getFellow(java.lang.String compId)

Description copied from interface: Component

Returns a component of the specified ID in the same ID space. Components in the same ID space are called fellows.

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

Specified by:

getFellow in interface Component

getFellowIfAny

public Component getFellowIfAny(java.lang.String compId)

Description copied from interface: Component

Returns a component of the specified ID in the same ID space, or null if not found.

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

Specified by:

getFellowIfAny in interface Component

getNextSibling

public Component getNextSibling()

Description copied from interface: Component

Returns the next sibling, or null if it is the last child.

Specified by:

getNextSibling in interface Component

getPreviousSibling

public Component getPreviousSibling()

Description copied from interface: Component

Returns the previous sibling, or null if it is the first child.

Specified by:

getPreviousSibling in interface Component

getFirstChild

public Component getFirstChild()

Description copied from interface: Component

Returns the first child component, or null if no child at all.

Specified by:

getFirstChild in interface Component

getLastChild

public Component getLastChild()

Description copied from interface: Component

Returns the last child component, or null if no child at all.

Specified by:

getLastChild in interface Component

getAttributes

public java.util.Map getAttributes(int scope)

Description copied from interface: Component

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.COMPONENT_SCOPE, it means custom attributes private to this component.

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

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

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

Specified by:

getAttributes in interface Component

Parameters:

scope - Component.COMPONENT_SCOPE, Component.SPACE_SCOPE, Component.PAGE_SCOPE, Component.DESKTOP_SCOPE, Component.SESSION_SCOPE, Component.REQUEST_SCOPE or Component.APPLICATION_SCOPE,

getAttribute

public java.lang.Object getAttribute(java.lang.String name,
                                     int scope)

Description copied from interface: Component

Returns the value of the specified custom attribute in the specified scope, or null if not defined.

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

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

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

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

Specified by:

getAttribute in interface Component

scope - Component.COMPONENT_SCOPE, Component.SPACE_SCOPE, Component.PAGE_SCOPE, Component.DESKTOP_SCOPE, Component.SESSION_SCOPE, Component.REQUEST_SCOPE or Component.APPLICATION_SCOPE,

setAttribute

public java.lang.Object setAttribute(java.lang.String name,
                                     java.lang.Object value,
                                     int scope)

Description copied from interface: Component

Sets the value of the specified custom attribute in the specified scope.

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

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

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

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

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

Specified by:

setAttribute in interface Component

value - the value. If null, the attribute is removed.

scope - Component.COMPONENT_SCOPE, Component.SPACE_SCOPE, Component.PAGE_SCOPE, Component.DESKTOP_SCOPE, Component.SESSION_SCOPE, Component.REQUEST_SCOPE or Component.APPLICATION_SCOPE,

removeAttribute

public java.lang.Object removeAttribute(java.lang.String name,
                                        int scope)

Description copied from interface: Component

Removes the specified custom attribute in the specified scope.

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

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

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

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

Specified by:

removeAttribute in interface Component

scope - Component.COMPONENT_SCOPE, Component.SPACE_SCOPE, Component.PAGE_SCOPE, Component.DESKTOP_SCOPE, Component.SESSION_SCOPE, Component.REQUEST_SCOPE or Component.APPLICATION_SCOPE,

getAttributes

public final java.util.Map getAttributes()

Description copied from interface: Component

Returns all custom attributes associated with this component, i.e., Component.COMPONENT_SCOPE.

Specified by:

getAttributes in interface Component

getAttribute

public final java.lang.Object getAttribute(java.lang.String name)

Description copied from interface: Component

Returns the custom attribute associated with this component, i.e., Component.COMPONENT_SCOPE.

Specified by:

getAttribute in interface Component

setAttribute

public final java.lang.Object setAttribute(java.lang.String name,
                                           java.lang.Object value)

Description copied from interface: Component

Sets the custom attribute associated with this component, i.e., Component.COMPONENT_SCOPE.

Specified by:

setAttribute in interface Component

removeAttribute

public final java.lang.Object removeAttribute(java.lang.String name)

Description copied from interface: Component

Removes the custom attribute associated with this component, i.e., Component.COMPONENT_SCOPE.

Specified by:

removeAttribute in interface Component

setVariable

public void setVariable(java.lang.String name,
                        java.lang.Object val,
                        boolean local)

Description copied from interface: Component

Sets a variable to the namespace.

This method is the same as getNamespace().setVariable(name, value, local).

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.

When to use setVariable and setAttribute?

First, only the ID space support Component.setVariable(java.lang.String, java.lang.Object, boolean) and so. Second, the variables can be referenced directly in zscript and EL expressions, while attributes are referenced thru the scope, such as spaceScope. On the other hand, using attributes causes less name popultion. In general, if you could use attributes, don't use variable.

Specified by:

setVariable in interface Component

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.

See Also:

Component.getSpaceOwner(), Component.getNamespace()

containsVariable

public boolean containsVariable(java.lang.String name,
                                boolean local)

Description copied from interface: Component

Returns whether the specified variable is defined.

Note: null is a valid value for variable, so this method is used to know whether a variable is defined. On the other hand, Component.setAttribute(java.lang.String, java.lang.Object, int) actually remove an attribute (by Component.removeAttribute(java.lang.String, int) if value is null.

Specified by:

containsVariable in interface Component

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

getVariable

public java.lang.Object getVariable(java.lang.String name,
                                    boolean local)

Description copied from interface: Component

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

This method is the same as getNamespace().getVariable(name, local).

Differences between Component.getVariable(java.lang.String, boolean) and Page.getZScriptVariable(java.lang.String)

Component.getVariable(java.lang.String, boolean) returns only variables defined by Component.setVariable(java.lang.String, java.lang.Object, boolean) (i.e., a shortcut of Namespace.setVariable(java.lang.String, java.lang.Object, boolean)). On the other hand, Page.getZScriptVariable(java.lang.String) returns these variables and those defined when executing zscripts.

Specified by:

getVariable in interface Component

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

See Also:

Component.getSpaceOwner(), Component.getNamespace()

unsetVariable

public void unsetVariable(java.lang.String name,
                          boolean local)

Description copied from interface: Component

Unsets a variable defined in the namespace.

This method is the same as getNamespace().getVariable(name, local).

Specified by:

unsetVariable in interface Component

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

See Also:

Component.getSpaceOwner(), Component.getNamespace()

getParent

public Component getParent()

Description copied from interface: Component

Returns the parent component, or null if this is the root component.

Specified by:

getParent in interface Component

setParent

public void setParent(Component parent)

Description copied from interface: Component

Sets the parent component.

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

Specified by:

setParent in interface 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.

Specified by:

insertBefore in interface Component

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

public final boolean appendChild(Component child)

Appends a child to the end of all children. It calls insertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component) with refChild to be null. Derives cannot override this method, and they shall override insertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component) instead.

Specified by:

appendChild in interface Component

See Also:

Component.insertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component)

removeChild

public boolean removeChild(Component child)

Description copied from interface: Component

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

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

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

Specified by:

removeChild in interface Component

Returns:

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

isChildable

public boolean isChildable()

Default: return true (allows to have children).

Specified by:

isChildable in interface Component

getChildren

public java.util.List getChildren()

Description copied from interface: Component

Returns a live list of children. You could add or remove a child by manipulating the returned list directly.

Specified by:

getChildren in interface Component

getRoot

public Component getRoot()

Returns the root of the specified component.

Specified by:

getRoot in interface Component

isVisible

public boolean isVisible()

Description copied from interface: Component

Returns whether this component is visible.

Specified by:

isVisible in interface Component

See Also:

Components.isRealVisible(org.zkoss.zk.ui.Component)

setVisible

public boolean setVisible(boolean visible)

Description copied from interface: Component

Sets whether this component is visible.

Specified by:

setVisible in interface Component

Returns:

the previous visibility

invalidate

public void invalidate()

Description copied from interface: Component

Invalidates this component by setting the dirty flag such that it will be redraw the whole content later.

It can be called only in the request-processing and event-processing phases; excluding the redrawing phase.

There are two ways to draw a component, one is to invoke Component.invalidate(), and the other is Component.smartUpdate(java.lang.String, java.lang.String). While Component.invalidate() causes the whole content to redraw, Component.smartUpdate(java.lang.String, java.lang.String) let component developer control which part to redraw.

Once this method is called, all invocations to Component.smartUpdate(java.lang.String, java.lang.String) will then be ignored, and Component.redraw(java.io.Writer) will be invoked later.

Specified by:

invalidate in interface Component

response

public void response(java.lang.String key,
                     AuResponse response)

Description copied from interface: Component

Causes a response (aka., a command) to be sent to the client.

If AuResponse.getDepends() is not null, the response depends on the existence of the returned componet. In other words, the response is removed if the component is removed. If it is null, the response is component-independent and it is always sent to the client.

Unlike Component.smartUpdate(java.lang.String, java.lang.String), responses are sent to client if it is component independent or it is not removed. In other words, it is sent even if Component.invalidate() was called. Typical examples include setting the focus, selecting the text and so on.

It can be called only in the request-processing and event-processing phases; excluding the redrawing phase.

Specified by:

response in interface Component

Parameters:

key - could be anything. The second invocation of this method in the same execution with the same key will override the previous one. However, if key is null, it won't override any other. All responses with key == null will be sent.

smartUpdate

public void smartUpdate(java.lang.String attr,
                        java.lang.String value)

Description copied from interface: Component

Smart-updates a property with the specified value. Called by component developers to do precise-update.

The second invocation with the same property will replace the previous call. In other words, the same property will be set only once in each execution.

This method has no effect if Component.invalidate() is ever invoked (during this execution).

It can be called only in the request-processing and event-processing phases; excluding the redrawing phase.

There are two ways to draw a component, one is to invoke Component.invalidate(), and the other is Component.smartUpdate(java.lang.String, java.lang.String). While Component.invalidate() causes the whole content to redraw, Component.smartUpdate(java.lang.String, java.lang.String) let component developer control which part to redraw.

Specified by:

smartUpdate in interface Component

value - the new value. If null, it means removing the property.

smartUpdate

public void smartUpdate(java.lang.String attr,
                        int value)

A special smart-update that update a value in int.

It will invoke smartUpdate(String,String) to update the attribute eventually.

smartUpdate

public void smartUpdate(java.lang.String attr,
                        boolean value)

A special smart-update that update a value in boolean.

It will invoke smartUpdate(String,String) to update the attribute eventually.

detach

public void detach()

Description copied from interface: Component

Detaches this component such that it won't belong to any page. If you don't call Component.setParent(org.zkoss.zk.ui.Component) or Component.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.

Specified by:

detach in interface Component

onChildAdded

public void onChildAdded(Component child)

Default: does nothing.

Specified by:

onChildAdded in interface Component

See Also:

Component.onChildAdded(org.zkoss.zk.ui.Component)

onChildRemoved

public void onChildRemoved(Component child)

Default: does nothing.

Specified by:

onChildRemoved in interface Component

See Also:

Component.onChildRemoved(org.zkoss.zk.ui.Component)

onPageAttached

public void onPageAttached(Page newpage,
                           Page oldpage)

Default: handles special event listeners.

Specified by:

onPageAttached in interface Component

Parameters:

newpage - the new page (never null).

oldpage - the previous page, if any, or null if it didn't belong to any page.

Since:

3.0.0

See Also:

Component.onPageAttached(org.zkoss.zk.ui.Page, org.zkoss.zk.ui.Page)

onPageDetached

public void onPageDetached(Page page)

Default: handles special event listeners.

Specified by:

onPageDetached in interface Component

Parameters:

page - the previous page (never null)

Since:

3.0.0

See Also:

Component.onPageDetached(org.zkoss.zk.ui.Page)

getPropagatee

public Component getPropagatee(java.lang.String evtnm)

Default: null (no propagation at all).

getMold

public final java.lang.String getMold()

Returns the mold used to render this component. Default: "default"

Specified by:

getMold in interface Component

See Also:

ComponentDefinition

setMold

public void setMold(java.lang.String mold)

Description copied from interface: Component

Sets the mold for this component.

Specified by:

setMold in interface Component

Parameters:

mold - the mold. If null or empty, "default" is assumed.

See Also:

ComponentDefinition

redraw

public void redraw(java.io.Writer out)
            throws java.io.IOException

Redraws this component. This method implements the mold mechanism.

1. It first invokes getMoldURI() to retrieve the mold to redraw. The mold is either an URI (String) or a ComponentRenderer instance.
2. If URI, it invokes Execution.include(java.io.Writer, java.lang.String, java.util.Map, int) to generate the output.
3. If a ComponentRenderer instance, ComponentRenderer.render(org.zkoss.zk.ui.Component, java.io.Writer) is called to generate the output.

Specified by:

redraw in interface Component

Throws:

java.io.IOException

onDrawNewChild

public void onDrawNewChild(Component child,
                           java.lang.StringBuffer out)
                    throws java.io.IOException

Description copied from interface: Component

Called when a new-created child is about to render. It gives the parent a chance to fine-tune the output. Note: it won't be called if the parent is rendered, too. In other words, it is called only if the child is attached dynamically.

It is called in the redrawing phase by the kernel, so it is too late to call Component.invalidate() or Component.smartUpdate(java.lang.String, java.lang.String) in this method.

Note: Component.onChildAdded(org.zkoss.zk.ui.Component) is called in the request-processing phase, while Component.onDrawNewChild(org.zkoss.zk.ui.Component, java.lang.StringBuffer) is called in the redrawing phase. Component developer might do one of the follows:

• Nothing, if new child can be inserted directly.
• Overwrite Component.onDrawNewChild(org.zkoss.zk.ui.Component, java.lang.StringBuffer) to add special tags, if new child needs to be added an exterior with some tags before insertion.
  Morever, if you shall add id="${child.uuid}!chdextr" to the added exterior.
• Redraw the parent, if it is too complicated. How: overwrite Component.onChildAdded(org.zkoss.zk.ui.Component) and calls Component.invalidate()

Specified by:

onDrawNewChild in interface Component

Parameters:

child - the child being rendered

out - the rendered result of the child.

Throws:

java.io.IOException

isAsapRequired

protected boolean isAsapRequired(java.lang.String evtnm)

Returns whether to send back the request of the specified event immediately -- i.e., non-deferrable. Returns true if you want the component (on the server) to process the event immediately.

Default: return true if any non-deferable event listener of the specified event is found. In other words, it returns Events.isListened(org.zkoss.zk.ui.Component, java.lang.String, boolean) with asap = true.

This method is moved from HtmlBasedComponent to AbstractComponent since 3.0.0.

Parameters:

evtnm - the event name, such as onClick

Since:

3.0.0

appendAsapAttr

protected java.lang.StringBuffer appendAsapAttr(java.lang.StringBuffer sb,
                                                java.lang.String evtnm)

Appends an attribute for the specified event name, say, onChange, if a non-deferrable listener is registered. The format of the generated attribute is as follows: onChange="true".

This method is moved from HtmlBasedComponent to AbstractComponent since 3.0.0.

Parameters:

sb - the string buffer to hold the HTML attribute. If null and isAsapRequired(java.lang.String) is true, a string buffer is created and returned.

evtnm - the event name, such as onClick

Returns:

the string buffer. If sb is null and isAsapRequired(java.lang.String) returns false, null is returned. If the caller passed non-null sb, the returned value must be the same as sb (so it usually ignores the returned value).

Since:

3.0.0

addEventListener

public boolean addEventListener(java.lang.String evtnm,
                                EventListener listener)

Description copied from interface: Component

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

Specified by:

addEventListener in interface Component

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

public boolean removeEventListener(java.lang.String evtnm,
                                   EventListener listener)

Description copied from interface: Component

Removes an event listener.

Specified by:

removeEventListener in interface Component

Returns:

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

addForward

public boolean addForward(java.lang.String orgEvent,
                          Component target,
                          java.lang.String targetEvent)

Description copied from interface: Component

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.

Specified by:

addForward in interface Component

Parameters:

orgEvent - 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 Component.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.

See Also:

Component.removeForward(String, Component, String)

addForward

public boolean addForward(java.lang.String orgEvent,
                          java.lang.String targetPath,
                          java.lang.String targetEvent)

Description copied from interface: Component

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.

Specified by:

addForward in interface Component

Parameters:

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

See Also:

Component.addForward(String, Component, String), Component.removeForward(String, String, String)

removeForward

public boolean removeForward(java.lang.String orgEvent,
                             Component target,
                             java.lang.String targetEvent)

Description copied from interface: Component

Removes a forward condition that was added by Component.addForward(String, Component, String). If no such forward condition exists, nothing happens but return false.

Specified by:

removeForward in interface Component

Parameters:

orgEvent - the oringal event that was received by this component. It must be the same as the one passed to Component.addForward(String, Component, String).

target - the target component to receive the event. It must be the same as the one passed to Component.addForward(String, Component, String).

targetEvent - the target event that the target component will receive. It must be the same as the one passed to Component.addForward(String, Component, String).

Returns:

whether the forward is removed successfully. It returns false if the forward condition is not found

See Also:

Component.addForward(String, Component, String)

removeForward

public boolean removeForward(java.lang.String orgEvent,
                             java.lang.String targetPath,
                             java.lang.String targetEvent)

Description copied from interface: Component

Removes a forward condition that was added by Component.addForward(String, String, String). If no such forward condition exists, nothing happens but return false.

Specified by:

removeForward in interface Component

Parameters:

orgEvent - the oringal event that was received by this component. It must be the same as the one passed to Component.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 Component.addForward(String, Component, String).

Returns:

whether the forward is removed successfully. It returns false if the forward condition is not found

See Also:

Component.addForward(String, String, String)

getNamespace

public Namespace getNamespace()

Description copied from interface: Component

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.

Namspace is another part of an ID space. It holds only variables defined thru Component.setVariable(java.lang.String, java.lang.Object, boolean) (and Namespace.setVariable(java.lang.String, java.lang.Object, boolean).

Note: The namespace doesn't include any variable defined by executing zscripts. To retrieve them, use Page.getZScriptVariable(java.lang.String).

Specified by:

getNamespace in interface Component

See Also:

Component.getSpaceOwner()

isListenerAvailable

public boolean isListenerAvailable(java.lang.String evtnm,
                                   boolean asap)

Description copied from interface: Component

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 Component.addEventListener(java.lang.String, org.zkoss.zk.ui.event.EventListener).

Specified by:

isListenerAvailable in interface Component

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), Component.addEventListener(java.lang.String, org.zkoss.zk.ui.event.EventListener)

getListenerIterator

public java.util.Iterator getListenerIterator(java.lang.String evtnm)

Description copied from interface: Component

Returns an iterator for iterating listener for the specified event.

Specified by:

getListenerIterator in interface Component

applyProperties

public void applyProperties()

Description copied from interface: Component

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

Specified by:

applyProperties in interface Component

getDefinition

public ComponentDefinition getDefinition()

Description copied from interface: Component

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

Specified by:

getDefinition in interface Component

setComponentDefinition

public void setComponentDefinition(ComponentDefinition compdef)

Description copied from interface: ComponentCtrl

Sets the component definition.

The component definition affects how a component behaves. Developers rarely need to call this method. If a wrong definition is assigned, the result is unpredictable (and hard to debug). It is mainly designed for developing tools.

Specified by:

setComponentDefinition in interface ComponentCtrl

getEventHandler

public ZScript getEventHandler(java.lang.String evtnm)

Description copied from interface: ComponentCtrl

Returns the event handler of the specified name, or null if not found.

Specified by:

getEventHandler in interface ComponentCtrl

addSharedEventHandlerMap

public void addSharedEventHandlerMap(EventHandlerMap evthds)

Description copied from interface: ComponentCtrl

Adds a map of event handlers which is shared by other components. In other words, this component shall have all event handlers defined in the specified map, evthds. Meanwhile, this component shall not modify evthds, since it is shared. The caller shall not change annots after the invocation, too

Specified by:

addSharedEventHandlerMap in interface ComponentCtrl

Parameters:

evthds - a map of event handler

addEventHandler

public void addEventHandler(java.lang.String name,
                            EventHandler evthd)

Description copied from interface: ComponentCtrl

Adds an event handler.

Specified by:

addEventHandler in interface ComponentCtrl

getAnnotation

public Annotation getAnnotation(java.lang.String annotName)

Description copied from interface: ComponentCtrl

Returns the annotation associated with the component, or null if not available.

Specified by:

getAnnotation in interface ComponentCtrl

Parameters:

annotName - the annotation name

getAnnotation

public Annotation getAnnotation(java.lang.String propName,
                                java.lang.String annotName)

Description copied from interface: ComponentCtrl

Returns the annotation associated with the definition of the specified property, or null if not available.

Specified by:

getAnnotation in interface ComponentCtrl

Parameters:

propName - the property name, e.g., "value".

annotName - the annotation name

getAnnotations

public java.util.Collection getAnnotations()

Description copied from interface: ComponentCtrl

Returns a read-only collection of all annotations associated with this component (never null).

Specified by:

getAnnotations in interface ComponentCtrl

getAnnotations

public java.util.Collection getAnnotations(java.lang.String propName)

Description copied from interface: ComponentCtrl

Returns a read-only collection of all annotations associated with the specified property (never null).

Specified by:

getAnnotations in interface ComponentCtrl

Parameters:

propName - the property name, e.g., "value".

getAnnotatedPropertiesBy

public java.util.List getAnnotatedPropertiesBy(java.lang.String annotName)

Description copied from interface: ComponentCtrl

Returns a read-only list of the names (String) of the properties that are associated with the specified annotation (never null).

Specified by:

getAnnotatedPropertiesBy in interface ComponentCtrl

getAnnotatedProperties

public java.util.List getAnnotatedProperties()

Description copied from interface: ComponentCtrl

Returns a read-only list of the name (String) of properties that are associated at least one annotation (never null).

Specified by:

getAnnotatedProperties in interface ComponentCtrl

addSharedAnnotationMap

public void addSharedAnnotationMap(AnnotationMap annots)

Description copied from interface: ComponentCtrl

Add a map of annotations which is shared by other components. In other words, this component shall have all annotations defined in the specified map, annots. Meanwhile, this component shall not modify annots, since it is shared. The caller shall not change annots after the invocation, too

Specified by:

addSharedAnnotationMap in interface ComponentCtrl

Parameters:

annots - a annotation map.

addAnnotation

public void addAnnotation(java.lang.String annotName,
                          java.util.Map annotAttrs)

Description copied from interface: ComponentCtrl

Associates an annotation to this component.

Unlike Java, you can add annotations dynamically, and each component has its own annotations.

Specified by:

addAnnotation in interface ComponentCtrl

Parameters:

annotName - the annotation name (never null, nor empty).

annotAttrs - a map of attributes, or null if no attribute. The attribute must be in a pair of strings (String name, String value).

addAnnotation

public void addAnnotation(java.lang.String propName,
                          java.lang.String annotName,
                          java.util.Map annotAttrs)

Description copied from interface: ComponentCtrl

Adds an annotation to the specified proeprty of this component.

Specified by:

addAnnotation in interface ComponentCtrl

Parameters:

propName - the property name (never nul, nor empty).

annotName - the annotation name (never null, nor empty).

annotAttrs - a map of attributes, or null if no attribute at all. The attribute must be in a pair of strings (String name, String value).

sessionWillPassivate

public void sessionWillPassivate(Page page)

Description copied from interface: ComponentCtrl

Notification that the session, which owns this component, is about to be passivated (aka., serialized).

Note: only root components are notified by this method.

Specified by:

sessionWillPassivate in interface ComponentCtrl

sessionDidActivate

public void sessionDidActivate(Page page)

Description copied from interface: ComponentCtrl

Notification that the session, which owns this component, has just been activated (aka., deserialized).

Note: only root components are notified by this method.

Specified by:

sessionDidActivate in interface ComponentCtrl

getExtraCtrl

public java.lang.Object getExtraCtrl()

Returns the extra controls that tell ZK how to handle this component specially. It is used only by component developers.

It is simpler to override newExtraCtrl() instead of this. By use of newExtraCtrl(), you don't need to care of cloning and serialization.

Default: return the object being created by newExtraCtrl(), if any.

Specified by:

getExtraCtrl in interface ComponentCtrl

Returns:

null if no special handling required. If the component requires some special controls, it could return an object that implements one or several interfaces in the org.zkoss.zk.ui.ext.render and org.zkoss.zk.ui.ext.client packages. For example, Cropper and Inputable.

See Also:

ComponentCtrl.getExtraCtrl()

newExtraCtrl

protected java.lang.Object newExtraCtrl()

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

Default: return null.

To provide extra controls, it is simpler to override this method instead of getExtraCtrl(). By use of newExtraCtrl(), you don't need to care of cloning and serialization.

onWrongValue

public WrongValueException onWrongValue(WrongValueException ex)

Notifies that an WrongValueException instance is thrown, and WrongValueException.getComponent() is this component. It is a callback and the component can store the error message, show up the custom information, or even 'eat' the exception.

Default: does nothing but returns ex.

Specified by:

onWrongValue in interface ComponentCtrl

Parameters:

ex - the exception being thrown (never null)

Returns:

the exception to throw, or null to ignore the exception In most cases, just return ex

Since:

2.4.0

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

equals

public final boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

clone

public java.lang.Object clone()

Description copied from interface: Component

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

Specified by:

clone in interface Component

Overrides:

clone in class java.lang.Object