.. module:: combo

=================
Module `wx.combo`
=================

`ComboCtrl` class that can have any type of popup widget, and also an owner-drawn combobox control.


Usage
=====

The following example shows a simple implementation that utilizes `wx.combo.ComboCtrl <wx.combo.ComboCtrl.html>`_::

    class ListCtrlComboPopup(wx.ListCtrl, wx.combo.ComboPopup):

        def __init__(self):
        
            # Since we are using multiple inheritance, and don't know yet
            # which window is to be the parent, we'll do 2-phase create of
            # the ListCtrl instead, and call its Create method later in
            # our Create method.  (See Create below.)
            self.PostCreate(wx.PreListCtrl())

            # Also init the ComboPopup base class.
            wx.combo.ComboPopup.__init__(self)


        def AddItem(self, txt):

            self.InsertStringItem(self.GetItemCount(), txt)


        def OnMotion(self, evt):

            item, flags = self.HitTest(evt.GetPosition())
            if item >= 0:
                self.Select(item)
                self.curitem = item


        def OnLeftDown(self, evt):

            self.value = self.curitem
            self.Dismiss()


        # The following methods are those that are overridable from the
        # ComboPopup base class.

        def Init(self):
            """ This is called immediately after construction finishes.  You can
            use self.GetCombo if needed to get to the ComboCtrl instance. """

            self.value = -1
            self.curitem = -1


        def Create(self, parent):
            """ Create the popup child control. Return True for success. """

            wx.ListCtrl.Create(self, parent,
                               style=wx.LC_LIST|wx.LC_SINGLE_SEL|wx.SIMPLE_BORDER)
            self.Bind(wx.EVT_MOTION, self.OnMotion)
            self.Bind(wx.EVT_LEFT_DOWN, self.OnLeftDown)

            return True


        def GetControl(self):
            """ Return the widget that is to be used for the popup. """

            return self

        def SetStringValue(self, val):
            """ Called just prior to displaying the popup, you can use it to
            'select' the current item. """

            idx = self.FindItem(-1, val)

            if idx != wx.NOT_FOUND:
                self.Select(idx)

    
        def GetStringValue(self):
            """ Return a string representation of the current item. """

            if self.value >= 0:
                return self.GetItemText(self.value)

            return ""

    
        def OnPopup(self):
            """ Called immediately after the popup is shown. """

            wx.combo.ComboPopup.OnPopup(self)


        def OnDismiss(self):
            " Called when popup is dismissed. """

            wx.combo.ComboPopup.OnDismiss(self)


|

Here's how you would create and populate it in a dialog/frame constructor::

    cc = wx.combo.ComboCtrl(self, style=0, size=(250,-1))
        
    # Create a Popup
    popup = ListCtrlComboPopup()

    # Associate them with each other.  This also triggers the
    # creation of the ListCtrl.
    cc.SetPopupControl(popup)

    # Add some items to the listctrl.
    for x in range(75):
        popup.AddItem("Item-%02d" % x)


|


Module API
==========

Widgets
^^^^^^^

.. toctree::
   :maxdepth: 1
   :glob:
 
   wx.combo.*