interface/wx/stattext.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        stattext.h
   3 // Purpose:     interface of wxStaticText
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxStaticText
  11
  12     A static text control displays one or more lines of read-only text.
  13
  14     @beginStyleTable
  15     @style{wxALIGN_LEFT}
  16            Align the text to the left
  17     @style{wxALIGN_RIGHT}
  18            Align the text to the right
  19     @style{wxALIGN_CENTRE}
  20            Center the text (horizontally)
  21     @style{wxST_NO_AUTORESIZE}
  22            By default, the control will adjust its size to exactly fit to the
  23            size of the text when  SetLabel is called. If this style flag is
  24            given, the control will not change its size (this style is
  25            especially useful with controls which also have wxALIGN_RIGHT or
  26            CENTER style because otherwise they won't make sense any longer
  27            after a call to SetLabel)
  28     @style{wxST_ELLIPSIZE_START}
  29            If the text width exceeds the control width, replace the beginning
  30            of the text with an ellipsis
  31     @style{wxST_ELLIPSIZE_MIDDLE}
  32            Same as above, but replace the text in the middle of the control
  33            with an ellipsis
  34     @style{wxST_ELLIPSIZE_END}
  35            Same as above, but replace the end of the text with an ellipsis
  36     @style{wxST_MARKUP}
  37            Support markup in the label; see SetLabel for more information
  38     @endStyleTable
  39
  40     @library{wxcore}
  41     @category{ctrl}
  42     <!-- @appearance{statictext.png} -->
  43
  44     @see wxStaticBitmap, wxStaticBox
  45 */
  46 class wxStaticText : public wxControl
  47 {
  48 public:
  49     /**
  50         Default constructor.
  51     */
  52     wxStaticText();
  53
  54     /**
  55         Constructor, creating and showing a text control.
  56
  57         @param parent
  58             Parent window. Should not be @NULL.
  59         @param id
  60             Control identifier. A value of -1 denotes a default value.
  61         @param label
  62             Text label.
  63         @param pos
  64             Window position.
  65         @param size
  66             Window size.
  67         @param style
  68             Window style. See wxStaticText.
  69         @param name
  70             Window name.
  71
  72         @see Create()
  73     */
  74     wxStaticText(wxWindow* parent, wxWindowID id,
  75                  const wxString& label,
  76                  const wxPoint& pos = wxDefaultPosition,
  77                  const wxSize& size = wxDefaultSize,
  78                  long style = 0,
  79                  const wxString& name = "staticText");
  80
  81     /**
  82         Creation function, for two-step construction. For details see wxStaticText().
  83     */
  84     bool Create(wxWindow* parent, wxWindowID id,
  85                 const wxString& label,
  86                 const wxPoint& pos = wxDefaultPosition,
  87                 const wxSize& size = wxDefaultSize,
  88                 long style = 0,
  89                 const wxString& name = "staticText");
  90
  91     /**
  92         Returns the contents of the control.
  93
  94         Note that the returned string contains both the mnemonics (@& characters),
  95         if any, and markup tags, if any.
  96         Use GetLabelText() if only the label text is needed.
  97     */
  98     wxString GetLabel() const;
  99
 100     /**
 101         This method returns the control's label without the mnemonics characters
 102         (if any) and without the markup (if the control has @c wxST_MARKUP style).
 103     */
 104     wxString GetLabelText() const;
 105
 106     /**
 107         This overload returns the given @a label string without the
 108         mnemonics characters (if any) and without the markup.
 109     */
 110     static wxString GetLabelText(const wxString& label);
 111
 112     /**
 113         Sets the static text label and updates the controls size to exactly fit the
 114         label unless the control has wxST_NO_AUTORESIZE flag.
 115
 116         This function allows to set decorated static label text on platforms which
 117         support it (currently only GTK+ 2). For the other platforms, the markup is
 118         ignored.
 119
 120         The supported tags are:
 121         <TABLE>
 122             <TR>
 123                 <TD>&lt;b&gt;</TD>
 124                 <TD>bold text</TD>
 125             </TR>
 126             <TR>
 127                 <TD>&lt;big&gt;</TD>
 128                 <TD>bigger text</TD>
 129             </TR>
 130             <TR>
 131                 <TD>&lt;i&gt;</TD>
 132                 <TD>italic text</TD>
 133             </TR>
 134             <TR>
 135                 <TD>&lt;s&gt;</TD>
 136                 <TD>strike-through text</TD>
 137             </TR>
 138             <TR>
 139                 <TD>&lt;sub&gt;</TD>
 140                 <TD>subscript text</TD>
 141             </TR>
 142             <TR>
 143                 <TD>&lt;sup&gt;</TD>
 144                 <TD>superscript text</TD>
 145             </TR>
 146             <TR>
 147                 <TD>&lt;small&gt;</TD>
 148                 <TD>smaller text</TD>
 149             </TR>
 150             <TR>
 151                 <TD>&lt;tt&gt;</TD>
 152                 <TD>monospaced text</TD>
 153             </TR>
 154             <TR>
 155                 <TD>&lt;u&gt;</TD>
 156                 <TD>underlined text</TD>
 157             </TR>
 158             <TR>
 159                 <TD>&lt;span&gt;</TD>
 160                 <TD>generic formatter tag; see Pango Markup
 161                     (http://library.gnome.org/devel/pango/unstable/PangoMarkupFormat.html)
 162                     for more information.</TD>
 163             </TR>
 164         </TABLE>
 165
 166         Note that the string must be well-formed (e.g. all tags must be correctly
 167         closed) otherwise it can be not shown correctly or at all.
 168         Also note that you need to escape the following special characters:
 169
 170         <TABLE>
 171             <TR>
 172                 <TD>@b Special character</TD>
 173                 <TD>@b Escape as</TD>
 174             </TR>
 175             <TR>
 176                 <TD>@c &amp;</TD>
 177                 <TD>@c &amp;amp; or as &amp;&amp;</TD>
 178             </TR>
 179             <TR>
 180                 <TD>@c &apos;</TD>
 181                 <TD>@c &amp;apos;</TD>
 182             </TR>
 183             <TR>
 184                 <TD>@c &quot;</TD>
 185                 <TD>@c &amp;quot;</TD>
 186             </TR>
 187             <TR>
 188                 <TD>@c &lt;</TD>
 189                 <TD>@c &amp;lt;</TD>
 190             </TR>
 191             <TR>
 192                 <TD>@c &gt;</TD>
 193                 <TD>@c &amp;gt;</TD>
 194             </TR>
 195         </TABLE>
 196
 197         The non-escaped ampersand @c &amp; characters are interpreted as
 198         mnemonics; see wxControl::SetLabel.
 199
 200         Example:
 201
 202         @param label
 203             The new label to set.
 204             It may contain newline characters and the markup tags described above.
 205     */
 206     virtual void SetLabel(const wxString& label);
 207
 208     /**
 209         This functions wraps the controls label so that each of its lines becomes at
 210         most @a width pixels wide if possible (the lines are broken at words
 211         boundaries so it might not be the case if words are too long).
 212
 213         If @a width is negative, no wrapping is done. Note that this width is not
 214         necessarily the total width of the control, since a few pixels for the
 215         border (depending on the controls border style) may be added.
 216
 217         @since 2.6.2
 218     */
 219     void Wrap(int width);
 220 };
 221