Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.eclipse.swt.graphics
Class TextLayout

    java.lang.Object
      org.eclipse.swt.graphics.TextLayout

public final class TextLayout
extends Object

`TextLayout` is a graphic object that represents styled text.

Instances of this class provide support for drawing, cursor navigation, hit testing, text wrapping, alignment, tab expansion line breaking, etc. These are aspects required for rendering internationalized text.

Application code must explicitly invoke the `TextLayout#dispose()` method to release the operating system resources managed by each instance when those instances are no longer required.

Since:
  3.0

Constructor Summary
`TextLayout(Device device)` Constructs a new instance of this class on the given device.

Method Summary
`void` | `dispose()` Disposes of the operating system resources associated with the text layout.
`void` | `draw(GC gc, int x, int y)` Draws the receiver's text using the specified GC at the specified point.
`void` | `draw(GC gc, int x, int y, int selectionStart, int selectionEnd, Color selectionForeground, Color selectionBackground)` Draws the receiver's text using the specified GC at the specified point.
`int` | `getAlignment()` Returns the receiver's horizontal text alignment, which will be one of `SWT.LEFT`, `SWT.CENTER` or `SWT.RIGHT`.
`int` | `getAscent()` Returns the ascent of the receiver.
`Rectangle` | `getBounds()` Returns the bounds of the receiver.
`Rectangle` | `getBounds(int start, int end)` Returns the bounds for the specified range of characters.
`int` | `getDescent()` Returns the descent of the receiver.
`Font` | `getFont()` Returns the default font currently being used by the receiver to draw and measure text.
`int` | `getLevel(int offset)` Returns the embedding level for the specified character offset.
`Rectangle` | `getLineBounds(int lineIndex)` Returns the bounds of the line for the specified line index.
`int` | `getLineCount()` Returns the receiver's line count.
`int` | `getLineIndex(int offset)` Returns the index of the line that contains the specified character offset.
`FontMetrics` | `getLineMetrics(int lineIndex)` Returns the font metrics for the specified line index.
`int[]` | `getLineOffsets()` Returns the line offsets.
`Point` | `getLocation(int offset, boolean trailing)` Returns the location for the specified character offset.
`int` | `getNextOffset(int offset, int movement)` Returns the next offset for the specified offset and movement type.
`int` | `getOffset(int x, int y, int[] trailing)` Returns the character offset for the specified point.
`int` | `getOffset(Point point, int[] trailing)` Returns the character offset for the specified point.
`int` | `getOrientation()` Returns the orientation of the receiver.
`int` | `getPreviousOffset(int offset, int movement)` Returns the previous offset for the specified offset and movement type.
`int[]` | `getSegments()` Returns the text segments offsets of the receiver.
`int` | `getSpacing()` Returns the line spacing of the receiver.
`TextStyle` | `getStyle(int offset)` Gets the style of the receiver at the specified character offset.
`int[]` | `getTabs()` Returns the tab list of the receiver.
`String` | `getText()` Gets the receiver's text, which will be an empty string if it has never been set.
`int` | `getWidth()` Returns the width of the receiver.
`boolean` | `isDisposed()` Returns `true` if the text layout has been disposed, and `false` otherwise.
`void` | `setAlignment(int alignment)` Sets the text alignment for the receiver.
`void` | `setAscent(int ascent)` Sets the ascent of the receiver.
`void` | `setDescent(int descent)` Sets the descent of the receiver.
`void` | `setFont(Font font)` Sets the default font which will be used by the receiver to draw and measure text.
`void` | `setOrientation(int orientation)` Sets the orientation of the receiver, which must be one of `SWT.LEFT_TO_RIGHT` or `SWT.RIGHT_TO_LEFT`.
`void` | `setSegments(int[] segments)` Sets the offsets of the receiver's text segments.
`void` | `setSpacing(int spacing)` Sets the line spacing of the receiver.
`void` | `setStyle(TextStyle style, int start, int end)` Sets the style of the receiver for the specified range.
`void` | `setTabs(int[] tabs)` Sets the receiver's tab list.
`void` | `setText(String text)` Sets the receiver's text.
`void` | `setWidth(int width)` Sets the line width of the receiver, which determines how text should be wrapped and aligned.

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

Constructor Detail

### TextLayout

    public TextLayout(Device device)

  Constructs a new instance of this class on the given device.

  You must dispose the text layout when it is no longer required.

