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 FormToolkit

    java.lang.Object
      org.eclipse.ui.forms.widgets.FormToolkit

public class FormToolkit
extends Object

The toolkit is responsible for creating SWT controls adapted to work in Eclipse forms. In addition to changing their presentation properties (fonts, colors etc.), various listeners are attached to make them behave correctly in the form context.

In addition to being the control factory, the toolkit is also responsible for painting flat borders for select controls, managing hyperlink groups and control colors.

The toolkit creates some of the most common controls used to populate Eclipse forms. Controls that must be created using their constructors, `adapt() method is available to change its properties in the same way as with the supported toolkit controls.`

Typically, one toolkit object is created per workbench part (for example, an editor or a form wizard). The toolkit is disposed when the part is disposed. To conserve resources, it is possible to create one color object for the entire plug-in and share it between several toolkits. The plug-in is responsible for disposing the colors (disposing the toolkit that uses shared color object will not dispose the colors).

FormToolkit is normally instantiated, but can also be subclassed if some of the methods needs to be modified. In those cases, `super` must be called to preserve normal behaviour.

Since:
  3.0

Field Summary
`static String` | `KEY_DRAW_BORDER`
`static String` | `TEXT_BORDER`
`static String` | `TREE_BORDER`

Constructor Summary
`FormToolkit(Display display)` Creates a toolkit that is self-sufficient (will manage its own colors).
`FormToolkit(FormColors colors)` Creates a toolkit that will use the provided (shared) colors.

Method Summary
`void` | `adapt(Composite composite)` Adapts a composite to be used in a form associated with this toolkit.
`void` | `adapt(Control control, boolean trackFocus, boolean trackKeyboard)` Adapts a control to be used in a form that is associated with this toolkit.
`Button` | `createButton(Composite parent, String text, int style)` Creates a button as a part of the form.
`Composite` | `createComposite(Composite parent)` Creates the composite as a part of the form.
`Composite` | `createComposite(Composite parent, int style)` Creates the composite as part of the form using the provided style.
`Composite` | `createCompositeSeparator(Composite parent)` Creats the composite that can server as a separator between various parts of a form.
`ExpandableComposite` | `createExpandableComposite(Composite parent, int expansionStyle)` Creates an expandable composite as a part of the form.
`Form` | `createForm(Composite parent)` Creates a form widget in the provided parent.
`FormText` | `createFormText(Composite parent, boolean trackFocus)` Creates a rich text as a part of the form.
`Hyperlink` | `createHyperlink(Composite parent, String text, int style)` Creates a hyperlink as a part of the form.
`ImageHyperlink` | `createImageHyperlink(Composite parent, int style)` Creates an image hyperlink as a part of the form.
`Label` | `createLabel(Composite parent, String text)` Creates a label as a part of the form.
`Label` | `createLabel(Composite parent, String text, int style)` Creates a label as a part of the form.
`ScrolledPageBook` | `createPageBook(Composite parent, int style)` Creates a rich text as a part of the form.
`ScrolledForm` | `createScrolledForm(Composite parent)` Creates a scrolled form widget in the provided parent.
`Section` | `createSection(Composite parent, int sectionStyle)` Creates a section as a part of the form.
`Label` | `createSeparator(Composite parent, int style)` Creates a separator label as a part of the form.
`Table` | `createTable(Composite parent, int style)` Creates a table as a part of the form.
`Text` | `createText(Composite parent, String value)` Creates a text as a part of the form.
`Text` | `createText(Composite parent, String value, int style)` Creates a text as a part of the form.
`Tree` | `createTree(Composite parent, int style)` Creates a tree widget as a part of the form.
`void` | `dispose()` Disposes the toolkit.
`static void` | `ensureVisible(Control c)` A helper method that ensures the provided control is visible when ScrolledComposite is somewhere in the parent chain.
`int` | `getBorderStyle()` Returns the border style used for various widgets created by this toolkit.
`FormColors` | `getColors()` Returns the colors used by this toolkit.
`HyperlinkGroup` | `getHyperlinkGroup()` Returns the hyperlink group that manages hyperlinks for this toolkit.
`void` | `paintBordersFor(Composite parent)` Paints flat borders for widgets created by this toolkit within the provided parent.
`void` | `refreshHyperlinkColors()` Refreshes the hyperlink colors by loading from JFace settings.
`void` | `setBackground(Color bg)` Sets the background color for the entire toolkit.
`void` | `setBorderStyle(int style)` Sets the border style to be used when creating widgets.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### KEY_DRAW_BORDER

    public static final String KEY_DRAW_BORDER

See Also:
  Constant Field Values

