Runtime

## org.eclipse.gmf.runtime.draw2d.ui.figures
Class WrappingLabel

    java.lang.Object
      org.eclipse.draw2d.Figure
          org.eclipse.gmf.runtime.draw2d.ui.figures.WrappingLabel

All Implemented Interfaces:
  IFigure, PositionConstants

Direct Known Subclasses:
  WrapLabel

    public class WrappingLabel

extends Figure
implements PositionConstants

An extended label that has the following extra features:
1. Allows selection, focus feedback, underlined and striked-through text.
2. Enhanced layout functionality for placing icon and text.
3. Text will be word-wrapped to fit the text in the width available.
4. Text will be truncated with an ellipsis if the entire text does not fit in the space available.

EXPLANATION OF LAYOUTS
This WrappingLabel contains functionality to display an icon alongside text. The following will describe how the layout of the icon and text are done.

Using `setTextPlacement(int)`:

The position of the text relative to the icon depends on `setTextPlacement(int)`. If the text placement is set to `PositionConstants.EAST`, then the text would be placed on the right of the icon. Similarly, if text placement is set to `PositionConstants.WEST`, the text will be placed on the left of the icon; `PositionConstants.NORTH` would put the text above the icon; and `PositionConstants.SOUTH` would place the text below the icon.

Using `setTextAlignment(int)` and `setIconAlignment(int)`:

Use `setTextAlignment(int)` and `setIconAlignment(int)` to align the text and icons relative to each other for more dynamic control. If the text placement is on the east or west of the icon(s) (i.e. the text on the right or left of the icon respectively), then only `PositionConstants.TOP`, `PositionConstants.CENTER`, and `PositionConstants.BOTTOM` can be used when calling `setTextAlignment(int)` and `setIconAlignment(int)`. In this case, setting the text alignment to `PositionConstants.TOP` will make sure that the top of the text is aligned horizontally with the top of the icon if the height of the icon is greater than the height of the text. Similarly, setting the text alignment to `PositionConstants.CENTER` will make sure that the top of the text is aligned horizontally with the vertical center of the size of icon if the height of the icon is greater than the height of the text. Also, setting the text alignment to `PositionConstants.BOTTOM` will make sure that the bottom of the text is aligned horizontally with the bottom of the icon if the height of the icon is greater than the height of the text.

The other scenario is when the text placement is on the south or north of the icon (i.e. the text is below or above the icon respectively). If this is true, only `PositionConstants.LEFT`, `PositionConstants.CENTER`, and `PositionConstants.RIGHT` can be used when calling `setTextAlignment(int)` and `setIconAlignment(int)`. In this case, setting the text alignment to `PositionConstants.LEFT` will make sure that the left of the text is aligned vertically with the left of the icon if the width of the icon is greater than the width of the text. Similarly, setting the text alignment to `PositionConstants.CENTER` will make sure that the left of the text is aligned vertically with the horizontal center of the icon if the width of the icon is greater than the width of the text. Also, setting the text alignment to `PositionConstants.RIGHT` will make sure that the right of the text is aligned vertically with the right of the icon if the width of the icon is greater than the width of the text.

`setIconAlignment(int)` works identically as `setTextAlignment(int)`, except the roles of text and icon are switched in the above descriptions.

Using `setAlignment(int)`:

The entire label, text and icon, can be moved into different positions with the label figure, if the figure is bigger than the icon and text. The alignment of the label places the text and icon (no matter how they are arranged relatively to each other) in the top-left, top, top-right, left, center, right, bottom-left, bottom, or bottom-right of the bounds of this `WrappingLabel` figure.

Using `#setTextHorizontalAlignment(int)`:

Use `setTextJustification(int)` with `PositionConstants.LEFT`, `PositionConstants.CENTER`, or `PositionConstants.RIGHT` to justify the text when wordwrap is turned on. The effect will be noticed in multi-lined text only.

WARNING: User-nested figures are not expected within this figure.

