ManualCustomWidgets
Custom Widgets, Compounds and Composites
There are 2 different types of widgets which can act as containers for other widgets; composites and compounds.
A composite uses an swt control as container for its children; the impact is, that the layout of children inside this composite is completely independent of the layout of the other controls in the form. If you want to group a label with a text control using a composite, use multiple of these groups in one form and like to align all labels in the form, this will not be possible.
For this reason rcpforms invented compounds; a compound logically groups its children, but does not use any swt composite, children are embedded into the swt control associated with the rcp parent of the compound.
This means that RCPCompound has no associated swt control at all!
Composite
Compound
extensible
A
D
non extensible
B
E
mixed mode
C
F
A - Extensible Composite
Description: Grouping of widgets which all share the same layout manager defined by the form developer but do not share layout properties with widgets outside the group.
Examples: sections, groups, nested forms ...
Technical Details:
- Form Developer adds children to composite using nested Builder
- Form Developer sets layout info by passing it in nested builder add method
- Builder creates swt control and assigns layout info
Example: Sandbox3FormPart.createUI() for an example using nested builder
B - Non extensible Composite
Description: Create a custom widget which is composed of multiple other widgets and the form developer has no control over the internal layout.
Examples: international phone numer widget composed of several text fields, color chooser composed of a color field and selection buttons ...
Technical Details:
- Framework Customizer creates Custom Composite overriding isExtensible() to return false
- Custom Composite creates its rcp children
- Custom Composite assigns layout info to children
- Form Developer uses custom composite like a standard widget by adding it to a form using a builder which assigns the layout info to the custom composite; children of the custom composite and their layout infos are not accessible by the Form Developer
- Composite creates childrens swt controls in createUI() of the custom composite (ATTENTION: ONLY IF isExtensible() returns false)
Example: StreetNumberCustomComposite
C - Mixed mode Composite
Description: this is not supported by the framework since there is no standard use case.
D - Extensible Compound
Description: Grouping of widgets which all share the layout manager defined by the parent of the compound. Thus can share the same layout properties with widgets outside the group.
Examples: setting the state (eg. enable or visible) of a group of controls at the same time
E - Non extensible Compound
Description: Create a custom widget which is composed of multiple other widgets and the form developer has control over the internal layout.
Examples: Grouping of a label and its associated control.
Technical Details:
- Framework Customizer creates custom RCPCompound subclass; by default RCPCompound.isExtensible() returns false already
- Framework Customizer adds children rcp controls to RCPCompound
- for layout there is a shortcut for common cases: compounds are often used to group e.g. a label with control or a label with a text and a select button. In these scenarios there is a main control which should use additional layout space, labels and buttons should use suitable default layout data. The GridBuilder has a mechanism to apply the layout passed when adding the compound to a form to the main control and get suitable defaults for other controls based on their types.
- Framework Customizer overrides getMainControl() to return the layout data suitable child control
- Framework Customizer may have to override GridBuilder.applyLayout() to define layout for main control in the context of the compound
- Form Developer uses Builder to add a compound to a form, specifying layout data for the main control
Example: RCPPicker, RCPDatePicker
F - Mixed mode Composite
Description: this is not supported by the framework since there is no standard use case.
When should one use composites or compounds?
If there is a need to have strictly aligned widgets (eg. labels and textfields) over the whole form, the compounds with its shared layout is the one to use.
In all other cases composites are preferred because this is the standard swt concept.
