// Name: control.h
// Purpose: interface of wxControl
// Author: wxWidgets team
-// RCS-ID: $Id$
-// Licence: wxWindows license
+// 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
- @wxheader{control.h}
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}
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 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
*/
- void Command(wxCommandEvent& event);
+ virtual void Command(wxCommandEvent& event);
/**
- Returns the control's text.
+ Returns the control's label, as it was passed to SetLabel().
- @note The returned string contains mnemonics ("&" characters) if it has
- any, use GetLabelText() if they are undesired.
+ 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().
*/
- const wxString GetLabelText();
+ 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;
/**
- Returns the given @a label string without mnemonics.
+ @overload
*/
- static wxString GetLabelText(const wxString& label);
+ wxSize GetSizeFromTextSize(const wxSize& tsize) const;
/**
- Sets the item's text.
+ Sets the control's label.
- Any "&" characters in the @a label are special and indicate that the
- following character is a mnemonic for this control and can be used to
+ 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 "&&".
+ 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("<b>&Bed</b> &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 & 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><b></TD>
+ <TD>bold text</TD>
+ </TR>
+ <TR>
+ <TD><big></TD>
+ <TD>bigger text</TD>
+ </TR>
+ <TR>
+ <TD><i></TD>
+ <TD>italic text</TD>
+ </TR>
+ <TR>
+ <TD><s></TD>
+ <TD>strike-through text</TD>
+ </TR>
+ <TR>
+ <TD><small></TD>
+ <TD>smaller text</TD>
+ </TR>
+ <TR>
+ <TD><tt></TD>
+ <TD>monospaced text</TD>
+ </TR>
+ <TR>
+ <TD><u></TD>
+ <TD>underlined text</TD>
+ </TR>
+ <TR>
+ <TD><span></TD>
+ <TD>generic formatter tag, see the table below for supported
+ attributes.
+ </TD>
+ </TR>
+ </TABLE>
+
+ Supported @c <span> 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 &</TD>
+ <TD>@c &amp; or as @c &&</TD>
+ </TR>
+ <TR>
+ <TD>@c '</TD>
+ <TD>@c &apos;</TD>
+ </TR>
+ <TR>
+ <TD>@c "</TD>
+ <TD>@c &quot;</TD>
+ </TR>
+ <TR>
+ <TD>@c <</TD>
+ <TD>@c &lt;</TD>
+ </TR>
+ <TR>
+ <TD>@c ></TD>
+ <TD>@c &gt;</TD>
+ </TR>
+ </TABLE>
+
+ 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);
+
+ /**
+ 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);
};
projects / wxWidgets.git / blobdiff