org.zkoss.zk.ui
Class AbstractComponent

java.lang.Object
  extended by org.zkoss.zk.ui.AbstractComponent
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, Component, Scope, ComponentCtrl
Direct Known Subclasses:
AbstractTag, Area, HtmlBasedComponent, HtmlNativeComponent, Script, Style, Text, Transformer, XmlMacroComponent, XmlNativeComponent, Zkhead

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

Nested Class Summary
protected  class AbstractComponent.Children
          The default implementation for newChildren().
 
Field Summary
protected  boolean _visible
          Whether this component is visible.
 
Fields inherited from interface org.zkoss.zk.ui.Component
APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE
 
Fields inherited from interface org.zkoss.zk.ui.sys.ComponentCtrl
CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE
 
Constructor Summary
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.
protected static void addClientEvent(java.lang.Class cls, java.lang.String evtnm, int flags)
          Adds an event that the client might send to the server.
 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, Component target, java.lang.String targetEvent, java.lang.Object eventData)
          Adds a forward condition to forward the event received by this component to another component with extra event data.
 boolean addForward(java.lang.String 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.
 boolean addForward(java.lang.String orgEvent, java.lang.String targetPath, java.lang.String targetEvent, java.lang.Object eventData)
          Adds a forward condition to forward the event received by this component to another component of the specified path with extra event data.
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.
 boolean addScopeListener(ScopeListener listener)
          Adds a listener to listen whether this scope is changed.
 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.
 void beforeChildAdded(Component child, Component insertBefore)
          Default: does nothing.
 void beforeChildRemoved(Component child)
          Default: does nothing.
 void beforeParentChanged(Component parent)
          Default: does nothing.
 java.lang.Object clone()
          Clones the component.
 boolean containsVariable(java.lang.String name, boolean local)
          Deprecated. As of release 5.0.0, replaced with hasAttribute(java.lang.String, int).
 void detach()
          Detaches this component such that it won't belong to any page.
protected  void didActivate(java.util.Collection c)
          Utility to invoke ComponentActivationListener.didActivate(org.zkoss.zk.ui.Component) for each object in the collection.
protected  void didActivate(java.lang.Object o)
          Utility to invoke ComponentActivationListener.didActivate(org.zkoss.zk.ui.Component) for the specified object.
protected  void didDeserialize(java.util.Collection c)
          Utility to invoke ComponentSerializationListener.didDeserialize(org.zkoss.zk.ui.Component) for each object in the collection.
protected  void didDeserialize(java.lang.Object o)
          Utility to invoke ComponentSerializationListener.didDeserialize(org.zkoss.zk.ui.Component) for the specified object.
 boolean disableClientUpdate(boolean disable)
          Sets whether to disable the update of the client widgets of this component and its descendants.
 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, boolean recurse)
          Returns the custom attribute associated with this object.
 java.lang.Object getAttribute(java.lang.String name, int scope)
          Returns the value of the specified custom attribute in the specified scope, or null if not defined.
 java.lang.Object getAttributeOrFellow(java.lang.String name, boolean recurse)
          Returns the custom attribute associated with this component, or the fellow of this component; or null if not found.
 java.util.Map getAttributes()
          Returns all custom attributes associated with this component, i.e., Component.COMPONENT_SCOPE.
 java.util.Map getAttributes(int scope)
          Returns all custom attributes of the specified scope.
 AuService getAuService()
          Returns an AU service to process the AU request before the component's default handling.
 java.util.List getChildren()
          Returns a live list of children.
 java.util.Map getClientEvents()
          Returns a map of event information that the client might send to this component.
 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 listener of the specified name, or null if not found.
 java.util.Set getEventHandlerNames()
          Returns a readonly collection of event names (String), or an empty collection if no event name is registered.
 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 getFellow(java.lang.String compId, boolean recurse)
          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 getFellowIfAny(java.lang.String compId, boolean recurse)
          Returns a component of the specified ID in the same ID space, or null if not found.
 java.util.Collection getFellows()
          Returns all fellows in the same ID space of this component.
 Component getFirstChild()
          Returns the first child component, or null if no child at all.
 java.lang.String getId()
          Returns the ID.
 Component getLastChild()
          Returns the last child component, or null if no child at all.
 java.util.Iterator getListenerIterator(java.lang.String evtnm)
          Returns an iterator for iterating listener for the specified event.
 java.lang.String getMold()
          Returns the mold used to render this component.
 Namespace getNamespace()
          Deprecated. As of release 5.0.0, use getAttribute(java.lang.String, int), setAttribute(java.lang.String, java.lang.Object, int) instead.
 Component getNextSibling()
          Returns the next sibling, or null if it is the last child.
 Page getPage()
          Returns the page that this component belongs to, or null if it doesn't belong to any page.
 Component getParent()
          Returns the parent component, or null if this is the root component.
 Component getPreviousSibling()
          Returns the previous sibling, or null if it is the first child.
 Component getRoot()
          Returns the root of 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)
          Deprecated. As of release 5.0.0, replaced with getAttribute(java.lang.String, int).
 java.lang.String getWidgetClass()
          Returns the widget class (aka., widget type), or null if not defined.
 java.lang.String getWidgetListener(java.lang.String evtnm)
          Returns the script of the client event, or null if not found.
 java.util.Set getWidgetListenerNames()
          Returns a readonly collection of event names (String) that the listener of the peer widget are assigned, or an empty collection if none is registered.
 java.lang.String getWidgetOverride(java.lang.String name)
          Returns the script of the method definition to override widget's method, or null if not found.
 java.util.Set getWidgetOverrideNames()
          Returns a readonly collection of the property names (String) that shall be overriden, or an empty collection if none is registered.
 boolean hasAttribute(java.lang.String name)
          Returns if the custom attribute is associate with this component.
 boolean hasAttribute(java.lang.String name, boolean recurse)
          Returns if a custom attribute is associated with this object.
 boolean hasAttribute(java.lang.String name, int scope)
          Returns if the custom attribute is associate with this component.
 boolean hasAttributeOrFellow(java.lang.String name, boolean recurse)
          Returns if a custom attribute is associated with this component, or the fellow of this component.
 boolean hasFellow(java.lang.String compId)
          Returns whether a fellow exists in the same ID space of this component.
 boolean hasFellow(java.lang.String compId, boolean recurse)
          Returns whether there is a fellow named with the specified component ID in the same ID space as this component.
 boolean insertBefore(Component newChild, Component refChild)
          Inserts a child before the reference child.
 void invalidate()
          Invalidates this component by setting the dirty flag such that it will be redraw the whole content of this component and its decendances later.
