public class ControlDecoration
extends java.lang.Object
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.
FieldDecoration
,
FieldDecorationRegistry
Modifier and Type | Class and Description |
---|---|
(package private) class |
ControlDecoration.Hover
The hover used to show a decoration image's description.
|
Modifier and Type | Field and Description |
---|---|
(package private) static boolean |
CARBON
Cached platform flags for dealing with platform-specific issues.
|
private org.eclipse.swt.widgets.Composite |
composite
The composite on which to render the decoration and hook mouse events, or null if we are hooking all parent
composites.
|
private org.eclipse.swt.widgets.Listener |
compositeListener
The untyped listener installed for notifying external listeners
|
(package private) org.eclipse.swt.widgets.Control |
control
The associated control
|
private static boolean |
DEBUG
Debug flag for tracing
|
(package private) org.eclipse.swt.graphics.Rectangle |
decorationRectangle
The current rectangle used for tracking mouse moves
|
private java.lang.String |
descriptionText
The associated description text.
|
private org.eclipse.swt.events.DisposeListener |
disposeListener
The dispose listener
|
private org.eclipse.swt.events.FocusListener |
focusListener
The focus listener
|
(package private) boolean |
hasFocus
An internal flag tracking whether we have focus.
|
private ControlDecoration.Hover |
hover
The hover used for showing description text
|
private org.eclipse.swt.graphics.Image |
image
The associated image.
|
private int |
listenerInstalls
Debug counter used to match add and remove listeners
|
private int |
marginWidth
Margin width used between the decorator and the control.
|
(package private) org.eclipse.core.runtime.ListenerList |
menuDetectListeners
Registered menu detect listeners.
|
(package private) org.eclipse.swt.events.MouseMoveListener |
mouseMoveListener
The mouse move listener installed for tracking the hover
|
private org.eclipse.swt.events.MouseTrackListener |
mouseTrackListener
The mouse listener installed for tracking the hover
|
(package private) org.eclipse.swt.widgets.Control |
moveListeningTarget
Control that we last installed a move listener on.
|
private org.eclipse.swt.events.PaintListener |
paintListener
The paint listener installed for drawing the decoration
|
private int |
position
The position of the decoration.
|
(package private) org.eclipse.core.runtime.ListenerList |
selectionListeners
Registered selection listeners.
|
(package private) boolean |
showHover
Boolean indicating whether the decoration should show its description text in a hover when the user hovers over the
decoration.
|
(package private) boolean |
showOnlyOnFocus
Boolean indicating whether the decoration should only be shown when the control has focus
|
(package private) boolean |
visible
The decoration's visibility flag
|
Constructor and Description |
---|
ControlDecoration(org.eclipse.swt.widgets.Control control,
int position)
Construct a ControlDecoration for decorating the specified control at the specified position relative to the
control.
|
ControlDecoration(org.eclipse.swt.widgets.Control control,
int position,
org.eclipse.swt.widgets.Composite composite)
Construct a ControlDecoration for decorating the specified control at the specified position relative to the
control.
|
Modifier and Type | Method and Description |
---|---|
private void |
addControlListeners()
Add any listeners needed on the target control and on the composite where the decoration is to be rendered.
|
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(org.eclipse.swt.events.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.
|
org.eclipse.swt.widgets.Control |
getControl()
Get the control that is decorated by the receiver.
|
protected org.eclipse.swt.graphics.Rectangle |
getDecorationRectangle(org.eclipse.swt.widgets.Control targetControl)
Return the rectangle in which the decoration should be rendered, in coordinates relative to the specified control.
|
java.lang.String |
getDescriptionText()
Get the description text that may be shown in a hover for this decoration.
|
org.eclipse.swt.graphics.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.
|
private void |
installCompositeListeners(org.eclipse.swt.widgets.Composite c) |
(package private) void |
notifyMenuDetectListeners(org.eclipse.swt.widgets.Event event) |
(package private) void |
notifySelectionListeners(org.eclipse.swt.widgets.Event event) |
(package private) void |
printAddListener(org.eclipse.swt.widgets.Widget widget,
java.lang.String listenerType) |
(package private) void |
printRemoveListener(org.eclipse.swt.widgets.Widget widget,
java.lang.String listenerType) |
private void |
removeCompositeListeners(org.eclipse.swt.widgets.Composite c) |
private void |
removeControlListeners() |
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(org.eclipse.swt.events.SelectionListener listener)
Removes the listener from the collection of listeners who will be notified when the decoration is selected.
|
void |
setDescriptionText(java.lang.String text)
Set the image shown in this control decoration.
|
void |
setImage(org.eclipse.swt.graphics.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.
|
(package private) boolean |
shouldShowDecoration() |
void |
show()
Show the control decoration.
|
void |
showHoverText(java.lang.String text)
Show the specified text using the same hover dialog as is used to show decorator descriptions.
|
private void |
showHoverText(java.lang.String text,
org.eclipse.swt.widgets.Control hoverNear) |
protected void |
update()
Something has changed, requiring redraw.
|
private static boolean DEBUG
static boolean CARBON
org.eclipse.swt.widgets.Control control
private org.eclipse.swt.widgets.Composite composite
private org.eclipse.swt.graphics.Image image
private java.lang.String descriptionText
private int position
boolean visible
boolean showOnlyOnFocus
boolean showHover
private int marginWidth
org.eclipse.core.runtime.ListenerList selectionListeners
org.eclipse.core.runtime.ListenerList menuDetectListeners
private org.eclipse.swt.events.FocusListener focusListener
private org.eclipse.swt.events.DisposeListener disposeListener
private org.eclipse.swt.events.PaintListener paintListener
private org.eclipse.swt.events.MouseTrackListener mouseTrackListener
org.eclipse.swt.events.MouseMoveListener mouseMoveListener
private org.eclipse.swt.widgets.Listener compositeListener
org.eclipse.swt.widgets.Control moveListeningTarget
private int listenerInstalls
org.eclipse.swt.graphics.Rectangle decorationRectangle
boolean hasFocus
private ControlDecoration.Hover hover
public ControlDecoration(org.eclipse.swt.widgets.Control control, int position)
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
).
control
- the control to be decoratedposition
- bit-wise or of position constants (SWT.TOP
, SWT.BOTTOM
,
SWT.LEFT
, SWT.RIGHT
, and SWT.CENTER
).public ControlDecoration(org.eclipse.swt.widgets.Control control, int position, org.eclipse.swt.widgets.Composite composite)
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
).
control
- the control to be decoratedposition
- 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.public void addMenuDetectListener(MenuDetectListener listener)
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.
listener
- the listener which should be notifiedMenuDetectListener
,
MenuDetectEvent
,
removeMenuDetectListener(org.eclipse.m2e.core.ui.internal.search.util.MenuDetectListener)
public void removeMenuDetectListener(MenuDetectListener listener)
listener
- the listener which should no longer be notified. This message has no effect if the listener was not
previously added to the receiver.MenuDetectListener
,
addMenuDetectListener(org.eclipse.m2e.core.ui.internal.search.util.MenuDetectListener)
public void addSelectionListener(org.eclipse.swt.events.SelectionListener listener)
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.
listener
- the listener which should be notifiedSelectionListener
,
SelectionEvent
,
removeSelectionListener(org.eclipse.swt.events.SelectionListener)
public void removeSelectionListener(org.eclipse.swt.events.SelectionListener listener)
listener
- the listener which should no longer be notified. This message has no effect if the listener was not
previously added to the receiver.SelectionListener
,
addSelectionListener(org.eclipse.swt.events.SelectionListener)
public void dispose()
public org.eclipse.swt.widgets.Control getControl()
null
if the control has been uninstalled.private void addControlListeners()
private void installCompositeListeners(org.eclipse.swt.widgets.Composite c)
private void removeCompositeListeners(org.eclipse.swt.widgets.Composite c)
void notifySelectionListeners(org.eclipse.swt.widgets.Event event)
void notifyMenuDetectListeners(org.eclipse.swt.widgets.Event event)
public void showHoverText(java.lang.String text)
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.text
- the text to be shown in the info hover, or null
if no text should be shown.public void hideHover()
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.
public void show()
setShowOnlyOnFocus(boolean)
is set to true
, the decoration will only be shown if the control
has focus.public void hide()
public java.lang.String getDescriptionText()
null
if none has been set.public void setDescriptionText(java.lang.String text)
text
- the text to be shown as a description for the decoration, or null
if none has been set.public org.eclipse.swt.graphics.Image getImage()
null
if one has not been set.public void setImage(org.eclipse.swt.graphics.Image image)
image
- the image to be shown adjacent to the control. Should never be null
.public boolean getShowOnlyOnFocus()
false
.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
.public void setShowOnlyOnFocus(boolean showOnlyOnFocus)
false
.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
.public boolean getShowHover()
true
.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.public void setShowHover(boolean showHover)
true
.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.public int getMarginWidth()
0
.public void setMarginWidth(int marginWidth)
0
.marginWidth
- the number of pixels that should be reserved between the horizontal edge of the control and the
adjacent edge of the decoration.protected void update()
private void showHoverText(java.lang.String text, org.eclipse.swt.widgets.Control hoverNear)
private void removeControlListeners()
protected org.eclipse.swt.graphics.Rectangle getDecorationRectangle(org.eclipse.swt.widgets.Control targetControl)
targetControl
- the control whose coordinates should be usedboolean shouldShowDecoration()
void printAddListener(org.eclipse.swt.widgets.Widget widget, java.lang.String listenerType)
void printRemoveListener(org.eclipse.swt.widgets.Widget widget, java.lang.String listenerType)