Package org.zkoss.stateless.ui

## Interface UiAgent

-     public interface UiAgent

  Utilities to manipulate `IComponent` to the client.

  Note: All the operational APIs for `IComponent` must be run in an asynchronous update phase. (aka. `Execution.isAsyncUpdate(Page)` will be true)

  Author:
    jumperchen

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface | Description
    --- | --- | ---
    `static class` | `UiAgent.Position` | Insert Adjacent position for `insertAdjacentComponent(Locator, Position, IComponent)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `<I extends IComponent> UiAgent` | `appendChild​(Locator locator, I newChild)` | Adds the specified child component as the last child to the current locator.
    `static UiAgent` | `getCurrent()` | Returns the current UiAgent if any.
    `<I extends IComponent> UiAgent` | `insertAdjacentComponent​(Locator locator, UiAgent.Position position, I newChild)` | Inserts a given newChild at a given `UiAgent.Position` relative to the locator component it is invoked upon.
    `<I extends IComponent> UiAgent` | `insertAfterBegin​(Locator locator, I newChild)` | Inserts a given newChild just inside the locator before its first child.
    `<I extends IComponent> UiAgent` | `insertAfterEnd​(Locator locator, I newChild)` | Inserts a given newChild after the locator itself.
    `<I extends IComponent> UiAgent` | `insertBefore​(Locator locator, I newChild, int childIndex)` | Inserts the given newChild just inside the locator, before its n-th child.
    `<I extends IComponent> UiAgent` | `insertBeforeBegin​(Locator locator, I newChild)` | Inserts a given newChild before the locator itself.
    `<I extends IComponent> UiAgent` | `insertBeforeEnd​(Locator locator, I newChild)` | Inserts a given newChild just inside the locator after its last child.
    `boolean` | `isActivated()` | Returns whether this execution of UiAgent is activated.
    `static UiAgent` | `of​(Execution execution)` | Returns a new UiAgent from the given execution, which is activated.
    `java.util.concurrent.CompletableFuture<UiAgent>` | `ofAsync()` | Returns a new CompletableFuture that is asynchronously completed by retrieving a new `UiAgent` instance in a CompletableFuture.
    `UiAgent` | `remove​(Locator locator)` | Removes the given locator component.
    `<I extends IComponent> UiAgent` | `replaceChild​(Locator locator, I newChild, int childIndex)` | Replaces the given newChild just inside the locator with its n-th child.
    `<I extends IComponent> UiAgent` | `replaceChildren​(Locator locator)` | Removes the existing children of the given locator component.
    `<I extends IComponent> UiAgent` | `replaceChildren​(Locator locator, I... children)` | Replaces the existing children of the given locator component with a specified new set of children `IComponent`s.
    `<I extends IComponent> UiAgent` | `replaceChildren​(Locator locator, java.util.List<I> children)` | Replaces the existing children of the given locator component with a specified new set of children `IComponent`s.
    `<I extends IComponent> UiAgent` | `replaceWith​(Locator locator, I newComp)` | Replaces the given locator component in the children list of its parent with a given new `IComponent`.
    `java.util.concurrent.CompletableFuture<UiAgent>` | `runAsync​(CheckedConsumer<UiAgent> consumer)` | Runs the given callback that is asynchronously completed by retrieving a new `UiAgent` instance in a CompletableFuture.
    `UiAgent` | `smartUpdate​(Locator locator, SmartUpdater updater)` | A special smart update to update all the new data in the given updater.

- - ### Method Detail

    - #### appendChild

          <I extends IComponent> UiAgent appendChild​(Locator locator,
                                                     I newChild)

      Adds the specified child component as the last child to the current locator.

    - #### insertBefore

          <I extends IComponent> UiAgent insertBefore​(Locator locator,
                                                      I newChild,
                                                      int childIndex)

      Inserts the given newChild just inside the locator, before its n-th child.

    - #### replaceChild

          <I extends IComponent> UiAgent replaceChild​(Locator locator,
                                                      I newChild,
                                                      int childIndex)

      Replaces the given newChild just inside the locator with its n-th child.

    - #### replaceWith

          <I extends IComponent> UiAgent replaceWith​(Locator locator,
                                                     I newComp)

      Replaces the given locator component in the children list of its parent with a given new `IComponent`.

    - #### replaceChildren

          <I extends IComponent> UiAgent replaceChildren​(Locator locator)

      Removes the existing children of the given locator component.

    - #### replaceChildren

          <I extends IComponent> UiAgent replaceChildren​(Locator locator,
                                                         I... children)

      Replaces the existing children of the given locator component with a specified new set of children `IComponent`s.

    - #### replaceChildren

          <I extends IComponent> UiAgent replaceChildren​(Locator locator,
                                                         java.util.List<I> children)

      Replaces the existing children of the given locator component with a specified new set of children `IComponent`s.

    - #### insertAdjacentComponent

          <I extends IComponent> UiAgent insertAdjacentComponent​(Locator locator,
                                                                 UiAgent.Position position,
                                                                 I newChild)

      Inserts a given newChild at a given `UiAgent.Position` relative to the locator component it is invoked upon.

    - #### insertBeforeBegin

          <I extends IComponent> UiAgent insertBeforeBegin​(Locator locator,
                                                           I newChild)

      Inserts a given newChild before the locator itself.
      See Also:
        `insertAdjacentComponent(Locator, Position, IComponent)`

    - #### insertBeforeEnd

          <I extends IComponent> UiAgent insertBeforeEnd​(Locator locator,
                                                         I newChild)

      Inserts a given newChild just inside the locator after its last child. The same as `appendChild(Locator, IComponent)`.
      See Also:
        `insertAdjacentComponent(Locator, Position, IComponent)`

    - #### insertAfterBegin

          <I extends IComponent> UiAgent insertAfterBegin​(Locator locator,
                                                          I newChild)

      Inserts a given newChild just inside the locator before its first child.
      See Also:
        `insertAdjacentComponent(Locator, Position, IComponent)`

    - #### insertAfterEnd

          <I extends IComponent> UiAgent insertAfterEnd​(Locator locator,
                                                        I newChild)

      Inserts a given newChild after the locator itself.
      See Also:
        `insertAdjacentComponent(Locator, Position, IComponent)`

    - #### smartUpdate

          UiAgent smartUpdate​(Locator locator,
                              SmartUpdater updater)

      A special smart update to update all the new data in the given updater.

    - #### remove

          UiAgent remove​(Locator locator)

      Removes the given locator component.
      Parameters:
        `locator` -

    - #### isActivated

          boolean isActivated()

      Returns whether this execution of UiAgent is activated.
      Returns:

    - #### runAsync

          java.util.concurrent.CompletableFuture<UiAgent> runAsync​(CheckedConsumer<UiAgent> consumer)

      Runs the given callback that is asynchronously completed by retrieving a new `UiAgent` instance in a CompletableFuture.

      Note: this doesn't support in cloud mode

    - #### ofAsync

          java.util.concurrent.CompletableFuture<UiAgent> ofAsync()

      Returns a new CompletableFuture that is asynchronously completed by retrieving a new `UiAgent` instance in a CompletableFuture.

      Note: this doesn't support in cloud mode

    - #### of

          static UiAgent of​(Execution execution)

      Returns a new UiAgent from the given execution, which is activated.

    - #### getCurrent

          static UiAgent getCurrent()

      Returns the current UiAgent if any.