### TREE_BORDER

    public static final String TREE_BORDER

See Also:
  Constant Field Values

### TEXT_BORDER

    public static final String TEXT_BORDER

See Also:
  Constant Field Values

Constructor Detail

### FormToolkit

    public FormToolkit(Display display)

  Creates a toolkit that is self-sufficient (will manage its own colors).

### FormToolkit

    public FormToolkit(FormColors colors)

  Creates a toolkit that will use the provided (shared) colors. The toolkit will not dispose the provided colors.

Parameters:
  `colors` - the shared colors

Method Detail

### createButton

    public Button createButton(Composite parent,
                               String text,
                               int style)

  Creates a button as a part of the form.

  Parameters:
    `parent` - the button parent
    `text` - an optional text for the button (can be `null`)
    `style` - the button style (for example, `SWT.PUSH`)
  Returns:
    the button widget

### createComposite

    public Composite createComposite(Composite parent)

  Creates the composite as a part of the form.

  Parameters:
    `parent` - the composite parent
  Returns:
    the composite widget

### createComposite

    public Composite createComposite(Composite parent,
                                     int style)

  Creates the composite as part of the form using the provided style.

  Parameters:
    `parent` - the composite parent
    `style` - the composite style
  Returns:
    the composite widget

### createCompositeSeparator

    public Composite createCompositeSeparator(Composite parent)

  Creats the composite that can server as a separator between various parts of a form. Separator height should be controlled by setting the height hint on the layout data for the composite.

  Parameters:
    `parent` - the separator parent
  Returns:
    the separator widget

### createLabel

    public Label createLabel(Composite parent,
                             String text)

  Creates a label as a part of the form.

  Parameters:
    `parent` - the label parent
    `text` - the label text
  Returns:
    the label widget

### createLabel

    public Label createLabel(Composite parent,
                             String text,
                             int style)

  Creates a label as a part of the form.

  Parameters:
    `parent` - the label parent
    `text` - the label text
    `style` - the label style
  Returns:
    the label widget

### createHyperlink

    public Hyperlink createHyperlink(Composite parent,
                                     String text,
                                     int style)

  Creates a hyperlink as a part of the form. The hyperlink will be added to the hyperlink group that belongs to this toolkit.

  Parameters:
    `parent` - the hyperlink parent
    `text` - the text of the hyperlink
    `style` - the hyperlink style
  Returns:
    the hyperlink widget

### createImageHyperlink

    public ImageHyperlink createImageHyperlink(Composite parent,
                                               int style)

  Creates an image hyperlink as a part of the form. The hyperlink will be added to the hyperlink group that belongs to this toolkit.

  Parameters:
    `parent` - the hyperlink parent
    `style` - the hyperlink style
  Returns:
    the image hyperlink widget

### createFormText

    public FormText createFormText(Composite parent,
                                   boolean trackFocus)

  Creates a rich text as a part of the form.

  Parameters:
    `parent` - the rich text parent
    `trackFocus` - if `true`, the toolkit will monitor focus transfers to ensure that the hyperlink in focus is visible in the form.
  Returns:
    the rich text widget

### adapt

    public void adapt(Control control,
                      boolean trackFocus,
                      boolean trackKeyboard)

  Adapts a control to be used in a form that is associated with this toolkit. This involves adjusting colors and optionally adding handlers to ensure focus tracking and keyboard management.

  Parameters:
    `control` - a control to adapt
    `trackFocus` - if `true`, form will be scrolled horizontally and/or vertically if needed to ensure that the control is visible when it gains focus. Set it to `false` if the control is not capable of gaining focus.
    `trackKeyboard` - if `true`, the control that is capable of gaining focus will be tracked for certain keys that are important to the underlying form (for example, PageUp, PageDown, ScrollUp, ScrollDown etc.). Set it to `false` if the control is not capable of gaining focus or these particular key event are already used by the control.

### adapt

    public void adapt(Composite composite)

  Adapts a composite to be used in a form associated with this toolkit.

  Parameters:
    `composite` - the composite to adapt

### ensureVisible

    public static void ensureVisible(Control c)

  A helper method that ensures the provided control is visible when ScrolledComposite is somewhere in the parent chain. If scroll bars are visible and the control is clipped, the client of the scrolled composite will be scrolled to reveal the control.

  Parameters:
    `c` - the control to reveal

### createSection

    public Section createSection(Composite parent,
                                 int sectionStyle)

  Creates a section as a part of the form.

  Parameters:
    `parent` - the section parent
    `sectionStyle` - the section style
  Returns:
    the section widget