Parameters:
  `device` - the device on which to allocate the text layout
Throws:
  `IllegalArgumentException` -
  - ERROR_NULL_ARGUMENT - if device is null and there is no current device
See Also:
  `dispose()`

Method Detail

### dispose

    public void dispose()

  Disposes of the operating system resources associated with the text layout. Applications must dispose of all allocated text layouts.

### draw

    public void draw(GC gc,
                     int x,
                     int y)

  Draws the receiver's text using the specified GC at the specified point.

  Parameters:
    `gc` - the GC to draw
    `x` - the x coordinate of the top left corner of the rectangular area where the text is to be drawn
    `y` - the y coordinate of the top left corner of the rectangular area where the text is to be drawn
  Throws:
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### draw

    public void draw(GC gc,
                     int x,
                     int y,
                     int selectionStart,
                     int selectionEnd,
                     Color selectionForeground,
                     Color selectionBackground)

  Draws the receiver's text using the specified GC at the specified point.

  Parameters:
    `gc` - the GC to draw
    `x` - the x coordinate of the top left corner of the rectangular area where the text is to be drawn
    `y` - the y coordinate of the top left corner of the rectangular area where the text is to be drawn
    `selectionStart` - the offset where the selections starts, or -1 indicating no selection
    `selectionEnd` - the offset where the selections ends, or -1 indicating no selection
    `selectionForeground` - selection foreground, or NULL to use the system default color
    `selectionBackground` - selection background, or NULL to use the system default color
  Throws:
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### getAlignment

    public int getAlignment()

  Returns the receiver's horizontal text alignment, which will be one of `SWT.LEFT`, `SWT.CENTER` or `SWT.RIGHT`.

  Returns:
    the alignment used to positioned text horizontally
  Throws:
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### getAscent

    public int getAscent()

  Returns the ascent of the receiver.

  Returns:
    the ascent
  Throws:
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
  See Also:
    `getDescent()`, `setDescent(int)`, `setAscent(int)`, `getLineMetrics(int)`

### getBounds

    public Rectangle getBounds()

  Returns the bounds of the receiver.

  Returns:
    the bounds of the receiver
  Throws:
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### getBounds

    public Rectangle getBounds(int start,
                               int end)

  Returns the bounds for the specified range of characters. The bounds is the smallest rectangle that encompasses all characters in the range. The start and end offsets are inclusive and will be clamped if out of range.

  Parameters:
    `start` - the start offset
    `end` - the end offset
  Returns:
    the bounds of the character range
  Throws:
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### getDescent

    public int getDescent()

  Returns the descent of the receiver.

  Returns:
    the descent
  Throws:
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
  See Also:
    `getAscent()`, `setAscent(int)`, `setDescent(int)`, `getLineMetrics(int)`

### getFont

    public Font getFont()

  Returns the default font currently being used by the receiver to draw and measure text.

  Returns:
    the receiver's font
  Throws:
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### getLevel

    public int getLevel(int offset)

  Returns the embedding level for the specified character offset. The embedding level is usually used to determine the directionality of a character in bidirectional text.

  Parameters:
    `offset` - the charecter offset
  Returns:
    the embedding level
  Throws:
    `IllegalArgumentException` -
    - ERROR_INVALID_ARGUMENT - if the character offset is out of range
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### getLineBounds

    public Rectangle getLineBounds(int lineIndex)

  Returns the bounds of the line for the specified line index.

  Parameters:
    `lineIndex` - the line index
  Returns:
    the line bounds
  Throws:
    `IllegalArgumentException` -
    - ERROR_INVALID_ARGUMENT - if the line index is out of range
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### getLineCount

    public int getLineCount()

  Returns the receiver's line count. This includes lines caused by wrapping.

  Returns:
    the line count
  Throws:
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### getLineIndex

    public int getLineIndex(int offset)

  Returns the index of the line that contains the specified character offset.

  Parameters:
    `offset` - the character offset
  Returns:
    the line index
  Throws:
    `IllegalArgumentException` -
    - ERROR_INVALID_ARGUMENT - if the character offset is out of range
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### getLineMetrics

    public FontMetrics getLineMetrics(int lineIndex)

  Returns the font metrics for the specified line index.

  Parameters:
    `lineIndex` - the line index
  Returns:
    the font metrics
  Throws:
    `IllegalArgumentException` -
    - ERROR_INVALID_ARGUMENT - if the line index is out of range
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### getLineOffsets

    public int[] getLineOffsets()

  Returns the line offsets. Each value in the array is the offset for the first character in a line except for the last value, which contains the length of the text.

  Returns:
    the line offsets
  Throws:
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### getLocation

    public Point getLocation(int offset,
                             boolean trailing)

  Returns the location for the specified character offset. The `trailing` argument indicates whether the offset corresponds to the leading or trailing edge of the cluster.

  Parameters:
    `offset` - the character offset
    `trailing` - the trailing flag
  Returns:
    the location of the character offset
  Throws:
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
  See Also:
    `getOffset(Point, int[])`, `getOffset(int, int, int[])`

