.. 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.adv.BitmapComboBox:

==========================================================================================================================================
|phoenix_title|  **wx.adv.BitmapComboBox**
==========================================================================================================================================

A combobox that displays bitmap in front of the list items.          

It currently only allows using bitmaps of one size, and resizes itself so that a bitmap can be shown next to the text field. 


^^  



.. _BitmapComboBox-styles:

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

This class supports the following styles: 

  

- ``wx.CB_READONLY``: Creates a combobox without a text editor. On some platforms the control may appear very different when this style is used.  
- ``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). Windows only. ^^ 




^^ 





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






         



.. note:: 

   While :ref:`wx.adv.BitmapComboBox`  contains the :ref:`wx.ComboBox`  API, but it might not actually be derived from that class. In fact, if the platform does not have a native implementation, :ref:`wx.adv.BitmapComboBox`  will inherit from :ref:`wx.adv.OwnerDrawnComboBox`. You can determine if the implementation is generic by checking whether  ``GENERIC_BITMAPCOMBOBOX``   is defined. Currently  :ref:`wx.adv.BitmapComboBox`  is implemented natively for MSW and GTK+.  







.. seealso:: :ref:`wx.ComboBox`, :ref:`wx.Choice`, :ref:`wx.adv.OwnerDrawnComboBox`, :ref:`wx.CommandEvent`    







.. todo:: create ``CB_PROCESS_ENTER`` rather than reusing ``wx.TE_PROCESS_ENTER``!   







|

|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>BitmapComboBox</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.adv.BitmapComboBox_inheritance.png" alt="Inheritance diagram of BitmapComboBox" 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.adv.BitmapComboBox.html" title="wx.adv.BitmapComboBox" alt="" coords="181,392,372,421"/> <area shape="rect" id="node2" href="wx.ComboBox.html" title="wx.ComboBox" alt="" coords="219,315,335,344"/> <area shape="rect" id="node3" href="wx.Control.html" title="wx.Control" alt="" coords="81,237,173,267"/> <area shape="rect" id="node4" href="wx.ItemContainer.html" title="wx.ItemContainer" alt="" coords="207,237,346,267"/> <area shape="rect" id="node5" href="wx.TextEntry.html" title="wx.TextEntry" alt="" coords="370,237,477,267"/> <area shape="rect" id="node6" href="wx.Window.html" title="wx.Window" alt="" coords="60,160,157,189"/> <area shape="rect" id="node7" href="wx.EvtHandler.html" title="wx.EvtHandler" alt="" coords="50,83,167,112"/> <area shape="rect" id="node8" href="wx.Object.html" title="wx.Object" alt="" coords="5,5,92,35"/> <area shape="rect" id="node9" href="wx.Trackable.html" title="wx.Trackable" alt="" coords="117,5,223,35"/> <area shape="rect" id="node10" href="wx.ItemContainerImmutable.html" title="wx.ItemContainerImmutable" alt="" coords="181,160,391,189"/> </map> 
   </p>
   </div>

|


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

|

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

   **wxMSW**


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

   **wxMAC**


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

   **wxGTK**


|


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

