net.rim.device.api.ui
Class DrawTextParam

java.lang.Object
  extended by net.rim.device.api.ui.DrawTextParam

public final class DrawTextParam
extends Object

Parameters used to control the drawing and measurement of text.

Since:
BlackBerry API 4.2.1

Field Summary
static int ALREADY_REVERSED
          Value for iReverse: draws text without reversing.
static int BIDI_REORDER
          Value for iReverse: performs bidirectional reordering on the text before drawing.
static int NO_REVERSE
          Value for iReverse: draws text without reversing.
static int NO_TRUNCATE_WITH_ELLIPSIS
          Value for iTruncateWithEllipsis: does not perform truncation with ellipsis.
static int REVERSE
          Value for iReverse: reverses the text before drawing.
static int TRUNCATE_WITH_ELLIPSIS_AT_END
          Value for iTruncateWithEllipsis: if the text would exceed iMaxAdvance, truncates it at the end and inserts an ellipsis.
static int TRUNCATE_WITH_ELLIPSIS_AT_START
          Value for iTruncateWithEllipsis: if the text would exceed iMaxAdvance, truncates it at the start and inserts an ellipsis.
static int TRUNCATE_WITH_NO_ELLIPSIS_AT_START
          Value for iTruncateWithEllipsis: if the text would exceed iMaxAdvance, truncates it at the start but does not insert an ellipsis.
 DrawTextParam.AdvancedDrawTextParam iAdvancedParam
          If non-null, parameters used for advanced features including drawing text on a path.
 int iAlignment
          Alignment flags.
 boolean iDrawNonPrintableCharacters
          Draws non-printable characters, defined as all characters with Unicode general categories Zl, Zp, Cc, Cf, Cs.
 int iEndOffset
          The end offset of the text to draw, within the supplied text.
 int iMaxAdvance
          Truncates the text if its advance width or the width of its inked area would exceed this value.
 int iMaxCharacters
          Truncates the text if it would exceed this number of characters.
 boolean iPasswordMode
          Replaces all characters with the current password character.
 int iReverse
          Whether the text is to be drawn normally, is to be reversed or has already been reversed.
 boolean iShaping
          Enables shaping (contextual glyph choice, diacritic placement and ligature building).
 int iStartOffset
          The start offset of the text to draw, within the supplied text.
 int iTracking
          Tracking is the amount of space, in pixels, defined as a 16.16 fixed-point number, added to the advance of each character.
 int iTruncateWithEllipsis
          Whether the text is to be truncated with an ellipsis, and if so, at the start or end.
 boolean iUnderlineToBounds
          When underlining, if iUnderlineToBounds is set, underlines as far as the left and right edges of the bounds of the inked pixels only.
 
Constructor Summary
DrawTextParam()
          Creates a DrawTextParam object with default values.
DrawTextParam(int aMaxAdvance)
          Creates a DrawTextParam object with a specified maximum advance.
 
Method Summary
 int getEndOffset()
          Deprecated. Use the data member iEndOffset directly.
 int getStartOffset()
          Deprecated. Use the data member iStartOffset directly.
 void reset()
          Sets all parameters to their default values.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

NO_REVERSE

public static final int NO_REVERSE
Value for iReverse: draws text without reversing.

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

REVERSE

public static final int REVERSE
Value for iReverse: reverses the text before drawing.

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

ALREADY_REVERSED

public static final int ALREADY_REVERSED
Value for iReverse: draws text without reversing.

This setting is used for right-to-left runs where bidirectional re-ordering has already been done and the text has already been reversed. It differs from NO_REVERSE in the way truncation is done, if specified; the left end of the text is truncated instead of the right.

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

BIDI_REORDER

public static final int BIDI_REORDER
Value for iReverse: performs bidirectional reordering on the text before drawing.

This is the default setting. Code that has already done bidirectional reordering should use NO_REVERSE for left-to-right runs and REVERSE for right-to-left runs.

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

NO_TRUNCATE_WITH_ELLIPSIS

public static final int NO_TRUNCATE_WITH_ELLIPSIS
Value for iTruncateWithEllipsis: does not perform truncation with ellipsis.

Truncation still happens if iMaxAdvance or iMaxCharacters would be exceeded, but no ellipsis is used.

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

TRUNCATE_WITH_ELLIPSIS_AT_START

public static final int TRUNCATE_WITH_ELLIPSIS_AT_START
Value for iTruncateWithEllipsis: if the text would exceed iMaxAdvance, truncates it at the start and inserts an ellipsis.

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

TRUNCATE_WITH_ELLIPSIS_AT_END

public static final int TRUNCATE_WITH_ELLIPSIS_AT_END
Value for iTruncateWithEllipsis: if the text would exceed iMaxAdvance, truncates it at the end and inserts an ellipsis.

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

