X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4cc4bfafe5a31cb96f35b3ec9b19fa2b0b3a4eef..bf956fac0e89eab569c41a9f121e728958767de7:/interface/choicdlg.h diff --git a/interface/choicdlg.h b/interface/choicdlg.h index 44de9f59ea..9fdc3d1a15 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 @@ -16,9 +16,7 @@ @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,52 +37,21 @@ 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. */ wxMultiChoiceDialog(wxWindow* parent, const wxString& message, @@ -104,12 +71,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,28 +85,28 @@ 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 + 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. - + Constructor, taking an array of wxString choices and optional client + data. + @param parent Parent window. @param message @@ -155,52 +122,21 @@ public: 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. */ wxSingleChoiceDialog(wxWindow* parent, const wxString& message, @@ -222,22 +158,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 +182,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 +215,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 +256,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 +291,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 +334,6 @@ size_t wxGetMultipleChoices(wxArrayInt& selections, bool centre = true, int width = 150, int height = 200); + //@}