Some code taken from the original `WrapLabel` in GMF by melaasar.

Since:
  2.1

Nested Class Summary

Nested classes/interfaces inherited from class org.eclipse.draw2d.Figure
`Figure.FigureIterator, Figure.IdentitySearch`

Nested classes/interfaces inherited from interface org.eclipse.draw2d.IFigure
`IFigure.NoInsets`

Field Summary
`protected static int` `MAX_FLAG` The largest flag defined in this class.
`protected Dimension` `preferredTextSize` The cached preferred text size that can be used after `getPreferredSize(int, int)` is called.

Fields inherited from class org.eclipse.draw2d.Figure
`bgColor, border, bounds, fgColor, flags, font, maxSize, minSize, NO_MANAGER, prefSize, toolTip`

Fields inherited from interface org.eclipse.draw2d.PositionConstants
`ALWAYS_LEFT, ALWAYS_RIGHT, BOTTOM, CENTER, EAST, EAST_WEST, HORIZONTAL, LEFT, LEFT_CENTER_RIGHT, MIDDLE, NONE, NORTH, NORTH_EAST, NORTH_SOUTH, NORTH_WEST, NSEW, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TOP_MIDDLE_BOTTOM, VERTICAL, WEST`

Fields inherited from interface org.eclipse.draw2d.IFigure
`MAX_DIMENSION, MIN_DIMENSION, NO_INSETS`

Constructor Summary
`WrappingLabel()` Construct an empty wrapping label.
`WrappingLabel(Image image)` Construct a wrapping label with thepassed Image as its icon.
`WrappingLabel(java.lang.String text)` Construct a wrapping label with the passed String as its text.
`WrappingLabel(java.lang.String text, Image image)` Construct a wrapping label with passed the String as its text and the passed Image as its icon.

Method Summary
`protected Dimension` `calculateLabelSize(Dimension txtSize)` Calculates the size of the Label using the passed Dimension as the size of the Label's text.
`int` `getAlignment()` Returns the alignment of the label (icon and text) within the figure.
`Image` `getIcon()` Returns the label's icon.
`Image` `getIcon(int index)` Gets the label's icon at the given index
`int` `getIconAlignment()` Returns the alignment of the label's icon relative to the label's text bounds.
`protected Point` `getIconLocation()` Returns the location of the Label's icon relative to the Label.
`protected Dimension` `getIconSize(int index)` getIconSize
`int` `getIconTextGap()` Returns the gap in pixels between the Label's icon and its text.
`Dimension` `getMinimumSize(int w, int h)`
`protected int` `getNumberofIcons()` getIconNumber
`Dimension` `getPreferredSize(int wHint, int hHint)`
`java.lang.String` `getText()` Returns the text of the label.
`int` `getTextAlignment()` Gets the alignment of the label's text relative to the label's icon bounds.
`Rectangle` `getTextBounds()` Returns the bounds of the label's text.
`IFigure` `getTextFigure()` Returns the top-level text figure.
`int` `getTextJustification()` Gets the text justification of the label text.
`int` `getTextPlacement()` Returns the current placement of the label's text relative to its icon.
`protected Dimension` `getTotalIconSize()` getTotalIconSize Calculates the total union of icon sizes
`protected java.lang.String` `getTruncationString()` Gets the truncation string.
`boolean` `hasFocus()`
`protected boolean` `hasIcons()` Determines if there is any icons by checking if icon size is zeros.
`void` `invalidate()`
`boolean` `isSelected()`
`boolean` `isTextStrikedThrough()`
`boolean` `isTextTruncated()` Returns `true` if the label's text is currently truncated and is displaying an ellipsis, `false` otherwise.
`boolean` `isTextUnderlined()`
`boolean` `isTextWrapOn()`
`void` `layout()`
`protected void` `paintClientArea(Graphics graphics)`
`void` `paintFigure(Graphics graphics)`
`void` `setAlignment(int alignment)` Sets the alignment of the label (icon and text) within the figure.
`void` `setFocus(boolean focus)` Sets the focus state of this label
`void` `setFont(Font f)`
`void` `setIcon(Image image)` Sets the label's icon to the passed image.
`void` `setIcon(Image image, int index)` Sets the label's icon at given index
`void` `setIconAlignment(int alignment)` Sets the alignment of the label's icon relative to the label's text bounds.
`protected void` `setIconLocation(Point location)`
`void` `setSelected(boolean selected)` Sets the selection state of this label
`void` `setText(java.lang.String text)` Sets the text in this label.
`void` `setTextAlignment(int alignment)` Sets the alignment of the label's text relative to the label's icon bounds.
`void` `setTextJustification(int justification)` Sets the text justification of the label text.
`void` `setTextPlacement(int where)` Sets the text placement of the label relative to its icon.
`void` `setTextStrikeThrough(boolean strikeThrough)` Sets whether the label text should be striked-through
`void` `setTextUnderline(boolean underline)` Sets whether the label text should be underlined
`void` `setTextWrap(boolean textWrapOn)` Sets whether the label text should wrap
`java.lang.String` `toString()`

Methods inherited from class org.eclipse.draw2d.Figure

`add, add, add, add, addAncestorListener, addCoordinateListener, addFigureListener, addFocusListener, addKeyListener, addLayoutListener, addListener, addMouseListener, addMouseMotionListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, containsPoint, containsPoint, erase, findDescendantAtExcluding, findFigureAt, findFigureAt, findFigureAt, findFigureAtExcluding, findMouseEventTargetAt, findMouseEventTargetInDescendantsAt, fireCoordinateSystemChanged, fireFigureMoved, fireMoved, firePropertyChange, firePropertyChange, firePropertyChange, getBackgroundColor, getBorder, getBounds, getChildren, getClientArea, getClientArea, getCursor, getFlag, getFont, getForegroundColor, getInsets, getLayoutManager, getListeners, getLocalBackgroundColor, getLocalFont, getLocalForegroundColor, getLocation, getMaximumSize, getMinimumSize, getParent, getPreferredSize, getSize, getToolTip, getUpdateManager, handleFocusGained, handleFocusLost, handleKeyPressed, handleKeyReleased, handleMouseDoubleClicked, handleMouseDragged, handleMouseEntered, handleMouseExited, handleMouseHover, handleMouseMoved, handleMousePressed, handleMouseReleased, internalGetEventDispatcher, intersects, invalidateTree, isCoordinateSystem, isEnabled, isFocusTraversable, isMirrored, isMouseEventTarget, isOpaque, isRequestFocusEnabled, isShowing, isValid, isValidationRoot, isVisible, paint, paintBorder, paintChildren, primTranslate, remove, removeAll, removeAncestorListener, removeCoordinateListener, removeFigureListener, removeFocusListener, removeKeyListener, removeLayoutListener, removeListener, removeMouseListener, removeMouseMotionListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, requestFocus, revalidate, setBackgroundColor, setBorder, setBounds, setChildrenDirection, setChildrenEnabled, setChildrenOrientation, setConstraint, setCursor, setEnabled, setFlag, setFocusTraversable, setForegroundColor, setLayoutManager, setLocation, setMaximumSize, setMinimumSize, setOpaque, setParent, setPreferredSize, setPreferredSize, setRequestFocusEnabled, setSize, setSize, setToolTip, setValid, setVisible, translate, translateFromParent, translateToAbsolute, translateToParent, translateToRelative, useLocalCoordinates, validate`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### MAX_FLAG

    protected static final int MAX_FLAG

  The largest flag defined in this class. If subclasses define flags, they should declare them as larger than this value and redefine MAX_FLAG to be their largest flag value.

  See Also:
    `Figure.MAX_FLAG`

### preferredTextSize

    protected Dimension preferredTextSize

  The cached preferred text size that can be used after `getPreferredSize(int, int)` is called.

Constructor Detail

### WrappingLabel

    public WrappingLabel()

  Construct an empty wrapping label.

### WrappingLabel

    public WrappingLabel(java.lang.String text)

  Construct a wrapping label with the passed String as its text.

  Parameters:
    `text` - the label text

### WrappingLabel

    public WrappingLabel(Image image)

  Construct a wrapping label with thepassed Image as its icon.

  Parameters:
    `image` - the label image

### WrappingLabel

    public WrappingLabel(java.lang.String text,
                         Image image)

  Construct a wrapping label with passed the String as its text and the passed Image as its icon.

  Parameters:
    `text` - the label text
    `image` - the label image

Method Detail

### getTextFigure

    public IFigure getTextFigure()

  Returns the top-level text figure. This is public to accommodate a bug in the TextDirectEditManager (see WrappingLabelDirectEditManager). It may not always remain public.

  Returns:
    the top-level text figure.

### calculateLabelSize

    protected Dimension calculateLabelSize(Dimension txtSize)

  Calculates the size of the Label using the passed Dimension as the size of the Label's text.

  Parameters:
    `txtSize` - the precalculated size of the label's text
  Returns:
    the label's size
  Since:
    2.0

### layout

    public void layout()

  Overrides:
    `layout` in class `Figure`

### getIcon

    public Image getIcon()

  Returns the label's icon.

  Returns:
    the label's icon.

### getIcon

    public Image getIcon(int index)

  Gets the label's icon at the given index

  Parameters:
    `index` - The icon index
  Returns:
    the `Image` that is the icon for the given index.

### hasIcons

    protected boolean hasIcons()

  Determines if there is any icons by checking if icon size is zeros.

  Returns:
    true if icons are present, false otherwise

### getIconAlignment

    public int getIconAlignment()

  Returns the alignment of the label's icon relative to the label's text bounds. This is only relevant if the icon's width or height (depending on the location of the icon relative to the text) is smaller than the text's width or height. The default is `PositionConstants.CENTER`.

  See the documentation describing the layout of the label in the class header `WrappingLabel` for more detailed information.

  Returns:
    the icon alignment relative to the text bounds

### getIconLocation

    protected Point getIconLocation()

  Returns the location of the Label's icon relative to the Label.

  Returns:
    the icon's location
  Since:
    2.0

### setIconLocation

    protected void setIconLocation(Point location)

### getIconTextGap

    public int getIconTextGap()

  Returns the gap in pixels between the Label's icon and its text.

  Returns:
    the gap
  Since:
    2.0

### getMinimumSize

    public Dimension getMinimumSize(int w,
                                    int h)

  Specified by:
    `getMinimumSize` in interface `IFigure`
  Overrides:
    `getMinimumSize` in class `Figure`

### getPreferredSize

    public Dimension getPreferredSize(int wHint,
                                      int hHint)

  Specified by:
    `getPreferredSize` in interface `IFigure`
  Overrides:
    `getPreferredSize` in class `Figure`

### getText

    public java.lang.String getText()

  Returns the text of the label. Note that this is the complete text of the label, regardless of whether it is currently being truncated.

  Returns:
    the complete text of this label

### getTextAlignment

    public int getTextAlignment()

  Gets the alignment of the label's text relative to the label's icon bounds. This is only relevant if the text's width or height (depending on the location of the text relative to the icon) is smaller than the icon's width or height. The default text alignment is `PositionConstants.CENTER`.

  See the documentation describing the layout of the label in the class header `WrappingLabel` for more detailed information.

  Returns:
    the text alignment relative to the icon bounds

### getAlignment

    public int getAlignment()

  Returns the alignment of the label (icon and text) within the figure.

  See the documentation describing the layout of the label in the class header `WrappingLabel` for more detailed information.

  Returns:
    the label alignment

