org.zkoss.zk.ui
Class Components

java.lang.Object
  extended by org.zkoss.zk.ui.Components

public class Components
extends java.lang.Object

Utilities to access Component.

Author:
tomyeh

Field Summary
static org.zkoss.zk.ui.Components.Exec EXECUTION_PROXY
          Execution Proxy
static org.zkoss.zk.ui.Components.RequestScope REQUEST_SCOPE_PROXY
          Request Scope Proxy
 
Constructor Summary
protected Components()
           
 
Method Summary
static void addForwards(Component comp, java.lang.Object controller)
          Adds forward conditions to myid source component so onXxx source event received by myid component can be forwarded to the specified target component with the target event name onXxx$myid.
static void addForwards(Component comp, java.lang.Object controller, char separator)
          Adds forward conditions to the specified component with a custom separator.
static java.lang.String componentToPath(Component comp, Component ref)
          Converts a component to a path (relavant to another component).
static ComponentDefinition getDefinitionByDeviceType(java.lang.String deviceType, java.lang.Class cls)
          Returns the component definition of the specified class in all language of the specified device, or null if not found
static java.lang.Object getImplicit(Component comp, java.lang.String name)
          Retuns the implicit object of the specified name, or null if not found.
static java.lang.Object getImplicit(Page page, Component comp, java.lang.String name)
          Retuns the implicit object of the specified name, or null if not found.
static java.lang.Object getImplicit(Page page, java.lang.String name)
          Retuns the implicit object of the specified name, or null if not found.
static IdSpace getParentIdSpace(IdSpace idspace)
          Returns the parent of the ID space, or null if not found.
static Component getRoot(Component comp)
          Returns the root component of the specified one.
static int getScope(java.lang.String scope)
          Converts a string to an integer that can be used to access Component.getAttribute(String, int)
static java.util.Collection getVisibleChildren(Component comp)
          Returns a collection of visible children.
static boolean isAncestor(Component node1, Component node2)
          Tests whether node1 is an ancessor of node 2.
static boolean isAutoId(java.lang.String id)
          Returns whether an ID is generated automatically.
static boolean isImplicit(java.lang.String id)
          Returns whether the given id is an implicit ZK object id.
static boolean isRealVisible(Component comp)
          Returns whether this component is real visible (all its parents are visible).
static Component pathToComponent(java.lang.String path, Component ref)
          Converts a path, generated by componentToPath(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component), to a component.
static void removeAllChildren(Component comp)
          Removes all children of the specified component.
static void replace(Component oldc, Component newc)
          Replaces a component with another.
static void replaceChildren(Component parent, java.util.Collection newChildren)
          Replaces all children of the specified component.
static java.lang.String scopeToString(int scope)
          Converts an integer to the string representing the scope.
static void sort(java.util.List list, java.util.Comparator cpr)
          Sorts the components in the list.
static void sort(java.util.List list, int from, int to, java.util.Comparator cpr)
          Sorts the components in the list.
static void wireController(Component comp, java.lang.Object controller)
          Wire controller as a variable objects of the specified component with a custom separator.
static void wireController(Component comp, java.lang.Object controller, char separator)
          Wire controller as a variable objects of the specified component with a custom separator.
static void wireFellows(IdSpace idspace, java.lang.Object controller)
          Wire fellow components and space owner ancestors of the specified Id space into a controller Java object.
static void wireFellows(IdSpace idspace, java.lang.Object controller, char separator)
          Wire fellow components and space owner with a custom separator.
static void wireVariables(Component comp, java.lang.Object controller)
          Wire accessible variable objects of the specified component into a controller Java object.
static void wireVariables(Component comp, java.lang.Object controller, char separator)
          Wire accessible variable objects of the specified component with a custom separator.
static void wireVariables(Page page, java.lang.Object controller)
          Wire accessible variables of the specified page into a controller Java object.
static void wireVariables(Page page, java.lang.Object controller, char separator)
          Wire accessible variable objects of the specified page with a custom separator.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

EXECUTION_PROXY

public static final org.zkoss.zk.ui.Components.Exec EXECUTION_PROXY
Execution Proxy


REQUEST_SCOPE_PROXY

public static final org.zkoss.zk.ui.Components.RequestScope REQUEST_SCOPE_PROXY
Request Scope Proxy

