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         Note that the returned string contains both the mnemonics (@c  characters),
  94         if any, and markup tags, if any.
  95         Use GetLabelText() if only the
  96         label text is needed.
  97     */
  98     wxString GetLabel() const;
  99
 100     //@{
 101     /**
 102         The first form returns the control's label without the mnemonics characters (if
 103         any)
 104         and without the markup (if the control has @c wxST_MARKUP style).
 105         The second (static) version returns the given @a label string without the
 106         mnemonics
 107         characters (if any) and without the markup.
 108     */
 109     wxString GetLabelText();
 110     const static wxString  GetLabelText(const wxString& label);
 111     //@}
 112
 113     /**
 114         Sets the static text label and updates the controls size to exactly fit the
 115         label unless the control has wxST_NO_AUTORESIZE flag.
 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         The supported tags are:
 120         <TABLE>
 121             <TR>
 122                 <TD>&lt;b&gt;</TD>
 123                 <TD>bold text</TD>
 124             </TR>
 125             <TR>
 126                 <TD>&lt;big&gt;</TD>
 127                 <TD>bigger text</TD>
 128             </TR>
 129             <TR>
 130                 <TD>&lt;i&gt;</TD>
 131                 <TD>italic text</TD>
 132             </TR>
 133             <TR>
 134                 <TD>&lt;s&gt;</TD>
 135                 <TD>strike-through text</TD>
 136             </TR>
 137             <TR>
 138                 <TD>&lt;sub&gt;</TD>
 139                 <TD>subscript text</TD>
 140             </TR>
 141             <TR>
 142                 <TD>&lt;sup&gt;</TD>
 143                 <TD>superscript text</TD>
 144             </TR>
 145             <TR>
 146                 <TD>&lt;small&gt;</TD>
 147                 <TD>smaller text</TD>
 148             </TR>
 149             <TR>
 150                 <TD>&lt;tt&gt;</TD>
 151                 <TD>monospaced text</TD>
 152             </TR>
 153             <TR>
 154                 <TD>&lt;u&gt;</TD>
 155                 <TD>underlined text</TD>
 156             </TR>
 157             <TR>
 158                 <TD>&lt;span&gt;</TD>
 159                 <TD>generic formatter tag; see Pango Markup for more information.</TD>
 160             </TR>
 161         </TABLE>
 162
 163         Note that the string must be well-formed (e.g. all tags must be correctly
 164         closed)
 165         otherwise it can be not shown correctly or at all.
 166         Also note that you need to escape the following special characters:
 167         <TABLE>
 168             <TR>
 169                 <TD>@b Special character</TD>
 170                 <TD>@b Escape as</TD>
 171             </TR>
 172             <TR>
 173                 <TD>@c &amp;</TD>
 174                 <TD>@c &amp;amp; or as &amp;&amp;</TD>
 175             </TR>
 176             <TR>
 177                 <TD>@c &apos;</TD>
 178                 <TD>@c &amp;apos;</TD>
 179             </TR>
 180             <TR>
 181                 <TD>@c &quot;</TD>
 182                 <TD>@c &amp;quot;</TD>
 183             </TR>
 184             <TR>
 185                 <TD>@c &lt;</TD>
 186                 <TD>@c &amp;lt;</TD>
 187             </TR>
 188             <TR>
 189                 <TD>@c &gt;</TD>
 190                 <TD>@c &amp;gt;</TD>
 191             </TR>
 192         </TABLE>
 193
 194         The non-escaped ampersand @c &amp; characters are interpreted as
 195         mnemonics; see wxControl::SetLabel.
 196
 197         Example:
 198
 199         @param label
 200             The new label to set. It may contain newline characters and the markup tags
 201         described above.
 202     */
 203     virtual void SetLabel(const wxString& label);
 204
 205     /**
 206         This functions wraps the controls label so that each of its lines becomes at
 207         most @a width pixels wide if possible (the lines are broken at words
 208         boundaries so it might not be the case if words are too long). If @e width
 209         is negative, no wrapping is done. Note that this width is not
 210         necessarily the total width of the control, since a few pixels for the
 211         border (depending on the controls border style) may be added.
 212
 213         @since 2.6.2
 214     */
 215     void Wrap(int width);
 216 };
 217