Class FxFormattedText

public class FxFormattedText extends FxText implements 
            IFxTextConstants, IFxGraphicsConstants, 
            IFxLocaleFormatting
{
  // Constructors
  public FxFormattedText();
  public FxFormattedText(String newBuff);
  public FxFormattedText(char newBuff[]);
  public FxFormattedText(char newBuff[], int offset, int length);

  // Methods
  public FxFormattedText dropTail(int iStart);
  public synchronized void ensureNotDirty( Graphics g );
  public Rectangle getBounding();
  public Point getClosestOffset(int scrnX, int scrnY);
  public Font getFont();
  public int getHeight();
  public int getHorizAlign();
  public boolean getKerning();
  public Locale getLocale();
  public boolean getLocaleFormattingOverride();
  public boolean getMnemonicDrawing();
  public Point getNextStartPoint();
  public int getOffsetFromPos(int scrnX, int scrnY, int flags);
  public IFxShape getOutline();
  public char getPasswordChar();
  public Point getScrnLocation(int index) ;
  public Point getStartPoint();
  public String getText();
  public int getTextDirection();
  public int getVertAlign();
  public int getWidth();
  public int getWordWrap();
  public void insert(char key, int iPos);
  public void insert(char key[], int iPos);
  public void insert(char key[], int offs, int len, int iPos);
  public boolean isBodyLocationDetermined();
  public boolean isDirty();
  public void paint(FxGraphics g, int startPos, int length,
        int opaquing);
  public void paint(Graphics g);
  public void remove(int iPos, int numberToRemove);
  public void setBounding(Rectangle r, boolean bRetainCurrPoint);
  public void setCallback(IFxTextCallback c);
  public void setFont(Font f);
  public void setHorizAlign(int h);
  public void setKerning(boolean useKerning);
  public void setLocale(Locale locale);
  public void setLocaleFormattingOverride(boolean override);
  public void setMnemonicDrawing(boolean mnem);
  public void setOutline(IFxShape outline);
  public void setPasswordChar(char c);
  public void setStartPoint(int x, int y);
  public void setStartPoint(Point p);
  public void setStartPointAtOrigin();
  public void setTabs(int newTabs[]);
  public void setText(char newBuff[], int offset, int len);
  public void setText(char newBuff[]);
  public void setText(String s);
  public void setTextDirection(int dir);
  public void setVertAlign(int v);
  public void setWordWrap(int ww);
  public Rectangle shrinkBound(boolean reset);
}

This class provides text layout and formatting for text in any language. FxFormattedText is used by UI and edit controls where features, such as text alignment and text direction, must be specified by the user.

You can draw FxFormattedText buffers directly with either paint methods. UIDrawText also uses FxFormattedText internally.

This class supports vertical writing.

FxText
  |
  +--FxFormattedText

Constructors

FxFormattedText

public FxFormattedText();

Creates and initiates an empty text buffer.

FxFormattedText

public FxFormattedText(String newBuff);

Creates a text buffer that is based on a specific string.

Parameter	Description
newBuff	The string that the new buffer is based on.

FxFormattedText

public FxFormattedText(char newBuff[]);

Creates and initializes a new text buffer, based on an specific array of characters. This constructor copies characters to the new buffer from the base offset of the character array. The FxFormattedText(char, int, int) constructor, however, enables character array manipulation that starts from a specified offset in the character array.

Parameter	Description
newBuff	The array of characters that the new buffer is based on.

FxFormattedText

public FxFormattedText(char newBuff[], int offset, int length);

Creates and initializes a new text buffer, based on a character array.

Parameter	Description
newBuff	The character array that the new text buffer is based on.
offset	The offset used in the specified character array.
length	The length of the character array that is copied to the new text buffer.

Methods

dropTail

public FxFormattedText dropTail(int iStart);

Retrieves an FxFormattedText buffer with the same attributes as the current buffer. The text from the offset iStart onward is removed.

Return Value:

Returns an FxFormattedText buffer with the text from iStart to the end of the buffer cropped.

Parameter	Description
iStart	The starting point of the text that is removed.

ensureNotDirty

