org.zkoss.zk.ui.sys
Interface ComponentCtrl

All Known Implementing Classes:

A, A, Abbr, Absolutechildren, Absolutelayout, AbstractComponent, AbstractTag, Acronym, Address, Anchorchildren, Anchorlayout, Applet, Area, Area, Audio, Auxhead, Auxheader, B, Bandbox, Bandpopup, Base, Big, Biglistbox, Blockquote, Body, Borderlayout, Box, Br, Button, Button, Calendar, Captcha, Caption, Caption, Cardlayout, Cell, Center, Center, Chart, Checkbox, Chosenbox, Cite, Code, Col, Colgroup, Colorbox, Column, Columnchildren, Columnlayout, Columns, Combobox, Combobutton, Comboitem, ContentTag, Datebox, Dd, Decimalbox, Del, Detail, Dfn, Dir, Div, Div, Dl, Doublebox, Doublespinner, Dropupload, Dt, East, Em, Embed, Fieldset, Fileupload, Fileupload, FileuploadDlg, Fisheye, Fisheyebar, Flash, Font, Foot, Footer, FooterElement, Form, FormatInputElement, Frozen, Fusionchart, Grid, Group, Groupbox, Groupfoot, H1, H2, H3, H4, Hbox, Head, HeaderElement, HeadersElement, Hlayout, Hr, Html, Html, HtmlBasedComponent, HtmlMacroComponent, HtmlNativeComponent, I, Idspace, Iframe, Iframe, Image, Imagemap, Img, Include, Input, InputElement, Ins, Intbox, Isindex, Jasperreport, Kbd, Label, Label, LabelElement, LabelImageElement, Layout, LayoutRegion, Legend, Li, Link, Listbox, Listcell, Listfoot, Listfooter, Listgroup, Listgroupfoot, Listhead, Listheader, Listitem, Longbox, Map, Menu, Menu, Menubar, Menuitem, Menupopup, Menuseparator, MeshElement, MessageboxDlg, MessageboxDlg.Button, Meta, Nobr, North, NumberInputElement, Object, Ol, Optgroup, Option, P, Paging, Panel, Panelchildren, Popup, Portalchildren, Portallayout, Pre, Progressmeter, Q, Radio, Radiogroup, Raw, Row, Rows, S, Samp, Script, Script, Scrollview, Select, Selectbox, Separator, Slider, Small, South, Space, Span, Span, Spinner, Splitter, Strong, StubComponent, StubsComponent, Style, Style, Sub, Sup, Tab, Tabbox, Table, Tablechildren, Tablelayout, Tabpanel, Tabpanels, Tabs, Tbody, Td, Text, Textarea, Textbox, Tfoot, Th, Thead, Timebox, Timer, Title, Toolbar, Toolbarbutton, Tr, Transformer, Tree, Treecell, Treechildren, Treecol, Treecols, Treefoot, Treefooter, Treeitem, Treerow, Tt, Ul, Var, Vbox, Vlayout, West, Window, XmlMacroComponent, XmlNativeComponent, XulElement, Zkhead

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

Field Summary

static int	CE_BUSY_IGNORE Returned by getClientEvents() to indicate the event can be ignored by the server when the server is busy.
static int	CE_DUPLICATE_IGNORE Returned by getClientEvents() to indicate the event can be ignored by the server when the server receives the same AU requests but not processed yet.
static int	CE_IMPORTANT Returned by getClientEvents() to indicate the event is important and the client must send it back even if no listener is registered.
static int	CE_NON_DEFERRABLE Returned by getClientEvents() to indicate the event is no deferrable, i.e., the event has to be sent back immediately.
static int	CE_REPEAT_IGNORE Returned by getClientEvents() to indicate the event an be ignored by the server when the server receives consecutive AU requests.

Method Summary

