X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..575821fad84c6f60602ffce6f8f6e727247ce651:/interface/wx/choicdlg.h diff --git a/interface/wx/choicdlg.h b/interface/wx/choicdlg.h index 734cecc83c..80262fbda6 100644 --- a/interface/wx/choicdlg.h +++ b/interface/wx/choicdlg.h @@ -3,16 +3,42 @@ // Purpose: interface of wx[Multi|Single]ChoiceDialog // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// +/** + Default width of the choice dialog. +*/ +#define wxCHOICE_WIDTH 150 + +/** + Default height of the choice dialog. +*/ +#define wxCHOICE_HEIGHT 200 + +/** + Default style of the choice dialog. + + @remarks wxRESIZE_BORDER is not used under WinCE. +*/ +#define wxCHOICEDLG_STYLE (wxDEFAULT_DIALOG_STYLE | wxOK | wxCANCEL | wxCENTRE | wxRESIZE_BORDER) + + /** @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. + @beginStyleTable + @style{wxOK} + Show an OK button. + @style{wxCANCEL} + Show a Cancel button. + @style{wxCENTRE} + Centre the message. Not Windows. + @endStyleTable + @library{wxbase} @category{cmndlg} @@ -37,36 +63,48 @@ public: 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. + dialog styles and the ones listed in the class documentation. 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 + 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); + /** + 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 styles and the ones listed in the class documentation. The + default value is equivalent to wxDEFAULT_DIALOG_STYLE | + wxRESIZE_BORDER | wxOK | wxCANCEL | wxCENTRE. + @param pos + Dialog position. Not Windows. + + @remarks Use ShowModal() to show the dialog. + + @beginWxPerlOnly + Use an array reference for the @a choices parameter. + @endWxPerlOnly + */ wxMultiChoiceDialog(wxWindow* parent, const wxString& message, const wxString& caption, @@ -78,12 +116,12 @@ public: /** Returns array with indexes of selected items. */ - wxArrayInt GetSelection() const; + wxArrayInt GetSelections() const; /** 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. @@ -95,12 +133,20 @@ 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. + @beginStyleTable + @style{wxOK} + Show an OK button. + @style{wxCANCEL} + Show a Cancel button. + @style{wxCENTRE} + Centre the message. Not Windows. + @endStyleTable + @library{wxbase} @category{cmndlg} @@ -126,33 +172,20 @@ 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 - GetSelectionClientData(). + 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. + dialog styles and the ones listed in the class documentation. 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 + Not supported by wxPerl. + @endWxPerlOnly */ wxSingleChoiceDialog(wxWindow* parent, const wxString& message, const wxString& caption, @@ -160,6 +193,35 @@ public: 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 in the class documentation. The + default value is equivalent to wxDEFAULT_DIALOG_STYLE | + wxRESIZE_BORDER | wxOK | wxCANCEL | wxCENTRE. + @param pos + Dialog position. Not Windows. + + @remarks Use ShowModal() to show the dialog. + + @beginWxPerlOnly + Use an array reference for the @a choices parameter. + @endWxPerlOnly + */ wxSingleChoiceDialog(wxWindow* parent, const wxString& message, const wxString& caption, @@ -176,8 +238,10 @@ public: /** Returns the client data associated with the selection. + + @since 2.9.4 */ - char* GetSelectionClientData() const; + void* GetSelectionData() const; /** Returns the selected string. @@ -187,7 +251,7 @@ public: /** 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. @@ -201,7 +265,7 @@ public: // Global functions/macros // ============================================================================ -/** @ingroup group_funcmacro_dialog */ +/** @addtogroup group_funcmacro_dialog */ //@{ /** @@ -209,30 +273,49 @@ public: 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, const wxArrayString& aChoices, wxWindow* parent = NULL, - int x = -1, - int y = -1, + int x = wxDefaultCoord, + int y = wxDefaultCoord, bool centre = true, - int width = 150, - int height = 200); + int width = wxCHOICE_WIDTH, + int height = wxCHOICE_HEIGHT, + int initialSelection = 0); + int wxGetSingleChoiceIndex(const wxString& message, const wxString& caption, int n, const wxString& choices[], wxWindow* parent = NULL, - int x = -1, - int y = -1, + int x = wxDefaultCoord, + int y = wxDefaultCoord, bool centre = true, - int width = 150, - int height = 200); + int width = wxCHOICE_WIDTH, + int height = wxCHOICE_HEIGHT, + 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 */ //@{ /** @@ -250,30 +333,49 @@ int wxGetSingleChoiceIndex(const wxString& message, 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, const wxArrayString& aChoices, wxWindow* parent = NULL, - int x = -1, - int y = -1, + int x = wxDefaultCoord, + int y = wxDefaultCoord, bool centre = true, - int width = 150, - int height = 200); + int width = wxCHOICE_WIDTH, + int height = wxCHOICE_HEIGHT, + int initialSelection = 0); wxString wxGetSingleChoice(const wxString& message, const wxString& caption, int n, const wxString& choices[], wxWindow* parent = NULL, - int x = -1, - int y = -1, + int x = wxDefaultCoord, + int y = wxDefaultCoord, bool centre = true, - int width = 150, - int height = 200); + int width = wxCHOICE_WIDTH, + int height = wxCHOICE_HEIGHT, + 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 */ //@{ /** @@ -283,32 +385,53 @@ wxString wxGetSingleChoice(const wxString& message, 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, const wxArrayString& aChoices, const wxString& client_data[], wxWindow* parent = NULL, - int x = -1, - int y = -1, + int x = wxDefaultCoord, + int y = wxDefaultCoord, bool centre = true, - int width = 150, - int height = 200); + int width = wxCHOICE_WIDTH, + int height = wxCHOICE_HEIGHT, + int initialSelection = 0); + 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, + int x = wxDefaultCoord, + int y = wxDefaultCoord, bool centre = true, - int width = 150, - int height = 200); + int width = wxCHOICE_WIDTH, + int height = wxCHOICE_HEIGHT, + 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 */ //@{ /** @@ -316,7 +439,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 - 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 @@ -326,28 +450,35 @@ wxString wxGetSingleChoiceData(const wxString& message, 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, wxWindow* parent = NULL, - int x = -1, - int y = -1, + int x = wxDefaultCoord, + int y = wxDefaultCoord, bool centre = true, - int width = 150, - int height = 200); -size_t wxGetMultipleChoices(wxArrayInt& selections, + int width = wxCHOICE_WIDTH, + int height = wxCHOICE_HEIGHT); + +int wxGetSelectedChoices(wxArrayInt& selections, const wxString& message, const wxString& caption, int n, const wxString& choices[], wxWindow* parent = NULL, - int x = -1, - int y = -1, + int x = wxDefaultCoord, + int y = wxDefaultCoord, bool centre = true, - int width = 150, - int height = 200); + int width = wxCHOICE_WIDTH, + int height = wxCHOICE_HEIGHT); //@}