Package org.zkoss.zk.ui

## Interface ShadowElementCtrl

- All Known Implementing Classes:
    `Apply`, `Choose`, `ForEach`, `HtmlShadowElement`, `If`, `Otherwise`, `TemplateBasedShadowElement`, `When`

      public interface ShadowElementCtrl

  An addition interface to `ShadowElement`
  Since:
    8.0.0
  Author:
    jumperchen

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `afterHostChildAdded​(Component child, int indexOfChild)` | Called when a child is added to the host.
    `void` | `afterHostChildRemoved​(Component child)` | Called when a child is removed to the host.
    `void` | `beforeHostChildAdded​(Component child, Component insertBefore, int indexOfInsertBefore)` | Called before the host adding a child.
    `void` | `beforeHostChildRemoved​(Component child, int indexOfChild)` | Called before the host removing a child.
    `void` | `beforeHostParentChanged​(Component parent)` | Called before the host changing the parent.
    `Component` | `getFirstInsertion()` | Returns the first component of its insertion range.
    `Component` | `getLastInsertion()` | Returns the last component of its insertion range.
    `Component` | `getNextInsertion()` | Returns the next insertion point, it may be a component, a shadow element, or null.
    `Component` | `getPreviousInsertion()` | Returns the previous insertion point, it may be a component, a shadow element, or null.
    `Component` | `getShadowHostIfAny()` | Return the shadow host from it or its ancestor, if any.
    `boolean` | `isDynamicValue()` | Returns whether the shadow element contains a dynamic value, it means the shadow element cannot be destroyed after evaluated.
    `void` | `onHostChildAdded​(Component child)` | Called when a child of a host is added into this shadow element.
    `void` | `onHostChildRemoved​(Component child)` | Called when a child of a host is added into this shadow element.
    `java.lang.Object` | `resolveVariable​(Component child, java.lang.String name, boolean recurse)` | Returns the variable associated with this base component or null if not found.
    `void` | `setDynamicValue​(boolean dynamicValue)` | Sets whether the shadow element contains a dynamic value, if true means the shadow element cannot be destroyed after evaluated, if false it will detect its attribute automatically.
    `void` | `setShadowHost​(Component host, Component insertBefore)` | Sets the owner component that hosts this shadow element.

- - ### Method Detail

    - #### setShadowHost

          void setShadowHost​(Component host,
                             Component insertBefore)

      Sets the owner component that hosts this shadow element.
      Parameters:
        `host` - the host of the shadow element
        `insertBefore` - a component or a shadow element to indicate where the shadow's insertion point is added.

    - #### beforeHostChildRemoved

          void beforeHostChildRemoved​(Component child,
                                      int indexOfChild)

      Called before the host removing a child.
      Parameters:
        `child` - the child to be removed (never null)
        `indexOfChild` - the index of the removed child

    - #### beforeHostParentChanged

          void beforeHostParentChanged​(Component parent)

      Called before the host changing the parent.
      Parameters:
        `parent` - the new parent. If null, it means detachment.

    - #### beforeHostChildAdded

          void beforeHostChildAdded​(Component child,
                                    Component insertBefore,
                                    int indexOfInsertBefore)

      Called before the host adding a child.
      Parameters:
        `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.
        `indexOfInsertBefore` - the index of the insertBefore, if any. Otherwise -1 is assumed.

    - #### afterHostChildAdded

          void afterHostChildAdded​(Component child,
                                   int indexOfChild)

      Called when a child is added to the host.
      Parameters:
        `child` - the child has been added (never null).
        `indexOfChild` - the index of the added child.

    - #### afterHostChildRemoved

          void afterHostChildRemoved​(Component child)

      Called when a child is removed to the host.
      Parameters:
        `child` - the child has been added (never null).

    - #### isDynamicValue

          boolean isDynamicValue()

      Returns whether the shadow element contains a dynamic value, it means the shadow element cannot be destroyed after evaluated.

    - #### setDynamicValue

          void setDynamicValue​(boolean dynamicValue)

      Sets whether the shadow element contains a dynamic value, if true means the shadow element cannot be destroyed after evaluated, if false it will detect its attribute automatically.

      Default: false (auto detection)

      Since:
        8.0.1

    - #### getShadowHostIfAny

          Component getShadowHostIfAny()

      Return the shadow host from it or its ancestor, if any.
      Returns:
        null or a host component

    - #### resolveVariable

          java.lang.Object resolveVariable​(Component child,
                                           java.lang.String name,
                                           boolean recurse)

      Returns the variable associated with this base component or null if not found.

      Notice that it doesn't check any variable defined in `VariableResolver` (of `Page.addVariableResolver(org.zkoss.xel.VariableResolver)`).

      Parameters:
        `child` - the child component of the shadow host
        `recurse` - whether to look up the parent shadow for the existence of the variable.
        If recurse is true, it will look up all parents until found.

    - #### getNextInsertion

          Component getNextInsertion()

      Returns the next insertion point, it may be a component, a shadow element, or null.

    - #### getPreviousInsertion

          Component getPreviousInsertion()

      Returns the previous insertion point, it may be a component, a shadow element, or null.

    - #### getFirstInsertion

          Component getFirstInsertion()

      Returns the first component of its insertion range.

    - #### getLastInsertion

          Component getLastInsertion()

      Returns the last component of its insertion range.

    - #### onHostChildAdded

          void onHostChildAdded​(Component child)

      Called when a child of a host is added into this shadow element.

    - #### onHostChildRemoved

          void onHostChildRemoved​(Component child)

      Called when a child of a host is added into this shadow element.