Package org.eclipse.jface.fieldassist

Class ControlDecoration

java.lang.Object
org.eclipse.jface.fieldassist.ControlDecoration
public class ControlDecoration extends Object
ControlDecoration renders an image decoration near a control. It allows clients to specify an image and a position for the image relative to the control. A ControlDecoration may be assigned description text, which can optionally be shown when the user hovers over the image. Clients can decorate any kind of control.

Decoration images always appear on the left or right side of the field, never above or below it. Decorations can be positioned at the top, center, or bottom of either side of the control. Future implementations may provide additional positioning options for decorations.

ControlDecoration renders the image adjacent to the specified (already created) control, with no guarantee that it won't be clipped or otherwise obscured or overlapped by adjacent controls, including another ControlDecoration placed in the same location. Clients should ensure that there is adequate space adjacent to the control to show the decoration properly.

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.

This class is intended to be instantiated and used by clients. It is not intended to be subclassed by clients.

Since:
3.3
See Also:
Restriction:
This class is not intended to be subclassed by clients.

  • Constructor Summary

    Constructors
    Constructor
    Description
    ControlDecoration(Control control, int position)
    Construct a ControlDecoration for decorating the specified control at the specified position relative to the control.
    ControlDecoration(Control control, int position, Composite composite)
    Construct a ControlDecoration for decorating the specified control at the specified position relative to the control.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addMenuDetectListener(MenuDetectListener listener)
    Adds the listener to the collection of listeners who will be notified when the platform-specific context menu trigger has occurred, by sending it one of the messages defined in the MenuDetectListener interface.
    void
    addSelectionListener(SelectionListener listener)
    Adds the listener to the collection of listeners who will be notified when the decoration is selected, by sending it one of the messages defined in the SelectionListener interface.
    void
    dispose()
    Dispose this ControlDecoration.
    Control
    getControl()
    Get the control that is decorated by the receiver.
    protected Rectangle
    getDecorationRectangle(Control targetControl)
    Return the rectangle in which the decoration should be rendered, in coordinates relative to the specified control.
    String
    getDescriptionText()
    Get the description text that may be shown in a hover for this decoration.
    Image
    getImage()
    Get the image shown in this control decoration.
    int
    getMarginWidth()
    Get the margin width in pixels that should be used between the decorator and the horizontal edge of the control.
    boolean
    getShowHover()
    Get the boolean that controls whether the decoration's description text should be shown in a hover when the user hovers over the decoration.
    boolean
    getShowOnlyOnFocus()
    Get the boolean that controls whether the decoration is shown only when the control has focus.
    void
    hide()
    Hide the control decoration and any associated hovers.
    void
    hideHover()
    Hide any hover popups that are currently showing on the control.
    boolean
    isVisible()
    Return a boolean indicating whether the decoration is visible.
    void
    removeMenuDetectListener(MenuDetectListener listener)
    Removes the listener from the collection of listeners who will be notified when the platform-specific context menu trigger has occurred.
    void
    removeSelectionListener(SelectionListener listener)
    Removes the listener from the collection of listeners who will be notified when the decoration is selected.
    void
    setDescriptionText(String text)
    Set the description text that may be shown in a hover for this decoration.
    void
    setImage(Image image)
    Set the image shown in this control decoration.
    void
    setMarginWidth(int marginWidth)
    Set the margin width in pixels that should be used between the decorator and the horizontal edge of the control.
    void
    setShowHover(boolean showHover)
    Set the boolean that controls whether the decoration's description text should be shown in a hover when the user hovers over the decoration.
    void
    setShowOnlyOnFocus(boolean showOnlyOnFocus)
    Set the boolean that controls whether the decoration is shown only when the control has focus.
    void
    show()
    Show the control decoration.
    void
    showHoverText(String text)
    Show the specified text using the same hover dialog as is used to show decorator descriptions.
    protected void
    update()
    Something has changed, requiring redraw.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • ControlDecoration

      public ControlDecoration(Control control, int position)
      Construct a ControlDecoration for decorating the specified control at the specified position relative to the control. Render the decoration on top of any Control that happens to appear at the specified location.

      SWT constants are used to specify the position of the decoration relative to the control. The position should include style bits describing both the vertical and horizontal orientation. SWT.LEFT and SWT.RIGHT describe the horizontal placement of the decoration relative to the control, and the constants SWT.TOP, SWT.CENTER, and SWT.BOTTOM describe the vertical alignment of the decoration relative to the control. Decorations always appear on either the left or right side of the control, never above or below it. For example, a decoration appearing on the left side of the field, at the top, is specified as SWT.LEFT | SWT.TOP. If no position style bits are specified, the control decoration will be positioned to the left and center of the control (SWT.LEFT | SWT.CENTER).

      Parameters:
      control - the control to be decorated
      position - bit-wise or of position constants (SWT.TOP, SWT.BOTTOM, SWT.LEFT, SWT.RIGHT, and SWT.CENTER).

    • ControlDecoration

      public ControlDecoration(Control control, int position, Composite composite)
      Construct a ControlDecoration for decorating the specified control at the specified position relative to the control. Render the decoration only on the specified Composite or its children. The decoration will be clipped if it does not appear within the visible bounds of the composite or its child composites.

      SWT constants are used to specify the position of the decoration relative to the control. The position should include style bits describing both the vertical and horizontal orientation. SWT.LEFT and SWT.RIGHT describe the horizontal placement of the decoration relative to the control, and the constants SWT.TOP, SWT.CENTER, and SWT.BOTTOM describe the vertical alignment of the decoration relative to the control. Decorations always appear on either the left or right side of the control, never above or below it. For example, a decoration appearing on the left side of the field, at the top, is specified as SWT.LEFT | SWT.TOP. If no position style bits are specified, the control decoration will be positioned to the left and center of the control (SWT.LEFT | SWT.CENTER).

      Parameters:
      control - the control to be decorated
      position - bit-wise or of position constants (SWT.TOP, SWT.BOTTOM, SWT.LEFT, SWT.RIGHT, and SWT.CENTER).
      composite - The SWT composite within which the decoration should be rendered. The decoration will be clipped to this composite, but it may be rendered on a child of the composite. The decoration will not be visible if the specified composite or its child composites are not visible in the space relative to the control, where the decoration is to be rendered. If this value is null, then the decoration will be rendered on whichever composite (or composites) are located in the specified position.

  • Method Details

    • addMenuDetectListener

      public void addMenuDetectListener(MenuDetectListener listener)
      Adds the listener to the collection of listeners who will be notified when the platform-specific context menu trigger has occurred, by sending it one of the messages defined in the MenuDetectListener interface.

      The widget field in the SelectionEvent will contain the Composite on which the decoration is rendered that received the click. The x and y fields will be in coordinates relative to the display. The data field will contain the decoration that received the event.

      Parameters:
      listener - the listener which should be notified
      See Also:

    • removeMenuDetectListener

      public void removeMenuDetectListener(MenuDetectListener listener)
      Removes the listener from the collection of listeners who will be notified when the platform-specific context menu trigger has occurred.
      Parameters:
      listener - the listener which should no longer be notified. This message has no effect if the listener was not previously added to the receiver.
      See Also:

    • addSelectionListener

      public void addSelectionListener(SelectionListener listener)
      Adds the listener to the collection of listeners who will be notified when the decoration is selected, by sending it one of the messages defined in the SelectionListener interface.

      widgetSelected is called when the decoration is selected (by mouse click). widgetDefaultSelected is called when the decoration is double-clicked.

      The widget field in the SelectionEvent will contain the Composite on which the decoration is rendered that received the click. The x and y fields will be in coordinates relative to that widget. The data field will contain the decoration that received the event.

      Parameters:
      listener - the listener which should be notified
      See Also:

    • removeSelectionListener

      public void removeSelectionListener(SelectionListener listener)
      Removes the listener from the collection of listeners who will be notified when the decoration is selected.
      Parameters:
      listener - the listener which should no longer be notified. This message has no effect if the listener was not previously added to the receiver.
      See Also:

    • dispose

      public void dispose()
      Dispose this ControlDecoration. Unhook any listeners that have been installed on the target control. This method has no effect if the receiver is already disposed.

    • getControl

      public Control getControl()
      Get the control that is decorated by the receiver.
      Returns:
      the Control decorated by the receiver. May be null if the control has been uninstalled.

    • showHoverText

      public void showHoverText(String text)
      Show the specified text using the same hover dialog as is used to show decorator descriptions. When setShowHover(boolean) has been set to true, a decoration's description text will be shown in an info hover over the field's control whenever the mouse hovers over the decoration. This method can be used to show a decoration's description text at other times (such as when the control receives focus), or to show other text associated with the field. The hover will not be shown if the decoration is hidden.
      Parameters:
      text - the text to be shown in the info hover, or null if no text should be shown.

    • hideHover

      public void hideHover()
      Hide any hover popups that are currently showing on the control. When setShowHover(boolean) has been set to true, a decoration's description text will be shown in an info hover over the field's control as long as the mouse hovers over the decoration, and will be hidden when the mouse exits the decoration. This method can be used to hide a hover, whether it was shown explicitly using showHoverText(String), or was showing because the user was hovering in the decoration.

      This message has no effect if there is no current hover.

    • show

      public void show()
      Show the control decoration. This message has no effect if the decoration is already showing. If setShowOnlyOnFocus(boolean) is set to true, the decoration will only be shown if the control has focus.

    • hide

      public void hide()
      Hide the control decoration and any associated hovers. This message has no effect if the decoration is already hidden.

    • getDescriptionText

      public String getDescriptionText()
      Get the description text that may be shown in a hover for this decoration.
      Returns:
      the text to be shown as a description for the decoration, or null if none has been set.

    • setDescriptionText

      public void setDescriptionText(String text)
      Set the description text that may be shown in a hover for this decoration. Update the rendered decoration.
      Parameters:
      text - the text to be shown as a description for the decoration, or null if none has been set.

    • getImage

      public Image getImage()
      Get the image shown in this control decoration.
      Returns:
      the image to be shown adjacent to the control, or null if one has not been set.

    • setImage

      public void setImage(Image image)
      Set the image shown in this control decoration. Update the rendered decoration.
      Parameters:
      image - the image to be shown adjacent to the control. Should never be null.

    • getShowOnlyOnFocus

      public boolean getShowOnlyOnFocus()
      Get the boolean that controls whether the decoration is shown only when the control has focus. The default value of this setting is false.
      Returns:
      true if the decoration should only be shown when the control has focus, and false if it should always be shown. Note that if the control is not capable of receiving focus (SWT.NO_FOCUS), then the decoration will never show when this value is true.

    • setShowOnlyOnFocus

      public void setShowOnlyOnFocus(boolean showOnlyOnFocus)
      Set the boolean that controls whether the decoration is shown only when the control has focus. The default value of this setting is false.
      Parameters:
      showOnlyOnFocus - true if the decoration should only be shown when the control has focus, and false if it should always be shown. Note that if the control is not capable of receiving focus (SWT.NO_FOCUS), then the decoration will never show when this value is true.

    • getShowHover

      public boolean getShowHover()
      Get the boolean that controls whether the decoration's description text should be shown in a hover when the user hovers over the decoration. The default value of this setting is true.
      Returns:
      true if a hover popup containing the decoration's description text should be shown when the user hovers over the decoration, and false if a hover should not be shown.

    • setShowHover

      public void setShowHover(boolean showHover)
      Set the boolean that controls whether the decoration's description text should be shown in a hover when the user hovers over the decoration. The default value of this setting is true.
      Parameters:
      showHover - true if a hover popup containing the decoration's description text should be shown when the user hovers over the decoration, and false if a hover should not be shown.

    • getMarginWidth

      public int getMarginWidth()
      Get the margin width in pixels that should be used between the decorator and the horizontal edge of the control. The default value of this setting is 0.
      Returns:
      the number of pixels that should be reserved between the horizontal edge of the control and the adjacent edge of the decoration.

    • setMarginWidth

      public void setMarginWidth(int marginWidth)
      Set the margin width in pixels that should be used between the decorator and the horizontal edge of the control. The default value of this setting is 0.
      Parameters:
      marginWidth - the number of pixels that should be reserved between the horizontal edge of the control and the adjacent edge of the decoration.

    • update

      protected void update()
      Something has changed, requiring redraw. Redraw the decoration and update the hover text if appropriate.

    • getDecorationRectangle

      protected Rectangle getDecorationRectangle(Control targetControl)
      Return the rectangle in which the decoration should be rendered, in coordinates relative to the specified control. If the specified control is null, return the rectangle in display coordinates.
      Parameters:
      targetControl - the control whose coordinates should be used
      Returns:
      the rectangle in which the decoration should be rendered

    • isVisible

      public boolean isVisible()
      Return a boolean indicating whether the decoration is visible. This method considers the visibility state of the decoration ( hide() and show()), the visibility state of the associated control (Control.isVisible()), and the focus state of the control if applicable (setShowOnlyOnFocus(boolean). When this method returns true, it means that the decoration should be visible. However, this method does not consider the case where the decoration should be visible, but is obscured by another window or control, or positioned off the screen. In these cases, the decoration will still be considered visible.
      Returns:
      true if the decoration is visible, and false if it is not.
      Since:
      3.6
      See Also: