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

/////////////////////////////////////////////////////////////////////////////
// Name:        control.h
// Purpose:     interface of wxControl
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows licence
/////////////////////////////////////////////////////////////////////////////

/**
    Flags used by wxControl::Ellipsize function.
*/
enum wxEllipsizeFlags
{
    /// No special flags.
    wxELLIPSIZE_FLAGS_NONE = 0,

    /**
        Take mnemonics into account when calculating the text width.

        With this flag when calculating the size of the passed string,
        mnemonics characters (see wxControl::SetLabel) will be automatically
        reduced to a single character. This leads to correct calculations only
        if the string passed to Ellipsize() will be used with
        wxControl::SetLabel. If you don't want ampersand to be interpreted as
        mnemonics (e.g. because you use wxControl::SetLabelText) then don't use
        this flag.
     */
    wxELLIPSIZE_FLAGS_PROCESS_MNEMONICS = 1,

    /**
        Expand tabs in spaces when calculating the text width.

        This flag tells wxControl::Ellipsize() to calculate the width of tab
        characters @c '\\t' as 6 spaces.
     */
    wxELLIPSIZE_FLAGS_EXPAND_TABS = 2,

    /// The default flags for wxControl::Ellipsize.
    wxELLIPSIZE_FLAGS_DEFAULT = wxELLIPSIZE_FLAGS_PROCESS_MNEMONICS|
                                wxELLIPSIZE_FLAGS_EXPAND_TABS
};


/**
    The different ellipsization modes supported by the
    wxControl::Ellipsize function.
*/
enum wxEllipsizeMode
{
    /// Don't ellipsize the text at all. @since 2.9.1
    wxELLIPSIZE_NONE,

    /// Put the ellipsis at the start of the string, if the string needs ellipsization.
    wxELLIPSIZE_START,

    /// Put the ellipsis in the middle of the string, if the string needs ellipsization.
    wxELLIPSIZE_MIDDLE,

    /// Put the ellipsis at the end of the string, if the string needs ellipsization.
    wxELLIPSIZE_END
};

/**
    @class wxControl

    This is the base class for a control or "widget".

    A control is generally a small window which processes user input and/or
    displays one or more item of data.

    @beginEventEmissionTable{wxClipboardTextEvent}
    @event{EVT_TEXT_COPY(id, func)}
           Some or all of the controls content was copied to the clipboard.
    @event{EVT_TEXT_CUT(id, func)}
           Some or all of the controls content was cut (i.e. copied and
           deleted).
    @event{EVT_TEXT_PASTE(id, func)}
           Clipboard content was pasted into the control.
    @endEventTable

    @library{wxcore}
    @category{ctrl}

    @see wxValidator
*/
class wxControl : public wxWindow
{
public:
    /**
        Simulates the effect of the user issuing a command to the item.

        @see wxCommandEvent
    */
    virtual void Command(wxCommandEvent& event);

    /**
        Returns the control's label, as it was passed to SetLabel().

        Note that the returned string may contains mnemonics ("&" characters) if they were
        passed to the SetLabel() function; use GetLabelText() if they are undesired.

        Also note that the returned string is always the string which was passed to
        SetLabel() but may be different from the string passed to SetLabelText()
        (since this last one escapes mnemonic characters).
    */
    wxString GetLabel() const;

    /**
        Returns the control's label without mnemonics.

        Note that because of the stripping of the mnemonics the returned string may differ
        from the string which was passed to SetLabel() but should always be the same which
        was passed to SetLabelText().
    */
    wxString GetLabelText() const;

    /**
        Sets the control's label.

        All "&" characters in the @a label are special and indicate that the
        following character is a @e mnemonic for this control and can be used to
        activate it from the keyboard (typically by using @e Alt key in
        combination with it). To insert a literal ampersand character, you need
        to double it, i.e. use "&&". If this behaviour is undesirable, use
        SetLabelText() instead.
    */
    void SetLabel(const wxString& label);

    /**
        Sets the control's label to exactly the given string.

        Unlike SetLabel(), this function shows exactly the @a text passed to it
        in the control, without interpreting ampersands in it in any way.
        Notice that it means that the control can't have any mnemonic defined
        for it using this function.

        @see EscapeMnemonics()
     */
    void SetLabelText(const wxString& text);

    // NB: when writing docs for the following function remember that Doxygen
    //     will always expand HTML entities (e.g. &quot;) and thus we need to
    //     write e.g. "&amp;lt;" to have in the output the "&lt;" string.

    /**
        Sets the controls label to a string using markup.

        Simple markup supported by this function can be used to apply different
        fonts or colours to different parts of the control label when supported.
        If markup is not supported by the control or platform, it is simply
        stripped and SetLabel() is used with the resulting string.

        For example,
        @code
            wxStaticText *text;
            ...
            text->SetLabelMarkup("<b>&amp;Bed</b> &amp;mp; "
                                 "<span foreground='red'>breakfast</span> "
                                 "available <big>HERE</big>");
        @endcode
        would show the string using bold, red and big for the corresponding
        words under wxGTK but will simply show the string "Bed &amp; breakfast
        available HERE" on the other platforms. In any case, the "B" of "Bed"
        will be underlined to indicate that it can be used as a mnemonic for
        this control.

        The supported tags are:
        <TABLE>
            <TR>
                <TD><b>Tag</b></TD>
                <TD><b>Description</b></TD>
            </TR>
            <TR>
                <TD>&lt;b&gt;</TD>
                <TD>bold text</TD>
            </TR>
            <TR>
                <TD>&lt;big&gt;</TD>
                <TD>bigger text</TD>
            </TR>
            <TR>
                <TD>&lt;i&gt;</TD>
                <TD>italic text</TD>
            </TR>
            <TR>
                <TD>&lt;s&gt;</TD>
                <TD>strike-through text</TD>
            </TR>
            <TR>
                <TD>&lt;small&gt;</TD>
                <TD>smaller text</TD>
            </TR>
            <TR>
                <TD>&lt;tt&gt;</TD>
                <TD>monospaced text</TD>
            </TR>
            <TR>
                <TD>&lt;u&gt;</TD>
                <TD>underlined text</TD>
            </TR>
            <TR>
                <TD>&lt;span&gt;</TD>
                <TD>generic formatter tag, see the table below for supported
                attributes.
                </TD>
            </TR>
        </TABLE>

        Supported @c &lt;span&gt; attributes:
        <TABLE>
            <TR>
                <TD><b>Name</b></TD>
                <TD><b>Description</b></TD>
            </TR>
            <TR>
                <TD>foreground, fgcolor, color</TD>
                <TD>Foreground text colour, can be a name or RGB value.</TD>
            </TR>
            <TR>
                <TD>background, bgcolor</TD>
                <TD>Background text colour, can be a name or RGB value.</TD>
            </TR>
            <TR>
                <TD>font_family, face</TD>
                <TD>Font face name.</TD>
            </TR>
            <TR>
                <TD>font_weight, weight</TD>
                <TD>Numeric value in 0..900 range or one of "ultralight",
                "light", "normal" (all meaning non-bold), "bold", "ultrabold"
                and "heavy" (all meaning bold).</TD>
            </TR>
            <TR>
                <TD>font_style, style</TD>
                <TD>Either "oblique" or "italic" (both with the same meaning)
                or "normal".</TD>
            </TR>
            <TR>
                <TD>size</TD>
                <TD>The font size can be specified either as "smaller" or
                "larger" relatively to the current font, as a CSS font size
                name ("xx-small", "x-small", "small", "medium", "large",
                "x-large" or "xx-large") or as a number giving font size in
                1024th parts of a point, i.e. 10240 for a 10pt font.</TD>
            </TR>
        </TABLE>

        This markup language is a strict subset of Pango markup (described at
        http://library.gnome.org/devel/pango/unstable/PangoMarkupFormat.html)
        and any tags and span attributes not documented above can't be used
        under non-GTK platforms.

        Also note that you need to escape the following special characters:
        <TABLE>
            <TR>
                <TD><b>Special character</b></TD>
                <TD><b>Escape as</b></TD>
            </TR>
            <TR>
                <TD>@c &amp;</TD>
                <TD>@c &amp;amp; or as @c &amp;&amp;</TD>
            </TR>
            <TR>
                <TD>@c &apos;</TD>
                <TD>@c &amp;apos;</TD>
            </TR>
            <TR>
                <TD>@c &quot;</TD>
                <TD>@c &amp;quot;</TD>
            </TR>
            <TR>
                <TD>@c &lt;</TD>
                <TD>@c &amp;lt;</TD>
            </TR>
            <TR>
                <TD>@c &gt;</TD>
                <TD>@c &amp;gt;</TD>
            </TR>
        </TABLE>

        The non-escaped ampersand @c &amp; characters are interpreted as
        mnemonics as with wxControl::SetLabel.


        @param markup
            String containing markup for the label. It may contain markup tags
            described above and newline characters but currently only wxGTK and
            wxOSX support multiline labels with markup, the generic
            implementation (also used in wxMSW) only handles single line markup
            labels. Notice that the string must be well-formed (e.g. all tags
            must be correctly closed) and won't be shown at all otherwise.
        @return
            @true if the new label was set (even if markup in it was ignored)
            or @false if we failed to parse the markup. In this case the label
            remains unchanged.


        Currently wxButton supports markup in all major ports (wxMSW, wxGTK and
        wxOSX/Cocoa) while wxStaticText supports it in wxGTK and wxOSX and its
        generic version (which can be used under MSW if markup support is
        required). Extending support to more controls is planned in the future.

        @since 2.9.2
    */
    bool SetLabelMarkup(const wxString& markup);


public:     // static functions
    
