.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2020 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc



.. _wx.ListBox:

==========================================================================================================================================
|phoenix_title|  **wx.ListBox**
==========================================================================================================================================

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 and while the maximal number of elements is unlimited, it is usually better to use a virtual control, not requiring to add all the items to it at once, such as :ref:`wx.dataview.DataViewCtrl`  or :ref:`wx.ListCtrl`  with  ``LC_VIRTUAL``   style, once more than a few hundreds items need to be displayed because this control is not optimized, neither from performance nor from user interface point of view, for large number of items. 

Notice that the list box doesn't support control characters other than  ``TAB`` . 

^^ 



.. _ListBox-styles:

|styles| Window Styles
================================

This class supports the following styles: 

  

- ``wx.LB_SINGLE``: Single-selection list.  
- ``wx.LB_MULTIPLE``: Multiple-selection list: the user can toggle multiple items on and off. This is the same as ``wx.LB_EXTENDED`` in wxGTK2 port.  
- ``wx.LB_EXTENDED``: Extended-selection list: the user can extend the selection by using  ``SHIFT``   or   ``CTRL``   keys together with the cursor movement keys or the mouse.   
- ``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_NO_SB``: Don't create vertical scrollbar (wxMSW and wxGTK only).  
- ``wx.LB_SORT``: The listbox contents are sorted in alphabetical order. ^^ 

Note that
 ``LB_SINGLE`` ,   ``LB_MULTIPLE``   and   ``LB_EXTENDED``   styles are mutually exclusive and you can specify at most one of them (single selection is the default). See also  :ref:`Window Styles <window styles>`. 

^^ 





.. _ListBox-events:

|events| Events Emitted by this Class
=====================================

Handlers bound for the following event types will receive a :ref:`wx.CommandEvent` parameter.


- EVT_LISTBOX: Process a  ``wxEVT_LISTBOX``   event, when an item on the list is selected or the selection changes.   
- EVT_LISTBOX_DCLICK: Process a  ``wxEVT_LISTBOX_DCLICK``   event, when the listbox is double-clicked. On some platforms (notably wxGTK2) pressing the enter key is handled as an equivalent of a double-click. ^^ 






         



.. seealso:: :ref:`wx.adv.EditableListBox`, :ref:`wx.Choice`, :ref:`wx.ComboBox`, :ref:`wx.ListCtrl`, :ref:`wx.CommandEvent`    







|

|class_hierarchy| Class Hierarchy
=================================

.. raw:: html

   <div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
   <img id="toggleBlock-trigger" src="_static/images/closed.png"/>
   Inheritance diagram for class <strong>ListBox</strong>:
   </div>
   <div id="toggleBlock-summary" style="display:block;"></div>
   <div id="toggleBlock-content" style="display:none;">
   <p class="graphviz">
   <center><img src="_static/images/inheritance/wx.ListBox_inheritance.png" alt="Inheritance diagram of ListBox" usemap="#dummy" class="inheritance"/></center>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.ListBox.html" title="A listbox is used to select one or more of a list of strings." alt="" coords="147,315,235,344"/> <area shape="rect" id="node2" href="wx.Control.html" title="This is the base class for a control or 'widget'." alt="" coords="71,237,159,267"/> <area shape="rect" id="node3" href="wx.ItemContainer.html" title="This class is an abstract base class for some wxWidgets controls which contain several items such as wx.ListBox, wx.CheckListBox, wx.ComboBox  or wx.Choice." alt="" coords="200,237,333,267"/> <area shape="rect" id="node4" href="wx.Window.html" title="wx.Window  is the base class for all windows and represents any visible object on screen." alt="" coords="61,160,150,189"/> <area shape="rect" id="node5" href="wx.EvtHandler.html" title="A class that can handle events from the windowing system." alt="" coords="49,83,161,112"/> <area shape="rect" id="node6" href="wx.Object.html" title="This is the root class of many of the wxWidgets classes." alt="" coords="5,5,88,35"/> <area shape="rect" id="node7" href="wx.Trackable.html" title="Add-on base class for a trackable object." alt="" coords="113,5,215,35"/> <area shape="rect" id="node8" href="wx.ItemContainerImmutable.html" title="wx.ItemContainer  defines an interface which is implemented by all controls which have string subitems each of which may be selected." alt="" coords="175,160,377,189"/> </map> 
   </p>
   </div>

