X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4cc4bfafe5a31cb96f35b3ec9b19fa2b0b3a4eef..3201a1046ba71ba8e5ef2ed694fde34d12f743f3:/interface/choicdlg.h diff --git a/interface/choicdlg.h b/interface/choicdlg.h index 44de9f59ea..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 @@ -10,15 +10,13 @@ @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,7 +24,7 @@ public: //@{ /** Constructor taking an array of wxString choices. - + @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 - 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. - - - - - - wxCANCEL - - - - + @style{wxCANCEL} Show a Cancel button. - - - - - - wxCENTRE - - - - + @style{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. - + @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, @@ -104,12 +78,12 @@ public: /** 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. @@ -118,6 +92,7 @@ public: }; + /** @class wxSingleChoiceDialog @wxheader{choicdlg.h} @@ -129,17 +104,16 @@ public: @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. - + Constructor, taking an array of wxString choices and optional client + data. + @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 - 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 - 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. - - - - - - wxCANCEL - - - - + @style{wxCANCEL} Show a Cancel button. - - - - - - wxCENTRE - - - - + @style{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. - + @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, + int n, const wxString* choices, void** clientData = NULL, long style = wxCHOICEDLG_STYLE, const wxPoint& pos = wxDefaultPosition); @@ -222,22 +172,22 @@ public: /** 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. @@ -246,14 +196,19 @@ 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, @@ -274,20 +229,27 @@ int wxGetSingleChoiceIndex(const wxString& message, 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 + 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 - @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. + + @header{wx/choicdlg.h} */ 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); + //@} +/** @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, @@ -338,20 +305,27 @@ wxString wxGetSingleChoiceData(const wxString& message, 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 + + 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 - @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. + + @header{wx/choicdlg.h} */ 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); + //@}