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     /**
  91         Constructs a control.
  92
  93         @param parent
  94             Pointer to a parent window.
  95         @param id
  96             Control identifier. If wxID_ANY, will automatically create an identifier.
  97         @param pos
  98             Control position. wxDefaultPosition indicates that wxWidgets
  99             should generate a default position for the control.
 100         @param size
 101             Control size. wxDefaultSize indicates that wxWidgets should generate
 102             a default size for the window. If no suitable size can  be found, the
 103             window will be sized to 20x20 pixels so that the window is visible but
 104             obviously not correctly sized.
 105         @param style
 106             Control style. For generic window styles, please see wxWindow.
 107         @param name
 108             Control name.
 109     */
 110    wxControl(wxWindow *parent, wxWindowID id,
 111              const wxPoint& pos = wxDefaultPosition,
 112              const wxSize& size = wxDefaultSize, long style = 0,
 113              const wxValidator& validator = wxDefaultValidator,
 114              const wxString& name = wxControlNameStr);
 115
 116     /**
 117        Default constructor to allow 2-phase creation.
 118     */
 119     wxControl();
 120
 121     bool Create(wxWindow *parent, wxWindowID id,
 122             const wxPoint& pos = wxDefaultPosition,
 123             const wxSize& size = wxDefaultSize, long style = 0,
 124             const wxValidator& validator = wxDefaultValidator,
 125             const wxString& name = wxControlNameStr);
 126
 127     /**
 128         Simulates the effect of the user issuing a command to the item.
 129
 130         @see wxCommandEvent
 131     */
 132     virtual void Command(wxCommandEvent& event);
 133
 134     /**
 135         Returns the control's label, as it was passed to SetLabel().
 136
 137         Note that the returned string may contains mnemonics ("&" characters) if they were
 138         passed to the SetLabel() function; use GetLabelText() if they are undesired.
 139
 140         Also note that the returned string is always the string which was passed to
 141         SetLabel() but may be different from the string passed to SetLabelText()
 142         (since this last one escapes mnemonic characters).
 143     */
 144     wxString GetLabel() const;
 145
 146     /**
 147         Returns the control's label without mnemonics.
 148
 149         Note that because of the stripping of the mnemonics the returned string may differ
 150         from the string which was passed to SetLabel() but should always be the same which
 151         was passed to SetLabelText().
 152     */
 153     wxString GetLabelText() const;
 154
 155     /**
 156         Determine the size needed by the control to leave the given area for
 157         its text.
 158
 159         This function is mostly useful with control displaying short amounts of
 160         text that can be edited by the user, e.g. wxTextCtrl, wxComboBox,
 161         wxSearchCtrl etc. Typically it is used to size these controls for the
 162         maximal amount of input they are supposed to contain, for example:
 163         @code
 164             // Create a control for post code entry.
 165             wxTextCtrl* postcode = new wxTextCtrl(this, ...);
 166
 167             // And set its initial and minimal size to be big enough for
 168             // entering 5 digits.
 169             postcode->SetInitialSize(
 170                 postcode->GetSizeFromTextSize(
 171                     postcode->GetTextExtent("99999")));
 172         @endcode
 173
 174         Currently this method is only implemented for wxTextCtrl, wxComboBox
 175         and wxChoice in wxMSW and wxGTK.
 176
 177         @param xlen The horizontal extent of the area to leave for text, in
 178             pixels.
 179         @param ylen The vertical extent of the area to leave for text, in
 180             pixels. By default -1 meaning that the vertical component of the
 181             returned size should be the default height of this control.
 182         @return The size that the control should have to leave the area of the
 183             specified size for its text. May return wxDefaultSize if this
 184             method is not implemented for this particular control under the
 185             current platform.
 186
 187         @since 2.9.5
 188      */
 189     wxSize GetSizeFromTextSize(int xlen, int ylen = -1) const;
 190
 191     /**
 192         @overload
 193     */
 194     wxSize GetSizeFromTextSize(const wxSize& tsize) const;
 195
 196     /**
 197         Sets the control's label.
 198
 199         All "&" characters in the @a label are special and indicate that the
 200         following character is a @e mnemonic for this control and can be used to
 201         activate it from the keyboard (typically by using @e Alt key in
 202         combination with it). To insert a literal ampersand character, you need
 203         to double it, i.e. use "&&". If this behaviour is undesirable, use
 204         SetLabelText() instead.
 205     */
 206     void SetLabel(const wxString& label);
 207
 208     /**
 209         Sets the control's label to exactly the given string.
 210
 211         Unlike SetLabel(), this function shows exactly the @a text passed to it
 212         in the control, without interpreting ampersands in it in any way.
 213         Notice that it means that the control can't have any mnemonic defined
 214         for it using this function.
 215
 216         @see EscapeMnemonics()
 217      */
 218     void SetLabelText(const wxString& text);
 219
 220     // NB: when writing docs for the following function remember that Doxygen
 221     //     will always expand HTML entities (e.g. &quot;) and thus we need to
 222     //     write e.g. "&amp;lt;" to have in the output the "&lt;" string.
 223
 224     /**
 225         Sets the controls label to a string using markup.
 226
 227         Simple markup supported by this function can be used to apply different
 228         fonts or colours to different parts of the control label when supported.
 229         If markup is not supported by the control or platform, it is simply
 230         stripped and SetLabel() is used with the resulting string.
 231
 232         For example,
 233         @code
 234             wxStaticText *text;
 235             ...
 236             text->SetLabelMarkup("<b>&amp;Bed</b> &amp;mp; "
 237                                  "<span foreground='red'>breakfast</span> "
 238                                  "available <big>HERE</big>");
 239         @endcode
 240         would show the string using bold, red and big for the corresponding
 241         words under wxGTK but will simply show the string "Bed &amp; breakfast
 242         available HERE" on the other platforms. In any case, the "B" of "Bed"
 243         will be underlined to indicate that it can be used as a mnemonic for
 244         this control.
 245
 246         The supported tags are:
 247         <TABLE>
 248             <TR>
 249                 <TD><b>Tag</b></TD>
 250                 <TD><b>Description</b></TD>
 251             </TR>
 252             <TR>
 253                 <TD>&lt;b&gt;</TD>
 254                 <TD>bold text</TD>
 255             </TR>
 256             <TR>
 257                 <TD>&lt;big&gt;</TD>
 258                 <TD>bigger text</TD>
 259             </TR>
 260             <TR>
 261                 <TD>&lt;i&gt;</TD>
 262                 <TD>italic text</TD>
 263             </TR>
 264             <TR>
 265                 <TD>&lt;s&gt;</TD>
 266                 <TD>strike-through text</TD>
 267             </TR>
 268             <TR>
 269                 <TD>&lt;small&gt;</TD>
 270                 <TD>smaller text</TD>
 271             </TR>
 272             <TR>
 273                 <TD>&lt;tt&gt;</TD>
 274                 <TD>monospaced text</TD>
 275             </TR>
 276             <TR>
 277                 <TD>&lt;u&gt;</TD>
 278                 <TD>underlined text</TD>
 279             </TR>
 280             <TR>
 281                 <TD>&lt;span&gt;</TD>
 282                 <TD>generic formatter tag, see the table below for supported
 283                 attributes.
 284                 </TD>
 285             </TR>
 286         </TABLE>
 287
 288         Supported @c &lt;span&gt; attributes:
 289         <TABLE>
 290             <TR>
 291                 <TD><b>Name</b></TD>
 292                 <TD><b>Description</b></TD>
 293             </TR>
 294             <TR>
 295                 <TD>foreground, fgcolor, color</TD>
 296                 <TD>Foreground text colour, can be a name or RGB value.</TD>
 297             </TR>
 298             <TR>
 299                 <TD>background, bgcolor</TD>
 300                 <TD>Background text colour, can be a name or RGB value.</TD>
 301             </TR>
 302             <TR>
 303                 <TD>font_family, face</TD>
 304                 <TD>Font face name.</TD>
 305             </TR>
 306             <TR>
 307                 <TD>font_weight, weight</TD>
 308                 <TD>Numeric value in 0..900 range or one of "ultralight",
 309                 "light", "normal" (all meaning non-bold), "bold", "ultrabold"
 310                 and "heavy" (all meaning bold).</TD>
 311             </TR>
 312             <TR>
 313                 <TD>font_style, style</TD>
 314                 <TD>Either "oblique" or "italic" (both with the same meaning)
 315                 or "normal".</TD>
 316             </TR>
 317             <TR>
 318                 <TD>size</TD>
 319                 <TD>The font size can be specified either as "smaller" or
 320                 "larger" relatively to the current font, as a CSS font size
 321                 name ("xx-small", "x-small", "small", "medium", "large",
 322                 "x-large" or "xx-large") or as a number giving font size in
 323                 1024th parts of a point, i.e. 10240 for a 10pt font.</TD>
 324             </TR>
 325         </TABLE>
 326
 327         This markup language is a strict subset of Pango markup (described at
 328         http://library.gnome.org/devel/pango/unstable/PangoMarkupFormat.html)
 329         and any tags and span attributes not documented above can't be used
 330         under non-GTK platforms.
 331
 332         Also note that you need to escape the following special characters:
 333         <TABLE>
 334             <TR>
 335                 <TD><b>Special character</b></TD>
 336                 <TD><b>Escape as</b></TD>
 337             </TR>
 338             <TR>
 339                 <TD>@c &amp;</TD>
 340                 <TD>@c &amp;amp; or as @c &amp;&amp;</TD>
 341             </TR>
 342             <TR>
 343                 <TD>@c &apos;</TD>
 344                 <TD>@c &amp;apos;</TD>
 345             </TR>
 346             <TR>
 347                 <TD>@c &quot;</TD>
 348                 <TD>@c &amp;quot;</TD>
 349             </TR>
 350             <TR>
 351                 <TD>@c &lt;</TD>
 352                 <TD>@c &amp;lt;</TD>
 353             </TR>
 354             <TR>
 355                 <TD>@c &gt;</TD>
 356                 <TD>@c &amp;gt;</TD>
 357             </TR>
 358         </TABLE>
 359
 360         The non-escaped ampersand @c &amp; characters are interpreted as
 361         mnemonics as with wxControl::SetLabel.
 362
 363
 364         @param markup
 365             String containing markup for the label. It may contain markup tags
 366             described above and newline characters but currently only wxGTK and
 367             wxOSX support multiline labels with markup, the generic
 368             implementation (also used in wxMSW) only handles single line markup
 369             labels. Notice that the string must be well-formed (e.g. all tags
 370             must be correctly closed) and won't be shown at all otherwise.
 371         @return
 372             @true if the new label was set (even if markup in it was ignored)
 373             or @false if we failed to parse the markup. In this case the label
 374             remains unchanged.
 375
 376
 377         Currently wxButton supports markup in all major ports (wxMSW, wxGTK and
 378         wxOSX/Cocoa) while wxStaticText supports it in wxGTK and wxOSX and its
 379         generic version (which can be used under MSW if markup support is
 380         required). Extending support to more controls is planned in the future.
 381
 382         @since 2.9.2
 383     */
 384     bool SetLabelMarkup(const wxString& markup);
 385
 386
 387 public:     // static functions
 388
 389     /**
 390         Returns the given @a label string without mnemonics ("&" characters).
 391     */
 392     static wxString GetLabelText(const wxString& label);
 393
 394     /**
 395         Returns the given @a str string without mnemonics ("&" characters).
 396
 397         @note This function is identical to GetLabelText() and is provided
 398               mostly for symmetry with EscapeMnemonics().
 399     */
 400     static wxString RemoveMnemonics(const wxString& str);
 401
 402     /**
 403         Escapes the special mnemonics characters ("&") in the given string.
 404
 405         This function can be helpful if you need to set the controls label to a
 406         user-provided string. If the string contains ampersands, they wouldn't
 407         appear on the display but be used instead to indicate that the
 408         character following the first of them can be used as a control mnemonic.
 409         While this can sometimes be desirable (e.g. to allow the user to
 410         configure mnemonics of the controls), more often you will want to use
 411         this function before passing a user-defined string to SetLabel().
 412         Alternatively, if the label is entirely user-defined, you can just call
 413         SetLabelText() directly -- but this function must be used if the label
 414         is a combination of a part defined by program containing the control
 415         mnemonics and a user-defined part.
 416
 417         @param text
 418             The string such as it should appear on the display.
 419         @return
 420             The same string with the ampersands in it doubled.
 421      */
 422     static wxString EscapeMnemonics(const wxString& text);
 423
 424     /**
 425         Replaces parts of the @a label string with ellipsis, if needed, so
 426         that it fits into @a maxWidth pixels if possible.
 427
 428         Note that this function does @em not guarantee that the returned string
 429         will always be shorter than @a maxWidth; if @a maxWidth is extremely
 430         small, ellipsized text may be larger.
 431
 432         @param label
 433             The string to ellipsize
 434         @param dc
 435             The DC used to retrieve the character widths through the
 436             wxDC::GetPartialTextExtents() function.
 437         @param mode
 438             The ellipsization mode. This is the setting which determines
 439             which part of the string should be replaced by the ellipsis.
 440             See ::wxEllipsizeMode enumeration values for more info.
 441         @param maxWidth
 442             The maximum width of the returned string in pixels.
 443             This argument determines how much characters of the string need to
 444             be removed (and replaced by ellipsis).
 445         @param flags
 446             One or more of the ::wxEllipsizeFlags enumeration values combined.
 447     */
 448     static wxString Ellipsize(const wxString& label, const wxDC& dc,
 449                               wxEllipsizeMode mode, int maxWidth,
 450                               int flags = wxELLIPSIZE_FLAGS_DEFAULT);
 451 };
 452