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(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.
|
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(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.
|
public ControlDecoration(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(Control control, int position, 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.swt.events.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.swt.events.MenuDetectListener)
public void addSelectionListener(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(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 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 Image getImage()
null
if one has not been set.public void setImage(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 Rectangle getDecorationRectangle(Control targetControl)
targetControl
- the control whose coordinates should be usedpublic boolean isVisible()
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.true
if the decoration is visible, and
false
if it is not.setShowOnlyOnFocus(boolean)
,
hide()
,
show()
Copyright (c) 2000, 2015 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.