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

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

    @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 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
            GetSelectionData().
        @param style
            A dialog style (bitlist) containing flags chosen from standard
            dialog styles and the ones listed below. The default value is
            equivalent to wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER | wxOK |
            wxCANCEL | wxCENTRE.
        @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.

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