================================================================================ ================================================================================
:meth:`~wx.adv.BitmapComboBox.__init__`                                          Default constructor.
:meth:`~wx.adv.BitmapComboBox.Append`                                            Adds the item to the end of the combo box.
:meth:`~wx.adv.BitmapComboBox.Create`                                            Creates the combobox for two-step construction.
:meth:`~wx.adv.BitmapComboBox.Dismiss`                                           Hides the list box portion of the combo box.
:meth:`~wx.adv.BitmapComboBox.FindString`                                        Finds an item whose label matches the given string.
:meth:`~wx.adv.BitmapComboBox.GetBitmapSize`                                     Returns the size of the bitmaps used in the combo box.
:meth:`~wx.adv.BitmapComboBox.GetClassDefaultAttributes`                         
:meth:`~wx.adv.BitmapComboBox.GetCount`                                          Returns the number of items in the control.
:meth:`~wx.adv.BitmapComboBox.GetInsertionPoint`                                 Same as :meth:`wx.TextEntry.GetInsertionPoint` .
:meth:`~wx.adv.BitmapComboBox.GetItemBitmap`                                     Returns the bitmap of the item with the given index.
:meth:`~wx.adv.BitmapComboBox.GetSelection`                                      Returns the index of the selected item or  ``NOT_FOUND``   if no item is selected.
:meth:`~wx.adv.BitmapComboBox.GetTextSelection`                                  Gets the current selection span.
:meth:`~wx.adv.BitmapComboBox.GetString`                                         Returns the label of the item with the given index.
:meth:`~wx.adv.BitmapComboBox.Insert`                                            Inserts the item into the list before `pos`.
:meth:`~wx.adv.BitmapComboBox.IsListEmpty`                                       Returns ``True`` if the list of combobox choices is empty.
:meth:`~wx.adv.BitmapComboBox.IsTextEmpty`                                       Returns ``True`` if the text of the combobox is empty.
:meth:`~wx.adv.BitmapComboBox.Popup`                                             Shows the list box portion of the combo box.
:meth:`~wx.adv.BitmapComboBox.SetItemBitmap`                                     Sets the bitmap for the given item.
:meth:`~wx.adv.BitmapComboBox.SetSelection`                                      Same as :meth:`wx.TextEntry.SetSelection` .
:meth:`~wx.adv.BitmapComboBox.SetString`                                         Changes the text of the specified combobox item.
:meth:`~wx.adv.BitmapComboBox.SetTextSelection`                                  Same as :meth:`wx.TextEntry.SetSelection` .
:meth:`~wx.adv.BitmapComboBox.SetValue`                                          Sets the text for the combobox text field.
================================================================================ ================================================================================


|


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

================================================================================ ================================================================================
:attr:`~wx.adv.BitmapComboBox.BitmapSize`                                        See :meth:`~wx.adv.BitmapComboBox.GetBitmapSize`
:attr:`~wx.adv.BitmapComboBox.Count`                                             See :meth:`~wx.adv.BitmapComboBox.GetCount`
:attr:`~wx.adv.BitmapComboBox.InsertionPoint`                                    See :meth:`~wx.adv.BitmapComboBox.GetInsertionPoint`
:attr:`~wx.adv.BitmapComboBox.Selection`                                         See :meth:`~wx.adv.BitmapComboBox.GetSelection` and :meth:`~wx.adv.BitmapComboBox.SetSelection`
================================================================================ ================================================================================


|


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


.. class:: wx.adv.BitmapComboBox(Control, TextEntry, ItemContainer)

   **Possible constructors**::

       BitmapComboBox()
       
       BitmapComboBox(parent, id=ID_ANY, value="", pos=DefaultPosition,
                      size=DefaultSize, choices=[], style=0, validator=DefaultValidator,
                      name=BitmapComboBoxNameStr)
       
   
   A combobox that displays bitmap in front of the list items.



   .. 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, value=EmptyString, pos=DefaultPosition, size=DefaultSize, choices=[], style=0, validator=DefaultValidator, name=BitmapComboBoxNameStr)`
      
      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`: Initial position.   
      :type `pos`: wx.Point
      :param `size`: Initial size.   
      :type `size`: wx.Size
      :param `choices`: A :ref:`ArrayString`  with which to initialise the control.   
      :type `choices`: list of strings
      :param `style`: The window style, see ``CB_`` flags.   
      :type `style`: long
      :param `validator`: Validator which can be used for additional data checks.   
      :type `validator`: wx.Validator
      :param `name`: Control name.  
      :type `name`: string
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
                        
      
      
      
      .. seealso:: :meth:`Create` , :ref:`wx.Validator`    
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






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



      |overload| Overloaded Implementations:

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

      
      **Append** `(self, item, bitmap=NullBitmap)`
      
      Adds the item to the end of the combo box.                  
      
      
      :param `item`: 
      :type `item`: string
      :param `bitmap`: 
      :type `bitmap`: wx.Bitmap
      
      
      
      
      :rtype: `int`
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **Append** `(self, item, bitmap, clientData)`
      
      Adds the item to the end of the combo box, associating the given typed client data pointer `clientData`  with the item.                  
      
      
      :param `item`: 
      :type `item`: string
      :param `bitmap`: 
      :type `bitmap`: wx.Bitmap
      :param `clientData`: 
      :type `clientData`: ClientData
      
      
      
      
      :rtype: `int`
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






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

      Creates the combobox for two-step construction.                  


      :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:: GetBitmapSize(self)

      Returns the size of the bitmaps used in the combo box.                  

      If the combo box is empty, then :ref:`wx.DefaultSize`  is returned.                  

      :rtype: :ref:`Size`








   .. staticmethod:: GetClassDefaultAttributes(variant=WINDOW_VARIANT_NORMAL)




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




      :rtype: :ref:`VisualAttributes`








   .. method:: GetCount(self)

      Returns the number of items in the control.                  

                

      :rtype: `int`







      .. seealso:: :meth:`IsEmpty`     








   .. 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:: GetItemBitmap(self, n)

      Returns the bitmap of the item with the given index.                  


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




      :rtype: :ref:`Bitmap`








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







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

      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:: Insert(self, *args, **kw)



      |overload| Overloaded Implementations:

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

      
      **Insert** `(self, item, bitmap, pos)`
      
      Inserts the item into the list before `pos`.                  
      
      Not valid for  ``CB_SORT``   style, use  :meth:`Append`   instead.                  
      
      
      :param `item`: 
      :type `item`: string
      :param `bitmap`: 
      :type `bitmap`: wx.Bitmap
      :param `pos`: 
      :type `pos`: int
      
      
      
      
      :rtype: `int`
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **Insert** `(self, item, bitmap, pos, clientData)`
      
      Inserts the item into the list before pos, associating the given typed client data pointer with the item.                  
      
      Not valid for  ``CB_SORT``   style, use  :meth:`Append`   instead.                  
      
      
      :param `item`: 
      :type `item`: string
      :param `bitmap`: 
      :type `bitmap`: wx.Bitmap
      :param `pos`: 
      :type `pos`: int
      :param `clientData`: 
      :type `clientData`: ClientData
      
      
      
      
      :rtype: `int`
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. 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:: SetItemBitmap(self, n, bitmap)

      Sets the bitmap for the given item.                  


      :param `n`: 
      :type `n`: int
      :param `bitmap`: 
      :type `bitmap`: wx.BitmapBundle







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



      |overload| Overloaded Implementations:

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

      
      **SetSelection** `(self, from_, to_)`
      
      Same as :meth:`wx.TextEntry.SetSelection` .                  
      
      
      :param `from_`: 
      :type `from_`: long
      :param `to_`: 
      :type `to_`: long
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **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`     
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






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

      For normal, editable comboboxes with a text entry field calling this method will generate a  ``wxEVT_TEXT``   event, consistently with  :meth:`wx.TextEntry.SetValue`   behaviour, use :meth:`wx.TextEntry.ChangeValue`   if this is undesirable. 

      For controls with  ``CB_READONLY``   style the method behaves somewhat differently: the string must be in the combobox choices list (the check for this is case-insensitive) and   ``wxEVT_TEXT``   is  `not`  generated in this case. 




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




                  





   .. attribute:: BitmapSize

      See :meth:`~wx.adv.BitmapComboBox.GetBitmapSize`


   .. attribute:: Count

      See :meth:`~wx.adv.BitmapComboBox.GetCount`


   .. attribute:: InsertionPoint

      See :meth:`~wx.adv.BitmapComboBox.GetInsertionPoint`


   .. attribute:: Selection

      See :meth:`~wx.adv.BitmapComboBox.GetSelection` and :meth:`~wx.adv.BitmapComboBox.SetSelection`