protected  boolean isChildable()
          Returns whether this component can have a child.
 boolean isInvalidated()
          Returns if this component needs to be redrawn at the client.
 boolean isListenerAvailable(java.lang.String evtnm, boolean asap)
          Returns whether the event listener is available.
 boolean isVisible()
          Returns whether this component is visible.
protected  java.util.List newChildren()
          Creates and returns the instance for storing child components.
protected  java.lang.Object newExtraCtrl()
          Used by getExtraCtrl() to create extra controls.
 void onChildAdded(Component child)
          Default: does nothing.
 void onChildRemoved(Component child)
          Default: does nothing.
 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 and all its decendants.
protected  void redrawChildren(java.io.Writer out)
          Redraws childrens (and then recursively descandants).
 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, boolean recurse)
          Removes the custom attribute associated with this 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).
 boolean removeScopeListener(ScopeListener listener)
          Removes a change listener from this scope.
protected  void render(ContentRenderer renderer, java.lang.String name, boolean value)
          An utility to be called by renderProperties(org.zkoss.zk.ui.sys.ContentRenderer) to render a boolean-value property if it is true.
protected  void render(ContentRenderer renderer, java.lang.String name, java.lang.Object value)
          An utility to be called by renderProperties(org.zkoss.zk.ui.sys.ContentRenderer) to render a string-value property.
protected  void render(ContentRenderer renderer, java.lang.String name, java.lang.String value)
          An utility to be called by renderProperties(org.zkoss.zk.ui.sys.ContentRenderer) to render a string-value property.
protected  void renderProperties(ContentRenderer renderer)
          Called by (ComponentCtrl.redraw(java.io.Writer)) to render the properties, excluding the enclosing tag and children.
protected  void response(java.lang.String key, AuResponse response)
          Causes a response to be sent to the client.
 void service(AuRequest request, boolean everError)
          Handles an AU request.
 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, boolean recurse)
          Sets the custom attribute associated with this scope, or the parent scope.
 java.lang.Object setAttribute(java.lang.String name, java.lang.Object value, int scope)
          Sets the value of the specified custom attribute in the specified scope.
 void setAuService(AuService ausvc)
          Sets an AU service to process the AU request before the component's default handling.
 void setDefinition(ComponentDefinition compdef)
          Sets the component definition.
 void setDefinition(java.lang.String name)
          Sets the component definition by specifing the name.
 void setId(java.lang.String id)
          Sets the ID.
 void setMold(java.lang.String mold)
          Sets the mold to render this component.
 void setPage(Page page)
          Sets what page this component belongs to.
 void setPageBefore(Page page, Component refRoot)
          Sets what page this component belongs to, and insert this component right before the reference component.
 void setParent(Component parent)
          Sets the parent component.
 void setVariable(java.lang.String name, java.lang.Object val, boolean local)
          Deprecated. As of release 5.0.0, replaced with setAttribute(java.lang.String, java.lang.Object, int).
 boolean setVisible(boolean visible)
          Sets whether this component is visible.
 java.lang.String setWidgetListener(java.lang.String evtnm, java.lang.String script)
          Sets or removes an event listener of the peer widget.
 java.lang.String setWidgetOverride(java.lang.String name, java.lang.String script)
          Sets or removes the script of the method definition to override widget's method.
