eu.webtoolkit.jwt
Class WText

java.lang.Object
  eu.webtoolkit.jwt.WObject
      eu.webtoolkit.jwt.WWidget
          eu.webtoolkit.jwt.WWebWidget
              eu.webtoolkit.jwt.WInteractWidget
                  eu.webtoolkit.jwt.WText

Direct Known Subclasses:

WDefaultLoadingIndicator

public class WText
extends WInteractWidget

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 TextFormat.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, JWt assumes that content in a WText is intended to be passive, and not contain any scripting elements.

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

In some situations, TextFormat.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.

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(Locale locale)

Constructor Summary

WText()
Creates a text widget with an empty text.

WText(java.lang.CharSequence text)
Creates a text widget with given text.

WText(java.lang.CharSequence text, TextFormat format)
Creates a text widget with given text and format.

WText(java.lang.CharSequence text, TextFormat format, WContainerWidget parent)
Creates a text widget with given text and format.

WText(java.lang.CharSequence text, WContainerWidget parent)
Creates a text widget with given text.

WText(WContainerWidget parent)
Creates a text widget with an empty text.

Method Summary

WLength	getPadding(Side side) Returns the padding set for the widget.
WString	getText() Returns the text.
TextFormat	getTextFormat() Returns the text format.
boolean	hasInternalPathEncoding() Returns whether internal paths are encoded.
boolean	isWordWrap() Returns whether the widget may break lines.
void	refresh() Refresh the widget.
void	remove() Destructor.
protected void	render(java.util.EnumSet<RenderFlag> flags)
void	setInternalPathEncoding(boolean enabled) Enables internal path encoding of anchors in the XHTML text.
void	setPadding(WLength length) Sets padding inside the widget.
void	setPadding(WLength length, java.util.EnumSet<Side> sides) Sets padding inside the widget.
void	setPadding(WLength length, Side side, Side... sides) Sets padding inside the widget.
boolean	setText(java.lang.CharSequence text) Sets the text.
boolean	setTextFormat(TextFormat textFormat) Sets the text format.
void	setWordWrap(boolean wordWrap) Configures word wrapping.

Methods inherited from class eu.webtoolkit.jwt.WInteractWidget

clicked, doubleClicked, enterPressed, escapePressed, gestureChanged, gestureEnded, gestureStarted, isEnabled, keyPressed, keyWentDown, keyWentUp, load, mouseDragged, mouseMoved, mouseWentDown, mouseWentOut, mouseWentOver, mouseWentUp, mouseWheel, propagateSetEnabled, setDraggable, setDraggable, setDraggable, setDraggable, touchEnded, touchMoved, touchStarted

Methods inherited from class eu.webtoolkit.jwt.WWebWidget

addStyleClass, callJavaScriptMember, childrenChanged, doJavaScript, domCanBeSaved, enableAjax, escapeText, escapeText, escapeText, escapeText, find, getAttributeValue, getChildren, getClearSides, getDecorationStyle, getFloatSide, getHeight, getId, getJavaScriptMember, getLineHeight, getMargin, getMaximumHeight, getMaximumWidth, getMinimumHeight, getMinimumWidth, getOffset, getPositionScheme, getStyleClass, getTabIndex, getToolTip, getVerticalAlignment, getVerticalAlignmentLength, getWidth, isDisabled, isHidden, isHiddenKeepsGeometry, isInline, isLoaded, isPopup, isRendered, isVisible, jsStringLiteral, jsStringLiteral, removeScript, removeStyleClass, resize, setAttributeValue, setClearSides, setDecorationStyle, setDisabled, setFloatSide, setHidden, setHiddenKeepsGeometry, setId, setInline, setJavaScriptMember, setLineHeight, setLoadLaterWhenInvisible, setMargin, setMaximumSize, setMinimumSize, setOffsets, setPopup, setPositionScheme, setSelectable, setStyleClass, setTabIndex, setToolTip, setVerticalAlignment, updateSignalConnection

