Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Programming
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Databases
Mail Systems
openSolaris
Eclipse Documentation
Techotopia.com
Virtuatopia.com

How To Guides
Virtualization
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Windows
Problem Solutions
Privacy Policy

  




 

 


Eclipse Platform
Release 3.5

org.eclipse.ui.forms.widgets
Class FormText

java.lang.Object
  extended by 

org.eclipse.swt.widgets.Widget
      extended by 

org.eclipse.swt.widgets.Control
          extended by 

org.eclipse.swt.widgets.Scrollable
              extended by 

org.eclipse.swt.widgets.Composite
                  extended by 

org.eclipse.swt.widgets.Canvas
                      extended by 
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. Canvas
drawBackground, getCaret, getIME, scroll, setCaret, setIME
 
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. Scrollable
computeTrim, getClientArea, getHorizontalBar, getVerticalBar
 
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
 
Methods inherited from class java.lang. Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

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).

Constructor Detail

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
Method Detail

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

Eclipse Platform
Release 3.5

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.


 
 
  Published under the terms of the Eclipse Public License Version 1.0 ("EPL") Design by Interspire