interface/wx/control.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        control.h
   3 // Purpose:     interface of wxControl
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     Flags used by wxControl::Ellipsize function.
  11 */
  12 enum wxEllipsizeFlags
  13 {
  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,
  37
  38     /// The default flags for wxControl::Ellipsize.
  39     wxELLIPSIZE_FLAGS_DEFAULT = wxELLIPSIZE_FLAGS_PROCESS_MNEMONICS|
  40                                 wxELLIPSIZE_FLAGS_EXPAND_TABS
  41 };
  42
  43
  44 /**
  45     The different ellipsization modes supported by the
  46     wxControl::Ellipsize function.
  47 */
  48 enum wxEllipsizeMode
  49 {
  50     /// Don't ellipsize the text at all. @since 2.9.1
  51     wxELLIPSIZE_NONE,
  52
  53     /// Put the ellipsis at the start of the string, if the string needs ellipsization.
  54     wxELLIPSIZE_START,
  55
  56     /// Put the ellipsis in the middle of the string, if the string needs ellipsization.
  57     wxELLIPSIZE_MIDDLE,
  58
  59     /// Put the ellipsis at the end of the string, if the string needs ellipsization.
  60     wxELLIPSIZE_END
  61 };
  62
  63 /**
  64     @class wxControl
  65
  66     This is the base class for a control or "widget".
  67
  68     A control is generally a small window which processes user input and/or
  69     displays one or more item of data.
  70
  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
  81     @library{wxcore}
  82     @category{ctrl}
  83
  84     @see wxValidator
  85 */
  86 class wxControl : public wxWindow
  87 {
  88 public:
  89     /**
  90         Simulates the effect of the user issuing a command to the item.
  91
  92         @see wxCommandEvent
  93     */
  94     virtual void Command(wxCommandEvent& event);
  95
  96     /**
  97         Returns the control's label, as it was passed to SetLabel().
  98
  99         Note that the returned string may contains mnemonics ("&" characters) if they were
 100         passed to the SetLabel() function; use GetLabelText() if they are undesired.
 101
 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).
 105     */
 106     wxString GetLabel() const;
 107
 108     /**
 109         Returns the control's label without mnemonics.
 110
 111         Note that because of the stripping of the mnemonics the returned string may differ
 112         from the string which was passed to SetLabel().
 113     */
 114     wxString GetLabelText() const;
 115
 116     /**
 117         Sets the control's label.
 118
 119         All "&" characters in the @a label are special and indicate that the
 120         following character is a @e mnemonic for this control and can be used to
 121         activate it from the keyboard (typically by using @e Alt key in
 122         combination with it). To insert a literal ampersand character, you need
 123         to double it, i.e. use use "&&". If this behaviour is undesirable, use
 124         SetLabelText() instead.
 125     */
 126     void SetLabel(const wxString& label);
 127
 128     /**
 129         Sets the control's label to exactly the given string.
 130
 131         Unlike SetLabel(), this function shows exactly the @a text passed to it
 132         in the control, without interpreting ampersands in it in any way.
 133         Notice that it means that the control can't have any mnemonic defined
 134         for it using this function.
 135
 136         @see EscapeMnemonics()
 137      */
 138     void SetLabelText(const wxString& text);
 139
 140
 141 public:     // static functions
 142
 143     /**
 144         Returns the given @a label string without mnemonics ("&" characters).
 145     */
 146     static wxString GetLabelText(const wxString& label);
 147
 148     /**
 149         Returns the given @a str string without mnemonics ("&" characters).
 150
 151         @note This function is identic to GetLabelText() and is provided both for symmetry
 152               with the wxStaticText::RemoveMarkup() function and to allow to write more
 153               readable code (since this function has a more descriptive name respect GetLabelText()).
 154     */
 155     static wxString RemoveMnemonics(const wxString& str);
 156
 157     /**
 158         Escapes the special mnemonics characters ("&") in the given string.
 159
 160         This function can be helpful if you need to set the controls label to a
 161         user-provided string. If the string contains ampersands, they wouldn't
 162         appear on the display but be used instead to indicate that the
 163         character following the first of them can be used as a control mnemonic.
 164         While this can sometimes be desirable (e.g. to allow the user to
 165         configure mnemonics of the controls), more often you will want to use
 166         this function before passing a user-defined string to SetLabel().
 167         Alternatively, if the label is entirely user-defined, you can just call
 168         SetLabelText() directly -- but this function must be used if the label
 169         is a combination of a part defined by program containing the control
 170         mnemonics and a user-defined part.
 171
 172         @param text
 173             The string such as it should appear on the display.
 174         @return
 175             The same string with the ampersands in it doubled.
 176      */
 177     static wxString EscapeMnemonics(const wxString& text);
 178
 179     /**
 180         Replaces parts of the @a label string with ellipsis, if needed, so
 181         that it doesn't exceed @a maxWidth.
 182
 183         Note that this functions is guaranteed to always returns a string
 184         whose rendering on the given DC takes less than @a maxWidth pixels
 185         in horizontal.
 186
 187         @param label
 188             The string to ellipsize
 189         @param dc
 190             The DC used to retrieve the character widths through the
 191             wxDC::GetPartialTextExtents() function.
 192         @param mode
 193             The ellipsization mode. This is the setting which determines
 194             which part of the string should be replaced by the ellipsis.
 195             See ::wxEllipsizeMode enumeration values for more info.
 196         @param maxWidth
 197             The maximum width of the returned string in pixels.
 198             This argument determines how much characters of the string need to
 199             be removed (and replaced by ellipsis).
 200         @param flags
 201             One or more of the ::wxEllipsizeFlags enumeration values combined.
 202     */
 203     static wxString Ellipsize(const wxString& label, const wxDC& dc,
 204                               wxEllipsizeMode mode, int maxWidth,
 205                               int flags = wxELLIPSIZE_FLAGS_DEFAULT);
 206 };
 207