org.zkoss.zk.ui
Interface Component

All Superinterfaces:

java.lang.Cloneable, java.io.Serializable

All Known Implementing Classes:

AbstractComponent, HtmlBasedComponent, HtmlMacroComponent

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

A UI component.

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

The Page Creation

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

The Asynchronous Update

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

No Synchronization Required

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

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

Author:

tomyeh

Field Summary

static int	APPLICATION_SCOPE Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the whole application.
static int	COMPONENT_SCOPE Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes private to a component is searched.
static int	DESKTOP_SCOPE Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the same desktop.
static int	PAGE_SCOPE Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the same page.
static int	REQUEST_SCOPE Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the same request.
static int	SESSION_SCOPE Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the same session.
static int	SPACE_SCOPE Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the same ID space.

Method Summary

boolean	addEventListener(java.lang.String evtnm, EventListener listener) Adds an event listener to specified event for this component.
boolean	appendChild(Component child) Appends a child.
void	applyProperties() Initializes the properties (aka. members) and custom-attributes based on what are defined in the component definition.
java.lang.Object	clone() Clones the component.
boolean	containsVariable(java.lang.String name, boolean local) Returns whether the specified variable is defined.
void	detach() Detaches this component such that it won't belong to any page.
java.lang.Object	getAttribute(java.lang.String name) Returns the custom attribute associated with this component, i.e., COMPONENT_SCOPE.
java.lang.Object	getAttribute(java.lang.String name, int scope) Returns the value of the specified custom attribute in the specified scope, or null if not defined.
java.util.Map	getAttributes() Returns all custom attributes associated with this component, i.e., COMPONENT_SCOPE.
java.util.Map	getAttributes(int scope) Returns all custom attributes of the specified scope.
java.util.List	getChildren() Returns a live list of children.
ComponentDefinition	getDefinition() Returns the component definition of this component (never null).
Desktop	getDesktop() Returns the desktop of this component, or null if this component doesn't belong to any desktop.
Component	getFellow(java.lang.String id) Returns a component of the specified ID in the same ID space.
Component	getFellowIfAny(java.lang.String id) 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() Returns the mold for this component.
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	getRoot() Returns the root of this component.
IdSpace	getSpaceOwner() Returns the owner of the ID space that this component belongs to.
java.lang.String	getUuid() Returns UUID (universal unique ID) which is unquie in the whole session.
java.lang.Object	getVariable(java.lang.String name, boolean local) 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() Returns whether this component allows to have any child.
boolean	isListenerAvailable(java.lang.String evtnm, boolean asap) Returns whether the event listener is available.
boolean	isVisible() Returns whether this component is visible.
void	onChildAdded(Component child) Called when a child is added.
void	onChildRemoved(Component child) Called when a child is removed.
void	onDrawNewChild(Component child, java.lang.StringBuffer out) Called when a new-created child is drawn.
void	redraw(java.io.Writer out) AuRequest this component to render (aka., redraw) itself and its children.
java.lang.Object	removeAttribute(java.lang.String name) Removes the custom attribute associated with this component, i.e., COMPONENT_SCOPE.
java.lang.Object	removeAttribute(java.lang.String name, int scope) Removes the specified custom attribute in the specified scope.
boolean	removeChild(Component child) Removes a child.
boolean	removeEventListener(java.lang.String evtnm, EventListener listener) Removes an event listener.
void	response(java.lang.String key, AuResponse response) Causes a response (aka., a command) to be sent to the client.
java.lang.Object	setAttribute(java.lang.String name, java.lang.Object value) Sets the custom attribute associated with this component, i.e., COMPONENT_SCOPE.
java.lang.Object	setAttribute(java.lang.String name, java.lang.Object value, int scope) Sets the value of the specified custom attribute in the specified scope.
void	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	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, java.lang.String value) Smart-updates a property with the specified value.
void	unsetVariable(java.lang.String name, boolean local) Unsets a variable defined in the namespace.

Field Detail

COMPONENT_SCOPE

static final int COMPONENT_SCOPE

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

It is also known as the component attributes.

It is the same as getAttributes(int).

See Also:

Constant Field Values

SPACE_SCOPE

static final int SPACE_SCOPE

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

It is also known as the ID space attributes.

See Also:

Constant Field Values

PAGE_SCOPE

static final int PAGE_SCOPE

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

It is also known as the page attributes.

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

See Also:

Constant Field Values

DESKTOP_SCOPE

static final int DESKTOP_SCOPE

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

It is also known as the desktop attributes.

It is the same as Desktop.getAttributes().

See Also:

Constant Field Values

SESSION_SCOPE

static final int SESSION_SCOPE

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

It is also known as the session attributes.

It is the same as Session.getAttributes().

See Also:

Constant Field Values

APPLICATION_SCOPE

static final int APPLICATION_SCOPE

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

It is also known as the application attributes.

It is the same as WebApp.getAttributes().

See Also:

Constant Field Values

REQUEST_SCOPE

static final int REQUEST_SCOPE

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

It is also known as the request attributes.

It is the same as Execution.getAttributes().

See Also:

Constant Field Values

Method Detail

getDefinition

ComponentDefinition getDefinition()

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

getSpaceOwner

IdSpace getSpaceOwner()

Returns the owner of the ID space that this component belongs to. 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 getFellow(java.lang.String). See IdSpace for more details.

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

See Also:

getNamespace()

getId

java.lang.String getId()

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

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

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

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

See Also:

Page

setId

void setId(java.lang.String id)

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

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

See Also:

Page

getDesktop

Desktop getDesktop()

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

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

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

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

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

