|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.
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 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). |
java.util.Map |
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 |
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 |
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 (aka., redraw) this component and all its descendants. |
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). |
void |
setDefinition(ComponentDefinition compdef)
Sets the component definition. |
void |
setDefinition(java.lang.String defname)
Sets the component definition by specifing the name. |
Field Detail |
---|
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.
Method Detail |
---|
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 definition
java.lang.IllegalArgumentException
- if defname is null
DefinitionNotFoundException
- 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)
Component.getWidgetListener(java.lang.String)
void addEventHandler(java.lang.String name, EventHandler evthd)
Component.setWidgetListener(java.lang.String, java.lang.String)
will
overwrite the pevious listener if the event name is the same.
Component.setWidgetListener(java.lang.String, java.lang.String)
void addSharedEventHandlerMap(EventHandlerMap evthds)
evthds
- a map of event handlerComponent.setWidgetListener(java.lang.String, java.lang.String)
java.util.Set getEventHandlerNames()
Component.getWidgetListenerNames()
java.util.Map 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)
annotName
- the annotation nameAnnotation getAnnotation(java.lang.String propName, java.lang.String annotName)
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>
annotName
- the annotation namepropName
- the property name, e.g., "value".
java.lang.IllegalArgumentException
- if propName is null or emptyjava.util.Collection getAnnotations()
java.util.Collection getAnnotations(java.lang.String propName)
propName
- the property name, e.g., "value".
java.lang.IllegalArgumentException
- if propName is null or emptyjava.util.List getAnnotatedPropertiesBy(java.lang.String annotName)
java.util.List getAnnotatedProperties()
void addSharedAnnotationMap(AnnotationMap annots)
annots
- a annotation map.void addAnnotation(java.lang.String annotName, java.util.Map annotAttrs)
Unlike Java, you can add annotations dynamically, and each component has its own annotations.
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).void addAnnotation(java.lang.String propName, java.lang.String annotName, java.util.Map annotAttrs)
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).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
.WrongValueException 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(java.lang.String, 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(org.zkoss.zk.au.AuRequest, boolean)
instead.
This method is designed to be overriden.
To send reponses to the client, use
AbstractComponent.smartUpdate(java.lang.String, java.lang.Object)
,
AbstractComponent.response(java.lang.String, 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 occured before
processing this request.Component.setAuService(org.zkoss.zk.au.AuService)
boolean disableClientUpdate(boolean disable)
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:
Also notice that, with Component.invalidate()
,
it is easy to synchronize the content of a component
(and its descendants) to the client.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |