Expandable composite and Section controls

ExpandableComposite acts similar to Group control with the ability to collapse a portion of a page a toggle control:

	ExpandableComposite ec = toolkit.createExpandableComposite(form.getBody(), 
	ec.setText("Expandable Composite title");
	String ctext = "We will now create a somewhat long text so that "+
	"we can use it as content for the expandable composite. "+
	"Expandable composite is used to hide or show the text using the "+
	"toggle control";
	Label client = toolkit.createLabel(ec, ctext, SWT.WRAP);
	ec.addExpansionListener(new ExpansionAdapter() {
		public void expansionStateChanged(ExpansionEvent e) {

The ExpandableComposite control accepts a number of styles that affect its appearance and behavior. Style TREE_NODE will create the toggle control used in a tree widget for expanding and collapsing nodes, while TWISTIE will create a triangle-style toggle. Using EXPANDED will create the control in the initial expanded state. If style COMPACT is used, control will report width in the collapsed state enough to fit in the title line only (i.e. when collapsed, it will be as compact horizontally as possible). Finally, CLIENT_INDENT will indent the client to align with the title (otherwise, client will be aligned with the toggle control).

Expandable composite itself is responsible for rendering the toggle control and the title. The control to expand or collapse is set as a client. Note the requirement that the client is a direct child of the expandable composite.

Expandable composite fires ExpansionEvent objects when expansion state changes. Adding an expansion listener to the control is needed in order to reflow the form on state change. This is because expansion causes changes in expandable composite size, but the change will not take effect until the next time the parent is laid out (hence we need to force it).

Section is a subclass of the expandable composite that adds additional capabilities. It is typically used to partition a form into a number of sections, each with its own title and optional description. When Section.TITLE_BAR or Section.SHORT_TITLE_BAR styles are used, decoration around the title area further enhances the grouping.

Unlike ExpandableComposite, Section automatically handles reflows on expansion state change. Other interesting uses of the expansion state notification are lazy creation of the Section content that is delayed until the section is expaned.