public class FormToolkit extends Object
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.
Modifier and Type | Field and Description |
---|---|
static String |
KEY_DRAW_BORDER |
static String |
TEXT_BORDER |
static String |
TREE_BORDER |
Constructor and Description |
---|
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.
|
Modifier and Type | Method and Description |
---|---|
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 scrolled page book widget 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 |
decorateFormHeading(Form form)
Takes advantage of the gradients and other capabilities to decorate the
form heading using colors computed based on the current skin and
operating system.
|
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 |
getBorderMargin()
Returns the margin required around the children whose border is being
painted by the toolkit using
paintBordersFor(Composite) . |
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.
|
int |
getOrientation()
Returns the orientation that all the widgets created by this toolkit will
inherit, if set.
|
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.
|
static void |
setControlVisible(Control c,
boolean verticalOnly)
A utility method that ensures that the control is visible in the scrolled
composite.
|
void |
setOrientation(int orientation)
Sets the orientation that all the widgets created by this toolkit will
inherit.
|
public static final String KEY_DRAW_BORDER
public static final String TREE_BORDER
public static final String TEXT_BORDER
public FormToolkit(Display display)
Clients that call this method must call dispose()
when they
are finished using the toolkit.
public FormToolkit(FormColors colors)
markShared()
method.
Clients that call this method must call dispose()
when they
are finished using the toolkit.
colors
- the shared colorspublic Button createButton(Composite parent, String text, int style)
parent
- the button parenttext
- an optional text for the button (can be null
)style
- the button style (for example, SWT.PUSH
)public Composite createComposite(Composite parent)
parent
- the composite parentpublic Composite createComposite(Composite parent, int style)
parent
- the composite parentstyle
- the composite stylepublic Composite createCompositeSeparator(Composite parent)
parent
- the separator parentpublic Label createLabel(Composite parent, String text)
parent
- the label parenttext
- the label textpublic Label createLabel(Composite parent, String text, int style)
parent
- the label parenttext
- the label textstyle
- the label stylepublic Hyperlink createHyperlink(Composite parent, String text, int style)
parent
- the hyperlink parenttext
- the text of the hyperlinkstyle
- the hyperlink stylepublic ImageHyperlink createImageHyperlink(Composite parent, int style)
parent
- the hyperlink parentstyle
- the hyperlink stylepublic FormText createFormText(Composite parent, boolean trackFocus)
parent
- the rich text parenttrackFocus
- if true
, the toolkit will monitor focus
transfers to ensure that the hyperlink in focus is visible in
the form.public void adapt(Control control, boolean trackFocus, boolean trackKeyboard)
control
- a control to adapttrackFocus
- 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.public void adapt(Composite composite)
composite
- the composite to adaptpublic static void ensureVisible(Control c)
c
- the control to revealpublic Section createSection(Composite parent, int sectionStyle)
parent
- the section parentsectionStyle
- the section stylepublic ExpandableComposite createExpandableComposite(Composite parent, int expansionStyle)
parent
- the expandable composite parentexpansionStyle
- the expandable composite stylepublic Label createSeparator(Composite parent, int style)
parent
- the separator parentstyle
- the separator stylepublic Table createTable(Composite parent, int style)
parent
- the table parentstyle
- the table stylepublic Text createText(Composite parent, String value)
parent
- the text parentvalue
- the text initial valuepublic Text createText(Composite parent, String value, int style)
parent
- the text parentvalue
- the text initial valuestyle
- the text stylepublic Tree createTree(Composite parent, int style)
parent
- the tree parentstyle
- the tree stylepublic ScrolledForm createScrolledForm(Composite parent)
parent
- the scrolled form parentcreateForm(org.eclipse.swt.widgets.Composite)
public Form createForm(Composite parent)
parent
- the form parentcreateScrolledForm(org.eclipse.swt.widgets.Composite)
public void decorateFormHeading(Form form)
form
- the form to decoratepublic ScrolledPageBook createPageBook(Composite parent, int style)
parent
- the page book parentstyle
- the text stylepublic void dispose()
public HyperlinkGroup getHyperlinkGroup()
public void setBackground(Color bg)
bg
- the new background colorpublic void refreshHyperlinkColors()
public void paintBordersFor(Composite parent)
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 borders in the following ways:
widget.setData(FormToolkit.KEY_DRAW_BORDER, FormToolkit.TREE_BORDER); or widget.setData(FormToolkit.KEY_DRAW_BORDER, FormToolkit.TEXT_BORDER);
If borders would normally be painted for a control, but they are not wanted, it is possible to suppress them in the following way:
widget.setData(FormToolkit.KEY_DRAW_BORDER, Boolean.FALSE);
parent
- the parent that owns the children for which the border needs
to be painted.public FormColors getColors()
public int getBorderStyle()
public int getBorderMargin()
paintBordersFor(Composite)
. Since
the border is painted around the controls on the parent, a number of
pixels needs to be reserved for this border. For windowing systems where
the native border is used, this margin is 0.public void setBorderStyle(int style)
style
- SWT.BORDER
or SWT.NULL
getBorderStyle()
public static void setControlVisible(Control c, boolean verticalOnly)
c
- the control to make visibleverticalOnly
- if true
, the scrolled composite will be
scrolled only vertically if needed. Otherwise, the scrolled
composite origin will be set to the control origin.public int getOrientation()
SWT.NULL
,
SWT.LEFT_TO_RIGHT
and SWT.RIGHT_TO_LEFT
.SWT.NULL
if
not set. The default orientation is inherited from the Window
default orientation.Window.getDefaultOrientation()
public void setOrientation(int orientation)
SWT.NULL
, SWT.LEFT_TO_RIGHT
and SWT.RIGHT_TO_LEFT
.orientation
- style for this toolkit.
Copyright (c) 2000, 2014 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.