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

/////////////////////////////////////////////////////////////////////////////
// Name:        control.h
// Purpose:     interface of wxControl
// Author:      wxWidgets team
// 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:

    /**
        Constructs a control.

        @param parent
            Pointer to a parent window.
        @param id
            Control identifier. If wxID_ANY, will automatically create an identifier.
        @param pos
            Control position. wxDefaultPosition indicates that wxWidgets
            should generate a default position for the control.
        @param size
            Control size. wxDefaultSize indicates that wxWidgets should generate
            a default size for the window. If no suitable size can  be found, the
            window will be sized to 20x20 pixels so that the window is visible but
            obviously not correctly sized.
        @param style
            Control style. For generic window styles, please see wxWindow.
        @param validator
            Control validator. 
        @param name
            Control name.
    */
   wxControl(wxWindow *parent, wxWindowID id,
             const wxPoint& pos = wxDefaultPosition,
             const wxSize& size = wxDefaultSize, long style = 0,
             const wxValidator& validator = wxDefaultValidator,
             const wxString& name = wxControlNameStr);

    /**
       Default constructor to allow 2-phase creation.
    */
    wxControl();
    
    bool Create(wxWindow *parent, wxWindowID id,
            const wxPoint& pos = wxDefaultPosition,
            const wxSize& size = wxDefaultSize, long style = 0,
            const wxValidator& validator = wxDefaultValidator,
            const wxString& name = wxControlNameStr);

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

    /**
        Determine the size needed by the control to leave the given area for
        its text.

        This function is mostly useful with control displaying short amounts of
        text that can be edited by the user, e.g. wxTextCtrl, wxComboBox,
        wxSearchCtrl etc. Typically it is used to size these controls for the
        maximal amount of input they are supposed to contain, for example:
        @code
            // Create a control for post code entry.
            wxTextCtrl* postcode = new wxTextCtrl(this, ...);

            // And set its initial and minimal size to be big enough for
            // entering 5 digits.
            postcode->SetInitialSize(
                postcode->GetSizeFromTextSize(
                    postcode->GetTextExtent("99999")));
        @endcode

        Currently this method is only implemented for wxTextCtrl, wxComboBox
        and wxChoice in wxMSW and wxGTK.

        @param xlen The horizontal extent of the area to leave for text, in
            pixels.
        @param ylen The vertical extent of the area to leave for text, in
            pixels. By default -1 meaning that the vertical component of the
            returned size should be the default height of this control.
        @return The size that the control should have to leave the area of the
            specified size for its text. May return wxDefaultSize if this
            method is not implemented for this particular control under the
            current platform.

        @since 2.9.5
     */
    wxSize GetSizeFromTextSize(int xlen, int ylen = -1) const;

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