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

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

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

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