Package org.eclipse.ui.forms.widgets

## Class Form

- 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.ui.forms.widgets.Form

All Implemented Interfaces:
  `Drawable`

    public class Form
    extends Composite

Form is a custom control that renders a title and an optional background image above the body composite. It can be used alone when part of parents that are scrolled. If scrolling is required, use `ScrolledForm` instead because it has an instance of `Form` and adds scrolling capability.

Form can have a title if set. If not set, title area will not be left empty - form body will be resized to fill the entire form. In addition, an optional title image can be set and is rendered to the left of the title (since 3.2).

Form can have a title drop down menu if the menu bar manager is not empty (since 3.3).

Form title can support drag and drop if drag and drop support methods are invoked. When used, additional decoration is rendered behind the title to reinforce the drag and drop ability (since 3.3).

The form supports status messages. These messages can have various severity (error, warning, info or none). If status hyperlink handler is specified, the messages with the specified severity other than none will be rendered as hyperlinks.

Form can have a background image behind the title text. The image is tiled as many times as needed to fill the title area. Alternatively, gradient background can be painted vertically or horizontally.

Form can be put in a 'busy' state. While in this state, title image is replaced with an animation that lasts as long as the 'busy' state is active.

It is possible to create an optional head client control. When created, this control is placed in the form heading as a second row.

Form has a custom layout manager that is wrap-enabled. If a form is placed in a composite whose layout manager implements ILayoutExtension, the body of the form will participate in wrapping as long as its layout manager implements ILayoutExtension as well.

Children of the form should typically be created using FormToolkit to match the appearance and behaviour. When creating children, use the form body as a parent by calling 'getBody()' on the form instance. Example:

     FormToolkit toolkit = new FormToolkit(parent.getDisplay());
     Form form = toolkit.createForm(parent);
     form.setText("Sample form");
     form.getBody().setLayout(new GridLayout());
     toolkit.createButton(form.getBody(), "Checkbox", SWT.CHECK);

No layout manager has been set on the body. Clients are required to set the desired layout manager explicitly.

Although the class is not final, it should not be subclassed.

Since:
  3.0
Restriction:
  This class is not intended to be subclassed by clients.

### Field Summary

### Fields inherited from class org.eclipse.swt.widgets.Control

`handle`

### Constructor Summary

Constructors
`Form​(Composite parent, int style)` Creates the form content control as a child of the provided parent.

### Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
`void` `addMessageHyperlinkListener​(IHyperlinkListener listener)` Adds a message hyperlink listener.
`void` `addTitleDragSupport​(int operations, Transfer[] transferTypes, DragSourceListener listener)` Adds support for dragging items out of the form title area via a user drag-and-drop operation.
`void` `addTitleDropSupport​(int operations, Transfer[] transferTypes, DropTargetListener listener)` Adds support for dropping items into the form title area via a user drag-and-drop operation.
`Image` `getBackgroundImage()` Returns the optional background image of the form head.
`int` `getBackgroundImageAlignment()` Deprecated. due to the underlying widget limitations, background image is either painted at 0,0 and/or tiled.
`Composite` `getBody()` Returns the container that occupies the body of the form (the form area below the title).
`IMessage[]` `getChildrenMessages()` Returns the children messages that the cause of the summary message currently set on the form.
`Composite` `getHead()` Returns the container that occupies the head of the form (the form area above the body).
`Control` `getHeadClient()` Returns the optional head client if set.
`Color` `getHeadColor​(String key)` Returns the color that is currently use to paint an aspect of the form heading, or `null` if not defined.
`Image` `getImage()` Returns the title image that will be rendered to the left of the title.
`IMenuManager` `getMenuManager()` Returns the menu manager that is used to manage title area drop-down menu items.
`String` `getMessage()`
`IMessageManager` `getMessageManager()` Returns the message manager that will keep track of messages in this form.
`int` `getMessageType()`
`Color` `getSeparatorColor()` Deprecated. use `getHeadColor(IFormColors.H_BOTTOM_KEYLINE2)`
`String` `getText()` Returns the title text that will be rendered at the top of the form.
`IToolBarManager` `getToolBarManager()` Returns the tool bar manager that is used to manage tool items in the form's title area.
`int` `getToolBarVerticalAlignment()` Returns the current tool bar alignment (if used).
`boolean` `isBackgroundImageClipped()` Deprecated. due to the underlying widget limitations, background image is always clipped.
`boolean` `isBackgroundImageTiled()` Tests if the background image is tiled to cover the entire area of the form heading.
`boolean` `isBusy()` Tests if the form is in the 'busy' state.
`boolean` `isSeparatorVisible()` Tests if the form head separator is visible.
`void` `removeMessageHyperlinkListener​(IHyperlinkListener listener)` Remove the message hyperlink listener.
`void` `setBackground​(Color bg)` Sets the background color of the form.
`void` `setBackgroundImage​(Image backgroundImage)` Sets the optional background image to be rendered behind the title starting at the position 0,0.
`void` `setBackgroundImageAlignment​(int backgroundImageAlignment)` Deprecated. due to the underlying widget limitations, background image is always tiled and alignment cannot be controlled.
`void` `setBackgroundImageClipped​(boolean backgroundImageClipped)` Deprecated. due to the underlying widget limitations, background image is always clipped.
`void` `setBackgroundImageTiled​(boolean backgroundImageTiled)` Sets whether the header background image is repeated to cover the entire heading area or not.
`void` `setBusy​(boolean busy)` Sets the form's busy state.
`void` `setFont​(Font font)` Sets the font of the header text.
`void` `setForeground​(Color fg)` Sets the foreground color of the form.
`void` `setHeadClient​(Control headClient)` Sets the optional head client.
`void` `setHeadColor​(String key, Color color)` Sets the color used to paint an aspect of the form heading.
`void` `setImage​(Image image)` Sets the image to be rendered to the left of the title.
`void` `setLayout​(Layout layout)` Prevents from changing the custom control layout.
`void` `setMenu​(Menu menu)` Passes the menu to the form body.
`void` `setMessage​(String message)` Sets the message for this form.
`void` `setMessage​(String newMessage, int newType)` Sets the message for this form with an indication of what type of message it is.
`void` `setMessage​(String newMessage, int newType, IMessage[] children)` Sets the message for this form with an indication of what type of message it is.
`void` `setSeparatorColor​(Color separatorColor)` Deprecated. use `setHeadColor(IFormColors.H_BOTTOM_KEYLINE2, separatorColor)`
`void` `setSeparatorVisible​(boolean addSeparator)` If set, adds a separator between the head and body.
`void` `setText​(String text)` Sets the text to be rendered at the top of the form above the body as a title.
`void` `setTextBackground​(Color[] gradientColors, int[] percents, boolean vertical)` Sets the background colors to be painted behind the title text in a gradient.
`void` `setToolBarVerticalAlignment​(int alignment)` Sets the tool bar vertical alignment relative to the header.
`void` `updateToolBar()` Updates the local tool bar manager if used.

### Methods inherited from class org.eclipse.swt.widgets.Composite

`changed, checkSubclass, drawBackground, getBackgroundMode, getChildren, getLayout, getLayoutDeferred, getTabList, isLayoutDeferred, layout, layout, layout, layout, layout, setBackgroundMode, setFocus, setLayoutDeferred, setTabList`

### Methods inherited from class org.eclipse.swt.widgets.Scrollable

`computeTrim, getClientArea, getHorizontalBar, getScrollbarsMode, getVerticalBar`

### Methods inherited from class org.eclipse.swt.widgets.Control

`addControlListener, addDragDetectListener, addFocusListener, addGestureListener, addHelpListener, addKeyListener, addMenuDetectListener, addMouseListener, addMouseMoveListener, addMouseTrackListener, addMouseWheelListener, addPaintListener, addTouchListener, addTraverseListener, computeSize, computeSize, dragDetect, dragDetect, forceFocus, getAccessible, getBackground, getBorderWidth, getBounds, getCursor, getDragDetect, getEnabled, getFont, getForeground, getLayoutData, getLocation, getMenu, getMonitor, getOrientation, getParent, getRegion, getShell, getSize, getTextDirection, getToolTipText, getTouchEnabled, getVisible, internal_dispose_GC, internal_new_GC, isEnabled, isFocusControl, isReparentable, isVisible, moveAbove, moveBelow, pack, pack, print, redraw, redraw, removeControlListener, removeDragDetectListener, removeFocusListener, removeGestureListener, removeHelpListener, removeKeyListener, removeMenuDetectListener, removeMouseListener, removeMouseMoveListener, removeMouseTrackListener, removeMouseWheelListener, removePaintListener, removeTouchListener, removeTraverseListener, requestLayout, setBounds, setBounds, setCapture, setCursor, setDragDetect, setEnabled, setLayoutData, setLocation, setLocation, setOrientation, setParent, setRedraw, setRegion, setSize, setSize, setTextDirection, setToolTipText, setTouchEnabled, setVisible, toControl, toControl, toDisplay, toDisplay, traverse, traverse, traverse, update`