protected  void smartUpdate(java.lang.String attr, boolean value)
          A special smart update to update a value in boolean.
protected  void smartUpdate(java.lang.String attr, byte value)
          A special smart update to update a value in byte.
protected  void smartUpdate(java.lang.String attr, char value)
          A special smart update to update a value in character.
protected  void smartUpdate(java.lang.String attr, java.util.Date value)
          A special smart update to update a value in Date.
protected  void smartUpdate(java.lang.String attr, double value)
          A special smart update to update a value in double.
protected  void smartUpdate(java.lang.String attr, float value)
          A special smart update to update a value in float.
protected  void smartUpdate(java.lang.String attr, int value)
          A special smart update to update a value in int.
protected  void smartUpdate(java.lang.String attr, long value)
          A special smart update to update a value in long.
protected  void smartUpdate(java.lang.String attr, java.lang.Object value)
          Smart-updates a property of the peer widget associated with the component, running at the client, with the specified value.
protected  void smartUpdateWidgetListener(java.lang.String evtnm, java.lang.String script)
          A special smart update to update an event listener for the peer widget.
protected  void smartUpdateWidgetOverride(java.lang.String name, java.lang.String script)
          A special smart update to update a method of the peer widget.
 java.lang.String toString()
           
 void unsetVariable(java.lang.String name, boolean local)
          Deprecated. As of release 5.0.0, replaced with removeAttribute(java.lang.String, int).
protected  void updateByClient(java.lang.String name, java.lang.Object value)
          Called when the widget running at the client asks the server to update a value (with an AU request named setAttr).
protected  void willPassivate(java.util.Collection c)
          Utility to invoke ComponentActivationListener.willPassivate(org.zkoss.zk.ui.Component) for each object in the collection.
protected  void willPassivate(java.lang.Object o)
          Utility to invoke ComponentActivationListener.willPassivate(org.zkoss.zk.ui.Component) for the specified object.
protected  void willSerialize(java.util.Collection c)
          Utility to invoke ComponentSerializationListener.willSerialize(org.zkoss.zk.ui.Component) for each object in the collection.
protected  void willSerialize(java.lang.Object o)
          Utility to invoke ComponentSerializationListener.willSerialize(org.zkoss.zk.ui.Component) for the specified object.
 
Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

_visible

protected boolean _visible
Whether this component is visible.

Since:
3.5.0 (becomes protected)
Constructor Detail

AbstractComponent

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

Since:
3.0.7 (becomes public)
Method Detail

newChildren

protected java.util.List newChildren()
Creates and returns the instance for storing child components.

Default: it instantiates AbstractComponent.Children.

Since:
3.5.1

getPage

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

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

Specified by:
setPage in interface Component
See Also:
ComponentCtrl.onPageAttached(org.zkoss.zk.ui.Page, org.zkoss.zk.ui.Page), ComponentCtrl.onPageDetached(org.zkoss.zk.ui.Page)

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).
See Also:
Component.setPage(org.zkoss.zk.ui.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
Parameters:
id - the identifier. It cannot be empty. If null, it means the previous ID is removed (aka., reset) and an anonymous ID is assigned.
See Also:
Page

getUuid

public 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 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.getAttributeOrFellow(java.lang.String, boolean).

Specified by:
getSpaceOwner in interface Component
See Also:
Component.getNamespace()

hasFellow

public boolean hasFellow(java.lang.String compId)
Description copied from interface: Component
Returns whether a fellow exists in the same ID space of this component.

Specified by:
hasFellow in interface Component

getFellow

public Component getFellow(java.lang.String compId)
                    throws ComponentNotFoundException
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
Throws:
ComponentNotFoundException - is thrown if fellow not found

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

getFellows

public java.util.Collection getFellows()
Description copied from interface: Component
Returns all fellows in the same ID space of this component. The returned collection is readonly.

Specified by:
getFellows in interface Component

getFellow

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

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

Specified by:
getFellow in interface Component
recurse - whether to look up the parent ID space for the existence of the fellow
Throws:
ComponentNotFoundException - is thrown if this component doesn't belong to any ID space

getFellowIfAny

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

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

Specified by:
getFellowIfAny in interface Component
recurse - whether to look up the parent ID space for the existence of the fellow

hasFellow

public boolean hasFellow(java.lang.String compId,
                         boolean recurse)
Description copied from interface: Component
Returns whether there is a fellow named with the specified component ID in the same ID space as this component. It is the same as getSpaceOwner().hasFellow(id, recurse);

Specified by:
hasFellow in interface Component
recurse - whether to look up the parent ID space for the existence of the fellow

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

setWidgetListener

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

Specified by:
setWidgetListener in interface Component
Parameters:
evtnm - the event name, such as onClick
script - the script to handle the event. If null, the event handler is removed.
Returns:
the previous script if any

getWidgetListener

public java.lang.String getWidgetListener(java.lang.String evtnm)
Description copied from interface: Component
Returns the script of the client event, or null if not found.

Specified by:
getWidgetListener in interface Component

getWidgetListenerNames

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

Specified by:
getWidgetListenerNames in interface Component

setWidgetOverride

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

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

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

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

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

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

getWidgetOverride

public java.lang.String getWidgetOverride(java.lang.String name)
Description copied from interface: Component
Returns the script of the method definition to override widget's method, or null if not found.

Specified by:
getWidgetOverride in interface Component

getWidgetOverrideNames

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

Specified by:
getWidgetOverrideNames 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,

hasAttribute

public boolean hasAttribute(java.lang.String name,
                            int scope)
Description copied from interface: Component
Returns if the custom attribute is associate with this component.

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.

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

Specified by:
hasAttribute 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 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
Specified by:
getAttributes in interface Scope

getAttribute

public 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
Specified by:
getAttribute in interface Scope

hasAttribute

public boolean hasAttribute(java.lang.String name)
Description copied from interface: Component
Returns if the custom attribute is associate with this component.

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

Specified by:
hasAttribute in interface Component
Specified by:
hasAttribute in interface Scope

setAttribute

public 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
Specified by:
setAttribute in interface Scope
Returns:
the previous value associated with the attribute, if any

removeAttribute

public 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
Specified by:
removeAttribute in interface Scope
Returns:
the previous value associated with the attribute, if any,

getAttribute

public java.lang.Object getAttribute(java.lang.String name,
                                     boolean recurse)
Description copied from interface: Scope
Returns the custom attribute associated with this object.

Specified by:
getAttribute in interface Scope
recurse - whether to search its ancestor scope. If true and the current scope doen't define the attribute, it searches up its ancestor to see any of them has defined the specified attribute.

hasAttribute

public boolean hasAttribute(java.lang.String name,
                            boolean recurse)
Description copied from interface: Scope
Returns if a custom attribute is associated with this object.

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

Specified by:
hasAttribute in interface Scope
recurse - whether to search its ancestor scope. If true and the current scope doen't define the attribute, it searches up its ancestor to see any of them has defined the specified attribute.

setAttribute

public java.lang.Object setAttribute(java.lang.String name,
                                     java.lang.Object value,
                                     boolean recurse)
Description copied from interface: Scope
Sets the custom attribute associated with this scope, or the parent scope.

Specified by:
setAttribute in interface Scope
recurse - whether to look up the parent scope for the existence of the attribute.
If recurse is true and the attribute is defined in one of its ancestor (including page), the attribute is replaced. Otherwise, it is the same as Scope.setAttribute(String,Object).

removeAttribute

public java.lang.Object removeAttribute(java.lang.String name,
                                        boolean recurse)
Description copied from interface: Scope
Removes the custom attribute associated with this scope.

Specified by:
removeAttribute in interface Scope
recurse - whether to look up the parent scope for the existence of the attribute.
If recurse is true and the attribute is defined in one of its ancestor (including page), the attribute is removed. Otherwise, it is the same as Scope.removeAttribute(String).

getAttributeOrFellow

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

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

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

hasAttributeOrFellow

public boolean hasAttributeOrFellow(java.lang.String name,
                                    boolean recurse)
Description copied from interface: Component
Returns if a custom attribute is associated with this component, or the fellow of this component.

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

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

addScopeListener

public boolean addScopeListener(ScopeListener listener)
Description copied from interface: Scope
Adds a listener to listen whether this scope is changed. The listener is called when a custom attribute is added, removed, or the parent is changed.

Specified by:
addScopeListener in interface Scope
Returns:
wether the listener is added successfully. Note: if the resolver was added before, it won't be added again and this method returns false.

removeScopeListener

public boolean removeScopeListener(ScopeListener listener)
Description copied from interface: Scope
Removes a change listener from this scope.

Specified by:
removeScopeListener in interface Scope
Returns:
false if listener is not added before.

setVariable

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

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.

containsVariable

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

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)
Deprecated. As of release 5.0.0, replaced with getAttribute(java.lang.String, int).

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.

unsetVariable

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

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.

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

protected boolean isChildable()
Returns whether this component can have a child.

Default: return true (means it can have children).


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

isInvalidated

public boolean isInvalidated()
Description copied from interface: Component
Returns if this component needs to be redrawn at the client.

Application developers rarely need to call this method.

Note:

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

Specified by:
isInvalidated in interface Component

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 of this component and its decendances later. And, the widget associated with this component and all its descendant at the client will be deleted and recreated, too.

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

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

Specified by:
invalidate in interface Component

response

protected void response(java.lang.String key,
                        AuResponse response)
Causes a response 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.Object), responses are 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.

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.
Since:
5.0.0 (become protected)

smartUpdate

protected void smartUpdate(java.lang.String attr,
                           java.lang.Object value)
Smart-updates a property of the peer widget associated with the component, running at the client, with the specified value.

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 (in the same execution), since invalidate() assumes the whole content shall be redrawn and all smart updates to this components can be ignored,

Once invalidate() is called, all invocations to smartUpdate(java.lang.String, java.lang.Object) will then be ignored, and redraw(java.io.Writer) will be invoked 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 smartUpdate(java.lang.String, java.lang.Object). While Component.invalidate() causes the whole content to redraw, smartUpdate(java.lang.String, java.lang.Object) let component developer control which part to redraw.

Parameters:
value - the new value. If it is DeferredValue, the value will be retrieved (by calling DeferredValue.getValue()) in the rendering phase. It is useful if the value can not be determined now.

For some old application servers (example, Webshpere 5.1), Execution.encodeURL(java.lang.String) cannot be called in the event processing thread. So, the developers have to use DeferredValue or disable the use of the event processing thread (by use of disable-event-thread in zk.xml).

In addition, the value can be any kind of objects that the client accepts (marshaled by JSON).

Since:
5.0.0 (become protected)
See Also:
updateByClient(java.lang.String, java.lang.Object)

smartUpdate

protected void smartUpdate(java.lang.String attr,
                           int value)
A special smart update to update a value in int.

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

Since:
5.0.0

smartUpdate

protected void smartUpdate(java.lang.String attr,
                           long value)
A special smart update to update a value in long.

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

Since:
5.0.0

smartUpdate

protected void smartUpdate(java.lang.String attr,
                           byte value)
A special smart update to update a value in byte.

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

Since:
5.0.0

smartUpdate

protected void smartUpdate(java.lang.String attr,
                           char value)
A special smart update to update a value in character.

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

Since:
5.0.0

smartUpdate

protected void smartUpdate(java.lang.String attr,
                           boolean value)
A special smart update to update a value in boolean.

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

Since:
5.0.0

smartUpdate

protected void smartUpdate(java.lang.String attr,
                           float value)
A special smart update to update a value in float.

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

Since:
5.0.0

smartUpdate

protected void smartUpdate(java.lang.String attr,
                           double value)
A special smart update to update a value in double.

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

Since:
5.0.0

smartUpdate

protected void smartUpdate(java.lang.String attr,
                           java.util.Date value)
A special smart update to update a value in Date.

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

Since:
5.0.0

smartUpdateWidgetListener

protected void smartUpdateWidgetListener(java.lang.String evtnm,
                                         java.lang.String script)
A special smart update to update an event listener for the peer widget. By default, it assumes the peer widget has a method called setListener and it will be invoked as follows.
wgt.setListener([evtnm, script]);

Devices that supports it in another way have to override this method. Devices that don't support it have to override this method to throw UnsupportedOperationException.

Parameters:
evtnm - the event name, such as onClick
script - the script. If null, it means to remove the event listener from the peer widget
Since:
5.0.0

smartUpdateWidgetOverride

protected void smartUpdateWidgetOverride(java.lang.String name,
                                         java.lang.String script)
A special smart update to update a method of the peer widget. By default, it assumes the peer widget has a method called setMethod and it will be invoked as follows.
wgt.setMethod([evtnm, script]);

Devices that supports it in another way have to override this method. Devices that don't support it have to override this method to throw UnsupportedOperationException.

Parameters:
name - the method name, such as setValue
script - the script. If null, the previous method override will be remove. And, the method defined in original widget will be restored.
Since:
5.0.0

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

beforeChildAdded

public void beforeChildAdded(Component child,
                             Component insertBefore)
Default: does nothing.

Specified by:
beforeChildAdded in interface ComponentCtrl
Parameters:
child - the child to be added (never null).
insertBefore - another child component that the new child will be inserted before it. If null, the new child will be the last child.
Since:
3.6.2
See Also:
ComponentCtrl.beforeChildAdded(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component)

beforeChildRemoved

public void beforeChildRemoved(Component child)
Default: does nothing.

Specified by:
beforeChildRemoved in interface ComponentCtrl
Parameters:
child - the child to be removed (never null)
Since:
3.6.2
See Also:
ComponentCtrl.beforeChildRemoved(org.zkoss.zk.ui.Component)

