// Purpose: interface of wxControl
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
virtual void Command(wxCommandEvent& event);
/**
- Replaces parts of the @a label string with ellipsis, if needed, so
- that it doesn't exceed @a maxWidth.
-
- Note that this functions is guaranteed to always returns a string
- whose rendering on the given DC takes less than @a maxWidth pixels
- in horizontal.
-
- @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);
+ Returns the control's label, as it was passed to SetLabel().
- /**
- Returns the control's text.
+ 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 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);
+
+
+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 identic to GetLabelText() and is provided both for symmetry
+ with the wxStaticText::RemoveMarkup() function and to allow to write more
+ readable code (since this function has a more descriptive name respect GetLabelText()).
*/
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
static wxString EscapeMnemonics(const wxString& text);
/**
- Sets the item's text.
+ Replaces parts of the @a label string with ellipsis, if needed, so
+ that it doesn't exceed @a maxWidth.
+
+ Note that this functions is guaranteed to always returns a string
+ whose rendering on the given DC takes less than @a maxWidth pixels
+ in horizontal.
- 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.
+ @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.
*/
- void SetLabel(const wxString& label);
-
- /**
- Sets the item's text 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);
+ static wxString Ellipsize(const wxString& label, const wxDC& dc,
+ wxEllipsizeMode mode, int maxWidth,
+ int flags = wxELLIPSIZE_FLAGS_DEFAULT);
};
projects / wxWidgets.git / blobdiff