void	addAnnotation(java.lang.String annotName, java.util.Map<java.lang.String,java.lang.String[]> annotAttrs) Deprecated. As of release 6.0.0, replaced with addAnnotation(String, String, Map)
void	addAnnotation(java.lang.String propName, java.lang.String annotName, java.util.Map<java.lang.String,java.lang.String[]> annotAttrs) Adds an annotation to the specified property of this component.
void	addEventHandler(java.lang.String name, EventHandler evthd) Adds an event handler.
void	addSharedEventHandlerMap(EventHandlerMap evthds) Adds a map of event handlers which is shared by other components.
void	beforeChildAdded(Component child, Component insertBefore) Called before adding a child.
void	beforeChildRemoved(Component child) Called before removing a child.
void	beforeParentChanged(Component parent) Called before changing the parent.
boolean	disableClientUpdate(boolean disable) Sets whether to disable the update of the client widgets of this component and its descendants.
java.util.List<java.lang.String>	getAnnotatedProperties() Returns a read-only list of the name of properties that are associated at least one annotation (never null).
java.util.List<java.lang.String>	getAnnotatedPropertiesBy(java.lang.String annotName) Returns a read-only list of the names of the properties that are associated with the specified annotation (never null).
Annotation	getAnnotation(java.lang.String annotName) Deprecated. As of release 6.0.0, replaced with getAnnotation(String, String).
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<Annotation>	getAnnotations() Deprecated. As of release 6.0.0, replaced with getAnnotations(String).
java.util.Collection<Annotation>	getAnnotations(java.lang.String propName) Returns a read-only collection of all annotations (Annotation) associated with the specified property.
java.util.Collection<Annotation>	getAnnotations(java.lang.String propName, java.lang.String annotName) Returns the annotations associated with the definition of the specified property.
java.util.Map<java.lang.String,java.lang.Integer>	getClientEvents() Returns a map of event information that the client might send to this component.
ZScript	getEventHandler(java.lang.String evtnm) Returns the event listener of the specified name, or null if not found.
java.util.Set<java.lang.String>	getEventHandlerNames() Returns a readonly collection of event names (String), or an empty collection if no event name is registered.
EventListenerMap	getEventListenerMap() Returns the map of event handlers and listeners defined in this component.
java.lang.Object	getExtraCtrl() Returns the extra controls that tell ZK how to handle this component specially.
void	onChildAdded(Component child) Called when a child is added.
void	onChildRemoved(Component child) Called when a child is removed.
void	onPageAttached(Page newpage, Page oldpage) Called when this component is attached to a page.
void	onPageDetached(Page page) Called when this component is detached from a page.
WrongValueException	onWrongValue(WrongValueException ex) Notifies that an WrongValueException instance is thrown, and WrongValueException.getComponent() is the component causing the exception.
void	redraw(java.io.Writer out) Render (a.k.a., redraw) this component and all its descendants.
void	service(AuRequest request, boolean everError) Handles an AU request.
void	service(Event event, Scope scope) Handles an event.
void	sessionDidActivate(Page page) Notification that the session, which owns this component, has just been activated (a.k.a., deserialized).
void	sessionWillPassivate(Page page) Notification that the session, which owns this component, is about to be passivated (a.k.a., serialized).
void	setDefinition(ComponentDefinition compdef) Sets the component definition.
void	setDefinition(java.lang.String defname) Sets the component definition by specifying the name.

Field Detail

CE_IMPORTANT

static final int CE_IMPORTANT

Returned by getClientEvents() to indicate the event is important and the client must send it back even if no listener is registered.

See Also:

Constant Field Values

CE_NON_DEFERRABLE

static final int CE_NON_DEFERRABLE

Returned by getClientEvents() to indicate the event is no deferrable, i.e., the event has to be sent back immediately. It is meaningful only used with CE_IMPORTANT

See Also:

Constant Field Values

CE_BUSY_IGNORE

static final int CE_BUSY_IGNORE

Returned by getClientEvents() to indicate the event can be ignored by the server when the server is busy.

See Also:

Constant Field Values

CE_DUPLICATE_IGNORE

static final int CE_DUPLICATE_IGNORE

Returned by getClientEvents() to indicate the event can be ignored by the server when the server receives the same AU requests but not processed yet. In other words, the server will remove the duplicate AU requests if it was queued.

See Also:

Constant Field Values

CE_REPEAT_IGNORE

static final int CE_REPEAT_IGNORE

Returned by getClientEvents() to indicate the event an be ignored by the server when the server receives consecutive AU requests. In other words, the server will remove the first request if it receives an event listed in this map consecutively.

See Also:

Constant Field Values

Method Detail

setDefinition

