adding a app-defined event seems to quit inner eventloops like eg the popup of the...

[wxWidgets.git] / interface / wx / choicdlg.h

diff --git a/interface/wx/choicdlg.h b/interface/wx/choicdlg.h
index 2a04b8c07083eef8db1042477cdf66fa1825392f..ff49376afcd425f88e698e2b0853aaf2a5045569 100644 (file)
--- a/interface/wx/choicdlg.h
+++ b/interface/wx/choicdlg.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wx[Multi|Single]ChoiceDialog
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wx[Multi|Single]ChoiceDialog
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**


@@ -60,12 +60,58 @@ public:
         strings.
 
         @endWxPythonOnly
         strings.
 
         @endWxPythonOnly

+
+        @beginWxPerlOnly
+        Not supported by wxPerl.
+        @endWxPerlOnly

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

+    /**
+        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 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.
+
+        @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
+
+        @beginWxPerlOnly
+        Use an array reference for the @a choices parameter.
+        @endWxPerlOnly
+    */

     wxMultiChoiceDialog(wxWindow* parent,
                         const wxString& message,
                         const wxString& caption,
     wxMultiChoiceDialog(wxWindow* parent,
                         const wxString& message,
                         const wxString& caption,


@@ -77,12 +123,12 @@ public:
     /**
         Returns array with indexes of selected items.
     */
     /**
         Returns array with indexes of selected items.
     */

-    wxArrayInt GetSelection() const;
+    wxArrayInt GetSelections() 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) const;
+    void SetSelections(const wxArrayInt& selections);

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


@@ -124,7 +170,7 @@ public:
             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
             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().
+            GetSelectionData().

         @param style
             A dialog style (bitlist) containing flags chosen from standard
             dialog styles and the ones listed below. The default value is
         @param style
             A dialog style (bitlist) containing flags chosen from standard
             dialog styles and the ones listed below. The default value is


@@ -151,6 +197,10 @@ public:
         strings.
 
         @endWxPythonOnly
         strings.
 
         @endWxPythonOnly

+
+        @beginWxPerlOnly
+        Not supported by wxPerl.
+        @endWxPerlOnly

     */
     wxSingleChoiceDialog(wxWindow* parent, const wxString& message,
                          const wxString& caption,
     */
     wxSingleChoiceDialog(wxWindow* parent, const wxString& message,
                          const wxString& caption,


@@ -158,6 +208,52 @@ public:
                          void** clientData = NULL,
                          long style = wxCHOICEDLG_STYLE,
                          const wxPoint& pos = wxDefaultPosition);
                          void** clientData = NULL,
                          long style = wxCHOICEDLG_STYLE,
                          const wxPoint& pos = wxDefaultPosition);

+    /**
+        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 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
+            GetSelectionData().
+        @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.
+
+        @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
+
+        @beginWxPerlOnly
+        Use an array reference for the @a choices parameter.
+        @endWxPerlOnly
+    */

     wxSingleChoiceDialog(wxWindow* parent,
                          const wxString& message,
                          const wxString& caption,
     wxSingleChoiceDialog(wxWindow* parent,
                          const wxString& message,
                          const wxString& caption,


@@ -174,8 +270,10 @@ public:
 
     /**
         Returns the client data associated with the selection.
 
     /**
         Returns the client data associated with the selection.

+
+        @since 2.9.4

     */
     */

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

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


@@ -185,7 +283,7 @@ public:
     /**
         Sets the index of the initially selected item.
     */
     /**
         Sets the index of the initially selected item.
     */

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

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


@@ -199,7 +297,7 @@ public:
 // Global functions/macros
 // ============================================================================
 
 // Global functions/macros
 // ============================================================================
 

-/** @ingroup group_funcmacro_dialog */
+/** @addtogroup group_funcmacro_dialog */

 //@{
 
 /**
 //@{
 
 /**


@@ -207,6 +305,10 @@ public:
     selected string. If the user pressed cancel, -1 is returned.
 
     @header{wx/choicdlg.h}
     selected string. If the user pressed cancel, -1 is returned.
 
     @header{wx/choicdlg.h}

+
+    @beginWxPerlOnly
+    Use an array reference for the @a aChoices parameter.
+    @endWxPerlOnly

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


@@ -216,7 +318,9 @@ int wxGetSingleChoiceIndex(const wxString& message,
                            int y = -1,
                            bool centre = true,
                            int width = 150,
                            int y = -1,
                            bool centre = true,
                            int width = 150,

-                           int height = 200);
+                           int height = 200,
+                           int initialSelection = 0);
+

 int wxGetSingleChoiceIndex(const wxString& message,
                            const wxString& caption,
                            int n,
 int wxGetSingleChoiceIndex(const wxString& message,
                            const wxString& caption,
                            int n,


@@ -226,11 +330,24 @@ int wxGetSingleChoiceIndex(const wxString& message,
                            int y = -1,
                            bool centre = true,
                            int width = 150,
                            int y = -1,
                            bool centre = true,
                            int width = 150,

-                           int height = 200);
+                           int height = 200,
+                           int initialSelection = 0);
+
+
+int wxGetSingleChoiceIndex(const wxString& message,
+                           const wxString& caption,
+                           const wxArrayString& choices,
+                           int initialSelection,
+                           wxWindow *parent = NULL);

 
 

+int wxGetSingleChoiceIndex(const wxString& message,
+                           const wxString& caption,
+                           int n, const wxString *choices,
+                           int initialSelection,
+                           wxWindow *parent = NULL);

 //@}
 
 //@}
 

-/** @ingroup group_funcmacro_dialog */
+/** @addtogroup group_funcmacro_dialog */

 //@{
 
 /**
 //@{
 
 /**


@@ -248,6 +365,10 @@ int wxGetSingleChoiceIndex(const wxString& message,
     characters) is centred; if @false, the message is left-justified.
 
     @header{wx/choicdlg.h}
     characters) is centred; if @false, the message is left-justified.
 
     @header{wx/choicdlg.h}

+
+    @beginWxPerlOnly
+    Use an array reference for the @a choices parameter.
+    @endWxPerlOnly

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


@@ -257,7 +378,8 @@ wxString wxGetSingleChoice(const wxString& message,
                            int y = -1,
                            bool centre = true,
                            int width = 150,
                            int y = -1,
                            bool centre = true,
                            int width = 150,

-                           int height = 200);
+                           int height = 200
+                           int initialSelection = 0);

 wxString wxGetSingleChoice(const wxString& message,
                            const wxString& caption,
                            int n,
 wxString wxGetSingleChoice(const wxString& message,
                            const wxString& caption,
                            int n,


@@ -267,11 +389,25 @@ wxString wxGetSingleChoice(const wxString& message,
                            int y = -1,
                            bool centre = true,
                            int width = 150,
                            int y = -1,
                            bool centre = true,
                            int width = 150,

-                           int height = 200);
+                           int height = 200
+                           int initialSelection = 0);
+
+
+wxString wxGetSingleChoice(const wxString& message,
+                           const wxString& caption,
+                           const wxArrayString& choices,
+                           int initialSelection,
+                           wxWindow *parent = NULL);
+
+wxString wxGetSingleChoice(const wxString& message,
+                           const wxString& caption,
+                           int n, const wxString *choices,
+                           int initialSelection,
+                           wxWindow *parent = NULL);

 
 //@}
 
 
 //@}
 

-/** @ingroup group_funcmacro_dialog */
+/** @addtogroup group_funcmacro_dialog */

 //@{
 
 /**
 //@{
 
 /**


@@ -281,6 +417,10 @@ wxString wxGetSingleChoice(const wxString& message,
     of elements as @c choices or @c aChoices!
 
     @header{wx/choicdlg.h}
     of elements as @c choices or @c aChoices!
 
     @header{wx/choicdlg.h}

+
+    @beginWxPerlOnly
+    Use an array reference for the @a aChoices and @a client_data parameters.
+    @endWxPerlOnly

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


@@ -291,7 +431,9 @@ wxString wxGetSingleChoiceData(const wxString& message,
                                int y = -1,
                                bool centre = true,
                                int width = 150,
                                int y = -1,
                                bool centre = true,
                                int width = 150,

-                               int height = 200);
+                               int height = 200
+                               int initialSelection = 0);
+

 wxString wxGetSingleChoiceData(const wxString& message,
                                const wxString& caption,
                                int n,
 wxString wxGetSingleChoiceData(const wxString& message,
                                const wxString& caption,
                                int n,


@@ -302,11 +444,26 @@ wxString wxGetSingleChoiceData(const wxString& message,
                                int y = -1,
                                bool centre = true,
                                int width = 150,
                                int y = -1,
                                bool centre = true,
                                int width = 150,

-                               int height = 200);
+                               int height = 200
+                               int initialSelection = 0);
+
+void* wxGetSingleChoiceData(const wxString& message,
+                            const wxString& caption,
+                            const wxArrayString& choices,
+                            void **client_data,
+                            int initialSelection,
+                            wxWindow *parent = NULL);
+
+void* wxGetSingleChoiceData(const wxString& message,
+                            const wxString& caption,
+                            int n, const wxString *choices,
+                            void **client_data,
+                            int initialSelection,
+                            wxWindow *parent = NULL);

 
 //@}
 
 
 //@}
 

-/** @ingroup group_funcmacro_dialog */
+/** @addtogroup group_funcmacro_dialog */

 //@{
 
 /**
 //@{
 
 /**


@@ -314,7 +471,8 @@ wxString wxGetSingleChoiceData(const wxString& message,
     multiple-selection listbox. The user may choose an arbitrary (including 0)
     number of items in the listbox whose indices will be returned in
     @c selections array. The initial contents of this array will be used to
     multiple-selection listbox. The user may choose an arbitrary (including 0)
     number of items in the listbox whose indices will be returned in
     @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. If the user cancels the dialog,
+    the function returns -1 and @c selections array is left unchanged.

 
     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
 
     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


@@ -324,8 +482,14 @@ wxString wxGetSingleChoiceData(const wxString& message,
     characters) is centred; if @false, the message is left-justified.
 
     @header{wx/choicdlg.h}
     characters) is centred; if @false, the message is left-justified.
 
     @header{wx/choicdlg.h}

+
+    @beginWxPerlOnly
+    Use an array reference for the @a choices parameter.
+    In wxPerl there is no @a selections parameter; the function
+    returns an array containing the user selections.
+    @endWxPerlOnly

 */
 */

-size_t wxGetMultipleChoices(wxArrayInt& selections,
+int wxGetSelectedChoices(wxArrayInt& selections,

                             const wxString& message,
                             const wxString& caption,
                             const wxArrayString& aChoices,
                             const wxString& message,
                             const wxString& caption,
                             const wxArrayString& aChoices,


@@ -335,7 +499,8 @@ size_t wxGetMultipleChoices(wxArrayInt& selections,
                             bool centre = true,
                             int width = 150,
                             int height = 200);
                             bool centre = true,
                             int width = 150,
                             int height = 200);

-size_t wxGetMultipleChoices(wxArrayInt& selections,
+
+int wxGetSelectedChoices(wxArrayInt& selections,

                             const wxString& message,
                             const wxString& caption,
                             int n,
                             const wxString& message,
                             const wxString& caption,
                             int n,