Package org.eclipse.jface.fieldassist

Class 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:
    FieldDecoration, FieldDecorationRegistry
    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

      All Methods Instance Methods Concrete Methods 
      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.

    • Constructor Detail

      • 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 Detail

      • 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:
        MenuDetectListener, MenuDetectEvent, removeMenuDetectListener(org.eclipse.swt.events.MenuDetectListener)

      • 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:
        SelectionListener, SelectionEvent, removeSelectionListener(org.eclipse.swt.events.SelectionListener)

      • 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:
        setShowOnlyOnFocus(boolean), hide(), show()