**********
wx.ListBox
**********

Inheritance diagram for `wx.ListBox`:

|

.. inheritance-diagram:: wx.ListBox

|

Description
===========

A listbox is used to select one or more of a list of strings. The strings are displayed in a scrolling box, with the selected string(s) marked in reverse video. 

A listbox can be single selection (if an item is selected, the previous selection is removed) or multiple selection (clicking an item toggles the item on or 
off independently of other selections).

List box elements are numbered from zero. Their number may be limited under some platforms.

A listbox callback gets an event ``wx.wxEVT_COMMAND_LISTBOX_SELECTED`` for single clicks, and ``wx.wxEVT_COMMAND_LISTBOX_DOUBLECLICKED`` for double clicks.


.. seealso:: `wx.Choice <wx.Choice.html>`_, `wx.ComboBox <wx.ComboBox.html>`_, `wx.ListCtrl <wx.ListCtrl.html>`_, `wx.CommandEvent <../Events/wx.CommandEvent.html>`_


Derived From
^^^^^^^^^^^^^

* `wx.ControlWithItems <wx.ControlWithItems.html>`_ 
* `wx.Control <wx.Control.html>`_ 
* `wx.Window <wx.Window.html>`_ 
* `wx.EvtHandler <wx.EvtHandler.html>`_ 
* `wx.Object <wx.Object.html>`_ 


Known Subclasses
^^^^^^^^^^^^^^^^

`wx.CheckListBox <wx.CheckListBox.html>`_

Window Styles
^^^^^^^^^^^^^

==================================================  ==================================================  
Window Style                                        Description
==================================================  ==================================================  
``wx.LB_SINGLE``                                    Single-selection list.
``wx.LB_MULTIPLE``                                  Multiple-selection list: the user can toggle multiple items on and off.
``wx.LB_EXTENDED``                                  Extended-selection list: the user can select multiple items using the ``SHIFT`` key and the mouse or special key combinations.
``wx.LB_HSCROLL``                                   Create horizontal scrollbar if contents are too wide (Windows only).
``wx.LB_ALWAYS_SB``                                 Always show a vertical scrollbar.
``wx.LB_NEEDED_SB``                                 Only create a vertical scrollbar if needed.
``wx.LB_SORT``                                      The listbox contents are sorted in alphabetical order.
==================================================  ==================================================  


Event Handling
^^^^^^^^^^^^^^

==================================================  ==================================================  
Event Name                                          Description
==================================================  ==================================================  
wx.EVT_LISTBOX(id, func)                            Process a ``wx.wxEVT_COMMAND_LISTBOX_SELECTED`` event, when an item on the list is selected or the selection changes.
wx.EVT_LISTBOX_DCLICK(id, func)                     Process a ``wx.wxEVT_COMMAND_LISTBOX_DOUBLECLICKED`` event, when the listbox is double-clicked.
==================================================  ==================================================  

|

Control Appearance
^^^^^^^^^^^^^^^^^^

|

.. figure:: ../images/wxWidgets/wxmsw/listbox.png 
   :alt: wxMSW
   :figclass: floatleft
   
   **wxMSW**


.. figure:: ../images/wxWidgets/wxmac/listbox.png 
   :alt: wxMAC
   :figclass: floatright

   **wxMAC**


.. figure:: ../images/wxWidgets/wxgtk/listbox.png
   :alt: wxGTK
   :figclass: floatcenter

   **wxGTK**


|

Methods Summary
^^^^^^^^^^^^^^^

* `__init__ <#__init__>`_ 
* `AppendAndEnsureVisible <#AppendAndEnsureVisible>`_ 
* `Deselect <#Deselect>`_ 
* `DeselectAll <#DeselectAll>`_ 
* `EnsureVisible <#EnsureVisible>`_ 
* `GetSelections <#GetSelections>`_ 
* `InsertItems <#InsertItems>`_ 
* `IsSelected <#IsSelected>`_ 
* `IsSorted <#IsSorted>`_ 
* `Set <#Set>`_ 
* `SetFirstItem <#SetFirstItem>`_ 
* `SetFirstItemStr <#SetFirstItemStr>`_ 
* `SetItemBackgroundColour <#SetItemBackgroundColour>`_ 
* `SetItemFont <#SetItemFont>`_ 
* `SetItemForegroundColour <#SetItemForegroundColour>`_ 

Properties Summary
^^^^^^^^^^^^^^^^^^

* `Selections <#Selections>`_ 

Class API
=========

Methods
^^^^^^^


.. method:: __init__(parent, id=-1, pos=wx.DefaultPosition, size=wx.DefaultSize, choices=[], style=0, validator=wx.DefaultValidator, name=wx.ListBoxNameStr)

   Constructor.

   **Parameters:**

   * `parent` (`wx.Window <wx.Window.html>`_)
   * `id` (int)
   * `pos` (`wx.Point <wx.Point.html>`_)
   * `size` (`wx.Size <wx.Size.html>`_)
   * `choices` (list of strings)
   * `style` (long)
   * `validator` (`wx.Validator <wx.Validator.html>`_)
   * `name` (string)

   |

   **Returns:**

   `wx.ListBox <wx.ListBox.html>`_
 

--------

.. method:: AppendAndEnsureVisible(s)

   Appends a string and ensure the item is visible.
   
   **Parameters:**

   * `s` (string)

--------

.. method:: Deselect(n)

   Deselects an item in the list box.

   **Parameters:**

   * `n` (int) 


.. note:: This applies to multiple selection listboxes only.
  

--------

.. method:: DeselectAll(itemToLeaveSelected=-1)

   Deselects all the items except the one specified in `itemToLeaveSelected`.
   
   **Parameters:**

   * `itemToLeaveSelected` (int)

--------

.. method:: EnsureVisible(n)

   Ensures that the item at position `n` is visible.
   
   **Parameters:**

   * `n` (int)

--------

.. method:: GetSelections()

   Fill an array of integers with the positions of the currently selected items.

   |  

   **Returns:**

   `list of integers` 


.. note:: Use this with a multiple selection listbox.
  

.. seealso:: `wx.ItemContainer.GetSelection <wx.ItemContainer.html#GetSelection>`_, 
   `wx.ItemContainer.GetStringSelection <wx.ItemContainer.html#GetStringSelection>`_, 
   `wx.ItemContainer.SetSelection <wx.ItemContainer.html#SetSelection>`_
  

--------

.. method:: InsertItems(items, pos)

   Insert the given number of strings before the specified position.

   **Parameters:**

   * `items` (list of strings)
   * `pos` (int)


--------

.. method:: IsSelected(n)

   Determines whether an item is selected.

   **Parameters:**

   * `n` (int): The zero-based item index.

   |  

   **Returns:**

   `bool` 

--------

.. method:: IsSorted()

   `No docstrings available for this method.` 

--------


.. method:: Set(s)

   Clears the list box and adds the given strings to it.

   **Parameters:**

   * `s` (list of string) 


.. note:: You may free the array from the calling program after this function has been called.
  

--------

.. method:: SetFirstItem(n)

   Set the specified item index to be the first visible item.

   **Parameters:**

   * `n` (int) 

--------

.. method:: SetFirstItemStr(s)

   Set the specified item string to be the first visible item.
   
   **Parameters:**

   * `s` (string)

--------

.. method:: SetItemBackgroundColour(item, c)

   Sets the item background colour.
   
   **Parameters:**

   * `item` (int)
   * `c` (`wx.Colour <wx.Colour.html>`_)

--------

.. method:: SetItemFont(item, f)

   Sets the item font.
   
   **Parameters:**

   * `item` (int)
   * `f` (`wx.Font <wx.Font.html>`_)

--------

.. method:: SetItemForegroundColour(item, c)

   Sets the item foreground colour.
   
   **Parameters:**

   * `item` (int)
   * `c` (`wx.Colour <wx.Colour.html>`_)

--------

Properties
^^^^^^^^^^


.. attribute:: Selections

   See `GetSelections <#GetSelections>`_