mac paths updated

[wxWidgets.git] / interface / choicdlg.h

diff --git a/interface/choicdlg.h b/interface/choicdlg.h
index c09dd08c1c24bc99986669900c8bf6f22b9ca8f6..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


@@ -9,16 +9,14 @@
 /**
     @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,73 +24,66 @@ public:
     //@{
     /**
         Constructor taking an array of wxString choices.
     //@{
     /**
         Constructor taking an array of wxString choices.

-        
-        @param parent 
-        Parent window.
-        
-        @param message 
-        Message to show on the dialog.
-        
-        @param caption 
-        The dialog caption.
-        
-        @param n 
-        The number of choices.
-        
-        @param choices 
-        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
-        
-        
-        Show an OK button.
-        
-        wxCANCEL
-        
-        
-        Show a Cancel button.
-        
-        wxCENTRE
-        
-        
-        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.
-        
+
+        @param parent
+            Parent window.
+        @param message
+            Message to show on the dialog.
+        @param caption
+            The dialog caption.
+        @param n
+            The number of choices.
+        @param choices
+            An array of strings, or a string list, containing the choices.
+        @param style
+            A dialog style (bitlist) containing flags chosen from standard
+            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.
+        @style{wxCANCEL}
+            Show a Cancel button.
+        @style{wxCENTRE}
+            Centre the message. 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,
+                        const wxString& message,
+                        const wxString& caption,
+                        const wxArrayString& choices,

                         long style = wxCHOICEDLG_STYLE,
                         const wxPoint& pos = wxDefaultPosition);
                         long style = wxCHOICEDLG_STYLE,
                         const wxPoint& pos = wxDefaultPosition);

-        wxMultiChoiceDialog(wxWindow* parent,
-                            const wxString& message,
-                            const wxString& caption,
-                            const wxArrayString& choices,
-                            long style = wxCHOICEDLG_STYLE,
-                            const wxPoint& pos = wxDefaultPosition);

     //@}
 
     /**
         Returns array with indexes of selected items.
     */
     //@}
 
     /**
         Returns array with indexes of selected items.
     */

-    wxArrayInt GetSelection();
+    wxArrayInt GetSelection() const;

 
     /**
         Sets selected items from the array of selected items' indexes.
     */
 
     /**
         Sets selected items from the array of selected items' indexes.
     */

-    void SetSelections(const wxArrayInt& selections);
+    void SetSelections(const wxArrayInt& selections) const;

 
     /**
         Shows the dialog, returning either wxID_OK or wxID_CANCEL.
 
     /**
         Shows the dialog, returning either wxID_OK or wxID_CANCEL.


@@ -101,110 +92,102 @@ public:
 };
 
 
 };
 
 

+

 /**
     @class wxSingleChoiceDialog
     @wxheader{choicdlg.h}
 /**
     @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
     single-clicking and then pressing OK.
     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}
     @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.
-        
-        @param parent 
-        Parent window.
-        
-        @param message 
-        Message to show on the dialog.
-        
-        @param caption 
-        The dialog caption.
-        
-        @param n 
-        The number of choices.
-        
-        @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.
-        
-        @param style 
-        A dialog style (bitlist) containing flags chosen from standard
-        dialog styles and the following:
-        
-        
-        wxOK
-        
-        
-        Show an OK button.
-        
-        wxCANCEL
-        
-        
-        Show a Cancel button.
-        
-        wxCENTRE
-        
-        
-        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.
-        
+        Constructor, taking an array of wxString choices and optional client
+        data.
+
+        @param parent
+            Parent window.
+        @param message
+            Message to show on the dialog.
+        @param caption
+            The dialog caption.
+        @param n
+            The number of choices.
+        @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().
+        @param style
+            A dialog style (bitlist) containing flags chosen from standard
+            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.
+        @style{wxCANCEL}
+            Show a Cancel button.
+        @style{wxCENTRE}
+            Centre the message. 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,
-                         void** clientData = @NULL,
+                         int n, const wxString* choices,
+                         void** clientData = NULL,
+                         long style = wxCHOICEDLG_STYLE,
+                         const wxPoint& pos = wxDefaultPosition);
+    wxSingleChoiceDialog(wxWindow* parent,
+                         const wxString& message,
+                         const wxString& caption,
+                         const wxArrayString& choices,
+                         void** clientData = NULL,

                          long style = wxCHOICEDLG_STYLE,
                          const wxPoint& pos = wxDefaultPosition);
                          long style = wxCHOICEDLG_STYLE,
                          const wxPoint& pos = wxDefaultPosition);

-        wxSingleChoiceDialog(wxWindow* parent,
-                             const wxString& message,
-                             const wxString& caption,
-                             const wxArrayString& choices,
-                             void** clientData = @NULL,
-                             long style = wxCHOICEDLG_STYLE,
-                             const wxPoint& pos = wxDefaultPosition);

     //@}
 
     /**
         Returns the index of selected item.
     */
     //@}
 
     /**
         Returns the index of selected item.
     */

-    int GetSelection();
+    int GetSelection() const;

 
     /**
         Returns the client data associated with the selection.
     */
 
     /**
         Returns the client data associated with the selection.
     */

-    char* GetSelectionClientData();
+    char* GetSelectionClientData() const;

 
     /**
         Returns the selected string.
     */
 
     /**
         Returns the selected string.
     */

-    wxString GetStringSelection();
+    wxString GetStringSelection() const;

 
     /**
         Sets the index of the initially selected item.
     */
 
     /**
         Sets the index of the initially selected item.
     */