    /**
        Returns the given @a label string without mnemonics ("&" characters).
    */
    static wxString GetLabelText(const wxString& label);

    /**
        Returns the given @a str string without mnemonics ("&" characters).
        
        @note This function is identical to GetLabelText() and is provided
              mostly for symmetry with EscapeMnemonics().
    */
    static wxString RemoveMnemonics(const wxString& str);

    /**
        Escapes the special mnemonics characters ("&") in the given string.

        This function can be helpful if you need to set the controls label to a
        user-provided string. If the string contains ampersands, they wouldn't
        appear on the display but be used instead to indicate that the
        character following the first of them can be used as a control mnemonic.
        While this can sometimes be desirable (e.g. to allow the user to
        configure mnemonics of the controls), more often you will want to use
        this function before passing a user-defined string to SetLabel().
        Alternatively, if the label is entirely user-defined, you can just call
        SetLabelText() directly -- but this function must be used if the label
        is a combination of a part defined by program containing the control
        mnemonics and a user-defined part.

        @param text
            The string such as it should appear on the display.
        @return
            The same string with the ampersands in it doubled.
     */
    static wxString EscapeMnemonics(const wxString& text);

    /**
        Replaces parts of the @a label string with ellipsis, if needed, so
        that it fits into @a maxWidth pixels if possible.

        Note that this function does @em not guarantee that the returned string
        will always be shorter than @a maxWidth; if @a maxWidth is extremely
        small, ellipsized text may be larger.

        @param label
            The string to ellipsize
        @param dc
            The DC used to retrieve the character widths through the
            wxDC::GetPartialTextExtents() function.
        @param mode
            The ellipsization mode. This is the setting which determines
            which part of the string should be replaced by the ellipsis.
            See ::wxEllipsizeMode enumeration values for more info.
        @param maxWidth
            The maximum width of the returned string in pixels.
            This argument determines how much characters of the string need to
            be removed (and replaced by ellipsis).
        @param flags
            One or more of the ::wxEllipsizeFlags enumeration values combined.
    */
    static wxString Ellipsize(const wxString& label, const wxDC& dc,
                              wxEllipsizeMode mode, int maxWidth,
                              int flags = wxELLIPSIZE_FLAGS_DEFAULT);
};
Commit	Line	Data
23324ae1 FM	1	/////////////////////////////////////////////////////////////////////////////
23324ae1 FM	2	// Name: control.h
e54c96f1	3	// Purpose: interface of wxControl
23324ae1 FM	4	// Author: wxWidgets team
23324ae1 FM	5	// RCS-ID: $Id$
526954c5	6	// Licence: wxWindows licence
23324ae1 FM	7	/////////////////////////////////////////////////////////////////////////////
23324ae1 FM	8
a78618b0 FM	9	/**
	10	Flags used by wxControl::Ellipsize function.
	11	*/
	12	enum wxEllipsizeFlags
	13	{
355ce7ad VZ	14	/// No special flags.
	15	wxELLIPSIZE_FLAGS_NONE = 0,
	16
	17	/**
	18	Take mnemonics into account when calculating the text width.
	19
	20	With this flag when calculating the size of the passed string,
	21	mnemonics characters (see wxControl::SetLabel) will be automatically
	22	reduced to a single character. This leads to correct calculations only
	23	if the string passed to Ellipsize() will be used with
	24	wxControl::SetLabel. If you don't want ampersand to be interpreted as
	25	mnemonics (e.g. because you use wxControl::SetLabelText) then don't use
	26	this flag.
	27	*/
	28	wxELLIPSIZE_FLAGS_PROCESS_MNEMONICS = 1,
	29
	30	/**
	31	Expand tabs in spaces when calculating the text width.
	32
	33	This flag tells wxControl::Ellipsize() to calculate the width of tab
	34	characters @c '\\t' as 6 spaces.
	35	*/
	36	wxELLIPSIZE_FLAGS_EXPAND_TABS = 2,
a78618b0 FM	37
a78618b0 FM	38	/// The default flags for wxControl::Ellipsize.
355ce7ad VZ	39	wxELLIPSIZE_FLAGS_DEFAULT = wxELLIPSIZE_FLAGS_PROCESS_MNEMONICS\|
355ce7ad VZ	40	wxELLIPSIZE_FLAGS_EXPAND_TABS
a78618b0 FM	41	};
	42
	43
