Class WText
- Direct Known Subclasses:
IndexText
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.XHTML
, 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.XHTML
format will automatically change to TextFormat.Plain
if
the text is not valid XML. Properly formatted HTML, which is not valid XHTML (e.g. a
<br>
tag without closing tag) will thus be shown literally, since the HTML markup
will be escaped. JWt does this as a safety measure, since it cannot reliably run the XSS filter
without parsing the XML successfully.
The TextFormat.Plain
format will display the text literally (escaping any HTML special
characters).
In some situations, TextFormat.UnsafeXHTML
may be useful to explicitly allow scripting
content. Like TextFormat.XHTML
, 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 TextFormat.XHTML
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.
-
Nested Class Summary
Nested classes/interfaces inherited from class eu.webtoolkit.jwt.WObject
WObject.FormData
-
Field Summary
Fields inherited from class eu.webtoolkit.jwt.WInteractWidget
dragTouchEndSlot_, dragTouchSlot_
-
Constructor Summary
ConstructorsConstructorDescriptionWText()
Creates a text widget with an empty text.WText
(WContainerWidget parentContainer) Creates a text widget with an empty text.WText
(CharSequence text) Creates a text widget with given text.WText
(CharSequence text, TextFormat format) Creates a text widget with given text and format.WText
(CharSequence text, TextFormat format, WContainerWidget parentContainer) Creates a text widget with given text and format.WText
(CharSequence text, WContainerWidget parentContainer) Creates a text widget with given text. -
Method Summary
Modifier and TypeMethodDescriptiongetPadding
(Side side) Returns the padding set for the widget.getText()
Returns the text.Returns the alignment of children.Returns the text format.boolean
Returns whether internal paths are encoded.boolean
Returns whether the widget may break lines.void
refresh()
Refresh the widget.void
remove()
Destructor.protected void
render
(EnumSet<RenderFlag> flags) Renders the widget.void
setInternalPathEncoding
(boolean enabled) Enables internal path encoding of anchors in the XHTML text.final void
setPadding
(WLength length) Sets padding inside the widget.final void
setPadding
(WLength length, Side side, Side... sides) Sets padding inside the widget.void
setPadding
(WLength length, EnumSet<Side> sides) Sets padding inside the widget.boolean
setText
(CharSequence text) Sets the text.void
setTextAlignment
(AlignmentFlag textAlignment) Specifies how text is aligned.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, getMouseOverDelay, isEnabled, keyPressed, keyWentDown, keyWentUp, load, mouseDragged, mouseMoved, mouseWentDown, mouseWentOut, mouseWentOver, mouseWentUp, mouseWheel, propagateSetEnabled, setDraggable, setDraggable, setDraggable, setDraggable, setMouseOverDelay, setPopup, touchEnded, touchMoved, touchStarted, unsetDraggable
Methods inherited from class eu.webtoolkit.jwt.WWebWidget
addStyleClass, beingDeleted, blurred, callJavaScriptMember, childrenChanged, createDomElement, doJavaScript, enableAjax, escapeText, escapeText, escapeText, escapeText, find, findById, focussed, getAttributeValue, getBaseZIndex, getChildren, getClearSides, getDecorationStyle, getDomChanges, getFloatSide, getHeight, getHtmlTagName, getId, getJavaScriptMember, getLineHeight, getMargin, getMaximumHeight, getMaximumWidth, getMinimumHeight, getMinimumWidth, getOffset, getPositionScheme, getScrollVisibilityMargin, getStyleClass, getTabIndex, getToolTip, getVerticalAlignment, getVerticalAlignmentLength, getWidth, hasFocus, hasStyleClass, isCanReceiveFocus, isDisabled, isHidden, isHiddenKeepsGeometry, isInline, isLoaded, isPopup, isRendered, isScrollVisibilityEnabled, isScrollVisible, isSetFirstFocus, isThemeStyleEnabled, isVisible, iterateChildren, jsStringLiteral, jsStringLiteral, manageWidget, parentResized, parentResized, propagateSetVisible, removeScript, removeStyleClass, resize, scrollVisibilityChanged, setAttributeValue, setBaseZIndex, setCanReceiveFocus, setClearSides, setDecorationStyle, setDeferredToolTip, setDisabled, setFlexBox, setFloatSide, setFocus, setHidden, setHiddenKeepsGeometry, setHtmlTagName, setId, setInline, setJavaScriptMember, setLineHeight, setLoadLaterWhenInvisible, setMargin, setMaximumSize, setMinimumSize, setObjectName, setOffsets, setParentWidget, setPositionScheme, setScrollVisibilityEnabled, setScrollVisibilityMargin, setSelectable, setStyleClass, setTabIndex, setThemeStyleEnabled, setToolTip, setVerticalAlignment, unescapeText, updateSignalConnection, voidEventSignal, widgetAdded, widgetRemoved
Methods inherited from class eu.webtoolkit.jwt.WWidget
acceptDrops, acceptDrops, addCssRule, addCssRule, addJSignal, addStyleClass, animateHide, animateShow, boxBorder, boxPadding, createJavaScript, disable, dropEvent, enable, getDropTouch, getJsRef, getParent, hide, htmlText, isExposed, isGlobalWidget, isLayoutSizeAware, layoutSizeChanged, needsRerender, positionAt, positionAt, removeFromParent, removeStyleClass, removeWidget, render, resize, scheduleRender, scheduleRender, scheduleRender, setClearSides, setDeferredToolTip, setFocus, 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
getObjectName, setFormData
-
Constructor Details
-
WText
Creates a text widget with an empty text. -
WText
public WText()Creates a text widget with an empty text. -
WText
Creates a text widget with given text.The textFormat is set to
TextFormat.XHTML
, unless thetext
is literal (not created usingWString#tr()
) and it could not be parsed as valid XML. In that case the textFormat is set toTextFormat.Plain
.Therefore, if you wish to use
TextFormat.XHTML
, but cannot be sure abouttext
being valid XML, you should verify that thegetTextFormat()
isTextFormat.XHTML
after construction.The XML parser will silently discard malicious tags and attributes for literal
TextFormat.XHTML
text. -
WText
Creates a text widget with given text. -
WText
Creates a text widget with given text and format.If textFormat is
TextFormat.XHTML
andtext
is not literal (not created usingWString#tr()
), then if thetext
could not be parsed as valid XML, the textFormat is changed toTextFormat.Plain
.Therefore, if you wish to use
TextFormat.XHTML
, but cannot be sure abouttext
being valid XML, you should verify that thegetTextFormat()
isTextFormat.XHTML
after construction.The XML parser will silently discard malicious tags and attributes for literal
TextFormat.XHTML
text. -
WText
Creates a text widget with given text and format.
-
-
Method Details
-
remove
public void remove()Destructor.- Overrides:
remove
in classWInteractWidget
- See Also:
-
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
Sets the text.When the current format is
TextFormat.XHTML
, andtext
is literal (not created usingWString#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 toTextFormat.Plain
. Iftext
is not a literal, the same parser is applied only when the text is resolved.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:
-
setTextFormat
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.XHTML
, and the current text is literal (not created usingWString#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.XHTML
. -
getTextFormat
Returns the text format.- See Also:
-
setWordWrap
public void setWordWrap(boolean wordWrap) Configures word wrapping.When
wordWrap
istrue
, the widget may break lines, creating a multi-line text. WhenwordWrap
isfalse
, the text will displayed on a single line, unless the text contains end-of-lines (forTextFormat.Plain
) or <br /> tags or other block-level tags (forTextFormat.XHTML
).The default value is
true
.- See Also:
-
isWordWrap
public boolean isWordWrap()Returns whether the widget may break lines.- See Also:
-
setTextAlignment
Specifies how text is aligned.Only the horizontal alignment can be specified. Note that there is no way to specify vertical alignment. You can put the text in a layout with vertical alignment options though, or (misuse) the line-height CSS property for single line texts.
-
getTextAlignment
Returns the alignment of children. -
setPadding
Sets padding inside the widget.Setting padding has the effect of adding distance between the widget children and the border.
Note: for an
inline
WText padding is only supported on the left and/or right. Setting padding on the top or bottom has no effect. -
setPadding
Sets padding inside the widget. -
setPadding
Sets padding inside the widget.Calls
setPadding(length, EnumSet.of (Side.Left, Side.Right))
-
getPadding
Returns the padding set for the widget. -
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.XHTML
(orTextFormat.UnsafeXHTML
) 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:
-
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.
Note: This does not rerender the widget! Calling
refresh()
usually does not have any effect (unless you've reimplementedrefresh()
to attach to it an effect).- Overrides:
refresh
in classWWebWidget
-
render
Description copied from class:WWidget
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.
- Overrides:
render
in classWWebWidget
-