Package org.eclipse.ui.forms.widgets

Class ExpandableComposite

java.lang.Object

org.eclipse.swt.widgets.Widget

org.eclipse.swt.widgets.Control

org.eclipse.swt.widgets.Scrollable

org.eclipse.swt.widgets.Composite

org.eclipse.swt.widgets.Canvas

org.eclipse.ui.forms.widgets.ExpandableComposite

All Implemented Interfaces:

Drawable

Direct Known Subclasses:

Section

public class ExpandableComposite
extends Canvas

This composite is capable of expanding or collapsing a single client that is its direct child. The composite renders an expansion toggle affordance (according to the chosen style), and a title that also acts as a hyperlink (can be selected and is traversable). The client is laid out below the title when expanded, or hidden when collapsed.

The widget can be instantiated as-is, or subclassed to modify some aspects of it. *

Since 3.1, left/right arrow keys can be used to control the expansion state. If several expandable composites are created in the same parent, up/down arrow keys can be used to traverse between them. Expandable text accepts mnemonics and mnemonic activation will toggle the expansion state.

While expandable composite recognize that different styles can be used to render the title bar, and even defines the constants for these styles (TITLE_BAR and SHORT_TITLE_BAR the actual painting is done in the subclasses.

Since:

3.0

See Also:

• Section

Field Summary

Fields

Modifier and Type	Field	Description
static final int	CLIENT_INDENT	If this style is used, the client origin will be vertically aligned with the title text.
int	clientVerticalSpacing	Vertical spacing between the title area and the composite client control (default is 3).
static final int	COMPACT	If this style is used, computed size of the composite will take the client width into consideration only in the expanded state.
int	descriptionVerticalSpacing	Vertical spacing between the title area and the description control (default is 0).
static final int	EXPANDED	If this style is used, the control will be created in the expanded state.
static final int	FOCUS_TITLE	If this style is used, the title text will be rendered as a hyperlink that can individually accept focus.
protected int	GAP	Deprecated. this variable was left as protected by mistake.
static final int	LEFT_TEXT_CLIENT_ALIGNMENT	By default, text client is right-aligned.
int	marginHeight	Height of the margin that will be added around the control (default is 0).
int	marginWidth	Width of the margin that will be added around the control (default is 0).
static final int	NO_TITLE	If this style is used, title will not be rendered.
static final int	NO_TITLE_FOCUS_BOX	By default, a focus box is painted around the title when it receives focus.
static final int	SHORT_TITLE_BAR	If this style is used, a short version of the title bar decoration will be painted behind the text.
protected Control	textLabel	The text label for the title.
static final int	TITLE_BAR	If this style is used, title bar decoration will be painted behind the text.
int	titleBarTextMarginWidth	Horizontal margin around the inside of the title bar area when TITLE_BAR or SHORT_TITLE_BAR style is used.
protected ToggleHyperlink	toggle	The toggle widget used to expand the composite.
static final int	TREE_NODE	If this style is used, a tree node with either + or - signs will be used to render the expansion toggle.
static final int	TWISTIE	If this style is used, a twistie will be used to render the expansion toggle.
protected int	VGAP	Deprecated. this variable was left as protected by mistake.

Fields inherited from class org.eclipse.swt.widgets.Control

handle

Fields inherited from class org.eclipse.swt.widgets.Widget

nativeZoom

Constructor Summary

Constructors

Constructor	Description
ExpandableComposite(Composite parent, int style)	Creates an expandable composite using a TWISTIE toggle.
ExpandableComposite(Composite parent, int style, int expansionStyle)	Creates the expandable composite in the provided parent.

Method Summary

Modifier and Type	Method	Description
void	addExpansionListener(IExpansionListener listener)	Adds the listener that will be notified when the expansion state changes.
Point	computeSize(int wHint, int hHint, boolean changed)	Computes the size of the expandable composite.
boolean	forceFocus()	Forces the receiver to have the keyboard focus, causing all keyboard events to be delivered to it.
Control	getClient()	Returns the current expandable client.
protected Control	getDescriptionControl()	Returns description control that will be placed under the title if present.
int	getExpansionStyle()	Returns the bitwise-ORed style bits for the expansion control.
protected Control	getSeparatorControl()	Returns the separator control that will be placed between the title and the description if present.
String	getText()	Returns the title string.
Control	getTextClient()	Returns the text client control.
int	getTextClientHeightDifference()	Returns the difference in height between the text and the text client (if set).
Color	getTitleBarForeground()	Returns the title bar foreground when TITLE_BAR style is used.
protected boolean	hasTitleBar()	Tests if this expandable composite renders a title bar around the text.
protected void	internalSetExpanded(boolean expanded)	Performs the expansion state change for the expandable control.
boolean	isExpanded()	Tests the expanded state of the composite.
protected boolean	isFixedStyle()	Returns true if the composite is fixed i.e. cannot be expanded or collapsed.
protected void	onPaint(PaintEvent e)	If TITLE_BAR or SHORT_TITLE_BAR style is used, title bar decoration will be painted behind the text in this method.
void	removeExpansionListener(IExpansionListener listener)	Removes the expansion listener.
void	setActiveToggleColor(Color c)	Sets the active color of the toggle control (when the mouse enters the toggle area).
void	setBackground(Color bg)	Sets the background of all the custom controls in the expandable.
void	setClient(Control client)	Sets the client of this expandable composite.
void	setEnabled(boolean enabled)	Enables the receiver if the argument is true, and disables it otherwise.
void	setExpanded(boolean expanded)	Changes expanded state.
void	setExpanded(boolean expanded, boolean fireExpanding)	Changes expanded state.
void	setFont(Font font)	Sets the fonts of all the custom controls in the expandable.
void	setForeground(Color fg)	Sets the foreground of all the custom controls in the expandable.
final void	setLayout(Layout layout)	Prevents assignment of the layout manager - expandable composite uses its own layout.
void	setMenu(Menu menu)	Overrides 'super' to pass the menu to the text label.
void	setText(String title)	Sets the title of the expandable composite.
void	setTextClient(Control textClient)	Sets the text client control.
void	setTitleBarForeground(Color color)	Sets the color of the title bar foreground when TITLE_BAR style is used.
void	setToggleColor(Color c)	Sets the color of the toggle control.
void	setToolTipText(String string)	Sets the receiver's tool tip text to the argument, which may be null indicating that the default tool tip for the control will be shown.

Methods inherited from class org.eclipse.swt.widgets.Canvas

drawBackground, getCaret, getIME, scroll, setCaret, setIME

Methods inherited from class org.eclipse.swt.widgets.Composite

changed, checkSubclass, drawBackground, getBackgroundMode, getChildren, getLayout, getLayoutDeferred, getTabList, isLayoutDeferred, layout, layout, layout, layout, layout, setBackgroundMode, setFocus, setLayoutDeferred, setTabList, toString

Methods inherited from class org.eclipse.swt.widgets.Scrollable

computeTrim, getClientArea, getHorizontalBar, getScrollbarsMode, getVerticalBar, setScrollbarsMode

Methods inherited from class org.eclipse.swt.widgets.Control

addControlListener, addDragDetectListener, addFocusListener, addGestureListener, addHelpListener, addKeyListener, addMenuDetectListener, addMouseListener, addMouseMoveListener, addMouseTrackListener, addMouseWheelListener, addPaintListener, addTouchListener, addTraverseListener, computeSize, dragDetect, dragDetect, getAccessible, getBackground, getBackgroundImage, 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, requestLayout, setBackgroundImage, setBounds, setBounds, setCapture, setCursor, setDragDetect, setLayoutData, setLocation, setLocation, setOrientation, setParent, setRedraw, setRegion, setSize, setSize, setTextDirection, setTouchEnabled, setVisible, toControl, toControl, toDisplay, toDisplay, traverse, traverse, traverse, update

Methods inherited from class org.eclipse.swt.widgets.Widget

addDisposeListener, addListener, addTypedListener, checkWidget, dispose, getData, getData, getDisplay, getListeners, getStyle, getTypedListeners, isAutoDirection, isDisposed, isListening, notifyListeners, removeDisposeListener, removeListener, removeListener, removeTypedListener, reskin, setData, setData

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.eclipse.swt.graphics.Drawable

isAutoScalable

Field Details

TWISTIE

public static final int TWISTIE

If this style is used, a twistie will be used to render the expansion toggle.

See Also:

• Constant Field Values

TREE_NODE

public static final int TREE_NODE

If this style is used, a tree node with either + or - signs will be used to render the expansion toggle.

See Also:

• Constant Field Values

FOCUS_TITLE

public static final int FOCUS_TITLE

If this style is used, the title text will be rendered as a hyperlink that can individually accept focus. Otherwise, it will still act like a hyperlink, but only the toggle control will accept focus.

See Also:

• Constant Field Values

CLIENT_INDENT

public static final int CLIENT_INDENT

If this style is used, the client origin will be vertically aligned with the title text. Otherwise, it will start at x = 0.

See Also:

• Constant Field Values

COMPACT

public static final int COMPACT

If this style is used, computed size of the composite will take the client width into consideration only in the expanded state. Otherwise, client width will always be taken into account.

See Also:

• Constant Field Values

EXPANDED

public static final int EXPANDED

If this style is used, the control will be created in the expanded state. This state can later be changed programmatically or by the user if TWISTIE or TREE_NODE style is used.

See Also:

• Constant Field Values

TITLE_BAR

public static final int TITLE_BAR

If this style is used, title bar decoration will be painted behind the text.

See Also:

• Constant Field Values

SHORT_TITLE_BAR

public static final int SHORT_TITLE_BAR

If this style is used, a short version of the title bar decoration will be painted behind the text. This style is useful when a more discrete option is needed for the title bar.

Since:

3.1

See Also:

• Constant Field Values

NO_TITLE

public static final int NO_TITLE

If this style is used, title will not be rendered.

See Also:

• Constant Field Values

LEFT_TEXT_CLIENT_ALIGNMENT

public static final int LEFT_TEXT_CLIENT_ALIGNMENT

By default, text client is right-aligned. If this style is used, it will be positioned after the text control and vertically centered with it.

See Also:

• Constant Field Values

NO_TITLE_FOCUS_BOX

public static final int NO_TITLE_FOCUS_BOX

By default, a focus box is painted around the title when it receives focus. If this style is used, the focus box will not be painted. This style does not apply when FOCUS_TITLE is used.

Since:

3.5

See Also:

• Constant Field Values

marginWidth

public int marginWidth

Width of the margin that will be added around the control (default is 0).

marginHeight

public int marginHeight

Height of the margin that will be added around the control (default is 0).

clientVerticalSpacing

public int clientVerticalSpacing

Vertical spacing between the title area and the composite client control (default is 3).

descriptionVerticalSpacing

public int descriptionVerticalSpacing

Vertical spacing between the title area and the description control (default is 0). The description control is normally placed at the new line as defined in the font used to render it. This value will be added to it.

Since:

3.3

titleBarTextMarginWidth

public int titleBarTextMarginWidth

Horizontal margin around the inside of the title bar area when TITLE_BAR or SHORT_TITLE_BAR style is used. This variable is not used otherwise.

Since:

3.3

toggle

protected ToggleHyperlink toggle

The toggle widget used to expand the composite.

textLabel

protected Control textLabel

The text label for the title.

VGAP

@Deprecated
protected int VGAP

Deprecated.

this variable was left as protected by mistake. It will be turned into static and hidden in the future versions. Do not use them and do not change its value.

GAP

@Deprecated
protected int GAP

Deprecated.

this variable was left as protected by mistake. It will be turned into static and hidden in the future versions. Do not use it and do not change its value.

Constructor Details

ExpandableComposite

public ExpandableComposite(Composite parent,
 int style)

Creates an expandable composite using a TWISTIE toggle.

Parameters:

parent - the parent composite

style - SWT style bits

ExpandableComposite

public ExpandableComposite(Composite parent,
 int style,
 int expansionStyle)

Creates the expandable composite in the provided parent.

Parameters:

parent - the parent

style - the control style (as expected by SWT subclass)

expansionStyle - the style of the expansion widget (TREE_NODE, TWISTIE, CLIENT_INDENT, COMPACT, FOCUS_TITLE, LEFT_TEXT_CLIENT_ALIGNMENT, NO_TITLE)

Method Details

forceFocus

public boolean forceFocus()

Description copied from class: Control

Forces the receiver to have the keyboard focus, causing all keyboard events to be delivered to it.

Overrides:

forceFocus in class Control

Returns:

true if the control got focus, and false if it was unable to.

See Also:

• Control.setFocus()

setMenu

public void setMenu(Menu menu)

Overrides 'super' to pass the menu to the text label.

Overrides:

setMenu in class Control

Parameters:

menu - the menu from the parent to attach to this control.

setLayout

public final void setLayout(Layout layout)

Prevents assignment of the layout manager - expandable composite uses its own layout.

Overrides:

setLayout in class Composite

Parameters:

layout - the receiver's new layout or null

setBackground

public void setBackground(Color bg)

Sets the background of all the custom controls in the expandable.

Overrides:

setBackground in class Control

Parameters:

bg - the new color (or null)

setForeground

public void setForeground(Color fg)

Sets the foreground of all the custom controls in the expandable.

Overrides:

setForeground in class Control

Parameters:

fg - the new color (or null)

setToggleColor

public void setToggleColor(Color c)

Sets the color of the toggle control.

Parameters:

c - the color object

setActiveToggleColor

public void setActiveToggleColor(Color c)

Sets the active color of the toggle control (when the mouse enters the toggle area).

Parameters:

c - the active color object

setFont

public void setFont(Font font)

Sets the fonts of all the custom controls in the expandable.

Overrides:

setFont in class Canvas

Parameters:

font - the new font (or null)

setEnabled

public void setEnabled(boolean enabled)

Description copied from class: Control

Enables the receiver if the argument is true, and disables it otherwise. A disabled control is typically not selectable from the user interface and draws with an inactive or "grayed" look.

Overrides:

setEnabled in class Control

Parameters:

enabled - the new enabled state

setClient

public void setClient(Control client)

Sets the client of this expandable composite. The client must not be null and must be a direct child of this container.

Parameters:

client - the client that will be expanded or collapsed

getClient

public Control getClient()

Returns the current expandable client.

Returns:

the client control

setText

public void setText(String title)

Sets the title of the expandable composite. The title will act as a hyperlink and activating it will toggle the client between expanded and collapsed state.

Parameters:

title - the new title string

See Also:

• getText()

setToolTipText

public void setToolTipText(String string)

Description copied from class: Control

Sets the receiver's tool tip text to the argument, which may be null indicating that the default tool tip for the control will be shown. For a control that has a default tool tip, such as the Tree control on Windows, setting the tool tip text to an empty string replaces the default, causing no tool tip text to be shown.

The mnemonic indicator (character '&') is not displayed in a tool tip. To display a single '&' in the tool tip, the character '&' can be escaped by doubling it in the string.

NOTE: This operation is a hint and behavior is platform specific, on Windows for CJK-style mnemonics of the form " (&C)" at the end of the tooltip text are not shown in tooltip.

Overrides:

setToolTipText in class Control

Parameters:

string - the new tool tip text (or null)

getText

public String getText()

Returns the title string.

Returns:

the title string

See Also:

• setText(String)

isExpanded

public boolean isExpanded()

Tests the expanded state of the composite.

Returns:

true if expanded, false if collapsed.

getExpansionStyle

public int getExpansionStyle()

Returns the bitwise-ORed style bits for the expansion control.

Returns:

the bitwise-ORed style bits for the expansion control

setExpanded

public void setExpanded(boolean expanded)

Changes expanded state. Equivalent to setExpanded(expanded, false).

Parameters:

expanded - the new expanded state

See Also:

• setExpanded(boolean, boolean)

setExpanded

public void setExpanded(boolean expanded,
 boolean fireExpanding)

Changes expanded state.

Parameters:

expanded - the new expanded state

fireExpanding - if true, listeners will be notified

Since:

3.13

internalSetExpanded

protected void internalSetExpanded(boolean expanded)

Performs the expansion state change for the expandable control.

Parameters:

expanded - the expansion state

addExpansionListener

public void addExpansionListener(IExpansionListener listener)

Adds the listener that will be notified when the expansion state changes.

Parameters:

listener - the listener to add

removeExpansionListener

public void removeExpansionListener(IExpansionListener listener)

Removes the expansion listener.

Parameters:

listener - the listener to remove

onPaint

protected void onPaint(PaintEvent e)

If TITLE_BAR or SHORT_TITLE_BAR style is used, title bar decoration will be painted behind the text in this method. The default implementation does nothing - subclasses are responsible for rendering the title area.

Parameters:

e - the paint event

getDescriptionControl

protected Control getDescriptionControl()

Returns description control that will be placed under the title if present.

Returns:

the description control or null if not used.

getSeparatorControl

protected Control getSeparatorControl()

Returns the separator control that will be placed between the title and the description if present.

Returns:

the separator control or null if not used.

computeSize

public Point computeSize(int wHint,
 int hHint,
 boolean changed)

Computes the size of the expandable composite.

Overrides:

computeSize in class Control

Parameters:

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 otherwise

Returns:

the preferred size of the control.

See Also:

• Control.computeSize(int, int)

isFixedStyle

protected boolean isFixedStyle()

Returns true if the composite is fixed i.e. cannot be expanded or collapsed. Fixed control will still contain the title, separator and description (if present) as well as the client, but will be in the permanent expanded state and the toggle affordance will not be shown.

Returns:

true if the control is fixed in the expanded state, false if it can be collapsed.

getTextClient

public Control getTextClient()

Returns the text client control.

Returns:

Returns the text client control if specified, or null if not.

setTextClient

public void setTextClient(Control textClient)

Sets the text client control. Text client is a control that is a child of the expandable composite and is placed to the right of the text. It can be used to place small image hyperlinks. If more than one control is needed, use Composite to hold them. Care should be taken that the height of the control is comparable to the height of the text.

Parameters:

textClient - the textClient to set or null if not needed any more.

getTextClientHeightDifference

public int getTextClientHeightDifference()

Returns the difference in height between the text and the text client (if set). This difference can cause vertical alignment problems when two expandable composites are placed side by side, one with and one without the text client. Use this method obtain the value to add to either descriptionVerticalSpacing (if you have description) or clientVerticalSpacing to correct the alignment of the expandable without the text client.

Returns:

the difference in height between the text and the text client or 0 if no corrective action is needed.

Since:

3.3

hasTitleBar

protected boolean hasTitleBar()

Tests if this expandable composite renders a title bar around the text.

Returns:

true for TITLE_BAR or SHORT_TITLE_BAR styles, false otherwise.

setTitleBarForeground

public void setTitleBarForeground(Color color)

Sets the color of the title bar foreground when TITLE_BAR style is used.

Parameters:

color - the title bar foreground

getTitleBarForeground

public Color getTitleBarForeground()

Returns the title bar foreground when TITLE_BAR style is used.

Returns:

the title bar foreground