.. wxPython Phoenix documentation

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

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

.. include:: headings.inc



.. _wx.ComboBox:

==========================================================================================================================================
|phoenix_title|  **wx.ComboBox**
==========================================================================================================================================

A combobox is like a combination of an edit control and a listbox.          

It can be displayed as static list with editable or read-only text field; or a drop-down list with text field; or a drop-down list without a text field depending on the platform and presence of ``wx.CB_READONLY`` style. 

A combobox permits a single selection only. Combobox items are numbered from zero. 

If you need a customized combobox, have a look at :ref:`wx.ComboCtrl`, :ref:`wx.adv.OwnerDrawnComboBox`, :ref:`wx.ComboPopup`  and the ready-to-use :ref:`wx.adv.BitmapComboBox`. 

Please refer to :ref:`wx.TextEntry`  documentation for the description of methods operating with the text entry part of the combobox and to :ref:`wx.ItemContainer`  for the methods operating with the list of strings. Notice that at least under MSW :ref:`wx.ComboBox`  doesn't behave correctly if it contains strings differing in case only so portable programs should avoid adding such strings to this control. 





.. _ComboBox-styles:

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

This class supports the following styles: 

  

- ``wx.CB_SIMPLE``: Creates a combobox with a permanently displayed list. Windows only.  
- ``wx.CB_DROPDOWN``: Creates a combobox with a drop-down list. MSW and Motif only.  
- ``wx.CB_READONLY``: A combobox with this style behaves like a :ref:`wx.Choice`  (and may look in the same way as well, although this is platform-dependent), i.e. it allows the user to choose from the list of options but doesn't allow to enter a value not present in the list.  
- ``wx.CB_SORT``: Sorts the entries in the list alphabetically.  
- ``wx.TE_PROCESS_ENTER``: The control will generate the event  ``wxEVT_TEXT_ENTER``   (otherwise pressing Enter key is either processed internally by the control or used for navigation between dialog controls).   








.. _ComboBox-events:

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

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


- EVT_COMBOBOX: Process a  ``wxEVT_COMBOBOX``   event, when an item on the list is selected. Note that calling  :meth:`~wx.ComboBox.GetValue`  returns the new value of selection.  
- EVT_TEXT: Process a  ``wxEVT_TEXT``   event, when the combobox text changes.   
- EVT_TEXT_ENTER: Process a  ``wxEVT_TEXT_ENTER``   event, when ``RETURN`` is pressed in the combobox (notice that the combobox must have been created with ``wx.TE_PROCESS_ENTER`` style to receive this event).   
- EVT_COMBOBOX_DROPDOWN: Process a  ``wxEVT_COMBOBOX_DROPDOWN``   event, which is generated when the list box part of the combo box is shown (drops down). Notice that this event is only supported by wxMSW, wxGTK with GTK+ 2.10 or later, and OSX/Cocoa.   
- EVT_COMBOBOX_CLOSEUP: Process a  ``wxEVT_COMBOBOX_CLOSEUP``   event, which is generated when the list box of the combo box disappears (closes up). This event is only generated for the same platforms as   ``wxEVT_COMBOBOX_DROPDOWN``   above. Also note that only wxMSW and OSX/Cocoa support adding or deleting items in this event.   








         



.. seealso:: :ref:`wx.ListBox`, :ref:`wx.TextCtrl`, :ref:`wx.Choice`, :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>ComboBox</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.ComboBox_inheritance.png" alt="Inheritance diagram of ComboBox" usemap="#dummy" class="inheritance"/></center>
   </div>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.Control.html" title="wx.Control" alt="" coords="323,237,411,267"/> <area shape="rect" id="node9" href="wx.ComboBox.html" title="wx.ComboBox" alt="" coords="192,315,303,344"/> <area shape="rect" id="node2" href="wx.Window.html" title="wx.Window" alt="" coords="322,160,411,189"/> <area shape="rect" id="node3" href="wx.ItemContainer.html" title="wx.ItemContainer" alt="" coords="40,237,173,267"/> <area shape="rect" id="node4" href="wx.ItemContainerImmutable.html" title="wx.ItemContainerImmutable" alt="" coords="5,160,208,189"/> <area shape="rect" id="node5" href="wx.Object.html" title="wx.Object" alt="" coords="268,5,349,35"/> <area shape="rect" id="node6" href="wx.EvtHandler.html" title="wx.EvtHandler" alt="" coords="311,83,421,112"/> <area shape="rect" id="node7" href="wx.Trackable.html" title="wx.Trackable" alt="" coords="375,5,476,35"/> <area shape="rect" id="node8" href="wx.TextEntry.html" title="wx.TextEntry" alt="" coords="198,237,297,267"/> </map> 
   </p>

|


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

|

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

   **wxMSW**


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

   **wxMAC**


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

   **wxGTK**


|


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

:ref:`wx.adv.BitmapComboBox`

|


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

================================================================================ ================================================================================
:meth:`~wx.ComboBox.__init__`                                                    Default constructor.
:meth:`~wx.ComboBox.Create`                                                      Creates the combobox for two-step construction.
:meth:`~wx.ComboBox.Dismiss`                                                     Hides the list box portion of the combo box.
:meth:`~wx.ComboBox.FindString`                                                  Finds an item whose label matches the given string.
:meth:`~wx.ComboBox.GetCount`                                                    Returns the number of items in the control.
:meth:`~wx.ComboBox.GetCurrentSelection`                                         Returns the item being selected right now.
:meth:`~wx.ComboBox.GetInsertionPoint`                                           Same as :meth:`wx.TextEntry.GetInsertionPoint` .
:meth:`~wx.ComboBox.GetSelection`                                                Returns the index of the selected item or  ``NOT_FOUND``   if no item is selected.
:meth:`~wx.ComboBox.GetTextSelection`                                            Gets the current selection span.
:meth:`~wx.ComboBox.GetString`                                                   Returns the label of the item with the given index.
:meth:`~wx.ComboBox.GetStringSelection`                                          Gets the text currently selected in the control.
:meth:`~wx.ComboBox.IsListEmpty`                                                 Returns ``True`` if the list of combobox choices is empty.
:meth:`~wx.ComboBox.IsTextEmpty`                                                 Returns ``True`` if the text of the combobox is empty.
:meth:`~wx.ComboBox.Popup`                                                       Shows the list box portion of the combo box.
:meth:`~wx.ComboBox.SetSelection`                                                Same as :meth:`wx.TextEntry.SetSelection` .
:meth:`~wx.ComboBox.SetString`                                                   Changes the text of the specified combobox item.
:meth:`~wx.ComboBox.SetTextSelection`                                            Same as :meth:`wx.TextEntry.SetSelection` .
:meth:`~wx.ComboBox.SetValue`                                                    Sets the text for the combobox text field.
================================================================================ ================================================================================


|


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

================================================================================ ================================================================================
:attr:`~wx.ComboBox.Count`                                                       See :meth:`~wx.ComboBox.GetCount`
:attr:`~wx.ComboBox.CurrentSelection`                                            See :meth:`~wx.ComboBox.GetCurrentSelection`
:attr:`~wx.ComboBox.InsertionPoint`                                              See :meth:`~wx.ComboBox.GetInsertionPoint`
:attr:`~wx.ComboBox.Selection`                                                   See :meth:`~wx.ComboBox.GetSelection` and :meth:`~wx.ComboBox.SetSelection`
:attr:`~wx.ComboBox.StringSelection`                                             See :meth:`~wx.ComboBox.GetStringSelection`
================================================================================ ================================================================================


|


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


