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

/////////////////////////////////////////////////////////////////////////////
// Name:        choicdlg.h
// Purpose:     interface of wx[Multi|Single]ChoiceDialog
// Author:      wxWidgets team
// RCS-ID:      $Id$
// 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

    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}

    @see @ref overview_cmndlg_multichoice, wxSingleChoiceDialog
*/
class wxMultiChoiceDialog : public wxDialog
{
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 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.

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

        @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,
                        const wxArrayString& choices,
                        long style = wxCHOICEDLG_STYLE,
                        const wxPoint& pos = wxDefaultPosition);
    //@}

    /**
        Returns array with indexes of selected items.
    */
    wxArrayInt GetSelections() const;

    /**
        Sets selected items from the array of selected items' indexes.
    */
    void SetSelections(const wxArrayInt& selections);

    /**
        Shows the dialog, returning either wxID_OK or wxID_CANCEL.
    */
    int ShowModal();
};


/**
    @class wxSingleChoiceDialog

    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}

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

        @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,
                         int n, const wxString* choices,
                         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.

        @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,
                         const wxArrayString& choices,
                         void** clientData = NULL,
                         long style = wxCHOICEDLG_STYLE,
                         const wxPoint& pos = wxDefaultPosition);
    //@}

    /**
        Returns the index of selected item.
    */
    int GetSelection() const;

    /**
        Returns the client data associated with the selection.

        @since 2.9.4
    */
    void* GetSelectionData() const;

    /**
        Returns the selected string.
    */
    wxString GetStringSelection() const;

    /**
        Sets the index of the initially selected item.
    */
    void SetSelection(int selection);

    /**
        Shows the dialog, returning either wxID_OK or wxID_CANCEL.
    */
    int ShowModal();
};


// ============================================================================
// Global functions/macros
// ============================================================================

/** @addtogroup group_funcmacro_dialog */
//@{

/**
    Same as wxGetSingleChoice() but returns the index representing the
    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 = wxDefaultCoord,
                           int y = wxDefaultCoord,
                           bool centre = true,
                           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 = wxDefaultCoord,
                           int y = wxDefaultCoord,
                           bool centre = true,
                           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);
//@}

/** @addtogroup 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 @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}

    @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 = wxDefaultCoord,
                           int y = wxDefaultCoord,
                           bool centre = true,
                           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 = wxDefaultCoord,
                           int y = wxDefaultCoord,
                           bool centre = true,
                           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);

//@}

/** @addtogroup group_funcmacro_dialog */
//@{

/**
    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}

    @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 = wxDefaultCoord,
                               int y = wxDefaultCoord,
                               bool centre = true,
                               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 = wxDefaultCoord,
                               int y = wxDefaultCoord,
                               bool centre = true,
                               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);

//@}

/** @addtogroup 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
    @c selections array. The initial contents of this array will be used to
    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
    @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}

    @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
*/
int wxGetSelectedChoices(wxArrayInt& selections,
                            const wxString& message,
                            const wxString& caption,
                            const wxArrayString& aChoices,
                            wxWindow* parent = NULL,
                            int x = wxDefaultCoord,
                            int y = wxDefaultCoord,
                            bool centre = true,
                            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 = wxDefaultCoord,
                            int y = wxDefaultCoord,
                            bool centre = true,
                            int width = wxCHOICE_WIDTH,
                            int height = wxCHOICE_HEIGHT);

//@}
Commit	Line	Data
23324ae1 FM	1	/////////////////////////////////////////////////////////////////////////////
23324ae1 FM	2	// Name: choicdlg.h
ba2874ff	3	// Purpose: interface of wx[Multi\|Single]ChoiceDialog
23324ae1 FM	4	// Author: wxWidgets team
23324ae1 FM	5	// RCS-ID: $Id$
526954c5	6	// Licence: wxWindows licence
23324ae1 FM	7	/////////////////////////////////////////////////////////////////////////////
23324ae1 FM	8
0b59366f VZ	9	/**
	10	Default width of the choice dialog.
	11	*/
	12	#define wxCHOICE_WIDTH 150
	13
	14	/**
	15	Default height of the choice dialog.
	16	*/
	17	#define wxCHOICE_HEIGHT 200
	18
	19	/**
	20	Default style of the choice dialog.
	21
	22	@remarks wxRESIZE_BORDER is not used under WinCE.
	23	*/
	24	#define wxCHOICEDLG_STYLE (wxDEFAULT_DIALOG_STYLE \| wxOK \| wxCANCEL \| wxCENTRE \| wxRESIZE_BORDER)
	25
	26