void setDefinition(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

setDefinition

void setDefinition(java.lang.String defname)

Sets the component definition by specifying the name.

Parameters:

defname - the name of the component definition

Throws:

java.lang.IllegalArgumentException - if defname is null

DefinitionNotFoundException - if the component definition not found

Since:

5.0.0

beforeChildAdded

void beforeChildAdded(Component child,
                      Component insertBefore)

Called before adding a child. If a component accepts only certain types of children, it shall override this method and throw an exception for an illegal child.

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

beforeChildRemoved

void beforeChildRemoved(Component child)

Called before removing a child. If a component denies a certain child to be removed, it shall override this method to avoid it.

Parameters:

child - the child to be removed (never null)

Since:

3.6.2

beforeParentChanged

void beforeParentChanged(Component parent)

Called before changing the parent. If a component can be a child of certain parents, it shall override this method and throws an exception for an illegal parent.

Parameters:

parent - the new parent. If null, it means detachment.

Since:

3.6.2

onChildAdded

void onChildAdded(Component child)

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

Note: onChildAdded(org.zkoss.zk.ui.Component) is called in the request-processing phase.

It is not a good idea to throw an exception in this method, since it is in the middle of modifying the component tree.

Since:

3.5.0

onChildRemoved

void onChildRemoved(Component child)

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

It is not a good idea to throw an exception in this method, since it is in the middle of modifying the component tree.

Since:

3.5.0

onPageAttached

void onPageAttached(Page newpage,
                    Page oldpage)

Called when this component is attached to a page.

If a component is moved from one page to another, onPageAttached(org.zkoss.zk.ui.Page, org.zkoss.zk.ui.Page) is called with both pages. Note: onPageDetached(org.zkoss.zk.ui.Page) is not called in this case.

Note: this method is called even if the component is attached to a page implicitly thru, say, Component.setParent(org.zkoss.zk.ui.Component).

It is not a good idea to throw an exception in this method, since it is in the middle of modifying the component tree.

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

onPageDetached

void onPageDetached(Page page)

Called when this component is detached from a page.

If a component is moved from one page to another, onPageAttached(org.zkoss.zk.ui.Page, org.zkoss.zk.ui.Page) is called with both pages. Note: onPageDetached(org.zkoss.zk.ui.Page) is not called in this case. In other words, onPageDetached(org.zkoss.zk.ui.Page) is called only if a component is detached from a page (not belong to any other page).

Note: this method is called even if the component is detached to a page implicitly thru, say, Component.setParent(org.zkoss.zk.ui.Component).

It is not a good idea to throw an exception in this method, since it is in the middle of modifying the component tree.

Parameters:

page - the previous page (never null)

Since:

3.5.0

getEventHandler

ZScript getEventHandler(java.lang.String evtnm)

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

See Also:

Component.getWidgetListener(java.lang.String)

addEventHandler

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

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 previous listener if the event name is the same.

See Also:

Component.setWidgetListener(java.lang.String, java.lang.String)

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

See Also:

Component.setWidgetListener(java.lang.String, java.lang.String)

getEventHandlerNames

java.util.Set<java.lang.String> getEventHandlerNames()

Returns a readonly collection of event names (String), or an empty collection if no event name is registered.

Since:

3.0.2

See Also:

Component.getWidgetListenerNames()

getClientEvents

java.util.Map<java.lang.String,java.lang.Integer> 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 CE_IMPORTANT, CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE and CE_REPEAT_IGNORE).

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

Since:

5.0.0

getAnnotation

Annotation getAnnotation(java.lang.String annotName)

Deprecated. As of release 6.0.0, replaced with getAnnotation(String, String).

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.

If there are multiple annotation with the given name, this method will merge them before return. If you prefer to get all of them without merging, please use getAnnotations(String, String) instead. For example,

<textbox value="@bind(abc, param1=foo1) @bind(xyz, param2=foo2)">

This method will return a single annotation with three attributes: value=xyz, param1=foo1 and param2=foo2. On the other hand, getAnnotations(String, String) will return a two-element collections.

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", "bind"))

<button foo="@bind(whatever=123)"/>

Furthermore, you can declare it as custom-attribute. For example, the following is equivalent to the above.

<button>
  <custom-attribute foo="@bind(whatever=123}">
</button>

Parameters:

propName - the property name, e.g., "value". If null, this method returns the annotation(s) associated with this component (rather than a particular property).

annotName - the annotation name

See Also:

getAnnotations(String, String)

getAnnotations

