Package org.zkoss.zul

## Class Column

- java.lang.Object
- - org.zkoss.zk.ui.AbstractComponent
  - - org.zkoss.zk.ui.HtmlBasedComponent
    - - org.zkoss.zul.impl.XulElement
      - - org.zkoss.zul.impl.LabelElement
        - - org.zkoss.zul.impl.LabelImageElement
          - - org.zkoss.zul.impl.HeaderElement
            - - org.zkoss.zul.Column

- All Implemented Interfaces:
    `java.io.Serializable`, `java.lang.Cloneable`, `Component`, `Scope`, `ComponentCtrl`

      public class Column
      extends HeaderElement

  A single column in a `Columns` element. Each child of the `Column` element is placed in each successive cell of the grid. The column with the most child elements determines the number of rows in each column.

  The use of column is mainly to define attributes for each cell in the grid.

  Default `getZclass()`: z-column. (since 3.5.0)

  Author:
    tomyeh
  See Also:
    Serialized Form

- - ### Nested Class Summary

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

      `LabelImageElement.ExtraCtrl`

    - ### Nested classes/interfaces inherited from class org.zkoss.zk.ui.AbstractComponent

      `AbstractComponent.Children, AbstractComponent.ForwardInfo, AbstractComponent.TargetInfo`

  - ### Field Summary

    - ### Fields inherited from class org.zkoss.zk.ui.HtmlBasedComponent

      `_zclass`

    - ### Fields inherited from interface org.zkoss.zk.ui.Component

      `APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE`

    - ### Fields inherited from interface org.zkoss.zk.ui.sys.ComponentCtrl

      `AFTER_CHILD_ADDED, AFTER_CHILD_REMOVED, AFTER_CLONED, AFTER_PAGE_ATTACHED, AFTER_PAGE_DETACHED, AFTER_PARENT_CHANGED, CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Column()` |
    `Column​(java.lang.String label)` |
    `Column​(java.lang.String label, java.lang.String src)` |
    `Column​(java.lang.String label, java.lang.String src, java.lang.String width)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `beforeParentChanged​(Component parent)` | Default: If parent is null, execute the @Destroy method if any.
    `java.lang.Object` | `clone()` | Clones the component.
    `Grid` | `getGrid()` | Returns the grid that contains this column.
    `java.util.Comparator<?>` | `getSortAscending()` | Returns the ascending sorter, or null if not available.
    `java.util.Comparator<?>` | `getSortDescending()` | Returns the descending sorter, or null if not available.
    `java.lang.String` | `getSortDirection()` | Returns the sort direction.
    `<T> T` | `getValue()` | Returns the value.
    `java.lang.String` | `getZclass()` | Returns the ZK Cascading Style class for this component.
    `boolean` | `group​(boolean ascending)` | Groups and sorts the rows (`Row`) based on `getSortAscending()`.
    `void` | `onGroupLater​(SortEvent event)` | Internal use only.
    `void` | `onSort​(SortEvent event)` | Invokes a sorting action based on a `SortEvent` and maintains `getSortDirection()`.
    `protected void` | `renderProperties​(ContentRenderer renderer)` | Renders the content of this component, excluding the enclosing tags and children.
    `void` | `service​(AuRequest request, boolean everError)` | Processes an AU request.
    `void` | `setSort​(java.lang.String type)` | Sets the type of the sorter.
    `void` | `setSortAscending​(java.lang.String clsnm)` | Sets the ascending sorter with the class name, or null for no sorter for the ascending order.
    `void` | `setSortAscending​(java.util.Comparator<?> sorter)` | Sets the ascending sorter, or null for no sorter for the ascending order.
    `void` | `setSortDescending​(java.lang.String clsnm)` | Sets the descending sorter with the class name, or null for no sorter for the descending order.
    `void` | `setSortDescending​(java.util.Comparator<?> sorter)` | Sets the descending sorter, or null for no sorter for the descending order.
    `void` | `setSortDirection​(java.lang.String sortDir)` | Sets the sort direction.
    `<T> void` | `setValue​(T value)` | Sets the value.
    `boolean` | `sort​(boolean ascending)` | Sorts the rows (`Row`) based on `getSortAscending()` and `getSortDescending()`, if `getSortDirection()` doesn't matches the ascending argument.
    `boolean` | `sort​(boolean ascending, boolean force)` | Sorts the rows (`Row`) based on `getSortAscending()` and `getSortDescending()`.
    `void` | `ungroup​(boolean ascending)` | Ungroups and sorts the rows (`Row`) based on the ascending.

    - ### Methods inherited from class org.zkoss.zul.impl.HeaderElement

      `evalCSSFlex, getAlign, getValign, setAlign, setValign`

    - ### Methods inherited from class org.zkoss.zul.impl.LabelImageElement

      `getExtraCtrl, getHoverImage, getHoverImageContent, getIconSclass, getIconSclasses, getIconTooltip, getIconTooltips, getImage, getImageContent, getPropertyAccess, isImageAssigned, setHoverImage, setHoverImageContent, setHoverImageContent, setIconSclass, setIconSclasses, setIconTooltip, setIconTooltips, setImage, setImageContent, setImageContent`

    - ### Methods inherited from class org.zkoss.zul.impl.LabelElement

      `getLabel, renderCrawlable, setLabel`

    - ### Methods inherited from class org.zkoss.zul.impl.XulElement

      `getContext, getCtrlKeys, getPopup, getTooltip, setContext, setContext, setContextAttributes, setCtrlKeys, setPopup, setPopup, setPopupAttributes, setTooltip, setTooltip, setTooltipAttributes`

    - ### Methods inherited from class org.zkoss.zk.ui.HtmlBasedComponent

      `addSclass, focus, getAction, getClientAction, getDraggable, getDroppable, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getStyle, getTabindex, getTabindexInteger, getTooltiptext, getTop, getVflex, getWidth, getZindex, getZIndex, removeSclass, removeSclass, setAction, setClass, setClientAction, setDraggable, setDroppable, setFocus, setHeight, setHeight0, setHeightDirectly, setHflex, setHflex0, setHflexDirectly, setLeft, setLeftDirectly, setRenderdefer, setSclass, setStyle, setTabindex, setTabindex, setTooltiptext, setTop, setTopDirectly, setVflex, setVflex0, setVflexDirectly, setWidth, setWidth0, setWidthDirectly, setZclass, setZindex, setZIndex, setZIndexDirectly`

    - ### Methods inherited from class org.zkoss.zk.ui.AbstractComponent

      `addAnnotation, addCallback, addClientEvent, addEventHandler, addEventListener, addEventListener, addForward, addForward, addForward, addForward, addMoved, addRedrawCallback, addScopeListener, addShadowRoot, addShadowRootBefore, addSharedEventHandlerMap, appendChild, applyProperties, beforeChildAdded, beforeChildRemoved, destroyIndexCacheMap, detach, didActivate, didActivate, didDeserialize, didDeserialize, disableBindingAnnotation, disableClientUpdate, disableHostChanged, enableBindingAnnotation, enableHostChanged, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getAutag, getCallback, getChildren, getClientAttribute, getClientDataAttribute, getClientEvents, getDefaultMold, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getEventListenerMap, getEventListeners, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getForwards, getId, getIndexCacheMap, getLastChild, getMold, getNextSibling, getPage, getParent, getPreviousSibling, getRedrawCallback, getRoot, getShadowFellowIfAny, getShadowRoots, getShadowVariable, getShadowVariable, getShadowVariable0, getSpaceOwner, getSpecialRendererOutput, getStubonly, getSubBindingAnnotationCount, getTemplate, getTemplateNames, getUuid, getWidgetAttributeNames, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasBindingAnnotation, hasFellow, hasFellow, hasSubBindingAnnotation, initIndexCacheMap, insertBefore, invalidate, isChildable, isDisabledHostChanged, isInitialized, isInvalidated, isListenerAvailable, isVisible, onChildAdded, onChildRemoved, onPageAttached, onPageDetached, onParentChanged, onWrongValue, query, queryAll, redraw, redrawChildren, removeAttribute, removeAttribute, removeAttribute, removeCallback, removeChild, removeEventListener, removeForward, removeForward, removeRedrawCallback, removeScopeListener, removeShadowRoot, render, render, render, renderPropertiesOnly, replace, response, response, response, service, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setAttribute, setAuService, setAutag, setClientAttribute, setClientDataAttribute, setDefinition, setDefinition, setId, setMold, setPage, setPageBefore, setParent, setStubonly, setStubonly, setSubBindingAnnotationCount, setTemplate, setVisible, setVisibleDirectly, setWidgetClass, setWidgetListener, setWidgetOverride, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdateWidgetListener, smartUpdateWidgetOverride, toString, updateByClient, updateSubBindingAnnotationCount, willPassivate, willPassivate, willSerialize, willSerialize`

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

      `equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Column

          public Column()

    - #### Column

          public Column​(java.lang.String label)

    - #### Column

          public Column​(java.lang.String label,
                        java.lang.String src)

    - #### Column

          public Column​(java.lang.String label,
                        java.lang.String src,
                        java.lang.String width)

  - ### Method Detail

    - #### getGrid

          public Grid getGrid()

      Returns the grid that contains this column.

    - #### getSortDirection

          public java.lang.String getSortDirection()

      Returns the sort direction.

      Default: "natural".

    - #### setSortDirection

          public void setSortDirection​(java.lang.String sortDir)
                                throws WrongValueException

      Sets the sort direction. This does not sort the data, it only serves as an indicator as to how the grid is sorted. (unless the grid has "autosort" attribute)

      If you use `sort(boolean)` to sort rows (`Row`), the sort direction is maintained automatically. If you want to sort it in customized way, you have to set the sort direction manually.

      Parameters:
        `sortDir` - one of "ascending", "descending" and "natural"
      Throws:
        `WrongValueException`

    - #### setSort

          public void setSort​(java.lang.String type)
                       throws java.lang.ClassNotFoundException,
                              java.lang.InstantiationException,
                              java.lang.IllegalAccessException

      Sets the type of the sorter. You might specify either "auto", "auto(FIELD_NAME1[,FIELD_NAME2] ...)"(since 3.5.3), "auto(number)" (since 5.0.6) or "none".

      If "client" or "client(number)" is specified, the sort functionality will be done by Javascript at client without notifying to server, that is, the order of the component in the row is out of sync.

      - "client" : it is treated by a string
      - "client(number)" : it is treated by a number

      Note: client sorting cannot work in model case. (since 5.0.0)

      If "auto" is specified, `setSortAscending(java.util.Comparator<?>)` and/or `setSortDescending(java.util.Comparator<?>)` are called with `RowComparator`, if `getSortDescending()` and/or `getSortAscending()` are null. If you assigned a comparator to them, it won't be affected. The auto created comparator is case-insensitive.

      If "auto(FIELD_NAME1, FIELD_NAME2, ...)" is specified, `setSortAscending(java.util.Comparator<?>)` and/or `setSortDescending(java.util.Comparator<?>)` are called with `FieldComparator`, if `getSortDescending()` and/or `getSortAscending()` are null. If you assigned a comparator to them, it won't be affected. The auto created comparator is case-sensitive.

      If "auto(LOWER(FIELD_NAME))" or "auto(UPPER(FIELD_NAME))" is specified, `setSortAscending(java.util.Comparator<?>)` and/or `setSortDescending(java.util.Comparator<?>)` are called with `FieldComparator`, if `getSortDescending()` and/or `getSortAscending()` are null. If you assigned a comparator to them, it won't be affected. The auto created comparator is case-insensitive.

      If "auto(number)" is specified, `setSortAscending(java.util.Comparator<?>)` and/or `setSortDescending(java.util.Comparator<?>)` are called with `ArrayComparator`. Notice that the data must be an array and the number-th element must be comparable (`Comparable`).

      If "none" is specified, both `setSortAscending(java.util.Comparator<?>)` and `setSortDescending(java.util.Comparator<?>)` are called with null. Therefore, no more sorting is available to users for this column.

      Throws:
        `java.lang.IllegalAccessException`
        `java.lang.InstantiationException`
        `java.lang.ClassNotFoundException`
      Since:
        3.5.3

    - #### getSortAscending

          public java.util.Comparator<?> getSortAscending()

      Returns the ascending sorter, or null if not available.

    - #### setSortAscending

          public void setSortAscending​(java.util.Comparator<?> sorter)

      Sets the ascending sorter, or null for no sorter for the ascending order.
      Parameters:
        `sorter` - the comparator used to sort the ascending order. If you are using the group feature, you can pass an instance of `GroupComparator` to have a better control. If an instance of `GroupComparator` is passed, `GroupComparator.compareGroup(D, D)` is used to group elements, and `Comparator.compare(T, T)` is used to sort elements with a group. Otherwise, `Comparator.compare(T, T)` is used to group elements and sort elements within a group.

    - #### setSortAscending

          public void setSortAscending​(java.lang.String clsnm)
                                throws java.lang.ClassNotFoundException,
                                       java.lang.InstantiationException,
                                       java.lang.IllegalAccessException

      Sets the ascending sorter with the class name, or null for no sorter for the ascending order.
      Throws:
        `java.lang.ClassNotFoundException`
        `java.lang.InstantiationException`
        `java.lang.IllegalAccessException`

    - #### getSortDescending

          public java.util.Comparator<?> getSortDescending()

      Returns the descending sorter, or null if not available.

    - #### setSortDescending

          public void setSortDescending​(java.util.Comparator<?> sorter)

      Sets the descending sorter, or null for no sorter for the descending order.
      Parameters:
        `sorter` - the comparator used to sort the descending order. If you are using the group feature, you can pass an instance of `GroupComparator` to have a better control. If an instance of `GroupComparator` is passed, `GroupComparator.compareGroup(D, D)` is used to group elements, and `Comparator.compare(T, T)` is used to sort elements with a group. Otherwise, `Comparator.compare(T, T)` is used to group elements and sort elements within a group.

    - #### setSortDescending

          public void setSortDescending​(java.lang.String clsnm)
                                 throws java.lang.ClassNotFoundException,
                                        java.lang.InstantiationException,
                                        java.lang.IllegalAccessException

      Sets the descending sorter with the class name, or null for no sorter for the descending order.
      Throws:
        `java.lang.ClassNotFoundException`
        `java.lang.InstantiationException`
        `java.lang.IllegalAccessException`

    - #### sort

          public boolean sort​(boolean ascending)

      Sorts the rows (`Row`) based on `getSortAscending()` and `getSortDescending()`, if `getSortDirection()` doesn't matches the ascending argument.

      It checks `getSortDirection()` to see whether sorting is required, and update `setSortDirection(java.lang.String)` after sorted. For example, if `getSortDirection()` returns "ascending" and the ascending argument is false, nothing happens. To enforce the sorting, you can invoke `setSortDirection(java.lang.String)` with "natural" before invoking this method. Alternatively, you can invoke `sort(boolean, boolean)` instead.

      It sorts the rows by use of `Components.sort(java.util.List<? extends org.zkoss.zk.ui.Component>, java.util.Comparator<? super org.zkoss.zk.ui.Component>)`, if not live data (i.e., `Grid.getModel()` is null).

      On the other hand, it invokes `Sortable.sort(java.util.Comparator<T>, boolean)` to sort the rows, if live data (i.e., `Grid.getModel()` is not null). In other words, if you use the live data, you have to implement `Sortable` to sort the live data explicitly.

      Parameters:
        `ascending` - whether to use `getSortAscending()`. If the corresponding comparator is not set, it returns false and does nothing.
      Returns:
        whether the rows are sorted.
      Throws:
        `UiException` - if `Grid.getModel()` is not null but `Sortable` is not implemented.

    - #### sort

          public boolean sort​(boolean ascending,
                              boolean force)

      Sorts the rows (`Row`) based on `getSortAscending()` and `getSortDescending()`.
      Parameters:
        `ascending` - whether to use `getSortAscending()`. If the corresponding comparator is not set, it returns false and does nothing.
        `force` - whether to enforce the sorting no matter what the sort direction (`getSortDirection()`) is. If false, this method is the same as `sort(boolean)`.
      Returns:
        whether the rows are sorted.

    - #### group

          public boolean group​(boolean ascending)

      Groups and sorts the rows (`Row`) based on `getSortAscending()`. If the corresponding comparator is not set, it returns false and does nothing.
      Parameters:
        `ascending` - whether to use `getSortAscending()`. If the corresponding comparator is not set, it returns false and does nothing.
      Returns:
        whether the rows are grouped.
      Since:
        3.5.0

    - #### renderProperties

          protected void renderProperties​(ContentRenderer renderer)
                                   throws java.io.IOException

      Description copied from class: `HtmlBasedComponent`
      Renders the content of this component, excluding the enclosing tags and children.

      See also ZK Client-side Reference: Property Rendering

      Overrides:
        `renderProperties` in class `HeaderElement`
      Throws:
        `java.io.IOException`

    - #### getValue

          public <T> T getValue()

      Returns the value.

      Default: null.

      Note: the value is application dependent, you can place whatever value you want.

      Since:
        3.6.0

    - #### setValue

          public <T> void setValue​(T value)

      Sets the value.
      Parameters:
        `value` - the value.

        Note: the value is application dependent, you can place whatever value you want.

      Since:
        3.6.0

    - #### onSort

          public void onSort​(SortEvent event)

      Invokes a sorting action based on a `SortEvent` and maintains `getSortDirection()`.
      Since:
        5.0.8

    - #### onGroupLater

          public void onGroupLater​(SortEvent event)

      Internal use only.
      Since:
        6.5.0

    - #### ungroup

          public void ungroup​(boolean ascending)

      Ungroups and sorts the rows (`Row`) based on the ascending. If the corresponding comparator is not set, it returns false and does nothing.
      Parameters:
        `ascending` - whether to use `getSortAscending()`. If the corresponding comparator is not set, it returns false and does nothing.
      Since:
        6.5.0

    - #### getZclass

          public java.lang.String getZclass()

      Description copied from class: `HtmlBasedComponent`
      Returns the ZK Cascading Style class for this component. It usually depends on the implementation of the mold (`AbstractComponent.getMold()`).

      Default: null (the default value depends on element).

      `HtmlBasedComponent.setZclass(java.lang.String)`) will completely replace the default style of a component. In other words, the default style of a component is associated with the default value of `HtmlBasedComponent.getZclass()`. Once it is changed, the default style won't be applied at all. If you want to perform small adjustments, use `HtmlBasedComponent.setSclass(java.lang.String)` instead.

      Overrides:
        `getZclass` in class `HtmlBasedComponent`
      See Also:
        `HtmlBasedComponent.getSclass()`

    - #### beforeParentChanged

          public void beforeParentChanged​(Component parent)

      Description copied from class: `AbstractComponent`
      Default: If parent is null, execute the @Destroy method if any.
      Specified by:
        `beforeParentChanged` in interface `ComponentCtrl`
      Overrides:
        `beforeParentChanged` in class `AbstractComponent`
      Parameters:
        `parent` - the new parent. If null, it means detachment.
      See Also:
        `ComponentCtrl.beforeParentChanged(org.zkoss.zk.ui.Component)`

    - #### service

          public void service​(AuRequest request,
                              boolean everError)

      Processes an AU request.

      Default: in addition to what are handled by its superclass, it also handles onSort.

      Specified by:
        `service` in interface `ComponentCtrl`
      Overrides:
        `service` in class `HtmlBasedComponent`
        `everError` - whether any error ever occurred before processing this request.
      Since:
        5.0.8
      See Also:
        `AbstractComponent.setAuService(org.zkoss.zk.au.AuService)`

    - #### clone

          public java.lang.Object clone()

      Description copied from interface: `Component`
      Clones the component. All of its children and descendants are cloned. Also, ID are preserved.
      Specified by:
        `clone` in interface `Component`
      Overrides:
        `clone` in class `LabelImageElement`
      Returns:
        the new component. Notice that it doesn't belong to any page, nor desktop. It doesn't have a parent, either.