### getTextBounds

    public Rectangle getTextBounds()

  Returns the bounds of the label's text. Note that the bounds are calculated using the label's complete text regardless of whether the label's text is currently truncated.

  Returns:
    the bounds of this label's complete text relative to this figure's bounds

### getTextPlacement

    public int getTextPlacement()

  Returns the current placement of the label's text relative to its icon. The default text placement is `PositionConstants.EAST`.

  See the documentation describing the layout of the label in the class header `WrappingLabel` for more detailed information.

  Returns:
    the text placement

### invalidate

    public void invalidate()

  Specified by:
    `invalidate` in interface `IFigure`
  Overrides:
    `invalidate` in class `Figure`

### paintFigure

    public void paintFigure(Graphics graphics)

  Overrides:
    `paintFigure` in class `Figure`

### paintClientArea

    protected void paintClientArea(Graphics graphics)

  Overrides:
    `paintClientArea` in class `Figure`

### setIcon

    public void setIcon(Image image)

  Sets the label's icon to the passed image.

  Parameters:
    `image` - the new label image
  Since:
    2.0

### setIcon

    public void setIcon(Image image,
                        int index)

  Sets the label's icon at given index

  Parameters:
    `image` - The icon image or null to remove the icon
    `index` - The icon index

### setIconAlignment

    public void setIconAlignment(int alignment)

  Sets the alignment of the label's icon relative to the label's text bounds. This is only relevant if the icon's width or height (depending on the location of the icon relative to the text) is smaller than the text's width or height. The default value is `PositionConstants.CENTER`.

  If the text placement is NORTH/SOUTH, valid values are:

  - `PositionConstants.CENTER`
  - `PositionConstants.LEFT`
  - `PositionConstants.RIGHT`

  If the text placement is EAST/WEST, valid values are:

  - `PositionConstants.CENTER`
  - `PositionConstants.TOP`
  - `PositionConstants.BOTTOM`

  See the documentation describing the layout of the label in the class header `WrappingLabel` for more detailed information.

  Parameters:
    `alignment` - the icon alignment relative to the text bounds

### getIconSize

    protected Dimension getIconSize(int index)

  getIconSize

  Parameters:
    `index` - of icon to retrieve size of.
  Returns:
    Dimension representing the icon size.

### getNumberofIcons

    protected int getNumberofIcons()

  getIconNumber

  Returns:
    int number of icons in the wrap label

### getTotalIconSize

    protected Dimension getTotalIconSize()

  getTotalIconSize Calculates the total union of icon sizes

  Returns:
    Dimension that is the union of icon sizes

### setAlignment

    public void setAlignment(int alignment)

  Sets the alignment of the label (icon and text) within the figure. If this figure's bounds are larger than the size needed to display the label, the label will be aligned accordingly. The default is `PositionConstants.LEFT`. Valid values are:
  - `PositionConstants.TOP` | `PositionConstants.LEFT`
  - `PositionConstants.TOP`
  - `PositionConstants.TOP` | `PositionConstants.RIGHT`
  - `PositionConstants.LEFT`
  - `PositionConstants.CENTER`
  - `PositionConstants.RIGHT`
  - `PositionConstants.BOTTOM` | `PositionConstants.LEFT`
  - `PositionConstants.BOTTOM`
  - `PositionConstants.BOTTOM` | `PositionConstants.RIGHT`

  See the documentation describing the layout of the label in the class header `WrappingLabel` for more detailed information.

  Parameters:
    `alignment` - label alignment

### getTruncationString

    protected java.lang.String getTruncationString()

  Gets the truncation string. The default is an ellipsis "...". Clients may override, but if the truncation string changes throughout the lifecycle of this figure, then revalidate() should be called to ensure the cached `truncationStringSize` is cleared.

  Returns:
    the truncation string

### setText

    public void setText(java.lang.String text)

  Sets the text in this label.

  Parameters:
    `text` - the new text to be set

