[ 1495657 ] Documentation for wxComboCtrl and wxOwnerDrawnComboBox.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@39731 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/category.tex

@@ -94,6 +94,7 @@ that are not static can have \helpref{validators}{wxvalidator} associated with t
 \twocolitem{\helpref{wxCheckListBox}{wxchecklistbox}}{A listbox with a checkbox to the left of each item}
 \twocolitem{\helpref{wxChoice}{wxchoice}}{Choice control (a combobox without the editable area)}
 \twocolitem{\helpref{wxComboBox}{wxcombobox}}{A choice with an editable area}
+\twocolitem{\helpref{wxComboCtrl}{wxcomboctrl}}{A combobox with application defined popup}
 \twocolitem{\helpref{wxGauge}{wxgauge}}{A control to represent a varying quantity, such as time remaining}
 \twocolitem{\helpref{wxGenericDirCtrl}{wxgenericdirctrl}}{A control for displaying a directory tree}
 \twocolitem{\helpref{wxHtmlListBox}{wxhtmllistbox}}{A listbox showing HTML content}
@@ -101,6 +102,7 @@ that are not static can have \helpref{validators}{wxvalidator} associated with t
 \twocolitem{\helpref{wxListBox}{wxlistbox}}{A list of strings for single or multiple selection}
 \twocolitem{\helpref{wxListCtrl}{wxlistctrl}}{A control for displaying lists of strings and/or icons, plus a multicolumn report view}
 \twocolitem{\helpref{wxListView}{wxlistview}}{A simpler interface ({\it fa\c{c}ade} for wxListCtrl in report mode}
+\twocolitem{\helpref{wxOwnerDrawnComboBox}{wxownerdrawncombobox}}{A combobox with owner-drawn list items}
 \twocolitem{\helpref{wxTextCtrl}{wxtextctrl}}{Single or multiline text editing control}
 \twocolitem{\helpref{wxTreeCtrl}{wxtreectrl}}{Tree (hierarchy) control}
 \twocolitem{\helpref{wxScrollBar}{wxscrollbar}}{Scrollbar control}

docs/latex/wx/classes.tex

@@ -46,6 +46,8 @@
 \input colour.tex
 \input colordlg.tex
 \input combobox.tex
+\input comboctrl.tex
+\input combopopup.tex
 \input command.tex
 \input cmdevent.tex
 \input cmdproc.tex
@@ -249,6 +251,7 @@
 \input nbsizer.tex
 \input notifevt.tex
 \input object.tex
+\input odcbox.tex
 \input outptstr.tex
 \input pagedlg.tex
 \input paintdc.tex

docs/latex/wx/comboctrl.tex

@@ -0,0 +1,628 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        comboctrl.tex
+%% Purpose:     wxComboCtrl docs
+%% Author:      Jaakko Salli
+%% Modified by:
+%% Created:
+%% RCS-ID:      $Id$
+%% Copyright:   (c) Jaakko Salli
+%% License:     wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxComboCtrl}}\label{wxcomboctrl}
+
+A combo control is a generic combobox that allows totally
+custom popup. In addition it has other customization features.
+For instance, position and size of the dropdown button
+can be changed.
+
+\wxheading{Setting Custom Popup for wxComboCtrl}
+
+wxComboCtrl needs to be told somehow which control to use
+and this is done by SetPopupControl(). However, we need
+something more than just a wxControl in this method as,
+for example, we need to call SetStringValue("initial text value")
+and wxControl doesn't have such method. So we also need a
+\helpref{wxComboPopup}{wxcombopopup} which is an interface which
+must be implemented by a control to be usable as a popup.
+
+We couldn't derive wxComboPopup from wxControl as this would make it
+impossible to have a class deriving from a wxWidgets control and from
+it, so instead it is just a mix-in.
+
+Here's a minimal sample of \helpref{wxListView}{wxlistview} popup:
+
+\begin{verbatim}
+
+#include <wx/combo.h>
+#include <wx/listctrl.h>
+
+class wxListViewComboPopup : public wxListView,
+                             public wxComboPopup
+{
+public:
+
+    // Initialize member variables
+    virtual void Init()
+    {
+        m_value = -1;
+    }
+
+    // Create popup control
+    virtual bool Create(wxWindow* parent)
+    {
+        return wxListView::Create(parent,1,wxPoint(0,0),wxDefaultSize);
+    }
+
+    // Return pointer to the created control
+    virtual wxWindow *GetControl() { return this; }
+
+    // Translate string into a list selection
+    virtual void SetStringValue(const wxString& s)
+    {
+        int n = wxListView::FindItem(-1,s);
+        if ( n >= 0 && n < wxListView::GetItemCount() )
+            wxListView::Select(n);
+    }
+
+    // Get list selection as a string
+    virtual wxString GetStringValue() const
+    {
+        if ( m_value >= 0 )
+            return wxListView::GetItemText(m_value);
+        return wxEmptyString;
+    }
+
+    // Do mouse hot-tracking (which is typical in list popups)
+    void OnMouseMove(wxMouseEvent& event)
+    {
+        // TODO: Move selection to cursor
+    }
+
+    // On mouse left up, set the value and close the popup
+    void OnMouseClick(wxMouseEvent& WXUNUSED(event))
+    {
+        m_value = wxListView::GetFirstSelected();
+
+        // TODO: Send event as well
+
+        Dismiss();
+    }
+
+protected:
+
+    int             m_value; // current item index
+
+private:
+    DECLARE_EVENT_TABLE()
+};
+
+BEGIN_EVENT_TABLE(wxListViewComboPopup, wxListView)
+    EVT_MOTION(wxListViewComboPopup::OnMouseMove)
+    EVT_LEFT_UP(wxListViewComboPopup::OnMouseClick)
+END_EVENT_TABLE()
+
+\end{verbatim}
+
+Here's how you would create and populate it in a dialog constructor:
+
+\begin{verbatim}
+
+    wxComboCtrl* comboCtrl = new wxComboCtrl(this,wxID_ANY,wxEmptyString);
+
+    wxListViewComboPopup* popupCtrl = new wxListViewComboPopup();
+
+    comboCtrl->SetPopupControl(popupCtrl);
+
+    // Populate using wxListView methods
+    popupCtrl->InsertItem(popupCtrl->GetItemCount(),wxT("First Item"));
+    popupCtrl->InsertItem(popupCtrl->GetItemCount(),wxT("Second Item"));
+    popupCtrl->InsertItem(popupCtrl->GetItemCount(),wxT("Third Item"));
+
+\end{verbatim}
+
+\wxheading{Derived from}
+
+\helpref{wxControl}{wxcontrol}\\
+\helpref{wxWindow}{wxwindow}\\
+\helpref{wxEvtHandler}{wxevthandler}\\
+\helpref{wxObject}{wxobject}
+
+\wxheading{Include files}
+
+<combo.h>
+
+\wxheading{Window styles}
+
+\begin{twocollist}\itemsep=0pt
+\twocolitem{\windowstyle{wxCB\_READONLY}}{Text will not be editable.}
+\twocolitem{\windowstyle{wxCB\_SORT}}{Sorts the entries in the list alphabetically.}
+\twocolitem{\windowstyle{wxPROCESS\_ENTER}}{The control will generate
+the event wxEVT\_COMMAND\_TEXT\_ENTER (otherwise pressing Enter key
+is either processed internally by the control or used for navigation between
+dialog controls). Windows only.}
+\twocolitem{\windowstyle{wxCC\_SPECIAL\_DCLICK}}{Double-clicking triggers a call
+to popup's OnComboDoubleClick. Actual behaviour is defined by a derived
+class. For instance, wxOwnerDrawnComboBox will cycle an item. This style only
+applies if wxCB\_READONLY is used as well.}
+\twocolitem{\windowstyle{wxCC\_ALT\_KEYS}}{Use keyboard behaviour alternate
+to platform default: up and down keys will show popup (instead of cycling value,
+for instance, on wxMSW).}
+\twocolitem{\windowstyle{wxCC\_STD\_BUTTON}}{Drop button will behave
+more like a standard push button.}
+\end{twocollist}
+
+See also \helpref{window styles overview}{windowstyles}.
+
+\wxheading{Event handling}
+
+\twocolwidtha{7cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf EVT\_TEXT(id, func)}}{Process a wxEVT\_COMMAND\_TEXT\_UPDATED event,
+when the text changes.}
+\twocolitem{{\bf EVT\_TEXT\_ENTER(id, func)}}{Process a wxEVT\_COMMAND\_TEXT\_ENTER event,
+when <RETURN> is pressed in the combo control.}
+\end{twocollist}
+
+\wxheading{See also}
+
+\helpref{wxComboBox}{wxcombobox}, \helpref{wxChoice}{wxchoice},
+\helpref{wxOwnerDrawnComboBox}{wxownerdrawncombobox},
+\rtfsp\helpref{wxComboPopup}{wxcombopopup}, \helpref{wxCommandEvent}{wxcommandevent}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+
+\membersection{wxComboCtrl::wxComboCtrl}\label{wxcomboctrlctor}
+
+\func{}{wxComboCtrl}{\void}
+
+Default constructor.
+
+\func{}{wxComboCtrl}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
+\param{const wxString\& }{value = ``"}, \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
+\param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboCtrl"}}
+
+Constructor, creating and showing a combo control.
+
+\wxheading{Parameters}
+
+\docparam{parent}{Parent window. Must not be NULL.}
+
+\docparam{id}{Window identifier. A value of -1 indicates a default value.}
+
+\docparam{value}{Initial selection string. An empty string indicates no selection.}
+
+\docparam{pos}{Window position.}
+
+\docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized
+appropriately.}
+
+\docparam{style}{Window style. See \helpref{wxComboCtrl}{wxcomboctrl}.}
+
+\docparam{validator}{Window validator.}
+
+\docparam{name}{Window name.}
+
+\wxheading{See also}
+
+\helpref{wxComboCtrl::Create}{wxcomboctrlcreate}, \helpref{wxValidator}{wxvalidator}
+
+
+\membersection{wxComboCtrl::\destruct{wxComboCtrl}}\label{wxcomboctrldtor}
+
+\func{}{\destruct{wxComboCtrl}}{\void}
+
+Destructor, destroying the combo control.
+
+
+\membersection{wxComboCtrl::Create}\label{wxcomboctrlcreate}
+
+\func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
+\param{const wxString\& }{value = ``"}, \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
+\param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboCtrl"}}
+
+Creates the combo control for two-step construction. Derived classes
+should call or replace this function. See \helpref{wxComboCtrl::wxComboCtrl}{wxcomboctrlctor}\rtfsp
+for further details.
+
+
+\membersection{wxComboCtrl::Copy}\label{wxcomboctrlcopy}
+
+\func{void}{Copy}{\void}
+
+Copies the selected text to the clipboard.
+
+
+\membersection{wxComboCtrl::Cut}\label{wxcomboctrlcut}
+
+\func{void}{Cut}{\void}
+
+Copies the selected text to the clipboard and removes the selection.
+
+
+\membersection{wxComboCtrl::GetBitmapDisabled}\label{wxcomboctrlgetbitmapdisabled}
+
+\constfunc{const wxBitmap\&}{GetBitmapDisabled}{\void}
+
+Returns disabled button bitmap that has been set with
+\helpref{SetButtonBitmaps}{wxcomboctrlsetbuttonbitmaps}.
+
+\wxheading{Return value}
+
+A reference to the disabled state bitmap.
+
+
+\membersection{wxComboCtrl::GetBitmapHover}\label{wxcomboctrlgetbitmaphover}
+
+\constfunc{const wxBitmap\&}{GetBitmapHover}{\void}
+
+Returns button mouse hover bitmap that has been set with
+\helpref{SetButtonBitmaps}{wxcomboctrlsetbuttonbitmaps}.
+
+\wxheading{Return value}
+
+A reference to the mouse hover state bitmap.
+
+
+\membersection{wxComboCtrl::GetBitmapNormal}\label{wxcomboctrlgetbitmapnormal}
+
+\constfunc{const wxBitmap\&}{GetBitmapNormal}{\void}
+
+Returns default button bitmap that has been set with
+\helpref{SetButtonBitmaps}{wxcomboctrlsetbuttonbitmaps}.
+
+\wxheading{Return value}
+
+A reference to the normal state bitmap.
+
+
+\membersection{wxComboCtrl::GetBitmapPressed}\label{wxcomboctrlgetbitmappressed}
+
+\constfunc{const wxBitmap\&}{GetBitmapPressed}{\void}
+
+Returns depressed button bitmap that has been set with
+\helpref{SetButtonBitmaps}{wxcomboctrlsetbuttonbitmaps}.
+
+\wxheading{Return value}
+
+A reference to the depressed state bitmap.
+
+
+\membersection{wxComboCtrl::GetCustomPaintWidth}\label{wxcomboctrlgetcustompaintwidth}
+
+\constfunc{int}{GetCustomPaintWidth}{\void}
+
+Returns custom painted area in control.
+
+\wxheading{See also}
+
+\helpref{wxComboCtrl::SetCustomPaintWidth}{wxcomboctrlsetcustompaintwidth}.
+
+
+\membersection{wxComboCtrl::GetFeatures}\label{wxcomboctrlgetfeatures}
+
+\func{static int}{GetFeatures}{\void}
+
+Returns features supported by wxComboCtrl. If needed feature is missing,
+you need to instead use wxGenericComboCtrl, which however may lack
+native look and feel (but otherwise sports identical API).
+
+\wxheading{Return value}
+
+Value returned is a combination of following flags:
+
+\twocolwidtha{8cm}%
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\tt wxComboCtrlFeatures::MovableButton}}{Button can
+be on either side of the control.}
+\twocolitem{{\tt wxComboCtrlFeatures::BitmapButton}}{Button may
+be replaced with bitmap.}
+\twocolitem{{\tt wxComboCtrlFeatures::ButtonSpacing}}{Button can
+have spacing.}
+\twocolitem{{\tt wxComboCtrlFeatures::TextIndent}}{SetTextIndent
+works.}
+\twocolitem{{\tt wxComboCtrlFeatures::PaintControl}}{Combo control
+itself can be custom painted.}
+\twocolitem{{\tt wxComboCtrlFeatures::PaintWritable}}{A variable-
+width area in front of writable combo control's textctrl can
+be custom painted.}
+\twocolitem{{\tt wxComboCtrlFeatures::Borderless}}{wxNO\_BORDER
+window style works.}
+\twocolitem{{\tt wxComboCtrlFeatures::All}}{All of the
+above.}
+\end{twocollist}
+
+
+\membersection{wxComboCtrl::GetInsertionPoint}\label{wxcomboctrlgetinsertionpoint}
+
+\constfunc{long}{GetInsertionPoint}{\void}
+
+Returns the insertion point for the combo control's text field.
+
+\textbf{Note:} Under wxMSW, this function always returns $0$ if the combo control
+doesn't have the focus.
+
+
+\membersection{wxComboCtrl::GetLastPosition}\label{wxcomboctrlgetlastposition}
+
+\constfunc{long}{GetLastPosition}{\void}
+
+Returns the last position in the combo control text field.
+
+
+\membersection{wxComboCtrl::GetPopupControl}\label{wxcomboctrlgetpopupcontrol}
+
+\func{wxComboPopup*}{GetPopupControl}{\void}
+
+Returns current popup interface that has been set with SetPopupControl.
+
+
+\membersection{wxComboCtrl::GetPopupWindow}\label{wxcomboctrlgetpopupwindow}
+
+\constfunc{wxWindow*}{GetPopupWindow}{\void}
+
+Returns popup window containing the popup control.
+
+
+\membersection{wxComboCtrl::GetTextCtrl}\label{wxcomboctrlgettextctrl}
+
+\constfunc{wxTextCtrl*}{GetTextCtrl}{\void}
+
+Get the text control which is part of the combo control.
+
+
+\membersection{wxComboCtrl::GetTextIndent}\label{wxcomboctrlgettextindent}
+
+\constfunc{wxCoord}{GetTextIndent}{\void}
+
+Returns actual indentation in pixels.
+
+
+\membersection{wxComboCtrl::GetValue}\label{wxcomboctrlgetvalue}
+
+\constfunc{wxString}{GetValue}{\void}
+
+Returns text representation of the current value. For writable
+combo control it always returns the value in the text field.
+
+
+\membersection{wxComboCtrl::HidePopup}\label{wxcomboctrlhidepopup}
+
+\func{void}{HidePopup}{\void}
+
+Dismisses the popup window.
+
+
+\membersection{wxComboCtrl::IsPopupShown}\label{wxcomboctrlispopupshown}
+
+\constfunc{bool}{IsPopupShown}{\void}
+
+Returns \true if the popup is currently shown
+
+
+\membersection{wxComboCtrl::OnButtonClick}\label{wxcomboctrlonbuttonclick}
+
+\func{void}{OnButtonClick}{\void}
+
+Implement in a derived class to define what happens on
+dropdown button click.
+
+Default action is to show the popup.
+
+
+\membersection{wxComboCtrl::Paste}\label{wxcomboctrlpaste}
+
+\func{void}{Paste}{\void}
+
+Pastes text from the clipboard to the text field.
+
+
+\membersection{wxComboCtrl::Remove}\label{wxcomboctrlremove}
+
+\func{void}{Remove}{\param{long }{from}, \param{long }{to}}
+
+Removes the text between the two positions in the combo control text field.
+
+\wxheading{Parameters}
+
+\docparam{from}{The first position.}
+
+\docparam{to}{The last position.}
+
+
+\membersection{wxComboCtrl::Replace}\label{wxcomboctrlreplace}
+
+\func{void}{Replace}{\param{long }{from}, \param{long }{to}, \param{const wxString\& }{value}}
+
+Replaces the text between two positions with the given text, in the combo control text field.
+
+\wxheading{Parameters}
+
+\docparam{from}{The first position.}
+
+\docparam{to}{The second position.}
+
+\docparam{text}{The text to insert.}
+
+
+\membersection{wxComboCtrl::SetButtonBitmaps}\label{wxcomboctrlsetbuttonbitmaps}
+
+\func{void}{SetButtonBitmaps}{\param{const wxBitmap\& }{bmpNormal}, \param{bool }{pushButtonBg = false}, \param{const wxBitmap\& }{bmpPressed = wxNullBitmap}, \param{const wxBitmap\& }{bmpHover = wxNullBitmap}, \param{const wxBitmap\& }{bmpDisabled = wxNullBitmap}}
+
+Sets custom dropdown button graphics.
+
+\wxheading{Parameters}
+
+\docparam{bmpNormal}{Default button image.}
+\docparam{pushButtonBg}{If \true, blank push button background is painted
+below the image.}
+\docparam{bmpPressed}{Depressed button image.}
+\docparam{bmpHover}{Button image when mouse hovers above it. This
+should be ignored on platforms and themes that do not generally draw
+different kind of button on mouse hover.}
+\docparam{bmpDisabled}{Disabled button image.}
+
+
+\membersection{wxComboCtrl::SetButtonPosition}\label{wxcomboctrlsetbuttonposition}
+
+\func{void}{SetButtonPosition}{\param{int }{width = 0}, \param{int }{height = 0}, \param{int }{side = wxRIGHT}, \param{int }{spacingX = 0}}
+
+Sets size and position of dropdown button.
+
+\wxheading{Parameters}
+
+\docparam{width}{If > $0$, defines specific button width. $0$ means platform default,
+while negative numbers allow adjusting smaller than default.}
+\docparam{height}{Same as width.}
+\docparam{side}{Indicates which side the button will be placed.
+Value can be {\tt wxLEFT} or {\tt wxRIGHT}.}
+\docparam{spacingX}{Horizontal spacing around the button. Default is $0$.}
+
+
+\membersection{wxComboCtrl::SetCustomPaintWidth}\label{wxcomboctrlsetcustompaintwidth}
+
+\func{void}{SetCustomPaintWidth}{\param{int }{width}}
+
+Set width, in pixels, of custom painted area in control without {\tt wxCB\_READONLY}
+style. In read-only \helpref{wxOwnerDrawnComboBox}{wxownerdrawncombobox}, this is used
+to indicate area that is not covered by the focus rectangle.
+
+
+\membersection{wxComboCtrl::SetInsertionPoint}\label{wxcomboctrlsetinsertionpoint}
+
+\func{void}{SetInsertionPoint}{\param{long }{pos}}
+
+Sets the insertion point in the text field.
+
+\wxheading{Parameters}
+
+\docparam{pos}{The new insertion point.}
+
+
+\membersection{wxComboCtrl::SetInsertionPointEnd}\label{wxcomboctrlsetinsertionpointend}
+
+\func{void}{SetInsertionPointEnd}{\void}
+
+Sets the insertion point at the end of the combo control text field.
+
+
+\membersection{wxComboCtrl::SetPopupAnchor}\label{wxcomboctrlsetpopupanchor}
+
+\func{void}{SetPopupAnchor}{\param{int }{anchorSide}}
+
+Set side of the control to which the popup will align itself. Valid values are
+{\tt wxLEFT}, {\tt wxRIGHT} and $0$. The default value $0$ means that the most appropriate
+side is used (which, currently, is always {\tt wxLEFT}).
+
+
+\membersection{wxComboCtrl::SetPopupControl}\label{wxcomboctrlsetpopupcontrol}
+
+\func{void}{SetPopupControl}{\param{wxComboPopup* }{popup}}
+
+Set popup interface class derived from wxComboPopup.
+This method should be called as soon as possible after the control
+has been created, unless \helpref{OnButtonClick}{wxcomboctrlonbuttonclick}
+has been overridden.
+
+
+\membersection{wxComboCtrl::SetPopupExtents}\label{wxcomboctrlsetpopupextents}
+
+\func{void}{SetPopupExtents}{\param{int }{extLeft}, \param{int }{extRight}}
+
+Extends popup size horizontally, relative to the edges of the combo control.
+
+\wxheading{Parameters}
+
+\docparam{extLeft}{How many pixel to extend beyond the left edge of the
+control. Default is $0$.}
+\docparam{extRight}{How many pixel to extend beyond the right edge of the
+control. Default is $0$.}
+
+\wxheading{Remarks}
+
+Popup minimum width may override arguments.
+
+It is up to the popup to fully take this into account.
+
+
+\membersection{wxComboCtrl::SetPopupMaxHeight}\label{wxcomboctrlsetpopupmaxheight}
+
+\func{void}{SetPopupMaxHeight}{\param{int }{height}}
+
+Sets preferred maximum height of the popup.
+
+\wxheading{Remarks}
+
+Value -1 indicates the default.
+
+Also, popup implementation may choose to ignore this.
+
+
+\membersection{wxComboCtrl::SetPopupMinWidth}\label{wxcomboctrlsetpopupminwidth}
+
+\func{void}{SetPopupMinWidth}{\param{int }{width}}
+
+Sets minimum width of the popup. If wider than combo control, it will extend to the left.
+
+\wxheading{Remarks}
+
+Value -1 indicates the default.
+
+Also, popup implementation may choose to ignore this.
+
+
+\membersection{wxComboCtrl::SetSelection}\label{wxcomboctrlsetselection}
+
+\func{void}{SetSelection}{\param{long }{from}, \param{long }{to}}
+
+Selects the text between the two positions, in the combo control text field.
+
+\wxheading{Parameters}
+
+\docparam{from}{The first position.}
+
+\docparam{to}{The second position.}
+
+
+\membersection{wxComboCtrl::SetText}\label{wxcomboctrlsettext}
+
+\func{void}{SetText}{\param{const wxString\& }{value}}
+
+Sets the text for the text field without affecting the
+popup. Thus, unlike \helpref{SetValue}{wxcomboctrlsetvalue}, it works
+equally well with combo control using {\tt wxCB\_READONLY} style.
+
+
+\membersection{wxComboCtrl::SetTextIndent}\label{wxcomboctrlsettextindent}
+
+\func{void}{SetTextIndent}{\param{int }{indent}}
+
+This will set the space in pixels between left edge of the control and the
+text, regardless whether control is read-only or not. Value -1 can be
+given to indicate platform default.
+
+
+\membersection{wxComboCtrl::SetValue}\label{wxcomboctrlsetvalue}
+
+\func{void}{SetValue}{\param{const wxString\& }{value}}
+
+Sets the text for the combo control text field.
+
+{\bf NB:} For a combo control with {\tt wxCB\_READONLY} style the
+string must be accepted by the popup (for instance, exist in the dropdown
+list), otherwise the call to SetValue() is ignored
+
+
+\membersection{wxComboCtrl::ShowPopup}\label{wxcomboctrlshowpopup}
+
+\func{void}{ShowPopup}{\void}
+
+Show the popup.
+
+
+\membersection{wxComboCtrl::Undo}\label{wxcomboctrlundo}
+
+\func{void}{Undo}{\void}
+
+Undoes the last edit in the text field. Windows only.

