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