Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Finished initial review of some [co*] interface headers.

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53098 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Bryan Petty
2008-04-10 02:57:09 +00:00
parent 47ac374e0d
commit 968f15e262
4 changed files with 307 additions and 297 deletions
Download Patch File Download Diff File Expand all files Collapse all files

422
interface/combo.h
View File

@@ -1,6 +1,6 @@
/////////////////////////////////////////////////////////////////////////////
// Name: combo.h
// Purpose: interface of wxComboPopup
// Purpose: interface of wxComboCtrl and wxComboPopup
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
@@ -10,14 +10,13 @@
@class wxComboPopup
@wxheader{combo.h}
In order to use a custom popup with wxComboCtrl, an interface class must
be derived from wxComboPopup.
In order to use a custom popup with wxComboCtrl, an interface class must be
derived from wxComboPopup.
For more information on how to use it, see @ref overview_wxcomboctrl "Setting Custom Popup for
wxComboCtrl".
For more information on how to use it, see @ref comboctrl_custompopup.
@library{wxcore}
@category{FIXME}
@category{ctrl}
@see wxComboCtrl
*/
@@ -25,9 +24,9 @@ class wxComboPopup
{
public:
/**
Default constructor. It is recommended that internal variables
are prepared in Init() instead
(because @ref mcombo() m_combo is not valid in constructor).
Default constructor. It is recommended that internal variables are
prepared in Init() instead (because m_combo is not valid in
constructor).
*/
wxComboPopup();
@@ -36,7 +35,7 @@ public:
@returns @true if the call succeeded, @false otherwise.
*/
bool Create(wxWindow* parent);
virtual bool Create(wxWindow* parent);
/**
Utility function that hides the popup.
@@ -44,123 +43,147 @@ public:
void Dismiss();
/**
The derived class may implement this to return adjusted size
for the popup control, according to the variables given.
The derived class may implement this to return adjusted size for the
popup control, according to the variables given.
@param minWidth
Preferred minimum width.
@param prefHeight
Preferred height. May be -1 to indicate
no preference.
Preferred height. May be -1 to indicate no preference.
@param maxWidth
Max height for window, as limited by
screen size.
Max height for window, as limited by screen size.
@remarks Called each time popup is about to be shown.
@remarks This function is called each time popup is about to be shown.
*/
wxSize GetAdjustedSize(int minWidth, int prefHeight,
int maxHeight);
virtual wxSize GetAdjustedSize(int minWidth, int prefHeight, int maxHeight);
/**
The derived class must implement this to return pointer
to the associated control created in Create().
The derived class must implement this to return pointer to the
associated control created in Create().
*/
wxWindow* GetControl();
virtual wxWindow* GetControl();
/**
The derived class must implement this to return
string representation of the value.
The derived class must implement this to return string representation
of the value.
*/
wxString GetStringValue() const;
virtual wxString GetStringValue() const;
/**
The derived class must implement this to initialize
its internal variables. This method is called immediately
after construction finishes. @ref mcombo() m_combo
member variable has been initialized before the call.
The derived class must implement this to initialize its internal
variables. This method is called immediately after construction
finishes. m_combo member variable has been initialized before the call.
*/
void Init();
virtual void Init();
/**
Utility method that returns @true if Create has been called.
Useful in conjunction with LazyCreate().
*/
bool IsCreated() const;
/**
The derived class may implement this to return
@true if it wants to delay call to Create()
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.
The derived class may implement this to return @true if it wants to
delay call to Create() 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.
@remarks Base implementation returns @false.
*/
bool LazyCreate();
virtual bool LazyCreate();
/**
The derived class may implement this to do something
when the parent wxComboCtrl gets double-clicked.
The derived class may implement this to do something when the parent
wxComboCtrl gets double-clicked.
*/
void OnComboDoubleClick();
virtual void OnComboDoubleClick();
/**
The derived class may implement this to receive
key events from the parent wxComboCtrl.
The derived class may implement this to receive key events from the
parent wxComboCtrl.
Events not handled should be skipped, as usual.
*/
void OnComboKeyEvent(wxKeyEvent& event);
virtual void OnComboKeyEvent(wxKeyEvent& event);
/**
The derived class may implement this to do
special processing when popup is hidden.
The derived class may implement this to do special processing when
popup is hidden.
*/
void OnDismiss();
virtual void OnDismiss();
/**
The derived class may implement this to do
special processing when popup is shown.
The derived class may implement this to do special processing when
popup is shown.
*/
void OnPopup();
virtual void OnPopup();
/**
The derived class may implement this to paint
the parent wxComboCtrl.
The derived class may implement this to paint the parent wxComboCtrl.
Default implementation draws value as string.
*/
void PaintComboControl(wxDC& dc, const wxRect& rect);
virtual void PaintComboControl(wxDC& dc, const wxRect& rect);
/**
The derived class must implement this to receive
string value changes from wxComboCtrl.
The derived class must implement this to receive string value changes
from wxComboCtrl.
*/
void SetStringValue(const wxString& value);
virtual void SetStringValue(const wxString& value);
/**
wxComboCtrl m_combo
Parent wxComboCtrl. This is parameter has
been prepared before Init() is called.
Parent wxComboCtrl. This is parameter has been prepared before Init()
is called.
*/
wxComboCtrl m_combo;
};
/**
Features enabled for wxComboCtrl.
@see wxComboCtrl::GetFeatures()
*/
struct wxComboCtrlFeatures
{
enum
{
MovableButton = 0x0001, ///< Button can be on either side of control.
BitmapButton = 0x0002, ///< Button may be replaced with bitmap.
ButtonSpacing = 0x0004, ///< Button can have spacing from the edge
///< of the control.
TextIndent = 0x0008, ///< wxComboCtrl::SetTextIndent() can be used.
PaintControl = 0x0010, ///< Combo control itself can be custom painted.
PaintWritable = 0x0020, ///< A variable-width area in front of writable
///< combo control's textctrl can be custom
///< painted.
Borderless = 0x0040, ///< wxNO_BORDER window style works.
All = MovableButton | BitmapButton | ButtonSpacing |
TextIndent | PaintControl | PaintWritable |
Borderless ///< All features.
};
};
/**
@class wxComboCtrl
@wxheader{combo.h}
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.
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.
@section wxcomboctrl_custompopup Setting Custom Popup for wxComboCtrl
@section comboctrl_custompopup 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 wxComboPopup which
is an interface which must be implemented by a control to be usable as a popup.
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 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,
@@ -172,11 +195,9 @@ public:
#include <wx/combo.h>
#include <wx/listctrl.h>
class wxListViewComboPopup : public wxListView,
public wxComboPopup
class wxListViewComboPopup : public wxListView, public wxComboPopup
{
public:
// Initialize member variables
virtual void Init()
{
@@ -204,7 +225,7 @@ public:
virtual wxString GetStringValue() const
{
if ( m_value >= 0 )
return wxListView::GetItemText(m_value);
return wxListView::GetItemText(m_value);
return wxEmptyString;
}
@@ -225,7 +246,8 @@ public:
}
protected:
int m_value; // current item index
int m_value; // current item index
private:
DECLARE_EVENT_TABLE()
@@ -240,16 +262,16 @@ public:
Here's how you would create and populate it in a dialog constructor:
@code
wxComboCtrl* comboCtrl = new wxComboCtrl(this,wxID_ANY,wxEmptyString);
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"));
popupCtrl->InsertItem(popupCtrl->GetItemCount(), "First Item");
popupCtrl->InsertItem(popupCtrl->GetItemCount(), "Second Item");
popupCtrl->InsertItem(popupCtrl->GetItemCount(), "Third Item");
@endcode
@beginStyleTable
@@ -281,14 +303,19 @@ public:
@library{wxbase}
@category{ctrl}
@appearance{comboctrl.png}
<!-- @appearance{comboctrl.png} -->
@see wxComboBox, wxChoice, wxOwnerDrawnComboBox, wxComboPopup, wxCommandEvent
@see wxComboBox, wxChoice, wxOwnerDrawnComboBox, wxComboPopup,
wxCommandEvent
*/
class wxComboCtrl : public wxControl
{
public:
//@{
/**
Default constructor.
*/
wxComboCtrl();
/**
Constructor, creating and showing a combo control.
@@ -301,8 +328,7 @@ public:
@param pos
Window position.
@param size
Window size. If wxDefaultSize is specified then the window is
sized
Window size. If wxDefaultSize is specified then the window is sized
appropriately.
@param style
Window style. See wxComboCtrl.
@@ -313,7 +339,6 @@ public:
@see Create(), wxValidator
*/
wxComboCtrl();
wxComboCtrl(wxWindow* parent, wxWindowID id,
const wxString& value = "",
const wxPoint& pos = wxDefaultPosition,
@@ -321,33 +346,34 @@ public:
long style = 0,
const wxValidator& validator = wxDefaultValidator,
const wxString& name = "comboCtrl");
//@}
/**
Destructor, destroying the combo control.
*/
~wxComboCtrl();
virtual ~wxComboCtrl();
/**
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.
Instead, it can be implemented in a derived class to create a custom
popup animation.
@returns @true if animation finishes before the function returns. @false
otherwise. In the latter case you need to manually call
DoShowPopup after the animation ends.
The parameters are the same as those for DoShowPopup().
@returns @true if animation finishes before the function returns,
@false otherwise. In the latter case you need to manually call
DoShowPopup() after the animation ends.
*/
virtual bool AnimateShow(const wxRect& rect, int flags);
/**
Copies the selected text to the clipboard.
*/
void Copy();
virtual void Copy();
/**
Creates the combo control for two-step construction. Derived classes
should call or replace this function. See wxComboCtrl()
for further details.
should call or replace this function. See wxComboCtrl() for further
details.
*/
bool Create(wxWindow* parent, wxWindowID id,
const wxString& value = "",
@@ -360,29 +386,37 @@ public:
/**
Copies the selected text to the clipboard and removes the selection.
*/
void Cut();
virtual void Cut();
/**
This member function is not normally called in application code.
Instead, it can be implemented in a derived class to return
default wxComboPopup, incase @c popup is @NULL.
@note If you have implemented OnButtonClick to do
something else than show the popup, then DoSetPopupControl
must always return @NULL.
Instead, it can be implemented in a derived class to return default
wxComboPopup, incase @a popup is @NULL.
@note If you have implemented OnButtonClick() to do something else than
show the popup, then DoSetPopupControl() must always set @a popup
to @NULL.
*/
void DoSetPopupControl(wxComboPopup* popup);
/**
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 AnimateShow() did not finish
the animation within it's function scope).
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
AnimateShow() did not finish the animation within its function scope).
@param rect
Position to show the popup window at, in screen coordinates.
@param flags
Combination of any of the following:
@beginTable
@row2col{wxComboCtrl::ShowAbove,
Popup is shown above the control instead of below.}
@row2col{wxComboCtrl::CanDeferShow,
Showing the popup can be deferred to happen sometime after
ShowPopup() has finished. In this case, AnimateShow() must
return false.}
@endTable
*/
virtual void DoShowPopup(const wxRect& rect, int flags);
@@ -437,28 +471,31 @@ public:
int GetCustomPaintWidth() const;
/**
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).
Returns features supported by wxComboCtrl. If needed feature is
missing, you need to instead use wxGenericComboCtrl, which however may
lack a native look and feel (but otherwise sports identical API).
@returns Value returned is a combination of following flags:
@returns Value returned is a combination of the flags defined in
wxComboCtrlFeatures.
*/
static int GetFeatures();
/**
Returns the insertion point for the combo control's text field.
@note Under wxMSW, this function always returns 0 if the combo control
doesn't have the focus.
@note Under Windows, this function always returns 0 if the combo
control doesn't have the focus.
*/
long GetInsertionPoint() const;
virtual long GetInsertionPoint() const;
/**
Returns the last position in the combo control text field.
*/
long GetLastPosition() const;
virtual long GetLastPosition() const;
/**
Returns current popup interface that has been set with SetPopupControl.
Returns current popup interface that has been set with
SetPopupControl().
*/
wxComboPopup* GetPopupControl();
@@ -484,15 +521,15 @@ public:
const wxRect GetTextRect() const;
/**
Returns text representation of the current value. For writable
combo control it always returns the value in the text field.
Returns text representation of the current value. For writable combo
control it always returns the value in the text field.
*/
wxString GetValue() const;
virtual wxString GetValue() const;
/**
Dismisses the popup window.
*/
void HidePopup();
virtual void HidePopup();
/**
Returns @true if the popup is currently shown
@@ -500,53 +537,47 @@ public:
bool IsPopupShown() const;
/**
Returns @true if the popup window is in the given state.
Possible values are:
Returns @true if the popup window is in the given state. Possible
values are:
@c Hidden()
Popup window is hidden.
@c Animating()
Popup window is being shown, but the
popup animation has not yet finished.
@c Visible()
Popup window is fully visible.
@beginTable
@row2col{wxComboCtrl::Hidden, Popup window is hidden.}
@row2col{wxComboCtrl::Animating, Popup window is being shown, but the
popup animation has not yet finished.}
@row2col{wxComboCtrl::Visible, Popup window is fully visible.}
@endTable
*/
bool IsPopupWindowState(int state) const;
/**
Implement in a derived class to define what happens on
dropdown button click.
Default action is to show the popup.
@note If you implement this to do something else than
show the popup, you must then also implement
DoSetPopupControl() to always
return @NULL.
Implement in a derived class to define what happens on dropdown button
click. Default action is to show the popup.
@note If you implement this to do something else than show the popup,
you must then also implement DoSetPopupControl() to always return
@NULL.
*/
void OnButtonClick();
virtual void OnButtonClick();
/**
Pastes text from the clipboard to the text field.
*/
void Paste();
virtual void Paste();
/**
Removes the text between the two positions in the combo control text field.
Removes the text between the two positions in the combo control text
field.
@param from
The first position.
@param to
The last position.
*/
void Remove(long from, long to);
virtual void Remove(long from, long to);
/**
Replaces the text between two positions with the given text, in the combo
control text field.
Replaces the text between two positions with the given text, in the
combo control text field.
@param from
The first position.
@@ -555,7 +586,7 @@ public:
@param text
The text to insert.
*/
void Replace(long from, long to, const wxString& value);
virtual void Replace(long from, long to, const wxString& value);
/**
Sets custom dropdown button graphics.
@@ -563,14 +594,13 @@ public:
@param bmpNormal
Default button image.
@param pushButtonBg
If @true, blank push button background is painted
below the image.
If @true, blank push button background is painted below the image.
@param bmpPressed
Depressed button image.
@param 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.
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.
@param bmpDisabled
Disabled button image.
*/
@@ -588,18 +618,17 @@ public:
@param height
Button height. Value = 0 specifies default.
@param side
Indicates which side the button will be placed.
Value can be wxLEFT or wxRIGHT.
Indicates which side the button will be placed. Value can be wxLEFT
or wxRIGHT.
@param spacingX
Horizontal spacing around the button. Default is 0.
*/
void SetButtonPosition(int width = -1, int height = -1,
int side = wxRIGHT,
int spacingX = 0);
int side = wxRIGHT, int spacingX = 0);
/**
Set width, in pixels, of custom painted area in control without @c wxCB_READONLY
style. In read-only wxOwnerDrawnComboBox, this is used
Set width, in pixels, of custom painted area in control without
@c wxCB_READONLY style. In read-only wxOwnerDrawnComboBox, this is used
to indicate area that is not covered by the focus rectangle.
*/
void SetCustomPaintWidth(int width);
@@ -610,39 +639,41 @@ public:
@param pos
The new insertion point.
*/
void SetInsertionPoint(long pos);
virtual void SetInsertionPoint(long pos);
/**
Sets the insertion point at the end of the combo control text field.
*/
void SetInsertionPointEnd();
virtual void SetInsertionPointEnd();
/**
Set side of the control to which the popup will align itself. Valid values are
@c wxLEFT, @c wxRIGHT and 0. The default value 0 means that the most appropriate
side is used (which, currently, is always @c wxLEFT).
Set side of the control to which the popup will align itself. Valid
values are @c wxLEFT, @c wxRIGHT and 0. The default value 0 means that
the most appropriate side is used (which, currently, is always
@c wxLEFT).
*/
void SetPopupAnchor(int anchorSide);
/**
Set popup interface class derived from wxComboPopup.
This method should be called as soon as possible after the control
has been created, unless OnButtonClick()
has been overridden.
Set popup interface class derived from wxComboPopup. This method should
be called as soon as possible after the control has been created,
unless OnButtonClick() has been overridden.
*/
void SetPopupControl(wxComboPopup* popup);
/**
Extends popup size horizontally, relative to the edges of the combo control.
Extends popup size horizontally, relative to the edges of the combo
control.
@param extLeft
How many pixel to extend beyond the left edge of the
control. Default is 0.
How many pixel to extend beyond the left edge of the control.
Default is 0.
@param extRight
How many pixel to extend beyond the right edge of the
control. Default is 0.
How many pixel to extend beyond the right edge of the control.
Default is 0.
@remarks Popup minimum width may override arguments.
@remarks Popup minimum width may override arguments. It is up to the
popup to fully take this into account.
*/
void SetPopupExtents(int extLeft, int extRight);
@@ -654,69 +685,70 @@ public:
void SetPopupMaxHeight(int height);
/**
Sets minimum width of the popup. If wider than combo control, it will extend to
the left.
Sets minimum width of the popup. If wider than combo control, it will
extend to the left.
@remarks Value -1 indicates the default.
@remarks Value -1 indicates the default. Also, popup implementation may
choose to ignore this.
*/
void SetPopupMinWidth(int width);
/**
Selects the text between the two positions, in the combo control text field.
Selects the text between the two positions, in the combo control text
field.
@param from
The first position.
@param to
The second position.
*/
void SetSelection(long from, long to);
virtual void SetSelection(long from, long to);
/**
Sets the text for the text field without affecting the
popup. Thus, unlike SetValue(), it works
equally well with combo control using @c wxCB_READONLY style.
Sets the text for the text field without affecting the popup. Thus,
unlike SetValue(), it works equally well with combo control using
@c wxCB_READONLY style.
*/
void SetText(const wxString& value);
/**
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.
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.
*/
void SetTextIndent(int indent);
/**
Sets the text for the combo control text field.
@note For a combo control with @c 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
@note For a combo control with @c 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.
*/
void SetValue(const wxString& value);
virtual void SetValue(const wxString& value);
/**
Same as SetValue, but also sends wxCommandEvent of type
wxEVT_COMMAND_TEXT_UPDATED
if @c withEvent is @true.
Same as SetValue(), but also sends wxCommandEvent of type
wxEVT_COMMAND_TEXT_UPDATED if @a withEvent is @true.
*/
void SetValueWithEvent(const wxString& value,
bool withEvent = true);
void SetValueWithEvent(const wxString& value, bool withEvent = true);
/**
Show the popup.
*/
void ShowPopup();
virtual void ShowPopup();
/**
Undoes the last edit in the text field. Windows only.
*/
void Undo();
virtual void Undo();
/**
Enable or disable usage of an alternative popup window, which guarantees
ability to focus the popup control, and allows common native controls to
function normally. This alternative popup window is usually a wxDialog,
and as such, when it is shown, its parent top-level window will appear
as if the focus has been lost from it.
Enable or disable usage of an alternative popup window, which
guarantees ability to focus the popup control, and allows common native
controls to function normally. This alternative popup window is usually
a wxDialog, and as such, when it is shown, its parent top-level window
will appear as if the focus has been lost from it.
*/
void UseAltPopupWindow(bool enable = true);
};