More initial reviews of [u*-v*] interface headers.

[wxWidgets.git] / interface / choicdlg.h

diff --git a/interface/choicdlg.h b/interface/choicdlg.h
index 138c60c88f42ed88d0c16a7a94672f730040e17c..734cecc83c0582ea6fc5a3855f7cf8666e02ab07 100644 (file)
--- a/interface/choicdlg.h
+++ b/interface/choicdlg.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        choicdlg.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        choicdlg.h

-// Purpose:     documentation for wxMultiChoiceDialog class
+// Purpose:     interface of wx[Multi|Single]ChoiceDialog

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license


@@ -10,15 +10,13 @@
     @class wxMultiChoiceDialog
     @wxheader{choicdlg.h}
 
     @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}
 
 
     @library{wxbase}
     @category{cmndlg}
 

-    @seealso
-    @ref overview_wxmultichoicedialogoverview "wxMultiChoiceDialog overview",
-    wxSingleChoiceDialog
+    @see @ref overview_cmndlg_multichoice, wxSingleChoiceDialog

 */
 class wxMultiChoiceDialog : public wxDialog
 {
 */
 class wxMultiChoiceDialog : public wxDialog
 {


@@ -26,7 +24,7 @@ public:
     //@{
     /**
         Constructor taking an array of wxString choices.
     //@{
     /**
         Constructor taking an array of wxString choices.

-        
+

         @param parent
             Parent window.
         @param message
         @param parent
             Parent window.
         @param message


@@ -39,58 +37,34 @@ public:
             An array of strings, or a string list, containing the choices.
         @param style
             A dialog style (bitlist) containing flags chosen from standard
             An array of strings, or a string list, containing the choices.
         @param style
             A dialog style (bitlist) containing flags chosen from standard

-            dialog styles and the following:
-        
-        
-        
-        
-        
-        
-        
-            wxOK
-        
-        
-        
-        
+            dialog style and the ones listed below. The default value is
+            equivalent to wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER | wxOK |
+            wxCANCEL | wxCENTRE.
+        @param pos
+            Dialog position. Not Windows.
+
+        @beginStyleTable
+        @style{wxOK}

             Show an OK button.
             Show an OK button.

-        
-        
-        
-        
-        
-            wxCANCEL
-        
-        
-        
-        
+        @style{wxCANCEL}

             Show a Cancel button.
             Show a Cancel button.

-        
-        
-        
-        
-        
-            wxCENTRE
-        
-        
-        
-        
+        @style{wxCENTRE}

             Centre the message. Not Windows.
             Centre the message. Not Windows.

-        
-        
-        
-        
-        
-            The default value is equivalent to wxDEFAULT_DIALOG_STYLE |
-        wxRESIZE_BORDER |  wxOK |  wxCANCEL |  wxCENTRE.
-        @param pos
-            Dialog position. Not Windows.
-        
+        @endStyleTable
+

         @remarks Use ShowModal() to show the dialog.
         @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,
     */
     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,
                         long style = wxCHOICEDLG_STYLE,
                         const wxPoint& pos = wxDefaultPosition);
     wxMultiChoiceDialog(wxWindow* parent,


@@ -118,6 +92,7 @@ public:
 };
 
 
 };
 
 

+

 /**
     @class wxSingleChoiceDialog
     @wxheader{choicdlg.h}
 /**
     @class wxSingleChoiceDialog
     @wxheader{choicdlg.h}


@@ -129,17 +104,16 @@ public:
     @library{wxbase}
     @category{cmndlg}
 
     @library{wxbase}
     @category{cmndlg}
 

-    @seealso
-    @ref overview_wxsinglechoicedialogoverview "wxSingleChoiceDialog overview",
-    wxMultiChoiceDialog
+    @see @ref overview_cmndlg_singlechoice, wxMultiChoiceDialog

 */
 class wxSingleChoiceDialog : public wxDialog
 {
 public:
     //@{
     /**
 */
 class wxSingleChoiceDialog : public wxDialog
 {
 public:
     //@{
     /**

-        Constructor, taking an array of wxString choices and optional client data.
-        
+        Constructor, taking an array of wxString choices and optional client
+        data.
+

         @param parent
             Parent window.
         @param message
         @param parent
             Parent window.
         @param message


@@ -151,62 +125,38 @@ public:
         @param choices
             An array of strings, or a string list, containing the choices.
         @param clientData
         @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
         @param style
             A dialog style (bitlist) containing flags chosen from standard

-            dialog styles and the following:
-        
-        
-        
-        
-        
-        
-        
-            wxOK
-        
-        
-        
-        
+            dialog styles and the ones listed below. The default value is
+            equivalent to wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER | wxOK |
+            wxCANCEL | wxCENTRE.
+        @param pos
+            Dialog position. Not Windows.
+
+        @beginStyleTable
+        @style{wxOK}

             Show an OK button.
             Show an OK button.

-        
-        
-        
-        
-        
-            wxCANCEL
-        
-        
-        
-        
+        @style{wxCANCEL}

             Show a Cancel button.
             Show a Cancel button.

-        
-        
-        
-        
-        
-            wxCENTRE
-        
-        
-        
-        
+        @style{wxCENTRE}

             Centre the message. Not Windows.
             Centre the message. Not Windows.

-        
-        
-        
-        
-        
-            The default value is equivalent to wxDEFAULT_DIALOG_STYLE |
-        wxRESIZE_BORDER |  wxOK |  wxCANCEL |  wxCENTRE.
-        @param pos
-            Dialog position. Not Windows.
-        
+        @endStyleTable
+

         @remarks Use ShowModal() to show the dialog.
         @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,
     */
     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);
                          void** clientData = NULL,
                          long style = wxCHOICEDLG_STYLE,
                          const wxPoint& pos = wxDefaultPosition);