.. class:: wx.ComboBox(Control, ItemContainer, TextEntry)

   **Possible constructors**::

       ComboBox()
       
       ComboBox(parent, id=ID_ANY, value=EmptyString, pos=DefaultPosition,
                size=DefaultSize, choices=[], style=0, validator=DefaultValidator,
                name=ComboBoxNameStr)
       
   
   A combobox is like a combination of an edit control and a listbox.



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



      |overload| Overloaded Implementations:

      **~~~**

      
      **__init__** `(self)`
      
      Default constructor.                   
      
      
      
      
      **~~~**

      
      **__init__** `(self, parent, id=ID_ANY, value=EmptyString, pos=DefaultPosition, size=DefaultSize, choices=[], style=0, validator=DefaultValidator, name=ComboBoxNameStr)`
      
      Constructor, creating and showing a combobox.                  
      
      
      
      
      :param `parent`: Parent window. Must not be ``None``.   
      :type `parent`: wx.Window
      :param `id`: Window identifier. The value ``wx.ID_ANY`` indicates a default value.   
      :type `id`: wx.WindowID
      :param `value`: Initial selection string. An empty string indicates no selection.   
      :type `value`: string
      :param `pos`: Window position.   
      :type `pos`: wx.Point
      :param `size`: Window size. If DefaultSize is specified then the window is sized appropriately.   
      :type `size`: wx.Size
      :param `choices`: An array of strings with which to initialise the control.   
      :type `choices`: list of strings
      :param `style`: Window style. See :ref:`wx.ComboBox`.   
      :type `style`: long
      :param `validator`: Window validator.   
      :type `validator`: wx.Validator
      :param `name`: Window name.  
      :type `name`: string
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      **~~~**






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

      Creates the combobox for two-step construction.                  

      Derived classes should call or replace this function. See :ref:`wx.ComboBox`  for further details.                  


      :param `parent`: 
      :type `parent`: wx.Window
      :param `id`: 
      :type `id`: wx.WindowID
      :param `value`: 
      :type `value`: string
      :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:: Dismiss(self)

      Hides the list box portion of the combo box.                  

      Currently this method is implemented in wxMSW, wxGTK and OSX/Cocoa. 

      Notice that calling this function will generate a  ``wxEVT_COMBOBOX_CLOSEUP``   event except under wxOSX where generation of this event is not supported at all. 

                 



      .. versionadded:: 2.9.1 
     








   .. 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.   








   .. method:: GetCount(self)

      Returns the number of items in the control.                  

                

      :rtype: `int`







      .. seealso:: :meth:`IsEmpty`     








   .. method:: GetCurrentSelection(self)

      Returns the item being selected right now.                  

      This function does the same things as :meth:`wx.Choice.GetCurrentSelection`   and returns the item currently selected in the dropdown list if it's open or the same thing as :meth:`wx.ControlWithItems.GetSelection`   otherwise.                  

      :rtype: `int`








   .. method:: GetInsertionPoint(self)

      Same as :meth:`wx.TextEntry.GetInsertionPoint` .                  

                

      :rtype: `long`







      .. note:: 

         Under wxMSW, this function always returns 0 if the combobox doesn't have the focus.   








   .. 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 should use :meth:`wx.ListBox.GetSelections`   for the list boxes with ``wx.LB_MULTIPLE`` style.  







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








   .. method:: GetTextSelection(self)

      Gets the current selection span.                  

      If the returned values are equal, there was no selection. Please note that the indices returned may be used with the other :ref:`wx.TextCtrl`  methods but don't necessarily represent the correct indices into the string returned by :meth:`GetValue`   for multiline controls under Windows (at least,) you should use :meth:`GetStringSelection`   to get the selected text. 







      :rtype: `tuple`



      




   .. method:: GetString(self, n)

      Returns the label of the item with the given index.                  




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






      :rtype: `string`



                  



      :returns: 

         The label of the item or an empty string if the position was invalid.   








   .. method:: GetStringSelection(self)

      Gets the text currently selected in the control.                  

      If there is no selection, the returned string is empty.                  

      :rtype: `string`








   .. method:: IsListEmpty(self)

      Returns ``True`` if the list of combobox choices is empty.                  

      Use this method instead of (not available in this class) :meth:`IsEmpty`   to test if the list of items is empty. 

                

      :rtype: `bool`







      .. versionadded:: 2.9.3 
     








   .. method:: IsTextEmpty(self)

      Returns ``True`` if the text of the combobox is empty.                  

      Use this method instead of (not available in this class) :meth:`IsEmpty`   to test if the text currently entered into the combobox is empty. 

                

      :rtype: `bool`







      .. versionadded:: 2.9.3 
     








   .. method:: Popup(self)

      Shows the list box portion of the combo box.                  

      Currently this method is implemented in wxMSW, wxGTK and OSX/Cocoa. 

      Notice that calling this function will generate a  ``wxEVT_COMBOBOX_DROPDOWN``   event except under wxOSX where generation of this event is not supported at all. 

                 



      .. versionadded:: 2.9.1 
     








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



      |overload| Overloaded Implementations:

      **~~~**

      
      **SetSelection** `(self, from_, to_)`
      
      Same as :meth:`wx.TextEntry.SetSelection` .                  
      
      
      :param `from_`: 
      :type `from_`: long
      :param `to_`: 
      :type `to_`: long
      
      
      
      
      
      
      **~~~**

      
      **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, text)

      Changes the text of the specified combobox item.                  

      Notice that if the item is the currently selected one, i.e. if its text is displayed in the text part of the combobox, then the text is also replaced with the new `text`.                  


      :param `n`: 
      :type `n`: int
      :param `text`: 
      :type `text`: string







   .. method:: SetTextSelection(self, from_, to_)

      Same as :meth:`wx.TextEntry.SetSelection` .                  


      :param `from_`: 
      :type `from_`: long
      :param `to_`: 
      :type `to_`: long







   .. method:: SetValue(self, text)

      Sets the text for the combobox text field.                  

      Notice that this method will generate a  ``wxEVT_TEXT``   event, use  :meth:`wx.TextEntry.ChangeValue`   if this is undesirable. 




      :param `text`: The text to set.   
      :type `text`: string




                  



      .. note:: 

         For a combobox with  ``CB_READONLY``   style the string must be in the combobox choices list, otherwise the call to  :meth:`SetValue`   is ignored. This is case insensitive.  








   .. attribute:: Count

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


   .. attribute:: CurrentSelection

      See :meth:`~wx.ComboBox.GetCurrentSelection`


   .. attribute:: InsertionPoint

      See :meth:`~wx.ComboBox.GetInsertionPoint`


   .. attribute:: Selection

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


   .. attribute:: StringSelection

      See :meth:`~wx.ComboBox.GetStringSelection`