docs/latex/wx/combopopup.tex

@@ -0,0 +1,183 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        combopopup.tex
+%% Purpose:     wxComboPopup docs
+%% Author:      Jaakko Salli
+%% Modified by:
+%% Created:
+%% RCS-ID:      $Id$
+%% Copyright:   (c) Jaakko Salli
+%% License:     wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxComboPopup}}\label{wxcombopopup}
+
+In order to use a custom popup with \helpref{wxComboCtrl}{wxcomboctrl},
+an interface class must be derived from wxComboPopup. For more information
+how to use it, see \helpref{Setting Custom Popup for wxComboCtrl}{wxcomboctrl}.
+
+\wxheading{Include files}
+
+<combo.h>
+
+\wxheading{See also}
+
+\helpref{wxComboCtrl}{wxcomboctrl}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+
+\membersection{wxComboPopup::wxComboPopup}\label{wxcombopopupwxcombopopup}
+
+\func{}{wxComboPopup}{\void}
+
+Default constructor. It is recommended that internal variables
+are prepared in \helpref{Init}{wxcombopopupinit} instead
+(because \helpref{m\_combo}{wxcombopopupmcombo} is not valid in constructor).
+
+
+\membersection{wxComboPopup::m\_combo}\label{wxcombopopupmcombo}
+
+\member{wxComboCtrl}{m\_combo}
+
+Parent \helpref{wxComboCtrl}{wxcomboctrl}. This is parameter has
+been prepared before \helpref{Init}{wxcombopopupinit} is called.
+
+
+\membersection{wxComboPopup::Create}\label{wxcombopopupcreate}
+
+\func{bool}{Create}{\param{wxWindow* }{parent}}
+
+The derived class must implement this to create the popup control.
+
+\wxheading{Return value}
+
+\true if the call succeeded, \false otherwise.
+
+
+\membersection{wxComboPopup::Dismiss}\label{wxcombopopupdismiss}
+
+\func{void}{Dismiss}{\void}
+
+Utility function that hides the popup.
+
+
+\membersection{wxComboPopup::GetAdjustedSize}\label{wxcombopopupgetadjustedsize}
+
+\func{wxSize}{GetAdjustedSize}{\param{int }{minWidth}, \param{int }{prefHeight}, \param{int }{maxHeight}}
+
+The derived class may implement this to return adjusted size
+for the popup control, according to the variables given.
+
+\wxheading{Parameters}
+
+\docparam{minWidth}{Preferred minimum width.}
+\docparam{prefHeight}{Preferred height. May be -1 to indicate
+no preference.}
+\docparam{maxWidth}{Max height for window, as limited by
+screen size.}
+
+\wxheading{Remarks}
+
+Called each time popup is about to be shown.
+
+
+\membersection{wxComboPopup::GetControl}\label{wxcombopopupgetcontrol}
+
+\func{wxWindow*}{GetControl}{\void}
+
+The derived class must implement this to return pointer
+to the associated control created in \helpref{Create}{wxcombopopupcreate}.
+
+
+\membersection{wxComboPopup::GetStringValue}\label{wxcombopopupgetstringvalue}
+
+\constfunc{wxString}{GetStringValue}{\void}
+
+The derived class must implement this to return
+string representation of the value.
+
+
+\membersection{wxComboPopup::Init}\label{wxcombopopupinit}
+
+\func{void}{Init}{\void}
+
+The derived class must implement this to initialize
+its internal variables. This method is called immediately
+after construction finishes. \helpref{m\_combo}{wxcombopopupmcombo}
+member variable has been initialized before the call.
+
+
+\membersection{wxComboPopup::IsCreated}\label{wxcombopopupiscreated}
+
+\constfunc{bool}{IsCreated}{\void}
+
+Utility method that returns \true if Create has been called.
+
+Useful in conjunction with \helpref{LazyCreate}{wxcombopopuplazycreate}.
+
+
+\membersection{wxComboPopup::LazyCreate}\label{wxcombopopuplazycreate}
+
+\func{bool}{LazyCreate}{\void}
+
+The derived class may implement this to return
+\true if it wants to delay call to \helpref{Create}{wxcombopopupcreate}
+until the popup is shown for the first time. It is more
+efficient, but on the other hand it is often more convenient
+to have the control created immediately.
+
+\wxheading{Remarks}
+
+Base implementation returns \false.
+
+
+\membersection{wxComboPopup::OnComboDoubleClick}\label{wxcombopopuponcombodoubleclick}
+
+\func{void}{OnComboDoubleClick}{\void}
+
+The derived class may implement this to do something
+when the parent \helpref{wxComboCtrl}{wxcomboctrl} gets double-clicked.
+
+
+\membersection{wxComboPopup::OnComboKeyEvent}\label{wxcombopopuponcombokeyevent}
+
+\func{void}{OnComboKeyEvent}{\param{wxKeyEvent\& }{event}}
+
+The derived class may implement this to receive
+key events from the parent \helpref{wxComboCtrl}{wxcomboctrl}.
+
+Events not handled should be skipped, as usual.
+
+
+\membersection{wxComboPopup::OnDismiss}\label{wxcombopopupondismiss}
+
+\func{void}{OnDismiss}{\void}
+
+The derived class may implement this to do
+special processing when popup is hidden.
+
+
+\membersection{wxComboPopup::OnPopup}\label{wxcombopopuponpopup}
+
+\func{void}{OnPopup}{\void}
+
+The derived class may implement this to do
+special processing when popup is shown.
+
+
+\membersection{wxComboPopup::PaintComboControl}\label{wxcombopopuppaintcombocontrol}
+
+\func{void}{PaintComboControl}{\param{wxDC\& }{dc}, \param{const wxRect\& }{rect}}
+
+The derived class may implement this to paint
+the parent \helpref{wxComboCtrl}{wxcomboctrl}.
+
+Default implementation draws value as string.
+
+
+\membersection{wxComboPopup::SetStringValue}\label{wxcombopopupsetstringvalue}
+
+\func{void}{SetStringValue}{\param{const wxString\& }{value}}
+
+The derived class must implement this to receive
+string value changes from \helpref{wxComboCtrl}{wxcomboctrl}.

