| |
org.eclipse.ui.forms.widgets
Class FormText
java.lang.Object
org.eclipse.swt.widgets.Widget
org.eclipse.swt.widgets.Control
org.eclipse.swt.widgets.Scrollable
org.eclipse.swt.widgets.Composite
org.eclipse.swt.widgets.Canvas
org.eclipse.ui.forms.widgets.FormText
-
All Implemented Interfaces:
-
Drawable
-
public class FormText
- extends
Canvas
This class is a read-only text control that is capable of rendering wrapped
text. Text can be rendered as-is or by parsing the formatting XML tags.
Independently, words that start with https:// can be converted into hyperlinks
on the fly.
When configured to use formatting XML, the control requires the root element
form to be used and requires any ampersand (&) characters in the text to
be replaced by the entity &. The following tags can be children of the
form element:
-
p - for defining paragraphs. The following attributes are
allowed:
-
vspace - if set to 'false', no vertical space will be added
(default is 'true')
-
li - for defining list items. The following attributes are
allowed:
-
vspace - the same as with the p tag
-
style - could be 'bullet' (default), 'text' and 'image'
-
value - not used for 'bullet'. For text, it is the value of the
text that is rendered as a bullet. For image, it is the href of the image to
be rendered as a bullet.
-
indent - the number of pixels to indent the text in the list item
-
bindent - the number of pixels to indent the bullet itself
Text in paragraphs and list items will be wrapped according to the width of
the control. The following tags can appear as children of either p or
li elements:
-
img - to render an image. Element accepts attribute 'href' that
is a key to the
Image set using 'setImage' method. Vertical
position of image relative to surrounding text is optionally controlled by
the attribute align that can have values top, middle
and bottom
-
a - to render a hyperlink. Element accepts attribute 'href' that
will be provided to the hyperlink listeners via HyperlinkEvent object. The
element also accepts 'nowrap' attribute (default is false). When set to
'true', the hyperlink will not be wrapped. Hyperlinks automatically created
when 'https://' is encountered in text are not wrapped.
-
b - the enclosed text will use bold font.
-
br - forced line break (no attributes).
-
span - the enclosed text will have the color and font specified
in the element attributes. Color is provided using 'color' attribute and is a
key to the Color object set by 'setColor' method. Font is provided using
'font' attribute and is a key to the Font object set by 'setFont' method. As with
hyperlinks, it is possible to block wrapping by setting 'nowrap' to true
(false by default).
-
control (new in 3.1) - to place a control that is a child of the
text control. Element accepts attribute 'href' that is a key to the Control
object set using 'setControl' method. Optionally, attribute 'fill' can be set
to
true to make the control fill the entire width of the text.
Form text is not responsible for creating or disposing controls, it only
places them relative to the surrounding text. Similar to img,
vertical position of the control can be set using the align
attribute. In addition, width and height attributes can
be used to force the dimensions of the control. If not used,
the preferred control size will be used.
None of the elements can nest. For example, you cannot have b inside
a span . This was done to keep everything simple and transparent.
Since 3.1, an exception to this rule has been added to support nesting images
and text inside the hyperlink tag (a). Image enclosed in the
hyperlink tag acts as a hyperlink, can be clicked on and can accept and
render selection focus. When both text and image is enclosed, selection and
rendering will affect both as a single hyperlink.
Since 3.1, it is possible to select text. Text selection can be
programmatically accessed and also copied to clipboard. Non-textual objects
(images, controls etc.) in the selection range are ignored.
Care should be taken when using this control. Form text is not an HTML
browser and should not be treated as such. If you need complex formatting
capabilities, use Browser widget. If you need editing capabilities and
font/color styles of text segments is all you need, use StyleText widget.
Finally, if all you need is to wrap text, use SWT Label widget and create it
with SWT.WRAP style.
-
Since:
- 3.0
-
See Also:
-
FormToolkit,
TableWrapLayout
|
Field Summary
|
int
|
marginHeight
Value of tue vertical margin (default is 1). |
int
|
marginWidth
Value of the horizontal margin (default is 0). |
static
String
|
URL_HANDLER_ID
The object ID to be used when registering action to handle URL hyperlinks
(those that should result in opening the web browser). |
|
Fields inherited from class org.eclipse.swt.widgets.
Control
|
handle
|
|
Constructor Summary
|
FormText
(
Composite parent,
int style)
Contructs a new form text widget in the provided parent and using the
styles. |
|
Method Summary
|
void
|
addHyperlinkListener
(
IHyperlinkListener listener)
Adds a listener that will handle hyperlink events. |
void
|
addSelectionListener
(
SelectionListener listener)
Adds a selection listener. |
boolean
|
canCopy
()
Tests if the text is selected and can be copied into the clipboard. |
Point
|
computeSize
(int wHint,
int hHint,
boolean changed)
Overrides the method by fully trusting the layout manager (computed width
or height may be larger than the provider width or height hints). |
void
|
copy
()
Copies the selected text into the clipboard. |
boolean
|
getFocus
()
Test for focus. |
HyperlinkSettings
|
getHyperlinkSettings
()
Returns the hyperlink settings that are in effect for this control. |
String
|
getLoadingText
()
Deprecated. loading text is not used since 3.1
|
boolean
|
getParagraphsSeparated
()
Tests if there is some inter-paragraph spacing. |
Object
|
getSelectedLinkHref
()
Returns the reference of the hyperlink that currently has keyboard focus,
or null if there are no hyperlinks in the receiver or no
hyperlink has focus at the moment. |
String
|
getSelectedLinkText
()
Returns the text of the hyperlink that currently has keyboard focus, or
null if there are no hyperlinks in the receiver or no
hyperlink has focus at the moment. |
String
|
getSelectionText
()
Returns the selected text. |
boolean
|
isLoading
()
Deprecated. not used any more - returns false
|
boolean
|
isWhitespaceNormalized
()
Tests whether whitespace inside paragraph and list item is normalized. |
void
|
removeHyperlinkListener
(
IHyperlinkListener listener)
Removes the hyperlink listener. |
void
|
removeSelectionListener
(
SelectionListener listener)
Removes the specified selection listener. |
void
|
setColor
(
String key,
Color color)
Registers the color referenced by the provided key. |
void
|
setContents
(
InputStream is,
boolean expandURLs)
Sets the contents of the stream. |
void
|
setControl
(
String key,
Control control)
Registers the control referenced by the provided key. |
void
|
setEnabled
(boolean enabled)
Enables the receiver if the argument is true,
and disables it otherwise. |
boolean
|
setFocus
()
Causes the receiver to have the keyboard focus,
such that all keyboard events will be delivered to it. |
void
|
setFont
(
Font font)
Sets the font to use to render the default text (text that does not have
special font property assigned). |
void
|
setFont
(
String key,
Font font)
Registers the font referenced by the provided key. |
void
|
setHyperlinkSettings
(
HyperlinkSettings settings)
Sets the hyperlink settings to be used for this control. |
void
|
setImage
(
String key,
Image image)
Registers the image referenced by the provided key. |
void
|
setLoadingText
(
String loadingText)
Deprecated. use setText(loadingText, false, false);
|
void
|
setMenu
(
Menu menu)
Disposes the internal menu if created and sets the menu provided as a
parameter. |
void
|
setParagraphsSeparated
(boolean value)
If paragraphs are separated, spacing will be added between them. |
void
|
setText
(
String text,
boolean parseTags,
boolean expandURLs)
Sets the provided text. |
void
|
setWhitespaceNormalized
(boolean value)
Controls whether whitespace inside paragraph and list items is
normalized. |
|
Methods inherited from class org.eclipse.swt.widgets.
Composite
|
changed,
checkSubclass,
getBackgroundMode,
getChildren,
getLayout,
getLayoutDeferred,
getTabList,
isLayoutDeferred,
layout,
layout,
layout,
layout,
setBackgroundMode,
setLayout,
setLayoutDeferred,
setTabList
|
|
Methods inherited from class org.eclipse.swt.widgets.
Control
|
addControlListener,
addDragDetectListener,
addFocusListener,
addHelpListener,
addKeyListener,
addMenuDetectListener,
addMouseListener,
addMouseMoveListener,
addMouseTrackListener,
addMouseWheelListener,
addPaintListener,
addTraverseListener,
computeSize,
dragDetect,
dragDetect,
forceFocus,
getAccessible,
getBackground,
getBackgroundImage,
getBorderWidth,
getBounds,
getCursor,
getDragDetect,
getEnabled,
getFont,
getForeground,
getLayoutData,
getLocation,
getMenu,
getMonitor,
getParent,
getRegion,
getShell,
getSize,
getToolTipText,
getVisible,
internal_dispose_GC,
internal_new_GC,
isEnabled,
isFocusControl,
isReparentable,
isVisible,
moveAbove,
moveBelow,
pack,
pack,
print,
redraw,
redraw,
removeControlListener,
removeDragDetectListener,
removeFocusListener,
removeHelpListener,
removeKeyListener,
removeMenuDetectListener,
removeMouseListener,
removeMouseMoveListener,
removeMouseTrackListener,
removeMouseWheelListener,
removePaintListener,
removeTraverseListener,
setBackground,
setBackgroundImage,
setBounds,
setBounds,
setCapture,
setCursor,
setDragDetect,
setForeground,
setLayoutData,
setLocation,
setLocation,
setParent,
setRedraw,
setRegion,
setSize,
setSize,
setToolTipText,
setVisible,
toControl,
toControl,
toDisplay,
toDisplay,
traverse,
update
|
|
Methods inherited from class org.eclipse.swt.widgets.
Widget
|
addDisposeListener,
addListener,
checkWidget,
dispose,
getData,
getData,
getDisplay,
getListeners,
getStyle,
isDisposed,
isListening,
notifyListeners,
removeDisposeListener,
removeListener,
removeListener,
setData,
setData,
toString
|
URL_HANDLER_ID
public static final
String URL_HANDLER_ID
- The object ID to be used when registering action to handle URL hyperlinks
(those that should result in opening the web browser). Value is
"urlHandler".
-
See Also:
-
Constant Field Values
marginWidth
public int marginWidth
- Value of the horizontal margin (default is 0).
marginHeight
public int marginHeight
- Value of tue vertical margin (default is 1).
FormText
public FormText(
Composite parent,
int style)
- Contructs a new form text widget in the provided parent and using the
styles.
The only valid style bit for FormText is SWT.NO_FOCUS.
This will cause the widget to always refuse focus.
-
Parameters:
-
parent - form text parent control -
style - the widget style
getFocus
public boolean getFocus()
- Test for focus.
-
-
Returns:
-
true if the widget has focus.
isLoading
public boolean isLoading()
-
Deprecated. not used any more - returns
false
- Test if the widget is currently processing the text it is about to
render.
-
-
Returns:
-
true if the widget is still loading the text,
false otherwise.
getLoadingText
public
String getLoadingText()
-
Deprecated. loading text is not used since 3.1
- Returns the text that will be shown in the control while the real content
is loading.
-
-
Returns:
- loading text message
setLoadingText
public void setLoadingText(
String loadingText)
-
Deprecated. use setText(loadingText, false, false);
- Sets the text that will be shown in the control while the real content is
loading. This is significant when content to render is loaded from the
input stream that was created from a remote URL, and the time to load the
entire content is nontrivial.
-
-
Parameters:
-
loadingText - loading text message
setParagraphsSeparated
public void setParagraphsSeparated(boolean value)
- If paragraphs are separated, spacing will be added between them.
Otherwise, new paragraphs will simply start on a new line with no
spacing.
-
-
Parameters:
-
value - true if paragraphs are separated, false
otherwise.
getParagraphsSeparated
public boolean getParagraphsSeparated()
- Tests if there is some inter-paragraph spacing.
-
-
Returns:
-
true if paragraphs are separated, false
otherwise.
setImage
public void setImage(
String key,
Image image)
- Registers the image referenced by the provided key.
For img tags, an object of a type Image must
be registered using the key equivalent to the value of the href
attribute used in the tag.
-
-
Parameters:
-
key - unique key that matches the value of the href
attribute. -
image - an object of a type Image .
setColor
public void setColor(
String key,
Color color)
- Registers the color referenced by the provided key.
For span tags, an object of a type Color must
be registered using the key equivalent to the value of the color
attribute.
-
-
Parameters:
-
key - unique key that matches the value of the color
attribute. -
color - an object of the type Color or null
if the key needs to be cleared.
setFont
public void setFont(
String key,
Font font)
- Registers the font referenced by the provided key.
For span tags, an object of a type Font must
be registered using the key equivalent to the value of the font
attribute.
-
-
Parameters:
-
key - unique key that matches the value of the font
attribute. -
font - an object of the type Font or null
if the key needs to be cleared.
setControl
public void setControl(
String key,
Control control)
- Registers the control referenced by the provided key.
For control tags, an object of a type Control
must be registered using the key equivalent to the value of the
control attribute.
-
-
Parameters:
-
key - unique key that matches the value of the control
attribute. -
control - an object of the type Control or null
if the existing control at the specified key needs to be
removed. -
Since:
- 3.1
setFont
public void setFont(
Font font)
- Sets the font to use to render the default text (text that does not have
special font property assigned). Bold font will be constructed from this
font.
-
-
Overrides:
-
setFont
in class
Canvas
-
-
Parameters:
-
font - the default font to use
setText
public void setText(
String text,
boolean parseTags,
boolean expandURLs)
- Sets the provided text. Text can be rendered as-is, or by parsing the
formatting tags. Optionally, sections of text starting with https:// will
be converted to hyperlinks.
-
-
Parameters:
-
text - the text to render -
parseTags - if true , formatting tags will be parsed.
Otherwise, text will be rendered as-is. -
expandURLs - if true , URLs found in the untagged text will be
converted into hyperlinks.
setContents
public void setContents(
InputStream is,
boolean expandURLs)
- Sets the contents of the stream. Optionally, URLs in untagged text can be
converted into hyperlinks. The caller is responsible for closing the
stream.
-
-
Parameters:
-
is - stream to render -
expandURLs - if true , URLs found in untagged text will be
converted into hyperlinks.
setWhitespaceNormalized
public void setWhitespaceNormalized(boolean value)
- Controls whether whitespace inside paragraph and list items is
normalized. Note that the new value will not affect the current text in
the control, only subsequent calls to
setText or
setContents.
If normalized:
- all white space characters will be condensed into at most one when
between words.
- new line characters will be ignored and replaced with one white
space character
- white space characters after the opening tags and before the closing
tags will be trimmed
-
-
Parameters:
-
value - true if whitespace is normalized,
false otherwise.
isWhitespaceNormalized
public boolean isWhitespaceNormalized()
- Tests whether whitespace inside paragraph and list item is normalized.
-
-
Returns:
-
true if whitespace is normalized,
false otherwise. -
See Also:
-
setWhitespaceNormalized(boolean)
setMenu
public void setMenu(
Menu menu)
- Disposes the internal menu if created and sets the menu provided as a
parameter.
-
-
Overrides:
-
setMenu
in class
Control
-
-
Parameters:
-
menu - the menu to associate with this text control
getHyperlinkSettings
public
HyperlinkSettings getHyperlinkSettings()
- Returns the hyperlink settings that are in effect for this control.
-
-
Returns:
- current hyperlinks settings
setHyperlinkSettings
public void setHyperlinkSettings(
HyperlinkSettings settings)
- Sets the hyperlink settings to be used for this control. Settings will
affect things like hyperlink color, rendering style, cursor etc.
-
-
Parameters:
-
settings - hyperlink settings for this control
addHyperlinkListener
public void addHyperlinkListener(
IHyperlinkListener listener)
- Adds a listener that will handle hyperlink events.
-
-
Parameters:
-
listener - the listener to add
removeHyperlinkListener
public void removeHyperlinkListener(
IHyperlinkListener listener)
- Removes the hyperlink listener.
-
-
Parameters:
-
listener - the listener to remove
addSelectionListener
public void addSelectionListener(
SelectionListener listener)
- Adds a selection listener. A Selection event is sent by the widget when
the selection has changed.
widgetDefaultSelected is not called for FormText.
-
-
Parameters:
-
listener - the listener
-
Throws:
-
SWTException
-
- ERROR_WIDGET_DISPOSED - if the receiver has been
disposed
- ERROR_THREAD_INVALID_ACCESS - if not called from the
thread that created the receiver
-
IllegalArgumentException
-
- ERROR_NULL_ARGUMENT when listener is null
-
Since:
- 3.1
removeSelectionListener
public void removeSelectionListener(
SelectionListener listener)
- Removes the specified selection listener.
-
-
Parameters:
-
listener - the listener
-
Throws:
-
SWTException
-
- ERROR_WIDGET_DISPOSED - if the receiver has been
disposed
- ERROR_THREAD_INVALID_ACCESS - if not called from the
thread that created the receiver
-
IllegalArgumentException
-
- ERROR_NULL_ARGUMENT when listener is null
-
Since:
- 3.1
getSelectionText
public
String getSelectionText()
- Returns the selected text.
-
-
Returns:
- selected text, or an empty String if there is no selection.
-
Throws:
-
SWTException
-
- ERROR_WIDGET_DISPOSED - if the receiver has been
disposed
- ERROR_THREAD_INVALID_ACCESS - if not called from the
thread that created the receiver
-
Since:
- 3.1
canCopy
public boolean canCopy()
- Tests if the text is selected and can be copied into the clipboard.
-
-
Returns:
-
true if the selected text can be copied into the
clipboard, false otherwise. -
Since:
- 3.1
copy
public void copy()
- Copies the selected text into the clipboard. Does nothing if no text is
selected or the text cannot be copied for any other reason.
-
-
Since:
- 3.1
getSelectedLinkHref
public
Object getSelectedLinkHref()
- Returns the reference of the hyperlink that currently has keyboard focus,
or
null if there are no hyperlinks in the receiver or no
hyperlink has focus at the moment.
-
-
Returns:
- href of the selected hyperlink or
null if none
selected. -
Since:
- 3.1
getSelectedLinkText
public
String getSelectedLinkText()
- Returns the text of the hyperlink that currently has keyboard focus, or
null if there are no hyperlinks in the receiver or no
hyperlink has focus at the moment.
-
-
Returns:
- text of the selected hyperlink or
null if none
selected. -
Since:
- 3.1
computeSize
public
Point computeSize(int wHint,
int hHint,
boolean changed)
- Overrides the method by fully trusting the layout manager (computed width
or height may be larger than the provider width or height hints). Callers
should be prepared that the computed width is larger than the provided
wHint.
-
-
Overrides:
-
computeSize
in class
Composite
-
-
Parameters:
-
wHint - the width hint (can be SWT.DEFAULT) -
hHint - the height hint (can be SWT.DEFAULT) -
changed - true if the control's contents have changed, and false otherwise
-
Returns:
- the preferred size of the control.
-
See Also:
-
Composite.computeSize(int, int, boolean)
setEnabled
public void setEnabled(boolean enabled)
-
Description copied from class:
Control
- Enables the receiver if the argument is
true,
and disables it otherwise. A disabled control is typically
not selectable from the user interface and draws with an
inactive or "grayed" look.
-
-
Overrides:
-
setEnabled
in class
Control
-
-
Parameters:
-
enabled - the new enabled state
setFocus
public boolean setFocus()
-
Description copied from class:
Control
- Causes the receiver to have the keyboard focus,
such that all keyboard events will be delivered to it. Focus
reassignment will respect applicable platform constraints.
-
-
Overrides:
-
setFocus
in class
Composite
-
-
Returns:
-
true if the control got focus, and false if it was unable to. -
See Also:
-
Control.forceFocus()
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.
|
|