Constructor Detail

Components

protected Components()
Method Detail

getParentIdSpace

public static IdSpace getParentIdSpace(IdSpace idspace)
Returns the parent of the ID space, or null if not found.

Since:
5.0.0

sort

public static void sort(java.util.List list,
                        java.util.Comparator cpr)
Sorts the components in the list.

Note: you cannot use Collections.sort(java.util.List) to sort Component.getChildren() because Collections.sort might cause some replicated item in the list.

See Also:
sort(List, int, int, Comparator)

replace

public static void replace(Component oldc,
                           Component newc)
Replaces a component with another.

Parameters:
oldc - the component to remove.
newc - the component to add
Throws:
java.lang.IllegalArgumentException - if oldc's parent and page are both null.
Since:
3.5.2

replaceChildren

public static void replaceChildren(Component parent,
                                   java.util.Collection newChildren)
Replaces all children of the specified component. It is the same as
parent.getChildren().clear();
parent.getChildren().addAll(newChildren);

Since:
3.5.2

sort

public static void sort(java.util.List list,
                        int from,
                        int to,
                        java.util.Comparator cpr)
Sorts the components in the list.

Parameters:
list - the list to be sorted
from - the index of the first element (inclusive) to be sorted
to - the index of the last element (exclusive) to be sorted
cpr - the comparator to determine the order of the list.
Since:
3.5.0

getRoot

public static Component getRoot(Component comp)
Returns the root component of the specified one. Notice that it could return comp, if it is already a root component (or it is null).

Since:
3.6.3

isAncestor

public static boolean isAncestor(Component node1,
                                 Component node2)
Tests whether node1 is an ancessor of node 2. If node1 and node2 is the same, true is returned.


removeAllChildren

public static void removeAllChildren(Component comp)
Removes all children of the specified component. It is the same as comp.getChildren().clear().


getDefinitionByDeviceType

public static final ComponentDefinition getDefinitionByDeviceType(java.lang.String deviceType,
                                                                  java.lang.Class cls)
Returns the component definition of the specified class in all language of the specified device, or null if not found

Parameters:
deviceType - the device type (Device), such as ajax. It cannot be null.
cls - the implementation class of the component.
Since:
5.0.0

isRealVisible

public static boolean isRealVisible(Component comp)
Returns whether this component is real visible (all its parents are visible).

Note: true is returned if comp is null. In other words, it can be used to examine parent's real visibity even if it is a root component, such as Components.isRealVisible(getParent()).

See Also:
Component.isVisible()

getVisibleChildren

public static java.util.Collection getVisibleChildren(Component comp)
Returns a collection of visible children.

The performance of the returned collection's size() is NO GOOD.


getScope

public static final int getScope(java.lang.String scope)
Converts a string to an integer that can be used to access Component.getAttribute(String, int)


scopeToString

public static final java.lang.String scopeToString(int scope)
Converts an integer to the string representing the scope.

Parameters:
scope - one of Component.COMPONENT_SCOPE, Component.SPACE_SCOPE, Component.PAGE_SCOPE, Component.DESKTOP_SCOPE, Component.SESSION_SCOPE, Component.REQUEST_SCOPE, and Component.APPLICATION_SCOPE.

isAutoId

public static final boolean isAutoId(java.lang.String id)
Returns whether an ID is generated automatically.


componentToPath

public static final java.lang.String componentToPath(Component comp,
                                                     Component ref)
Converts a component to a path (relavant to another component). It is usefully to implement a serializable component that contains a reference to another component. In this case, we can not serializes the reference directly (otherwise, another component will be created, when deserialized).

Rather, it is better to store the path related, and then restore it back to a component by calling pathToComponent(java.lang.String, org.zkoss.zk.ui.Component).

Parameters:
comp - the component to be converted to path. It cannot be null.
ref - the component used to generated the path from. It cannot be null.
Returns:
the path. Notice that you have to use pathToComponent(java.lang.String, org.zkoss.zk.ui.Component) to convert it back.
Throws:
java.lang.UnsupportedOperationException - if we cannot find a path to the component to write.
Since:
3.0.0

pathToComponent

public static final Component pathToComponent(java.lang.String path,
                                              Component ref)
Converts a path, generated by componentToPath(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component), to a component.

