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

==========================================================================================================================================
|phoenix_title|  **wx.RearrangeList**
==========================================================================================================================================

A listbox-like control allowing the user to rearrange the items and to enable or disable them.          

This class allows changing the order of the items shown in it as well as checking or unchecking them individually. The data structure used to allow this is the order array which contains the items indices indexed by their position with an added twist that the unchecked items are represented by the bitwise complement of the corresponding index (for any architecture using two's complement for negative numbers representation (i.e. just about any at all) this means that a checked item N is represented by ``-N-1`` in unchecked state). In practice this means that you must apply the C bitwise complement operator when constructing the order array, e.g. ::

            order = [0]  # checked item #0



So, for example, the array order ``[1`` -3 ``0]`` used in conjunction with the items array ["first", "second", "third"] means that the items order is "second", "third", "first" and the "third" item is unchecked while the other two are checked. 

This convention is used both for the order argument of the control constructor or :meth:`~wx.RearrangeList.Create`  and for the array returned from :meth:`~wx.RearrangeList.GetCurrentOrder`. 

Usually this control will be used together with other controls allowing to move the items around in it interactively. The simplest possible solution is to use :ref:`wx.RearrangeCtrl`  which combines it with two standard buttons to move the current item up or down. 

Note that while most of the methods for items manipulation such as :meth:`~wx.RearrangeList.Append`, :meth:`~wx.RearrangeList.Insert`  or :meth:`~wx.RearrangeList.Delete`, inherited from :ref:`wx.ItemContainer`  work as expected for this class, :meth:`~wx.RearrangeList.Set`  somewhat unexpectedly resets the order of the items as it clears the control first, also clearing the order as a side effect, before adding the new items. 







.. versionadded:: 2.9.0 
    







|

|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>RearrangeList</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.RearrangeList_inheritance.png" alt="Inheritance diagram of RearrangeList" 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.RearrangeList.html" title="A listbox-like control allowing the user to rearrange the items and to enable or disable them." alt="" coords="125,469,256,499"/> <area shape="rect" id="node2" href="wx.CheckListBox.html" title="A wx.CheckListBox  is like a wx.ListBox, but allows items to be checked or unchecked." alt="" coords="127,392,254,421"/> <area shape="rect" id="node3" 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="node4" 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="node5" 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="node6" 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="node7" 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="node8" 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="node9" href="wx.Trackable.html" title="Add-on base class for a trackable object." alt="" coords="113,5,215,35"/> <area shape="rect" id="node10" 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>

|


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

================================================================================ ================================================================================
:meth:`~wx.RearrangeList.__init__`                                               Default constructor.
:meth:`~wx.RearrangeList.CanMoveCurrentDown`                                     Return ``True`` if the currently selected item can be moved down.
:meth:`~wx.RearrangeList.CanMoveCurrentUp`                                       Return ``True`` if the currently selected item can be moved up.
:meth:`~wx.RearrangeList.Create`                                                 Effectively creates the window for an object created using the default constructor.
:meth:`~wx.RearrangeList.GetClassDefaultAttributes`                              
:meth:`~wx.RearrangeList.GetCurrentOrder`                                        Return the current order of the items.
:meth:`~wx.RearrangeList.MoveCurrentDown`                                        Move the currently selected item one position below.
:meth:`~wx.RearrangeList.MoveCurrentUp`                                          Move the currently selected item one position above.
================================================================================ ================================================================================


|


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

================================================================================ ================================================================================
:attr:`~wx.RearrangeList.CurrentOrder`                                           See :meth:`~wx.RearrangeList.GetCurrentOrder`
================================================================================ ================================================================================


|


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


.. class:: wx.RearrangeList(CheckListBox)

   **Possible constructors**::

       RearrangeList()
       
       RearrangeList(parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize,
                     order=[], items=[], style=0, validator=DefaultValidator,
                     name=RearrangeListNameStr)
       
   
   A listbox-like control allowing the user to rearrange the items and to
   enable or disable them.



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



      |overload| Overloaded Implementations:

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

      
      **__init__** `(self)`
      
      Default constructor.                  
      
      :meth:`Create`   must be called later to effectively create the control.                   
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, order=[], items=[], style=0, validator=DefaultValidator, name=RearrangeListNameStr)`
      
      Constructor really creating the control.                  
      
      Please see :meth:`Create`   for the parameters description.                  
      
      
      :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 `order`: 
      :type `order`: list of integers
      :param `items`: 
      :type `items`: list of strings
      :param `style`: 
      :type `style`: long
      :param `validator`: 
      :type `validator`: wx.Validator
      :param `name`: 
      :type `name`: string
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. method:: CanMoveCurrentDown(self)

      Return ``True`` if the currently selected item can be moved down.                  

                

      :rtype: `bool`







      .. seealso:: :meth:`CanMoveCurrentUp`     








   .. method:: CanMoveCurrentUp(self)

      Return ``True`` if the currently selected item can be moved up.                  

      This function is useful for ``EVT_UPDATE_UI`` handler for the standard "Up" button often used together with this control and :ref:`wx.RearrangeCtrl`  uses it in this way. 

                

      :rtype: `bool`







      :returns: 

         ``True`` if the currently selected item can be moved up in the listbox, ``False`` if there is no selection or the current item is the first one.  







      .. seealso:: :meth:`CanMoveCurrentDown`     








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

      Effectively creates the window for an object created using the default constructor.                  

      This function is very similar to :meth:`wx.CheckListBox.Create`   except that it has an additional parameter specifying the initial order of the items. Please see the class documentation for the explanation of the conventions used by the `order`  argument. 




      :param `parent`: The parent window, must be not ``None``.   
      :type `parent`: wx.Window
      :param `id`: The window identifier.   
      :type `id`: wx.WindowID
      :param `pos`: The initial window position.   
      :type `pos`: wx.Point
      :param `size`: The initial window size.   
      :type `size`: wx.Size
      :param `order`: Array specifying the initial order of the items in  `items`  array.   
      :type `order`: list of integers
      :param `items`: The items to display in the list.   
      :type `items`: list of strings
      :param `style`: The control style, there are no special styles for this class but the base class styles can be used here.   
      :type `style`: long
      :param `validator`: Optional window validator.   
      :type `validator`: wx.Validator
      :param `name`: Optional window name.   
      :type `name`: string






















      :rtype: `bool`



                  





   .. staticmethod:: GetClassDefaultAttributes(variant=WINDOW_VARIANT_NORMAL)




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




      :rtype: :ref:`wx.VisualAttributes`








   .. method:: GetCurrentOrder(self)

      Return the current order of the items.                  

      The order may be different from the one passed to the constructor if :meth:`MoveCurrentUp`   or :meth:`MoveCurrentDown`   were called.                  

      :rtype: `list of integers`








   .. method:: MoveCurrentDown(self)

      Move the currently selected item one position below.                  

                

      :rtype: `bool`







      .. seealso:: :meth:`MoveCurrentUp`     








   .. method:: MoveCurrentUp(self)

      Move the currently selected item one position above.                  

      This method is useful to implement the standard "Up" button behaviour and :ref:`wx.RearrangeCtrl`  uses it for this. 

                

      :rtype: `bool`







      :returns: 

         ``True`` if the item was moved or ``False`` if this couldn't be done.  







      .. seealso:: :meth:`MoveCurrentDown`     








   .. attribute:: CurrentOrder

      See :meth:`~wx.RearrangeList.GetCurrentOrder`