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

/////////////////////////////////////////////////////////////////////////////
// Name:        choicdlg.h
// Purpose:     interface of wx[Multi|Single]ChoiceDialog
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/**
    @class wxMultiChoiceDialog

    This class represents a dialog that shows a list of strings, and allows the
    user to select one or more.

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

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

        @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 GetSelection() 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.

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

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

        @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.
    */
    char* GetSelectionClientData() 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 = -1,
                           int y = -1,
                           bool centre = true,
                           int width = 150,
                           int height = 200,
                           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,
                           bool centre = true,
                           int width = 150,
                           int height = 200,
                           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 = -1,
                           int y = -1,
                           bool centre = true,
                           int width = 150,
                           int height = 200
                           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,
                           bool centre = true,
                           int width = 150,
                           int height = 200
                           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 = -1,
                               int y = -1,
                               bool centre = true,
                               int width = 150,
                               int height = 200
                               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,
                               bool centre = true,
                               int width = 150,
                               int height = 200
                               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 = -1,
                            int y = -1,
                            bool centre = true,
                            int width = 150,
                            int height = 200);

int wxGetSelectedChoices(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);

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