Eclipse Platform
Release 3.2

org.eclipse.ui.forms.widgets
Class Form

java.lang.Object
  extended byorg.eclipse.swt.widgets.Widget
      extended byorg.eclipse.swt.widgets.Control
          extended byorg.eclipse.swt.widgets.Scrollable
              extended byorg.eclipse.swt.widgets.Composite
                  extended byorg.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).

The form supports status messages. These messages can have various severity (error, warning, info or none). Message tray can be minimized and later restored by the user, but can only be closed programmatically.

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 next to the title. If title tool bar is also present, a new row is created in the header, and the tool bar is right-justified in the 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 worm 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);
 formContent.setText("Sample form");
 formContent.getBody().setLayout(new GridLayout());
 toolkit.createButton(formContent.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

Field Summary
 
Fields inherited from class org.eclipse.swt.widgets.Control
handle
 
Constructor Summary
Form(Composite parent, int style)
          Creates the form content control as a child of the provided parent.
 
Method Summary
 Point computeSize(int wHint, int hHint, boolean changed)
          Fully delegates the size computation to the internal layout manager.
 Image getBackgroundImage()
          Returns the optional background image of the form head.
 int getBackgroundImageAlignment()
          Deprecated. due to the underlying widget limitations, background image is always tiled and alignment cannot be controlled.
 Composite getBody()
          Returns the container that occupies the body of the form (the form area below the title).
 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.
 Image getImage()
          Returns the title image that will be rendered to the left of the title.
 Color getSeparatorColor()
          Returns the color used to render the optional head separator.
 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.
 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 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 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 setSeparatorColor(Color separatorColor)
          Sets the color to be used to render the optional head separator.
 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 updateToolBar()
          Updates the local tool bar manager if used.
 
Methods inherited from class org.eclipse.swt.widgets.Composite
changed, checkSubclass, getBackgroundMode, getChildren, getLayout, getLayoutDeferred, getTabList, isLayoutDeferred, layout, layout, layout, layout, setBackgroundMode, setFocus, 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, 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, setBounds, setBounds, setCapture, setCursor, setEnabled, setLayoutData, setLocation, setLocation, 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
 

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

computeSize

public final Point computeSize(int wHint,
                               int hHint,
                               boolean changed)
Fully delegates the size computation to the internal layout manager.

Overrides:
computeSize in class Composite

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.

Parameters:
text - the title text

setImage

public void setImage(Image image)
Sets the image to be rendered to the left of the title.

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.

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.

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

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

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

getBackgroundImageAlignment

public int getBackgroundImageAlignment()
Deprecated. due to the underlying widget limitations, background image is always tiled and alignment cannot be controlled.

Returns the background image alignment.

Returns:
SWT.LEFT

setBackgroundImageAlignment

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

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

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. If gradient text background is used, the separator will use gradient colors.

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

getSeparatorColor

public Color getSeparatorColor()
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

public void setSeparatorColor(Color 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

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.

Parameters:
newMessage - the message, or null to clear the message
newType - the message type
Since:
3.2

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

Eclipse Platform
Release 3.2

Guidelines for using Eclipse APIs.

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