Wt: Wt::WText Class Reference

Wt 3.3.0

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes

- Class List
- Class Hierarchy
- Class Members

Public Member Functions | Protected Member Functions
Wt::WText Class Reference

A widget that renders (XHTML) text. More...

`#include <Wt/WText>`

Inheritance diagram for Wt::WText:
[legend]

List of all members.

## Public Member Functions
| WText (WContainerWidget *parent=0)
| Creates a text widget with an empty text.
| WText (const WString &text, WContainerWidget *parent=0)
| Creates a text widget with given text.
| WText (const WString &text, TextFormat textFormat, WContainerWidget *parent=0)
| Creates a text widget with given text and format.
| ~WText ()
| Destructor.
const WString & | text () const
| Returns the text.
bool | setText (const WString &text)
| Sets the text.
bool | setTextFormat (TextFormat format)
| Sets the text format.
TextFormat | textFormat () const
| Returns the text format.
void | setWordWrap (bool wordWrap)
| Configures word wrapping.
bool | wordWrap () const
| Returns whether the widget may break lines.
void | setPadding (const WLength &padding, WFlags< Side > sides=Left|Right)
| Sets padding inside the widget.
WLength | padding (Side side) const
| Returns the padding set for the widget.
void | setInternalPathEncoding (bool enabled)
| Enables internal path encoding of anchors in the XHTML text.
bool | hasInternalPathEncoding () const
| Returns whether internal paths are encoded.
virtual void | refresh ()
| Refresh the widget.
## Protected Member Functions
virtual void | render (WFlags< RenderFlag > flags)
| Renders the widget.

## Detailed Description

A widget that renders (XHTML) text.

The text is provided through a WString, which may either hold a literal text, or a key to localized text which is looked up in locale dependent XML files (see WString::tr()).

Use setTextFormat() to configure the textFormat of the text. The default textFormat is Wt::XHTMLText, which allows XHMTL markup to be included in the text. Tags and attributes that indicate "active" content are not allowed and stripped out, to avoid security risks exposed by JavaScript such as the common web-based Cross-Site Scripting (XSS) malicious attack. XSS is the situation where one user of your web application is able to execute a script in another user's browser while your application only intended to display a message entered by the mailicious user to the other user. To defeat this attack, Wt assumes that content in a WText is intended to be passive, and not contain any scripting elements.

The Wt::PlainText format will display the text literally (escaping any HTML special characters).

In some situations, Wt::XHTMLUnsafeText may be useful to explicitly allow scripting content. Like XHTMLText, it allows XHTML markup, but it also allows potentially dangerous tags and attributes. Use this if you're sure that a user cannot interfere with the text set, and XHTMLText is too limiting.

WText is by default inline, unless the XHTML contents starts with an element such as `<div>`, `<h>` or `<p>` that is displayed as a block, in which case the widget will also display as a block.

Usage examples:

     Wt::WContainerWidget *container = new Wt::WContainerWidget();

     // display an XHTML text:
     container->addWidget(new Wt::WText("Hello <i>dear</i> visitor."));

     // display a plain text:
     container->addWidget(new Wt::WText("The <i> tag displays italic text.", Wt::PlainText));

     // display an XHTML fragment from a resource bundle:
     container->addWidget(new Wt::WText(tr("introduction")));

### CSS

The widget corresponds to an HTML `<span>` tag or an HTML `<div>` depending on whether the widget is inline.

This widget does not provide styling, and can be styled using inline or external CSS as appropriate.

See also:
  WApplication::setLocale()
  WApplication::messageResourceBundle()

## Constructor & Destructor Documentation

Wt::WText::WText | ( | const WString & | text,
|  | WContainerWidget * | parent = `0`
| ) |  |

Creates a text widget with given text.

The textFormat is set to Wt::XHTMLText, unless the `text` is literal (not created using WString::tr()) and it could not be parsed as valid XML. In that case the textFormat is set to Wt::PlainText.

Therefore, if you wish to use Wt::XHTMLText, but cannot be sure about `text` being valid XML, you should verify that the textFormat() is Wt::XHTMLText after construction.

The XML parser will silently discard malicious tags and attributes for literal Wt::XHTMLText text.

Wt::WText::WText | ( | const WString & | text,
|  | TextFormat | textFormat,
|  | WContainerWidget * | parent = `0`
| ) |  |

Creates a text widget with given text and format.