beforeParentChanged

public void beforeParentChanged(Component parent)
Default: does nothing.

Specified by:
beforeParentChanged in interface ComponentCtrl
Parameters:
parent - the new parent. If null, it means detachment.
Since:
3.6.2
See Also:
ComponentCtrl.beforeParentChanged(org.zkoss.zk.ui.Component)

onChildAdded

public void onChildAdded(Component child)
Default: does nothing.

Specified by:
onChildAdded in interface ComponentCtrl
See Also:
ComponentCtrl.onChildAdded(org.zkoss.zk.ui.Component)

onChildRemoved

public void onChildRemoved(Component child)
Default: does nothing.

Specified by:
onChildRemoved in interface ComponentCtrl
See Also:
ComponentCtrl.onChildRemoved(org.zkoss.zk.ui.Component)

onPageAttached

public void onPageAttached(Page newpage,
                           Page oldpage)
Default: handles special event listeners.

Specified by:
onPageAttached in interface ComponentCtrl
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:
ComponentCtrl.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 ComponentCtrl
Parameters:
page - the previous page (never null)
Since:
3.0.0
See Also:
ComponentCtrl.onPageDetached(org.zkoss.zk.ui.Page)

getWidgetClass

public java.lang.String getWidgetClass()
Returns the widget class (aka., widget type), or null if not defined.

Default: return the widget class based on the current mold (by use of ComponentDefinition.getWidgetClass(java.lang.String)), or null if not found.

Specified by:
getWidgetClass in interface Component
Since:
5.0.0

getMold

public java.lang.String getMold()
Description copied from interface: Component
Returns the mold used to render this component.

Default: "default"

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

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

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

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 to render this component.

Specified by:
setMold in interface Component
Parameters:
mold - the mold. If null or empty, "default" is assumed.
See Also:
ComponentDefinition

disableClientUpdate

public boolean disableClientUpdate(boolean disable)
Description copied from interface: ComponentCtrl
Sets whether to disable the update of the client widgets of this component and its descendants.

By default, if a component is attached to a page, modications that change the visual representation will be sent to the client to ensure the consistency.

Though rarely needed, you can disable the synchronization of the visual representation, if you prefer to update the client batchly or the modification is caused by the client.

Notice:

  • Once disabled, it not only affects the synchronization of this component but also all its descendants.
  • The disable remains until the end of this execution (or the invocation of this method with false). In other words, it is enabled automatically in the next execution.
  • The updates, if any, before calling this method will still be sent to the client.
  • It does nothing, if there is no current execution.

Also notice that, with Component.invalidate(), it is easy to synchronize the content of a component (and its descendants) to the client.

Specified by:
disableClientUpdate in interface ComponentCtrl
Returns:
whether it has been disabled before this invocation, i.e., the previous disable status

redraw

public void redraw(java.io.Writer out)
            throws java.io.IOException
Redraws this component and all its decendants.

Default: It uses JsContentRenderer to render all information in JavaScript codes. For devices that don't support JavaScript, it must override this method. To generate all information, it first invokes renderProperties(org.zkoss.zk.ui.sys.ContentRenderer) to render component's properties, and then redrawChildren(java.io.Writer) to redraw children (and descendants) (by calling their redraw(java.io.Writer)).

If a dervied class wants to render more properties, it can override renderProperties(org.zkoss.zk.ui.sys.ContentRenderer).

If a derived class renders only a subset of its children (such as paging/cropping), it could override redrawChildren(java.io.Writer).

If a deriving class wants to do something before renderProperties(org.zkoss.zk.ui.sys.ContentRenderer), it has to override redraw(java.io.Writer).

If a deriving class doesn't want to render in JavaScript codes, it has to override redraw(java.io.Writer) with the proper implementation of ContentRenderer.

Specified by:
redraw in interface ComponentCtrl
Throws:
java.io.IOException

redrawChildren

protected void redrawChildren(java.io.Writer out)
                       throws java.io.IOException
Redraws childrens (and then recursively descandants).

Default: it invokes redraw(java.io.Writer) for all its children.

If a derived class renders only a subset of its children (such as paging/cropping), it could override redrawChildren(java.io.Writer).

Throws:
java.io.IOException
Since:
5.0.0
See Also:
redraw(java.io.Writer)

renderProperties

protected void renderProperties(ContentRenderer renderer)
                         throws java.io.IOException
Called by (ComponentCtrl.redraw(java.io.Writer)) to render the properties, excluding the enclosing tag and children.

Default: it renders getId() if it was assigned, and event names if listened (and listed in getClientEvents()).

Note: it doesn't render getWidgetClass(), getUuid() and getMold(), which are caller's job.

Throws:
java.io.IOException
Since:
5.0.0

render

