Package org.zkoss.zk.ui.ext.render

## Interface Cropper

- All Known Implementing Classes:
    `GridDataLoader`, `Listbox.ExtraCtrl`, `ListboxDataLoader`, `LiveGridDataLoader`, `LiveListboxDataLoader`, `Rows.ExtraCtrl`, `Treechildren.ExtraCtrl`

      public interface Cropper

  Implemented by the object returned by `ComponentCtrl.getExtraCtrl()` if not all of the children of a component are available at the client. In other word, the component support 'cropping'. Example: only children of the active page of ZUL's grid are available at the client, if it is in the paging mold.

  ZK Update Engine detects this interface and then ignores any update to components that don't have counterpart at the client.

  Author:
    tomyeh

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `java.util.Set<? extends Component>` | `getAvailableAtClient()` | Returns a set of child components that are available at the client, or null if ALL available.
    `Component` | `getCropOwner()` | Returns the owner of the cropping scope.
    `boolean` | `isCropper()` | Returns whether it is a cropper, i.e., cropping is applied.

- - ### Method Detail

    - #### isCropper

          boolean isCropper()

      Returns whether it is a cropper, i.e., cropping is applied.

      Note: this method is called when an child is detached, so you have to count one more for the total number of children. Example <= must be used, not <:
      `getChildCount() <= getPageSize()`

      The result of returning false is the same as not declaring with `Cropper`.

    - #### getAvailableAtClient

          java.util.Set<? extends Component> getAvailableAtClient()

      Returns a set of child components that are available at the client, or null if ALL available. The child components in the returned set must be in the same order of `Component.getChildren()`. In order words, you must use LinkedHashSet or similar to ensure the order in the returned set.

      Note: for better performance, it is better to return null if all children are available at the client.

      Note: the components in the returned set can have different parents. It is useful if you want to implement multi-level cropping, such as tree. Refer to `getCropOwner()`.

    - #### getCropOwner

          Component getCropOwner()

      Returns the owner of the cropping scope. In most cases, `getAvailableAtClient()` returns only the available direct children of this component, and this method returns this component. It is so-called a single-level cropping, such as listbox and tree.

      If you want to implement multi-level cropping, such as tree, you can consider the whole tree as a cropping scope. And, `getAvailableAtClient()` returns all available items, not just the child of this component. In additions, this method returns the tree.

      Since:
        3.6.3