### Methods inherited from class org.eclipse.swt.widgets.Widget

`addDisposeListener, addListener, checkWidget, dispose, getData, getData, getDisplay, getListeners, getStyle, isAutoDirection, isDisposed, isListening, notifyListeners, removeDisposeListener, removeListener, removeListener, reskin, setData, setData, toString`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

### Methods inherited from interface org.eclipse.swt.graphics.Drawable

`isAutoScalable`

### Constructor Detail

#### Form

    public Form​(Composite parent,
                int style)

Creates the form content control as a child of the provided parent.

Parameters:
  `parent` - the parent widget

### Method Detail

#### setMenu

    public void setMenu​(Menu menu)

Passes the menu to the form body.

Overrides:
  `setMenu` in class `Control`
Parameters:
  `menu` - the parent menu

#### setLayout

    public final void setLayout​(Layout layout)

Prevents from changing the custom control layout.

Overrides:
  `setLayout` in class `Composite`
Parameters:
  `layout` - the receiver's new layout or null

#### getText

    public String getText()

Returns the title text that will be rendered at the top of the form.

Returns:
  the title text

#### getImage

    public Image getImage()

Returns the title image that will be rendered to the left of the title.

Returns:
  the title image or `null` if not set.
Since:
  3.2

#### setForeground

    public void setForeground​(Color fg)

Sets the foreground color of the form. This color will also be used for the body.

Overrides:
  `setForeground` in class `Control`
Parameters:
  `fg` - the foreground color

#### setBackground

    public void setBackground​(Color bg)

Sets the background color of the form. This color will also be used for the body.

Overrides:
  `setBackground` in class `Control`
Parameters:
  `bg` - the background color

#### setFont

    public void setFont​(Font font)

Sets the font of the header text.

Overrides:
  `setFont` in class `Control`
Parameters:
  `font` - the new font

#### setText

    public void setText​(String text)

Sets the text to be rendered at the top of the form above the body as a title.

Note: Mnemonics are indicated by an '&' that causes the next character to be the mnemonic. Mnemonics are not applicable in the case of the form title but need to be taken into account due to the usage of the underlying widget that renders mnemonics in the title area. The mnemonic indicator character '&' can be escaped by doubling it in the string, causing a single '&' to be displayed.

Parameters:
  `text` - the title text

#### setImage

    public void setImage​(Image image)

Sets the image to be rendered to the left of the title. This image will be temporarily hidden in two cases:

1. When the form is busy - replaced with a busy animation
2. When the form has message set - replaced with the image indicating message severity

Parameters:
  `image` - the title image or `null` to show no image.
Since:
  3.2

#### setTextBackground

    public void setTextBackground​(Color[] gradientColors,
                                  int[] percents,
                                  boolean vertical)

Sets the background colors to be painted behind the title text in a gradient. Note that this method will reset color previously set by `setBackground(Color)`. This is necessary for the simulated transparency of the heading in all of its children control.

Parameters:
  `gradientColors` - the array of colors that form the gradient
  `percents` - the partition of the overall space between the gradient colors
  `vertical` - of `true`, the gradient will be rendered vertically, if `false` the orientation will be horizontal.

#### getBackgroundImage

    public Image getBackgroundImage()

Returns the optional background image of the form head.

Overrides:
  `getBackgroundImage` in class `Control`
Returns:
  the background image or `null` if not specified.

#### setBackgroundImage

    public void setBackgroundImage​(Image backgroundImage)

Sets the optional background image to be rendered behind the title starting at the position 0,0. If the image is smaller than the container in any dimension, it will be tiled. As of version 3.2, this method only supports SWT.BITMAP image types. This is because the rendering is now delegated to SWT which imposes this restriction on background images,

Overrides:
  `setBackgroundImage` in class `Control`
Parameters:
  `backgroundImage` - the head background image.

#### getToolBarManager

    public IToolBarManager getToolBarManager()

Returns the tool bar manager that is used to manage tool items in the form's title area.

Returns:
  form tool bar manager

#### setToolBarVerticalAlignment

    public void setToolBarVerticalAlignment​(int alignment)

Sets the tool bar vertical alignment relative to the header. Can be useful when there is more free space at the second row (with the head client).

Parameters:
  `alignment` - SWT.TOP or SWT.BOTTOM
Since:
  3.3

#### getToolBarVerticalAlignment

    public int getToolBarVerticalAlignment()

