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

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.
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.
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.
java.lang.String	getId() Returns the ID.
java.util.Iterator	getListenerIterator(java.lang.String evtnm) Returns an iterator for iterating listener for the specified event.
java.lang.String	getMold() Default: "default"
protected java.lang.String	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.
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	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.
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 drawn.
WrongValueException	onWrongValue(WrongValueException ex) Notifies that an WrongValueException instance is thrown, and WrongValueException.getComponent() is this component.
void	redraw(java.io.Writer out) Includes the page returned by getMoldURI() and set the self attribute to be 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.
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 the page that this component belongs to.
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.String getMoldURI()

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

Used usually 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)

Sets the page that this component belongs to.

Specified by:

setPage in interface Component

getId

public final 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. It is either a component, a page or null. If it has an ancestor that implements IdSpace, it 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

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.

Specified by:

setParent in interface Component

isChildable

public boolean isChildable()

Default: return true (allows to have children).

Specified by:

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

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.

Specified by:

removeChild in interface Component

Returns:

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

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

onChildRemoved

public void onChildRemoved(Component child)

Default: does nothing.

Specified by:

onChildRemoved in interface Component

getPropagatee

public Component getPropagatee(java.lang.String evtnm)

Default: null (no propagation at all).

getMold

public final java.lang.String getMold()

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

Includes the page returned by getMoldURI() and set the self attribute to be this component.

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 drawn. It gives the parent a chance to fine-tune the output.

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

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.

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,