public class Form extends Composite
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.
Constructor and Description |
---|
Form(Composite parent,
int style)
Creates the form content control as a child of the provided parent.
|
Modifier and Type | Method and Description |
---|---|
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.
|
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
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.
|
changed, checkSubclass, drawBackground, getBackgroundMode, getChildren, getLayout, getLayoutDeferred, getTabList, isLayoutDeferred, layout, layout, layout, layout, layout, setBackgroundMode, setFocus, setLayoutDeferred, setTabList
computeTrim, getClientArea, getHorizontalBar, getScrollbarsMode, getVerticalBar
addControlListener, addDragDetectListener, addFocusListener, addGestureListener, addHelpListener, addKeyListener, addMenuDetectListener, addMouseListener, addMouseMoveListener, addMouseTrackListener, addMouseWheelListener, addPaintListener, addTouchListener, addTraverseListener, 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, 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
addDisposeListener, addListener, checkWidget, dispose, getData, getData, getDisplay, getListeners, getStyle, isDisposed, isListening, notifyListeners, removeDisposeListener, removeListener, removeListener, reskin, setData, setData, toString
public Form(Composite parent, int style)
parent
- the parent widgetpublic void setMenu(Menu menu)
public final Point computeSize(int wHint, int hHint, boolean changed)
computeSize
in class Composite
wHint
- the width hint (can be SWT.DEFAULT
)hHint
- the height hint (can be SWT.DEFAULT
)changed
- true
if the control's contents have changed, and false
otherwiseLayout
,
Control.getBorderWidth()
,
Control.getBounds()
,
Control.getSize()
,
Control.pack(boolean)
,
"computeTrim, getClientArea for controls that implement them"public final void setLayout(Layout layout)
public String getText()
public Image getImage()
null
if not set.public void setForeground(Color fg)
setForeground
in class Control
fg
- the foreground colorpublic void setBackground(Color bg)
setBackground
in class Control
bg
- the background colorpublic void setFont(Font font)
public void setText(String text)
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.
text
- the title textpublic void setImage(Image image)
image
- the title image or null
to show no image.public void setTextBackground(Color[] gradientColors, int[] percents, boolean vertical)
setBackground(Color)
. This is necessary for the simulated
transparency of the heading in all of its children control.gradientColors
- the array of colors that form the gradientpercents
- the partition of the overall space between the gradient colorsvertical
- of true
, the gradient will be rendered
vertically, if false
the orientation will be
horizontal.public Image getBackgroundImage()
getBackgroundImage
in class Control
null
if not specified.public void setBackgroundImage(Image backgroundImage)
setBackgroundImage
in class Control
backgroundImage
- the head background image.public IToolBarManager getToolBarManager()
public void setToolBarVerticalAlignment(int alignment)
alignment
- SWT.TOP or SWT.BOTTOMpublic int getToolBarVerticalAlignment()
public IMenuManager getMenuManager()
public void updateToolBar()
public Composite getHead()
public Control getHeadClient()
null
if not set.setHeadClient(Control)
public void setHeadClient(Control headClient)
The head client must be a child of the composite returned by
getHead()
method.
headClient
- the optional child of the headpublic Composite getBody()
public boolean isBackgroundImageTiled()
true
if heading background image is tiled,
false
otherwise.public void setBackgroundImageTiled(boolean backgroundImageTiled)
backgroundImageTiled
- set true
to tile the image, or
false
to paint the background image only once
at 0,0public int getBackgroundImageAlignment()
public void setBackgroundImageAlignment(int backgroundImageAlignment)
backgroundImageAlignment
- The backgroundImageAlignment to set.public boolean isBackgroundImageClipped()
public void setBackgroundImageClipped(boolean backgroundImageClipped)
backgroundImageClipped
- the value to setpublic boolean isSeparatorVisible()
true
if the head/body separator is visible,
false
otherwisepublic void setSeparatorVisible(boolean addSeparator)
IFormColors.H_BOTTOM_KEYLINE1
and
IFormColors.H_BOTTOM_KEYLINE2
.addSeparator
- true
to make the separator visible,
false
otherwise.public Color getSeparatorColor()
getHeadColor(IFormColors.H_BOTTOM_KEYLINE2)
null
if not set.public void setSeparatorColor(Color separatorColor)
setHeadColor(IFormColors.H_BOTTOM_KEYLINE2, separatorColor)
separatorColor
- the color to render the head separator or null
to use the default color.public void setHeadColor(String key, Color color)
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 keypublic Color getHeadColor(String key)
null
if not defined.key
- the color keynull
if not set.public void setMessage(String message)
message
- the message, or null
to clear the messagesetMessage(String, int)
public void setMessage(String newMessage, int newType)
The valid message types are one of NONE
,
INFORMATION
,WARNING
, or
ERROR
defined in IMessageProvider interface.
newMessage
- the message, or null
to clear the messagenewType
- the message typeIMessageProvider
public void setMessage(String newMessage, int newType, IMessage[] children)
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.
newMessage
- the message, or null
to clear the messagenewType
- the message typechildren
- the individual messages that contributed to the overall
messageIMessageProvider
public void addMessageHyperlinkListener(IHyperlinkListener listener)
listener
- removeMessageHyperlinkListener(IHyperlinkListener)
public void removeMessageHyperlinkListener(IHyperlinkListener listener)
listener
- addMessageHyperlinkListener(IHyperlinkListener)
public boolean isBusy()
true
if busy, false
otherwise.public void setBusy(boolean busy)
busy
- the form's busy statepublic void addTitleDragSupport(int operations, Transfer[] transferTypes, DragSourceListener listener)
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 operationlistener
- the callback that will be invoked to set the drag data and to
cleanup after the drag and drop operation finishesDND
public void addTitleDropSupport(int operations, Transfer[] transferTypes, DropTargetListener listener)
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 operationlistener
- the callback that will be invoked after the drag and drop
operation finishesDND
public String getMessage()
public int getMessageType()
public IMessage[] getChildrenMessages()
null
if not set.setMessage(String, int, IMessage[])
public IMessageManager getMessageManager()
Copyright (c) 2000, 2015 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.