Class ControlDecoration
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:
- Restriction:
- This class is not intended to be subclassed by clients.
-
Constructor Summary
ConstructorsConstructorDescriptionControlDecoration
(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
Modifier and TypeMethodDescriptionvoid
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 theMenuDetectListener
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 theSelectionListener
interface.void
dispose()
Dispose this ControlDecoration.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.Get the description text that may be shown in a hover for this decoration.getImage()
Get the image shown in this control decoration.int
Get the margin width in pixels that should be used between the decorator and the horizontal edge of the control.boolean
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
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
Hide any hover popups that are currently showing on the control.boolean
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
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 Details
-
ControlDecoration
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
andSWT.RIGHT
describe the horizontal placement of the decoration relative to the control, and the constantsSWT.TOP
,SWT.CENTER
, andSWT.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 decoratedposition
- bit-wise or of position constants (SWT.TOP
,SWT.BOTTOM
,SWT.LEFT
,SWT.RIGHT
, andSWT.CENTER
).
-
ControlDecoration
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
andSWT.RIGHT
describe the horizontal placement of the decoration relative to the control, and the constantsSWT.TOP
,SWT.CENTER
, andSWT.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 decoratedposition
- bit-wise or of position constants (SWT.TOP
,SWT.BOTTOM
,SWT.LEFT
,SWT.RIGHT
, andSWT.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 isnull
, then the decoration will be rendered on whichever composite (or composites) are located in the specified position.
-
-
Method Details
-
addMenuDetectListener
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 theMenuDetectListener
interface.The
widget
field in the SelectionEvent will contain the Composite on which the decoration is rendered that received the click. Thex
andy
fields will be in coordinates relative to the display. Thedata
field will contain the decoration that received the event.- Parameters:
listener
- the listener which should be notified- See Also:
-
removeMenuDetectListener
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:
-
addSelectionListener
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 theSelectionListener
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. Thex
andy
fields will be in coordinates relative to that widget. Thedata
field will contain the decoration that received the event.- Parameters:
listener
- the listener which should be notified- See Also:
-
removeSelectionListener
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:
-
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
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
Show the specified text using the same hover dialog as is used to show decorator descriptions. WhensetShowHover(boolean)
has been set totrue
, 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, ornull
if no text should be shown.
-
hideHover
public void hideHover()Hide any hover popups that are currently showing on the control. WhensetShowHover(boolean)
has been set totrue
, 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 usingshowHoverText(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. IfsetShowOnlyOnFocus(boolean)
is set totrue
, 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
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
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, ornull
if none has been set.
-
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
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 benull
.
-
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 isfalse
.- Returns:
true
if the decoration should only be shown when the control has focus, andfalse
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 istrue
.
-
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 isfalse
.- Parameters:
showOnlyOnFocus
-true
if the decoration should only be shown when the control has focus, andfalse
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 istrue
.
-
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 istrue
.- Returns:
true
if a hover popup containing the decoration's description text should be shown when the user hovers over the decoration, andfalse
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 istrue
.- Parameters:
showHover
-true
if a hover popup containing the decoration's description text should be shown when the user hovers over the decoration, andfalse
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 is0
.- 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 is0
.- 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
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()
andshow()
), the visibility state of the associated control (Control.isVisible()
), and the focus state of the control if applicable (setShowOnlyOnFocus(boolean)
. When this method returnstrue
, 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, andfalse
if it is not.- Since:
- 3.6
- See Also:
-