Finished initial review of the rest of the [co*] interface headers.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53152 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/combobox.h

@@ -10,16 +10,15 @@
     @class wxComboBox
     @wxheader{combobox.h}
 
-    A combobox is like a combination of an edit control and a listbox. It can be
+    A combobox is like a combination of an edit control and a listbox. It can
-    displayed as static list with editable or read-only text field; or a drop-down
+    be displayed as static list with editable or read-only text field; or a
-    list with
+    drop-down list with text field; or a drop-down list without a text field.
-    text field; or a drop-down list without a text field.
 
-    A combobox permits a single selection only. Combobox items are numbered from
+    A combobox permits a single selection only. Combobox items are numbered
-    zero.
+    from zero.
 
-    If you need a customized combobox, have a look at wxComboCtrl, wxOwnerDrawnComboBox,
+    If you need a customized combobox, have a look at wxComboCtrl,
-    wxComboPopup and the ready-to-use wxBitmapComboBox.
+    wxOwnerDrawnComboBox, wxComboPopup and the ready-to-use wxBitmapComboBox.
 
     @beginStyleTable
     @style{wxCB_SIMPLE}
@@ -27,9 +26,9 @@
     @style{wxCB_DROPDOWN}
            Creates a combobox with a drop-down list.
     @style{wxCB_READONLY}
-           Same as wxCB_DROPDOWN but only the strings specified as the
+           Same as wxCB_DROPDOWN but only the strings specified as the combobox
-           combobox choices can be selected, it is impossible to select (even
+           choices can be selected, it is impossible to select (even from a
-           from a program) a string which is not in the choices list.
+           program) a string which is not in the choices list.
     @style{wxCB_SORT}
            Sorts the entries in the list alphabetically.
     @style{wxTE_PROCESS_ENTER}
@@ -42,7 +41,7 @@
     @beginEventTable{wxCommandEvent}
     @event{EVT_COMBOBOX(id, func)}
            Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on
-           the list is selected. Note that calling GetValue returns the new
+           the list is selected. Note that calling GetValue() returns the new
            value of selection.
     @event{EVT_TEXT(id, func)}
            Process a wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text
@@ -55,13 +54,18 @@
 
     @library{wxcore}
     @category{ctrl}
