Eclipse Plug-in Developer Guide (Galileo) - ControlDecoration (Eclipse Platform API Specification)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse Platform
Release 3.5

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.eclipse.jface.fieldassist
Class ControlDecoration


java.lang.Object
  
org.eclipse.jface.fieldassist.ControlDecoration

public class ControlDecoration
extends Object
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

Constructor Summary

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

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.

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 image shown in this control 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 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.

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)

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:: MenuDetectListener, addMenuDetectListener(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)

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:: SelectionListener, addSelectionListener(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 image shown in this control 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

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse Platform
Release 3.5

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

org.eclipse.jface.fieldassist Class ControlDecoration

ControlDecoration

ControlDecoration

addMenuDetectListener

removeMenuDetectListener

addSelectionListener

removeSelectionListener

dispose

getControl

showHoverText

hideHover

show

hide

getDescriptionText

setDescriptionText

getImage

setImage

getShowOnlyOnFocus

setShowOnlyOnFocus

getShowHover

setShowHover

getMarginWidth

setMarginWidth

update

getDecorationRectangle

org.eclipse.jface.fieldassist
Class ControlDecoration