Parameters:
ref - the component used to generated the path from. It cannot be null. It is the same as the one when calling componentToPath(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component).
Since:
3.0.0

wireFellows

public static final void wireFellows(IdSpace idspace,
                                     java.lang.Object controller)
Wire fellow components and space owner ancestors of the specified Id space into a controller Java object. This implementation checks the setXxx() method names first then the field names. If a setXxx() method name matches the id of a fellow or space owner ancestors and with correct argument type, the found method is called with the fellow component as the argument. If no proper setXxx() method then search the field of the controller object for a matched field with name equals to the fellow component's id and proper type. Then the fellow component is assigned as the value of the matched field.

Note that fellow components are looked up first, then the space owner ancestors

since 3.5.2, the controller would be assigned as a variable of the given idspace per the naming convention composed of the idspace id and controller Class name. e.g. if the idspace id is "xwin" and the controller class is org.zkoss.MyController, then the variable name would be "xwin$MyController"

This is useful in writing controller code in MVC design practice. You can wire the components into the controller object per the component's id and do whatever you like.

Since 3.6.0, for Groovy or other environment that '$' is not applicable, you can invoke wireFellows(IdSpace,Object,char) to use '_' as the separator.

Parameters:
idspace - the id space to be bound
controller - the controller Java object to be injected the fellow components.
Since:
3.0.6

wireFellows

public static final void wireFellows(IdSpace idspace,
                                     java.lang.Object controller,
                                     char separator)
Wire fellow components and space owner with a custom separator. The separator is used to separate the component ID and additional information, such as event name. By default, it is '$'. However, for Groovy or other environment that '$' is not applicable, you can invoke this method to use '_' as the separator.

Since:
3.6.0
See Also:
wireFellows(IdSpace, Object)

wireVariables

public static final void wireVariables(Component comp,
                                       java.lang.Object controller)

Wire accessible variable objects of the specified component into a controller Java object. This implementation checks the setXxx() method names first then the field names. If a setXxx() method name matches the name of the resolved variable object with correct argument type and the associated field value is null, then the method is called with the resolved variable object as the argument. If no proper setXxx() method then search the field name of the controller object. If the field name matches the name of the resolved variable object with correct field type and null field value, the field is then assigned the resolved variable object.

since 3.5.2, the controller would be assigned as a variable of the given component per the naming convention composed of the component id and controller Class name. e.g. if the component id is "xwin" and the controller class is org.zkoss.MyController, then the variable name would be "xwin$MyController"

This is useful in writing controller code in MVC design practice. You can wire the embedded objects, components, and accessible variables into the controller object per the components' id and variables' name and do whatever you like.

Since 3.6.0, for Groovy or other environment that '$' is not applicable, you can invoke wireVariables(Component,Object,char) to use '_' as the separator.

Parameters:
comp - the reference component to wire variables
controller - the controller Java object to be injected the accessible variable objects.
Since:
3.0.6
See Also:
GenericAutowireComposer

wireVariables

public static final void wireVariables(Component comp,
                                       java.lang.Object controller,
                                       char separator)
Wire accessible variable objects of the specified component with a custom separator. The separator is used to separate the component ID and additional information, such as event name. By default, it is '$'. However, for Groovy or other environment that '$' is not applicable, you can invoke this method to use '_' as the separator.

Since:
3.6.0
See Also:
wireVariables(Component, Object)

wireVariables

public static final void wireVariables(Page page,
                                       java.lang.Object controller)

Wire accessible variables of the specified page into a controller Java object. This implementation checks the setXxx() method names first then the field names. If a setXxx() method name matches the name of the resolved variable object with correct argument type and the associated field value is null, then the method is called with the resolved variable object as the argument. If no proper setXxx() method then search the field name of the controller object. If the field name matches the name of the resolved variable object with correct field type and null field value, the field is then assigned the resolved variable object.

since 3.5.2, the controller would be assigned as a variable of the given page per the naming convention composed of the page id and controller Class name. e.g. if the page id is "xpage" and the controller class is org.zkoss.MyController, then the variable name would be "xpage$MyController"

Since 3.0.8, if the method name of field name matches the ZK implicit object name, ZK implicit object will be wired in, too.

This is useful in writing controller code in MVC design practice. You can wire the embedded objects, components, and accessible variables into the controller object per the component's id and variable name and do whatever you like.

