.. 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.adv.OwnerDrawnComboBox:
==========================================================================================================================================
|phoenix_title| **wx.adv.OwnerDrawnComboBox**
==========================================================================================================================================
:ref:`wx.adv.OwnerDrawnComboBox` is a combobox with owner-drawn list items.
In essence, it is a :ref:`wx.ComboCtrl` with :ref:`wx.VListBox` popup and :ref:`wx.ControlWithItems` interface.
Implementing item drawing and measuring is similar to :ref:`wx.VListBox`. Application needs to subclass :ref:`wx.adv.OwnerDrawnComboBox` and implement :meth:`~wx.adv.OwnerDrawnComboBox.OnDrawItem`, :meth:`~wx.adv.OwnerDrawnComboBox.OnMeasureItem` and :meth:`~wx.adv.OwnerDrawnComboBox.OnMeasureItemWidth`.
.. _OwnerDrawnComboBox-styles:
|styles| Window Styles
================================
This class supports the following styles:
- ``wx.adv.ODCB_DCLICK_CYCLES``: Double-clicking cycles item if ``wx.CB_READONLY`` is also used. Synonymous with ``wx.CC_SPECIAL_DCLICK``.
- ``wx.adv.ODCB_STD_CONTROL_PAINT``: Control itself is not custom painted using OnDrawItem. Even if this style is not used, writable :ref:`wx.adv.OwnerDrawnComboBox` is never custom painted unless :meth:`~wx.ComboCtrl.SetCustomPaintWidth` is called.
.. _OwnerDrawnComboBox-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. Note that calling :meth:`~wx.ComboCtrl.GetValue` returns the new value of selection.
.. seealso:: :ref:`wx.ComboCtrl` window styles and :ref:`Window Styles <window styles>`.
.. seealso:: Events emitted by :ref:`wx.ComboCtrl`.
.. seealso:: :ref:`wx.ComboCtrl`, :ref:`wx.ComboBox`, :ref:`wx.VListBox`, :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>OwnerDrawnComboBox</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.OwnerDrawnComboBox_inheritance.png" alt="Inheritance diagram of OwnerDrawnComboBox" 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.OwnerDrawnComboBox.html" title="wx.adv.OwnerDrawnComboBox is a combobox with owner-drawn list items." alt="" coords="195,392,429,421"/> <area shape="rect" id="node2" href="wx.ComboCtrl.html" title="A combo control is a generic combobox that allows totally custom popup." alt="" coords="178,315,294,344"/> <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="334,315,474,344"/> <area shape="rect" id="node4" href="wx.Control.html" title="This is the base class for a control or 'widget'." alt="" coords="64,237,157,267"/> <area shape="rect" id="node5" href="wx.TextEntry.html" title="Common base class for single line text entry fields." alt="" coords="181,237,291,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="62,160,159,189"/> <area shape="rect" id="node7" href="wx.EvtHandler.html" title="A class that can handle events from the windowing system." alt="" coords="51,83,170,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,93,35"/> <area shape="rect" id="node9" href="wx.Trackable.html" title="Add-on base class for a trackable object." alt="" coords="118,5,229,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="315,237,527,267"/> </map>
</p>
</div>
|
|appearance| Control Appearance
===============================
|
.. figure:: _static/images/widgets/fullsize/wxmsw/wx.adv.ownerdrawncombobox.png
:alt: wxMSW
:figclass: floatleft
**wxMSW**
.. figure:: _static/images/widgets/fullsize/wxmac/wx.adv.ownerdrawncombobox.png
:alt: wxMAC
:figclass: floatright
**wxMAC**
.. figure:: _static/images/widgets/fullsize/wxgtk/wx.adv.ownerdrawncombobox.png
:alt: wxGTK
:figclass: floatcenter
**wxGTK**
|
|method_summary| Methods Summary
================================
================================================================================ ================================================================================
:meth:`~wx.adv.OwnerDrawnComboBox.__init__` Default constructor.
:meth:`~wx.adv.OwnerDrawnComboBox.Create` Creates the combobox for two-step construction.
:meth:`~wx.adv.OwnerDrawnComboBox.GetClassDefaultAttributes`
:meth:`~wx.adv.OwnerDrawnComboBox.GetWidestItem` Returns index to the widest item in the list.
:meth:`~wx.adv.OwnerDrawnComboBox.GetWidestItemWidth` Returns width of the widest item in the list.
:meth:`~wx.adv.OwnerDrawnComboBox.OnDrawBackground` This method is used to draw the items background and, maybe, a border around it.
:meth:`~wx.adv.OwnerDrawnComboBox.OnDrawItem` The derived class may implement this function to actually draw the item with the given index on the provided DC.
:meth:`~wx.adv.OwnerDrawnComboBox.OnMeasureItem` The derived class may implement this method to return the height of the specified item (in pixels).
:meth:`~wx.adv.OwnerDrawnComboBox.OnMeasureItemWidth` The derived class may implement this method to return the width of the specified item (in pixels).
================================================================================ ================================================================================
|
|property_summary| Properties Summary
=====================================
================================================================================ ================================================================================
:attr:`~wx.adv.OwnerDrawnComboBox.WidestItem` See :meth:`~wx.adv.OwnerDrawnComboBox.GetWidestItem`
:attr:`~wx.adv.OwnerDrawnComboBox.WidestItemWidth` See :meth:`~wx.adv.OwnerDrawnComboBox.GetWidestItemWidth`
================================================================================ ================================================================================
|
|api| Class API
===============
.. class:: wx.adv.OwnerDrawnComboBox(ComboCtrl, ItemContainer)
**Possible constructors**::
OwnerDrawnComboBox()
OwnerDrawnComboBox(parent, id=ID_ANY, value="", pos=DefaultPosition,
size=DefaultSize, choices=[], style=0, validator=DefaultValidator,
name="comboBox")
OwnerDrawnComboBox is a combobox with owner-drawn 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="", pos=DefaultPosition, size=DefaultSize, choices=[], style=0, validator=DefaultValidator, name="comboBox")`
Constructor, creating and showing a owner-drawn combobox.
:param `parent`: Parent window. Must not be ``None``.
:type `parent`: wx.Window
:param `id`: Window identifier. The value ``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`: Window position.
:type `pos`: wx.Point
:param `size`: Window size. If `wx.DefaultSize` is specified then the window is sized appropriately.
:type `size`: wx.Size
:param `choices`: An array of strings with which to initialise the control.
:type `choices`: list of strings
:param `style`: Window style. See :ref:`wx.adv.OwnerDrawnComboBox`.
:type `style`: long
:param `validator`: Window validator.
:type `validator`: wx.Validator
:param `name`: Window name.
:type `name`: string
.. seealso:: :meth:`Create` , :ref:`wx.Validator`
:html:`<hr class="overloadsep" /><br />`
.. method:: Create(self, parent, id=ID_ANY, value="", pos=DefaultPosition, size=DefaultSize, choices=[], style=0, validator=DefaultValidator, name=ComboBoxNameStr)
Creates the combobox for two-step construction.
See :ref:`wx.adv.OwnerDrawnComboBox` for further details.
: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`
.. note::
Derived classes should call or replace this function.
.. staticmethod:: GetClassDefaultAttributes(variant=WINDOW_VARIANT_NORMAL)
:param `variant`:
:type `variant`: wx.WindowVariant
:rtype: `VisualAttributes`
.. method:: GetWidestItem(self)
Returns index to the widest item in the list.
:rtype: `int`
.. method:: GetWidestItemWidth(self)
Returns width of the widest item in the list.
:rtype: `int`
.. method:: OnDrawBackground(self, dc, rect, item, flags)
This method is used to draw the items background and, maybe, a border around it.
The base class version implements a reasonable default behaviour which consists in drawing the selected item with the standard background colour and drawing a border around the item if it is either selected or current.
:param `dc`:
:type `dc`: wx.DC
:param `rect`:
:type `rect`: wx.Rect
:param `item`:
:type `item`: int
:param `flags`:
:type `flags`: int
.. note::
flags has the same meaning as with :meth:`OnDrawItem` .
.. method:: OnDrawItem(self, dc, rect, item, flags)
The derived class may implement this function to actually draw the item with the given index on the provided DC.
If function is not implemented, the item text is simply drawn, as if the control was a normal combobox.
:param `dc`: The device context to use for drawing
:type `dc`: wx.DC
:param `rect`: The bounding rectangle for the item being drawn (DC clipping region is set to this rectangle before calling this function)
:type `rect`: wx.Rect
:param `item`: The index of the item to be drawn
:type `item`: int
:param `flags`: A combination of the :ref:`wx.adv.OwnerDrawnComboBoxPaintingFlags` enumeration values.
:type `flags`: int
.. method:: OnMeasureItem(self, item)
The derived class may implement this method to return the height of the specified item (in pixels).
The default implementation returns text height, as if this control was a normal combobox.
:param `item`:
:type `item`: int
:rtype: `wx.Coord`
.. method:: OnMeasureItemWidth(self, item)
The derived class may implement this method to return the width of the specified item (in pixels).
If -1 is returned, then the item text width is used.
The default implementation returns -1.
:param `item`:
:type `item`: int
:rtype: `wx.Coord`
.. attribute:: WidestItem
See :meth:`~wx.adv.OwnerDrawnComboBox.GetWidestItem`
.. attribute:: WidestItemWidth
See :meth:`~wx.adv.OwnerDrawnComboBox.GetWidestItemWidth`