### createExpandableComposite

    public ExpandableComposite createExpandableComposite(Composite parent,
                                                         int expansionStyle)

  Creates an expandable composite as a part of the form.

  Parameters:
    `parent` - the expandable composite parent
    `expansionStyle` - the expandable composite style
  Returns:
    the expandable composite widget

### createSeparator

    public Label createSeparator(Composite parent,
                                 int style)

  Creates a separator label as a part of the form.

  Parameters:
    `parent` - the separator parent
    `style` - the separator style
  Returns:
    the separator label

### createTable

    public Table createTable(Composite parent,
                             int style)

  Creates a table as a part of the form.

  Parameters:
    `parent` - the table parent
    `style` - the table style
  Returns:
    the table widget

### createText

    public Text createText(Composite parent,
                           String value)

  Creates a text as a part of the form.

  Parameters:
    `parent` - the text parent
    `value` - the text initial value
  Returns:
    the text widget

### createText

    public Text createText(Composite parent,
                           String value,
                           int style)

  Creates a text as a part of the form.

  Parameters:
    `parent` - the text parent
    `value` - the text initial value
  Returns:
    the text widget

### createTree

    public Tree createTree(Composite parent,
                           int style)

  Creates a tree widget as a part of the form.

  Parameters:
    `parent` - the tree parent
    `style` - the tree style
  Returns:
    the tree widget

### createScrolledForm

    public ScrolledForm createScrolledForm(Composite parent)

  Creates a scrolled form widget in the provided parent. If you do not require scrolling because there is already a scrolled composite up the parent chain, use 'createForm' instead.

  Parameters:
    `parent` - the scrolled form parent
  Returns:
    the form that can scroll itself
  See Also:
    `createForm(org.eclipse.swt.widgets.Composite)`

### createForm

    public Form createForm(Composite parent)

  Creates a form widget in the provided parent. Note that this widget does not scroll its content, so make sure there is a scrolled composite up the parent chain. If you require scrolling, use 'createScrolledForm' instead.

  Returns:
    the form that does not scroll
  See Also:
    `createScrolledForm(org.eclipse.swt.widgets.Composite)`

### createPageBook

    public ScrolledPageBook createPageBook(Composite parent,
                                           int style)

  Creates a rich text as a part of the form.

  Parameters:
    `parent` - the rich text parent
  Returns:
    the rich text widget

### dispose

    public void dispose()

  Disposes the toolkit.

### getHyperlinkGroup

    public HyperlinkGroup getHyperlinkGroup()

  Returns the hyperlink group that manages hyperlinks for this toolkit.

  Returns:
    the hyperlink group

### setBackground

    public void setBackground(Color bg)

  Sets the background color for the entire toolkit. The method delegates the call to the FormColors object and also updates the hyperlink group so that hyperlinks and other objects are in sync.

  Parameters:
    `bg` - the new background color

### refreshHyperlinkColors

    public void refreshHyperlinkColors()

  Refreshes the hyperlink colors by loading from JFace settings.

### paintBordersFor

    public void paintBordersFor(Composite parent)

  Paints flat borders for widgets created by this toolkit within the provided parent. Borders will not be painted if the global border style is SWT.BORDER (i.e. if native borders are used). Call this method during creation of a form composite to get the borders of its children painted. Care should be taken when selection layout margins. At least one pixel pargin width and height must be chosen to allow the toolkit to paint the border on the parent around the widgets.

  Borders are painted for some controls that are selected by the toolkit by default. If a control needs a border but is not on its list, it is possible to force border in the following way:

          widget.setData(FormToolkit.KEY_DRAW_BORDER, FormToolkit.TREE_BORDER);

          or

          widget.setData(FormToolkit.KEY_DRAW_BORDER, FormToolkit.TEXT_BORDER);

  Parameters:
    `parent` - the parent that owns the children for which the border needs to be painted.

### getColors

    public FormColors getColors()

  Returns the colors used by this toolkit.

  Returns:
    the color object

### getBorderStyle

    public int getBorderStyle()

  Returns the border style used for various widgets created by this toolkit. The intent of the toolkit is to create controls with styles that yield a 'flat' appearance. On systems where the native borders are already flat, we set the style to SWT.BORDER and don't paint the borders ourselves. Otherwise, the style is set to SWT.NULL, and borders are painted by the toolkit.

  Returns:
    the global border style

### setBorderStyle

    public void setBorderStyle(int style)

  Sets the border style to be used when creating widgets. The toolkit chooses the correct style based on the platform but this value can be changed using this method.

  Parameters:
    `style` - `SWT.BORDER` or `SWT.NULL`
  See Also:
    `getBorderStyle()`

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.