interface/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     @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     @see wxStaticBitmap, wxStaticBox
  46 */
  47 class wxStaticText : public wxControl
  48 {
  49 public:
  50     //@{
  51     /**
  52         Constructor, creating and showing a text control.
  53
  54         @param parent
  55             Parent window. Should not be @NULL.
  56         @param id
  57             Control identifier. A value of -1 denotes a default value.
  58         @param label
  59             Text label.
  60         @param pos
  61             Window position.
  62         @param size
  63             Window size.
  64         @param style
  65             Window style. See wxStaticText.
  66         @param name
  67             Window name.
  68
  69         @see Create()
  70     */
  71     wxStaticText();
  72     wxStaticText(wxWindow* parent, wxWindowID id,
  73                  const wxString& label,
  74                  const wxPoint& pos = wxDefaultPosition,
  75                  const wxSize& size = wxDefaultSize,
  76                  long style = 0,
  77                  const wxString& name = "staticText");
  78     //@}
  79
  80     /**
  81         Creation function, for two-step construction. For details see wxStaticText().
  82     */
  83     bool Create(wxWindow* parent, wxWindowID id,
  84                 const wxString& label,
  85                 const wxPoint& pos = wxDefaultPosition,
  86                 const wxSize& size = wxDefaultSize,
  87                 long style = 0,
  88                 const wxString& name = "staticText");
  89
  90     /**
  91         Returns the contents of the control.
  92         Note that the returned string contains both the mnemonics (@c  characters),
  93         if any, and markup tags, if any.
  94         Use GetLabelText() if only the
  95         label text is needed.
  96     */
  97     wxString GetLabel() const;
  98
  99     //@{
 100     /**
 101         The first form returns the control's label without the mnemonics characters (if
 102         any)
 103         and without the markup (if the control has @c wxST_MARKUP style).
 104         The second (static) version returns the given @a label string without the
 105         mnemonics
 106         characters (if any) and without the markup.
 107     */
 108     wxString GetLabelText();
 109     const static wxString  GetLabelText(const wxString& label);
 110     //@}
 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         This function allows to set decorated static label text on platforms which
 116         support it (currently only GTK+ 2). For the other platforms, the markup is
 117         ignored.
 118         The supported tags are:
 119
 120         b
 121
 122         bold text
 123
 124         big
 125
 126         bigger text
 127
 128         i
 129
 130         italic text
 131
 132         s
 133
 134         strike-through text
 135
 136         sub
 137
 138         subscript text
 139
 140         sup
 141
 142         superscript text
 143
 144         small
 145
 146         smaller text
 147
 148         tt
 149
 150         monospaced text
 151
 152         u
 153
 154         underlined text
 155
 156         span
 157
 158         generic formatter tag; see Pango Markup for more information.
 159
 160         Note that the string must be well-formed (e.g. all tags must be correctly
 161         closed)
 162         otherwise it can be not shown correctly or at all.
 163         Also note that you need to escape the following special characters:
 164
 165         @b Special character
 166
 167         @b Escape as
 168
 169         @c
 170
 171         @c amp; or as @c
 172
 173         @c '
 174
 175         @c apos;
 176
 177         @c "
 178
 179         @c quot;
 180
 181         @c
 182
 183         @c lt;
 184
 185         @c
 186
 187         @c gt;
 188
 189         The non-escaped ampersand @c  characters are interpreted as
 190         mnemonics; see wxControl::SetLabel.
 191
 192         Example:
 193
 194         @param label
 195             The new label to set. It may contain newline characters and the markup tags
 196         described above.
 197     */
 198     virtual void SetLabel(const wxString& label);
 199
 200     /**
 201         This functions wraps the controls label so that each of its lines becomes at
 202         most @a width pixels wide if possible (the lines are broken at words
 203         boundaries so it might not be the case if words are too long). If @e width
 204         is negative, no wrapping is done. Note that this width is not
 205         necessarily the total width of the control, since a few pixels for the
 206         border (depending on the controls border style) may be added.
 207
 208         @since 2.6.2
 209     */
 210     void Wrap(int width);
 211 };
 212