23324ae1 FM	27	/**
23324ae1 FM	28	@class wxMultiChoiceDialog
7c913512	29
bfac6166 BP	30	This class represents a dialog that shows a list of strings, and allows the
bfac6166 BP	31	user to select one or more.
7c913512	32
634034d5 VZ	33	@beginStyleTable
	34	@style{wxOK}
	35	Show an OK button.
	36	@style{wxCANCEL}
	37	Show a Cancel button.
	38	@style{wxCENTRE}
	39	Centre the message. Not Windows.
	40	@endStyleTable
	41
23324ae1 FM	42	@library{wxbase}
23324ae1 FM	43	@category{cmndlg}
7c913512	44
ba2874ff	45	@see @ref overview_cmndlg_multichoice, wxSingleChoiceDialog
23324ae1 FM	46	*/
	47	class wxMultiChoiceDialog : public wxDialog
	48	{
	49	public:
	50	//@{
	51	/**
	52	Constructor taking an array of wxString choices.
ba2874ff	53
7c913512	54	@param parent
4cc4bfaf	55	Parent window.
7c913512	56	@param message
4cc4bfaf	57	Message to show on the dialog.
7c913512	58	@param caption
4cc4bfaf	59	The dialog caption.
7c913512	60	@param n
4cc4bfaf	61	The number of choices.
7c913512	62	@param choices
4cc4bfaf	63	An array of strings, or a string list, containing the choices.
7c913512	64	@param style
4cc4bfaf	65	A dialog style (bitlist) containing flags chosen from standard
634034d5 VZ	66	dialog styles and the ones listed in the class documentation. The
	67	default value is equivalent to wxDEFAULT_DIALOG_STYLE \|
	68	wxRESIZE_BORDER \| wxOK \| wxCANCEL \| wxCENTRE.
ba2874ff BP	69	@param pos
	70	Dialog position. Not Windows.
	71
23324ae1	72	@remarks Use ShowModal() to show the dialog.
bfac6166 BP	73
	74	@beginWxPythonOnly
	75
	76	For Python the two parameters @a n and @a choices are collapsed into a
	77	multi parameter @a choices which is expected to be a Python list of
	78	strings.
	79
	80	@endWxPythonOnly
1058f652 MB	81
	82	@beginWxPerlOnly
	83	Not supported by wxPerl.
	84	@endWxPerlOnly
23324ae1 FM	85	*/
	86	wxMultiChoiceDialog(wxWindow* parent, const wxString& message,
	87	const wxString& caption,
bfac6166	88	int n, const wxString* choices,
23324ae1 FM	89	long style = wxCHOICEDLG_STYLE,
23324ae1 FM	90	const wxPoint& pos = wxDefaultPosition);
792255cc VZ	91	/**
	92	Constructor taking an array of wxString choices.
	93
	94	@param parent
	95	Parent window.
	96	@param message
	97	Message to show on the dialog.
	98	@param caption
	99	The dialog caption.
	100	@param choices
	101	An array of strings, or a string list, containing the choices.
	102	@param style
	103	A dialog style (bitlist) containing flags chosen from standard
634034d5 VZ	104	dialog styles and the ones listed in the class documentation. The
	105	default value is equivalent to wxDEFAULT_DIALOG_STYLE \|
	106	wxRESIZE_BORDER \| wxOK \| wxCANCEL \| wxCENTRE.
792255cc VZ	107	@param pos
	108	Dialog position. Not Windows.
	109
792255cc VZ	110	@remarks Use ShowModal() to show the dialog.
	111
	112	@beginWxPythonOnly
	113
	114	For Python the two parameters @a n and @a choices are collapsed into a
	115	multi parameter @a choices which is expected to be a Python list of
	116	strings.
	117
	118	@endWxPythonOnly
1058f652 MB	119
	120	@beginWxPerlOnly
	121	Use an array reference for the @a choices parameter.
	122	@endWxPerlOnly
792255cc	123	*/
7c913512 FM	124	wxMultiChoiceDialog(wxWindow* parent,
	125	const wxString& message,
	126	const wxString& caption,
	127	const wxArrayString& choices,
	128	long style = wxCHOICEDLG_STYLE,
	129	const wxPoint& pos = wxDefaultPosition);
23324ae1 FM	130	//@}
	131
	132	/**
	133	Returns array with indexes of selected items.
	134	*/
c68b8967	135	wxArrayInt GetSelections() const;
23324ae1 FM	136
	137	/**
	138	Sets selected items from the array of selected items' indexes.
	139	*/
b7e94bd7	140	void SetSelections(const wxArrayInt& selections);
23324ae1 FM	141
	142	/**
	143	Shows the dialog, returning either wxID_OK or wxID_CANCEL.
	144	*/
	145	int ShowModal();
	146	};
	147
	148
