Package org.zkoss.zul

## Class GroupsModelArray<D,​H,​F,​E>

- java.lang.Object
- - org.zkoss.zul.AbstractGroupsModel<D,​H,​F,​E>
  - - org.zkoss.zul.GroupsModelArray<D,​H,​F,​E>

- All Implemented Interfaces:
    `java.io.Serializable`, `java.lang.Cloneable`, `ComponentCloneListener`, `GroupsSelectableModel<E>`, `GroupsSortableModel<D>`, `Selectable<E>`, `Sortable<D>`, `GroupsModel<D,​H,​F>`

      public class GroupsModelArray<D,​H,​F,​E>
      extends AbstractGroupsModel<D,​H,​F,​E>
      implements GroupsSortableModel<D>, ComponentCloneListener, java.lang.Cloneable

  An array implementation of `GroupsModel`. This implementation takes a list of elements that are not grouped yet, and a comparator that will be used to group them. The c supports regroup array to groups depends on `Comparator` and `GroupComparator`. For immutable content (no re-grouping allowed), please use `SimpleGroupsModel` instead.

  Generics:

  D
    The class of each data
  H
    The class of each group header
  F
    The class of each group footer
  E
    The class of each selection. It is the common base class of D, H, F. In other words, D, H and F must extend from E.

  For more information, please refer to ZK Developer's Reference: Groups Model

  By default, the model support cloneable when the component is cloned. (since 6.0.0)

  Since:
    5.0.5
  Author:
    Dennis.Chen
  See Also:
    `GroupsModel`, `SimpleGroupsModel`, `GroupComparator`, `ComponentCloneListener`, Serialized Form

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.zkoss.zul.AbstractGroupsModel

      `AbstractGroupsModel.DefaultSelectionControl<E>`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected java.util.Comparator<D>` | `_comparator` | member field to store Comparator for initial grouping.
    `protected D[][]` | `_data` | member field to store group data
    `protected java.lang.Object[]` | `_foots` | member field to store group foot data (generated in `organizeGroup(java.util.Comparator<D>, int)`)
    `protected java.lang.Object[]` | `_heads` | member field to store group head data (generated in `organizeGroup(java.util.Comparator<D>, int)`)
    `protected D[]` | `_nativedata` | member field to store native (original) array data
    `protected boolean[]` | `_opens` | member field to store group close status
    `protected boolean` | `_sortDir` | is the sort ascending?
    `protected java.util.Comparator<D>` | `_sorting` | the sorting comparator

    - ### Fields inherited from class org.zkoss.zul.AbstractGroupsModel

      `_selection`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `GroupsModelArray​(D[] data, java.util.Comparator<D> cmpr)` | Constructor with an array of data.
    `GroupsModelArray​(D[] data, java.util.Comparator<D> cmpr, int col)` | Constructor with an array of data.
    `GroupsModelArray​(D[] data, java.util.Comparator<D> cmpr, int col, boolean clone)` | Constructor with an array of data.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `addOpenGroup​(int groupIndex)` | Opens the group at the specified index.
    `java.lang.Object` | `clone()` |
    `protected F` | `createGroupFoot​(D[] groupdata, int index, int col)` | create group foot Object, default implementation return null, which means no foot .
    `protected H` | `createGroupHead​(D[] groupdata, int index, int col)` | create group head Object, default implementation return first element of groupdata.
    `protected boolean` | `createGroupOpen​(D[] groupdata, int index, int col)` | create group open status, default implementation return true, which means open the group.
    `boolean` | `equals​(java.lang.Object o)` |
    `D` | `getChild​(int groupIndex, int index)` | Returns the child value of the specified group at the specified index.
    `int` | `getChildCount​(int groupIndex)` | Returns the number of children of the specified group.
    `H` | `getGroup​(int groupIndex)` | Returns the group value at the specified index.
    `int` | `getGroupCount()` | Returns the number of groups.
    `F` | `getGroupfoot​(int groupIndex)` | Returns the foot value of the specified group, or null if the specified group does not have any foot.
    `java.lang.String` | `getSortDirection​(java.util.Comparator<D> cmpr)` | Returns the sort direction of this model for the given comparator.
    `void` | `group​(java.util.Comparator<D> cmpr, boolean ascending, int col)` | Groups and sorts the data by the specified column.
    `boolean` | `hasGroupfoot​(int groupIndex)` | Returns if the specified group has a foot value.
    `int` | `hashCode()` |
    `boolean` | `isGroupOpened​(int groupIndex)` | Whether the group is open at the specified index.
    `protected void` | `organizeGroup​(java.util.Comparator<D> cmpr, int col)` | Organizes groups based sorted data.
    `boolean` | `removeOpenGroup​(int groupIndex)` | Closes the group at the specified index.
    `void` | `sort​(java.util.Comparator<D> cmpr, boolean ascending, int col)` | It called when `Listbox` or `Grid` has to sort the content.
    `protected void` | `sortDataInGroupOrder​(java.util.Comparator<D> cmpr, boolean ascending, int colIndex)` | Sorts the native data in the group order.
    `protected void` | `sortGroupData​(H group, D[] groupdata, java.util.Comparator<D> cmpr, boolean ascending, int col)` | Sorts data within a group.
    `java.lang.String` | `toString()` |
    `java.lang.Object` | `willClone​(Component comp)` | Allows the model to clone

    - ### Methods inherited from class org.zkoss.zul.AbstractGroupsModel

      `addGroupsDataListener, addToSelection, clearSelection, fireEvent, fireSelectionEvent, getSelection, getSelectionControl, isGroupSelectable, isMultiple, isSelected, isSelectionEmpty, newEmptySelection, readSelection, removeAllSelection, removeFromSelection, removeGroupsDataListener, retainAllSelection, setGroupSelectable, setMultiple, setSelection, setSelectionControl, writeSelection`

    - ### Methods inherited from class java.lang.Object

      `finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface org.zkoss.zul.ext.GroupsSortableModel

      `sort`

    - ### Methods inherited from interface org.zkoss.zul.ext.Sortable

      `sort`