public synchronized void ensureNotDirty( Graphics g );

Updates text block formatting according to the specified graphics context.

Return Value:

No return value.

Parameter	Description
g	The graphics object used to draw the text buffer.

Remarks:

This method must be called before widths, heights, and other parameters can be retrieved.

getBounding

public Rectangle getBounding();

Retrieves the current bounding box that is associated with the text.

Return Value:

Returns the Rectangle that is used as the bounding box.

See Also: setBounding

getClosestOffset

public Point getClosestOffset(int scrnX, int scrnY);

Finds the closest character to the screen location.

This method is used when isBodyLocationDetermined returns false, which indicates that the exact screen location of a character cannot be determined.

Return Value:

Returns the point where the closest character was found.

Parameter	Description
scrnX	The x coordinate of the screen location.
scrnY	The y coordinate of the screen location.

Remarks:

The x coordinate of the Point returned is equal to the offset idx into the text buffer, while the y coordinate of the Point is y = match param --> (x-x1)2 + (y-y1)2. This is returned so that all formats in a UIEdit object get the chance to pick the character position.

getFont

public Font getFont();

Retrieves the current font that is used with the FxFormattedText buffer. If no font is specified when this method is called, a default font is returned.

Return Value:

Returns the font that is used.

See Also: setFont

getHeight

public int getHeight();

Retrieves the height of a line of text in the current font (in pixels).

Return Value:

Returns the height of the text.

Remarks:

This method takes into account the standard leading (inter-line space) between the regular ascent and descent of a line of text. (The ascent is the distance from the baseline of the text to the top of most characters in a specific font. Similarly, the descent is the distance from the baseline to the bottom of most characters in a specific font.)

getHorizAlign

public int getHorizAlign();

Retrieves the horizontal alignment of the text.

Return Value:

Returns the horizontal alignment.

See Also: setHorizAlign, setVertAlign, getVertAlign

getKerning

public boolean getKerning();

Determines whether kerning is in use.

Return Value:

Returns true if kerning is currently used to format text; otherwise, returns false.

See Also: setKerning

getLocale

public Locale getLocale();

Retrieves the java.util.Locale that the text is based on.

Return Value:

Returns the current java.util.Locale.

See Also: setLocale

getLocaleFormattingOverride

public boolean getLocaleFormattingOverride();

Determines whether text formatting override features are based on locale.

Return Value:

Returns true if the locale determines overriding features; otherwise, returns false.

See Also: setLocaleFormattingOverride

getMnemonicDrawing

public boolean getMnemonicDrawing();

Determines whether text uses underlining for hot key tracking. This method is available for backward compatibility; the underlined character must be preceded by an ampersand.

Return Value:

Returns true if underlines are set; otherwise, returns false.

See Also: setMnemonicDrawing

getNextStartPoint

public Point getNextStartPoint();

Retrieves the next position to draw after the text.

Return Value:

Returns the point that is the next position to draw after the text.

Remarks:

This method, which is useful for tying multiple sentences together, is used by the FxFormattedText class. Be aware that if the text ends on a hard return, the Point object must refer to the next line.

getOffsetFromPos

public int getOffsetFromPos(int scrnX, int scrnY, int flags);

Retrieves the offset of the character that is closest to a specific screen location.

Return Value:

Returns the closest offset if successful; otherwise, returns -1.

Parameter	Description
scrnX	The x coordinate of the screen location to check.
scrnY	The y coordinate of the screen location to check.
flags	The flags controlling the method.

Remarks:

This method is used by the edit classes (including UIDrawText, UIEdit, and FxFormattedText) to find which character is closest to the caret. The flags are the same as those for opaquing text drawing. If there are dy arrays, this method will fail and return -1. If a failure occurs, use the getClosestOffset method to determine the offset in an array that is nearest to a given screen location.

See Also: getClosestOffset

getOutline

public IFxShape getOutline();

Retrieves the outline of the shape.

Return Value:

Returns the shape that is used as the outline.

See Also: setOutline

getPasswordChar

public char getPasswordChar();

Retrieves the character used to mask user text input.

Return Value:

