X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/3051a44a73502c2b03d1618d0a8e94274ee67e16..0a7ee6e0f400f0d10b158bc0396be22f59d6ad8f:/interface/wx/control.h diff --git a/interface/wx/control.h b/interface/wx/control.h index 2d56ad3c60..32fd306b6e 100644 --- a/interface/wx/control.h +++ b/interface/wx/control.h @@ -3,7 +3,7 @@ // Purpose: interface of wxControl // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -11,21 +11,33 @@ */ enum wxEllipsizeFlags { - /// 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_PROCESS_MNEMONICS = 1, - - /// This flag tells wxControl::Ellipsize to calculate the width of tab - /// characters @c '\\t' as 6 spaces. - wxELLIPSIZE_EXPAND_TAB = 2, + /// 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_DEFAULT_FLAGS = wxELLIPSIZE_PROCESS_MNEMONICS|wxELLIPSIZE_EXPAND_TAB + wxELLIPSIZE_FLAGS_DEFAULT = wxELLIPSIZE_FLAGS_PROCESS_MNEMONICS| + wxELLIPSIZE_FLAGS_EXPAND_TABS }; @@ -35,6 +47,9 @@ enum wxEllipsizeFlags */ 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, @@ -71,58 +86,280 @@ enum wxEllipsizeMode class wxControl : public wxWindow { public: + /** - Simulates the effect of the user issuing a command to the item. + Constructs a control. - @see wxCommandEvent + @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 name + Control name. */ - virtual void Command(wxCommandEvent& event); + wxControl(wxWindow *parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxControlNameStr); /** - Replaces parts of the @a label string with ellipsis, if needed, so - that it doesn't exceed @a maxWidth. + 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); - @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 modes. See ::wxEllipsizeMode. - @param maxWidth - The maximum width of the returned string in pixels. - @param flags - One or more of the ::wxEllipsize + /** + Simulates the effect of the user issuing a command to the item. + + @see wxCommandEvent */ - static wxString Ellipsize(const wxString& label, const wxDC& dc, - wxEllipsizeMode mode, int maxWidth, - int flags = wxELLIPSIZE_DEFAULT_FLAGS); + virtual void Command(wxCommandEvent& event); /** - Returns the control's text. + 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. - @note The returned string contains mnemonics ("&" characters) if it has - any, 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. ") and thus we need to + // write e.g. "&lt;" to have in the output the "<" 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("&Bed &mp; " + "breakfast " + "available HERE"); + @endcode + would show the string using bold, red and big for the corresponding + words under wxGTK but will simply show the string "Bed & 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: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TagDescription
<b>bold text
<big>bigger text
<i>italic text
<s>strike-through text
<small>smaller text
<tt>monospaced text
<u>underlined text
<span>generic formatter tag, see the table below for supported + attributes. +
+ + Supported @c <span> attributes: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescription
foreground, fgcolor, colorForeground text colour, can be a name or RGB value.
background, bgcolorBackground text colour, can be a name or RGB value.
font_family, faceFont face name.
font_weight, weightNumeric value in 0..900 range or one of "ultralight", + "light", "normal" (all meaning non-bold), "bold", "ultrabold" + and "heavy" (all meaning bold).
font_style, styleEither "oblique" or "italic" (both with the same meaning) + or "normal".
sizeThe 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.
+ + 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: + + + + + + + + + + + + + + + + + + + + + + + + + +
Special characterEscape as
@c &@c &amp; or as @c &&
@c '@c &apos;
@c "@c &quot;
@c <@c &lt;
@c >@c &gt;
+ + The non-escaped ampersand @c & 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); /** - Removes the mnemonics ("&" characters) from the given string. + 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); /** - Escape the special mnemonics characters ("&") in the given string. + 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 @@ -144,27 +381,31 @@ public: static wxString EscapeMnemonics(const wxString& text); /** - Sets the item's text. - - Any "&" 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 use "&&". If this behaviour is undesirable, use - SetLabelText() instead. - */ - void SetLabel(const wxString& label); - - /** - Sets the item's text to exactly the given string. + Replaces parts of the @a label string with ellipsis, if needed, so + that it fits into @a maxWidth pixels if possible. - 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. + 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. - @see EscapeMnemonics() - */ - void SetLabelText(const wxString& text); + @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); };