| java.lang.Object
 com.ibm.richtext.textformat.MFormatter
All known Subclasses: com.ibm.richtext.textformat.AsyncFormatter,
| MFormatter | | abstract public class MFormatter (Code) | | This class formats lines of text to a given length.
It provides services needed for static text display,
and also editable text, including: displaying text,
reformatting text after an edit, converting between
screen locations and offsets into the text, calculating
areas of the screen for "highlighting," and computing
offsets into the text resulting from arrow keys.
Text clients instantiate this class with an
MConstText object and a format width. Text
can be formatted such that all lines fit within the
format length. Alternatively, text can be formatted
such that lines end only at the end of paragraphs.
The format length is specified with the setLineBound()
method.
Methods in the formatter which interact with the graphics
system generally take as a paramter a Point object
which represents the "origin" of the text display. The
origin represents the location, in the graphics system used to display the text, of
the top-left corner of the text.
To display the text, call draw(), passing the
a rectangle in which to draw as a parameter. Only lines
of text in the draw rectangle will be drawn.
When the formatter's text changes, it is important to first call
stopBackgroundFormatting() to prevent the Formatter from
accessing the text from a background thread. After modifications are
complete,
call the updateFormat() method before invoking any other
methods of the formatter. updateFormat() reformats the
new text, formatting no more text than is necessary.
The formatter provides services for responding to user input from the
mouse and keyboard. The method pointToTextOffset() converts
a screen location to an offset in the text. The method textOffsetToPoint
converts an offset in the text to an array of two Point objects, which can be
used to draw a verticle caret, denoting an insertion point. highlightArea
accepts two offsets into the text as paramters, and returns an array of Polygon
objects representing areas where visual highlighting should be applied.
Finally, for
keyboard handling, the findNewInsertionOffset() method accepts an "initial"
offset, a "previous" offset, as well as a direction, and returns a new offset. The direction
can be up, down, left, or right. The previous offset is the insertion point location, before
the arrow key is processed. The initial offset is the offset where an up or down arrow
key sequence began. Using the initial offset allows for "intelligent" handling of up and down
arrow keys.
Examples of using the MFormatter class
are given in the AsyncFormatter class
documentation.
author:
John Raley
See Also: com.ibm.richtext.styledtext.MText |
| Method Summary | |
| public static MFormatter | createFormatter(MConstText text, AttributeMap defaultValues, int lineBound, boolean wrap, Graphics g)
Return a new MFormatter.
Parameters:
text - the text to format
Parameters:
defaultValues - values to use when certain attributes are not specified. | | abstract public void | draw(Graphics g, Rectangle drawArea, Point origin, TextOffset selStart, TextOffset selStop, Color highlight)
Display text in drawArea, with highlighting. | | abstract public void | draw(Graphics g, Rectangle drawArea, Point origin)
| | abstract public void | drawCaret(Graphics g, TextOffset offset, Point origin, Color strongCaretColor, Color weakCaretColor)
Draw the caret(s) associated with the given offset into the given Graphics. | | abstract public TextOffset | findInsertionOffset(TextOffset result, TextOffset previousOffset, short direction)
Compute the offset resulting from moving from a previous offset in direction dir. | | abstract public TextOffset | findNewInsertionOffset(TextOffset result, TextOffset initialOffset, TextOffset previousOffset, short direction)
Compute the offset resulting from moving from a previous offset, starting at an original offset, in direction dir.
For arrow keys. | | abstract public void | formatToHeight(int height)
Format text down to given height. | | abstract public int | formattedHeight()
Return the actual pixel length of the text which has been formatted. | | abstract public Rectangle | getBoundingRect(TextOffset offset1, TextOffset offset2, Point origin, boolean tight)
Given two offsets in the text, return a rectangle which encloses the lines containing the offsets.
Offsets do not need to be ordered or nonnegative.
Parameters:
offset1 - an offset into the text
Parameters:
offset2 - the other offset into the text
Parameters:
origin - the top-left corner of the text, in the display's coordinate system
Parameters:
tight - if equal to TIGHT, the bounds is as small as possible. | | abstract public void | getBoundingRect(Rectangle boundingRect, TextOffset offset1, TextOffset offset2, Point origin, boolean tight)
| | abstract public Rectangle | getCaretRect(TextOffset offset, Point origin)
Given an offset, return the Rectangle bounding the caret at the offset. | | abstract public AttributeMap | getDefaultValues()
| | abstract public int | getLineCount()
Return the number of lines. | | abstract public int | lineAtHeight(int height)
Return the line number at the given graphic height. | | abstract public int | lineBound()
Return the number of pixels along the line dimension. | | abstract public int | lineContaining(int index)
Return the index of the line containing the given character index.
This method has complicated semantics, arising from not knowing
which side of the index to check. | | abstract public int | lineContaining(TextOffset offset)
Return the index of the line containing the given offset. | | abstract public int | lineGraphicStart(int lineNumber)
Return the graphic height where the given line begins. | | abstract public boolean | lineIsLeftToRight(int lineNumber)
Return true if the given line is left-to-right. | | abstract public int | lineRangeLimit(int lineNumber)
Return the index of the first character following the given line. | | abstract public int | lineRangeLow(int lineNumber)
Return the index of the first character on the given line. | | abstract public int | maxX()
Return the maximum horizontal coordinate of the document area. | | abstract public int | maxY()
Return the maximum vertical coordinate of the document area. | | abstract public int | minX()
| | abstract public int | minY()
| | abstract public TextOffset | pointToTextOffset(TextOffset result, int px, int py, Point origin, TextOffset anchor, boolean infiniteMode)
Given a screen location p, return the offset of the character in the text nearest to p.
The offset may or may not include a newline at the end of a line, determined by anchor and infiniteMode.
The newline is not included if infiniteMode is true and the anchor is the position before the newline.
Parameters:
result - TextOffset to modify and return. | | abstract public void | setLineBound(int lineBound)
Specify the number of pixels along the "line dimension".
Lines are formatted to fit within the line dimension. | | abstract public void | setWrap(boolean wrap)
Specify whether to wrap line at the edge of the destination area. | | abstract public void | stopBackgroundFormatting()
Tells the formatter to stop accessing the text until updateFormat is called. | | abstract public Rectangle | updateFormat(int afStart, int afLength, Rectangle viewRect, Point origin)
Reformat text after a change.
After the formatter's text changes, call this method to reformat. | | abstract public boolean | wrap()
Return whether text is wrapped at the edge of the destination area. |
| eUpeDowneLefteRight | | final public static short eUpeDowneLefteRight(Code) | | |
| createFormatter | | public static MFormatter createFormatter(MConstText text, AttributeMap defaultValues, int lineBound, boolean wrap, Graphics g)(Code) | | Return a new MFormatter.
Parameters:
text - the text to format
Parameters:
defaultValues - values to use when certain attributes are not specified. defaultValues must contain values for the following attributes:FAMILY, WEIGHT, POSTURE, SIZE, SUPERSCRIPT, FOREGROUND, UNDERLINE, STRIKETHROUGH,EXTRA_LINE_SPACING, FIRST_LINE_INDENT,MIN_LINE_SPACING,LINE_FLUSH, LEADING_MARGIN, TRAILING_MARGIN, TAB_RULER
Parameters:
lineBound - length to which lines are formatted
Parameters:
wrap - true if text should be "line wrapped" (formatted to fit destination area) |
| draw | | abstract public void draw(Graphics g, Rectangle drawArea, Point origin, TextOffset selStart, TextOffset selStop, Color highlight)(Code) | | Display text in drawArea, with highlighting.
Does not reformat text
Parameters:
g - the Graphics object in which to draw
Parameters:
drawArea - the rectangle, in g's coordinate system, in which to draw
Parameters:
origin - the top-left corner of the text, in g's coordinate system
Parameters:
selStart - the offset where the current selection begins; pass null if no selection
Parameters:
selStop - the offset where the current selection ends
Parameters:
highlight - the color of the highlighting |
| drawCaret | | abstract public void drawCaret(Graphics g, TextOffset offset, Point origin, Color strongCaretColor, Color weakCaretColor)(Code) | | Draw the caret(s) associated with the given offset into the given Graphics.
Parameters:
g - the Graphics to draw into
Parameters:
offset - the offset in the text for which the caret is drawn
Parameters:
origin - the top-left corner of the text, in the display's coordinate system
Parameters:
strongCaretColor - the color of the strong caret
Parameters:
weakCaretColor - the color of the weak caret (if any) |
| findInsertionOffset | | abstract public TextOffset findInsertionOffset(TextOffset result, TextOffset previousOffset, short direction)(Code) | | Compute the offset resulting from moving from a previous offset in direction dir.
For arrow keys.
Parameters:
previousOffset - the insertion offset prior to the arrow key press
Parameters:
direction - the direction of the arrow key (eUp, eDown, eLeft, or eRight) new offset based on direction and previous offset. |
| findNewInsertionOffset | | abstract public TextOffset findNewInsertionOffset(TextOffset result, TextOffset initialOffset, TextOffset previousOffset, short direction)(Code) | | Compute the offset resulting from moving from a previous offset, starting at an original offset, in direction dir.
For arrow keys. Use this for "smart" up/down keys.
Parameters:
result - TextOffset to modify and return. If null, a new TextOffset is created, modified, and returned.
Parameters:
initialOffset - The offset at which an up-down arrow key sequence began.
Parameters:
previousOffset - The insertion offset prior to the arrow key press.
Parameters:
direction - The direction of the arrow key (eUp, eDown, eLeft, or eRight) new offset based on direction and previous offset(s). |
| formatToHeight | | abstract public void formatToHeight(int height)(Code) | | Format text down to given height.
Parameters:
height - the height to which text will be formatted |
| formattedHeight | | abstract public int formattedHeight()(Code) | | Return the actual pixel length of the text which has been formatted.
|
| getBoundingRect | | abstract public Rectangle getBoundingRect(TextOffset offset1, TextOffset offset2, Point origin, boolean tight)(Code) | | Given two offsets in the text, return a rectangle which encloses the lines containing the offsets.
Offsets do not need to be ordered or nonnegative.
Parameters:
offset1 - an offset into the text
Parameters:
offset2 - the other offset into the text
Parameters:
origin - the top-left corner of the text, in the display's coordinate system
Parameters:
tight - if equal to TIGHT, the bounds is as small as possible. If LOOSE, the widthof the bounds is allowed to be wider than necesary. Loose bounds are easier to compute. a Rectangle, relative to origin, which encloses the lines containing the offsets |
| getCaretRect | | abstract public Rectangle getCaretRect(TextOffset offset, Point origin)(Code) | | Given an offset, return the Rectangle bounding the caret at the offset.
Parameters:
offset - an offset into the text
Parameters:
origin - the top-left corner of the text, in the display's coordinate system a Rectangle bounding the caret. |
| getLineCount | | abstract public int getLineCount()(Code) | | Return the number of lines.
|
| lineAtHeight | | abstract public int lineAtHeight(int height)(Code) | | Return the line number at the given graphic height. If height is greater than
the text height, maxLineNumber + 1 is returned.
|
| lineBound | | abstract public int lineBound()(Code) | | Return the number of pixels along the line dimension.
the number of pixels along the line dimension. |
| lineContaining | | abstract public int lineContaining(int index)(Code) | | Return the index of the line containing the given character index.
This method has complicated semantics, arising from not knowing
which side of the index to check. The index will be given an
implicit AFTER bias, unless the index is the last index in the text,
the text length is non-zero, and there is not a paragraph separator
at the end of the text.
|
| lineContaining | | abstract public int lineContaining(TextOffset offset)(Code) | | Return the index of the line containing the given offset.
|
| lineGraphicStart | | abstract public int lineGraphicStart(int lineNumber)(Code) | | Return the graphic height where the given line begins. If the lineNumber is
maxLineNumber the entire text height is returned.
|
| lineIsLeftToRight | | abstract public boolean lineIsLeftToRight(int lineNumber)(Code) | | Return true if the given line is left-to-right.
Parameters:
lineNumber - a valid line true if lineNumber is left-to-right |
| lineRangeLimit | | abstract public int lineRangeLimit(int lineNumber)(Code) | | Return the index of the first character following the given line.
|
| lineRangeLow | | abstract public int lineRangeLow(int lineNumber)(Code) | | Return the index of the first character on the given line.
|
| maxX | | abstract public int maxX()(Code) | | Return the maximum horizontal coordinate of the document area.
|
| maxY | | abstract public int maxY()(Code) | | Return the maximum vertical coordinate of the document area.
|
| minX | | abstract public int minX()(Code) | | |
| minY | | abstract public int minY()(Code) | | |
| pointToTextOffset | | abstract public TextOffset pointToTextOffset(TextOffset result, int px, int py, Point origin, TextOffset anchor, boolean infiniteMode)(Code) | | Given a screen location p, return the offset of the character in the text nearest to p.
The offset may or may not include a newline at the end of a line, determined by anchor and infiniteMode.
The newline is not included if infiniteMode is true and the anchor is the position before the newline.
Parameters:
result - TextOffset to modify and return. If null, one will be allocated, modified, and returned.
Parameters:
px - the x component of the point.
Parameters:
py - the y component of the point.
Parameters:
origin - the top-left corner of the text, in the display's coordinate system
Parameters:
anchor - the previous offset. May be null. Used to determine whether newlines are included.
Parameters:
infiniteMode - if true, treat newlines at end of line as having infinite width. |
| setLineBound | | abstract public void setLineBound(int lineBound)(Code) | | Specify the number of pixels along the "line dimension".
Lines are formatted to fit within the line dimension. The
line dimension in Roman script is horizontal.
Parameters:
lineBound - the length, in pixels, to which lines will be formatted |
| setWrap | | abstract public void setWrap(boolean wrap)(Code) | | Specify whether to wrap line at the edge of the destination area.
true means wrap lines; false means to break lines
only when an end-of-line character is reached.
Parameters:
wrap - true to break lines at the edge of the destinationarea; false otherwise. |
| stopBackgroundFormatting | | abstract public void stopBackgroundFormatting()(Code) | | Tells the formatter to stop accessing the text until updateFormat is called.
|
| updateFormat | | abstract public Rectangle updateFormat(int afStart, int afLength, Rectangle viewRect, Point origin)(Code) | | Reformat text after a change.
After the formatter's text changes, call this method to reformat. Does
not redraw.
Parameters:
afStart - the offset into the text where modification began; ie, thefirst character in the text which is "different" in some way. Does nothave to be nonnegative.
Parameters:
afLength - the number of new or changed characters in the text. Should neverbe less than 0.
Parameters:
viewRect - the Rectangle in which the text will be displayed. This is needed forreturning the "damaged" area - the area of the screen in which the text must be redrawn.
Parameters:
origin - the top-left corner of the text, in the display's coordinate system a Rectangle which specifies the area in which text must beredrawn to reflect the change to the text. |
| wrap | | abstract public boolean wrap()(Code) | | Return whether text is wrapped at the edge of the destination area.
See Also: MFormatter.setWrap |
|
|