5c87527c FM	44	/**
	45	The different ellipsization modes supported by the
	46	wxControl::Ellipsize function.
	47	*/
	48	enum wxEllipsizeMode
	49	{
c937bcac VZ	50	/// Don't ellipsize the text at all. @since 2.9.1
	51	wxELLIPSIZE_NONE,
	52
a78618b0	53	/// Put the ellipsis at the start of the string, if the string needs ellipsization.
5c87527c	54	wxELLIPSIZE_START,
a78618b0 FM	55
a78618b0 FM	56	/// Put the ellipsis in the middle of the string, if the string needs ellipsization.
5c87527c	57	wxELLIPSIZE_MIDDLE,
a78618b0 FM	58
a78618b0 FM	59	/// Put the ellipsis at the end of the string, if the string needs ellipsization.
5c87527c FM	60	wxELLIPSIZE_END
	61	};
	62
23324ae1 FM	63	/**
23324ae1 FM	64	@class wxControl
7c913512	65
cdbcf4c2	66	This is the base class for a control or "widget".
7c913512	67
23324ae1 FM	68	A control is generally a small window which processes user input and/or
23324ae1 FM	69	displays one or more item of data.
7c913512	70
3051a44a FM	71	@beginEventEmissionTable{wxClipboardTextEvent}
	72	@event{EVT_TEXT_COPY(id, func)}
	73	Some or all of the controls content was copied to the clipboard.
	74	@event{EVT_TEXT_CUT(id, func)}
	75	Some or all of the controls content was cut (i.e. copied and
	76	deleted).
	77	@event{EVT_TEXT_PASTE(id, func)}
	78	Clipboard content was pasted into the control.
	79	@endEventTable
	80
23324ae1 FM	81	@library{wxcore}
23324ae1 FM	82	@category{ctrl}
7c913512	83
e54c96f1	84	@see wxValidator
23324ae1 FM	85	*/
	86	class wxControl : public wxWindow
	87	{
	88	public:
	89	/**
bd0812fe BP	90	Simulates the effect of the user issuing a command to the item.
	91
	92	@see wxCommandEvent
23324ae1	93	*/
b7e94bd7	94	virtual void Command(wxCommandEvent& event);
23324ae1	95
5c87527c	96	/**
32ee98eb	97	Returns the control's label, as it was passed to SetLabel().
5c87527c	98
32ee98eb FM	99	Note that the returned string may contains mnemonics ("&" characters) if they were
32ee98eb FM	100	passed to the SetLabel() function; use GetLabelText() if they are undesired.
bd0812fe	101
32ee98eb FM	102	Also note that the returned string is always the string which was passed to
	103	SetLabel() but may be different from the string passed to SetLabelText()
	104	(since this last one escapes mnemonic characters).
23324ae1	105	*/
328f5751	106	wxString GetLabel() const;
23324ae1	107
23324ae1	108	/**
bd0812fe	109	Returns the control's label without mnemonics.
32ee98eb FM	110
32ee98eb FM	111	Note that because of the stripping of the mnemonics the returned string may differ
a7d354c6 FM	112	from the string which was passed to SetLabel() but should always be the same which
a7d354c6 FM	113	was passed to SetLabelText().
23324ae1	114	*/
4707b84c	115	wxString GetLabelText() const;
bd0812fe	116
32ee98eb FM	117	/**
	118	Sets the control's label.
	119
	120	All "&" characters in the @a label are special and indicate that the
	121	following character is a @e mnemonic for this control and can be used to
	122	activate it from the keyboard (typically by using @e Alt key in
	123	combination with it). To insert a literal ampersand character, you need
57ab6f23	124	to double it, i.e. use "&&". If this behaviour is undesirable, use
32ee98eb FM	125	SetLabelText() instead.
	126	*/
	127	void SetLabel(const wxString& label);
	128
	129	/**
	130	Sets the control's label to exactly the given string.
	131
	132	Unlike SetLabel(), this function shows exactly the @a text passed to it
	133	in the control, without interpreting ampersands in it in any way.
	134	Notice that it means that the control can't have any mnemonic defined
	135	for it using this function.
	136
	137	@see EscapeMnemonics()
	138	*/
	139	void SetLabelText(const wxString& text);
	140
3da9cffc VZ	141	// NB: when writing docs for the following function remember that Doxygen
	142	// will always expand HTML entities (e.g. ") and thus we need to
	143	// write e.g. "&lt;" to have in the output the "<" string.
	144
	145	/**
	146	Sets the controls label to a string using markup.
	147
	148	Simple markup supported by this function can be used to apply different
7d5051cb VZ	149	fonts or colours to different parts of the control label when supported.
	150	If markup is not supported by the control or platform, it is simply
	151	stripped and SetLabel() is used with the resulting string.
3da9cffc VZ	152
	153	For example,
	154	@code
	155	wxStaticText *text;
	156	...
	157	text->SetLabelMarkup("<b>&Bed</b> &mp; "
	158	"<span foreground='red'>breakfast</span> "
	159	"available <big>HERE</big>");
	160	@endcode
	161	would show the string using bold, red and big for the corresponding
	162	words under wxGTK but will simply show the string "Bed & breakfast
	163	available HERE" on the other platforms. In any case, the "B" of "Bed"
	164	will be underlined to indicate that it can be used as a mnemonic for
	165	this control.
	166
	167	The supported tags are:
	168	<TABLE>
	169	<TR>
	170	<TD><b>Tag</b></TD>
	171	<TD><b>Description</b></TD>
	172	</TR>
	173	<TR>
	174	<TD><b></TD>
	175	<TD>bold text</TD>
	176	</TR>
	177	<TR>
	178	<TD><big></TD>
	179	<TD>bigger text</TD>
	180	</TR>
	181	<TR>
	182	<TD><i></TD>
	183	<TD>italic text</TD>
	184	</TR>
	185	<TR>
	186	<TD><s></TD>
	187	<TD>strike-through text</TD>
	188	</TR>
	189	<TR>
	190	<TD><small></TD>
	191	<TD>smaller text</TD>
	192	</TR>
	193	<TR>
	194	<TD><tt></TD>
	195	<TD>monospaced text</TD>
	196	</TR>
	197	<TR>
	198	<TD><u></TD>
	199	<TD>underlined text</TD>
	200	</TR>
	201	<TR>
	202	<TD><span></TD>
	203	<TD>generic formatter tag, see the table below for supported
	204	attributes.
	205	</TD>
	206	</TR>
	207	</TABLE>
	208
	209	Supported @c <span> attributes:
	210	<TABLE>
	211	<TR>
	212	<TD><b>Name</b></TD>
	213	<TD><b>Description</b></TD>
	214	</TR>
	215	<TR>
216	<TD>foreground, fgcolor, color</TD>
217	<TD>Foreground text colour, can be a name or RGB value.</TD>
218	</TR>
219	<TR>
220	<TD>background, bgcolor</TD>
221	<TD>Background text colour, can be a name or RGB value.</TD>
222	</TR>
223	<TR>
224	<TD>font_family, face</TD>
225	<TD>Font face name.</TD>
226	</TR>
227	<TR>
228	<TD>font_weight, weight</TD>
229	<TD>Numeric value in 0..900 range or one of "ultralight",
230	"light", "normal" (all meaning non-bold), "bold", "ultrabold"
231	and "heavy" (all meaning bold).</TD>
232	</TR>
233	<TR>
234	<TD>font_style, style</TD>
235	<TD>Either "oblique" or "italic" (both with the same meaning)
236	or "normal".</TD>
237	</TR>
238	<TR>
239	<TD>size</TD>
240	<TD>The font size can be specified either as "smaller" or
241	"larger" relatively to the current font, as a CSS font size
242	name ("xx-small", "x-small", "small", "medium", "large",
243	"x-large" or "xx-large") or as a number giving font size in
244	1024th parts of a point, i.e. 10240 for a 10pt font.</TD>
245	</TR>
246	</TABLE>
247
248	This markup language is a strict subset of Pango markup (described at
249	http://library.gnome.org/devel/pango/unstable/PangoMarkupFormat.html)
250	and any tags and span attributes not documented above can't be used
251	under non-GTK platforms.
252
253	Also note that you need to escape the following special characters:
254	<TABLE>
255	<TR>
256	<TD><b>Special character</b></TD>
257	<TD><b>Escape as</b></TD>
258	</TR>
259	<TR>
260	<TD>@c &</TD>
261	<TD>@c &amp; or as @c &&</TD>
262	</TR>
263	<TR>
264	<TD>@c '</TD>
265	<TD>@c &apos;</TD>
266	</TR>
267	<TR>
268	<TD>@c "</TD>
269	<TD>@c &quot;</TD>
270	</TR>
271	<TR>
272	<TD>@c <</TD>
273	<TD>@c &lt;</TD>
274	</TR>
275	<TR>
276	<TD>@c ></TD>
277	<TD>@c &gt;</TD>
278	</TR>
279	</TABLE>
280
281	The non-escaped ampersand @c & characters are interpreted as
282	mnemonics as with wxControl::SetLabel.
283
284
285	@param markup
7d5051cb VZ	286	String containing markup for the label. It may contain markup tags
	287	described above and newline characters but currently only wxGTK and
	288	wxOSX support multiline labels with markup, the generic
	289	implementation (also used in wxMSW) only handles single line markup
	290	labels. Notice that the string must be well-formed (e.g. all tags
	291	must be correctly closed) and won't be shown at all otherwise.
3da9cffc VZ	292	@return
	293	@true if the new label was set (even if markup in it was ignored)
	294	or @false if we failed to parse the markup. In this case the label
	295	remains unchanged.
	296
7d5051cb VZ	297
	298	Currently wxButton supports markup in all major ports (wxMSW, wxGTK and
	299	wxOSX/Cocoa) while wxStaticText supports it in wxGTK and wxOSX and its
	300	generic version (which can be used under MSW if markup support is
	301	required). Extending support to more controls is planned in the future.
3da9cffc VZ	302
	303	@since 2.9.2
	304	*/
	305	bool SetLabelMarkup(const wxString& markup);
	306
32ee98eb FM	307
	308	public: // static functions
	309
bd0812fe	310	/**
4520d583	311	Returns the given @a label string without mnemonics ("&" characters).
bd0812fe BP	312	*/
bd0812fe BP	313	static wxString GetLabelText(const wxString& label);
23324ae1	314
4520d583	315	/**
32ee98eb FM	316	Returns the given @a str string without mnemonics ("&" characters).
32ee98eb FM	317
3da9cffc VZ	318	@note This function is identical to GetLabelText() and is provided
3da9cffc VZ	319	mostly for symmetry with EscapeMnemonics().
4520d583 FM	320	*/
	321	static wxString RemoveMnemonics(const wxString& str);
	322
5b8b2c84	323	/**
32ee98eb	324	Escapes the special mnemonics characters ("&") in the given string.
5b8b2c84 VZ	325
	326	This function can be helpful if you need to set the controls label to a
	327	user-provided string. If the string contains ampersands, they wouldn't
	328	appear on the display but be used instead to indicate that the
	329	character following the first of them can be used as a control mnemonic.
	330	While this can sometimes be desirable (e.g. to allow the user to
	331	configure mnemonics of the controls), more often you will want to use
	332	this function before passing a user-defined string to SetLabel().
	333	Alternatively, if the label is entirely user-defined, you can just call
	334	SetLabelText() directly -- but this function must be used if the label
	335	is a combination of a part defined by program containing the control
	336	mnemonics and a user-defined part.
	337
	338	@param text
	339	The string such as it should appear on the display.
	340	@return
	341	The same string with the ampersands in it doubled.
	342	*/
	343	static wxString EscapeMnemonics(const wxString& text);
	344
23324ae1	345	/**
32ee98eb	346	Replaces parts of the @a label string with ellipsis, if needed, so
508fc76d VS	347	that it fits into @a maxWidth pixels if possible.
	348
	349	Note that this function does @em not guarantee that the returned string
	350	will always be shorter than @a maxWidth; if @a maxWidth is extremely
	351	small, ellipsized text may be larger.
bd0812fe	352
32ee98eb FM	353	@param label
	354	The string to ellipsize
	355	@param dc
	356	The DC used to retrieve the character widths through the
	357	wxDC::GetPartialTextExtents() function.
	358	@param mode
	359	The ellipsization mode. This is the setting which determines
	360	which part of the string should be replaced by the ellipsis.
	361	See ::wxEllipsizeMode enumeration values for more info.
	362	@param maxWidth
	363	The maximum width of the returned string in pixels.
	364	This argument determines how much characters of the string need to
	365	be removed (and replaced by ellipsis).
	366	@param flags
	367	One or more of the ::wxEllipsizeFlags enumeration values combined.
23324ae1	368	*/
32ee98eb FM	369	static wxString Ellipsize(const wxString& label, const wxDC& dc,
	370	wxEllipsizeMode mode, int maxWidth,
	371	int flags = wxELLIPSIZE_FLAGS_DEFAULT);
23324ae1	372	};
e54c96f1	373