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