com.ibm.richtext.textformat
Class MFormatter

java.lang.Object
  |
  +--com.ibm.richtext.textformat.MFormatter

public abstract class MFormatter
extends java.lang.Object

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:
MText

Field Summary
static short eDown
           
static short eLeft
           
static short eRight
           
static short eUp
           
static boolean LOOSE
           
static boolean TIGHT
           
 
Constructor Summary
MFormatter()
           
 
Method Summary
static MFormatter createFormatter(MConstText text, AttributeMap defaultValues, int lineBound, boolean wrap, java.awt.Graphics g)
          Return a new MFormatter.
abstract  void draw(java.awt.Graphics g, java.awt.Rectangle drawArea, java.awt.Point origin)
           
abstract  void draw(java.awt.Graphics g, java.awt.Rectangle drawArea, java.awt.Point origin, TextOffset selStart, TextOffset selStop, java.awt.Color highlight)
          Display text in drawArea, with highlighting.
abstract  void drawCaret(java.awt.Graphics g, TextOffset offset, java.awt.Point origin, java.awt.Color strongCaretColor, java.awt.Color weakCaretColor)
          Draw the caret(s) associated with the given offset into the given Graphics.
abstract  TextOffset findInsertionOffset(TextOffset result, TextOffset previousOffset, short direction)
          Compute the offset resulting from moving from a previous offset in direction dir.
abstract  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.
abstract  int formattedHeight()
          Return the actual pixel length of the text which has been formatted.
abstract  void formatToHeight(int height)
          Format text down to given height.
abstract  void getBoundingRect(java.awt.Rectangle boundingRect, TextOffset offset1, TextOffset offset2, java.awt.Point origin, boolean tight)
           
abstract  java.awt.Rectangle getBoundingRect(TextOffset offset1, TextOffset offset2, java.awt.Point origin, boolean tight)
          Given two offsets in the text, return a rectangle which encloses the lines containing the offsets.
abstract  java.awt.Rectangle getCaretRect(TextOffset offset, java.awt.Point origin)
          Given an offset, return the Rectangle bounding the caret at the offset.
abstract  AttributeMap getDefaultValues()
           
abstract  int getLineCount()
          Return the number of lines.
abstract  int lineAtHeight(int height)
          Return the line number at the given graphic height.
abstract  int lineBound()
          Return the number of pixels along the line dimension.
abstract  int lineContaining(int index)
          Return the index of the line containing the given character index.
abstract  int lineContaining(TextOffset offset)
          Return the index of the line containing the given offset.
abstract  int lineGraphicStart(int lineNumber)
          Return the graphic height where the given line begins.
abstract  boolean lineIsLeftToRight(int lineNumber)
          Return true if the given line is left-to-right.
abstract  int lineRangeLimit(int lineNumber)
          Return the index of the first character following the given line.
abstract  int lineRangeLow(int lineNumber)
          Return the index of the first character on the given line.
abstract  int maxX()
          Return the maximum horizontal coordinate of the document area.
abstract  int maxY()
          Return the maximum vertical coordinate of the document area.
abstract  int minX()
           
abstract  int minY()
           
abstract  TextOffset pointToTextOffset(TextOffset result, int px, int py, java.awt.Point origin, TextOffset anchor, boolean infiniteMode)
          Given a screen location p, return the offset of the character in the text nearest to p.
abstract  void setLineBound(int lineBound)
          Specify the number of pixels along the "line dimension".
abstract  void setWrap(boolean wrap)
          Specify whether to wrap line at the edge of the destination area.
abstract  void stopBackgroundFormatting()
          Tells the formatter to stop accessing the text until updateFormat is called.
abstract  java.awt.Rectangle updateFormat(int afStart, int afLength, java.awt.Rectangle viewRect, java.awt.Point origin)
          Reformat text after a change.
abstract  boolean wrap()
          Return whether text is wrapped at the edge of the destination area.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

eUp

public static final short eUp

eDown

public static final short eDown

eLeft

public static final short eLeft

eRight

public static final short eRight

LOOSE

public static final boolean LOOSE
See Also:
getBoundingRect(com.ibm.richtext.textformat.TextOffset, com.ibm.richtext.textformat.TextOffset, java.awt.Point, boolean)

TIGHT

public static final boolean TIGHT
See Also:
getBoundingRect(com.ibm.richtext.textformat.TextOffset, com.ibm.richtext.textformat.TextOffset, java.awt.Point, boolean)
Constructor Detail

MFormatter

public MFormatter()
Method Detail

getDefaultValues

public abstract AttributeMap getDefaultValues()

draw

public abstract void draw(java.awt.Graphics g,
                          java.awt.Rectangle drawArea,
                          java.awt.Point origin,
                          TextOffset selStart,
                          TextOffset selStop,
                          java.awt.Color highlight)
Display text in drawArea, with highlighting. Does not reformat text
Parameters:
g - the Graphics object in which to draw
drawArea - the rectangle, in g's coordinate system, in which to draw
origin - the top-left corner of the text, in g's coordinate system
selStart - the offset where the current selection begins; pass null if no selection
selStop - the offset where the current selection ends
highlight - the color of the highlighting

draw

public abstract void draw(java.awt.Graphics g,
                          java.awt.Rectangle drawArea,
                          java.awt.Point origin)

setWrap

public abstract void setWrap(boolean wrap)
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 destination area; false otherwise.

wrap

public abstract boolean wrap()
Return whether text is wrapped at the edge of the destination area.
See Also:
setWrap(boolean)

setLineBound