e54c96f1	149
23324ae1 FM	150	/**
23324ae1 FM	151	@class wxSingleChoiceDialog
7c913512	152
bfac6166 BP	153	This class represents a dialog that shows a list of strings, and allows the
bfac6166 BP	154	user to select one. Double-clicking on a list item is equivalent to
23324ae1	155	single-clicking and then pressing OK.
7c913512	156
634034d5 VZ	157	@beginStyleTable
	158	@style{wxOK}
	159	Show an OK button.
	160	@style{wxCANCEL}
	161	Show a Cancel button.
	162	@style{wxCENTRE}
	163	Centre the message. Not Windows.
	164	@endStyleTable
	165
23324ae1 FM	166	@library{wxbase}
23324ae1 FM	167	@category{cmndlg}
7c913512	168
ba2874ff	169	@see @ref overview_cmndlg_singlechoice, wxMultiChoiceDialog
23324ae1 FM	170	*/
	171	class wxSingleChoiceDialog : public wxDialog
	172	{
	173	public:
	174	//@{
	175	/**
ba2874ff BP	176	Constructor, taking an array of wxString choices and optional client
	177	data.
	178
7c913512	179	@param parent
4cc4bfaf	180	Parent window.
7c913512	181	@param message
4cc4bfaf	182	Message to show on the dialog.
7c913512	183	@param caption
4cc4bfaf	184	The dialog caption.
7c913512	185	@param n
4cc4bfaf	186	The number of choices.
7c913512	187	@param choices
4cc4bfaf	188	An array of strings, or a string list, containing the choices.
7c913512	189	@param clientData
bfac6166	190	An array of client data to be associated with the items. See
fc12b1f1	191	GetSelectionData().
7c913512	192	@param style
4cc4bfaf	193	A dialog style (bitlist) containing flags chosen from standard
634034d5 VZ	194	dialog styles and the ones listed in the class documentation. The
	195	default value is equivalent to wxDEFAULT_DIALOG_STYLE \|
	196	wxRESIZE_BORDER \| wxOK \| wxCANCEL \| wxCENTRE.
ba2874ff BP	197	@param pos
	198	Dialog position. Not Windows.
	199
23324ae1	200	@remarks Use ShowModal() to show the dialog.
bfac6166 BP	201
	202	@beginWxPythonOnly
	203
	204	For Python the two parameters @a n and @a choices are collapsed into a
	205	multi parameter @a choices which is expected to be a Python list of
	206	strings.
	207
	208	@endWxPythonOnly
1058f652 MB	209
	210	@beginWxPerlOnly
	211	Not supported by wxPerl.
	212	@endWxPerlOnly
23324ae1 FM	213	*/
	214	wxSingleChoiceDialog(wxWindow* parent, const wxString& message,
	215	const wxString& caption,
bfac6166	216	int n, const wxString* choices,
4cc4bfaf	217	void** clientData = NULL,
23324ae1 FM	218	long style = wxCHOICEDLG_STYLE,
23324ae1 FM	219	const wxPoint& pos = wxDefaultPosition);
792255cc VZ	220	/**
	221	Constructor, taking an array of wxString choices and optional client
	222	data.
	223
	224	@param parent
	225	Parent window.
	226	@param message
	227	Message to show on the dialog.
	228	@param caption
	229	The dialog caption.
	230	@param choices
	231	An array of strings, or a string list, containing the choices.
	232	@param clientData
	233	An array of client data to be associated with the items. See
fc12b1f1	234	GetSelectionData().
792255cc VZ	235	@param style
792255cc VZ	236	A dialog style (bitlist) containing flags chosen from standard
634034d5 VZ	237	dialog styles and the ones listed in the class documentation. The
	238	default value is equivalent to wxDEFAULT_DIALOG_STYLE \|
	239	wxRESIZE_BORDER \| wxOK \| wxCANCEL \| wxCENTRE.
792255cc VZ	240	@param pos
	241	Dialog position. Not Windows.
	242
792255cc VZ	243	@remarks Use ShowModal() to show the dialog.
	244
	245	@beginWxPythonOnly
	246
	247	For Python the two parameters @a n and @a choices are collapsed into a
	248	multi parameter @a choices which is expected to be a Python list of
	249	strings.
	250
	251	@endWxPythonOnly
1058f652 MB	252
	253	@beginWxPerlOnly
	254	Use an array reference for the @a choices parameter.
	255	@endWxPerlOnly
792255cc	256	*/
7c913512 FM	257	wxSingleChoiceDialog(wxWindow* parent,
	258	const wxString& message,
	259	const wxString& caption,
	260	const wxArrayString& choices,
4cc4bfaf	261	void** clientData = NULL,
7c913512 FM	262	long style = wxCHOICEDLG_STYLE,
7c913512 FM	263	const wxPoint& pos = wxDefaultPosition);
23324ae1 FM	264	//@}
	265
	266	/**
	267	Returns the index of selected item.
	268	*/
328f5751	269	int GetSelection() const;
23324ae1 FM	270
	271	/**
	272	Returns the client data associated with the selection.
fc12b1f1 VZ	273
fc12b1f1 VZ	274	@since 2.9.4
23324ae1	275	*/
fc12b1f1	276	void* GetSelectionData() const;
23324ae1 FM	277
	278	/**
	279	Returns the selected string.
	280	*/
328f5751	281	wxString GetStringSelection() const;
23324ae1 FM	282
	283	/**
	284	Sets the index of the initially selected item.
	285	*/
b7e94bd7	286	void SetSelection(int selection);
23324ae1 FM	287
	288	/**
	289	Shows the dialog, returning either wxID_OK or wxID_CANCEL.
	290	*/
	291	int ShowModal();
	292	};
	293
	294
