+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% 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.
projects / wxWidgets.git / commitdiff