docs/latex/wx/odcbox.tex

@@ -0,0 +1,204 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        odcbox.tex
+%% Purpose:     wxOwnerDrawnComboBox docs
+%% Author:      Jaakko Salli
+%% Modified by:
+%% Created:
+%% RCS-ID:      $Id$
+%% Copyright:   (c) Jaakko Salli
+%% License:     wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxOwnerDrawnComboBox}}\label{wxownerdrawncombobox}
+
+wxOwnerDrawnComboBox is a combobox with owner-drawn list items.
+In essence, it is a \helpref{wxComboCtrl}{wxcomboctrl} with
+\helpref{wxVListBox}{wxvlistbox} popup and \helpref{wxControlWithItems}{wxcontrolwithitems}
+interface.
+
+Implementing item drawing and measuring is similar to \helpref{wxVListBox}{wxvlistbox}.
+Application needs to subclass wxOwnerDrawnComboBox and implement
+\helpref{OnDrawItem()}{wxownerdrawncomboboxondrawitem}, \helpref{OnMeasureItem()}{wxownerdrawncomboboxonmeasureitem}
+and \helpref{OnMeasureItemWidth()}{wxownerdrawncomboboxonmeasureitemwidth}.
+
+
+\wxheading{Derived from}
+
+\helpref{wxComboCtrl}{wxcomboctrl}\\
+\helpref{wxControlWithItems}{wxcontrolwithitems}\\
+\helpref{wxControl}{wxcontrol}\\
+\helpref{wxWindow}{wxwindow}\\
+\helpref{wxEvtHandler}{wxevthandler}\\
+\helpref{wxObject}{wxobject}
+
+\wxheading{Include files}
+
+<odcombo.h>
+
+\wxheading{Window styles}
+
+\begin{twocollist}\itemsep=0pt
+\twocolitem{\windowstyle{wxODCB\_DCLICK\_CYCLES}}{Double-clicking cycles item
+if wxCB\_READONLY is also used. Synonymous with wxCC\_SPECIAL\_DCLICK.}
+\twocolitem{\windowstyle{wxODCB\_STD\_CONTROL\_PAINT}}{Control itself is not
+custom painted using OnDrawItem. Even if this style is not used, writable
+wxOwnerDrawnComboBox is never custom painted unless SetCustomPaintWidth is
+called.}
+\end{twocollist}
+
+See also \helpref{wxComboCtrl window styles}{wxcomboctrl} and
+base \helpref{window styles overview}{windowstyles}.
+
+\wxheading{Event handling}
+
+\twocolwidtha{7cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf EVT\_COMBOBOX(id, func)}}{Process a wxEVT\_COMMAND\_COMBOBOX\_SELECTED event,
+when an item on the list is selected. Note that calling
+\helpref{GetValue}{wxcomboctrlgetvalue} returns the new value of selection.}
+\end{twocollist}
+
+See also events emitted by \helpref{wxComboCtrl}{wxcomboctrl}.
+
+\wxheading{See also}
+
+\helpref{wxComboCtrl}{wxcomboctrl}, \helpref{wxComboBox}{wxcombobox}, \helpref{wxVListBox}{wxvlistbox},
+\rtfsp\helpref{wxCommandEvent}{wxcommandevent}
+
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+
+\membersection{wxOwnerDrawnComboBox::wxOwnerDrawnComboBox}\label{wxownerdrawncomboboxctor}
+
+\func{}{wxOwnerDrawnComboBox}{\void}
+
+Default constructor.
+
+\func{}{wxOwnerDrawnComboBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
+\param{const wxString\& }{value = ``"}, \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
+\param{int}{ n = 0}, \param{const wxString }{choices[] = NULL},\rtfsp
+\param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
+
+\func{}{wxOwnerDrawnComboBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
+\param{const wxString\& }{value}, \param{const wxPoint\&}{ pos}, \param{const wxSize\&}{ size},\rtfsp
+\param{const wxArrayString\& }{choices},\rtfsp
+\param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
+
+Constructor, creating and showing a owner-drawn combobox.
+
+\wxheading{Parameters}
+
+\docparam{parent}{Parent window. Must not be NULL.}
+
+\docparam{id}{Window identifier. A value of -1 indicates a default value.}
+
+\docparam{value}{Initial selection string. An empty string indicates no selection.}
+
+\docparam{pos}{Window position.}
+
+\docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized
+appropriately.}
+
+\docparam{n}{Number of strings with which to initialise the control.}
+
+\docparam{choices}{An array of strings with which to initialise the control.}
+
+\docparam{style}{Window style. See \helpref{wxOwnerDrawnComboBox}{wxownerdrawncombobox}.}
+
+\docparam{validator}{Window validator.}
+
+\docparam{name}{Window name.}
+
+\wxheading{See also}
+
+\helpref{wxOwnerDrawnComboBox::Create}{wxownerdrawncomboboxcreate}, \helpref{wxValidator}{wxvalidator}
+
+
+\membersection{wxOwnerDrawnComboBox::\destruct{wxOwnerDrawnComboBox}}\label{wxownerdrawncomboboxdtor}
+
+\func{}{\destruct{wxOwnerDrawnComboBox}}{\void}
+
+Destructor, destroying the owner-drawn combobox.
+
+
+\membersection{wxOwnerDrawnComboBox::Create}\label{wxownerdrawncomboboxcreate}
+
+\func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
+\param{const wxString\& }{value = ``"}, \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
+\param{int}{ n}, \param{const wxString }{choices[]},\rtfsp
+\param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
+
+\func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
+\param{const wxString\& }{value}, \param{const wxPoint\&}{ pos}, \param{const wxSize\&}{ size},\rtfsp
+\param{const wxArrayString\& }{choices},\rtfsp
+\param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
+
+Creates the combobox for two-step construction. Derived classes
+should call or replace this function. See
+\helpref{wxOwnerDrawnComboBox::wxOwnerDrawnComboBox}{wxownerdrawncomboboxctor}\rtfsp
+for further details.
+
+
+\membersection{wxOwnerDrawnComboBox::OnDrawBackground}\label{wxownerdrawncomboboxondrawbackground}
+
+\constfunc{void}{OnDrawBackground}{\param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{int }{item}, \param{int }{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.
+
+\wxheading{Remarks}
+
+\arg{flags} has the same meaning as with \helpref{OnDrawItem}{wxownerdrawncomboboxondrawitem}.
+
+
+\membersection{wxOwnerDrawnComboBox::OnDrawItem}\label{wxownerdrawncomboboxondrawitem}
+
+\constfunc{void}{OnDrawItem}{\param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{int }{item}, \param{int }{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.
+
+\wxheading{Parameters}
+
+\docparam{dc}{The device context to use for drawing}
+
+\docparam{rect}{The bounding rectangle for the item being drawn (DC clipping
+region is set to this rectangle before calling this function)}
+
+\docparam{item}{The index of the item to be drawn}
+
+\docparam{flags}{Combines any of the following flag values:}
+
+\twocolwidtha{7cm}%
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\tt wxODCB\_PAINTING\_CONTROL}}{Combo control is being
+painted, instead of a list item. Argument item may be wxNOT\_FOUND in this
+case.}
+\end{twocollist}
+
+
+\membersection{wxOwnerDrawnComboBox::OnMeasureItem}\label{wxownerdrawncomboboxonmeasureitem}
+
+\constfunc{wxCoord}{OnMeasureItem}{\param{size\_t }{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.
+
+
+\membersection{wxOwnerDrawnComboBox::OnMeasureItemWidth}\label{wxownerdrawncomboboxonmeasureitemwidth}
+
+\constfunc{wxCoord}{OnMeasureItemWidth}{\param{size\_t }{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.