-    void SetSelection(int selection);
+    void SetSelection(int selection) const;

 
     /**
         Shows the dialog, returning either wxID_OK or wxID_CANCEL.
 
     /**
         Shows the dialog, returning either wxID_OK or wxID_CANCEL.


@@ -213,137 +196,158 @@ 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,
                            const wxArrayString& aChoices,
 */
 int wxGetSingleChoiceIndex(const wxString& message,
                            const wxString& caption,
                            const wxArrayString& aChoices,

-                           wxWindow * parent = @NULL,
+                           wxWindow* parent = NULL,

                            int x = -1,
                            int y = -1,
                            int x = -1,
                            int y = -1,

-                           bool centre = @true,
-                           int width=150,
-                           int height=200);
-    int wxGetSingleChoiceIndex(const wxString& message,
-                               const wxString& caption,
-                               int n,
-                               const wxString& choices[],
-                               wxWindow * parent = @NULL,
-                               int x = -1,
-                               int y = -1,
-                               bool centre = @true,
-                               int width=150,
-                               int height=200);
+                           bool centre = true,
+                           int width = 150,
+                           int height = 200);
+int wxGetSingleChoiceIndex(const wxString& message,
+                           const wxString& caption,
+                           int n,
+                           const wxString& choices[],
+                           wxWindow* parent = NULL,
+                           int x = -1,
+                           int y = -1,
+                           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
-    which is an array of @e n strings for the listbox or by using a single
-    @e aChoices parameter of type wxArrayString.
-    
-    If @e centre is @true, the message text (which may include new line
+    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
+    @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,
                            const wxArrayString& aChoices,
 */
 wxString wxGetSingleChoice(const wxString& message,
                            const wxString& caption,
                            const wxArrayString& aChoices,

-                           wxWindow * parent = @NULL,
+                           wxWindow* parent = NULL,

                            int x = -1,
                            int y = -1,
                            int x = -1,
                            int y = -1,

-                           bool centre = @true,
-                           int width=150,
-                           int height=200);
-    wxString wxGetSingleChoice(const wxString& message,
-                               const wxString& caption,
-                               int n,
-                               const wxString& choices[],
-                               wxWindow * parent = @NULL,
-                               int x = -1,
-                               int y = -1,
-                               bool centre = @true,
-                               int width=150,
-                               int height=200);
+                           bool centre = true,
+                           int width = 150,
+                           int height = 200);
+wxString wxGetSingleChoice(const wxString& message,
+                           const wxString& caption,
+                           int n,
+                           const wxString& choices[],
+                           wxWindow* parent = NULL,
+                           int x = -1,
+                           int y = -1,
+                           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,
                                const wxArrayString& aChoices,
                                const wxString& client_data[],
 */
 wxString wxGetSingleChoiceData(const wxString& message,
                                const wxString& caption,
                                const wxArrayString& aChoices,
                                const wxString& client_data[],

-                               wxWindow * parent = @NULL,
+                               wxWindow* parent = NULL,

                                int x = -1,
                                int y = -1,
                                int x = -1,
                                int y = -1,

-                               bool centre = @true,
-                               int width=150,
-                               int height=200);
-    wxString wxGetSingleChoiceData(const wxString& message,
-                                   const wxString& caption,
-                                   int n,
-                                   const wxString& choices[],
-                                   const wxString& client_data[],
-                                   wxWindow * parent = @NULL,
-                                   int x = -1,
-                                   int y = -1,
-                                   bool centre = @true,
-                                   int width=150,
-                                   int height=200);
+                               bool centre = true,
+                               int width = 150,
+                               int height = 200);
+wxString wxGetSingleChoiceData(const wxString& message,
+                               const wxString& caption,
+                               int n,
+                               const wxString& choices[],
+                               const wxString& client_data[],
+                               wxWindow* parent = NULL,
+                               int x = -1,
+                               int y = -1,
+                               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
-    which is an array of @e n strings for the listbox or by using a single
-    @e aChoices parameter of type wxArrayString.
-    
-    If @e centre is @true, the message text (which may include new line
+
+    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
+    @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,
                             const wxString& caption,
                             const wxArrayString& aChoices,
 */
 size_t wxGetMultipleChoices(wxArrayInt& selections,
                             const wxString& message,
                             const wxString& caption,
                             const wxArrayString& aChoices,

-                            wxWindow * parent = @NULL,
+                            wxWindow* parent = NULL,

                             int x = -1,
                             int y = -1,
                             int x = -1,
                             int y = -1,

-                            bool centre = @true,
-                            int width=150,
-                            int height=200);
-    size_t wxGetMultipleChoices(wxArrayInt& selections,
-                                const wxString& message,
-                                const wxString& caption,
-                                int n,
-                                const wxString& choices[],
-                                wxWindow * parent = @NULL,
-                                int x = -1,
-                                int y = -1,
-                                bool centre = @true,
-                                int width=150,
-                                int height=200);
+                            bool centre = true,
+                            int width = 150,
+                            int height = 200);
+size_t wxGetMultipleChoices(wxArrayInt& selections,
+                            const wxString& message,
+                            const wxString& caption,
+                            int n,
+                            const wxString& choices[],
+                            wxWindow* parent = NULL,
+                            int x = -1,
+                            int y = -1,
+                            bool centre = true,
+                            int width = 150,
+                            int height = 200);
+

 //@}
 
 //@}