java.util.Collection<Annotation> getAnnotations(java.lang.String propName,
                                                java.lang.String annotName)

Returns the annotations associated with the definition of the specified property. It never returns null.

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", "bind"))

<button foo="@bind(whatever=123)"/>

Furthermore, you can declare it as custom-attribute. For example, the following is equivalent to the above.

<button>
  <custom-attribute foo="@bind(whatever=123}">
</button>

Parameters:

propName - the property name, e.g., "value". If null, this method returns the annotation(s) associated with this component (rather than a particular property).

annotName - the annotation name

Since:

6.0.0

See Also:

getAnnotation(String, String)

getAnnotations

java.util.Collection<Annotation> getAnnotations()

Deprecated. As of release 6.0.0, replaced with getAnnotations(String).

getAnnotations

java.util.Collection<Annotation> getAnnotations(java.lang.String propName)

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

Parameters:

propName - the property name, e.g., "value". If null, this method returns the annotation(s) associated with this component (rather than a particular property).

getAnnotatedPropertiesBy

java.util.List<java.lang.String> getAnnotatedPropertiesBy(java.lang.String annotName)

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

getAnnotatedProperties

java.util.List<java.lang.String> getAnnotatedProperties()

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

addAnnotation

void addAnnotation(java.lang.String annotName,
                   java.util.Map<java.lang.String,java.lang.String[]> annotAttrs)

Deprecated. As of release 6.0.0, replaced with addAnnotation(String, String, Map)

addAnnotation

void addAnnotation(java.lang.String propName,
                   java.lang.String annotName,
                   java.util.Map<java.lang.String,java.lang.String[]> annotAttrs)

Adds an annotation to the specified property of this component.

If the given property is null, the annotation is associated to this component, rather than a particular property.

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

Parameters:

propName - the property name. If null, the annotation is associated with the component (rather than a particular property).

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

annotAttrs - a map of attributes, or null if no attribute at all. This method will make a copy of annotAttrs, so the caller can use it after the invocation.

sessionWillPassivate

void sessionWillPassivate(Page page)

Notification that the session, which owns this component, is about to be passivated (a.k.a., 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 (a.k.a., 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 a set of extra controls: 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 package. For example, Cropper.

onWrongValue

WrongValueException onWrongValue(WrongValueException ex)

Notifies that an WrongValueException instance is thrown, and WrongValueException.getComponent() is the component causing the exception. 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

redraw

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

Render (a.k.a., redraw) this component and all its descendants.

It is called in the redrawing phase by the kernel, so it is too late to call Component.invalidate(), AbstractComponent.smartUpdate(java.lang.String, java.lang.Object) or AbstractComponent.response(org.zkoss.zk.au.AuResponse) in this method.

Throws:

java.io.IOException

Since:

5.0.0

service

void service(AuRequest request,
             boolean everError)

Handles an AU request.

Notice: don't invoke this method directly. Rather, invoke DesktopCtrl.service(AuRequest, boolean) instead. This method is designed to be overridden.

To send responses to the client, use AbstractComponent.smartUpdate(java.lang.String, java.lang.Object), AbstractComponent.response(org.zkoss.zk.au.AuResponse) or Component.invalidate(). To handle the AU requests sent from the client, override this method.

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

Parameters:

everError - whether any error ever occurred before processing this request.

Since:

5.0.0

See Also:

Component.setAuService(org.zkoss.zk.au.AuService)

service

void service(Event event,
             Scope scope)
             throws java.lang.Exception

Handles an event. This method will invoke the event handlers registered in a ZUML page, the event listeners registered in Java, and the event handlers declared as part of the component.

Parameters:

event - the event to handle

scope - the scope to evaluate the zscript, if any. (see also Page.interpret(java.lang.String, java.lang.String, org.zkoss.zk.ui.ext.Scope).

Throws:

java.lang.Exception

Since:

6.0.0

disableClientUpdate

boolean disableClientUpdate(boolean disable)

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, modifications 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 in a batch 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.

Returns:

whether it has been disabled before this invocation, i.e., the previous disable status

Since:

3.6.2

getEventListenerMap

EventListenerMap getEventListenerMap()

Returns the map of event handlers and listeners defined in this component. This method is rarely used, but it is useful if you'd like to retrieve the behavior of the event handling of this component (and if you don't have the reference to the component)

Since:

6.0.0