protected void render(ContentRenderer renderer,
                      java.lang.String name,
                      java.lang.String value)
               throws java.io.IOException
An utility to be called by renderProperties(org.zkoss.zk.ui.sys.ContentRenderer) to render a string-value property. It ignores if value is null or empty. If you want to render it even if null/empty, invoke ContentRenderer.render(String, String) directly.

Throws:
java.io.IOException
Since:
5.0.0

render

protected void render(ContentRenderer renderer,
                      java.lang.String name,
                      java.lang.Object value)
               throws java.io.IOException
An utility to be called by renderProperties(org.zkoss.zk.ui.sys.ContentRenderer) to render a string-value property. It ignores if value is null. If you want to render it even if null, invoke ContentRenderer.render(String, Object) directly.

Throws:
java.io.IOException
Since:
5.0.0

render

protected void render(ContentRenderer renderer,
                      java.lang.String name,
                      boolean value)
               throws java.io.IOException
An utility to be called by renderProperties(org.zkoss.zk.ui.sys.ContentRenderer) to render a boolean-value property if it is true. If you want to render it no matter true or false, use ContentRenderer.render(String, boolean) directly.

Throws:
java.io.IOException
Since:
5.0.0

getClientEvents

public java.util.Map getClientEvents()
Returns a map of event information that the client might send to this component. The key of the returned map is a String instance representing the event name, and the value an integer representing the flags (a combination of ComponentCtrl.CE_IMPORTANT, ComponentCtrl.CE_NON_DEFERRABLE, ComponentCtrl.CE_BUSY_IGNORE, ComponentCtrl.CE_DUPLICATE_IGNORE and ComponentCtrl.CE_REPEAT_IGNORE).

Default: return the collection of events added by getClientEvents().

Rather than overriding this method, it is suggested to invoke addClientEvent(java.lang.Class, java.lang.String, int) in the static statement. For example,

public MyComponent extend HtmlBasedComponent {
  static {
    addClientEvent(MyComponent.class, "onOpen", 0);
  }

Specified by:
getClientEvents in interface ComponentCtrl
Since:
5.0.0

addClientEvent

protected static void addClientEvent(java.lang.Class cls,
                                     java.lang.String evtnm,
                                     int flags)
Adds an event that the client might send to the server. It must be called when loading the class (i.e., in static {}). It cannot be called after that.

Parameters:
cls - the component's class (implementation class).
flags - a combination of ComponentCtrl.CE_IMPORTANT, ComponentCtrl.CE_NON_DEFERRABLE ComponentCtrl.CE_BUSY_IGNORE, ComponentCtrl.CE_DUPLICATE_IGNORE and ComponentCtrl.CE_REPEAT_IGNORE.
Since:
5.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), Component.addForward(String, Component, String, Object)

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)

addForward

public boolean addForward(java.lang.String orgEvent,
                          Component target,
                          java.lang.String targetEvent,
                          java.lang.Object eventData)
Description copied from interface: Component
Adds a forward condition to forward the event received by this component to another component with extra event data.

Specified by:
addForward in interface Component
eventData - the extra data that can be retrieve by Event.getData().
See Also:
Component.addForward(String, Component, String)

addForward

public boolean addForward(java.lang.String orgEvent,
                          java.lang.String targetPath,
                          java.lang.String targetEvent,
                          java.lang.Object eventData)
Description copied from interface: Component
Adds a forward condition to forward the event received by this component to another component of the specified path with extra event data.