TRUNCATE_WITH_NO_ELLIPSIS_AT_START

public static final int TRUNCATE_WITH_NO_ELLIPSIS_AT_START
Value for iTruncateWithEllipsis: if the text would exceed iMaxAdvance, truncates it at the start but does not insert an ellipsis.

This is a convenience feature that is equivalent to using ETruncateWithEllipsisAtStart with the ellipsis character set to U+FFFF.

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

iMaxAdvance

public int iMaxAdvance
Truncates the text if its advance width or the width of its inked area would exceed this value.

This parameter is scaled by the transform applied to the font used to draw the text.

Since:
BlackBerry API 5.0.0

iMaxCharacters

public int iMaxCharacters
Truncates the text if it would exceed this number of characters.

Since:
BlackBerry API 5.0.0

iTracking

public int iTracking
Tracking is the amount of space, in pixels, defined as a 16.16 fixed-point number, added to the advance of each character. If the tracking amount is negative the characters are moved closer together. This parameter is scaled by the transform applied to the font used to draw the text.

Since:
BlackBerry API 5.0.0

iReverse

public int iReverse
Whether the text is to be drawn normally, is to be reversed or has already been reversed.

Since:
BlackBerry API 5.0.0

iTruncateWithEllipsis

public int iTruncateWithEllipsis
Whether the text is to be truncated with an ellipsis, and if so, at the start or end.

Since:
BlackBerry API 5.0.0

iStartOffset

public int iStartOffset
The start offset of the text to draw, within the supplied text. The default is 0.

The purpose of this parameter is to allow substrings of the same string to be drawn or measured, and to supply context for contextual shaping (e.g. for Arabic). If the start offset is greater than 0, text is drawn starting at this offset, and the characters preceding iStartOffset are taken into account when doing contextual glyph substitution.

Since:
BlackBerry API 5.0.0

iEndOffset

public int iEndOffset
The end offset of the text to draw, within the supplied text. The default is Integer.MAX_VALUE, meaning the whole of the text will be drawn.

The purpose of this parameter is to allow substrings of the same string to be drawn or measured, and to supply context for contextual shaping (e.g. for Arabic). If the end offset is less than the length of the text, text is drawn ending at this offset, and the characters following iEndOffset are taken into account when doing contextual glyph substitution.

Since:
BlackBerry API 5.0.0

iAlignment

public int iAlignment
Alignment flags. See DrawStyle (the truncation flags are obselete in this interface; use iTruncateWithEllipsis instead).

Since:
BlackBerry API 5.0.0

iAdvancedParam

public DrawTextParam.AdvancedDrawTextParam iAdvancedParam
If non-null, parameters used for advanced features including drawing text on a path.

Since:
BlackBerry API 5.0.0

iDrawNonPrintableCharacters

public boolean iDrawNonPrintableCharacters
Draws non-printable characters, defined as all characters with Unicode general categories Zl, Zp, Cc, Cf, Cs. Private use and unassigned characters are always drawn, because private use characters are usually printable, and unassigned characters may have been assigned since the category table was generated. The default value is true.

Since:
BlackBerry API 5.0.0

iUnderlineToBounds

public boolean iUnderlineToBounds
When underlining, if iUnderlineToBounds is set, underlines as far as the left and right edges of the bounds of the inked pixels only. If not, underlines from the old pen position to the new pen position - that is, as far as the advance. The default value is true.

Since:
BlackBerry API 5.0.0

iShaping

public boolean iShaping
Enables shaping (contextual glyph choice, diacritic placement and ligature building). The default value is true.

Since:
BlackBerry API 5.0.0

iPasswordMode

public boolean iPasswordMode
Replaces all characters with the current password character.

Since:
BlackBerry API 5.0.0


Constructor Detail

DrawTextParam

public DrawTextParam(int aMaxAdvance)
Creates a DrawTextParam object with a specified maximum advance. All other parameters take their default values.

Parameters:
aMaxAdvance - the maximum advance, in pixels.
Since:
BlackBerry API 5.0.0

DrawTextParam

public DrawTextParam()
Creates a DrawTextParam object with default values.

Since:
BlackBerry API 5.0.0


Method Detail

reset

public void reset()
Sets all parameters to their default values.

Since:
BlackBerry API 5.0.0

getStartOffset

public int getStartOffset()
Deprecated. Use the data member iStartOffset directly.

Gets the start offset of the text to draw.

Returns:
The start offset of the text to draw, within the supplied text.
Since:
BlackBerry API 4.2.1

getEndOffset

public int getEndOffset()
Deprecated. Use the data member iEndOffset directly.

Gets the end offset of the text to draw.

Returns:
The end offset of the text to draw, within the supplied text.
Since:
BlackBerry API 4.2.1





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.