comboctrl.tex

很牛的GUI源码wxWidgets-2.8.0.zip 可在多种平台下运行.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Name:        comboctrl.tex
%% Purpose:     wxComboCtrl docs
%% Author:      Jaakko Salli
%% Modified by:
%% Created:
%% RCS-ID:      $Id: comboctrl.tex,v 1.9 2006/10/26 20:35:43 RR Exp $
%% 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::AnimateShow}\label{wxcomboctrlanimateshow}

\func{virtual bool}{AnimateShow}{\param{const wxRect\& }{rect}, \param{int }{flags}}

This member function is not normally called in application code.
Instead, it can be implemented in a derived class to create a
custom popup animation.

\wxheading{Parameters}

Same as in \helpref{DoShowPopup}{wxcomboctrldoshowpopup}.

\wxheading{Return value}

\true if animation finishes before the function returns.
\false otherwise. In the latter case you need to manually call DoShowPopup
after the animation ends.


\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::DoShowPopup}\label{wxcomboctrldoshowpopup}

\func{virtual void}{DoShowPopup}{\param{const wxRect\& }{rect}, \param{int }{flags}}

This member function is not normally called in application code.
Instead, it must be called in a derived class to make sure popup
is properly shown after a popup animation has finished (but only
if \helpref{AnimateShow}{wxcomboctrlanimateshow} did not finish
the animation within it's function scope).

\wxheading{Parameters}

\docparam{rect}{Position to show the popup window at, in screen coordinates.}

\docparam{flags}{Combination of any of the following:}
\twocolwidtha{8cm}%
\begin{twocollist}\itemsep=0pt
\twocolitem{{\tt wxComboCtrl::ShowAbove}}{Popup is shown above the control instead
of below.}
\twocolitem{{\tt wxComboCtrl::CanDeferShow}}{Showing the popup can be deferred
to happen sometime after \helpref{ShowPopup}{wxcomboctrlshowpopup} has finished.
In this case, \helpref{AnimateShow}{wxcomboctrlanimateshow} must return \false.}
\end{twocollist}


\membersection{wxComboCtrl::EnablePopupAnimation}\label{wxcomboctrlenablepopupanimation}

\func{void}{EnablePopupAnimation}{\param{bool }{enable = true}}

Enables or disables popup animation, if any, depending on the value of
the argument.


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