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

==========================================================================================================================================
|phoenix_title|  **wx.Choice**
==========================================================================================================================================

A choice item is used to select one of a list of strings.          

Unlike a :ref:`wx.ListBox`, only the selection is visible until the user pulls down the menu of choices. 

^^ 



.. _Choice-styles:

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

This class supports the following styles: 

  

- ``wx.CB_SORT``: Sorts the entries alphabetically. ^^ 

^^






.. _Choice-events:

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

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


- EVT_CHOICE: Process a  ``wxEVT_CHOICE``   event, when an item on the list is selected. ^^ 






         



.. seealso:: :ref:`wx.ListBox`, :ref:`wx.ComboBox`, :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>Choice</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.Choice_inheritance.png" alt="Inheritance diagram of Choice" 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.Choice.html" title="A choice item is used to select one of a list of strings." alt="" coords="148,315,233,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.choice.png
   :alt: wxMSW
   :figclass: floatleft

   **wxMSW**


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

   **wxMAC**


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

   **wxGTK**


|


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

:ref:`wx.DirFilterListCtrl`

|


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

================================================================================ ================================================================================
:meth:`~wx.Choice.__init__`                                                      Default constructor.
:meth:`~wx.Choice.Create`                                                        Creates the choice for two-step construction.
:meth:`~wx.Choice.FindString`                                                    Finds an item whose label matches the given string.
:meth:`~wx.Choice.GetClassDefaultAttributes`                                     
:meth:`~wx.Choice.GetColumns`                                                    Gets the number of columns in this choice item.
:meth:`~wx.Choice.GetCount`                                                      Returns the number of items in the control.
:meth:`~wx.Choice.GetCurrentSelection`                                           Unlike :meth:`wx.ControlWithItems.GetSelection`   which only returns the accepted selection value (the selection in the control once the user closes the dropdown list), this function returns the current selection.
:meth:`~wx.Choice.GetSelection`                                                  Returns the index of the selected item or  ``NOT_FOUND``   if no item is selected.
:meth:`~wx.Choice.GetString`                                                     Returns the label of the item with the given index.
:meth:`~wx.Choice.IsSorted`                                                      
:meth:`~wx.Choice.SetColumns`                                                    Sets the number of columns in this choice item.
:meth:`~wx.Choice.SetSelection`                                                  Sets the selection to the given item `n`  or removes the selection entirely if `n`  ==  ``NOT_FOUND`` .
:meth:`~wx.Choice.SetString`                                                     Sets the label for the given item.
================================================================================ ================================================================================


|


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

================================================================================ ================================================================================
:attr:`~wx.Choice.Columns`                                                       See :meth:`~wx.Choice.GetColumns` and :meth:`~wx.Choice.SetColumns`
:attr:`~wx.Choice.Count`                                                         See :meth:`~wx.Choice.GetCount`
:attr:`~wx.Choice.CurrentSelection`                                              See :meth:`~wx.Choice.GetCurrentSelection`
:attr:`~wx.Choice.Selection`                                                     See :meth:`~wx.Choice.GetSelection` and :meth:`~wx.Choice.SetSelection`
================================================================================ ================================================================================


|


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


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

   **Possible constructors**::

       Choice()
       
       Choice(parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize,
              choices=[], style=0, validator=DefaultValidator, name=ChoiceNameStr)
       
   
   A choice item is used to select one of a list of strings.



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



      |overload| Overloaded Implementations:

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

      
      **__init__** `(self)`
      
      Default constructor.                  
      
                       
      
      
      
      .. seealso:: :meth:`Create` , :ref:`wx.Validator`    
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, choices=[], style=0, validator=DefaultValidator, name=ChoiceNameStr)`
      
      Constructor, creating and showing a choice.                  
      
      
      
      
      :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 `pos`: Window position.   
      :type `pos`: wx.Point
      :param `size`: Window size. If DefaultSize is specified then the choice is sized appropriately.   
      :type `size`: wx.Size
      :param `choices`: An array of strings with which to initialise the choice control.   
      :type `choices`: list of strings
      :param `style`: Window style. See :ref:`wx.Choice`.   
      :type `style`: long
      :param `validator`: Window validator.   
      :type `validator`: wx.Validator
      :param `name`: Window name.  
      :type `name`: string
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






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

      Creates the choice for two-step construction.                  

      See :ref:`wx.Choice`.                  


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

      Gets the number of columns in this choice item.                  

                

      :rtype: `int`







      .. note:: 

         This is implemented for GTK and Motif only and always returns 1 for the other platforms.   








   .. method:: GetCount(self)

      Returns the number of items in the control.                  

                

      :rtype: `int`







      .. seealso:: :meth:`IsEmpty`     








   .. method:: GetCurrentSelection(self)

      Unlike :meth:`wx.ControlWithItems.GetSelection`   which only returns the accepted selection value (the selection in the control once the user closes the dropdown list), this function returns the current selection.                  

      That is, while the dropdown list is shown, it returns the currently selected item in it. When it is not shown, its result is the same as for the other function. 

                

      :rtype: `int`







      .. versionadded:: 2.6.2.
          In older versions, :meth:`wx.ControlWithItems.GetSelection`   itself behaved like this.   








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



      :rtype: `bool`








   .. method:: SetColumns(self, n=1)

      Sets the number of columns in this choice item.                  




      :param `n`: Number of columns.  
      :type `n`: int




                  



      .. note:: 

         This is implemented for GTK and Motif only and doesn’t do anything under other platforms.   








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






                  





   .. attribute:: Columns

      See :meth:`~wx.Choice.GetColumns` and :meth:`~wx.Choice.SetColumns`


   .. attribute:: Count

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


   .. attribute:: CurrentSelection

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


   .. attribute:: Selection

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