Returns the current tool bar alignment (if used).

Returns:
  SWT.TOP or SWT.BOTTOM
Since:
  3.3

#### getMenuManager

    public IMenuManager getMenuManager()

Returns the menu manager that is used to manage title area drop-down menu items.

Returns:
  title area drop-down menu manager
Since:
  3.3

#### updateToolBar

    public void updateToolBar()

Updates the local tool bar manager if used. Does nothing if local tool bar manager has not been created yet.

#### getHead

    public Composite getHead()

Returns the container that occupies the head of the form (the form area above the body). Use this container as a parent for the head client.

Returns:
  the head of the form.
Since:
  3.2

#### getHeadClient

    public Control getHeadClient()

Returns the optional head client if set.

Returns:
  the head client or `null` if not set.
Since:
  3.2
See Also:
  `setHeadClient(Control)`

#### setHeadClient

    public void setHeadClient​(Control headClient)

Sets the optional head client. Head client is placed after the form title. This option causes the tool bar to be placed in the second raw of the header (below the head client).

The head client must be a child of the composite returned by `getHead()` method.

Parameters:
  `headClient` - the optional child of the head
Since:
  3.2

#### getBody

    public Composite getBody()

Returns the container that occupies the body of the form (the form area below the title). Use this container as a parent for the controls that should be in the form. No layout manager has been set on the form body.

Returns:
  Returns the body of the form.

#### isBackgroundImageTiled

    public boolean isBackgroundImageTiled()

Tests if the background image is tiled to cover the entire area of the form heading.

Returns:
  `true` if heading background image is tiled, `false` otherwise.

#### setBackgroundImageTiled

    public void setBackgroundImageTiled​(boolean backgroundImageTiled)

Sets whether the header background image is repeated to cover the entire heading area or not.

Parameters:
  `backgroundImageTiled` - set `true` to tile the image, or `false` to paint the background image only once at 0,0

#### getBackgroundImageAlignment

    @Deprecated
    public int getBackgroundImageAlignment()

Deprecated.
due to the underlying widget limitations, background image is either painted at 0,0 and/or tiled.
Returns the background image alignment.

Returns:
  SWT.LEFT

#### setBackgroundImageAlignment

    @Deprecated
    public void setBackgroundImageAlignment​(int backgroundImageAlignment)

Deprecated.
due to the underlying widget limitations, background image is always tiled and alignment cannot be controlled.
Sets the background image alignment.

Parameters:
  `backgroundImageAlignment` - The backgroundImageAlignment to set.
Since:
  3.1

#### isBackgroundImageClipped

    @Deprecated
    public boolean isBackgroundImageClipped()

Deprecated.
due to the underlying widget limitations, background image is always clipped.
Tests if background image is clipped.

Returns:
  true
Since:
  3.1

#### setBackgroundImageClipped

    @Deprecated
    public void setBackgroundImageClipped​(boolean backgroundImageClipped)

Deprecated.
due to the underlying widget limitations, background image is always clipped.
Sets whether the background image is clipped.

Parameters:
  `backgroundImageClipped` - the value to set
Since:
  3.1

#### isSeparatorVisible

    public boolean isSeparatorVisible()

Tests if the form head separator is visible.

Returns:
  `true` if the head/body separator is visible, `false` otherwise
Since:
  3.2

#### setSeparatorVisible

    public void setSeparatorVisible​(boolean addSeparator)

If set, adds a separator between the head and body. Since 3.3, the colors that are used to render it are `IFormColors.H_BOTTOM_KEYLINE1` and `IFormColors.H_BOTTOM_KEYLINE2`.

Parameters:
  `addSeparator` - `true` to make the separator visible, `false` otherwise.
Since:
  3.2

#### getSeparatorColor

    @Deprecated
    public Color getSeparatorColor()

Deprecated.
use `getHeadColor(IFormColors.H_BOTTOM_KEYLINE2)`
Returns the color used to render the optional head separator. If gradient text background is used additional colors from the gradient will be used to render the separator.

Returns:
  separator color or `null` if not set.
Since:
  3.2

#### setSeparatorColor

    @Deprecated
    public void setSeparatorColor​(Color separatorColor)

Deprecated.
use `setHeadColor(IFormColors.H_BOTTOM_KEYLINE2, separatorColor)`
Sets the color to be used to render the optional head separator.

Parameters:
  `separatorColor` - the color to render the head separator or `null` to use the default color.
Since:
  3.2

#### setHeadColor

    public void setHeadColor​(String key,
                             Color color)

