X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/23324ae1c7938ba904770fc456d3c07764b9c5e9..3201a1046ba71ba8e5ef2ed694fde34d12f743f3:/interface/choicdlg.h?ds=sidebyside diff --git a/interface/choicdlg.h b/interface/choicdlg.h index c09dd08c1c..734cecc83c 100644 --- a/interface/choicdlg.h +++ b/interface/choicdlg.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: choicdlg.h -// Purpose: documentation for wxMultiChoiceDialog class +// Purpose: interface of wx[Multi|Single]ChoiceDialog // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -9,16 +9,14 @@ /** @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} - - @seealso - @ref overview_wxmultichoicedialogoverview "wxMultiChoiceDialog overview", - wxSingleChoiceDialog + + @see @ref overview_cmndlg_multichoice, wxSingleChoiceDialog */ class wxMultiChoiceDialog : public wxDialog { @@ -26,73 +24,66 @@ public: //@{ /** 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. + + @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, + const wxString& message, + const wxString& caption, + const wxArrayString& 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); //@} /** Returns array with indexes of selected items. */ - wxArrayInt GetSelection(); + wxArrayInt GetSelection() const; /** 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. @@ -101,110 +92,102 @@ 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 single-clicking and then pressing OK. - + @library{wxbase} @category{cmndlg} - - @seealso - @ref overview_wxsinglechoicedialogoverview "wxSingleChoiceDialog overview", - wxMultiChoiceDialog + + @see @ref overview_cmndlg_singlechoice, wxMultiChoiceDialog */ 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. + + @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, - 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); - 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. */ - int GetSelection(); + int GetSelection() const; /** Returns the client data associated with the selection. */ - char* GetSelectionClientData(); + char* GetSelectionClientData() const; /** Returns the selected string. */ - wxString GetStringSelection(); + wxString GetStringSelection() const; /** 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. @@ -213,137 +196,158 @@ public: }; + // ============================================================================ // 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, - wxWindow * parent = @NULL, + wxWindow* parent = NULL, 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 - 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. + + @header{wx/choicdlg.h} */ wxString wxGetSingleChoice(const wxString& message, const wxString& caption, const wxArrayString& aChoices, - wxWindow * parent = @NULL, + wxWindow* parent = NULL, 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[], - wxWindow * parent = @NULL, + wxWindow* parent = NULL, 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 - @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. - - 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. + + @header{wx/choicdlg.h} */ 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, - 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); + //@}