interface/stattext.h

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