Sets the color used to paint an aspect of the form heading.

Parameters:
  `key` - a valid form heading color key as defined in `IFormColors`. Relevant keys all start with an H_ prefix.
  `color` - the color to use for the provided key
Since:
  3.3

#### getHeadColor

    public Color getHeadColor​(String key)

Returns the color that is currently use to paint an aspect of the form heading, or `null` if not defined.

Parameters:
  `key` - the color key
Returns:
  the color object or `null` if not set.
Since:
  3.3

#### setMessage

    public void setMessage​(String message)

Sets the message for this form. Message text is rendered in the form head when shown.

Parameters:
  `message` - the message, or `null` to clear the message
Since:
  3.2
See Also:
  `setMessage(String, int)`

#### setMessage

    public void setMessage​(String newMessage,
                           int newType)

Sets the message for this form with an indication of what type of message it is.

The valid message types are one of `NONE`, `INFORMATION`,`WARNING`, or `ERROR` defined in IMessageProvider interface.

Parameters:
  `newMessage` - the message, or `null` to clear the message
  `newType` - the message type
Since:
  3.2
See Also:
  `IMessageProvider`

#### setMessage

    public void setMessage​(String newMessage,
                           int newType,
                           IMessage[] children)

Sets the message for this form with an indication of what type of message it is.

The valid message types are one of `NONE`, `INFORMATION`,`WARNING`, or `ERROR` defined in IMessageProvider interface.

In addition to the summary message, this method also sets an array of individual messages.

Parameters:
  `newMessage` - the message, or `null` to clear the message
  `newType` - the message type
  `children` - the individual messages that contributed to the overall message
Since:
  3.3
See Also:
  `IMessageProvider`

#### addMessageHyperlinkListener

    public void addMessageHyperlinkListener​(IHyperlinkListener listener)

Adds a message hyperlink listener. If at least one listener is present, messages will be rendered as hyperlinks.

Parameters:
  `listener` -
Since:
  3.3
See Also:
  `removeMessageHyperlinkListener(IHyperlinkListener)`

#### removeMessageHyperlinkListener

    public void removeMessageHyperlinkListener​(IHyperlinkListener listener)

Remove the message hyperlink listener.

Parameters:
  `listener` -
Since:
  3.3
See Also:
  `addMessageHyperlinkListener(IHyperlinkListener)`

#### isBusy

    public boolean isBusy()

Tests if the form is in the 'busy' state. Busy form displays 'busy' animation in the area of the title image.

Returns:
  `true` if busy, `false` otherwise.
Since:
  3.2

#### setBusy

    public void setBusy​(boolean busy)

Sets the form's busy state. Busy form will display 'busy' animation in the area of the title image.

Parameters:
  `busy` - the form's busy state
Since:
  3.2

#### addTitleDragSupport

    public void addTitleDragSupport​(int operations,
                                    Transfer[] transferTypes,
                                    DragSourceListener listener)

Adds support for dragging items out of the form title area via a user drag-and-drop operation.

Parameters:
  `operations` - a bitwise OR of the supported drag and drop operation types ( `DROP_COPY`,`DROP_LINK`, and `DROP_MOVE`)
  `transferTypes` - the transfer types that are supported by the drag operation
  `listener` - the callback that will be invoked to set the drag data and to cleanup after the drag and drop operation finishes
Since:
  3.3
See Also:
  `DND`

#### addTitleDropSupport

    public void addTitleDropSupport​(int operations,
                                    Transfer[] transferTypes,
                                    DropTargetListener listener)

Adds support for dropping items into the form title area via a user drag-and-drop operation.

Parameters:
  `operations` - a bitwise OR of the supported drag and drop operation types ( `DROP_COPY`,`DROP_LINK`, and `DROP_MOVE`)
  `transferTypes` - the transfer types that are supported by the drop operation
  `listener` - the callback that will be invoked after the drag and drop operation finishes
Since:
  3.3
See Also:
  `DND`

#### getMessage

    public String getMessage()

#### getMessageType

    public int getMessageType()

#### getChildrenMessages

    public IMessage[] getChildrenMessages()

Returns the children messages that the cause of the summary message currently set on the form.

Returns:
  an array of children messages or `null` if not set.
Since:
  3.3
See Also:
  `setMessage(String, int, IMessage[])`

#### getMessageManager

    public IMessageManager getMessageManager()

Returns the message manager that will keep track of messages in this form.

Returns:
  the message manager instance
Since:
  org.eclipse.ui.forms 3.4