getPage

Page getPage()

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

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

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

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

See Also:

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

setPage

void setPage(Page page)

Sets what page this component belongs to.

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

getUuid

java.lang.String getUuid()

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

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

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

getFellow

Component getFellow(java.lang.String id)

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

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

Throws:

ComponentNotFoundException - is thrown if fellow not found

getFellowIfAny

Component getFellowIfAny(java.lang.String id)

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

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

getAttributes

java.util.Map getAttributes(int scope)

Returns all custom attributes of the specified scope. You could reference them thru componentScope, spaceScope, pageScope, requestScope and desktopScope in zscript and EL.

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

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

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

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

Parameters:

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

getAttribute

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

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

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

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

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

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

Parameters:

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

setAttribute

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

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

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

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

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

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

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

Parameters:

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

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

removeAttribute

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

Removes the specified custom attribute in the specified scope.

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

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

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

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

Parameters:

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

getAttributes

java.util.Map getAttributes()

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

getAttribute

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

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

setAttribute

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

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

removeAttribute

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

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

setVariable

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

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

Parameters:

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

See Also:

getSpaceOwner(), getNamespace()

containsVariable

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

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, setAttribute(java.lang.String, java.lang.Object, int) actually remove an attribute (by removeAttribute(java.lang.String, int) if value is null.

Parameters:

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

getVariable

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.

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

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

getVariable(java.lang.String, boolean) returns only variables defined by 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.

Parameters:

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

See Also:

getSpaceOwner(), getNamespace()

unsetVariable

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

Unsets a variable defined in the namespace.

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

Parameters:

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

See Also:

getSpaceOwner(), getNamespace()

getParent

Component getParent()

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

setParent

void setParent(Component parent)

Sets the parent component.

getChildren

java.util.List getChildren()

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

getRoot

Component getRoot()

Returns the root of this component.

isVisible

boolean isVisible()

Returns whether this component is visible.

See Also:

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

setVisible

boolean setVisible(boolean visible)

Sets whether this component is visible.

Returns:

the previous visibility

insertBefore

boolean insertBefore(Component newChild,
                     Component refChild)

Inserts a child before the reference child.

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

Parameters:

newChild - the new child to be inserted.

refChild - the child before which you want the new child being inserted. If null, the new child is append to the end.

Returns:

true if newChild is added successfully or moved; false if it already has the specified child and the order doesn't change.

appendChild

boolean appendChild(Component child)

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

See Also:

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

removeChild

boolean removeChild(Component child)

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

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

Returns:

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

detach

void detach()

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

onChildAdded

void onChildAdded(Component child)

Called when a child is added. If a component want to optimize the update, it might do something different. Otherwise, it does nothing.

Note: onChildAdded(org.zkoss.zk.ui.Component) is called in the request-processing phase, while onDrawNewChild(org.zkoss.zk.ui.Component, java.lang.StringBuffer) is called in the redrawing phase. See onDrawNewChild(org.zkoss.zk.ui.Component, java.lang.StringBuffer) for more details.

onChildRemoved

void onChildRemoved(Component child)

Called when a child is removed. If a component want to optimize the update, it might do something different. Otherwise, it simply does nothing.

getMold

java.lang.String getMold()

Returns the mold for this component.

Default: "default"

See Also:

ComponentDefinition

setMold

void setMold(java.lang.String mold)

Sets the mold for this component.

Parameters:

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

See Also:

ComponentDefinition

addEventListener

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

Adds an event listener to specified event for this component. The second registration is ignored and false is returned.

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

Parameters:

evtnm - what event to listen (never null)

Returns:

whether the listener is added; false if it was added before

See Also:

Page.addEventListener(java.lang.String, org.zkoss.zk.ui.event.EventListener)

removeEventListener

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

Removes an event listener.

Returns:

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

isListenerAvailable

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

Returns whether the event listener is available.

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

Parameters:

asap - whether to check only non-deferrable listener, i.e., not implementing Deferrable, or Deferrable.isDeferrable() is false.

See Also:

Deferrable, Events.isListened(org.zkoss.zk.ui.Component, java.lang.String, boolean), addEventListener(java.lang.String, org.zkoss.zk.ui.event.EventListener)

getListenerIterator

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

Returns an iterator for iterating listener for the specified event.

invalidate

void invalidate()

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 invalidate(), and the other is smartUpdate(java.lang.String, java.lang.String). While invalidate() causes the whole content to redraw, smartUpdate(java.lang.String, java.lang.String) let component developer control which part to redraw.

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

smartUpdate

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

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 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 invalidate(), and the other is smartUpdate(java.lang.String, java.lang.String). While invalidate() causes the whole content to redraw, smartUpdate(java.lang.String, java.lang.String) let component developer control which part to redraw.

Parameters:

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

response

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

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

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.

redraw

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

AuRequest this component to render (aka., redraw) itself and its children.

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

Throws:

java.io.IOException

onDrawNewChild

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

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 invalidate() or smartUpdate(java.lang.String, java.lang.String) in this method.

Note: onChildAdded(org.zkoss.zk.ui.Component) is called in the request-processing phase, while 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 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 onChildAdded(org.zkoss.zk.ui.Component) and calls invalidate()

Parameters:

child - the child being rendered

out - the rendered result of the child.

Throws:

java.io.IOException

isChildable

boolean isChildable()

Returns whether this component allows to have any child.

getNamespace

Namespace getNamespace()

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

See Also:

getSpaceOwner()

applyProperties

void applyProperties()

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

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

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

clone

java.lang.Object clone()

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