If textFormat is Wt::XHTMLText and `text` is not literal (not created using WString::tr()), then if the `text` could not be parsed as valid XML, the textFormat is changed to Wt::PlainText.

Therefore, if you wish to use Wt::XHTMLText, but cannot be sure about `text` being valid XML, you should verify that the textFormat() is Wt::XHTMLText after construction.

The XML parser will silently discard malicious tags and attributes for literal Wt::XHTMLText text.

## Member Function Documentation

bool Wt::WText::hasInternalPathEncoding | ( |  | ) | const

Returns whether internal paths are encoded.

See also:
  setInternalPathEncoding()

WLength Wt::WText::padding | ( | Side | side | ) | const

Returns the padding set for the widget.

See also:
  setPadding(const WLength&, WFlags<Side>)

void Wt::WText::refresh | ( |  | ) | `[virtual]`

Refresh the widget.

The refresh method is invoked when the locale is changed using WApplication::setLocale() or when the user hit the refresh button.

The widget must actualize its contents in response.

Reimplemented from Wt::WWebWidget.

void Wt::WText::render | ( | WFlags< RenderFlag > | flags | ) | `[protected, virtual]`

Renders the widget.

This function renders the widget (or an update for the widget), after this has been scheduled using scheduleRender().

The default implementation will render the widget by serializing changes to JavaScript and HTML. You may want to reimplement this widget if you have been postponing some of the layout / rendering implementation until the latest moment possible. In that case you should make sure you call the base implementation however.

Reimplemented from Wt::WWebWidget.

void Wt::WText::setInternalPathEncoding | ( | bool | enabled | ) |

Enables internal path encoding of anchors in the XHTML text.

Anchors to internal paths are represented differently depending on the session implementation (plain HTML, Ajax or HTML5 history). By enabling this option, anchors which reference an internal path (by referring a URL of the form `href="#/..."`), are re-encoded to link to the internal path.

When using Wt::XHTMLText (or Wt::XHTMLUnsafeText) formatted text, the text is pasted verbatim in the browser (with the exception of XSS filtering if applicable). With this option, however, the XHTML text may be transformed at the cost of an additional XML parsing step.

The default value is `false`.

See also:
  WAnchor::setInternalPath()

void Wt::WText::setPadding | ( | const WLength & | padding,
|  | WFlags< Side > | sides = `Left | Right`
| ) |  |

Sets padding inside the widget.

Setting padding has the effect of adding distance between the widget children and the border, for a WText padding is only supported on the left and/or right.

bool Wt::WText::setText | ( | const WString & | text | ) |

Sets the text.

When the current format is Wt::XHTMLText, and `text` is literal (not created using WString::tr()), it is parsed using an XML parser which discards malicious tags and attributes silently. When the parser encounters an XML parse error, the textFormat is changed to Wt::PlainText.

Returns whether the text could be set using the current textFormat. A return value of `false` indicates that the textFormat was changed in order to be able to accept the new text.

See also:
  text(), setText()

bool Wt::WText::setTextFormat | ( | TextFormat | format | ) |

Sets the text format.

The textFormat controls how the string should be interpreted: either as plain text, which is displayed literally, or as XHTML-markup.

When changing the textFormat to Wt::XHTMLText, and the current text is literal (not created using WString::tr()), the current text is parsed using an XML parser which discards malicious tags and attributes silently. When the parser encounters an XML parse error, the textFormat is left unchanged, and this method returns false.

Returns whether the textFormat could be set for the current text.

The default format is Wt::XHTMLText.

void Wt::WText::setWordWrap | ( | bool | wordWrap | ) |

Configures word wrapping.

When `wordWrap` is `true`, the widget may break lines, creating a multi-line text. When `wordWrap` is `false`, the text will displayed on a single line, unless the text contains end-of-lines (for Wt::PlainText) or <br /> tags or other block-level tags (for Wt::XHTMLText).

The default value is `true`.

See also:
  wordWrap()

const WString& Wt::WText::text | ( |  | ) | const

Returns the text.

When a literal XHTMLFormatted text was set, this may differ from the text that was set since malicious tags/attributes may have been stripped.

See also:
  setText(const WString&)

TextFormat Wt::WText::textFormat | ( |  | ) | const

Returns the text format.

See also:
  setTextFormat()

bool Wt::WText::wordWrap | ( |  | ) | const

Returns whether the widget may break lines.

See also:
  setWordWrap(bool)

All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator