Bug 163461 [Field Assist] - API - ControlDecoration should work with image+text, not FieldDecoration
DecoratedField supported multiple decoration locations, so it was useful to expose a data structure that referred to a particular decoration. Hence FieldDecoration was defined. It is just an image+text data structure, but was useful for asking DecoratedField to "do things" to a particular decoration, such as hiding it, showing it, updating it, etc. The initial API for ControlDecoration also supported FieldDecoration, in an attempt to "explain itself" as being similar to DecoratedField. However, since a ControlDecoration only shows one decoration, there's not really a need for the image+text to have any kind of identity. It would be better if the ControlDecoration API worked in terms of having an image and a description text. Clients could still use FieldDecorations and the registry if desired, but the API shouldn't require it, since it's trivial to pull the image and text out of a decoration and feed it to ControlDecoration.
bundles/org.eclipse.jface/src/org/eclipse/jface/fieldassist/ControlDecoration.java
* composite that parents the decorations and fields, and reserving space for
 * any decorations added to the field. ControlDecoration simply renders the
 * decoration adjacent to the specified (already created) control, with no
 * guarantee that the decoration won't be clipped or otherwise obscured or
 * overlapped by adjacent controls, including another ControlDecoration placed
 * in the same location. The tradeoff is one of guaranteed placement (via
 * {@link DecoratedField}) vs. more flexibility in creating the control, using
 * ControlDecoration, along with less concern for aligning decorated and
 * non-decorated fields.
 * <p>
 * Clients using ControlDecoration should typically ensure that enough margin
 * space is reserved for a decoration by altering the layout data margins,
 * although this is not assumed or required by the ControlDecoration
 * implementation.
 * <p>
 * This class is intended to be instantiated and used by clients. It is not
 * intended to be subclassed by clients.
 * 
 * <p>
 * <strong>EXPERIMENTAL</strong> This class or interface has been added as part
 * of a work in progress. This API may change at any given time. Please do not
 * use this API without consulting with the Platform/UI team.
 * 
 * @since 3.3
 * 
 * @see FieldDecoration
 * @see FieldDecorationRegistry
 * @see DecoratedField
 */
public class ControlDecoration {