|


|appearance| Control Appearance
===============================

|

.. figure:: _static/images/widgets/fullsize/wxmsw/wx.listbox.png
   :alt: wxMSW
   :figclass: floatleft

   **wxMSW**


.. figure:: _static/images/widgets/fullsize/wxmac/wx.listbox.png
   :alt: wxMAC
   :figclass: floatright

   **wxMAC**


.. figure:: _static/images/widgets/fullsize/wxgtk/wx.listbox.png
   :alt: wxGTK
   :figclass: floatcenter

   **wxGTK**


|


|sub_classes| Known Subclasses
==============================

:ref:`wx.CheckListBox`

|


|method_summary| Methods Summary
================================

================================================================================ ================================================================================
:meth:`~wx.ListBox.__init__`                                                     Default constructor.
:meth:`~wx.ListBox.Create`                                                       Creates the listbox for two-step construction.
:meth:`~wx.ListBox.Deselect`                                                     Deselects an item in the list box.
:meth:`~wx.ListBox.EnsureVisible`                                                Ensure that the item with the given index is currently shown.
:meth:`~wx.ListBox.FindString`                                                   Finds an item whose label matches the given string.
:meth:`~wx.ListBox.GetClassDefaultAttributes`                                    
:meth:`~wx.ListBox.GetCount`                                                     Returns the number of items in the control.
:meth:`~wx.ListBox.GetCountPerPage`                                              Return the number of items that can fit vertically in the visible area of the listbox.
:meth:`~wx.ListBox.GetSelection`                                                 Returns the index of the selected item or  ``NOT_FOUND``   if no item is selected.
:meth:`~wx.ListBox.GetSelections`                                                Fill an array of ints with the positions of the currently selected items.
:meth:`~wx.ListBox.GetString`                                                    Returns the label of the item with the given index.
:meth:`~wx.ListBox.GetTopItem`                                                   Return the index of the topmost visible item.
:meth:`~wx.ListBox.HitTest`                                                      Returns the item located at `point`, or  ``NOT_FOUND``   if there is no item located at  `point`.
:meth:`~wx.ListBox.InsertItems`                                                  Insert the given number of strings before the specified position.
:meth:`~wx.ListBox.IsSelected`                                                   Determines whether an item is selected.
:meth:`~wx.ListBox.IsSorted`                                                     Return ``True`` if the listbox has ``LB_SORT``  style.
:meth:`~wx.ListBox.MSWSetTabStops`                                               
:meth:`~wx.ListBox.SetFirstItem`                                                 Set the specified item to be the first visible item.
:meth:`~wx.ListBox.SetItemBackgroundColour`                                      Set the background colour of an item in the ListBox.
:meth:`~wx.ListBox.SetItemFont`                                                  Set the font of an item in the ListBox.
:meth:`~wx.ListBox.SetItemForegroundColour`                                      Set the foreground colour of an item in the ListBox.
:meth:`~wx.ListBox.SetSelection`                                                 Sets the selection to the given item `n`  or removes the selection entirely if `n`  ==  ``NOT_FOUND`` .
:meth:`~wx.ListBox.SetString`                                                    Sets the label for the given item.
:meth:`~wx.ListBox.SetStringSelection`                                           
================================================================================ ================================================================================


|


|property_summary| Properties Summary
=====================================

================================================================================ ================================================================================
:attr:`~wx.ListBox.Count`                                                        See :meth:`~wx.ListBox.GetCount`
:attr:`~wx.ListBox.CountPerPage`                                                 See :meth:`~wx.ListBox.GetCountPerPage`
:attr:`~wx.ListBox.Selection`                                                    See :meth:`~wx.ListBox.GetSelection` and :meth:`~wx.ListBox.SetSelection`
:attr:`~wx.ListBox.Selections`                                                   See :meth:`~wx.ListBox.GetSelections`
:attr:`~wx.ListBox.TopItem`                                                      See :meth:`~wx.ListBox.GetTopItem`
================================================================================ ================================================================================


|


|api| Class API
===============


.. class:: wx.ListBox(Control, ItemContainer)

   **Possible constructors**::

       ListBox()
       
       ListBox(parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize,
               choices=[], style=0, validator=DefaultValidator, name=ListBoxNameStr)
       
   
   A listbox is used to select one or more of a list of strings.



   .. method:: __init__(self, *args, **kw)



      |overload| Overloaded Implementations:

      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self)`
      
      Default constructor.                   
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, choices=[], style=0, validator=DefaultValidator, name=ListBoxNameStr)`
      
      Constructor, creating and showing a list box.                  
      
      See the other :ref:`wx.ListBox`  constructor; the only difference is that this overload takes a list of strings       instead of a pointer to an array of `String`     . 
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. method:: Create(self, parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, choices=[], style=0, validator=DefaultValidator, name=ListBoxNameStr)

      Creates the listbox for two-step construction.                  

      See :ref:`wx.ListBox`  for further details.                  


      :param `parent`: 
      :type `parent`: wx.Window
      :param `id`: 
      :type `id`: wx.WindowID
      :param `pos`: 
      :type `pos`: wx.Point
      :param `size`: 
      :type `size`: wx.Size
      :param `choices`: 
      :type `choices`: list of strings
      :param `style`: 
      :type `style`: long
      :param `validator`: 
      :type `validator`: wx.Validator
      :param `name`: 
      :type `name`: string




      :rtype: `bool`








   .. method:: Deselect(self, n)

      Deselects an item in the list box.                  




      :param `n`: The zero-based item to deselect.  
      :type `n`: int




                  



      .. note:: 

         This applies to multiple selection listboxes only.   








   .. method:: EnsureVisible(self, n)

      Ensure that the item with the given index is currently shown.                  

      This method scrolls the listbox only if necessary and doesn't do anything if this item is already shown, unlike :meth:`SetFirstItem` .                  


      :param `n`: 
      :type `n`: int







   .. method:: FindString(self, string, caseSensitive=False)

      Finds an item whose label matches the given string.                  




      :param `string`: String to find.   
      :type `string`: string
      :param `caseSensitive`: Whether search is case sensitive (default is not).  
      :type `caseSensitive`: bool








      :rtype: `int`



                  



      :returns: 

         The zero-based position of the item, or ``wx.NOT_FOUND`` if the string was not found.   








   .. staticmethod:: GetClassDefaultAttributes(variant=WINDOW_VARIANT_NORMAL)




      :param `variant`: 
      :type `variant`: wx.WindowVariant




      :rtype: :ref:`wx.VisualAttributes`








   .. method:: GetCount(self)

      Returns the number of items in the control.                  

                

      :rtype: `int`







      .. seealso:: :meth:`IsEmpty`     








   .. method:: GetCountPerPage(self)

      Return the number of items that can fit vertically in the visible area of the listbox.                  

      Returns -1 if the number of items per page couldn't be determined. On wxGTK this method can only determine the number of items per page if there is at least one item in the listbox. 

                

      :rtype: `int`







      .. versionadded:: 4.1/wxWidgets-3.1.0  
     








   .. method:: GetSelection(self)

      Returns the index of the selected item or  ``NOT_FOUND``   if no item is selected.                   

                

      :rtype: `int`







      :returns: 

         The position of the current selection.  







      .. note:: 

         This method can be used with single selection list boxes only, you must use :meth:`wx.ListBox.GetSelections`   for the list boxes with ``wx.LB_MULTIPLE`` style.  







      .. seealso:: :meth:`SetSelection` , :meth:`GetStringSelection`     








   .. method:: GetSelections(self)

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





      :rtype: `list of integers`



      




   .. method:: GetString(self, n)

      Returns the label of the item with the given index.                  

      The index must be valid, i.e. less than the value returned by :meth:`GetCount` , otherwise an assert is triggered. Notably, this function can't be called if the control is empty. 




      :param `n`: The zero-based index.  
      :type `n`: int






      :rtype: `string`



                  



      :returns: 

         The label of the item.   








   .. method:: GetTopItem(self)

      Return the index of the topmost visible item.                  

      Returns ``NOT_FOUND``  if the method is not implemented for the current platform. 

                

      :rtype: `int`







      .. versionadded:: 4.1/wxWidgets-3.1.0  
     








   .. method:: HitTest(self, *args, **kw)



      |overload| Overloaded Implementations:

      :html:`<hr class="overloadsep" /><br />`

      
      **HitTest** `(self, point)`
      
      Returns the item located at `point`, or  ``NOT_FOUND``   if there is no item located at  `point`.                  
      
      It is currently implemented for wxMSW, Mac and wxGTK2 ports. 
      
      
      
      
      :param `point`: Point of item (in client coordinates) to obtain  
      :type `point`: wx.Point
      
      
      
      
      
      
      :rtype: `int`
      
      
      
                        
      
      
      
      :returns: 
      
         Item located at point, or ``wx.NOT_FOUND`` if unimplemented or the item does not exist.  
      
      
      
      
      
      
      
      .. versionadded:: 2.7.0 
           
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **HitTest** `(self, x, y)`
      
      This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.                  
      
      
      :param `x`: 
      :type `x`: int
      :param `y`: 
      :type `y`: int
      
      
      
      
      :rtype: `int`
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. method:: InsertItems(self, items, pos)

      Insert the given number of strings before the specified position.                  




      :param `items`: Labels of items to be inserted   
      :type `items`: list of strings
      :param `pos`: Position before which to insert the items: if pos is  ``0``   the items will be inserted in the beginning of the listbox  
      :type `pos`: int






      




   .. method:: IsSelected(self, n)

      Determines whether an item is selected.                  




      :param `n`: The zero-based item index.  
      :type `n`: int






      :rtype: `bool`



                  



      :returns: 

         ``True`` if the given item is selected, ``False`` otherwise.   








   .. method:: IsSorted(self)

      Return ``True`` if the listbox has ``LB_SORT``  style.                  

      This method is mostly meant for internal use only.                  

      :rtype: `bool`








   .. method:: MSWSetTabStops(self, tabStops)

                        





   .. method:: SetFirstItem(self, *args, **kw)



      |overload| Overloaded Implementations:

      :html:`<hr class="overloadsep" /><br />`

      
      **SetFirstItem** `(self, n)`
      
      Set the specified item to be the first visible item.                  
      
      
      
      
      :param `n`: The zero-based item index that should be visible.   
      :type `n`: int
      
      
      
      
                        
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **SetFirstItem** `(self, string)`
      
      Set the specified item to be the first visible item.                  
      
      
      
      
      :param `string`: The string that should be visible.   
      :type `string`: string
      
      
      
      
                        
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. method:: SetItemBackgroundColour(self, item, c)

                              Set the background colour of an item in the ListBox.
                              Only valid on MSW and if the ``wx.LB_OWNERDRAW`` flag is set.  





   .. method:: SetItemFont(self, item, f)

                              Set the font of an item in the ListBox.
                              Only valid on MSW and if the ``wx.LB_OWNERDRAW`` flag is set.  





   .. method:: SetItemForegroundColour(self, item, c)

                              Set the foreground colour of an item in the ListBox.
                              Only valid on MSW and if the ``wx.LB_OWNERDRAW`` flag is set.  





   .. method:: SetSelection(self, n)

      Sets the selection to the given item `n`  or removes the selection entirely if `n`  ==  ``NOT_FOUND`` .                   

      Note that this does not cause any command events to be emitted nor does it deselect any other items in the controls which support multiple selections. 




      :param `n`: The string position to select, starting from zero.  
      :type `n`: int




                  



      .. seealso:: :meth:`SetString` , :meth:`SetStringSelection`     








   .. method:: SetString(self, n, string)

      Sets the label for the given item.                  




      :param `n`: The zero-based item index.   
      :type `n`: int
      :param `string`: The label to set.   
      :type `string`: string






                  





   .. method:: SetStringSelection(self, *args, **kw)



      |overload| Overloaded Implementations:

      :html:`<hr class="overloadsep" /><br />`

      
      **SetStringSelection** `(self, s, select)`
      
      
      
      
      :param `s`: 
      :type `s`: string
      :param `select`: 
      :type `select`: bool
      
      
      
      
      :rtype: `bool`
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **SetStringSelection** `(self, s)`
      
      
      
      
      :param `s`: 
      :type `s`: string
      
      
      
      
      :rtype: `bool`
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. attribute:: Count

      See :meth:`~wx.ListBox.GetCount`


   .. attribute:: CountPerPage

      See :meth:`~wx.ListBox.GetCountPerPage`


   .. attribute:: Selection

      See :meth:`~wx.ListBox.GetSelection` and :meth:`~wx.ListBox.SetSelection`


   .. attribute:: Selections

      See :meth:`~wx.ListBox.GetSelections`


   .. attribute:: TopItem

      See :meth:`~wx.ListBox.GetTopItem`