org.zkoss.zk.ui.sys
Interface ComponentCtrl

All Known Implementing Classes:

AbstractComponent, HtmlBasedComponent, HtmlMacroComponent, HtmlNativeComponent

public interface ComponentCtrl

An addition interface to Component that is used for implementation or tools.

Application developers rarely need to access methods in this interface.

Author:

tomyeh

Method Summary

void	addAnnotation(java.lang.String annotName, java.util.Map annotAttrs) Associates an annotation to this component.
void	addAnnotation(java.lang.String propName, java.lang.String annotName, java.util.Map annotAttrs) Adds an annotation to the specified proeprty of this component.
void	addEventHandler(java.lang.String name, EventHandler evthd) Adds an event handler.
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.
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).
ZScript	getEventHandler(java.lang.String evtnm) Returns the event handler of the specified name, or null if not found.
java.lang.Object	getExtraCtrl() Returns the extra controls that tell ZK how to handle this component specially.
WrongValueException	onWrongValue(WrongValueException ex) Notifies that an WrongValueException instance is thrown, and WrongValueException.getComponent() is this component.
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).
void	setComponentDefinition(ComponentDefinition compdef) Sets the component definition.

Method Detail

setComponentDefinition

void setComponentDefinition(ComponentDefinition compdef)

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.

Throws:

java.lang.IllegalArgumentException - if compdef is null

getEventHandler

ZScript getEventHandler(java.lang.String evtnm)

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

addEventHandler

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

Adds an event handler.

addSharedEventHandlerMap

void addSharedEventHandlerMap(EventHandlerMap evthds)

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

Parameters:

evthds - a map of event handler

getAnnotation

Annotation getAnnotation(java.lang.String annotName)

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

Parameters:

annotName - the annotation name

getAnnotation

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.

Parameters:

annotName - the annotation name

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

Throws:

java.lang.IllegalArgumentException - if propName is null or empty

getAnnotations

java.util.Collection getAnnotations()

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

getAnnotations

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

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

Parameters:

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

Throws:

java.lang.IllegalArgumentException - if propName is null or empty

getAnnotatedPropertiesBy

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

getAnnotatedProperties

java.util.List getAnnotatedProperties()

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

addSharedAnnotationMap

void addSharedAnnotationMap(AnnotationMap annots)

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

Parameters:

annots - a annotation map.

addAnnotation

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

Associates an annotation to this component.

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

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

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

Adds an annotation to the specified proeprty of this component.

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

void sessionWillPassivate(Page page)

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

Note: only root components are notified by this method.

sessionDidActivate

void sessionDidActivate(Page page)

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

Note: only root components are notified by this method.

getExtraCtrl

java.lang.Object getExtraCtrl()

Returns the extra controls that tell ZK how to handle this component specially.

Application developers need NOT to access this method.

There are two set of extra controls: org.zkoss.zk.ui.ext.client and org.zkoss.zk.ui.ext.render.

The first package is used if the content of a component can be changed by the user at the client. It is so-called the client controls.

The second package is used to control how to render a component specially.

Override this method only if you want to return the extra controls.

Returns:

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

onWrongValue

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.

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