-    @appearance{combobox.png}
+    <!-- @appearance{combobox.png} -->
 
     @see wxListBox, wxTextCtrl, wxChoice, wxCommandEvent
 */
 class wxComboBox : public wxControl, public wxItemContainer
 {
 public:
+    /**
+        Default constructor.
+    */
+    wxComboBox();
+
     //@{
     /**
         Constructor, creating and showing a combobox.
@@ -75,8 +79,7 @@ public:
         @param pos
             Window position.
         @param size
-            Window size. If wxDefaultSize is specified then the window is
+            Window size. If wxDefaultSize is specified then the window is sized
-        sized
             appropriately.
         @param n
             Number of strings with which to initialise the control.
@@ -89,9 +92,13 @@ public:
         @param name
             Window name.
 
+        @beginWxPythonOnly
+        The wxComboBox constructor in wxPython reduces the @a n and @a choices
+        arguments are to a single argument, which is a list of strings.
+        @endWxPythonOnly
+
         @see Create(), wxValidator
     */
-    wxComboBox();
     wxComboBox(wxWindow* parent, wxWindowID id,
                const wxString& value = "",
                const wxPoint& pos = wxDefaultPosition,
@@ -116,49 +123,10 @@ public:
     */
     ~wxComboBox();
 
-    /**
-        Returns @true if the combobox is editable and there is a text selection to copy
-        to the clipboard.
-        Only available on Windows.
-    */
-    bool CanCopy() const;
-
-    /**
-        Returns @true if the combobox is editable and there is a text selection to copy
-        to the clipboard.
-        Only available on Windows.
-    */
-    bool CanCut() const;
-
-    /**
-        Returns @true if the combobox is editable and there is text on the clipboard
-        that can be pasted into the
-        text field. Only available on Windows.
-    */
-    bool CanPaste() const;
-
-    /**
-        Returns @true if the combobox is editable and the last undo can be redone.
-        Only available on Windows.
-    */
-    bool CanRedo() const;
-
-    /**
-        Returns @true if the combobox is editable and the last edit can be undone.
-        Only available on Windows.
-    */
-    bool CanUndo() const;
-
-    /**
-        Copies the selected text to the clipboard.
-    */
-    void Copy();
-
     //@{
     /**
-        Creates the combobox for two-step construction. Derived classes
+        Creates the combobox for two-step construction. Derived classes should
-        should call or replace this function. See wxComboBox()
+        call or replace this function. See wxComboBox() for further details.
-        for further details.
     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxString& value = "",
@@ -178,23 +146,59 @@ public:
                 const wxString& name = "comboBox");
     //@}
 
+    /**
+        Returns @true if the combobox is editable and there is a text selection
+        to copy to the clipboard. Only available on Windows.
+    */
+    bool CanCopy() const;
+
+    /**
+        Returns @true if the combobox is editable and there is a text selection
+        to copy to the clipboard. Only available on Windows.
+    */
+    bool CanCut() const;
+
+    /**
+        Returns @true if the combobox is editable and there is text on the
+        clipboard that can be pasted into the text field. Only available on
+        Windows.
+    */
+    bool CanPaste() const;
+
+    /**
+        Returns @true if the combobox is editable and the last undo can be
+        redone. Only available on Windows.
+    */
+    bool CanRedo() const;
+
+    /**
+        Returns @true if the combobox is editable and the last edit can be
+        undone. Only available on Windows.
+    */
+    bool CanUndo() const;
+
+    /**
+        Copies the selected text to the clipboard.
+    */
+    void Copy();
+
     /**
         Copies the selected text to the clipboard and removes the selection.
     */
     void Cut();
 
     /**
-        This function does the same things as
+        This function does the same things as wxChoice::GetCurrentSelection()
-        wxChoice::GetCurrentSelection and
+        and returns the item currently selected in the dropdown list if it's
-        returns the item currently selected in the dropdown list if it's open or the
+        open or the same thing as wxControlWithItems::GetSelection() otherwise.
-        same thing as wxControlWithItems::GetSelection otherwise.
     */
     int GetCurrentSelection() const;
 
     /**
         Returns the insertion point for the combobox's text field.
+
         @note Under wxMSW, this function always returns 0 if the combobox
-        doesn't have the focus.
+              doesn't have the focus.
     */
     long GetInsertionPoint() const;
 
@@ -204,9 +208,10 @@ public:
     virtual wxTextPos GetLastPosition() const;
 
     /**
-        This is the same as wxTextCtrl::GetSelection
+        This is the same as wxTextCtrl::GetSelection() for the text control
-        for the text control which is part of the combobox. Notice that this is a
+        which is part of the combobox. Notice that this is a different method
-        different method from wxControlWithItems::GetSelection.
+        from wxControlWithItems::GetSelection().
+
         Currently this method is only implemented in wxMSW and wxGTK.
     */
     void GetSelection(long* from, long* to) const;
@@ -237,8 +242,8 @@ public:
     void Remove(long from, long to);
 
     /**
-        Replaces the text between two positions with the given text, in the combobox
+        Replaces the text between two positions with the given text, in the
-        text field.
+        combobox text field.
 
         @param from
             The first position.
@@ -269,6 +274,11 @@ public:
             The first position.
         @param to
             The second position.
+
+        @beginWxPythonOnly
+        This method is called SetMark() in wxPython, "SetSelection" is kept for
+        wxControlWithItems::SetSelection().
+        @endWxPythonOnly
     */
     void SetSelection(long from, long to);
 
@@ -276,7 +286,8 @@ public:
         Sets the text for the combobox text field.
 
         @note For a combobox with @c wxCB_READONLY style the string must be in
-              the combobox choices list, otherwise the call to SetValue() is ignored.
+              the combobox choices list, otherwise the call to SetValue() is
+              ignored.
 
         @param text
             The text to set.

interface/control.h

@@ -17,7 +17,6 @@
 
     @library{wxcore}
     @category{ctrl}
-    @appearance{control.png}
 
     @see wxValidator
 */
@@ -25,35 +24,38 @@ class wxControl : public wxWindow
 {
 public:
     /**
-        Simulates the effect of the user issuing a command to the item. See
+        Simulates the effect of the user issuing a command to the item.
-        wxCommandEvent.
+
+        @see wxCommandEvent
     */
     void Command(wxCommandEvent& event);
 
     /**
         Returns the control's text.
-        Note that the returned string contains the mnemonics (@c  characters) if
+
-        any, use GetLabelText() if they are
+        @note The returned string contains mnemonics ("&" characters) if it has
-        undesired.
+              any, use GetLabelText() if they are undesired.
     */
     wxString GetLabel() const;
 
-    //@{
     /**
-        Returns the control's label, or the given @a label string for the static
+        Returns the control's label without mnemonics.
-        version, without the mnemonics characters.
     */
     const wxString GetLabelText();
-    const static wxString  GetLabelText(const wxString& label);
+
-    //@}
+    /**
+        Returns the given @a label string without mnemonics.
+    */
+    static wxString GetLabelText(const wxString& label);
 
     /**
         Sets the item's text.
-        The @c  characters in the @a label are special and indicate that the
+
-        following character is a mnemonic for this control and can be used to activate
+        Any "&" characters in the @a label are special and indicate that the
-        it from the keyboard (typically by using @e Alt key in combination with
+        following character is a mnemonic for this control and can be used to
-        it). To insert a literal ampersand character, you need to double it, i.e. use
+        activate it from the keyboard (typically by using @e Alt key in
-        @c "".
+        combination with it). To insert a literal ampersand character, you need
+        to double it, i.e. use "&&".
     */
     void SetLabel(const wxString& label);
 };

interface/convauto.h

@@ -13,84 +13,84 @@
     This class implements a Unicode to/from multibyte converter capable of
     automatically recognizing the encoding of the multibyte text on input. The
     logic used is very simple: the class uses the BOM (byte order mark) if it's
-    present and tries to interpret the input as UTF-8 otherwise. If this fails, the
+    present and tries to interpret the input as UTF-8 otherwise. If this fails,
-    input is interpreted as being in the default multibyte encoding which can be
+    the input is interpreted as being in the default multibyte encoding which
-    specified in the constructor of a wxConvAuto instance and, in turn, defaults to
+    can be specified in the constructor of a wxConvAuto instance and, in turn,
-    the value of @ref wxConvAuto::getdefaultmbencoding GetFallbackEncoding if
+    defaults to the value of GetFallbackEncoding() if not explicitly given.
-    not explicitly given.
 
     For the conversion from Unicode to multibyte, the same encoding as was
     previously used for multibyte to Unicode conversion is reused. If there had
     been no previous multibyte to Unicode conversion, UTF-8 is used by default.
-    Notice that once the multibyte encoding is automatically detected, it doesn't
+    Notice that once the multibyte encoding is automatically detected, it
-    change any more, i.e. it is entirely determined by the first use of wxConvAuto
+    doesn't change any more, i.e. it is entirely determined by the first use of
-    object in the multibyte-to-Unicode direction. However creating a copy of
+    wxConvAuto object in the multibyte-to-Unicode direction. However creating a
-    wxConvAuto object, either via the usual copy constructor or assignment
+    copy of wxConvAuto object, either via the usual copy constructor or
-    operator, or using wxMBConv::Clone method, resets the
+    assignment operator, or using wxMBConv::Clone(), resets the automatically
-    automatically detected encoding so that the new copy will try to detect the
+    detected encoding so that the new copy will try to detect the encoding of
-    encoding of the input on first use.
+    the input on first use.
 
-    This class is used by default in wxWidgets classes and functions reading text
+    This class is used by default in wxWidgets classes and functions reading
-    from files such as wxFile, wxFFile,
+    text from files such as wxFile, wxFFile, wxTextFile, wxFileConfig and
-    wxTextFile, wxFileConfig and
+    various stream classes so the encoding set with its SetFallbackEncoding()
-    various stream classes so the encoding set with its
+    method will affect how these classes treat input files. In particular, use
-    @ref wxConvAuto::setdefaultmbencoding SetFallbackEncoding method will
+    this method to change the fall-back multibyte encoding used to interpret
-    affect how these classes treat input files. In particular, use this method
+    the contents of the files whose contents isn't valid UTF-8 or to disallow
-    to change the fall-back multibyte encoding used to interpret the contents of
+    it completely.
-    the files whose contents isn't valid UTF-8 or to disallow it completely.
 
     @library{wxbase}
-    @category{FIXME}
+    @category{data}
 
-    @see @ref overview_mbconvclasses "wxMBConv classes overview"
+    @see @ref overview_mbconv
 */
 class wxConvAuto : public wxMBConv
 {
 public:
     /**
-        Constructs a new wxConvAuto instance. The object will try to detect the input
+        Constructs a new wxConvAuto instance. The object will try to detect the
-        of the multibyte text given to its wxMBConv::ToWChar method
+        input of the multibyte text given to its wxMBConv::ToWChar() method
-        automatically but if the automatic detection of Unicode encodings fails, the
+        automatically but if the automatic detection of Unicode encodings
-        fall-back encoding @a enc will be used to interpret it as multibyte text.
+        fails, the fall-back encoding @a enc will be used to interpret it as
-        The default value of this parameter, @c wxFONTENCODING_DEFAULT means
+        multibyte text.
-        that the global default value which can be set using
+
-        @ref setdefaultmbencoding() SetFallbackEncoding method should be
+        The default value of @a enc, @c wxFONTENCODING_DEFAULT, means that the
-        used. As with that method, passing @c wxFONTENCODING_MAX inhibits using
+        global default value (which can be set using SetFallbackEncoding())
-        this encoding completely so the input multibyte text will always be interpreted
+        should be used. As with that method, passing @c wxFONTENCODING_MAX
-        as UTF-8 in the absence of BOM and the conversion will fail if the input
+        inhibits using this encoding completely so the input multibyte text
-        doesn't form valid UTF-8 sequence. Another special value is
+        will always be interpreted as UTF-8 in the absence of BOM and the
-        @c wxFONTENCODING_SYSTEM which means to use the encoding currently used
+        conversion will fail if the input doesn't form valid UTF-8 sequence.
-        on the user system, i.e. the encoding returned by
+
-        wxLocale::GetSystemEncoding. Any other
+        Another special value is @c wxFONTENCODING_SYSTEM which means to use
-        encoding will be used as is, e.g. passing @c wxFONTENCODING_ISO8859_1
+        the encoding currently used on the user system, i.e. the encoding
-        ensures that non-UTF-8 input will be treated as latin1.
+        returned by wxLocale::GetSystemEncoding(). Any other encoding will be
+        used as is, e.g. passing @c wxFONTENCODING_ISO8859_1 ensures that
+        non-UTF-8 input will be treated as latin1.
     */
     wxConvAuto(wxFontEncoding enc = wxFONTENCODING_DEFAULT);
 
     /**
-        Disable the use of the fall back encoding: if the input doesn't have a BOM and
+        Disable the use of the fall back encoding: if the input doesn't have a
-        is not valid UTF-8, the conversion will fail.
+        BOM and is not valid UTF-8, the conversion will fail.
     */
     static void DisableFallbackEncoding();
 
     /**
-        Returns the encoding used by default by wxConvAuto if no other encoding is
+        Returns the encoding used by default by wxConvAuto if no other encoding
-        explicitly specified in constructor. By default, returns
+        is explicitly specified in constructor. By default, returns
         @c wxFONTENCODING_ISO8859_1 but can be changed using
-        @ref setdefaultmbencoding() SetFallbackEncoding method.
+        SetFallbackEncoding().
     */
     static wxFontEncoding GetFallbackEncoding();
 
     /**
-        Changes the encoding used by default by wxConvAuto if no other encoding is
+        Changes the encoding used by default by wxConvAuto if no other encoding
-        explicitly specified in constructor. The default value, which can be retrieved
+        is explicitly specified in constructor. The default value, which can be
-        using @ref getdefaultmbencoding() GetFallbackEncoding, is
+        retrieved using GetFallbackEncoding(), is @c wxFONTENCODING_ISO8859_1.
-        @c wxFONTENCODING_ISO8859_1.
+
-        Special values of @c wxFONTENCODING_SYSTEM or
+        Special values of @c wxFONTENCODING_SYSTEM or @c wxFONTENCODING_MAX can
-        @c wxFONTENCODING_MAX can be used for @a enc parameter to use the
+        be used for the @a enc parameter to use the encoding of the current
-        encoding of the current user locale as fall back or not use any encoding for
+        user locale as fall back or not use any encoding for fall back at all,
-        fall back at all, respectively (just as with the similar constructor
+        respectively (just as with the similar constructor parameter). However,
-        parameter). However @c wxFONTENCODING_DEFAULT value cannot be used here.
+        @c wxFONTENCODING_DEFAULT can't be used here.
     */
     static void SetFallbackEncoding(wxFontEncoding enc);
 };