public abstract void setLineBound(int lineBound)
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:
lineWidth - the length, in pixels, to which lines will be formatted

lineBound

public abstract int lineBound()
Return the number of pixels along the line dimension.

formatToHeight

public abstract void formatToHeight(int height)
Format text down to given height.
Parameters:
height - the height to which text will be formatted

updateFormat

public abstract java.awt.Rectangle updateFormat(int afStart,
                                                int afLength,
                                                java.awt.Rectangle viewRect,
                                                java.awt.Point origin)
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, the first character in the text which is "different" in some way. Does not have to be nonnegative.
afLength - the number of new or changed characters in the text. Should never be less than 0.
viewRect - the Rectangle in which the text will be displayed. This is needed for returning the "damaged" area - the area of the screen in which the text must be redrawn.
origin - the top-left corner of the text, in the display's coordinate system
Returns:
a Rectangle which specifies the area in which text must be redrawn to reflect the change to the text.

minY

public abstract int minY()

maxY

public abstract int maxY()
Return the maximum vertical coordinate of the document area.

minX

public abstract int minX()

maxX

public abstract int maxX()
Return the maximum horizontal coordinate of the document area.

formattedHeight

public abstract int formattedHeight()
Return the actual pixel length of the text which has been formatted.

pointToTextOffset

public abstract TextOffset pointToTextOffset(TextOffset result,
                                             int px,
                                             int py,
                                             java.awt.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. If null, one will be allocated, modified, and returned.
px - the x component of the point.
py - the y component of the point.
origin - the top-left corner of the text, in the display's coordinate system
anchor - the previous offset. May be null. Used to determine whether newlines are included.
infiniteMode - if true, treat newlines at end of line as having infinite width.

getCaretRect

public abstract java.awt.Rectangle getCaretRect(TextOffset offset,
                                                java.awt.Point origin)
Given an offset, return the Rectangle bounding the caret at the offset.
Parameters:
offset - an offset into the text
origin - the top-left corner of the text, in the display's coordinate system
Returns:
a Rectangle bounding the caret.

drawCaret

public abstract void drawCaret(java.awt.Graphics g,
                               TextOffset offset,
                               java.awt.Point origin,
                               java.awt.Color strongCaretColor,
                               java.awt.Color weakCaretColor)
Draw the caret(s) associated with the given offset into the given Graphics.
Parameters:
g - the Graphics to draw into
offset - the offset in the text for which the caret is drawn
origin - the top-left corner of the text, in the display's coordinate system
strongCaretColor - the color of the strong caret
weakCaretColor - the color of the weak caret (if any)

getBoundingRect

public abstract java.awt.Rectangle getBoundingRect(TextOffset offset1,
                                                   TextOffset offset2,
                                                   java.awt.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,offset2 - offsets into the text
origin - the top-left corner of the text, in the display's coordinate system
tight - if equal to TIGHT, the bounds is as small as possible. If LOOSE, the width of the bounds is allowed to be wider than necesary. Loose bounds are easier to compute.
Returns:
a Rectangle, relative to origin, which encloses the lines containing the offsets

getBoundingRect

public abstract void getBoundingRect(java.awt.Rectangle boundingRect,
                                     TextOffset offset1,
                                     TextOffset offset2,
                                     java.awt.Point origin,
                                     boolean tight)

findInsertionOffset

public abstract TextOffset findInsertionOffset(TextOffset result,
                                               TextOffset previousOffset,
                                               short direction)
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
direction - the direction of the arrow key (eUp, eDown, eLeft, or eRight)
Returns:
new offset based on direction and previous offset.

findNewInsertionOffset

public abstract 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. Use this for "smart" up/down keys.
Parameters:
result - TextOffset to modify and return. If null, a new TextOffset is created, modified, and returned.
initialOffset - The offset at which an up-down arrow key sequence began.
previousOffset - The insertion offset prior to the arrow key press.
direction - The direction of the arrow key (eUp, eDown, eLeft, or eRight)
Returns:
new offset based on direction and previous offset(s).

lineContaining

public abstract 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. 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

public abstract int lineContaining(TextOffset offset)
Return the index of the line containing the given offset.

getLineCount

public abstract int getLineCount()
Return the number of lines.

lineRangeLow

public abstract int lineRangeLow(int lineNumber)
Return the index of the first character on the given line.

lineRangeLimit

public abstract int lineRangeLimit(int lineNumber)
Return the index of the first character following the given line.

stopBackgroundFormatting

public abstract void stopBackgroundFormatting()
Tells the formatter to stop accessing the text until updateFormat is called.

lineAtHeight

public abstract int lineAtHeight(int height)
Return the line number at the given graphic height. If height is greater than the text height, maxLineNumber + 1 is returned.

lineGraphicStart

public abstract int lineGraphicStart(int lineNumber)
Return the graphic height where the given line begins. If the lineNumber is maxLineNumber the entire text height is returned.

lineIsLeftToRight

public abstract boolean lineIsLeftToRight(int lineNumber)
Return true if the given line is left-to-right.
Parameters:
lineNumber - a valid line
Returns:
true if lineNumber is left-to-right

createFormatter

public static MFormatter createFormatter(MConstText text,
                                         AttributeMap defaultValues,
                                         int lineBound,
                                         boolean wrap,
                                         java.awt.Graphics g)
Return a new MFormatter.
Parameters:
text - the text to format
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
lineBound - length to which lines are formatted
wrap - true if text should be "line wrapped" (formatted to fit destination area)


Copyright (c) 2001 IBM Corporation and others.