interface/wx/control.h

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