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