net.rim.device.api.ui
Class DrawTextParam

java.lang.Object
  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

Nested Class Summary
static class	DrawTextParam.AdvancedDrawTextParam Advanced text drawing parameters.

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 6.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