@@ -246,14 +196,19 @@ public:
 };
 
 
 };
 
 

+

 // ============================================================================
 // Global functions/macros
 // ============================================================================
 
 // ============================================================================
 // Global functions/macros
 // ============================================================================
 

+/** @ingroup group_funcmacro_dialog */

 //@{
 //@{

+

 /**
 /**

-    As @b wxGetSingleChoice but returns the index representing the selected
-    string. If the user pressed cancel, -1 is returned.
+    Same as wxGetSingleChoice() but returns the index representing the
+    selected string. If the user pressed cancel, -1 is returned.
+
+    @header{wx/choicdlg.h}

 */
 int wxGetSingleChoiceIndex(const wxString& message,
                            const wxString& caption,
 */
 int wxGetSingleChoiceIndex(const wxString& message,
                            const wxString& caption,


@@ -274,20 +229,27 @@ int wxGetSingleChoiceIndex(const wxString& message,
                            bool centre = true,
                            int width = 150,
                            int height = 200);
                            bool centre = true,
                            int width = 150,
                            int height = 200);

+

 //@}
 
 //@}
 

+/** @ingroup group_funcmacro_dialog */

 //@{
 //@{

+

 /**
     Pops up a dialog box containing a message, OK/Cancel buttons and a
 /**
     Pops up a dialog box containing a message, OK/Cancel buttons and a

-    single-selection listbox. The user may choose an item and press OK to return a
-    string or Cancel to return the empty string. Use
-    wxGetSingleChoiceIndex if empty string is a
-    valid choice and if you want to be able to detect pressing Cancel reliably.
-    You may pass the list of strings to choose from either using @e choices
+    single-selection listbox. The user may choose an item and press OK to
+    return a string or Cancel to return the empty string. Use
+    wxGetSingleChoiceIndex() if empty string is a valid choice and if you want
+    to be able to detect pressing Cancel reliably.
+
+    You may pass the list of strings to choose from either using @c choices

     which is an array of @a n strings for the listbox or by using a single
     which is an array of @a n strings for the listbox or by using a single

-    @a aChoices parameter of type wxArrayString.
-    If @a centre is @true, the message text (which may include new line
+    @c aChoices parameter of type wxArrayString.
+
+    If @c centre is @true, the message text (which may include new line

     characters) is centred; if @false, the message is left-justified.
     characters) is centred; if @false, the message is left-justified.

+
+    @header{wx/choicdlg.h}

 */
 wxString wxGetSingleChoice(const wxString& message,
                            const wxString& caption,
 */
 wxString wxGetSingleChoice(const wxString& message,
                            const wxString& caption,


@@ -308,14 +270,19 @@ wxString wxGetSingleChoice(const wxString& message,
                            bool centre = true,
                            int width = 150,
                            int height = 200);
                            bool centre = true,
                            int width = 150,
                            int height = 200);

+

 //@}
 
 //@}
 

+/** @ingroup group_funcmacro_dialog */

 //@{
 //@{

+

 /**
 /**

-    As @b wxGetSingleChoice but takes an array of client data pointers
-    corresponding to the strings, and returns one of these pointers or @NULL if
-    Cancel was pressed. The @e client_data array must have the same number of
-    elements as @e choices or @e aChoices!
+    Same as wxGetSingleChoice but takes an array of client data pointers
+    corresponding to the strings, and returns one of these pointers or @NULL
+    if Cancel was pressed. The @c client_data array must have the same number
+    of elements as @c choices or @c aChoices!
+
+    @header{wx/choicdlg.h}

 */
 wxString wxGetSingleChoiceData(const wxString& message,
                                const wxString& caption,
 */
 wxString wxGetSingleChoiceData(const wxString& message,
                                const wxString& caption,


@@ -338,20 +305,27 @@ wxString wxGetSingleChoiceData(const wxString& message,
                                bool centre = true,
                                int width = 150,
                                int height = 200);
                                bool centre = true,
                                int width = 150,
                                int height = 200);

+

 //@}
 
 //@}
 

+/** @ingroup group_funcmacro_dialog */

 //@{
 //@{

+

 /**
     Pops up a dialog box containing a message, OK/Cancel buttons and a
     multiple-selection listbox. The user may choose an arbitrary (including 0)
     number of items in the listbox whose indices will be returned in
 /**
     Pops up a dialog box containing a message, OK/Cancel buttons and a
     multiple-selection listbox. The user may choose an arbitrary (including 0)
     number of items in the listbox whose indices will be returned in

-    @e selection array. The initial contents of this array will be used to
+    @c selections array. The initial contents of this array will be used to

     select the items when the dialog is shown.
     select the items when the dialog is shown.

-    You may pass the list of strings to choose from either using @e choices
+
+    You may pass the list of strings to choose from either using @c choices

     which is an array of @a n strings for the listbox or by using a single
     which is an array of @a n strings for the listbox or by using a single

-    @a aChoices parameter of type wxArrayString.
-    If @a centre is @true, the message text (which may include new line
+    @c aChoices parameter of type wxArrayString.
+
+    If @c centre is @true, the message text (which may include new line

     characters) is centred; if @false, the message is left-justified.
     characters) is centred; if @false, the message is left-justified.

+
+    @header{wx/choicdlg.h}

 */
 size_t wxGetMultipleChoices(wxArrayInt& selections,
                             const wxString& message,
 */
 size_t wxGetMultipleChoices(wxArrayInt& selections,
                             const wxString& message,


@@ -374,5 +348,6 @@ size_t wxGetMultipleChoices(wxArrayInt& selections,
                             bool centre = true,
                             int width = 150,
                             int height = 200);
                             bool centre = true,
                             int width = 150,
                             int height = 200);

+

 //@}
 
 //@}