| org.zkoss.zk.ui.Component
All known Subclasses: org.zkoss.zk.ui.AbstractComponent,
Component | public interface Component extends java.io.Serializable,Cloneable(Code) | | A UI component.
There are two kind of lifecycles: one is page creations and the other
is asynchronous updates.
The Page Creation
The page creation occurs when a page is about to render at the first
time. The detailed phases can be found in the devloper's guide.
The Asynchronous Update
The asynchronous update occurs when users does something on the browser,
such as changing the content of input, clicking buttons and so on.
Such behaviors are packed as requests, queue in the browser, and then
send to the server at the proper time. The detailed phases
can be found in the developer's guide.
No Synchronization Required
To simplify the development of components and applications,
invocations of methods of components and event listener are all serialized.
In other words, application and component developers need not worry
synchronization and other thread issues (unless you are developing
background thread to handle long operations).
It also implies a limitation that you cannot access components
belonging to other desktops when processing an event.
author: tomyeh |
Method Summary | |
public boolean | addEventListener(String evtnm, EventListener listener) Adds an event listener to specified event for this component. | public boolean | addForward(String originalEvent, Component target, String targetEvent) Adds a forward condition to forward the event received
by this component to another component.
Default: no forward condition at all.
Once the condition is added, a event called targetEvent
is posted to the target compoennt,
when this component receives the orginalEvent event.
Parameters: originalEvent - the original event that was receivedby this component. | public boolean | addForward(String originalEvent, String targetPath, String targetEvent) Adds a forward condition to forward the event received
by this component to another component, specified with a path.
Note: the target component is retrieved from the path, each time
the event is received. | public boolean | appendChild(Component child) Appends a child. | public void | applyProperties() Initializes the properties (aka. | public Object | clone() Clones the component.
All of its children is cloned.
Notice that the cloned component doesn't belong to any page, nor
desktop. | public boolean | containsVariable(String name, boolean local) Returns whether the specified variable is defined. | public void | detach() Detaches this component such that it won't belong to any page. | public Object | getAttribute(String name, int scope) Returns the value of the specified custom attribute in the specified scope,
or null if not defined. | public Object | getAttribute(String name) Returns the custom attribute associated with this component, i.e.,
Component.COMPONENT_SCOPE . | public Map | getAttributes(int scope) Returns all custom attributes of the specified scope. | public Map | getAttributes() Returns all custom attributes associated with this component, i.e.,
Component.COMPONENT_SCOPE . | public List | getChildren() Returns a live list of children. | public ComponentDefinition | getDefinition() Returns the component definition of this component (never null). | public Desktop | getDesktop() Returns the desktop of this component,
or null if this component doesn't belong to any desktop.
When a component is created in an event listener, it
is assigned to the current desktop automatically.
If a component is created not in any event listener, it doesn't
belong to any desktop and this method returns null.
Once a component is attached to a desktop (thru
Component.setPage or
Component.setParent ), it belongs to the desktop.
Notice: there is no way to detach a component from a desktop,
once it is attached as described above.
In other words, you cannot move a component (or page) from
one desktop to another.
In summary, there are only two ways to handle components.
- Handle them all in event listeners and don't access any components
from other desktops.
| public Component | getFellow(String id) Returns a component of the specified ID in the same ID space. | public Component | getFellowIfAny(String id) Returns a component of the specified ID in the same ID space, or null
if not found. | public Component | getFirstChild() Returns the first child component, or null if no child at all. | public String | getId() Returns the ID. | public Component | getLastChild() Returns the last child component, or null if no child at all. | public Iterator | getListenerIterator(String evtnm) Returns an iterator for iterating listener for the specified event. | public String | getMold() Returns the mold for this component. | public Namespace | getNamespace() Returns the namespace to store variables and functions belonging
to the ID space of this component.
Exactly one namespace is allocated for each ID space.
For example, if the space owner of this component is the page, then
the returned namespace is the same as
Page.getNamespace .
Otherwise, it is the same as the namspace returned by the component
owning this ID space.
Namspace is another part of an ID space. | public Component | getNextSibling() Returns the next sibling, or null if it is the last child. | public Page | getPage() Returns the page that this component belongs to, or null if
it doesn't belong to any page.
When a component is created (aka., constructed), it doesn't
belong to any page. | public Component | getParent() Returns the parent component, or null if this is the root component. | public Component | getPreviousSibling() Returns the previous sibling, or null if it is the first child. | public Component | getRoot() Returns the root of this component. | public IdSpace | getSpaceOwner() Returns the owner of the ID space that this component belongs to.
The returned value could be a component, a page or null.
If this component itself implements
IdSpace , this method
returns itself.
If it has an ancestor that implements
IdSpace ,
the ancestor is returned.
Otherwise, the page it belongs to is returned
Each ID space defines an independent set of IDs. | public String | getUuid() Returns UUID (universal unique ID) which is unquie in the whole
session. | public Object | getVariable(String name, boolean local) Returns the value of a variable defined in the namespace,
or null if not defined or the value is null. | public boolean | insertBefore(Component newChild, Component refChild) Inserts a child before the reference child.
You could use
Component.setParent or
Component.appendChild instead of this method, unless
you want to control where to put the child.
Note:
Component.setParent always calls back
Component.insertBefore and/or
Component.removeChild ,
while
Component.insertBefore and
Component.removeChild always calls back
Component.setParent ,
if the parent is changed. | public void | invalidate() Invalidates this component by setting the dirty flag
such that it will be redraw the whole content later. | public boolean | isChildable() Returns whether this component allows to have any child. | public boolean | isListenerAvailable(String evtnm, boolean asap) Returns whether the event listener is available. | public boolean | isVisible() Returns whether this component is visible. | public void | onChildAdded(Component child) Called when a child is added.
If a component want to optimize the update, it might do something
different. | public void | onChildRemoved(Component child) Called when a child is removed.
If a component want to optimize the update, it might do something
different. | public void | onDrawNewChild(Component child, StringBuffer out) Called when a new-created child is about to render. | public void | onPageAttached(Page newpage, Page oldpage) Called when this component is attached to a page. | public void | onPageDetached(Page page) Called when this component is detached from a page. | public void | redraw(Writer out) AuRequest this component to render (aka., redraw) itself
and its children. | public Object | removeAttribute(String name, int scope) Removes the specified custom attribute in the specified scope. | public Object | removeAttribute(String name) Removes the custom attribute associated with this component, i.e.,
Component.COMPONENT_SCOPE . | public boolean | removeChild(Component child) Removes a child. | public boolean | removeEventListener(String evtnm, EventListener listener) Removes an event listener. | public boolean | removeForward(String originalEvent, Component target, String targetEvent) Removes a forward condition that was added by
Component.addForward(String,Component,String) .
If no such forward condition exists, nothing happens but return false.
Parameters: originalEvent - the oringal event that was receivedby this component.It must be the same as the one passed to Component.addForward(String,Component,String). Parameters: target - the target component to receive the event.It must be the same as the one passed to Component.addForward(String,Component,String). Parameters: targetEvent - the target event that the target component will receive.It must be the same as the one passed to Component.addForward(String,Component,String). | public boolean | removeForward(String originalEvent, String targetPath, String targetEvent) Removes a forward condition that was added by
Component.addForward(String,String,String) .
If no such forward condition exists, nothing happens but return false.
Parameters: originalEvent - the oringal event that was receivedby this component.It must be the same as the one passed to Component.addForward(String,Component,String). Parameters: targetPath - the target component's path related to this component.If ".", this component is assumed.If null, the space owner is assumed.If null and the space owner is the page, the root component is assumed. Parameters: targetEvent - the target event that the target component will receive.It must be the same as the one passed to Component.addForward(String,Component,String). | public void | response(String key, AuResponse response) Causes a response (aka., a command) 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
Component.smartUpdate , responses are sent to client if
it is component independent or it is not removed.
In other words, it is 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 methodin the same execution with the same key will override the previous one.However, if key is null, it won't override any other. | public Object | setAttribute(String name, Object value, int scope) Sets the value of the specified custom attribute in the specified scope.
Note: The attribute is removed (by
Component.removeAttribute if value is null, while
Component.setVariable considers null as a legal value.
If scope is
Component.COMPONENT_SCOPE , it means custom attributes private
to this component.
If scope is
Component.SPACE_SCOPE , it means custom attributes shared
by components from the same ID space as this one's.
If scope is
Component.PAGE_SCOPE , it means custom attributes shared
by components from the same page as this one's.
If scope is
Component.DESKTOP_SCOPE , it means custom attributes shared
by components from the same desktopas this one's.
Parameters: scope - Component.COMPONENT_SCOPE, Component.SPACE_SCOPE,Component.PAGE_SCOPE, Component.DESKTOP_SCOPE, Component.SESSION_SCOPE,Component.REQUEST_SCOPE or Component.APPLICATION_SCOPE, Parameters: value - the value. | public Object | setAttribute(String name, Object value) Sets the custom attribute associated with this component, i.e.,
Component.COMPONENT_SCOPE . | public void | setId(String id) Sets the ID. | public void | setMold(String mold) Sets the mold for this component.
Parameters: mold - the mold. | public void | setPage(Page page) Sets what page this component belongs to.
If this component already belongs to the same page, nothing
is changed.
For child components, the page they belong is maintained
automatically. | public void | setPageBefore(Page page, Component refRoot) Sets what page this component belongs to, and insert
this component right before the reference component.
For child components, the page they belong is maintained
automatically. | public void | setParent(Component parent) Sets the parent component.
Note:
Component.setParent always calls back
Component.insertBefore and/or
Component.removeChild ,
while
Component.insertBefore and
Component.removeChild always calls back
Component.setParent ,
if the parent is changed. | public void | setVariable(String name, Object val, boolean local) Sets a variable to the namespace.
This method is the same as
getNamespace().setVariable(name, value, local).
Once a variable is set thru this method, it is visible to
both the interpreter and EL.
Note: Exactly one namespace is allocated for each ID space.
For example, if the space owner of this component is the page, then
the returned namespace is the same as
Page.getNamespace .
Otherwise, it is the same as the namspace returned by the component
owning this ID space.
When to use setVariable and setAttribute?
First, only the ID space support
Component.setVariable and so.
Second, the variables can be referenced directly in zscript and EL
expressions, while attributes are referenced thru the scope,
such as spaceScope.
On the other hand, using attributes causes less name popultion.
In general, if you could use attributes, don't use variable.
Parameters: local - whether not to search any of the ancestor namespace definesthe variable. | public boolean | setVisible(boolean visible) Sets whether this component is visible. | public void | smartUpdate(String attr, 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. | public void | smartUpdateDeferred(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. | public void | unsetVariable(String name, boolean local) Unsets a variable defined in the namespace. |
APPLICATION_SCOPE | final public static int APPLICATION_SCOPE(Code) | | Used with
Component.getAttribute and relevants to denote
custom attributes shared by the whole application.
It is also known as the application attributes.
It is the same as
WebApp.getAttributes .
|
COMPONENT_SCOPE | final public static int COMPONENT_SCOPE(Code) | | Used with
Component.getAttribute and relevants to denote
custom attributes private to a component is searched.
It is also known as the component attributes.
It is the same as
Component.getAttributes .
|
DESKTOP_SCOPE | final public static int DESKTOP_SCOPE(Code) | | Used with
Component.getAttribute and relevants to denote
custom attributes shared by the same desktop.
It is also known as the desktop attributes.
It is the same as
Desktop.getAttributes .
|
PAGE_SCOPE | final public static int PAGE_SCOPE(Code) | | Used with
Component.getAttribute and relevants to denote
custom attributes shared by the same page.
It is also known as the page attributes.
It is the same as
Page.getAttributes .
|
SESSION_SCOPE | final public static int SESSION_SCOPE(Code) | | Used with
Component.getAttribute and relevants to denote
custom attributes shared by the same session.
It is also known as the session attributes.
It is the same as
Session.getAttributes .
|
SPACE_SCOPE | final public static int SPACE_SCOPE(Code) | | Used with
Component.getAttribute and relevants to denote
custom attributes shared by the same ID space.
It is also known as the ID space attributes.
|
addEventListener | public boolean addEventListener(String evtnm, EventListener listener)(Code) | | Adds an event listener to specified event for this component.
The second registration is ignored and false is returned.
You could register listener to all components in the same page
by use of
Page.addEventListener .
Parameters: evtnm - what event to listen (never null) whether the listener is added; false if it was added before See Also: Page.addEventListener |
addForward | public boolean addForward(String originalEvent, Component target, String targetEvent)(Code) | | Adds a forward condition to forward the event received
by this component to another component.
Default: no forward condition at all.
Once the condition is added, a event called targetEvent
is posted to the target compoennt,
when this component receives the orginalEvent event.
Parameters: originalEvent - the original event that was receivedby this component. If null, "onClick" is assumed. Parameters: target - the target component to receive the event.If null, the space owner Component.getSpaceOwner is assumed.If null and the space owner is the page, the root component is assumed. Parameters: targetEvent - the target event that the target componentwill receive.If null, it is the same as the original event. whether it is added successfully.It returns false if the conditioin was always added before. since: 3.0.0 See Also: Component.removeForward(String,Component,String) |
addForward | public boolean addForward(String originalEvent, String targetPath, String targetEvent)(Code) | | Adds a forward condition to forward the event received
by this component to another component, specified with a path.
Note: the target component is retrieved from the path, each time
the event is received. Thus, you can reference to a component
that is created later.
Parameters: originalEvent - the original event that was receivedby this component. If null, "onClick" is assumed. Parameters: targetPath - the target component's path related to this component.If ".", this component is assumed.If null, the space owner is assumed.If null and the space owner is the page, the root component is assumed. Parameters: targetEvent - the target event that the target componentwill receive.If null, it is the same as the original event. whether it is added successfully.It returns false if the conditioin was always added before. See Also: Component.addForward(String,Component,String) See Also: Component.removeForward(String,String,String) since: 3.0.0 |
applyProperties | public void applyProperties()(Code) | | Initializes the properties (aka. members) and custom-attributes
based on what are defined in the component definition.
This method is invoked automatically if a component is created
by evaluating a ZUML page, i.e., if it is specified as an elemnt
of a ZUML page.
On the other hand, if it is created manually (by program),
developer might choose to invoke this method or not,
depending whether he wants to
initializes the component with the properties and custom-attributes
defined in the ZUML page (
org.zkoss.zk.ui.metainfo.PageDefinition )
and the language definition (
org.zkoss.zk.ui.metainfo.LanguageDefinition ).
|
clone | public Object clone()(Code) | | Clones the component.
All of its children is cloned.
Notice that the cloned component doesn't belong to any page, nor
desktop. It doesn't have parent, either.
|
containsVariable | public boolean containsVariable(String name, boolean local)(Code) | | Returns whether the specified variable is defined.
Note: null is a valid value for variable, so this method is used
to know whether a variable is defined.
On the other hand,
Component.setAttribute actually remove
an attribute (by
Component.removeAttribute if value is null.
Parameters: local - whether not to search its ancestor.If false and the current namespace doen't define the variable,it searches up its ancestor (via Component.getParent) to seeany of them has defined the specified variable. |
detach | public void detach()(Code) | | Detaches this component such that it won't belong to any page.
If you don't call
Component.setParent or
Component.setPage to
attach it to any page, it will be removed automatically
(from the client) after the current event is processed.
|
getAttribute | public Object getAttribute(String name, int scope)(Code) | | Returns the value of the specified custom attribute in the specified scope,
or null if not defined.
If scope is
Component.COMPONENT_SCOPE , it means attributes private
to this component.
If scope is
Component.SPACE_SCOPE , it means custom attributes shared
by components from the same ID space as this one's.
If scope is
Component.PAGE_SCOPE , it means custom attributes shared
by components from the same page as this one's.
If scope is
Component.DESKTOP_SCOPE , it means custom attributes shared
by components from the same desktopas this one's.
Parameters: scope - Component.COMPONENT_SCOPE, Component.SPACE_SCOPE,Component.PAGE_SCOPE, Component.DESKTOP_SCOPE, Component.SESSION_SCOPE,Component.REQUEST_SCOPE or Component.APPLICATION_SCOPE, |
getAttributes | public Map getAttributes(int scope)(Code) | | Returns all custom attributes of the specified scope.
You could reference them thru componentScope, spaceScope, pageScope,
requestScope and desktopScope in zscript and EL.
If scope is
Component.COMPONENT_SCOPE , it means custom attributes private
to this component.
If scope is
Component.SPACE_SCOPE , it means custom attributes shared
by components from the same ID space as this one's.
If scope is
Component.PAGE_SCOPE , it means custom attributes shared
by components from the same page as this one's.
If scope is
Component.DESKTOP_SCOPE , it means custom attributes shared
by components from the same desktopas this one's.
Parameters: scope - Component.COMPONENT_SCOPE, Component.SPACE_SCOPE,Component.PAGE_SCOPE, Component.DESKTOP_SCOPE, Component.SESSION_SCOPE,Component.REQUEST_SCOPE or Component.APPLICATION_SCOPE, |
getChildren | public List getChildren()(Code) | | Returns a live list of children.
You could add or remove a child by manipulating the returned list directly.
|
getDefinition | public ComponentDefinition getDefinition()(Code) | | Returns the component definition of this component (never null).
|
getDesktop | public Desktop getDesktop()(Code) | | Returns the desktop of this component,
or null if this component doesn't belong to any desktop.
When a component is created in an event listener, it
is assigned to the current desktop automatically.
If a component is created not in any event listener, it doesn't
belong to any desktop and this method returns null.
Once a component is attached to a desktop (thru
Component.setPage or
Component.setParent ), it belongs to the desktop.
Notice: there is no way to detach a component from a desktop,
once it is attached as described above.
In other words, you cannot move a component (or page) from
one desktop to another.
In summary, there are only two ways to handle components.
- Handle them all in event listeners and don't access any components
from other desktops. This is simplest and clearest.
- Creates components in another thread (other than event listener)
and attach them to a page (and then desktop) upon an event is received.
|
getFellowIfAny | public Component getFellowIfAny(String id)(Code) | | Returns a component of the specified ID in the same ID space, or null
if not found.
Unlike
Component.getFellow , it returns null if not found.
|
getFirstChild | public Component getFirstChild()(Code) | | Returns the first child component, or null if no child at all.
since: 3.0.0 |
getId | public String getId()(Code) | | Returns the ID. If it is a root component (i.e., without parent),
its ID must be unquie among root components of the same page.
If a component belongs to an ID space (see
IdSpace ),
the ID must also be unique in the ID space it belongs.
any its parent and ancestor implements
IdSpace .
A page itself is also an ID space, so you could retrieve
compnents in a page by use of
Page.getFellow , unless
the component is a descendant of another component that implements
IdSpace . In this case, you have to retrieve the parent
first (by use of
Page.getFellow and then use
Component.getFellow against the owner of the ID space.
In zscript and EL, a component with explicit ID can be accessed
directly by the ID. In other word, a variable named by the ID is
created automatically.
See Also: Page |
getLastChild | public Component getLastChild()(Code) | | Returns the last child component, or null if no child at all.
since: 3.0.0 |
getListenerIterator | public Iterator getListenerIterator(String evtnm)(Code) | | Returns an iterator for iterating listener for the specified event.
|
getNamespace | public Namespace getNamespace()(Code) | | Returns the namespace to store variables and functions belonging
to the ID space of this component.
Exactly one namespace is allocated for each ID space.
For example, if the space owner of this component is the page, then
the returned namespace is the same as
Page.getNamespace .
Otherwise, it is the same as the namspace returned by the component
owning this ID space.
Namspace is another part of an ID space. It holds only variables
defined thru
Component.setVariable (and
Namespace.setVariable .
Note: The namespace doesn't include any variable defined by
executing zscripts. To retrieve them, use
Page.getZScriptVariable .
See Also: Component.getSpaceOwner |
getNextSibling | public Component getNextSibling()(Code) | | Returns the next sibling, or null if it is the last child.
since: 3.0.0 |
getPage | public Page getPage()(Code) | | Returns the page that this component belongs to, or null if
it doesn't belong to any page.
When a component is created (aka., constructed), it doesn't
belong to any page. And, if a component doesn't belong to
any page, they won't be displayed at the client.
When changing parent (
Component.setParent ), the child component's
page will become the same as parent's. In other words, a component
is added to a page automatically if it becomes a child of
another component (who belongs to a page).
For root components, you have to invoke
Component.setPage explicityly.
See Also: Component.setParent See Also: Component.setPage |
getParent | public Component getParent()(Code) | | Returns the parent component, or null if this is the root component.
|
getPreviousSibling | public Component getPreviousSibling()(Code) | | Returns the previous sibling, or null if it is the first child.
since: 3.0.0 |
getRoot | public Component getRoot()(Code) | | Returns the root of this component.
|
getSpaceOwner | public IdSpace getSpaceOwner()(Code) | | Returns the owner of the ID space that this component belongs to.
The returned value could be a component, a page or null.
If this component itself implements
IdSpace , this method
returns itself.
If it has an ancestor that implements
IdSpace ,
the ancestor is returned.
Otherwise, the page it belongs to is returned
Each ID space defines an independent set of IDs. No component
in the same ID space could have the same ID.
To get any component in the same ID space, you could use
Component.getFellow .
See
IdSpace for more details.
The ID space relevant methods include
Component.getFellow ,
Component.getAttribute and
Component.getVariable .
See Also: Component.getNamespace |
getUuid | public String getUuid()(Code) | | Returns UUID (universal unique ID) which is unquie in the whole
session. The UUID is generated automatically and immutable, unless
org.zkoss.zk.ui.ext.RawId is also implemented.
It is mainly used for communication between client and server
and you rarely need to access it.
If
org.zkoss.zk.ui.ext.RawId is implemented as part of
a component, UUID is the same as
Component.getId if
Component.setId is ever called. It is designed to migrate HTML pages to ZK, such
that the element ID could remain the same.
|
invalidate | public void invalidate()(Code) | | Invalidates this component by setting the dirty flag
such that it will be redraw the whole content 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
Component.smartUpdate .
While
Component.invalidate() causes the whole content to redraw,
Component.smartUpdate let component developer control which part
to redraw.
Once this method is called, all invocations to
Component.smartUpdate will then be ignored, and
Component.redraw will be invoked later.
|
isChildable | public boolean isChildable()(Code) | | Returns whether this component allows to have any child.
|
onChildAdded | public void onChildAdded(Component child)(Code) | | Called when a child is added.
If a component want to optimize the update, it might do something
different. Otherwise, it does nothing.
Note:
Component.onChildAdded is called in the request-processing
phase, while
Component.onDrawNewChild is called in the redrawing phase.
See
Component.onDrawNewChild 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.
|
onChildRemoved | public void onChildRemoved(Component child)(Code) | | 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.
|
onDrawNewChild | public void onDrawNewChild(Component child, StringBuffer out) throws IOException(Code) | | 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
Component.smartUpdate in this method.
Note:
Component.onChildAdded is called in the request-processing
phase, while
Component.onDrawNewChild is called in the redrawing phase.
Component developer might do one of the follows:
- Nothing, if new child can be inserted directly.
- Overwrite
Component.onDrawNewChild 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
Component.onChildAdded and calls
Component.invalidate()
Parameters: child - the child being rendered Parameters: out - the rendered result of the child. |
onPageAttached | public void onPageAttached(Page newpage, Page oldpage)(Code) | | Called when this component is attached to a page.
If a component is moved from one page to another,
Component.onPageAttached is called with both pages.
Note:
Component.onPageDetached 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 .
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). Parameters: oldpage - the previous page, if any, or null if it didn'tbelong to any page. since: 3.0.0 |
onPageDetached | public void onPageDetached(Page page)(Code) | | Called when this component is detached from a page.
If a component is moved from one page to another,
Component.onPageAttached is called with both pages.
Note:
Component.onPageDetached is not called in this case.
In other words,
Component.onPageDetached 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 .
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.0.0 |
removeAttribute | public Object removeAttribute(String name, int scope)(Code) | | Removes the specified custom attribute in the specified scope.
If scope is
Component.COMPONENT_SCOPE , it means attributes private
to this component.
If scope is
Component.SPACE_SCOPE , it means custom attributes shared
by components from the same ID space as this one's.
If scope is
Component.PAGE_SCOPE , it means custom attributes shared
by components from the same page as this one's.
If scope is
Component.DESKTOP_SCOPE , it means custom attributes shared
by components from the same desktopas this one's.
Parameters: scope - Component.COMPONENT_SCOPE, Component.SPACE_SCOPE,Component.PAGE_SCOPE, Component.DESKTOP_SCOPE, Component.SESSION_SCOPE,Component.REQUEST_SCOPE or Component.APPLICATION_SCOPE, |
removeEventListener | public boolean removeEventListener(String evtnm, EventListener listener)(Code) | | Removes an event listener.
whether the listener is removed; false if it was never added. |
removeForward | public boolean removeForward(String originalEvent, Component target, String targetEvent)(Code) | | Removes a forward condition that was added by
Component.addForward(String,Component,String) .
If no such forward condition exists, nothing happens but return false.
Parameters: originalEvent - the oringal event that was receivedby this component.It must be the same as the one passed to Component.addForward(String,Component,String). Parameters: target - the target component to receive the event.It must be the same as the one passed to Component.addForward(String,Component,String). Parameters: targetEvent - the target event that the target component will receive.It must be the same as the one passed to Component.addForward(String,Component,String). whether the forward is removed successfully.It returns false if the forward condition is not found See Also: Component.addForward(String,Component,String) since: 3.0.0 |
removeForward | public boolean removeForward(String originalEvent, String targetPath, String targetEvent)(Code) | | Removes a forward condition that was added by
Component.addForward(String,String,String) .
If no such forward condition exists, nothing happens but return false.
Parameters: originalEvent - the oringal event that was receivedby this component.It must be the same as the one passed to Component.addForward(String,Component,String). Parameters: targetPath - the target component's path related to this component.If ".", this component is assumed.If null, the space owner is assumed.If null and the space owner is the page, the root component is assumed. Parameters: targetEvent - the target event that the target component will receive.It must be the same as the one passed to Component.addForward(String,Component,String). whether the forward is removed successfully.It returns false if the forward condition is not found See Also: Component.addForward(String,String,String) since: 3.0.0 |
response | public void response(String key, AuResponse response)(Code) | | Causes a response (aka., a command) 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
Component.smartUpdate , responses are sent to client if
it is component independent or it is not removed.
In other words, it is 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 methodin the same execution with the same key will override the previous one.However, if key is null, it won't override any other. All responseswith key == null will be sent. |
setAttribute | public Object setAttribute(String name, Object value, int scope)(Code) | | Sets the value of the specified custom attribute in the specified scope.
Note: The attribute is removed (by
Component.removeAttribute if value is null, while
Component.setVariable considers null as a legal value.
If scope is
Component.COMPONENT_SCOPE , it means custom attributes private
to this component.
If scope is
Component.SPACE_SCOPE , it means custom attributes shared
by components from the same ID space as this one's.
If scope is
Component.PAGE_SCOPE , it means custom attributes shared
by components from the same page as this one's.
If scope is
Component.DESKTOP_SCOPE , it means custom attributes shared
by components from the same desktopas this one's.
Parameters: scope - Component.COMPONENT_SCOPE, Component.SPACE_SCOPE,Component.PAGE_SCOPE, Component.DESKTOP_SCOPE, Component.SESSION_SCOPE,Component.REQUEST_SCOPE or Component.APPLICATION_SCOPE, Parameters: value - the value. If null, the attribute is removed. |
setId | public void setId(String id)(Code) | | Sets the ID. The scope of uniqunes depends on whether this component
is a root component. Refer to
Component.getId for more details.
When a component is constructed, an ID is generated automatically.
Thus, calling this method only you need to identify a component.
See Also: Page |
setPage | public void setPage(Page page)(Code) | | Sets what page this component belongs to.
If this component already belongs to the same page, nothing
is changed.
For child components, the page they belong is maintained
automatically. You need to invoke this method only for root
components.
|
setPageBefore | public void setPageBefore(Page page, Component refRoot)(Code) | | Sets what page this component belongs to, and insert
this component right before the reference component.
For child components, the page they belong is maintained
automatically. You need to invoke this method only for root
components.
It is similar to
Component.setPage , except this component
will be placed before the reference component.
If the reference component is null, this component is placed
at the end of all root components.
Parameters: refRoot - another root component used as a referencewhich this component will be placed before.If null, this component will be placed at the end of allroot components (no matter whether it already belongs to the same page). since: 3.0.0 |
setVariable | public void setVariable(String name, Object val, boolean local)(Code) | | Sets a variable to the namespace.
This method is the same as
getNamespace().setVariable(name, value, local).
Once a variable is set thru this method, it is visible to
both the interpreter and EL.
Note: Exactly one namespace is allocated for each ID space.
For example, if the space owner of this component is the page, then
the returned namespace is the same as
Page.getNamespace .
Otherwise, it is the same as the namspace returned by the component
owning this ID space.
When to use setVariable and setAttribute?
First, only the ID space support
Component.setVariable and so.
Second, the variables can be referenced directly in zscript and EL
expressions, while attributes are referenced thru the scope,
such as spaceScope.
On the other hand, using attributes causes less name popultion.
In general, if you could use attributes, don't use variable.
Parameters: local - whether not to search any of the ancestor namespace definesthe variable. If local is false and an ancesotor has defined a variablewith the same name, the variable in the ancestor is changed directly.Otherwise, a new variable is created in the namespace containingthis component. See Also: Component.getSpaceOwner See Also: Component.getNamespace |
setVisible | public boolean setVisible(boolean visible)(Code) | | Sets whether this component is visible.
the previous visibility |
smartUpdate | public void smartUpdate(String attr, String value)(Code) | | 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
(during this execution).
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
Component.smartUpdate .
While
Component.invalidate() causes the whole content to redraw,
Component.smartUpdate let component developer control which part
to redraw.
Parameters: value - the new value. If null, it means removing the property. |
smartUpdateDeferred | public void smartUpdateDeferred(String attr, DeferredValue value)(Code) | | 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 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.0.1 |
unsetVariable | public void unsetVariable(String name, boolean local)(Code) | | Unsets a variable defined in the namespace.
This method is the same as getNamespace().getVariable(name, local).
Parameters: local - whether not to search its ancestor.If false and the current namespace doen't define the variable,it searches up its ancestor (via Component.getParent) to seeany of them has defined the specified variable. See Also: Component.getSpaceOwner See Also: Component.getNamespace |
|
|