e54c96f1	295
23324ae1 FM	296	// ============================================================================
	297	// Global functions/macros
	298	// ============================================================================
	299
b21126db	300	/** @addtogroup group_funcmacro_dialog */
23324ae1	301	//@{
ba2874ff	302
23324ae1	303	/**
ba2874ff BP	304	Same as wxGetSingleChoice() but returns the index representing the
	305	selected string. If the user pressed cancel, -1 is returned.
	306
	307	@header{wx/choicdlg.h}
1058f652 MB	308
	309	@beginWxPerlOnly
	310	Use an array reference for the @a aChoices parameter.
	311	@endWxPerlOnly
23324ae1 FM	312	*/
	313	int wxGetSingleChoiceIndex(const wxString& message,
	314	const wxString& caption,
	315	const wxArrayString& aChoices,
4cc4bfaf	316	wxWindow* parent = NULL,
0b59366f VZ	317	int x = wxDefaultCoord,
0b59366f VZ	318	int y = wxDefaultCoord,
4cc4bfaf	319	bool centre = true,
0b59366f VZ	320	int width = wxCHOICE_WIDTH,
0b59366f VZ	321	int height = wxCHOICE_HEIGHT,
697f4a96 VZ	322	int initialSelection = 0);
697f4a96 VZ	323
7c913512 FM	324	int wxGetSingleChoiceIndex(const wxString& message,
	325	const wxString& caption,
	326	int n,
	327	const wxString& choices[],
4cc4bfaf	328	wxWindow* parent = NULL,
0b59366f VZ	329	int x = wxDefaultCoord,
0b59366f VZ	330	int y = wxDefaultCoord,
4cc4bfaf	331	bool centre = true,
0b59366f VZ	332	int width = wxCHOICE_WIDTH,
0b59366f VZ	333	int height = wxCHOICE_HEIGHT,
697f4a96 VZ	334	int initialSelection = 0);
	335
	336
	337	int wxGetSingleChoiceIndex(const wxString& message,
	338	const wxString& caption,
	339	const wxArrayString& choices,
	340	int initialSelection,
	341	wxWindow *parent = NULL);
