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 licence
   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() but should always be the same which
 113         was passed to SetLabelText().
 114     */
 115     wxString GetLabelText() const;
 116
 117     /**
 118         Sets the control's label.
 119
 120         All "&" characters in the @a label are special and indicate that the
 121         following character is a @e mnemonic for this control and can be used to
 122         activate it from the keyboard (typically by using @e Alt key in
 123         combination with it). To insert a literal ampersand character, you need
 124         to double it, i.e. use use "&&". If this behaviour is undesirable, use
 125         SetLabelText() instead.
 126     */
 127     void SetLabel(const wxString& label);
 128
 129     /**
 130         Sets the control's label to exactly the given string.
 131
 132         Unlike SetLabel(), this function shows exactly the @a text passed to it
 133         in the control, without interpreting ampersands in it in any way.
 134         Notice that it means that the control can't have any mnemonic defined
 135         for it using this function.
 136
 137         @see EscapeMnemonics()
 138      */
 139     void SetLabelText(const wxString& text);
 140
 141     // NB: when writing docs for the following function remember that Doxygen
 142     //     will always expand HTML entities (e.g. &quot;) and thus we need to
 143     //     write e.g. "&amp;lt;" to have in the output the "&lt;" string.
 144
 145     /**
 146         Sets the controls label to a string using markup.
 147
 148         Simple markup supported by this function can be used to apply different
 149         fonts or colours to different parts of the control label when supported
 150         (currently only wxStaticText under GTK+ 2). If markup is not supported
 151         by the control or platform, it is simply stripped and SetLabel() is
 152         used with the resulting string.
 153
 154         For example,
 155         @code
 156             wxStaticText *text;
 157             ...
 158             text->SetLabelMarkup("<b>&amp;Bed</b> &amp;mp; "
 159                                  "<span foreground='red'>breakfast</span> "
 160                                  "available <big>HERE</big>");
 161         @endcode
 162         would show the string using bold, red and big for the corresponding
 163         words under wxGTK but will simply show the string "Bed &amp; breakfast
 164         available HERE" on the other platforms. In any case, the "B" of "Bed"
 165         will be underlined to indicate that it can be used as a mnemonic for
 166         this control.
 167
 168         The supported tags are:
 169         <TABLE>
 170             <TR>
 171                 <TD><b>Tag</b></TD>
 172                 <TD><b>Description</b></TD>
 173             </TR>
 174             <TR>
 175                 <TD>&lt;b&gt;</TD>
 176                 <TD>bold text</TD>
 177             </TR>
 178             <TR>
 179                 <TD>&lt;big&gt;</TD>
 180                 <TD>bigger text</TD>
 181             </TR>
 182             <TR>
 183                 <TD>&lt;i&gt;</TD>
 184                 <TD>italic text</TD>
 185             </TR>
 186             <TR>
 187                 <TD>&lt;s&gt;</TD>
 188                 <TD>strike-through text</TD>
 189             </TR>
 190             <TR>
 191                 <TD>&lt;small&gt;</TD>
 192                 <TD>smaller text</TD>
 193             </TR>
 194             <TR>
 195                 <TD>&lt;tt&gt;</TD>
 196                 <TD>monospaced text</TD>
 197             </TR>
 198             <TR>
 199                 <TD>&lt;u&gt;</TD>
 200                 <TD>underlined text</TD>
 201             </TR>
 202             <TR>
 203                 <TD>&lt;span&gt;</TD>
 204                 <TD>generic formatter tag, see the table below for supported
 205                 attributes.
 206                 </TD>
 207             </TR>
 208         </TABLE>
 209
 210         Supported @c &lt;span&gt; attributes:
 211         <TABLE>
 212             <TR>
 213                 <TD><b>Name</b></TD>
 214                 <TD><b>Description</b></TD>
 215             </TR>
 216             <TR>
 217                 <TD>foreground, fgcolor, color</TD>
 218                 <TD>Foreground text colour, can be a name or RGB value.</TD>
 219             </TR>
 220             <TR>
 221                 <TD>background, bgcolor</TD>
 222                 <TD>Background text colour, can be a name or RGB value.</TD>
 223             </TR>
 224             <TR>
 225                 <TD>font_family, face</TD>
 226                 <TD>Font face name.</TD>
 227             </TR>
 228             <TR>
 229                 <TD>font_weight, weight</TD>
 230                 <TD>Numeric value in 0..900 range or one of "ultralight",
 231                 "light", "normal" (all meaning non-bold), "bold", "ultrabold"
 232                 and "heavy" (all meaning bold).</TD>
 233             </TR>
 234             <TR>
 235                 <TD>font_style, style</TD>
 236                 <TD>Either "oblique" or "italic" (both with the same meaning)
 237                 or "normal".</TD>
 238             </TR>
 239             <TR>
 240                 <TD>size</TD>
 241                 <TD>The font size can be specified either as "smaller" or
 242                 "larger" relatively to the current font, as a CSS font size
 243                 name ("xx-small", "x-small", "small", "medium", "large",
 244                 "x-large" or "xx-large") or as a number giving font size in
 245                 1024th parts of a point, i.e. 10240 for a 10pt font.</TD>
 246             </TR>
 247         </TABLE>
 248
 249         This markup language is a strict subset of Pango markup (described at
 250         http://library.gnome.org/devel/pango/unstable/PangoMarkupFormat.html)
 251         and any tags and span attributes not documented above can't be used
 252         under non-GTK platforms.
 253
 254         Also note that you need to escape the following special characters:
 255         <TABLE>
 256             <TR>
 257                 <TD><b>Special character</b></TD>
 258                 <TD><b>Escape as</b></TD>
 259             </TR>
 260             <TR>
 261                 <TD>@c &amp;</TD>
 262                 <TD>@c &amp;amp; or as @c &amp;&amp;</TD>
 263             </TR>
 264             <TR>
 265                 <TD>@c &apos;</TD>
 266                 <TD>@c &amp;apos;</TD>
 267             </TR>
 268             <TR>
 269                 <TD>@c &quot;</TD>
 270                 <TD>@c &amp;quot;</TD>
 271             </TR>
 272             <TR>
 273                 <TD>@c &lt;</TD>
 274                 <TD>@c &amp;lt;</TD>
 275             </TR>
 276             <TR>
 277                 <TD>@c &gt;</TD>
 278                 <TD>@c &amp;gt;</TD>
 279             </TR>
 280         </TABLE>
 281
 282         The non-escaped ampersand @c &amp; characters are interpreted as
 283         mnemonics as with wxControl::SetLabel.
 284
 285
 286         @param markup
 287             String containing markup for the label. It may contain newline
 288             characters and the markup tags described above.
 289         @return
 290             @true if the new label was set (even if markup in it was ignored)
 291             or @false if we failed to parse the markup. In this case the label
 292             remains unchanged.
 293
 294         Note that the string must be well-formed (e.g. all tags must be correctly
 295         closed) and won't be shown at all otherwise.
 296
 297         @since 2.9.2
 298     */
 299     bool SetLabelMarkup(const wxString& markup);
 300
 301
 302 public:     // static functions
 303
 304     /**
 305         Returns the given @a label string without mnemonics ("&" characters).
 306     */
 307     static wxString GetLabelText(const wxString& label);
 308
 309     /**
 310         Returns the given @a str string without mnemonics ("&" characters).
 311
 312         @note This function is identical to GetLabelText() and is provided
 313               mostly for symmetry with EscapeMnemonics().
 314     */
 315     static wxString RemoveMnemonics(const wxString& str);
 316
 317     /**
 318         Escapes the special mnemonics characters ("&") in the given string.
 319
 320         This function can be helpful if you need to set the controls label to a
 321         user-provided string. If the string contains ampersands, they wouldn't
 322         appear on the display but be used instead to indicate that the
 323         character following the first of them can be used as a control mnemonic.
 324         While this can sometimes be desirable (e.g. to allow the user to
 325         configure mnemonics of the controls), more often you will want to use
 326         this function before passing a user-defined string to SetLabel().
 327         Alternatively, if the label is entirely user-defined, you can just call
 328         SetLabelText() directly -- but this function must be used if the label
 329         is a combination of a part defined by program containing the control
 330         mnemonics and a user-defined part.
 331
 332         @param text
 333             The string such as it should appear on the display.
 334         @return
 335             The same string with the ampersands in it doubled.
 336      */
 337     static wxString EscapeMnemonics(const wxString& text);
 338
 339     /**
 340         Replaces parts of the @a label string with ellipsis, if needed, so
 341         that it fits into @a maxWidth pixels if possible.
 342
 343         Note that this function does @em not guarantee that the returned string
 344         will always be shorter than @a maxWidth; if @a maxWidth is extremely
 345         small, ellipsized text may be larger.
 346
 347         @param label
 348             The string to ellipsize
 349         @param dc
 350             The DC used to retrieve the character widths through the
 351             wxDC::GetPartialTextExtents() function.
 352         @param mode
 353             The ellipsization mode. This is the setting which determines
 354             which part of the string should be replaced by the ellipsis.
 355             See ::wxEllipsizeMode enumeration values for more info.
 356         @param maxWidth
 357             The maximum width of the returned string in pixels.
 358             This argument determines how much characters of the string need to
 359             be removed (and replaced by ellipsis).
 360         @param flags
 361             One or more of the ::wxEllipsizeFlags enumeration values combined.
 362     */
 363     static wxString Ellipsize(const wxString& label, const wxDC& dc,
 364                               wxEllipsizeMode mode, int maxWidth,
 365                               int flags = wxELLIPSIZE_FLAGS_DEFAULT);
 366 };
 367