Returns the password character. If no password character is specified, zero (cast as a char) is returned.

getScrnLocation

public Point getScrnLocation(int index) ;

Finds the screen location of a particular character. If the character index given is not valid for the current character buffer, the method returns null.

Return Value:

Returns the screen location of the character.

Parameter	Description
index	The index of the character for which the screen location is being retrieved.

getStartPoint

public Point getStartPoint();

Retrieves the current specified starting point for drawing the text.

Return Value:

Returns the point where the text starts.

See Also: setStartPoint

getText

public String getText();

Retrieves the current text in the text buffer as a String object.

Return Value:

Returns a string that contains the current text in the buffer.

See Also: com.ms.fx.FxFormattedText.setText

getTextDirection

public int getTextDirection();

Retrieves the current text direction.

Return Value:

Returns the current text direction.

See Also: setTextDirection

getVertAlign

public int getVertAlign();

Retrieves the vertical alignment for the text.

Return Value:

Returns the vertical alignment.

See Also: setVertAlign

getWidth

public int getWidth();

Retrieves the width of the entire buffer if it is one long string.

Return Value:

Returns the advance width of the character buffer, in number of characters.

getWordWrap

public int getWordWrap();

Retrieves the word-wrapping functionality.

Return Value:

Returns the word-wrapping functionality.

See Also: setWordWrap

insert

public void insert(char key, int iPos);

Inserts a single character into the buffer.

Return Value:

No return value.

Parameter	Description
key	The character to insert.
iPos	The position in the buffer where the character is inserted.

Overrides:

insert(char,int) in FxText.

insert

public void insert(char key[], int iPos);

Inserts an array of characters into the buffer.

Return Value:

No return value.

Parameter	Description
key	The array of characters to insert.
iPos	The position where the characters are inserted.

Overrides:

insert(char[],int) in FxText.

insert

public void insert(char key[], int offs, int len, int iPos);

Inserts an array of characters into the buffer.

Return Value:

No return value.

Parameter	Description
key	The source array of characters to insert.
offs	The specified offset in the source array.
len	The length of the character array fragment starting from offs.
iPos	The position in the buffer where the characters are to be inserted.

Overrides:

insert(char[],int,int,int) in FxText.

isBodyLocationDetermined

public boolean isBodyLocationDetermined();

Checks if there are definable start, body, and end screen positions.

Return Value:

Returns true if the exact screen location of a character is determined. In this event, you can use the getScrnLocation method. If the return value is false, use the getClosestOffset method to determine the offset nearest to the specified screen coordinates.

See Also: getScrnLocation, getClosestOffset

isDirty

public boolean isDirty();

Determines whether the text needs reformatting before any other operations may be performed on the buffer. Use the ensureNotDirty method to reformat the text.

Return Value:

Returns true if there is a pending update for the text.

paint

public void paint(FxGraphics g, int startPos, int length, int opaquing);

Paints the selected characters in the text block.

Return Value:

No return value.

Parameter	Description
g	The graphics object to use.
startPos	The starting character position.
length	The length of the character array.
opaquing	Used only if the graphics object has a text background color set and the text has a bounding box. Can be a combination of the following values: 0 Don't opaque. IFxTextConstants.OPAQUE_PRIOR Opaque everything prior to the starting character position, startPos. IFxTextConstants.OPAQUE_BODY Fill out the lines painted between the character position startPos and the screen position NextPos. IFxTextConstants.OPAQUE_POST Opaque everything after the screen position NextPos.

paint

public void paint(Graphics g);

Paints the text block.

Return Value:

No return value.

Parameter	Description
g	The graphics object to use.

remove

public void remove(int iPos, int numberToRemove);

Deletes characters from a buffer. This may be a single character; if so, numberToRemove is 1.

Return Value:

No return value.

Parameter	Description
iPos	The starting position of the characters to remove.
numberToRemove	The number of characters to remove.

Overrides:

remove(int,int) in FxText.

setBounding

public void setBounding(Rectangle r, boolean bRetainCurrPoint);

Sets the bounding box. If there isn't a bounding box, the text is drawn in a single line.

