public class ControlDecoration extends 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
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 |
---|---|
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.
|
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.
|
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(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.
|
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.
|
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.public void showHoverText(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 String getDescriptionText()
null
if none has been set.public void setDescriptionText(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()
protected org.eclipse.swt.graphics.Rectangle getDecorationRectangle(org.eclipse.swt.widgets.Control targetControl)
targetControl
- the control whose coordinates should be usedCopyright © 2005–2015 Sonatype, Inc.. All rights reserved.