ba2874ff	342
697f4a96 VZ	343	int wxGetSingleChoiceIndex(const wxString& message,
	344	const wxString& caption,
	345	int n, const wxString *choices,
	346	int initialSelection,
	347	wxWindow *parent = NULL);
23324ae1 FM	348	//@}
23324ae1 FM	349
b21126db	350	/** @addtogroup group_funcmacro_dialog */
23324ae1	351	//@{
ba2874ff	352
23324ae1 FM	353	/**
23324ae1 FM	354	Pops up a dialog box containing a message, OK/Cancel buttons and a
ba2874ff BP	355	single-selection listbox. The user may choose an item and press OK to
	356	return a string or Cancel to return the empty string. Use
	357	wxGetSingleChoiceIndex() if empty string is a valid choice and if you want
	358	to be able to detect pressing Cancel reliably.
	359
	360	You may pass the list of strings to choose from either using @c choices
4cc4bfaf	361	which is an array of @a n strings for the listbox or by using a single
ba2874ff BP	362	@c aChoices parameter of type wxArrayString.
	363
	364	If @c centre is @true, the message text (which may include new line
23324ae1	365	characters) is centred; if @false, the message is left-justified.
ba2874ff BP	366
ba2874ff BP	367	@header{wx/choicdlg.h}
1058f652 MB	368
	369	@beginWxPerlOnly
	370	Use an array reference for the @a choices parameter.
	371	@endWxPerlOnly
23324ae1 FM	372	*/
	373	wxString wxGetSingleChoice(const wxString& message,
	374	const wxString& caption,
	375	const wxArrayString& aChoices,
4cc4bfaf	376	wxWindow* parent = NULL,
0b59366f VZ	377	int x = wxDefaultCoord,
0b59366f VZ	378	int y = wxDefaultCoord,
4cc4bfaf	379	bool centre = true,
0b59366f VZ	380	int width = wxCHOICE_WIDTH,
0b59366f VZ	381	int height = wxCHOICE_HEIGHT,
697f4a96	382	int initialSelection = 0);
7c913512 FM	383	wxString wxGetSingleChoice(const wxString& message,
	384	const wxString& caption,
	385	int n,
	386	const wxString& choices[],
4cc4bfaf	387	wxWindow* parent = NULL,
0b59366f VZ	388	int x = wxDefaultCoord,
0b59366f VZ	389	int y = wxDefaultCoord,
4cc4bfaf	390	bool centre = true,
0b59366f VZ	391	int width = wxCHOICE_WIDTH,
0b59366f VZ	392	int height = wxCHOICE_HEIGHT,
697f4a96 VZ	393	int initialSelection = 0);
	394
	395
	396	wxString wxGetSingleChoice(const wxString& message,
	397	const wxString& caption,
	398	const wxArrayString& choices,
	399	int initialSelection,
	400	wxWindow *parent = NULL);
	401
	402	wxString wxGetSingleChoice(const wxString& message,
	403	const wxString& caption,
	404	int n, const wxString *choices,
	405	int initialSelection,
	406	wxWindow *parent = NULL);
