org.zkoss.zk.ui.sys
Interface ComponentCtrl

All Known Implementing Classes:

A, Abbr, AbstractComponent, AbstractTag, Acronym, Address, Applet, Area, Area, Audio, Auxhead, Auxheader, B, Bandbox, Bandpopup, Base, Big, Blockquote, Body, Borderlayout, Box, Br, Button, Button, Calendar, Captcha, Caption, Caption, Center, Center, Chart, Checkbox, Cite, Code, Col, Colgroup, Column, Columnchildren, Columnlayout, Columns, Combobox, Comboitem, Datebox, Dd, Decimalbox, Del, Detail, Dfn, Dir, Div, Div, Dl, Doublebox, Dt, East, Em, Embed, FailoverButton, Fieldset, Fileupload, FileuploadDlg, Fisheye, Fisheyebar, Flash, Font, Foot, Footer, Form, FormatInputElement, Grid, Group, Groupbox, Groupfoot, H1, H2, H3, H4, Hbox, Head, HeaderElement, HeadersElement, Hello, Hr, Html, Html, HtmlBasedComponent, HtmlMacroComponent, HtmlNativeComponent, I, Iframe, Iframe, Image, Imagemap, Img, Include, Input, InputElement, Ins, Intbox, Isindex, Jasperreport, Kbd, Label, Label, LabelElement, LabelImageElement, LayoutRegion, Legend, Li, Link, Listbox, Listcell, Listfoot, Listfooter, Listgroup, Listgroupfoot, Listhead, Listheader, Listitem, Longbox, MainLayout, MainWindow, Map, Menu, Menu, Menubar, Menuitem, Menupopup, Menuseparator, 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, Select, Separator, SimpleAutoComplete, Slider, Small, South, Space, Span, Span, Spinner, Splitter, Strong, Style, Style, Sub, Sup, Tab, Tabbox, Table, Tablechildren, Tablelayout, Tabpanel, Tabpanels, Tabs, Tbody, Td, Text, Textarea, Textbox, Tfoot, Th, Thead, ThemeImage, Timebox, Timer, Title, Toolbar, Toolbarbutton, Tr, Transformer, Tree, Treecell, Treechildren, Treecol, Treecols, Treefoot, Treefooter, Treeitem, Treerow, Tt, Ul, Var, Vbox, 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

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.
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	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).
Command	getCommand(java.lang.String cmdId) Returns the component-specific command of the specified command ID, or null if not found.
ZScript	getEventHandler(java.lang.String evtnm) Returns the event handler 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.
void	onChildAdded(Component child) Called when a child is added.
void	onChildRemoved(Component child) Called when a child is removed.
void	onDrawNewChild(Component child, java.lang.StringBuffer out) Called when a new-created child is about to render.
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	response(java.lang.String key, AuResponse response) Causes a response to be sent to the client.
void	sessionDidActivate(Page page) Notification that the session, which owns this component, has just been activated (aka., deserialized).
void	sessionWillPassivate(Page page) Notification that the session, which owns this component, is about to be passivated (aka., serialized).
void	setComponentDefinition(ComponentDefinition compdef) Sets the component definition.
void	smartUpdate(java.lang.String attr, java.lang.String value) Smart-updates a property with the specified value.
void	smartUpdateDeferred(java.lang.String attr, DeferredValue value) Smart-updates a property with a deferred value.
void	smartUpdateValues(java.lang.String attr, java.lang.Object[] values) Smart-updates a property with an array of values.

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

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, while onDrawNewChild(org.zkoss.zk.ui.Component, java.lang.StringBuffer) is called in the redrawing phase. See onDrawNewChild(org.zkoss.zk.ui.Component, java.lang.StringBuffer) for more details.

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

onDrawNewChild

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

Called when a new-created child is about to render. It gives the parent a chance to fine-tune the output. Note: it won't be called if the parent is rendered, too. In other words, it is called only if the child is attached dynamically.

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

Note: onChildAdded(org.zkoss.zk.ui.Component) is called in the request-processing phase, while onDrawNewChild(org.zkoss.zk.ui.Component, java.lang.StringBuffer) is called in the redrawing phase. Component developer might do one of the follows:

• Nothing, if new child can be inserted directly.
• Overwrite onDrawNewChild(org.zkoss.zk.ui.Component, java.lang.StringBuffer) to add special tags, if new child needs to be added an exterior with some tags before insertion.
  Morever, if you shall add id="${child.uuid}!chdextr" to the added exterior.
• Redraw the parent, if it is too complicated. How: overwrite onChildAdded(org.zkoss.zk.ui.Component) and calls Component.invalidate()

Parameters:

child - the child being rendered

out - the rendered result of the child.

Throws:

java.io.IOException

Since:

3.5.0

smartUpdate

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

Smart-updates a property with the specified value. Called by component developers to do precise-update.

The second invocation with the same property will replace the previous call. In other words, the same property will be set only once in each execution.

This method has no effect if Component.invalidate() is ever invoked (in the same execution), since Component.invalidate() assumes the whole content shall be redrawn and all smart updates to this components can be ignored,

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

Parameters:

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

Since:

3.5.0

See Also:

smartUpdateDeferred(java.lang.String, org.zkoss.zk.ui.util.DeferredValue), smartUpdateValues(java.lang.String, java.lang.Object[])

smartUpdateDeferred

void smartUpdateDeferred(java.lang.String attr,
                         DeferredValue value)

Smart-updates a property with a deferred value. A deferred value is used to encapsulate a value that shall be retrieved only in the rendering phase. In other words, DeferredValue.getValue() won't be called until the rendering phase. On the other hand, this method is usually called in the event processing phase.

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

Since:

3.5.0

See Also:

smartUpdate(java.lang.String, java.lang.String), smartUpdateValues(java.lang.String, java.lang.Object[])

smartUpdateValues

void smartUpdateValues(java.lang.String attr,
                       java.lang.Object[] values)

Smart-updates a property with an array of values.

Parameters:

values - an array of values. Any of them must be an instance of String or DeferredValue.

Since:

3.5.0

See Also:

smartUpdate(java.lang.String, java.lang.String), smartUpdateDeferred(java.lang.String, org.zkoss.zk.ui.util.DeferredValue)

response

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.String), 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:

3.5.0

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

getEventHandlerNames

java.util.Set getEventHandlerNames()

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

Since:

3.0.2

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

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

getCommand

Command getCommand(java.lang.String cmdId)

Returns the component-specific command of the specified command ID, or null if not found. It searches only the command specific to this component. For global commands, use AuRequest.getCommand(java.lang.String) instead.

Since:

3.0.5

See Also:

ComponentCommand

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

Returns:

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

Since:

3.6.2