|
Eclipse Platform Release 3.3 |
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.eclipse.jface.fieldassist.ControlDecoration
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.
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. |
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 |
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.Method Detail |
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.
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 controlpublic 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 used
|
Eclipse Platform Release 3.3 |
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Guidelines for using Eclipse APIs.
Copyright (c) IBM Corp. and others 2000, 2007. All rights reserved.