Return Value:

No return value.

Parameter	Description
r	The rectangle to set as the bounding box.
bRetainCurrPoint	If false, the alignment is processed as in UIDrawText and the current point is lost. If the alignments are set to tdScriptDefault, right-to-left/top-to-bottom and so on, will be incorporated.

Remarks:

See the rules for setCurrPoint.

setCallback

public void setCallback(IFxTextCallback c);

Sets the callback interface.

Return Value:

No return value.

Parameter	Description
c	The callback interface to associate with the current object.

Remarks:

This method allows applications to make final modifications to the layout after all script processing has been done.

setFont

public void setFont(Font f);

Sets the font for the buffer.

Return Value:

No return value.

Parameter	Description
f	The font to set.

setHorizAlign

public void setHorizAlign(int h);

Sets the horizontal alignment for the text.

Return Value:

No return value.

Parameter	Description
h	The horizontal alignment. It may be one those that are shown in the following table. htaCenter htaLeft htaRight htaJustified htaStretch or htaScriptDefault

Remarks:

Some of the vertical and horizontal alignment values are script and locale dependant. Although all values are valid, the ensureNotDirty method may use default values (htaLeft and vtaTop) if the horizontal or vertical alignment are not appropriate for the current locale or script direction.

See Also: setVertAlign, getVertAlign

setKerning

public void setKerning(boolean useKerning);

Sets whether the text buffer, when formatted, will use kerning.

Return Value:

No return value.

Parameter	Description
useKerning	Set to true if you want the text, when formatted, to use kerning.

Remarks:

Currently, this method is not implemented.

See Also: getKerning

setLocale

public void setLocale(Locale locale);

Sets the locale for the text.

Return Value:

No return value.

Parameter

Description

locale

The current java.util.Locale. Locale can also control vertical writing directions, when used with the Locale.JAPANESE_VERTICAL, Locale.SIMPLIFIED_CHINESE_VERTICAL, Locale.KOREAN_VERTICAL, and Locale.TRADITIONAL_CHINESE_VERTICAL locale constants. Note The JAPANESE_VERTICAL, and other similar constants, are Microsoft additions to the java.util.Locale class. When used with the setLocale method, their effect is the same as using the setTextDirection method. For example, the setLocale(Locale.KOREAN_VERTICAL) method has the same effect as calling setTextDirection(IFxTextConstants.tdTB_RL).

Remarks:

This method determines which locale handler is used for formatting, word-breaking, and other operations.

See Also: getLocale

setLocaleFormattingOverride

public void setLocaleFormattingOverride(boolean override);

Sets whether the locale will determine overriding features for text formatting. For example, if the locale is Japan, and the text direction is set to tdJapanTradNormal, pure vertical writing will not occur, but the punctuation will be moved, and so on.

Return Value:

No return value.

Parameter	Description
override	Set to true if the locale should determine the override features.

Remarks:

Currently, this method is not implemented.

See Also: getLocaleFormattingOverride

setMnemonicDrawing

public void setMnemonicDrawing(boolean mnem);

Sets whether the text displays underlines for hot key tracking.

Return Value:

No return value.

Parameter	Description
mnem	Set to true to enable mnemonic drawing.

See Also: getMnemonicDrawing

setOutline

public void setOutline(IFxShape outline);

Sets the outline that the text will wrap around.

Return Value:

No return value.

Parameter	Description
outline	The shape to use as the outline.

Remarks:

When a shape is used, the meanings of the parameters for the block change. The horizontal text alignment becomes the reference for where the text is located on the shape (left, center, and so on). The vertical text alignment becomes a reference for whether the text sits above, on, or below the shape. Opaquing has no effect when a shape is in use, as opaquing cannot be determined.

See Also: getOutline

setPasswordChar

public void setPasswordChar(char c);

Displays all characters using the same base character. One common use for this is to set the character echoed when password text is entered.

Return Value:

No return value.

Parameter	Description
c	The base character to use for all echoed text.

See Also: getPasswordChar

setStartPoint

public void setStartPoint(int x, int y);

Sets the start point of the text.

Return Value:

