From bfac616654010d1a369c14b33b78c888da5a85e0 Mon Sep 17 00:00:00 2001 From: Bryan Petty Date: Sat, 5 Apr 2008 09:12:23 +0000 Subject: [PATCH] Finished initial review of [ca*-ch*] interface headers. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53019 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/doxygen/mainpages/libs.h | 4 +- interface/caret.h | 71 +++++++++++++------------------ interface/checkbox.h | 78 ++++++++++++++++++++++------------- interface/checklst.h | 28 +++++++++---- interface/choicdlg.h | 34 ++++++++++----- interface/choice.h | 49 ++++++++++++++-------- interface/choicebk.h | 44 +++++++++++++------- 7 files changed, 185 insertions(+), 123 deletions(-) diff --git a/docs/doxygen/mainpages/libs.h b/docs/doxygen/mainpages/libs.h index cff03201c3..7806b6dedf 100644 --- a/docs/doxygen/mainpages/libs.h +++ b/docs/doxygen/mainpages/libs.h @@ -55,8 +55,8 @@ digraph Dependancies @enddot Please note that arrows indicate the "depends from" relation and that all blue -boxes depend on the @ref page_libs_wxbase library (i.e. they are non-GUI -libraries), and all green boxes depend on the @ref page_libs_wxcore library +libraries depend on the @ref page_libs_wxbase library (i.e. they are non-GUI +libraries), and all green libraries depend on the @ref page_libs_wxcore library (i.e. they are GUI libraries). diff --git a/interface/caret.h b/interface/caret.h index 3b386e6e9a..4182c41f60 100644 --- a/interface/caret.h +++ b/interface/caret.h @@ -11,79 +11,64 @@ @wxheader{caret.h} A caret is a blinking cursor showing the position where the typed text will - appear. The text controls usually have a caret but wxCaret class also allows - to use a caret in other windows. + appear. Text controls usually have their own caret but wxCaret provides a + way to use a caret in other windows. - Currently, the caret appears as a rectangle of the given size. In the future, - it will be possible to specify a bitmap to be used for the caret shape. + Currently, the caret appears as a rectangle of the given size. In the + future, it will be possible to specify a bitmap to be used for the caret + shape. A caret is always associated with a window and the current caret can be - retrieved using wxWindow::GetCaret. The same caret - can't be reused in two different windows. + retrieved using wxWindow::GetCaret(). The same caret can't be reused in two + different windows. @library{wxcore} @category{misc} - - @see wxCaret::GetBlinkTime */ class wxCaret { public: - //@{ /** - Create the caret of given (in pixels) width and height and associates it - with the given window. + Default constructor. */ wxCaret(); + + //@{ + /** + Creates a caret with the given size (in pixels) and associates it with + the @a window. + */ wxCaret(wxWindow* window, int width, int height); wxCaret(wxWindowBase* window, const wxSize& size); //@} //@{ /** - Create the caret of given (in pixels) width and height and associates it - with the given window (same as constructor). + Creates a caret with the given size (in pixels) and associates it with + the @a window (same as the equivalent constructors). */ bool Create(wxWindowBase* window, int width, int height); bool Create(wxWindowBase* window, const wxSize& size); //@} /** - Returns the blink time which is measured in milliseconds and is the time elapsed - between 2 inversions of the caret (blink time of the caret is the same - for all carets, so this functions is static). + Returns the blink time which is measured in milliseconds and is the + time elapsed between 2 inversions of the caret (blink time of the caret + is the same for all carets, so this functions is static). */ static int GetBlinkTime(); //@{ /** Get the caret position (in pixels). - - @b GetPosition() - - Returns a Wx::Point - - @b GetPositionXY() - - Returns a 2-element list - @c ( x, y ) */ void GetPosition(int* x, int* y) const; - const wxPoint GetPosition() const; + const wxPoint GetPosition() const; //@} //@{ /** Get the caret size. - - @b GetSize() - - Returns a Wx::Size - - @b GetSizeWH() - - Returns a 2-element list - @c ( width, height ) */ void GetSize(int* width, int* height) const; const wxSize GetSize() const; @@ -95,7 +80,7 @@ public: wxWindow* GetWindow() const; /** - Same as wxCaret::Show(@false). + Hides the caret, same as Show(@false). */ void Hide(); @@ -106,8 +91,8 @@ public: /** Returns @true if the caret is visible and @false if it is permanently - hidden (if it is is blinking and not shown currently but will be after the - next blink, this method still returns @true). + hidden (if it is is blinking and not shown currently but will be after + the next blink, this method still returns @true). */ bool IsVisible() const; @@ -122,9 +107,9 @@ public: /** Sets the blink time for all the carets. - @remarks Under Windows, this function will change the blink time for all - carets permanently (until the next time it is called), - even for the carets in other applications. + @warning Under Windows, this function will change the blink time for + all carets permanently (until the next time it is called), + even for carets in other applications. @see GetBlinkTime() */ @@ -139,8 +124,8 @@ public: //@} /** - Shows or hides the caret. Notice that if the caret was hidden N times, it - must be shown N times as well to reappear on the screen. + Shows or hides the caret. Notice that if the caret was hidden N times, + it must be shown N times as well to reappear on the screen. */ void Show(bool show = true); }; diff --git a/interface/checkbox.h b/interface/checkbox.h index 8fe098e3b8..66b60b3651 100644 --- a/interface/checkbox.h +++ b/interface/checkbox.h @@ -6,14 +6,25 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// +/** + The possible states of a 3-state wxCheckBox (Compatible with the 2-state + wxCheckBox). +*/ +enum wxCheckBoxState +{ + wxCHK_UNCHECKED, + wxCHK_CHECKED, + wxCHK_UNDETERMINED ///< 3-state checkbox only +}; + /** @class wxCheckBox @wxheader{checkbox.h} A checkbox is a labelled box which by default is either on (checkmark is - visible) or off (no checkmark). Optionally (when the wxCHK_3STATE style flag - is set) it can have a third state, called the mixed or undetermined state. - Often this is used as a "Does Not Apply" state. + visible) or off (no checkmark). Optionally (when the wxCHK_3STATE style + flag is set) it can have a third state, called the mixed or undetermined + state. Often this is used as a "Does Not Apply" state. @beginStyleTable @style{wxCHK_2STATE}: @@ -37,14 +48,20 @@ @library{wxcore} @category{ctrl} - @appearance{checkbox.png} + @see wxRadioButton, wxCommandEvent */ class wxCheckBox : public wxControl { public: - //@{ + /** + Default constructor. + + @see Create(), wxValidator + */ + wxCheckBox(); + /** Constructor, creating and showing a checkbox. @@ -56,10 +73,10 @@ public: Text to be displayed next to the checkbox. @param pos Checkbox position. If wxDefaultPosition is specified then a default - position is chosen. + position is chosen. @param size - Checkbox size. If wxDefaultSize is specified then a default - size is chosen. + Checkbox size. If wxDefaultSize is specified then a default size is + chosen. @param style Window style. See wxCheckBox. @param validator @@ -69,7 +86,6 @@ public: @see Create(), wxValidator */ - wxCheckBox(); wxCheckBox(wxWindow* parent, wxWindowID id, const wxString& label, const wxPoint& pos = wxDefaultPosition, @@ -77,7 +93,6 @@ public: long style = 0, const wxValidator& val = wxDefaultValidator, const wxString& name = "checkBox"); - //@} /** Destructor, destroying the checkbox. @@ -96,17 +111,6 @@ public: const wxValidator& val = wxDefaultValidator, const wxString& name = "checkBox"); - /** - Gets the state of a 3-state checkbox. - - @returns Returns wxCHK_UNCHECKED when the checkbox is unchecked, - wxCHK_CHECKED when it is checked and - wxCHK_UNDETERMINED when it's in the undetermined state. - Asserts when the function is used with a 2-state - checkbox. - */ - wxCheckBoxState Get3StateValue() const; - /** Gets the state of a 2-state checkbox. @@ -114,27 +118,34 @@ public: */ bool GetValue() const; + /** + Gets the state of a 3-state checkbox. Asserts when the function is used + with a 2-state checkbox. + */ + wxCheckBoxState Get3StateValue() const; + /** Returns whether or not the checkbox is a 3-state checkbox. - @returns Returns @true if this checkbox is a 3-state checkbox, @false if - it's a 2-state checkbox. + @returns Returns @true if this checkbox is a 3-state checkbox, @false + if it's a 2-state checkbox. */ bool Is3State() const; /** - Returns whether or not the user can set the checkbox to the third state. + Returns whether or not the user can set the checkbox to the third + state. @returns Returns @true if the user can set the third state of this - checkbox, @false if it can only be set programmatically - or if it's a 2-state checkbox. + checkbox, @false if it can only be set programmatically or if + it's a 2-state checkbox. */ bool Is3rdStateAllowedForUser() const; /** - This is just a maybe more readable synonym for - GetValue(): just as the latter, it returns - @true if the checkbox is checked and @false otherwise. + This is just a maybe more readable synonym for GetValue(): just as the + latter, it returns @true if the checkbox is checked and @false + otherwise. */ bool IsChecked() const; @@ -146,5 +157,14 @@ public: If @true, the check is on, otherwise it is off. */ void SetValue(bool state); + + /** + Sets the checkbox to the given state. This does not cause a + wxEVT_COMMAND_CHECKBOX_CLICKED event to get emitted. + + Asserts when the checkbox is a 2-state checkbox and setting the state + to wxCHK_UNDETERMINED. + */ + void Set3StateValue(const wxCheckBoxState state); }; diff --git a/interface/checklst.h b/interface/checklst.h index 80c5763f37..d3d6d206fa 100644 --- a/interface/checklst.h +++ b/interface/checklst.h @@ -10,10 +10,11 @@ @class wxCheckListBox @wxheader{checklst.h} - A checklistbox is like a listbox, but allows items to be checked or unchecked. + A wxCheckListBox is like a wxListBox, but allows items to be checked or + unchecked. When using this class under Windows wxWidgets must be compiled with - USE_OWNER_DRAWN set to 1. + wxUSE_OWNER_DRAWN set to 1. Only the new functions for this class are documented; see also wxListBox. @@ -28,13 +29,18 @@ @library{wxcore} @category{ctrl} - @appearance{checklistbox.png} + @see wxListBox, wxChoice, wxComboBox, wxListCtrl, wxCommandEvent */ class wxCheckListBox : public wxListBox { public: + /** + Default constructor. + */ + wxCheckListBox(); + //@{ /** Constructor, creating and showing a list box. @@ -46,8 +52,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 n Number of strings with which to initialise the control. @@ -60,7 +65,6 @@ public: @param name Window name. */ - wxCheckListBox(); wxCheckListBox(wxWindow* parent, wxWindowID id, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, @@ -84,8 +88,8 @@ public: ~wxCheckListBox(); /** - Checks the given item. Note that calling this method doesn't result in - wxEVT_COMMAND_CHECKLISTBOX_TOGGLE being emitted. + Checks the given item. Note that calling this method does not result in + a wxEVT_COMMAND_CHECKLISTBOX_TOGGLE event being emitted. @param item Index of item to check. @@ -93,5 +97,13 @@ public: @true if the item is to be checked, @false otherwise. */ void Check(int item, bool check = true); + + /** + Returns @true if the given item is checked, @false otherwise. + + @param item + Index of item whose check status is to be returned. + */ + bool IsChecked(unsigned int item) const; }; diff --git a/interface/choicdlg.h b/interface/choicdlg.h index 9fdc3d1a15..9e80604ee8 100644 --- a/interface/choicdlg.h +++ b/interface/choicdlg.h @@ -10,8 +10,8 @@ @class wxMultiChoiceDialog @wxheader{choicdlg.h} - This class represents a dialog that shows a list of strings, and allows - the user to select one or more. + This class represents a dialog that shows a list of strings, and allows the + user to select one or more. @library{wxbase} @category{cmndlg} @@ -53,11 +53,18 @@ public: @endStyleTable @remarks Use ShowModal() to show the dialog. + + @beginWxPythonOnly + + For Python the two parameters @a n and @a choices are collapsed into a + multi parameter @a choices which is expected to be a Python list of + strings. + + @endWxPythonOnly */ wxMultiChoiceDialog(wxWindow* parent, const wxString& message, const wxString& caption, - int n, - const wxString* choices, + int n, const wxString* choices, long style = wxCHOICEDLG_STYLE, const wxPoint& pos = wxDefaultPosition); wxMultiChoiceDialog(wxWindow* parent, @@ -90,8 +97,8 @@ public: @class wxSingleChoiceDialog @wxheader{choicdlg.h} - This class represents a dialog that shows a list of strings, and allows - the user to select one. Double-clicking on a list item is equivalent to + This class represents a dialog that shows a list of strings, and allows the + user to select one. Double-clicking on a list item is equivalent to single-clicking and then pressing OK. @library{wxbase} @@ -118,8 +125,8 @@ public: @param choices An array of strings, or a string list, containing the choices. @param clientData - An array of client data to be associated with the items. - See GetSelectionClientData. + An array of client data to be associated with the items. See + GetSelectionClientData(). @param style A dialog style (bitlist) containing flags chosen from standard dialog styles and the ones listed below. The default value is @@ -138,11 +145,18 @@ public: @endStyleTable @remarks Use ShowModal() to show the dialog. + + @beginWxPythonOnly + + For Python the two parameters @a n and @a choices are collapsed into a + multi parameter @a choices which is expected to be a Python list of + strings. + + @endWxPythonOnly */ wxSingleChoiceDialog(wxWindow* parent, const wxString& message, const wxString& caption, - int n, - const wxString* choices, + int n, const wxString* choices, void** clientData = NULL, long style = wxCHOICEDLG_STYLE, const wxPoint& pos = wxDefaultPosition); diff --git a/interface/choice.h b/interface/choice.h index 48ff01128a..be6766bee6 100644 --- a/interface/choice.h +++ b/interface/choice.h @@ -11,7 +11,7 @@ @wxheader{choice.h} A choice item is used to select one of a list of strings. Unlike a - listbox, only the selection is visible until the user pulls down the + wxListBox, only the selection is visible until the user pulls down the menu of choices. @beginStyleTable @@ -27,13 +27,20 @@ @library{wxcore} @category{ctrl} - @appearance{choice.png} + @see wxListBox, wxComboBox, wxCommandEvent */ class wxChoice : public wxControlWithItems { public: + /** + Default constructor. + + @see Create(), wxValidator + */ + wxChoice(); + //@{ /** Constructor, creating and showing a choice. @@ -45,8 +52,7 @@ public: @param pos Window position. @param size - Window size. If wxDefaultSize is specified then the choice is - sized + Window size. If wxDefaultSize is specified then the choice is sized appropriately. @param n Number of strings with which to initialise the choice control. @@ -60,8 +66,14 @@ public: Window name. @see Create(), wxValidator + + @beginWxPythonOnly + + The wxChoice constructor in wxPython reduces the @a n and @a choices + arguments to a single argument, which is a list of strings. + + @endWxPythonOnly */ - wxChoice(); wxChoice(wxWindow* parent, wxWindowID id, const wxPoint& pos, const wxSize& size, int n, @@ -105,22 +117,22 @@ public: /** Gets the number of columns in this choice item. - @remarks This is implemented for Motif only and always returns 1 for the - other platforms. + @remarks This is implemented for Motif only and always returns 1 for + the other platforms. */ int GetColumns() const; /** - Unlike wxControlWithItems::GetSelection which only - returns the accepted selection value, i.e. the selection in the control once - the user closes the dropdown list, this function returns the current selection. - That is, while the dropdown list is shown, it returns the currently selected - item in it. When it is not shown, its result is the same as for the other - function. - - @wxsince{2.6.2} (before this version - wxControlWithItems::GetSelection itself behaved like - this). + Unlike wxControlWithItems::GetSelection() which only returns the + accepted selection value, i.e. the selection in the control once the + user closes the dropdown list, this function returns the current + selection. That is, while the dropdown list is shown, it returns the + currently selected item in it. When it is not shown, its result is the + same as for the other function. + + @wxsince{2.6.2} (before this version, + wxControlWithItems::GetSelection() itself behaved like + this). */ int GetCurrentSelection() const; @@ -129,6 +141,9 @@ public: @param n Number of columns. + + @remarks This is implemented for Motif only and doesn’t do anything + under other platforms. */ void SetColumns(int n = 1); }; diff --git a/interface/choicebk.h b/interface/choicebk.h index 4482f14dc2..dc8a9ee5db 100644 --- a/interface/choicebk.h +++ b/interface/choicebk.h @@ -10,20 +10,18 @@ @class wxChoicebook @wxheader{choicebk.h} - wxChoicebook is a class similar to wxNotebook but which - uses a wxChoice to show the labels instead of the - tabs. + wxChoicebook is a class similar to wxNotebook, but uses a wxChoice control + to show the labels instead of the tabs. - There is no documentation for this class yet but its usage is - identical to wxNotebook (except for the features clearly related to tabs - only), so please refer to that class documentation for now. You can also - use the @ref overview_samplenotebook "notebook sample" to see wxChoicebook in - action. + There is no documentation for this class yet but its usage is identical to + wxNotebook (except for the features clearly related to tabs only), so + please refer to that class documentation for now. You can also use the + @ref page_samples_notebook to see wxChoicebook in action. - wxChoicebook allows the use of wxBookCtrl::GetControlSizer, allowing a program - to add other controls next to the choice control. This is particularly useful - when screen space is restricted, as it often is when wxChoicebook is being - employed. + wxChoicebook allows the use of wxBookCtrlBase::GetControlSizer(), allowing + a program to add other controls next to the choice control. This is + particularly useful when screen space is restricted, as it often is when + wxChoicebook is being employed. @beginStyleTable @style{wxCHB_DEFAULT}: @@ -39,12 +37,25 @@ Place labels below the page area. @endStyleTable + @beginEventTable{wxChoicebookEvent} + @event{EVT_CHOICEBOOK_PAGE_CHANGED(id, func)}: + The page selection was changed. Processes a + wxEVT_COMMAND_LISTBOOK_PAGE_CHANGED event. + @event{EVT_CHOICEBOOK_PAGE_CHANGING(id, func)}: + The page selection is about to be changed. Processes a + wxEVT_COMMAND_CHOICEBOOK_PAGE_CHANGING event. This event can be + vetoed (using wxNotifyEvent::Veto()). + @endEventTable + @library{wxcore} @category{miscwnd} - @see wxBookCtrl(), wxNotebook, @ref overview_samplenotebook "notebook sample" + @see @ref overview_bookctrl, wxNotebook, @ref page_samples_notebook + + @todo Write up wxBookCtrlBase documentation, where most of this class' + functionality comes from. */ -class wxChoicebook : public wxBookCtrl overview +class wxChoicebook : public wxBookCtrlBase { public: //@{ @@ -58,5 +69,10 @@ public: long style = 0, const wxString& name = wxEmptyStr); //@} + + /** + Returns the wxChoice associated with the control. + */ + wxChoice * GetChoiceCtrl() const; }; -- 2.45.2