### setTextAlignment

    public void setTextAlignment(int alignment)

  Sets the alignment of the label's text relative to the label's icon bounds. This is only relevant if the text's width or height (depending on the location of the text relative to the icon) is smaller than the icon's width or height. The default value is `PositionConstants.CENTER`.

  If the text placement is EAST/WEST, valid values are:

  - `PositionConstants.CENTER`
  - `PositionConstants.TOP`
  - `PositionConstants.BOTTOM`

  If the text placement is NORTH/SOUTH, and the icon is bigger than the text, then the location of the text can be controlled by how the text is justified `setTextJustification(int)`.

  See the documentation describing the layout of the label in the class header `WrappingLabel` for more detailed information.

  Parameters:
    `alignment` - the text alignment relative to the icon bounds

### setTextPlacement

    public void setTextPlacement(int where)

  Sets the text placement of the label relative to its icon. The default is `PositionConstants.EAST`. Valid values are
  - `PositionConstants.EAST`
  - `PositionConstants.NORTH`
  - `PositionConstants.SOUTH`
  - `PositionConstants.WEST`
  e.g. PositionConstants#EAST indicates the text is on the east of the icon.

  See the documentation describing the layout of the label in the class header `WrappingLabel` for more detailed information.

  Parameters:
    `where` - the text placement

### setTextUnderline

    public void setTextUnderline(boolean underline)

  Sets whether the label text should be underlined

  Parameters:
    `underline` - Whether the label text should be underlined

### isTextUnderlined

    public boolean isTextUnderlined()

  Returns:
    whether the label text is underlined

### setTextStrikeThrough

    public void setTextStrikeThrough(boolean strikeThrough)

  Sets whether the label text should be striked-through

  Parameters:
    `strikeThrough` - whether the label text should be striked-through

### isTextStrikedThrough

    public boolean isTextStrikedThrough()

  Returns:
    whether the label text is striked-through

### setTextWrap

    public void setTextWrap(boolean textWrapOn)

  Sets whether the label text should wrap

  Parameters:
    `b` - whether the label text should wrap

### isTextWrapOn

    public boolean isTextWrapOn()

  Returns:
    whether the label text wrap is on

### setTextJustification

    public void setTextJustification(int justification)

  Sets the text justification of the label text. The default is `PositionConstants.LEFT`. Valid values are
  - `PositionConstants.LEFT`
  - `PositionConstants.CENTER`
  - `PositionConstants.RIGHT`

  Parameters:
    `alignment` - the text justification.

### getTextJustification

    public int getTextJustification()

  Gets the text justification of the label text.

  Returns:
    the text justification -- `PositionConstants.LEFT`, `PositionConstants.CENTER`, or `PositionConstants.RIGHT`

### hasFocus

    public boolean hasFocus()

  Specified by:
    `hasFocus` in interface `IFigure`
  Overrides:
    `hasFocus` in class `Figure`
  Returns:
    the focus state of this label

### setFocus

    public void setFocus(boolean focus)

  Sets the focus state of this label

  Parameters:
    `focus` - true will cause a focus rectangle to be drawn around the text of the Label

### isSelected

    public boolean isSelected()

  Returns:
    the selection state of this label

### setSelected

    public void setSelected(boolean selected)

  Sets the selection state of this label

  Parameters:
    `selected` - true will cause the label to appear selected

### setFont

    public void setFont(Font f)

  Specified by:
    `setFont` in interface `IFigure`
  Overrides:
    `setFont` in class `Figure`

### toString

    public java.lang.String toString()

  Overrides:
    `toString` in class `java.lang.Object`

### isTextTruncated

    public boolean isTextTruncated()

  Returns `true` if the label's text is currently truncated and is displaying an ellipsis, `false` otherwise.
  Note that this code only reports horizontal truncation by delegating to the GEF TextFlow and ignores that fact that GMF TextFlowEx may be vertically truncated.

  Returns:
    `true` if the label's text is truncated

Runtime

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp., Borland Software Corp., and others 2005,2006. All rights reserved.