Since 3.6.0, for Groovy or other environment that '$' is not applicable, you can invoke wireVariables(Page,Object,char) to use '_' as the separator.

Parameters:
page - the reference page to wire variables
controller - the controller Java object to be injected the fellow components.
Since:
3.0.6

wireVariables

public static final void wireVariables(Page page,
                                       java.lang.Object controller,
                                       char separator)
Wire accessible variable objects of the specified page with a custom separator. The separator is used to separate the component ID and additional information, such as event name. By default, it is '$'. However, for Groovy or other environment that '$' is not applicable, you can invoke this method to use '_' as the separator.

Since:
3.6.0
See Also:
wireVariables(Page, Object)

wireController

public static final void wireController(Component comp,
                                        java.lang.Object controller)
Wire controller as a variable objects of the specified component with a custom separator. The separator is used to separate the component ID and the controller. By default, it is '$'. However, for Groovy or other environment that '$' is not applicable, you can invoke wireController(Component, Object, char) to use '_' as the separator.

Since:
3.6.1

wireController

public static final void wireController(Component comp,
                                        java.lang.Object controller,
                                        char separator)
Wire controller as a variable objects of the specified component with a custom separator. The separator is used to separate the component ID and the controller. By default, it is '$'. However, for Groovy or other environment that '$' is not applicable, you can invoke this method to use '_' as the separator.

Since:
3.6.1

addForwards

public static void addForwards(Component comp,
                               java.lang.Object controller)

Adds forward conditions to myid source component so onXxx source event received by myid component can be forwarded to the specified target component with the target event name onXxx$myid.

The controller is a POJO file with onXxx$myid methods (the event handler codes). This utility method search such onXxx$myid methods and adds forward condition to the source myid component looked up by Component.getAttributeOrFellow(java.lang.String, boolean) of the specified component, so you don't have to specify in zul file the "forward" attribute one by one. If the source component cannot be looked up or the object looked up is not a component, this method will log the error and ignore it.

since 3.0.8, cascade '$' will add Forwards cascadely. E.g. define method onClick$btn$w1 in window w2. This method will add a forward on the button "btn.onClick=w1.onClick$btn" and add another forward on the window w1 "w1.onClick$btn=w2.onClick$btn$w1"

Since 3.6.0, for Groovy or other environment that '$' is not applicable, you can invoke addForwards(Component,Object,char) to use '_' as the separator.

Parameters:
comp - the targetComponent
controller - the controller code with onXxx$myid event handler methods
Since:
3.0.7

addForwards

public static void addForwards(Component comp,
                               java.lang.Object controller,
                               char separator)
Adds forward conditions to the specified component with a custom separator. The separator is used to separate the component ID and additional information, such as event name. By default, it is '$'. However, for Groovy or other environment that '$' is not applicable, you can invoke this method to use '_' as the separator.

Since:
3.6.0
See Also:
addForwards(Component, Object)

isImplicit

public static boolean isImplicit(java.lang.String id)
Returns whether the given id is an implicit ZK object id.

Parameters:
id - Component id
Returns:
whether the given name is a implicit object.
Since:
3.5.2

getImplicit

public static java.lang.Object getImplicit(Page page,
                                           Component comp,
                                           java.lang.String name)
Retuns the implicit object of the specified name, or null if not found.

Notice that it does check for the current scope (Scopes.getCurrent(org.zkoss.zk.ui.Page)). Rather, Scopes.getImplicit(java.lang.String, java.lang.Object) depends on this method.

Parameters:
page - the page. If page is null and comp is not, comp.getPage() is assumed
Since:
5.0.0
See Also:
Scopes.getImplicit(java.lang.String, java.lang.Object)

getImplicit

public static java.lang.Object getImplicit(Component comp,
                                           java.lang.String name)
Retuns the implicit object of the specified name, or null if not found.

It is the same as getImplicit(null, comp, name).

Since:
3.6.0

getImplicit

public static java.lang.Object getImplicit(Page page,
                                           java.lang.String name)
Retuns the implicit object of the specified name, or null if not found.

It is the same as getImplicit(page, null, name).

Since:
3.6.0


Copyright © 2005-2009 Potix Corporation. All Rights Reserved. SourceForge.net Logo