### getNextOffset

    public int getNextOffset(int offset,
                             int movement)

  Returns the next offset for the specified offset and movement type. The movement is one of `SWT.MOVEMENT_CHAR`, `SWT.MOVEMENT_CLUSTER` or `SWT.MOVEMENT_WORD`.

  Parameters:
    `offset` - the start offset
    `movement` - the movement type
  Returns:
    the next offset
  Throws:
    `IllegalArgumentException` -
    - ERROR_INVALID_ARGUMENT - if the offset is out of range
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
  See Also:
    `getPreviousOffset(int, int)`

### getOffset

    public int getOffset(Point point,
                         int[] trailing)

  Returns the character offset for the specified point. For a typical character, the trailing argument will be filled in to indicate whether the point is closer to the leading edge (0) or the trailing edge (1). When the point is over a cluster composed of multiple characters, the trailing argument will be filled with the position of the character in the cluster that is closest to the point.

  Parameters:
    `point` - the point
    `trailing` - the trailing buffer
  Returns:
    the character offset
  Throws:
    `IllegalArgumentException` -
    - ERROR_INVALID_ARGUMENT - if the trailing length is less than `1`
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
  See Also:
    `getLocation(int, boolean)`

### getOffset

    public int getOffset(int x,
                         int y,
                         int[] trailing)

  Returns the character offset for the specified point. For a typical character, the trailing argument will be filled in to indicate whether the point is closer to the leading edge (0) or the trailing edge (1). When the point is over a cluster composed of multiple characters, the trailing argument will be filled with the position of the character in the cluster that is closest to the point.

  Parameters:
    `x` - the x coordinate of the point
    `y` - the y coordinate of the point
    `trailing` - the trailing buffer
  Returns:
    the character offset
  Throws:
    `IllegalArgumentException` -
    - ERROR_INVALID_ARGUMENT - if the trailing length is less than `1`
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
  See Also:
    `getLocation(int, boolean)`

### getOrientation

    public int getOrientation()

  Returns the orientation of the receiver.

  Returns:
    the orientation style
  Throws:
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### getPreviousOffset

    public int getPreviousOffset(int offset,
                                 int movement)

  Returns the previous offset for the specified offset and movement type. The movement is one of `SWT.MOVEMENT_CHAR`, `SWT.MOVEMENT_CLUSTER` or `SWT.MOVEMENT_WORD`.

  Parameters:
    `offset` - the start offset
    `movement` - the movement type
  Returns:
    the previous offset
  Throws:
    `IllegalArgumentException` -
    - ERROR_INVALID_ARGUMENT - if the offset is out of range
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
  See Also:
    `getNextOffset(int, int)`

### getSegments

    public int[] getSegments()

  Returns the text segments offsets of the receiver.

  Returns:
    the text segments offsets
  Throws:
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### getSpacing

    public int getSpacing()

  Returns the line spacing of the receiver.

  Returns:
    the line spacing
  Throws:
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### getStyle

    public TextStyle getStyle(int offset)

  Gets the style of the receiver at the specified character offset.

  Parameters:
    `offset` - the text offset
  Returns:
    the style or `null` if not set
  Throws:
    `IllegalArgumentException` -
    - ERROR_INVALID_ARGUMENT - if the character offset is out of range
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### getTabs

    public int[] getTabs()

  Returns the tab list of the receiver.

  Returns:
    the tab list
  Throws:
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### getText

    public String getText()

  Gets the receiver's text, which will be an empty string if it has never been set.

  Returns:
    the receiver's text
  Throws:
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### getWidth

    public int getWidth()

  Returns the width of the receiver.

  Returns:
    the width
  Throws:
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### isDisposed

    public boolean isDisposed()

  Returns `true` if the text layout has been disposed, and `false` otherwise.

  This method gets the dispose state for the text layout. When a text layout has been disposed, it is an error to invoke any other method using the text layout.

  Returns:
    `true` when the text layout is disposed and `false` otherwise

