.. _pages/widget/virtualwidgets#virtualselectbox:

Virtual SelectBox
*****************
The virtual SelectBox has the same act like the :doc:`selectbox`, but the virtual SelectBox is based on the virtual infrastructure from the framework.

.. _pages/widget/virtualselectbox#preview_image:

Preview Image
-------------

|widget/virtualselectbox.png|

.. |widget/virtualselectbox.png| image:: /pages/widget/virtualselectbox.png

.. _pages/widget/virtualselectbox#features:

Features
--------
* Mouse and keyboard support.
* Items with plane text and/or icons
* Ellipsis: If the label does not fit into the widget bounds an ellipsis (”...”) is rendered at the end of the label.
* Supports filtering, sorting, grouping, data binding and custom rendering like the :doc:`virtuallist`.

**Mouse and keyboard behavior:**

+------------------+----------+-----------------------------------+----------------------------------------+
|                  |          |                                   |                                        |
+==================+==========+===================================+========================================+
|                  | keyboard | **open drop-down**                | key down; key up; space; enter         |
+------------------+----------+-----------------------------------+----------------------------------------+
|                  |          | **close drop-down**               | esc; enter                             |
+------------------+----------+-----------------------------------+----------------------------------------+
|                  | mouse    | **open drop-down**                | click on widget                        |
+------------------+----------+-----------------------------------+----------------------------------------+
|                  |          | **close drop-down**               | click on item; click outside drop-down |
+------------------+----------+-----------------------------------+----------------------------------------+
| drop-down closed | keyboard | **select next**                   | not possible                           |
+------------------+----------+-----------------------------------+----------------------------------------+
|                  |          | **select previous**               | not possible                           |
+------------------+----------+-----------------------------------+----------------------------------------+
|                  |          | **select first**                  | not possible                           |
+------------------+----------+-----------------------------------+----------------------------------------+
|                  |          | **select last**                   | not possible                           |
+------------------+----------+-----------------------------------+----------------------------------------+
|                  | mouse    | **select next**                   | not possible                           |
+------------------+----------+-----------------------------------+----------------------------------------+
|                  |          | **select previous**               | not possible                           |
+------------------+----------+-----------------------------------+----------------------------------------+
| drop-down open   | keyboard | **select next**                   | key down then enter                    |
+------------------+----------+-----------------------------------+----------------------------------------+
|                  |          | **select previous**               | key up then enter                      |
+------------------+----------+-----------------------------------+----------------------------------------+
|                  |          | **select first**                  | page up then enter                     |
+------------------+----------+-----------------------------------+----------------------------------------+
|                  |          | **select last**                   | page down then enter                   |
+------------------+----------+-----------------------------------+----------------------------------------+
|                  | mouse    | **select next**                   | click on item                          |
+------------------+----------+-----------------------------------+----------------------------------------+
|                  |          | **select previous**               | click on item                          |
+------------------+----------+-----------------------------------+----------------------------------------+
|                  |          | **wrap in list**                  | no                                     |
+------------------+----------+-----------------------------------+----------------------------------------+
|                  |          | **preselect**                     | mouse over; key up; key down           |
+------------------+----------+-----------------------------------+----------------------------------------+
|                  |          | **select drop-down item on open** | yes                                    |
+------------------+----------+-----------------------------------+----------------------------------------+

.. _pages/widget/virtualselectbox#description:

Description
-----------

The ``qx.ui.form.VirtualSelectBox`` is based on the virtual infrastructure. It can be used for one selection and uses the :doc:`virtuallist` as drop-down.
 
Using the virtual infrastructure has considerable advantages when there is a huge amount of model items to render because the virtual infrastructure only creates widgets for visible items and reuses them. This saves both creation time and memory.

The virtual SelectBox uses the same `qx.ui.list.core.IListDelegate <http://demo.qooxdoo.org/%{version}/apiviewer/#qx.ui.list.core.IListDelegate>`_ interface like the :doc:`virtuallist` to configure the SelectBox's behavior (item and group renderer configuration, filtering, sorting, grouping, etc.).

.. note::
  At the moment we only support widget based rendering for list and group items, but we are planing also to support HTML based rendering in a future release.

.. _pages/widget/virtualselectbox#codeexample:

Code Example
------------

Here's an example. We create a simple SelectBox example with 2500 items, sorting the items ascending, selecting the 20th item and we log each selection change.

::

    //create the model data
    var rawData = [];
    for (var i = 0; i < 2500; i++) {
      rawData[i] = "Item No " + i;
    }
    var model = qx.data.marshal.Json.createModel(rawData);
     
    //create the SelectBox
    var selectBox = new qx.ui.form.VirtualSelectBox(model);
     
    //configure the SelectBox's behavior
    var delegate = {
      sorter : function(a, b) {
        return a > b ? 1 : a < b ? -1 : 0;
      }
    };
    selectBox.setDelegate(delegate);
     
    //Pre-Select "Item No 20"
    selectBox.getSelection().push(model.getItem(20));
    
    //log selection changes
    selectBox.getSelection().addListener("change", function(e) {
      this.debug("Selection: " + selectBox.getSelection().getItem(0));
    }, this);

.. _pages/widget/virtualselectbox#demos:

Demos
-----
Here are some links that demonstrate the usage of the widget:

* `SelectBox demo <http://demo.qooxdoo.org/%{version}/demobrowser/#virtual~SelectBox.html>`_

.. _pages/widget/virtualselectbox#api:

API
---
| Here is a link to the API of the widget:
| `qx.ui.form.VirtualSelectBox <http://demo.qooxdoo.org/%{version}/apiviewer/#qx.ui.form.VirtualSelectBox>`_