No return value.

Parameter	Description
x	The x coordinate of the start point.
y	The y coordinate of the start point.

Remarks:

If there is no bounding box associated with the text, this is the (x,y) position and the text will be drawn relative to the position using the alignment flags.

If there is a bounding box, the (x,y) position is used to set the start point within the bounding box, and the box is used for limiting the text. Although you can set the (x,y) point outside the bounding box, the start of the text will not be drawn.

See Also: setBounding, getBounding

setStartPoint

public void setStartPoint(Point p);

Sets the start point for the text, using a Point object instead of a specified (x,y) coordinate.

Return Value:

No return value.

Parameter	Description
p	The starting point for the text.

Remarks:

If no bounding box is associated with the text, the start point is the (x,y) screen position and the text will be drawn relative to the position according to the alignment flags.

If a bounding box exists, the (x,y) position sets the start point within the bounding box, and the box is used for limiting the text. Although you can set the (x,y) point outside the bounding box, the start of the text will not be drawn.

See Also: getBounding, setBounding

setStartPointAtOrigin

public void setStartPointAtOrigin();

Resets the current specified starting point when a bounding box is associated with text. The horizontal and vertical text alignment flags control where the point is reset. If no bounding box is associated with the buffer, an (x,y) point of (0,0) is set.

Return Value:

No return value.

setTabs

public void setTabs(int newTabs[]);

Sets the tabs for the FxFormattedText block.

Return Value:

No return value.

Parameter	Description
newTabs	An array of tab positions.

setText

public void setText(char newBuff[], int offset, int len);

Replaces the text in the buffer with that of a character array, starting at a specified offset.

Return Value:

No return value.

Parameter	Description
newBuff	A character array.
offset	The specified offset in newBuff.
len	The length of the character array.

Overrides:

setText(char[],int,int) in FxText.

setText

public void setText(char newBuff[]);

Replaces the text in the buffer with that of a character array.

Return Value:

No return value.

Parameter	Description
newBuff	A character array.

Overrides:

setText(char[]) in FxText.

setText

public void setText(String s);

Replaces the text in the buffer with the contents of a string.

Return Value:

No return value.

Parameter	Description
s	The string to place in the buffer.

Overrides:

setText(String) in FxText.

setTextDirection

public void setTextDirection(int dir);

Sets the text flow direction. The direction can be one of those shown in the following table.

tdLR_TB

tdTB_LR

tdTB_RL

tdLatinNormal

The direction can also be an angle value of 0 to 360 (where the angle value 0 represents "East" if you use a BorderLayout layout manager).

Return Value:

No return value.

Parameter	Description
dir	The direction that the text should flow.

setVertAlign

public void setVertAlign(int v);

Sets the vertical alignment for the text. This may be one of the alignments shown in the following table.

vtaCenter	vtaTop	vtaBottom
vtaBaseline	vtaStretch or	vtaScriptDefault

Return Value:

No return value.

Parameter	Description
v	The vertical alignment.

Remarks:

Some of the vertical and horizontal alignment values are script and locale dependant. Although all values are valid, the ensureNotDirty method may use default values (htaLeft and vtaTop) if the horizontal or vertical alignments are not appropriate for the current locale or script direction.

See Also: setHorizAlign

setWordWrap

public void setWordWrap(int ww);

Sets the word-wrapping functionality. This may be one of the following:

wwWrap

wwKeepWordIntact

wwVirtualRectEnd

wwVirtualRectSide

wwCleanEdges

Return Value:

No return value.

Parameter	Description
ww	The word-wrapping value to set.

shrinkBound

public Rectangle shrinkBound(boolean reset);

Shrinks the bounding rectangle to the minimum size that still contains all the text. If no text is currently in the bounding rectangle, the rectangle shrinks completely.

Return Value:

Returns the new bounding rectangle if reset is true.

Parameter	Description
reset	If true, the bounding rectangle of the object will reflect the change; otherwise, the result will be returned, but the bounding rectangle will not be updated.

Remarks:

The direction of shrinkage will depend on the text direction (for example, the upper left corner will not necessarily remain at (0,0)).