escape more underscores (we need a pre-commit check for those...)

[wxWidgets.git] / docs / latex / wx / comboctrl.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% 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{wxTE\_PROCESS\_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\_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::DoSetPopupControl}\label{wxcomboctrldosetpopupcontrol}

\func{void}{DoSetPopupControl}{\param{wxComboPopup* }{popup}}

This member function is not normally called in application code.
Instead, it can be implemented in a derived class to return
default wxComboPopup, incase {\tt popup} is NULL.

\textbf{Note:} If you have implemented OnButtonClick to do
something else than show the popup, then DoSetPopupControl
must always return NULL.


\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::GetButtonSize}\label{wxcomboctrlgetbuttonsize}

\func{wxSize}{GetButtonSize}{\void}

Returns current size of the dropdown button.


\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::GetTextRect}\label{wxcomboctrlgettextrect}

\constfunc{const wxRect\&}{GetTextRect}{\void}

Returns area covered by the text field (includes everything except
borders and the dropdown button).


\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.

\textbf{Note:} If you implement this to do something else than
show the popup, you must then also implement
\helpref{DoSetPopupControl}{wxcomboctrldosetpopupcontrol} to always
return NULL.


\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 = -1}, \param{int }{height = -1}, \param{int }{side = wxRIGHT}, \param{int }{spacingX = 0}}

Sets size and position of dropdown button.

\wxheading{Parameters}

\docparam{width}{Button width. Value <= $0$ specifies default.}
\docparam{height}{Button height. Value <= $0$ specifies default.}
\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::SetValueWithEvent}\label{wxcomboctrlsetvaluewithevent}

\func{void}{SetValueWithEvent}{\param{const wxString\& }{value}, \param{bool }{withEvent = true}}

Same as SetValue, but also sends wxCommandEvent of type wxEVT\_COMMAND\_TEXT\_UPDATED
if {\tt withEvent} is \true.


\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.