Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 final 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 http:// can be converted into hyperlinks on the fly.

When configured to use formatting XML, the control requires the root element `form` to be used. 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 to 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.
- 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.
- 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.

None of the elements can nest. For example, you cannot have b inside a span . This was done to keep everything simple and transparent.

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.

You should be careful not to ask the control to render large quantities of text. It does not have advanced support for dirty regions and will repaint fully each time. Instead, combine the control in a composite with other controls and let SWT take care of the dirty regions.

Although the class is not marked final,

Since:
  3.0
See Also:
  `FormToolkit`, `TableWrapLayout`

Field Summary
`int` | `marginHeight` Value of hte horizontal 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.
`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).
`protected void` | `contextMenuAboutToShow(IMenuManager manager)` Context menu is about to show - override to add actions to the menu manager.
`boolean` | `getFocus()` Test for focus.
`HyperlinkSettings` | `getHyperlinkSettings()` Returns the hyperlink settings that are in effect for this control.
`String` | `getLoadingText()` Returns the text that will be shown in the control while the real content is loading.
`boolean` | `getParagraphsSeparated()` Tests if there is some inter-paragraph spacing.
`boolean` | `isLoading()` Test if the widget is currently processing the text it is about to render.
`boolean` | `isWhitespaceNormalized()` Tests whether whitespace inside paragraph and list item is normalized.
`void` | `removeHyperlinkListener(IHyperlinkListener listener)` Removes the hyperlink 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.
`boolean` | `setFocus()` Sets the focus to the first hyperlink, or the widget itself if there are no hyperlinks.
`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)` Sets the text that will be shown in the control while the real content is loading.
`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
`getCaret, scroll, setCaret`

Methods inherited from class org.eclipse.swt.widgets.Composite
`checkSubclass, getChildren, getLayout, getTabList, layout, layout, setLayout, setTabList`

Methods inherited from class org.eclipse.swt.widgets.Scrollable
`computeTrim, getClientArea, getHorizontalBar, getVerticalBar`

Methods inherited from class org.eclipse.swt.widgets.Control
`addControlListener, addFocusListener, addHelpListener, addKeyListener, addMouseListener, addMouseMoveListener, addMouseTrackListener, addPaintListener, addTraverseListener, computeSize, forceFocus, getAccessible, getBackground, getBorderWidth, getBounds, getEnabled, getFont, getForeground, getLayoutData, getLocation, getMenu, getMonitor, getParent, getShell, getSize, getToolTipText, getVisible, internal_dispose_GC, internal_new_GC, isEnabled, isFocusControl, isReparentable, isVisible, moveAbove, moveBelow, pack, pack, redraw, redraw, removeControlListener, removeFocusListener, removeHelpListener, removeKeyListener, removeMouseListener, removeMouseMoveListener, removeMouseTrackListener, removePaintListener, removeTraverseListener, setBackground, setBounds, setBounds, setCapture, setCursor, setEnabled, setForeground, setLayoutData, setLocation, setLocation, setMenu, setParent, setRedraw, 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, 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 hte horizontal 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.

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

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

  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)

  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 a type `Color` .

### 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 a type `Font` .

### 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 http:// 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.

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

### setFocus

    public boolean setFocus()

  Sets the focus to the first hyperlink, or the widget itself if there are no hyperlinks.

  Overrides:
    `setFocus` in class `Composite`
  Returns:
    `true` if the control got focus, `false` otherwise.

### 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

### contextMenuAboutToShow

    protected void contextMenuAboutToShow(IMenuManager manager)

  Context menu is about to show - override to add actions to the menu manager. Subclasses are required to call 'super' when overriding.

  Parameters:
    `manager` - the pop-up menu manager

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

  Overrides:
    `computeSize` in class `Composite`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2004. All rights reserved.