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

==========================================================================================================================================
|phoenix_title|  **wx.ItemContainer**
==========================================================================================================================================

This class is an abstract base class for some wxWidgets controls which contain several items such as :ref:`wx.ListBox`, :ref:`wx.CheckListBox`, :ref:`wx.ComboBox`  or :ref:`wx.Choice`.          

It defines an interface which is implemented by all controls which have string subitems each of which may be selected. 

:ref:`wx.ItemContainer`  extends :ref:`wx.ItemContainerImmutable`  interface with methods for adding/removing items. 

It defines the methods for accessing the controls items and although each of the derived classes implements them differently, they still all conform to the same interface. 

The items in a :ref:`wx.ItemContainer`  have (non-empty) string labels and, optionally, client data associated with them. Client data may be of two different kinds: either simple untyped ( ``void``   ) pointers which are simply stored by the control but not used in any way by it, or typed pointers (wxClientData) which are owned by the control meaning that the typed client data (and only it) will be deleted when an item is deleted using  :meth:`~wx.ItemContainer.Delete`  or the entire control is cleared using :meth:`~wx.ItemContainer.Clear`, which also happens when it is destroyed. 

Finally note that in the same control all items must have client data of the same type (typed or untyped), if any. This type is determined by the first call to :meth:`~wx.ItemContainer.Append`  (the version with client data pointer) or :meth:`~wx.ItemContainer.SetClientData`. 

Note that this is not a control, it's a mixin interface that classes have to derive from in addition to :ref:`wx.Control`  or :ref:`wx.Window`. Convenience class :ref:`wx.ControlWithItems`  is provided for this purpose. 







         



.. seealso:: :ref:`wx.ControlWithItems`, :ref:`wx.ItemContainerImmutable`    







|

|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>ItemContainer</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.ItemContainer_inheritance.png" alt="Inheritance diagram of ItemContainer" 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.ItemContainer.html" title="wx.ItemContainer" alt="" coords="40,83,173,112"/> <area shape="rect" id="node2" href="wx.ItemContainerImmutable.html" title="wx.ItemContainerImmutable" alt="" coords="5,5,208,35"/> </map> 
   </p>

|


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

:ref:`wx.Choice`, :ref:`wx.ComboBox`, :ref:`wx.ControlWithItems`, :ref:`wx.ListBox`, :ref:`wx.adv.OwnerDrawnComboBox`, :ref:`wx.html.SimpleHtmlListBox`

|


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

================================================================================ ================================================================================
:meth:`~wx.ItemContainer.Append`                                                 Appends item into the control.
:meth:`~wx.ItemContainer.AppendItems`                                            
:meth:`~wx.ItemContainer.Clear`                                                  Removes all items from the control.
:meth:`~wx.ItemContainer.Delete`                                                 Deletes an item from the control.
:meth:`~wx.ItemContainer.DetachClientObject`                                     Returns the client object associated with the given item and transfers its ownership to the caller.
:meth:`~wx.ItemContainer.GetClientData`                                          Returns a pointer to the client data associated with the given item (if any).
:meth:`~wx.ItemContainer.GetClientObject`                                        Alias for :meth:`~ItemContainer.GetClientData`
:meth:`~wx.ItemContainer.GetItems`                                               
:meth:`~wx.ItemContainer.HasClientData`                                          Returns ``True``, if either untyped data ( ``void*`` ) or object data (wxClientData) is associated with the items of the control.
:meth:`~wx.ItemContainer.HasClientObjectData`                                    Returns ``True``, if object data is associated with the items of the control.
:meth:`~wx.ItemContainer.HasClientUntypedData`                                   Returns ``True``, if untyped data ( ``void*`` ) is associated with the items of the control.
:meth:`~wx.ItemContainer.Insert`                                                 Inserts item into the control.
:meth:`~wx.ItemContainer.Set`                                                    Replaces the current control contents with the given items.
:meth:`~wx.ItemContainer.SetClientData`                                          Associates the given typed client data pointer with the given item: the `data`  object will be deleted when the item is deleted (either explicitly by using :meth:`~ItemContainer.Delete`   or implicitly when the control itself is destroyed).
:meth:`~wx.ItemContainer.SetClientObject`                                        Alias for :meth:`~ItemContainer.SetClientData`
:meth:`~wx.ItemContainer.SetItems`                                               
================================================================================ ================================================================================