- - ### Field Detail

    - #### _nativedata

          protected D[] _nativedata

      member field to store native (original) array data

    - #### _comparator

          protected java.util.Comparator<D> _comparator

      member field to store Comparator for initial grouping.

    - #### _data

          protected D[][] _data

      member field to store group data

    - #### _heads

          protected java.lang.Object[] _heads

      member field to store group head data (generated in `organizeGroup(java.util.Comparator<D>, int)`)

    - #### _foots

          protected java.lang.Object[] _foots

      member field to store group foot data (generated in `organizeGroup(java.util.Comparator<D>, int)`)

    - #### _opens

          protected boolean[] _opens

      member field to store group close status

    - #### _sorting

          protected java.util.Comparator<D> _sorting

      the sorting comparator

    - #### _sortDir

          protected boolean _sortDir

      is the sort ascending?

  - ### Constructor Detail

    - #### GroupsModelArray

          public GroupsModelArray​(D[] data,
                                  java.util.Comparator<D> cmpr)

      Constructor with an array of data.
      Parameters:
        `data` - an array data to be grouping.
        `cmpr` - a comparator implementation help group the data. you could implements `GroupComparator` to do more grouping control.
        At 1st phase, it calls `Comparator.compare(Object, Object)` or `GroupComparator.compareGroup(Object, Object)` to sort the data.
        At 2nd phase, it calls `Comparator.compare(Object, Object)` or `GroupComparator.compareGroup(Object, Object)` to decide which data belong to which group. In this phase it also invoke `createGroupHead(Object[], int, int)` and `createGroupFoot(Object[], int, int)` to create head of foot Object of each group.
        At 3rd phase, it calls `Comparator.compare(Object, Object)` to sort data in each group.

    - #### GroupsModelArray

          public GroupsModelArray​(D[] data,
                                  java.util.Comparator<D> cmpr,
                                  int col)

      Constructor with an array of data. It is the same as GroupsModelArray(data, cmpr, col, true), i.e., `data` will be cloned first, so `data`'s content won't be changed.
      Parameters:
        `data` - an array data to be grouping.
        `cmpr` - a comparator implementation help group the data. you could implements `GroupComparator` to do more grouping control.
        At 1st phase, it calls `Comparator.compare(Object, Object)` or `GroupComparator.compareGroup(Object, Object)` to sort the data.
        At 2nd phase, it calls `Comparator.compare(Object, Object)` or `GroupComparator.compareGroup(Object, Object)` to decide which data belong to which group. In this phase it also invoke `createGroupHead(Object[], int, int)` and `createGroupFoot(Object[], int, int)` to create head of foot Object of each group.
        At 3rd phase, it calls `Comparator.compare(Object, Object)` to sort data in each group.
        `col` - column index associate with cmpr.

    - #### GroupsModelArray

          public GroupsModelArray​(D[] data,
                                  java.util.Comparator<D> cmpr,
                                  int col,
                                  boolean clone)

      Constructor with an array of data.
      Parameters:
        `data` - an array data to be grouping.
        `cmpr` - a comparator implementation help group the data. you could implements `GroupComparator` to do more grouping control.
        At 1st phase, it calls `Comparator.compare(Object, Object)` or `GroupComparator.compareGroup(Object, Object)` to sort the data.
        At 2nd phase, it calls `Comparator.compare(Object, Object)` or `GroupComparator.compareGroup(Object, Object)` to decide which data belong to which group. In this phase it also invoke `createGroupHead(Object[], int, int)` and `createGroupFoot(Object[], int, int)` to create head of foot Object of each group.
        At 3rd phase, it calls `Comparator.compare(Object, Object)` to sort data in each group.
        `col` - column index associate with cmpr.
        `clone` - whether to clone `data`. If not cloning, data's content will be changed.
      Since:
        5.0.6

  - ### Method Detail

    - #### getChild

          public D getChild​(int groupIndex,
                            int index)

      Description copied from interface: `GroupsModel`
      Returns the child value of the specified group at the specified index.
      Specified by:
        `getChild` in interface `GroupsModel<D,​H,​F>`
      Parameters:
        `groupIndex` - the index of the group.
        `index` - the index of the element in the group.

    - #### getChildCount

          public int getChildCount​(int groupIndex)

      Description copied from interface: `GroupsModel`
      Returns the number of children of the specified group.

      Note: it does not include the group foot (`GroupsModel.getGroupfoot(int)`).

      Specified by:
        `getChildCount` in interface `GroupsModel<D,​H,​F>`
      Parameters:
        `groupIndex` - the index of the group.

    - #### getGroup

          public H getGroup​(int groupIndex)

      Description copied from interface: `GroupsModel`
      Returns the group value at the specified index. It is used to render `Group` and `Listgroup`.
      Specified by:
        `getGroup` in interface `GroupsModel<D,​H,​F>`
      Parameters:
        `groupIndex` - the index of the group.

    - #### getGroupCount

          public int getGroupCount()

      Description copied from interface: `GroupsModel`
      Returns the number of groups.
      Specified by:
        `getGroupCount` in interface `GroupsModel<D,​H,​F>`

    - #### getGroupfoot

          public F getGroupfoot​(int groupIndex)

      Description copied from interface: `GroupsModel`
      Returns the foot value of the specified group, or null if the specified group does not have any foot. It is used to render `Groupfoot` and `Listgroupfoot`.

      Note: it is ignored if `GroupsModel.hasGroupfoot(int)` returns false.

      Specified by:
        `getGroupfoot` in interface `GroupsModel<D,​H,​F>`
      Parameters:
        `groupIndex` - the index of the group.

    - #### hasGroupfoot

          public boolean hasGroupfoot​(int groupIndex)

      Description copied from interface: `GroupsModel`
      Returns if the specified group has a foot value.
      Specified by:
        `hasGroupfoot` in interface `GroupsModel<D,​H,​F>`
      Parameters:
        `groupIndex` - the index of the group.

    - #### sort

          public void sort​(java.util.Comparator<D> cmpr,
                           boolean ascending,
                           int col)

      Description copied from interface: `GroupsSortableModel`
      It called when `Listbox` or `Grid` has to sort the content.

      After sorting, this model shall notify the instances of `ListDataListener` (registered thru `ListModel.addListDataListener(org.zkoss.zul.event.ListDataListener)`) to update the content. Typically you have to notify with

          new ListDataEvent(this, ListDataEvent.CONTENTS_CHANGED, -1, -1)

      to denote all data are changed (and reloading is required).

      The comparator assigned to, say, `Listheader.setSortAscending(java.util.Comparator)` is passed to method as the cmpr argument. Thus, developers could use it as a tag to know which column or what kind of order to sort. Notice that the comparator is capable to sort under the order specified in the ascending parameter. In other words, you could ignore the ascending parameter (which is used only for providing additional information)

      Specified by:
        `sort` in interface `GroupsSortableModel<D>`
      Parameters:
        `cmpr` - the comparator assigned to `Listheader.setSortAscending(java.util.Comparator)` and other relative methods. If developers didn't assign any one, the default comparator is used. Notice that it is capable to sort the data in the correct order, you could ignore the ascending parameter.
        `ascending` - whether to sort in the ascending order (or in the descending order, if false). Notice that it is used only to provide additional information. To sort the data correctly, you could count on the cmpr parameter only.
        `col` - the index of the column

    - #### group

          public void group​(java.util.Comparator<D> cmpr,
                            boolean ascending,
                            int col)

      Description copied from interface: `GroupsSortableModel`
      Groups and sorts the data by the specified column. It only called when `Listbox` or `Grid` has the sort function.
      Specified by:
        `group` in interface `GroupsSortableModel<D>`
      Parameters:
        `cmpr` - the comparator assigned to `Column.setSortAscending(java.util.Comparator<?>)` and other relative methods. If developers didn't assign any one, the method is returned directly.
        `ascending` - whether to sort in the ascending order (or in the descending order)
        `col` - the index of the column

    - #### addOpenGroup

          public boolean addOpenGroup​(int groupIndex)

      Description copied from interface: `GroupsModel`
      Opens the group at the specified index.
      Specified by:
        `addOpenGroup` in interface `GroupsModel<D,​H,​F>`
      Parameters:
        `groupIndex` - the index of the group.
      Returns:
        if it has been added successfully; false if it was opened.

    - #### removeOpenGroup

          public boolean removeOpenGroup​(int groupIndex)

      Description copied from interface: `GroupsModel`
      Closes the group at the specified index.
      Specified by:
        `removeOpenGroup` in interface `GroupsModel<D,​H,​F>`
      Parameters:
        `groupIndex` - the index of the group.
      Returns:
        if it has been removed successfully; false if it was closed.

    - #### isGroupOpened

          public boolean isGroupOpened​(int groupIndex)

      Description copied from interface: `GroupsModel`
      Whether the group is open at the specified index. It is used to render `Group` and `Listgroup`.

      Default: true

      Specified by:
        `isGroupOpened` in interface `GroupsModel<D,​H,​F>`
      Parameters:
        `groupIndex` - the index of the group.

    - #### sortGroupData

          protected void sortGroupData​(H group,
                                       D[] groupdata,
                                       java.util.Comparator<D> cmpr,
                                       boolean ascending,
                                       int col)

      Sorts data within a group. Notice that this method doesn't fire event.

      There are three steps to re-group data: `sortDataInGroupOrder(java.util.Comparator<D>, boolean, int)`, `organizeGroup(java.util.Comparator<D>, int)` and then `sortGroupData(H, D[], java.util.Comparator<D>, boolean, int)`.

      It is the last step of grouping. It sorts data in the specified group.

    - #### organizeGroup

          protected void organizeGroup​(java.util.Comparator<D> cmpr,
                                       int col)

      Organizes groups based sorted data.

      There are three steps to re-group data: `sortDataInGroupOrder(java.util.Comparator<D>, boolean, int)`, `organizeGroup(java.util.Comparator<D>, int)` and then `sortGroupData(H, D[], java.util.Comparator<D>, boolean, int)`.

      It is the second step of grouping. It creates group data based on the data sorted in the group order by `sortDataInGroupOrder(java.util.Comparator<D>, boolean, int)`.

      Parameters:
        `cmpr` - the comparator used to compare data in the group order. Notice that the comparator is never an instance of `GroupComparator`. The implementation just uses `Comparator.compare(T, T)` to sort the data.
        `col` - column index

    - #### createGroupHead

          protected H createGroupHead​(D[] groupdata,
                                      int index,
                                      int col)

      create group head Object, default implementation return first element of groupdata. you can override this method to return your Object.
      Parameters:
        `groupdata` - data the already in a group.
        `index` - group index
        `col` - column to group

    - #### createGroupFoot

          protected F createGroupFoot​(D[] groupdata,
                                      int index,
                                      int col)

      create group foot Object, default implementation return null, which means no foot . you can override this method to return your Object.
      Parameters:
        `groupdata` - data the already in a group.
        `index` - group index
        `col` - column to group

    - #### sortDataInGroupOrder

          protected void sortDataInGroupOrder​(java.util.Comparator<D> cmpr,
                                              boolean ascending,
                                              int colIndex)

      Sorts the native data in the group order. After sorted, all data in the first group shall be placed in front of the second group, and so on.

      There are three steps to re-group data: `sortDataInGroupOrder(java.util.Comparator<D>, boolean, int)`, `organizeGroup(java.util.Comparator<D>, int)` and then `sortGroupData(H, D[], java.util.Comparator<D>, boolean, int)`.

      Parameters:
        `cmpr` - the comparator used to compare data in the group order. Notice that the comparator is never an instance of `GroupComparator`. The implementation just uses `Comparator.compare(T, T)` to sort the data.

    - #### createGroupOpen

          protected boolean createGroupOpen​(D[] groupdata,
                                            int index,
                                            int col)

      create group open status, default implementation return true, which means open the group. you can override this method to return your group open status.
      Parameters:
        `groupdata` - data the already in a group.
        `index` - group index
        `col` - column to group
      Since:
        6.0.0

    - #### clone

          public java.lang.Object clone()

      Overrides:
        `clone` in class `AbstractGroupsModel<D,​H,​F,​E>`

    - #### willClone

          public java.lang.Object willClone​(Component comp)

      Allows the model to clone
      Specified by:
        `willClone` in interface `ComponentCloneListener`
      Parameters:
        `comp` - the cloned component (not the original one)
      Returns:
        the object to be used in the cloned component. If this object is returned, the same object is shared by the cloned and original components. If other object is returned, it is used by the cloned component. If null is returned, it is not used by the cloned component at all.
      Since:
        6.0.0

    - #### equals

          public boolean equals​(java.lang.Object o)

      Overrides:
        `equals` in class `java.lang.Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### getSortDirection

          public java.lang.String getSortDirection​(java.util.Comparator<D> cmpr)

      Description copied from interface: `Sortable`
      Returns the sort direction of this model for the given comparator. It must be one of "ascending", "descending" and "natural".

      Default: "natural".

      Specified by:
        `getSortDirection` in interface `GroupsSortableModel<D>`
      Specified by:
        `getSortDirection` in interface `Sortable<D>`