ba2874ff	407
23324ae1 FM	408	//@}
23324ae1 FM	409
b21126db	410	/** @addtogroup group_funcmacro_dialog */
23324ae1	411	//@{
ba2874ff	412
23324ae1	413	/**
ba2874ff BP	414	Same as wxGetSingleChoice but takes an array of client data pointers
	415	corresponding to the strings, and returns one of these pointers or @NULL
	416	if Cancel was pressed. The @c client_data array must have the same number
	417	of elements as @c choices or @c aChoices!
	418
	419	@header{wx/choicdlg.h}
1058f652 MB	420
	421	@beginWxPerlOnly
	422	Use an array reference for the @a aChoices and @a client_data parameters.
	423	@endWxPerlOnly
23324ae1 FM	424	*/
	425	wxString wxGetSingleChoiceData(const wxString& message,
	426	const wxString& caption,
	427	const wxArrayString& aChoices,
	428	const wxString& client_data[],
4cc4bfaf	429	wxWindow* parent = NULL,
0b59366f VZ	430	int x = wxDefaultCoord,
0b59366f VZ	431	int y = wxDefaultCoord,
4cc4bfaf	432	bool centre = true,
0b59366f VZ	433	int width = wxCHOICE_WIDTH,
0b59366f VZ	434	int height = wxCHOICE_HEIGHT,
697f4a96 VZ	435	int initialSelection = 0);
697f4a96 VZ	436
7c913512 FM	437	wxString wxGetSingleChoiceData(const wxString& message,
	438	const wxString& caption,
	439	int n,
	440	const wxString& choices[],
	441	const wxString& client_data[],
4cc4bfaf	442	wxWindow* parent = NULL,
0b59366f VZ	443	int x = wxDefaultCoord,
0b59366f VZ	444	int y = wxDefaultCoord,
4cc4bfaf	445	bool centre = true,
0b59366f VZ	446	int width = wxCHOICE_WIDTH,
0b59366f VZ	447	int height = wxCHOICE_HEIGHT,
697f4a96 VZ	448	int initialSelection = 0);
	449
	450	void* wxGetSingleChoiceData(const wxString& message,
	451	const wxString& caption,
	452	const wxArrayString& choices,
	453	void **client_data,
	454	int initialSelection,
	455	wxWindow *parent = NULL);
	456
	457	void* wxGetSingleChoiceData(const wxString& message,
	458	const wxString& caption,
	459	int n, const wxString *choices,
	460	void **client_data,
	461	int initialSelection,
	462	wxWindow *parent = NULL);
ba2874ff	463
23324ae1 FM	464	//@}
23324ae1 FM	465
b21126db	466	/** @addtogroup group_funcmacro_dialog */
23324ae1	467	//@{
ba2874ff	468
23324ae1 FM	469	/**
	470	Pops up a dialog box containing a message, OK/Cancel buttons and a
	471	multiple-selection listbox. The user may choose an arbitrary (including 0)
	472	number of items in the listbox whose indices will be returned in
ba2874ff	473	@c selections array. The initial contents of this array will be used to
e5cfb314 VZ	474	select the items when the dialog is shown. If the user cancels the dialog,
e5cfb314 VZ	475	the function returns -1 and @c selections array is left unchanged.
ba2874ff BP	476
ba2874ff BP	477	You may pass the list of strings to choose from either using @c choices
4cc4bfaf	478	which is an array of @a n strings for the listbox or by using a single
ba2874ff BP	479	@c aChoices parameter of type wxArrayString.
	480
	481	If @c centre is @true, the message text (which may include new line
23324ae1	482	characters) is centred; if @false, the message is left-justified.
ba2874ff BP	483
ba2874ff BP	484	@header{wx/choicdlg.h}
1058f652 MB	485
	486	@beginWxPerlOnly
	487	Use an array reference for the @a choices parameter.
	488	In wxPerl there is no @a selections parameter; the function
	489	returns an array containing the user selections.
	490	@endWxPerlOnly
23324ae1	491	*/
e5cfb314	492	int wxGetSelectedChoices(wxArrayInt& selections,
23324ae1 FM	493	const wxString& message,
	494	const wxString& caption,
	495	const wxArrayString& aChoices,
4cc4bfaf	496	wxWindow* parent = NULL,
0b59366f VZ	497	int x = wxDefaultCoord,
0b59366f VZ	498	int y = wxDefaultCoord,
4cc4bfaf	499	bool centre = true,
0b59366f VZ	500	int width = wxCHOICE_WIDTH,
0b59366f VZ	501	int height = wxCHOICE_HEIGHT);
697f4a96	502
e5cfb314	503	int wxGetSelectedChoices(wxArrayInt& selections,
7c913512 FM	504	const wxString& message,
	505	const wxString& caption,
	506	int n,
	507	const wxString& choices[],
4cc4bfaf	508	wxWindow* parent = NULL,
0b59366f VZ	509	int x = wxDefaultCoord,
0b59366f VZ	510	int y = wxDefaultCoord,
4cc4bfaf	511	bool centre = true,
0b59366f VZ	512	int width = wxCHOICE_WIDTH,
0b59366f VZ	513	int height = wxCHOICE_HEIGHT);
ba2874ff	514
23324ae1 FM	515	//@}
23324ae1 FM	516