| org.eclipse.ui.forms.widgets.Form
| Form | | public class Form extends Composite (Code) | | 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 |
| Constructor Summary | |
| public | Form(Composite parent, int style)
Creates the form content control as a child of the provided parent. |
| Method Summary | |
| public void | addMessageHyperlinkListener(IHyperlinkListener listener)
Adds a message hyperlink listener. | | 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. | | 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. | | final public Point | computeSize(int wHint, int hHint, boolean changed)
Fully delegates the size computation to the internal layout manager. | | public Image | getBackgroundImage()
Returns the optional background image of the form head. | | public int | getBackgroundImageAlignment()
Returns the background image alignment. | | public Composite | getBody()
Returns the container that occupies the body of the form (the form area
below the title). | | public IMessage[] | getChildrenMessages()
Returns the children messages that the cause of the summary message
currently set on the form. | | public Composite | getHead()
Returns the container that occupies the head of the form (the form area
above the body). | | public Control | getHeadClient()
Returns the optional head client if set. | | 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. | | public Image | getImage()
Returns the title image that will be rendered to the left of the title. | | public IMenuManager | getMenuManager()
Returns the menu manager that is used to manage title area drop-down menu
items. | | public String | getMessage()
| | public int | getMessageType()
| | public Color | getSeparatorColor()
Returns the color used to render the optional head separator. | | public String | getText()
Returns the title text that will be rendered at the top of the form. | | public IToolBarManager | getToolBarManager()
Returns the tool bar manager that is used to manage tool items in the
form's title area. | | public int | getToolBarVerticalAlignment()
Returns the current tool bar alignment (if used). | | public boolean | isBackgroundImageClipped()
Tests if background image is clipped. | | public boolean | isBackgroundImageTiled()
Tests if the background image is tiled to cover the entire area of the
form heading. | | public boolean | isBusy()
Tests if the form is in the 'busy' state. | | public boolean | isSeparatorVisible()
Tests if the form head separator is visible. | | public void | removeMessageHyperlinkListener(IHyperlinkListener listener)
Remove the message hyperlink listener. | | public void | setBackground(Color bg)
Sets the background color of the form. | | public void | setBackgroundImage(Image backgroundImage)
Sets the optional background image to be rendered behind the title
starting at the position 0,0. | | public void | setBackgroundImageAlignment(int backgroundImageAlignment)
Sets the background image alignment. | | public void | setBackgroundImageClipped(boolean backgroundImageClipped)
Sets whether the background image is clipped. | | public void | setBackgroundImageTiled(boolean backgroundImageTiled)
Sets whether the header background image is repeated to cover the entire
heading area or not. | | public void | setBusy(boolean busy)
Sets the form's busy state. | | public void | setFont(Font font)
Sets the font of the header text. | | public void | setForeground(Color fg)
Sets the foreground color of the form. | | public void | setHeadClient(Control headClient)
Sets the optional head client. | | 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 inIFormColors. | | public void | setImage(Image image)
Sets the image to be rendered to the left of the title. | | final public void | setLayout(Layout layout)
Prevents from changing the custom control layout. | | public void | setMenu(Menu menu)
Passes the menu to the form body. | | public void | setMessage(String message)
Sets the message for this form. | | public void | setMessage(String newMessage, int newType)
Sets the message for this form with an indication of what type of message
it is. | | 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. | | void | setSelectionText(FormText text)
| | public void | setSeparatorColor(Color separatorColor)
Sets the color to be used to render the optional head separator. | | public void | setSeparatorVisible(boolean addSeparator)
If set, adds a separator between the head and body. | | 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. | | public void | setTextBackground(Color[] gradientColors, int[] percents, boolean vertical)
Sets the background colors to be painted behind the title text in a
gradient. | | public void | setToolBarVerticalAlignment(int alignment)
Sets the tool bar vertical alignment relative to the header. | | public void | updateToolBar()
Updates the local tool bar manager if used. |
| Form | | public Form(Composite parent, int style)(Code) | | Creates the form content control as a child of the provided parent.
Parameters:
parent - the parent widget |
| addTitleDragSupport | | public void addTitleDragSupport(int operations, Transfer[] transferTypes, DragSourceListener listener)(Code) | | 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, andDROP_MOVE)
Parameters:
transferTypes - the transfer types that are supported by the drag operation
Parameters:
listener - the callback that will be invoked to set the drag data and tocleanup after the drag and drop operation finishes
See Also: org.eclipse.swt.dnd.DND
since:
3.3 |
| addTitleDropSupport | | public void addTitleDropSupport(int operations, Transfer[] transferTypes, DropTargetListener listener)(Code) | | 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, andDROP_MOVE)
Parameters:
transferTypes - the transfer types that are supported by the drop operation
Parameters:
listener - the callback that will be invoked after the drag and dropoperation finishes
See Also: org.eclipse.swt.dnd.DND
since:
3.3 |
| computeSize | | final public Point computeSize(int wHint, int hHint, boolean changed)(Code) | | Fully delegates the size computation to the internal layout manager.
|
| getBackgroundImage | | public Image getBackgroundImage()(Code) | | Returns the optional background image of the form head.
the background image or null if not specified. |
| getBackgroundImageAlignment | | public int getBackgroundImageAlignment()(Code) | | Returns the background image alignment.
SWT.LEFT |
| getBody | | public Composite getBody()(Code) | | 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 the body of the form. |
| getChildrenMessages | | public IMessage[] getChildrenMessages()(Code) | | Returns the children messages that the cause of the summary message
currently set on the form.
an array of children messages or null if not set.
See Also: Form.setMessage(String,int,IMessage[])
since:
3.3 |
| getHead | | public Composite getHead()(Code) | | 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.
the head of the form.
since:
3.2 |
| getHeadClient | | public Control getHeadClient()(Code) | | Returns the optional head client if set.
the head client or null if not set.
See Also: Form.setHeadClient(Control)
since:
3.2 |
| getHeadColor | | public Color getHeadColor(String key)(Code) | | 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 the color object or null if not set.
since:
3.3 |
| getImage | | public Image getImage()(Code) | | Returns the title image that will be rendered to the left of the title.
the title image or null if not set.
since:
3.2 |
| getMenuManager | | public IMenuManager getMenuManager()(Code) | | Returns the menu manager that is used to manage title area drop-down menu
items.
title area drop-down menu manager
since:
3.3 |
| getMessageType | | public int getMessageType()(Code) | | |
| getSeparatorColor | | public Color getSeparatorColor()(Code) | | 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.
separator color or null if not set.
since:
3.2 |
| getText | | public String getText()(Code) | | Returns the title text that will be rendered at the top of the form.
the title text |
| getToolBarManager | | public IToolBarManager getToolBarManager()(Code) | | Returns the tool bar manager that is used to manage tool items in the
form's title area.
form tool bar manager |
| getToolBarVerticalAlignment | | public int getToolBarVerticalAlignment()(Code) | | Returns the current tool bar alignment (if used).
SWT.TOP or SWT.BOTTOM
since:
3.3 |
| isBackgroundImageClipped | | public boolean isBackgroundImageClipped()(Code) | | Tests if background image is clipped.
true
since:
3.1 |
| isBackgroundImageTiled | | public boolean isBackgroundImageTiled()(Code) | | Tests if the background image is tiled to cover the entire area of the
form heading.
true if heading background image is tiled,false otherwise. |
| isBusy | | public boolean isBusy()(Code) | | Tests if the form is in the 'busy' state. Busy form displays 'busy'
animation in the area of the title image.
true if busy, false otherwise.
since:
3.2 |
| isSeparatorVisible | | public boolean isSeparatorVisible()(Code) | | Tests if the form head separator is visible.
true if the head/body separator is visible,false otherwise
since:
3.2 |
| setBackground | | public void setBackground(Color bg)(Code) | | Sets the background color of the form. This color will also be used for
the body.
Parameters:
bg - the background color |
| setBackgroundImage | | public void setBackgroundImage(Image backgroundImage)(Code) | | 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.
since:
3.2
Parameters:
backgroundImage - the head background image. |
| setBackgroundImageAlignment | | public void setBackgroundImageAlignment(int backgroundImageAlignment)(Code) | | Sets the background image alignment.
Parameters:
backgroundImageAlignment - The backgroundImageAlignment to set.
since:
3.1 |
| setBackgroundImageClipped | | public void setBackgroundImageClipped(boolean backgroundImageClipped)(Code) | | Sets whether the background image is clipped.
Parameters:
backgroundImageClipped - the value to set
since:
3.1 |
| setBackgroundImageTiled | | public void setBackgroundImageTiled(boolean backgroundImageTiled)(Code) | | Sets whether the header background image is repeated to cover the entire
heading area or not.
Parameters:
backgroundImageTiled - set true to tile the image, orfalse to paint the background image only onceat 0,0 |
| setBusy | | public void setBusy(boolean busy)(Code) | | 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 |
| setFont | | public void setFont(Font font)(Code) | | Sets the font of the header text.
Parameters:
font - the new font |
| setForeground | | public void setForeground(Color fg)(Code) | | Sets the foreground color of the form. This color will also be used for
the body.
Parameters:
fg - the foreground color |
| setHeadClient | | public void setHeadClient(Control headClient)(Code) | | 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 |
| setHeadColor | | public void setHeadColor(String key, Color color)(Code) | | Sets the color used to paint an aspect of the form heading.
Parameters:
key - a valid form heading color key as defined inIFormColors. Relevant keys all start with an H_prefix.
Parameters:
color - the color to use for the provided key
since:
3.3 |
| setImage | | public void setImage(Image image)(Code) | | Sets the image to be rendered to the left of the title. This image will
be temporarily hidden in two cases:
- When the form is busy - replaced with a busy animation
- 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 |
| setLayout | | final public void setLayout(Layout layout)(Code) | | Prevents from changing the custom control layout.
|
| setMenu | | public void setMenu(Menu menu)(Code) | | Passes the menu to the form body.
Parameters:
menu - the parent menu |
| setMessage | | public void setMessage(String message)(Code) | | 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
See Also: Form.setMessage(String,int)
since:
3.2 |
| setMessage | | public void setMessage(String newMessage, int newType)(Code) | | 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
Parameters:
newType - the message type
See Also: org.eclipse.jface.dialogs.IMessageProvider
since:
3.2 |
| setMessage | | public void setMessage(String newMessage, int newType, IMessage[] children)(Code) | | 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
Parameters:
newType - the message type
Parameters:
children - the individual messages that contributed to the overallmessage
See Also: org.eclipse.jface.dialogs.IMessageProvider
since:
3.3 |
| setSeparatorColor | | public void setSeparatorColor(Color separatorColor)(Code) | | Sets the color to be used to render the optional head separator.
Parameters:
separatorColor - the color to render the head separator or nullto use the default color.
since:
3.2 |
| setSeparatorVisible | | public void setSeparatorVisible(boolean addSeparator)(Code) | | 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 |
| setText | | public void setText(String text)(Code) | | 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 acount 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 |
| setTextBackground | | public void setTextBackground(Color[] gradientColors, int[] percents, boolean vertical)(Code) | | Sets the background colors to be painted behind the title text in a
gradient. Note that this method will reset color previously set by
Form.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
Parameters:
percents - the partition of the overall space between the gradient colors
Parameters:
vertical - of true, the gradient will be renderedvertically, if false the orientation will behorizontal. |
| setToolBarVerticalAlignment | | public void setToolBarVerticalAlignment(int alignment)(Code) | | 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 |
| updateToolBar | | public void updateToolBar()(Code) | | Updates the local tool bar manager if used. Does nothing if local tool
bar manager has not been created yet.
|
|
|