org.argeo.cms.ui.eclipse.forms

Class FormToolkit

java.lang.Object

org.argeo.cms.ui.eclipse.forms.FormToolkit

public class FormToolkit
extends java.lang.Object

The toolkit is responsible for creating SWT controls adapted to work in Eclipse forms. In addition to changing their presentation properties (fonts, colors etc.), various listeners are attached to make them behave correctly in the form context.

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.

Since:

1.0

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	KEY_DRAW_BORDER
static java.lang.String	TEXT_BORDER
static java.lang.String	TREE_BORDER

Constructor Summary

Constructors

Constructor and Description
FormToolkit(org.eclipse.swt.widgets.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.

Method Summary

Modifier and Type	Method and Description
void	adapt(org.eclipse.swt.widgets.Composite composite) Adapts a composite to be used in a form associated with this toolkit.
void	adapt(org.eclipse.swt.widgets.Control control, boolean trackFocus, boolean trackKeyboard) Adapts a control to be used in a form that is associated with this toolkit.
org.eclipse.swt.widgets.Button	createButton(org.eclipse.swt.widgets.Composite parent, java.lang.String text, int style) Creates a button as a part of the form.
org.eclipse.swt.widgets.Composite	createComposite(org.eclipse.swt.widgets.Composite parent) Creates the composite as a part of the form.
org.eclipse.swt.widgets.Composite	createComposite(org.eclipse.swt.widgets.Composite parent, int style) Creates the composite as part of the form using the provided style.
org.eclipse.swt.widgets.Composite	createCompositeSeparator(org.eclipse.swt.widgets.Composite parent) Creats the composite that can server as a separator between various parts of a form.
org.eclipse.swt.widgets.Label	createLabel(org.eclipse.swt.widgets.Composite parent, java.lang.String text) Creates a label as a part of the form.
org.eclipse.swt.widgets.Label	createLabel(org.eclipse.swt.widgets.Composite parent, java.lang.String text, int style) Creates a label as a part of the form.
org.eclipse.swt.custom.ScrolledComposite	createScrolledForm(org.eclipse.swt.widgets.Composite parent) Creates a scrolled form widget in the provided parent.
org.eclipse.swt.widgets.Label	createSeparator(org.eclipse.swt.widgets.Composite parent, int style) Creates a separator label as a part of the form.
org.eclipse.swt.widgets.Table	createTable(org.eclipse.swt.widgets.Composite parent, int style) Creates a table as a part of the form.
org.eclipse.swt.widgets.Text	createText(org.eclipse.swt.widgets.Composite parent, java.lang.String value) Creates a text as a part of the form.
org.eclipse.swt.widgets.Text	createText(org.eclipse.swt.widgets.Composite parent, java.lang.String value, int style) Creates a text as a part of the form.
org.eclipse.swt.widgets.Tree	createTree(org.eclipse.swt.widgets.Composite parent, int style) Creates a tree widget as a part of the form.
void	dispose() Disposes the toolkit.
static void	ensureVisible(org.eclipse.swt.widgets.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.
int	getOrientation() Returns the orientation that all the widgets created by this toolkit will inherit, if set.
void	setBackground(org.eclipse.swt.graphics.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(org.eclipse.swt.widgets.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.

Methods inherited from class java.lang.Object

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

Field Detail

KEY_DRAW_BORDER

public static final java.lang.String KEY_DRAW_BORDER

See Also:

Constant Field Values

TREE_BORDER

public static final java.lang.String TREE_BORDER

See Also:

Constant Field Values

TEXT_BORDER

public static final java.lang.String TEXT_BORDER

See Also:

Constant Field Values

Constructor Detail

FormToolkit

public FormToolkit(org.eclipse.swt.widgets.Display display)

Creates a toolkit that is self-sufficient (will manage its own colors).

Clients that call this method must call dispose() when they are finished using the toolkit.

FormToolkit

public FormToolkit(FormColors colors)

Creates a toolkit that will use the provided (shared) colors. The toolkit will dispose the colors if and only if they are not marked as shared via the markShared() method.

Clients that call this method must call dispose() when they are finished using the toolkit.

Parameters:

colors - the shared colors

Method Detail

createButton

public org.eclipse.swt.widgets.Button createButton(org.eclipse.swt.widgets.Composite parent,
                                                   java.lang.String text,
                                                   int style)

Creates a button as a part of the form.

Parameters:

parent - the button parent

text - an optional text for the button (can be null)

style - the button style (for example, SWT.PUSH)

Returns:

the button widget

createComposite

public org.eclipse.swt.widgets.Composite createComposite(org.eclipse.swt.widgets.Composite parent)

Creates the composite as a part of the form.

Parameters:

parent - the composite parent

Returns:

the composite widget

createComposite

public org.eclipse.swt.widgets.Composite createComposite(org.eclipse.swt.widgets.Composite parent,
                                                         int style)

Creates the composite as part of the form using the provided style.

Parameters:

parent - the composite parent

style - the composite style

Returns:

the composite widget

createCompositeSeparator

public org.eclipse.swt.widgets.Composite createCompositeSeparator(org.eclipse.swt.widgets.Composite parent)

Creats the composite that can server as a separator between various parts of a form. Separator height should be controlled by setting the height hint on the layout data for the composite.

Parameters:

parent - the separator parent

Returns:

the separator widget

createLabel

public org.eclipse.swt.widgets.Label createLabel(org.eclipse.swt.widgets.Composite parent,
                                                 java.lang.String text)

Creates a label as a part of the form.

Parameters:

parent - the label parent

text - the label text

Returns:

the label widget

createLabel

public org.eclipse.swt.widgets.Label createLabel(org.eclipse.swt.widgets.Composite parent,
                                                 java.lang.String text,
                                                 int style)

Creates a label as a part of the form.

Parameters:

parent - the label parent

text - the label text

style - the label style

Returns:

the label widget

adapt

public void adapt(org.eclipse.swt.widgets.Control control,
                  boolean trackFocus,
                  boolean trackKeyboard)

Adapts a control to be used in a form that is associated with this toolkit. This involves adjusting colors and optionally adding handlers to ensure focus tracking and keyboard management.

Parameters:

control - a control to adapt

trackFocus - 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.

adapt

public void adapt(org.eclipse.swt.widgets.Composite composite)

Adapts a composite to be used in a form associated with this toolkit.

Parameters:

composite - the composite to adapt

ensureVisible

public static void ensureVisible(org.eclipse.swt.widgets.Control c)

A helper method that ensures the provided control is visible when ScrolledComposite is somewhere in the parent chain. If scroll bars are visible and the control is clipped, the client of the scrolled composite will be scrolled to reveal the control.

Parameters:

c - the control to reveal

createSeparator

public org.eclipse.swt.widgets.Label createSeparator(org.eclipse.swt.widgets.Composite parent,
                                                     int style)

Creates a separator label as a part of the form.

Parameters:

parent - the separator parent

style - the separator style

Returns:

the separator label

createTable

public org.eclipse.swt.widgets.Table createTable(org.eclipse.swt.widgets.Composite parent,
                                                 int style)

Creates a table as a part of the form.

Parameters:

parent - the table parent

style - the table style

Returns:

the table widget

createText

public org.eclipse.swt.widgets.Text createText(org.eclipse.swt.widgets.Composite parent,
                                               java.lang.String value)

Creates a text as a part of the form.

Parameters:

parent - the text parent

value - the text initial value

Returns:

the text widget

createText

public org.eclipse.swt.widgets.Text createText(org.eclipse.swt.widgets.Composite parent,
                                               java.lang.String value,
                                               int style)

Creates a text as a part of the form.

Parameters:

parent - the text parent

value - the text initial value

style - the text style

Returns:

the text widget

createTree

public org.eclipse.swt.widgets.Tree createTree(org.eclipse.swt.widgets.Composite parent,
                                               int style)

Creates a tree widget as a part of the form.

Parameters:

parent - the tree parent

style - the tree style

Returns:

the tree widget

createScrolledForm

public org.eclipse.swt.custom.ScrolledComposite createScrolledForm(org.eclipse.swt.widgets.Composite parent)

Creates a scrolled form widget in the provided parent. If you do not require scrolling because there is already a scrolled composite up the parent chain, use 'createForm' instead.

Parameters:

parent - the scrolled form parent

Returns:

the form that can scroll itself

See Also:

#createForm

dispose

public void dispose()

Disposes the toolkit.

setBackground

public void setBackground(org.eclipse.swt.graphics.Color bg)

Sets the background color for the entire toolkit. The method delegates the call to the FormColors object and also updates the hyperlink group so that hyperlinks and other objects are in sync.

Parameters:

bg - the new background color

getColors

public FormColors getColors()

Returns the colors used by this toolkit.

Returns:

the color object

getBorderStyle

public int getBorderStyle()

Returns the border style used for various widgets created by this toolkit. The intent of the toolkit is to create controls with styles that yield a 'flat' appearance. On systems where the native borders are already flat, we set the style to SWT.BORDER and don't paint the borders ourselves. Otherwise, the style is set to SWT.NULL, and borders are painted by the toolkit.

Returns:

the global border style

getBorderMargin

public int getBorderMargin()

Returns the margin required around the children whose border is being painted by the toolkit using #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.

Returns:

the margin in the parent when children have their border painted

setBorderStyle

public void setBorderStyle(int style)

Sets the border style to be used when creating widgets. The toolkit chooses the correct style based on the platform but this value can be changed using this method.

Parameters:

style - SWT.BORDER or SWT.NULL

See Also:

getBorderStyle()

setControlVisible

public static void setControlVisible(org.eclipse.swt.widgets.Control c,
                                     boolean verticalOnly)

A utility method that ensures that the control is visible in the scrolled composite. The prerequisite for this method is that the control has a class that extends ScrolledComposite somewhere in the parent chain. If the control is partially or fully clipped, the composite is scrolled to set by setting the origin to the control origin.

Parameters:

c - the control to make visible

verticalOnly - if true, the scrolled composite will be scrolled only vertically if needed. Otherwise, the scrolled composite origin will be set to the control origin.

getOrientation

public int getOrientation()

Returns the orientation that all the widgets created by this toolkit will inherit, if set. Can be SWT.NULL, SWT.LEFT_TO_RIGHT and SWT.RIGHT_TO_LEFT.

Returns:

orientation style for this toolkit, or SWT.NULL if not set. The default orientation is inherited from the Window default orientation.

See Also:

Window.getDefaultOrientation()

setOrientation

public void setOrientation(int orientation)

Sets the orientation that all the widgets created by this toolkit will inherit. Can be SWT.NULL, SWT.LEFT_TO_RIGHT and SWT.RIGHT_TO_LEFT.

Parameters:

orientation - style for this toolkit.