Specified by:
addForward in interface Component
eventData - the extra data that can be retrieve by Event.getData().
See Also:
Component.addForward(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()
Deprecated. As of release 5.0.0, use getAttribute(java.lang.String, int), setAttribute(java.lang.String, java.lang.Object, int) instead.

Specified by:
getNamespace in interface Component

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.

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

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

setDefinition

public void setDefinition(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:
setDefinition in interface ComponentCtrl

setDefinition

public void setDefinition(java.lang.String name)
Description copied from interface: ComponentCtrl
Sets the component definition by specifing the name.

Specified by:
setDefinition in interface ComponentCtrl
Parameters:
name - the name of the component definition

getEventHandler

public ZScript getEventHandler(java.lang.String evtnm)
Description copied from interface: ComponentCtrl
Returns the event listener of the specified name, or null if not found.

Specified by:
getEventHandler in interface ComponentCtrl
See Also:
Component.getWidgetListener(java.lang.String)

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
See Also:
Component.setWidgetListener(java.lang.String, java.lang.String)

getEventHandlerNames

public java.util.Set getEventHandlerNames()
Description copied from interface: ComponentCtrl
Returns a readonly collection of event names (String), or an empty collection if no event name is registered.

Specified by:
getEventHandlerNames in interface ComponentCtrl
See Also:
Component.getWidgetListenerNames()

addEventHandler

public void addEventHandler(java.lang.String name,
                            EventHandler evthd)
Description copied from interface: ComponentCtrl
Adds an event handler. Note: it is OK to add multiple event handlers to the same event. They are evaluated one-by-one. On the other hand, Component.setWidgetListener(java.lang.String, java.lang.String) will overwrite the pevious listener if the event name is the same.

Specified by:
addEventHandler in interface ComponentCtrl
See Also:
Component.setWidgetListener(java.lang.String, java.lang.String)

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.

Notice that the property is not limited the 'real' property. For example, the following statement is correct though button doesn't have setFoo method. And, you can retrieve it by use of this method (getAnnotation("foo", "default"))

<button foo="@{value=123}"/>

Furthermore, you can declare it as custom-attribute (since ZK 5.0). For example, the following is equivalent to the above.

<button>
  <custom-attribute foo="@{value=123}">
</button>

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

willPassivate

protected void willPassivate(java.util.Collection c)
Utility to invoke ComponentActivationListener.willPassivate(org.zkoss.zk.ui.Component) for each object in the collection.

Parameters:
c - a collection of objects. Ignored if null.
Since:
3.6.4

willPassivate

protected void willPassivate(java.lang.Object o)
Utility to invoke ComponentActivationListener.willPassivate(org.zkoss.zk.ui.Component) for the specified object.

Parameters:
o - the object to invoke. Ignore if ComponentActivationListener not implemented or null.
Since:
3.6.4

didActivate

protected void didActivate(java.util.Collection c)
Utility to invoke ComponentActivationListener.didActivate(org.zkoss.zk.ui.Component) for each object in the collection.

Parameters:
c - a collection of objects. Ignored if null.
Since:
3.6.4

didActivate

protected void didActivate(java.lang.Object o)
Utility to invoke ComponentActivationListener.didActivate(org.zkoss.zk.ui.Component) for the specified object.

Parameters:
o - the object to invoke. Ignore if ComponentActivationListener not implemented or null.
Since:
3.6.4

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 package. For example, Cropper.
See Also:
ComponentCtrl.getExtraCtrl()

newExtraCtrl

protected java.lang.Object newExtraCtrl()
Used by getExtraCtrl() to create extra controls. 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

getAuService

public AuService getAuService()
Description copied from interface: Component
Returns an AU service to process the AU request before the component's default handling.

Default: null

Specified by:
getAuService in interface Component

setAuService

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

Default: null.

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

See also how to process data with JSON.

Specified by:
setAuService in interface Component

service

public void service(AuRequest request,
                    boolean everError)
Handles an AU request. It is invoked internally.

Default: it handles echo and setAttr, and it convests other request to an event (by Event.getEvent(org.zkoss.zk.au.AuRequest)) and then posts the event (by Events.postEvent(org.zkoss.zk.ui.event.Event)).

Application developer can plug the custom service to handle the AU request by setAuService(org.zkoss.zk.au.AuService).

Specified by:
service in interface ComponentCtrl
everError - whether any error ever occured before processing this request.
Since:
5.0.0
See Also:
setAuService(org.zkoss.zk.au.AuService)

updateByClient

protected void updateByClient(java.lang.String name,
                              java.lang.Object value)
Called when the widget running at the client asks the server to update a value (with an AU request named setAttr).

By default, it uses reflection to find out the setter to update the value. Nothing happens if the method is not found. You can override it if necessary.

Notice: this method will invoke disableClientUpdate(boolean) to disable any update to the client, when calling the setter

See also zk.Widget.smartUpdate().

Since:
5.0.0

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

equals

public 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

willSerialize

protected void willSerialize(java.util.Collection c)
Utility to invoke ComponentSerializationListener.willSerialize(org.zkoss.zk.ui.Component) for each object in the collection.

Parameters:
c - a collection of objects. Ignored if null.
Since:
3.6.4

willSerialize

protected void willSerialize(java.lang.Object o)
Utility to invoke ComponentSerializationListener.willSerialize(org.zkoss.zk.ui.Component) for the specified object.

Parameters:
o - the object to invoke. Ignore if ComponentSerializationListener not implemented or null.
Since:
3.6.4

didDeserialize

protected void didDeserialize(java.util.Collection c)
Utility to invoke ComponentSerializationListener.didDeserialize(org.zkoss.zk.ui.Component) for each object in the collection.

Parameters:
c - a collection of objects. Ignored if null.
Since:
3.6.4

didDeserialize

protected void didDeserialize(java.lang.Object o)
Utility to invoke ComponentSerializationListener.didDeserialize(org.zkoss.zk.ui.Component) for the specified object.

Parameters:
o - the object to invoke. Ignore if ComponentSerializationListener not implemented or null.
Since:
3.6.4


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