Methods inherited from class eu.webtoolkit.jwt.WWidget

acceptDrops, acceptDrops, addCssRule, addCssRule, addStyleClass, animateHide, animateShow, boxBorder, boxPadding, containsExposed, disable, dropEvent, enable, getDrop, getJsRef, getParent, hide, htmlText, isLayoutSizeAware, layoutSizeChanged, positionAt, positionAt, removeStyleClass, resize, setClearSides, setHeight, setHidden, setLayoutSizeAware, setMargin, setMargin, setMargin, setMargin, setMargin, setOffsets, setOffsets, setOffsets, setOffsets, setOffsets, setToolTip, setVerticalAlignment, setWidth, show, stopAcceptDrops, toggleStyleClass, toggleStyleClass, tr

Methods inherited from class eu.webtoolkit.jwt.WObject

addChild, getObjectName, setObjectName

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

WText

public WText(WContainerWidget parent)

Creates a text widget with an empty text.

WText

public WText()

Creates a text widget with an empty text.

Calls this((WContainerWidget)null)

WText

public WText(java.lang.CharSequence text,
             WContainerWidget parent)

Creates a text widget with given text.

The textFormat is set to TextFormat.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 TextFormat.PlainText.

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

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

WText

public WText(java.lang.CharSequence text)

Creates a text widget with given text.

Calls this(text, (WContainerWidget)null)

WText

public WText(java.lang.CharSequence text,
             TextFormat format,
             WContainerWidget parent)

Creates a text widget with given text and format.

If textFormat is TextFormat.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 TextFormat.PlainText.

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

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

WText

public WText(java.lang.CharSequence text,
             TextFormat format)

Creates a text widget with given text and format.

Calls this(text, format, (WContainerWidget)null)

Method Detail

remove

public void remove()

Destructor.

Overrides:

remove in class WInteractWidget

See Also:

WContainerWidget.removeWidget(WWidget widget)

getText

public WString getText()

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(CharSequence text)

setText

public boolean setText(java.lang.CharSequence text)

Sets the text.

When the current format is TextFormat.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 TextFormat.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:

getText(), setText(CharSequence text)

setTextFormat

public boolean setTextFormat(TextFormat textFormat)

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 TextFormat.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 TextFormat.XHTMLText.

getTextFormat

public TextFormat getTextFormat()

Returns the text format.

See Also:

setTextFormat(TextFormat textFormat)

setWordWrap

public void setWordWrap(boolean 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 TextFormat.PlainText) or <br /> tags or other block-level tags (for TextFormat.XHTMLText).

The default value is true.

See Also:

isWordWrap()

isWordWrap

public boolean isWordWrap()

Returns whether the widget may break lines.

See Also:

setWordWrap(boolean wordWrap)

setPadding

public void setPadding(WLength length,
                       java.util.EnumSet<Side> sides)

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.

setPadding

public final void setPadding(WLength length,
                             Side side,
                             Side... sides)

Sets padding inside the widget.

Calls setPadding(length, EnumSet.of(side, sides))

setPadding

public final void setPadding(WLength length)

Sets padding inside the widget.

Calls setPadding(length, EnumSet.of (Side.Left, Side.Right))

getPadding

public WLength getPadding(Side side)

Returns the padding set for the widget.

See Also:

setPadding(WLength length, EnumSet sides)

setInternalPathEncoding

public void setInternalPathEncoding(boolean 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 TextFormat.XHTMLText (or TextFormat.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.

hasInternalPathEncoding

public boolean hasInternalPathEncoding()

Returns whether internal paths are encoded.

See Also:

setInternalPathEncoding(boolean enabled)

refresh

public void refresh()

Description copied from class: WWidget

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.

Overrides:

refresh in class WWebWidget

render

protected void render(java.util.EnumSet<RenderFlag> flags)

Overrides:

render in class WWebWidget