Eclipse Platform
Release 3.0

org.eclipse.ui.forms.widgets
Class ExpandableComposite

java.lang.Object
  extended byorg.eclipse.swt.widgets.Widget
      extended byorg.eclipse.swt.widgets.Control
          extended byorg.eclipse.swt.widgets.Scrollable
              extended byorg.eclipse.swt.widgets.Composite
                  extended byorg.eclipse.ui.forms.widgets.ExpandableComposite
All Implemented Interfaces:
Drawable
Direct Known Subclasses:
Section

public class ExpandableComposite
extends Composite

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 layed 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.0
See Also:
Section

Field Summary
static int CLIENT_INDENT
          If this style is used, the client origin will be vertically aligned with the title text.
 int clientVerticalSpacing
           
static int COMPACT
          If this style is used, computed size of the composite will take the client width into consideration only in the expanded state.
static int EXPANDED
          If this style is used, the control will be created in the expanded state.
static 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
           
 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 int NO_TITLE
          If this style is used, title will not be rendered.
protected  Control textLabel
           
static int TITLE_BAR
          If this style is used, title bar decoration will be painted behind the text.
protected  ToggleHyperlink toggle
           
static int TREE_NODE
          If this style is used, a tree node with either + or - signs will be used to render the expansion toggle.
static int TWISTIE
          If this style is used, a twistie will be used to render the expansion toggle.
 
Fields inherited from class org.eclipse.swt.widgets.Control
handle
 
Constructor Summary
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
 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.
 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.
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 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 setExpanded(boolean expanded)
          Programmatically 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.
 void setLayout(Layout layout)
          Prevents assignment of the layout manager - expandable composite uses its own layout.
 void setText(String title)
          Sets the title of the expandable composite.
 void setTextClient(Control textClient)
          Sets the text client control.
 void setToggleColor(Color c)
          Sets the color of the toggle control.
 
Methods inherited from class org.eclipse.swt.widgets.Composite
checkSubclass, getChildren, getLayout, getTabList, layout, layout, setFocus, setTabList
 
Methods inherited from class org.eclipse.swt.widgets.Scrollable
computeTrim, getClientArea, getHorizontalBar, getVerticalBar
 
Methods inherited from class org.eclipse.swt.widgets.Control
addControlListener, addFocusListener, addHelpListener, addKeyListener, addMouseListener, addMouseMoveListener, addMouseTrackListener, addPaintListener, addTraverseListener, computeSize, forceFocus, getAccessible, getBackground, getBorderWidth, getBounds, getEnabled, getFont, getForeground, getLayoutData, getLocation, getMenu, getMonitor, getParent, getShell, getSize, getToolTipText, getVisible, internal_dispose_GC, internal_new_GC, isEnabled, isFocusControl, isReparentable, isVisible, moveAbove, moveBelow, pack, pack, redraw, redraw, removeControlListener, removeFocusListener, removeHelpListener, removeKeyListener, removeMouseListener, removeMouseMoveListener, removeMouseTrackListener, removePaintListener, removeTraverseListener, setBounds, setBounds, setCapture, setCursor, setEnabled, setLayoutData, setLocation, setLocation, setMenu, setParent, setRedraw, setSize, setSize, setToolTipText, setVisible, toControl, toControl, toDisplay, toDisplay, traverse, update
 
Methods inherited from class org.eclipse.swt.widgets.Widget
addDisposeListener, addListener, checkWidget, dispose, getData, getData, getDisplay, getStyle, isDisposed, isListening, notifyListeners, removeDisposeListener, removeListener, removeListener, setData, setData, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

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

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

NO_TITLE

public static final int NO_TITLE
If this style is used, title will not be rendered.

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

GAP

protected int GAP

toggle

protected ToggleHyperlink toggle

textLabel

protected Control textLabel
Constructor Detail

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
expansionStyle - the style of the expansion widget (TREE_NODE, TWISTIE, CLIENT_INDENT, COMPACT, FOCUS_TITLE)
Method Detail

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 Control
Parameters:
font - the new font (or null)

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:
#getTitle

getText

public String getText()
Returns the title string.

Returns:
the title string
See Also:
#setTitle

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:

setExpanded

public void setExpanded(boolean expanded)
Programmatically changes expanded state.

Parameters:
expanded - the new expanded state

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 listner to remove

onPaint

protected void onPaint(PaintEvent e)
If 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 Composite
See Also:
Composite.computeSize(int, int, boolean)

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.

Eclipse Platform
Release 3.0

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2004. All rights reserved.