Package org.zkoss.zk.ui

## Class Components

- java.lang.Object
- - org.zkoss.zk.ui.Components

-     public class Components
      extends java.lang.Object

  Utilities to access `Component`.
  Author:
    tomyeh

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `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

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `Components()` |

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static java.lang.String` | `componentToPath​(Component comp, Component ref)` | Converts a component to a path (relevant to another component).
    `static Composer` | `getComposer​(Component comp)` | Returns the composer object, or null if not found.
    `static Page` | `getCurrentPage​(Component comp)` | Returns the page of the give component, or the current page if the component is null or it doesn't belong to any page.
    `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)` | Returns the implicit object of the specified name, or null if not found.
    `static java.lang.Object` | `getImplicit​(Page page, java.lang.String name)` | Returns 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)` | Returns the implicit object of the specified name, or null if not found.
    `static java.util.Collection<java.lang.String>` | `getImplicitNames()` | Returns a readonly collection of the names of the implicit objects.
    `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<Component>` | `getVisibleChildren​(Component comp)` | Returns a collection of visible children.
    `static boolean` | `isAncestor​(Component node1, Component node2)` | Tests whether node1 is an ancestor of node 2.
    `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<Component> 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` | `smartUpdate​(Component comp, java.lang.String key, java.lang.Object value, boolean append)` | Adds the smartUpdate command to the specific component.
    `static void` | `sort​(java.util.List<? extends Component> list, int from, int to, java.util.Comparator<? super Component> cpr)` | Sorts the components in the list.
    `static void` | `sort​(java.util.List<? extends Component> list, java.util.Comparator<? super Component> cpr)` | Sorts the components in the list.

    - ### 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<? extends Component> list,
                                  java.util.Comparator<? super Component> cpr)

      Sorts the components in the list.

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

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

    - #### sort

          public static void sort​(java.util.List<? extends Component> list,
                                  int from,
                                  int to,
                                  java.util.Comparator<? super Component> 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

    - #### 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<Component> newChildren)

      Replaces all children of the specified component. It is the same as

          parent.getChildren().clear();
          parent.getChildren().addAll(newChildren);

      Since:
        3.5.2

    - #### 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 ancestor 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 visibility even if it is a root component, such as `Components.isRealVisible(getParent())`.

      See Also:
        `Component.isVisible()`

    - #### getVisibleChildren

          public static java.util.Collection<Component> 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`.

    - #### componentToPath

          public static final java.lang.String componentToPath​(Component comp,
                                                               Component ref)

      Converts a component to a path (relevant 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

    - #### 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

    - #### getImplicitNames

          public static java.util.Collection<java.lang.String> getImplicitNames()

      Returns a readonly collection of the names of the implicit objects.
      Since:
        6.0.0

    - #### getImplicit

          public static java.lang.Object getImplicit​(Page page,
                                                     Component comp,
                                                     java.lang.String name)

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

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

      Returns 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

    - #### getComposer

          public static Composer getComposer​(Component comp)

      Returns the composer object, or null if not found.
      Since:
        7.0.3

    - #### smartUpdate

          public static void smartUpdate​(Component comp,
                                         java.lang.String key,
                                         java.lang.Object value,
                                         boolean append)

      Adds the smartUpdate command to the specific component.
      Since:
        7.0.3

    - #### getCurrentPage

          public static Page getCurrentPage​(Component comp)

      Returns the page of the give component, or the current page if the component is null or it doesn't belong to any page. The current page is retrieved by `ExecutionCtrl.getCurrentPage()` or the current execution. This method returns null if no execution or no current page at all.
      Parameters:
        `comp` - the component to retrieve the page. Ignored if null.
      Since:
        6.0.0