### setAlignment

    public void setAlignment(int alignment)

  Sets the text alignment for the receiver. The alignment controls how a line of text is positioned horizontally. The argument should be one of `SWT.LEFT`, `SWT.RIGHT` or `SWT.CENTER`.

  The default alignment is `SWT.LEFT`. Note that the receiver's width must be set in order to use `SWT.RIGHT` or `SWT.CENTER` alignment.

  Parameters:
    `alignment` - the new alignment
  Throws:
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
  See Also:
    `setWidth(int)`

### setAscent

    public void setAscent(int ascent)

  Sets the ascent of the receiver. The ascent is distance in pixels from the baseline to the top of the line and it is applied to all lines. The default value is `-1` which means that the ascent is calculated from the line fonts.

  Parameters:
    `ascent` - the new ascent
  Throws:
    `IllegalArgumentException` -
    - ERROR_INVALID_ARGUMENT - if the ascent is less than `-1`
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
  See Also:
    `setDescent(int)`, `#getLineMetrics()`

### setDescent

    public void setDescent(int descent)

  Sets the descent of the receiver. The descent is distance in pixels from the baseline to the bottom of the line and it is applied to all lines. The default value is `-1` which means that the descent is calculated from the line fonts.

  Parameters:
    `descent` - the new descent
  Throws:
    `IllegalArgumentException` -
    - ERROR_INVALID_ARGUMENT - if the descent is less than `-1`
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
  See Also:
    `setAscent(int)`, `#getLineMetrics()`

### setFont

    public void setFont(Font font)

  Sets the default font which will be used by the receiver to draw and measure text. If the argument is null, then a default font appropriate for the platform will be used instead. Note that a text style can override the default font.

  Parameters:
    `font` - the new font for the receiver, or null to indicate a default font
  Throws:
    `IllegalArgumentException` -
    - ERROR_INVALID_ARGUMENT - if the font has been disposed
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### setOrientation

    public void setOrientation(int orientation)

  Sets the orientation of the receiver, which must be one of `SWT.LEFT_TO_RIGHT` or `SWT.RIGHT_TO_LEFT`.

  Parameters:
    `orientation` - new orientation style
  Throws:
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### setSegments

    public void setSegments(int[] segments)

  Sets the offsets of the receiver's text segments. Text segments are used to override the default behaviour of the bidirectional algorithm. Bidirectional reordering can happen within a text segment but not between two adjacent segments. Each text segment is determined by two consecutive offsets in the `segments` arrays. The first element of the array should always be zero and the last one should always be equals to length of the text.

  Parameters:
    `segments` - the text segments offset
  Throws:
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### setSpacing

    public void setSpacing(int spacing)

  Sets the line spacing of the receiver. The line spacing is the space left between lines.

  Parameters:
    `spacing` - the new line spacing
  Throws:
    `IllegalArgumentException` -
    - ERROR_INVALID_ARGUMENT - if the spacing is negative
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### setStyle

    public void setStyle(TextStyle style,
                         int start,
                         int end)

  Sets the style of the receiver for the specified range. Styles previously set for that range will be overwritten. The start and end offsets are inclusive and will be clamped if out of range.

  Parameters:
    `style` - the style
    `start` - the start offset
    `end` - the end offset
  Throws:
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### setTabs

    public void setTabs(int[] tabs)

  Sets the receiver's tab list. Each value in the tab list specifies the space in pixels from the origin of the text layout to the respective tab stop. The last tab stop width is repeated continuously.

  Parameters:
    `tabs` - the new tab list
  Throws:
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### setText

    public void setText(String text)

  Sets the receiver's text.

  Parameters:
    `text` - the new text
  Throws:
    `IllegalArgumentException` -
    - ERROR_NULL_ARGUMENT - if the text is null
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

### setWidth

    public void setWidth(int width)

  Sets the line width of the receiver, which determines how text should be wrapped and aligned. The default value is `-1` which means wrapping is disabled.

  Parameters:
    `width` - the new width
  Throws:
    `IllegalArgumentException` -
    - ERROR_INVALID_ARGUMENT - if the width is `0` or less than `-1`
    `SWTException` -
    - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
  See Also:
    `setAlignment(int)`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
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, 2004. All rights reserved.