Package org.zkoss.zkmax.zul

## Class Biglistbox

- java.lang.Object
- - org.zkoss.zk.ui.AbstractComponent
  - - org.zkoss.zk.ui.HtmlBasedComponent
    - - org.zkoss.zul.impl.XulElement
      - - org.zkoss.zkmax.zul.Biglistbox

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

      public class Biglistbox
      extends XulElement

  A component to handle a huge data sets and provides the same and as many as the functionalities of `Listbox` including selection, sorting, keystroke navigation, ROD(rendering-on-demand), and so on.

  Event:

  1. `SelectEvent` is sent when user changes the selection.
  2. `ScrollEventExt` for onScroll is sent when user changes the scroll position either x or y.
  3. `ScrollEventExt` for onScrollY is sent when user changes the scroll position y.
  4. `ScrollEventExt` for onScrollX is sent when user changes the scroll position x.
  5. `SortEventExt` is sent when user sort the column.
  6. `CellClickEvent` is sent when user click upon the cell field.
  7. onAfterRender is sent when the model's data has been rendered.

  ### Custom Attributes

  org.zkoss.zkmax.zul.biglistbox.preloadSize
  .
    Specifies the number of items to preload when receiving the rendering request from the client.

    Default `getZclass()`: z-biglistbox.

    Note: This component can only support those browsers which support HTML5/CSS3 selector. Like IE8+, Firefox, Safari, Opera, and Chrome.

  Since:
    6.0.1
  Author:
    jumperchen
  See Also:
    Serialized Form

