public interface ComponentCtrl
Component
that is used for implementation or tools.
Application developers rarely need to access methods in this interface.
Modifier and Type | Field and Description |
---|---|
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. |
Modifier and Type | Method and Description |
---|---|
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.
|
boolean |
addRedrawCallback(Callback<ContentRenderer> callback)
Adds a callback at component redraw phase.
|
boolean |
addShadowRoot(ShadowElement shadow)
Adds the given shadow root from this host.
|
boolean |
addShadowRootBefore(ShadowElement shadow,
ShadowElement insertBefore)
Adds the given shadow root from this host.
|
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.
|
void |
disableBindingAnnotation()
Set to disable the component with binding annotation.
|
boolean |
disableClientUpdate(boolean disable)
Sets whether to disable the update of the client widgets of
this component and its descendants.
|
void |
enableBindingAnnotation()
Set to enable the component with binding annotation.
|
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.
|
PropertyAccess |
getPropertyAccess(java.lang.String prop)
Returns the corresponding property access object from the given property
name, if any.
|
java.util.Collection<Callback<ContentRenderer>> |
getRedrawCallback()
Returns all of callbacks for component redraw phase
|
<T extends ShadowElement> |
getShadowRoots()
Returns a set of shadow elements, if any.
|
int |
getSubBindingAnnotationCount()
Returns the count of the component's subtree binding annotation.
|
boolean |
hasBindingAnnotation()
Returns whether the component itself has binding annotation or not.
|
boolean |
hasSubBindingAnnotation()
Returns whether the component and its children have binding annotation or not.
|
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.
|
boolean |
removeRedrawCallback(Callback<ContentRenderer> callback)
Removes a callback for component redraw phase.
|
boolean |
removeShadowRoot(ShadowElement shadow)
Removes the given shadow root from this host.
|
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.
|
static final int CE_IMPORTANT
getClientEvents()
to indicate the event is important
and the client must send it back even if no listener is registered.static final int CE_NON_DEFERRABLE
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
static final int CE_BUSY_IGNORE
getClientEvents()
to indicate the event
can be ignored by the server when the server is busy.static final int CE_DUPLICATE_IGNORE
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.static final int CE_REPEAT_IGNORE
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.void setDefinition(ComponentDefinition compdef)
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.
java.lang.IllegalArgumentException
- if compdef is nullvoid setDefinition(java.lang.String defname)
defname
- the name of the component definitionjava.lang.IllegalArgumentException
- if defname is nullDefinitionNotFoundException
- if the component definition not foundvoid beforeChildAdded(Component child, Component insertBefore)
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.void beforeChildRemoved(Component child)
child
- the child to be removed (never null)void beforeParentChanged(Component parent)
parent
- the new parent. If null, it means detachment.void onChildAdded(Component child)
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.
void onChildRemoved(Component child)
It is not a good idea to throw an exception in this method, since it is in the middle of modifying the component tree.
void onPageAttached(Page newpage, Page oldpage)
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.
newpage
- the new page (never null).oldpage
- the previous page, if any, or null if it didn't
belong to any page.void onPageDetached(Page 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.
page
- the previous page (never null)ZScript getEventHandler(java.lang.String evtnm)
void addEventHandler(java.lang.String name, EventHandler evthd)
Component.setWidgetListener(java.lang.String, java.lang.String)
will
overwrite the previous listener if the event name is the same.void addSharedEventHandlerMap(EventHandlerMap evthds)
evthds
- a map of event handlerComponent.setWidgetListener(java.lang.String, java.lang.String)
java.util.Set<java.lang.String> getEventHandlerNames()
Component.getWidgetListenerNames()
java.util.Map<java.lang.String,java.lang.Integer> getClientEvents()
CE_IMPORTANT
, CE_BUSY_IGNORE
,
CE_DUPLICATE_IGNORE
and CE_REPEAT_IGNORE
).
Default: return the collection of events
added by getClientEvents()
.
Annotation getAnnotation(java.lang.String annotName)
getAnnotation(String, String)
.Annotation getAnnotation(java.lang.String propName, java.lang.String annotName)
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 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>
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 namegetAnnotations(String, String)
java.util.Collection<Annotation> getAnnotations(java.lang.String propName, java.lang.String annotName)
Notice that the property is 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>
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 namegetAnnotation(String, String)
java.util.Collection<Annotation> getAnnotations()
getAnnotations(String)
.java.util.Collection<Annotation> getAnnotations(java.lang.String propName)
Annotation
)
associated with the specified property. It never returns null.propName
- the property name, e.g., "value".
If null, this method returns the annotation(s) associated with this
component (rather than a particular property).java.util.List<java.lang.String> getAnnotatedPropertiesBy(java.lang.String annotName)
java.util.List<java.lang.String> getAnnotatedProperties()
void addAnnotation(java.lang.String annotName, java.util.Map<java.lang.String,java.lang.String[]> annotAttrs)
addAnnotation(String, String, Map)
void addAnnotation(java.lang.String propName, java.lang.String annotName, java.util.Map<java.lang.String,java.lang.String[]> annotAttrs)
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.
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.void sessionWillPassivate(Page page)
Note: only root components are notified by this method.
void sessionDidActivate(Page page)
Note: only root components are notified by this method.
java.lang.Object getExtraCtrl()
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.
Cropper
.PropertyAccess getPropertyAccess(java.lang.String prop)
prop
- the name of the propertyWrongValueException onWrongValue(WrongValueException ex)
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.ex
- the exception being thrown (never null)void redraw(java.io.Writer out) throws java.io.IOException
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.
java.io.IOException
void service(AuRequest request, boolean everError)
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)
.
everError
- whether any error ever occurred before
processing this request.Component.setAuService(org.zkoss.zk.au.AuService)
void service(Event event, Scope scope) throws java.lang.Exception
event
- the event to handlescope
- the scope to evaluate the zscript, if any.
(see also Page.interpret(java.lang.String, java.lang.String, org.zkoss.zk.ui.ext.Scope)
.java.lang.Exception
boolean disableClientUpdate(boolean disable)
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:
Also notice that, with Component.invalidate()
,
it is easy to synchronize the content of a component
(and its descendants) to the client.
EventListenerMap getEventListenerMap()
<T extends ShadowElement> java.util.List<T> getShadowRoots()
boolean removeShadowRoot(ShadowElement shadow)
shadow
- a shadow elementboolean addShadowRoot(ShadowElement shadow)
shadow
- a shadow elementboolean addShadowRootBefore(ShadowElement shadow, ShadowElement insertBefore)
shadow
- a shadow elementinsertBefore
- the shadow before which you want the new childvoid enableBindingAnnotation()
void disableBindingAnnotation()
boolean hasBindingAnnotation()
boolean hasSubBindingAnnotation()
int getSubBindingAnnotationCount()
boolean addRedrawCallback(Callback<ContentRenderer> callback)
callback
- boolean removeRedrawCallback(Callback<ContentRenderer> callback)
callback
- java.util.Collection<Callback<ContentRenderer>> getRedrawCallback()
Copyright © 2005-2011 Potix Corporation. All Rights Reserved.