|


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

================================================================================ ================================================================================
:attr:`~wx.ItemContainer.Items`                                                  See :meth:`~wx.ItemContainer.GetItems` and :meth:`~wx.ItemContainer.SetItems`
================================================================================ ================================================================================


|


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


.. class:: wx.ItemContainer(ItemContainerImmutable)

   This class is an abstract base class for some wxWidgets controls which
   contain several items such as ListBox, CheckListBox, ComboBox or
   Choice.



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



      |overload| Overloaded Implementations:

      **~~~**

      
      **Append** `(self, item)`
      
      Appends item into the control.                  
      
      
      
      
      :param `item`: String to add.  
      :type `item`: string
      
      
      
      
      
      
      :rtype: `int`
      
      
      
                        
      
      
      
      :returns: 
      
         The return value is the index of the newly inserted item. Note that this may be different from the last one if the control is sorted (e.g. has  ``LB_SORT``   or   ``CB_SORT``   style).    
      
      
      
      
      
      
      
      **~~~**

      
      **Append** `(self, item, clientData)`
      
      Appends item into the control.                  
      
      
      
      
      :param `item`: String to add.   
      :type `item`: string
      :param `clientData`: Pointer to client data to associate with the new item.  
      :type `clientData`: ClientData
      
      
      
      
      
      
      
      
      :rtype: `int`
      
      
      
                        
      
      
      
      :returns: 
      
         The return value is the index of the newly inserted item. Note that this may be different from the last one if the control is sorted (e.g. has  ``LB_SORT``   or   ``CB_SORT``   style).    
      
      
      
      
      
      
      
      **~~~**

      
      **Append** `(self, items)`
      
      Appends several items at once into the control.                  
      
      Notice that calling this method is usually much faster than appending them one by one if you need to add a lot of items. 
      
      
      
      
      :param `items`: Array of strings to insert.   
      :type `items`: list of strings
      
      
      
      
      
      
      :rtype: `int`
      
      
      
                        
      
      
      
      
      **~~~**






   .. method:: AppendItems(self, items)




   .. method:: Clear(self)

      Removes all items from the control.                  

      :meth:`Clear`   also deletes the client data of the existing items if it is owned by the control.                   





   .. method:: Delete(self, n)

      Deletes an item from the control.                  

      The client data associated with the item will be also deleted if it is owned by the control. Note that it is an error (signalled by an assert failure in debug builds) to remove an item with the index negative or greater or equal than the number of items in the control. 




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




                  



      .. seealso:: :meth:`Clear`     








   .. method:: DetachClientObject(self, n)

      Returns the client object associated with the given item and transfers its ownership to the caller.                  

      This method, unlike :meth:`GetClientObject` , expects the caller to delete the returned pointer. It also replaces the internally stored pointer with ``None``, i.e. completely detaches the client object pointer from the control. 

      It's an error to call this method unless :meth:`HasClientObjectData`   returns ``True``. 




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






      :rtype: :ref:`ClientData`



                  



      :returns: 

         The associated client object pointer to be deleted by caller or ``None``.  







      .. versionadded:: 2.9.2 
     








   .. method:: GetClientData(self, n)

      Returns a pointer to the client data associated with the given item (if any).                  

      It is an error to call this function for a control which doesn't have typed client data at all although it is ``wx.OK`` to call it even if the given item doesn't have any client data associated with it (but other items do). 

      Notice that the returned pointer is still owned by the control and will be deleted by it, use :meth:`DetachClientObject`   if you want to remove the pointer from the control. 




      :param `n`: The zero-based position of the item.  
      :type `n`: int






      :rtype: :ref:`ClientData`



                  



      :returns: 

         A pointer to the client data, or ``None`` if not present.   








   .. method:: GetClientObject(self, n)

      Alias for :meth:`GetClientData`



   .. method:: GetItems(self)




   .. method:: HasClientData(self)

      Returns ``True``, if either untyped data ( ``void*`` ) or object data (wxClientData) is associated with the items of the control.                   

      :rtype: `bool`








   .. method:: HasClientObjectData(self)

      Returns ``True``, if object data is associated with the items of the control.                  

      Object data pointers have the type  ``ClientData*``   instead of   ``void*``   and, importantly, are owned by the control, i.e. will be deleted by it, unlike their untyped counterparts.                   

      :rtype: `bool`








   .. method:: HasClientUntypedData(self)

      Returns ``True``, if untyped data ( ``void*`` ) is associated with the items of the control.                   

      :rtype: `bool`








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



      |overload| Overloaded Implementations:

      **~~~**

      
      **Insert** `(self, item, pos)`
      
      Inserts item into the control.                  
      
      
      
      
      :param `item`: String to add.   
      :type `item`: string
      :param `pos`: Position to insert item before, zero based.  
      :type `pos`: int
      
      
      
      
      
      
      
      
      :rtype: `int`
      
      
      
                        
      
      
      
      :returns: 
      
         The return value is the index of the newly inserted item. If the insertion failed for some reason, -1 is returned.   
      
      
      
      
      
      
      
      **~~~**

      
      **Insert** `(self, item, pos, clientData)`
      
      Inserts item into the control.                  
      
      
      
      
      :param `item`: String to add.   
      :type `item`: string
      :param `pos`: Position to insert item before, zero based.   
      :type `pos`: int
      :param `clientData`: Pointer to client data to associate with the new item.  
      :type `clientData`: ClientData
      
      
      
      
      
      
      
      
      
      
      :rtype: `int`
      
      
      
                        
      
      
      
      :returns: 
      
         The return value is the index of the newly inserted item. If the insertion failed for some reason, -1 is returned.   
      
      
      
      
      
      
      
      **~~~**

      
      **Insert** `(self, items, pos)`
      
      Inserts several items at once into the control.                  
      
      Notice that calling this method is usually much faster than inserting them one by one if you need to insert a lot of items. 
      
      
      
      
      :param `items`: Array of strings to insert.   
      :type `items`: list of strings
      :param `pos`: Position to insert the items before, zero based.   
      :type `pos`: int
      
      
      
      
      
      
      
      
      :rtype: `int`
      
      
      
                        
      
      
      
      :returns: 
      
         The return value is the index of the last inserted item. If the insertion failed for some reason, -1 is returned.   
      
      
      
      
      
      
      
      **~~~**






   .. method:: Set(self, items)

      Replaces the current control contents with the given items.                  

      Notice that calling this method is usually much faster than appending them one by one if you need to add a lot of items. 




      :param `items`: Array of strings to insert.   
      :type `items`: list of strings




                  





   .. method:: SetClientData(self, n, data)

      Associates the given typed client data pointer with the given item: the `data`  object will be deleted when the item is deleted (either explicitly by using :meth:`Delete`   or implicitly when the control itself is destroyed).                  

      Note that it is an error to call this function if any untyped client data pointers had been associated with the control items before. 




      :param `n`: The zero-based item index.   
      :type `n`: int
      :param `data`: The client data to associate with the item.   
      :type `data`: ClientData






                  





   .. method:: SetClientObject(self, n, data)

      Alias for :meth:`SetClientData`



   .. method:: SetItems(self, items)




   .. attribute:: Items

      See :meth:`~wx.ItemContainer.GetItems` and :meth:`~wx.ItemContainer.SetItems`