- - ### Nested Class Summary

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

      `HtmlBasedComponent.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
    --- | ---
    `Biglistbox()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `int` | `getCols()` | Returns the number of columns within the viewport.
    `java.lang.String` | `getColWidth()` | Returns the width of the single column
    `int` | `getFrozenCols()` | Returns the size of the frozen columns.
    `<T> MatrixRenderer<T>` | `getMatrixRenderer()` | Returns the matrix renderer.
    `MatrixModel<?,​?,​?,​?>` | `getModel()` | Returns the matrix model.
    `java.lang.String` | `getOddRowSclass()` | Returns the style class for the odd rows.
    `int` | `getPreloadSize()` | Returns the number of items to preload when receiving the rendering request from the client.
    `<T> MatrixRenderer<T>` | `getRealMatrixRenderer()` | Return the real matrix renderer, if `getMatrixRenderer()` is null, the default implementation is assumed.
    `java.lang.String` | `getRowHeight()` | Returns the height of the single row.
    `int` | `getRows()` | Returns the rows' size of the viewport.
    `int` | `getSelectedIndex()` | Returns the index of the selected item (-1 if no one is selected).
    `java.lang.Object` | `getSelectedObject()` | Returns the selected object.
    `Sortable` | `getSortableModel()` | Returns the sortable model, if any.
    `MatrixComparatorProvider<?>` | `getSortAscending()` | Returns the ascending sorter provider, or null if not available.
    `MatrixComparatorProvider<?>` | `getSortDescending()` | Returns the descending sorter provider, or null if not available.
    `java.lang.String` | `getZclass()` | The default zclass is "z-biglistbox"
    `void` | `invalidate()` | Invalidates this component by setting the dirty flag such that it will be redraw the whole content of this component and its dependencies later.
    `boolean` | `isAutoCols()` | Returns whether enables the auto adjusting cols size.
    `boolean` | `isAutoRows()` | Returns whether enables the auto adjusting rows size.
    `protected boolean` | `isChildable()` | Returns whether this component can have a child.
    `boolean` | `isFixFrozenCols()` | Returns whether is fix frozen columns, that means user cannot change the size of the frozen columns dynamically.
    `void` | `onInitRender()` | Handles a private event, onInitRender.
    `void` | `onPageAttached​(Page newpage, Page oldpage)` | Default: handles special event listeners.
    `void` | `onPageDetached​(Page page)` | Default: handles special event listeners.
    `void` | `onSort​(SortEventExt event)` |
    `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` | `sessionDidActivate​(Page page)` | Notification that the session, which owns this component, has just been activated (a.k.a., deserialized).
    `void` | `sessionWillPassivate​(Page page)` | Notification that the session, which owns this component, is about to be passivated (a.k.a., serialized).
    `void` | `setAutoCols​(boolean autoCols)` | Sets whether enables auto adjusting the number of cols.
    `void` | `setAutoRows​(boolean autoRows)` | Sets whether enables auto adjusting the number of rows.
    `void` | `setCols​(int cols)` | Sets the number of columns within the viewport.
    `void` | `setColWidth​(java.lang.String colWidth)` | Sets the width of the single column.
    `void` | `setFixFrozenCols​(boolean fixFrozenCols)` | Sets to fix the frozen columns, if true, meaning the user cannot change the size of the frozen columns dynamically.
    `void` | `setFrozenCols​(int fcols)` | Sets the size of the frozen columns.
    `void` | `setMatrixRenderer​(java.lang.String clsnm)` | Sets the matrix renderer from a class string.
    `void` | `setMatrixRenderer​(MatrixRenderer<?> renderer)` | Sets the matrix renderer.
    `void` | `setModel​(MatrixModel<?,​?,​?,​?> model)` | Sets the matrix model.
    `void` | `setOddRowSclass​(java.lang.String scls)` | Sets the style class for the odd rows.
    `void` | `setRowHeight​(java.lang.String rowHeight)` | Sets the height of the single row.
    `void` | `setRows​(int rows)` | Sets the rows' size of the viewport.
    `void` | `setSortAscending​(java.lang.String clsnm)` | Sets the ascending sorter provider with the class name, or null for no sorter for the ascending order.
    `void` | `setSortAscending​(MatrixComparatorProvider<?> sorter)` | Sets the ascending sorter provider, or null for no sorter for the ascending order.
    `void` | `setSortDescending​(java.lang.String clsnm)` | Sets the descending sorter provider with the class name, or null for no sorter for the descending order.
    `void` | `setSortDescending​(MatrixComparatorProvider<?> sorter)` | Sets the descending sorter provider, or null for no sorter for the descending order.
    `boolean` | `sort​(boolean ascending, int columnIndex)` |

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

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

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

      `addSclass, evalCSSFlex, focus, getAction, getClientAction, getDraggable, getDroppable, getExtraCtrl, 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, beforeParentChanged, 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, isDisabledHostChanged, isInitialized, isInvalidated, isListenerAvailable, isVisible, onChildAdded, onChildRemoved, 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, 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

    - #### Biglistbox

          public Biglistbox()

  - ### Method Detail

    - #### setAutoCols

          public void setAutoCols​(boolean autoCols)

      Sets whether enables auto adjusting the number of cols.

      Default: true.

    - #### isAutoCols

          public boolean isAutoCols()

      Returns whether enables the auto adjusting cols size.

      Default: true.

    - #### setAutoRows

          public void setAutoRows​(boolean autoRows)

      Sets whether enables auto adjusting the number of rows.

      Default: true.

    - #### isAutoRows

          public boolean isAutoRows()

      Returns whether enables the auto adjusting rows size.

      Default: true.

    - #### setFrozenCols

          public void setFrozenCols​(int fcols)

      Sets the size of the frozen columns.
      Parameters:
        `fcols` - the size of the frozen columns, it cannot be negative.

    - #### getFrozenCols

          public int getFrozenCols()

      Returns the size of the frozen columns.

      Default: 0

    - #### setFixFrozenCols

          public void setFixFrozenCols​(boolean fixFrozenCols)

      Sets to fix the frozen columns, if true, meaning the user cannot change the size of the frozen columns dynamically.

    - #### isFixFrozenCols

          public boolean isFixFrozenCols()

      Returns whether is fix frozen columns, that means user cannot change the size of the frozen columns dynamically.

      Default: false

    - #### getSortAscending

          public MatrixComparatorProvider<?> getSortAscending()

      Returns the ascending sorter provider, or null if not available.

    - #### setSortAscending

          public void setSortAscending​(MatrixComparatorProvider<?> sorter)

      Sets the ascending sorter provider, or null for no sorter for the ascending order.
      Parameters:
        `sorter` - the comparator provider used to return an sorter of the ascending order.

    - #### setSortAscending

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

      Sets the ascending sorter provider 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 MatrixComparatorProvider<?> getSortDescending()

      Returns the descending sorter provider, or null if not available.

    - #### setSortDescending

          public void setSortDescending​(MatrixComparatorProvider<?> sorter)

      Sets the descending sorter provider, or null for no sorter for the descending order.
      Parameters:
        `sorter` - he comparator provider used to return an sorter of the descending order.

    - #### setSortDescending

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

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

    - #### getOddRowSclass

          public java.lang.String getOddRowSclass()

      Returns the style class for the odd rows.

      Default: `getZclass()`-odd.

    - #### setOddRowSclass

          public void setOddRowSclass​(java.lang.String scls)

      Sets the style class for the odd rows. If the style class doesn't exist, the striping effect disappears. You can provide different effects by providing the proper style classes.

    - #### getPreloadSize

          public int getPreloadSize()

      Returns the number of items to preload when receiving the rendering request from the client.

      Default: 50

    - #### getRows

          public int getRows()

      Returns the rows' size of the viewport.

      Default: 30

    - #### setRows

          public void setRows​(int rows)

      Sets the rows' size of the viewport.

      Default: 30, and it will be adjusted by client engine according with the browser height.

    - #### getCols

          public int getCols()

      Returns the number of columns within the viewport.

      Default: 30

    - #### setCols

          public void setCols​(int cols)

      Sets the number of columns within the viewport.

      Default: 30, and it will be adjusted by client engine according with the browser width.

    - #### getRowHeight

          public java.lang.String getRowHeight()

      Returns the height of the single row.

      Default: 30px

    - #### setRowHeight

          public void setRowHeight​(java.lang.String rowHeight)

      Sets the height of the single row.

      Default: 32px

    - #### getColWidth

          public java.lang.String getColWidth()

      Returns the width of the single column

      Default: 60px

    - #### setColWidth

          public void setColWidth​(java.lang.String colWidth)

      Sets the width of the single column.

      Default: 60px

    - #### getModel

          public MatrixModel<?,​?,​?,​?> getModel()

      Returns the matrix model.

    - #### setModel

          public void setModel​(MatrixModel<?,​?,​?,​?> model)

      Sets the matrix model.

      Note: the matrix model must implement `Selectable` interface

    - #### onInitRender

          public void onInitRender()

      Handles a private event, onInitRender. It is used only for implementation, and you rarely need to invoke it explicitly.

    - #### getRealMatrixRenderer

          public <T> MatrixRenderer<T> getRealMatrixRenderer()

      Return the real matrix renderer, if `getMatrixRenderer()` is null, the default implementation is assumed.

    - #### getMatrixRenderer

          public <T> MatrixRenderer<T> getMatrixRenderer()

      Returns the matrix renderer.

    - #### setMatrixRenderer

          public void setMatrixRenderer​(MatrixRenderer<?> renderer)

      Sets the matrix renderer.

    - #### setMatrixRenderer

          public void setMatrixRenderer​(java.lang.String clsnm)
                                 throws java.lang.ClassNotFoundException,
                                        java.lang.NoSuchMethodException,
                                        java.lang.IllegalAccessException,
                                        java.lang.InstantiationException,
                                        java.lang.reflect.InvocationTargetException

      Sets the matrix renderer from a class string.
      Parameters:
        `clsnm` - the full package name
      Throws:
        `java.lang.ClassNotFoundException`
        `java.lang.NoSuchMethodException`
        `java.lang.IllegalAccessException`
        `java.lang.InstantiationException`
        `java.lang.reflect.InvocationTargetException`

    - #### invalidate

          public void invalidate()

      Description copied from interface: `Component`
      Invalidates this component by setting the dirty flag such that it will be redraw the whole content of this component and its dependencies later. And, the widget associated with this component and all its descendant at the client will be deleted and recreated, too.

      If the application is totally controlled by the server side (i.e., you don't write client codes), you rarely need to access this method.

      It can be called only in the request-processing and event-processing phases. However, it is NOT allowed in the rendering phase.

      Specified by:
        `invalidate` in interface `Component`
      Overrides:
        `invalidate` in class `AbstractComponent`

    - #### isChildable

          protected boolean isChildable()

      Description copied from class: `AbstractComponent`
      Returns whether this component can have a child.

      Default: return true (means it can have children).

      Overrides:
        `isChildable` in class `AbstractComponent`

    - #### getSelectedIndex

          public int getSelectedIndex()

      Returns the index of the selected item (-1 if no one is selected).

    - #### getSelectedObject

          public java.lang.Object getSelectedObject()

      Returns the selected object.

    - #### 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 `XulElement`
      Throws:
        `java.io.IOException`

    - #### getZclass

          public java.lang.String getZclass()

      The default zclass is "z-biglistbox"
      Overrides:
        `getZclass` in class `HtmlBasedComponent`
      See Also:
        `HtmlBasedComponent.getSclass()`

    - #### service

          public void service​(AuRequest request,
                              boolean everError)

      Description copied from class: `HtmlBasedComponent`
      Processes an AU request.

      Default: it handles onClick, onDoubleClick, onRightClick onMove, onSize, onZIndex.

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

    - #### onSort

          public void onSort​(SortEventExt event)

    - #### getSortableModel

          public Sortable getSortableModel()

      Returns the sortable model, if any.

    - #### sort

          public boolean sort​(boolean ascending,
                              int columnIndex)

    - #### sessionWillPassivate

          public void sessionWillPassivate​(Page page)

      Description copied from interface: `ComponentCtrl`
      Notification that the session, which owns this component, is about to be passivated (a.k.a., serialized).

      Note: only root components are notified by this method.

      Specified by:
        `sessionWillPassivate` in interface `ComponentCtrl`
      Overrides:
        `sessionWillPassivate` in class `AbstractComponent`

    - #### sessionDidActivate

          public void sessionDidActivate​(Page page)

      Description copied from interface: `ComponentCtrl`
      Notification that the session, which owns this component, has just been activated (a.k.a., deserialized).

      Note: only root components are notified by this method.

      Specified by:
        `sessionDidActivate` in interface `ComponentCtrl`
      Overrides:
        `sessionDidActivate` in class `AbstractComponent`

    - #### onPageAttached

          public void onPageAttached​(Page newpage,
                                     Page oldpage)

      Description copied from class: `AbstractComponent`
      Default: handles special event listeners.
      Specified by:
        `onPageAttached` in interface `ComponentCtrl`
      Overrides:
        `onPageAttached` in class `AbstractComponent`
      Parameters:
        `newpage` - the new page (never null).
        `oldpage` - the previous page, if any, or null if it didn't belong to any page.
      See Also:
        `ComponentCtrl.onPageAttached(org.zkoss.zk.ui.Page, org.zkoss.zk.ui.Page)`

    - #### onPageDetached

          public void onPageDetached​(Page page)

      Description copied from class: `AbstractComponent`
      Default: handles special event listeners.
      Specified by:
        `onPageDetached` in interface `ComponentCtrl`
      Overrides:
        `onPageDetached` in class `AbstractComponent`
      Parameters:
        `page` - the previous page (never null)
      See Also:
        `ComponentCtrl.onPageDetached(org.zkoss.zk.ui.Page)`