com.ibm.richtext.textpanel
Interface MTextPanel

All Known Implementing Classes:
JTextPanel, TextPanel

public interface MTextPanel

MTextPanel is implemented by Components which provide selectable editable styled text.

Implementations of MTextPanel provide a simple, standard user interface for text editing. MTextPanel supplies scrollable display, typing, arrow-key support, character selection, word- and sentence-selection (by double-clicking and triple-clicking, respectively), text styles, clipboard operations (cut, copy and paste) and a log of changes for undo-redo.

MTextPanel implementations do not provide user interface elements such as an edit menu or style menu. This support is provided in different packages, and is implemented with MTextPanel's API. MTextPanel includes methods for setting selections and styles on text, and using the clipboard and command-log functionality. MTextPanel's API for selection and text handling is similar to that of java.awt.TextArea and java.awt.TextComponent.

MTextPanel supports bidirectional and complex text. In bidirectional text, offsets at direction boundaries have dual carets. Logical selection is used, so selections across run directions may not be contiguous in display.


Field Summary
static java.lang.String COPYRIGHT
           
static java.lang.Object MULTIPLE_VALUES
          This value is returned from getCharacterStyleOverSelection and getParagraphStyleOverSelection to indicate that the selection range contains multiple values for a key.
 
Method Summary
 void addListener(TextPanelListener listener)
          Add the given TextPanelListener to the listeners which will receive update notifications from this MTextPanel.
 void append(MConstText newText)
          Append the given text to the end of the document.
 boolean canRedo()
          Return true if there is a change which can be redone.
 boolean canUndo()
          Return true if there is a change which can be undone.
 void clear()
          Remove selected text from the document, without altering the clipboard.
 void clearCommandLog()
          Remove all commands from the command log.
 boolean clipboardNotEmpty()
          Return true if the clipboard contains contents which could be transfered into the text.
 void copy()
          Place the selected text on the clipboard.
 void cut()
          Remove the selected text from the document and place it on the clipboard.
 java.lang.Object getCharacterStyleOverSelection(java.lang.Object key)
          This method inspects the character style runs in the selection range (or the typing style at the insertion point).
 int getCommandLogSize()
          Return the number of commands the command log can hold.
 AttributeMap getDefaultValues()
          Return an AttributeMap of keys with default values.
 int getFormatWidth()
          Return the total format width, in pixels.
 KeyRemap getKeyRemap()
          Return the KeyRemap used to process key events.
 java.lang.Object getParagraphStyleOverSelection(java.lang.Object key)
          This method inspects the paragraph style runs in the selection range (or the typing style at the insertion point).
 int getSelectionEnd()
          Return the offset of the end of the selection.
 int getSelectionStart()
          Return the offset of the start of the selection.
 MConstText getText()
          Return the text document in the MTextPanel.
 int getTextLength()
          Return the length of the text document in the MTextPanel.
 void insert(MConstText newText, int position)
          Insert the given text into the document at the given position.
 boolean isModified()
          Return the modification flag of the current text change.
 void modifyCharacterStyleOnSelection(StyleModifier modifier)
          Modify the character styles on the selected characters.
 void modifyParagraphStyleOnSelection(StyleModifier modifier)
          Modify the paragraph styles in paragraphs containing selected characters, or the paragraph containing the insertion point.
 boolean paragraphIsLeftToRight(int offset)
          Return true if the paragraph at the given offset is left-to-right.
 void paste()
          Replace the currently selected text with the text on the clipboard.
 void redo()
          Redo the most recent text change.
 void removeListener(TextPanelListener listener)
          Remove the given TextPanelListener from the listeners which will receive update notifications from this MTextPanel.
 void replaceRange(MConstText newText, int start, int end)
          Replace the given range with newText.
 void select(int selectionStart, int selectionEnd)
          Set the selection range to the given range.
 void selectAll()
          Select all of the text in the document.
 void setCaretPosition(int position)
          Set the selection range to an insertion point at the given offset.
 void setCommandLogSize(int size)
          Set the number of commands the command log can hold.
 void setKeyRemap(KeyRemap remap)
          Use the given KeyRemap to map key events to characters.
 void setModified(boolean modified)
          Set the modification flag of the current text change.
 void setSelectionEnd(int selectionEnd)
          Set the end of the selection range.
 void setSelectionStart(int selectionStart)
          Set the beginning of the selection range.
 void setText(MConstText newText)
          Set the document to newText.
 void undo()
          Undo the most recent text change.
 

Field Detail

COPYRIGHT

public static final java.lang.String COPYRIGHT

MULTIPLE_VALUES

public static final java.lang.Object MULTIPLE_VALUES
This value is returned from getCharacterStyleOverSelection and getParagraphStyleOverSelection to indicate that the selection range contains multiple values for a key.

There is no reason for this Object ever to appear in an AttributeMap as a value. Obviously, if it does there will be no way to distinguish between multiple values across the selection and a consistent value of MULTIPLE_VALUES for the key.

See Also:
getCharacterStyleOverSelection(java.lang.Object), getParagraphStyleOverSelection(java.lang.Object)
Method Detail

addListener

public void addListener(TextPanelListener listener)
Add the given TextPanelListener to the listeners which will receive update notifications from this MTextPanel.
Parameters:
listener - the listener to add

removeListener

public void removeListener(TextPanelListener listener)
Remove the given TextPanelListener from the listeners which will receive update notifications from this MTextPanel.
Parameters:
listener - the listener to remove

setText

public void setText(MConstText newText)
Set the document to newText. This operation modifies the text in the MTextPanel. It does not modify or adopt newText. This method sets the selection an insertion point at the end of the text.
Parameters:
newText - the text which will replace the current text.

append

public void append(MConstText newText)
Append the given text to the end of the document. Equivalent to insert(newText, getTextLength()).
Parameters:
newText - the text to append to the document

insert

public void insert(MConstText newText,
                   int position)
Insert the given text into the document at the given position. Equivalent to replaceRange(newText, position, position).
Parameters:
newText - the text to insert into the document.
position - the position in the document where the text will be inserted

replaceRange

public void replaceRange(MConstText newText,
                         int start,
                         int end)
Replace the given range with newText. After this operation the selection range is an insertion point at the end of the new text.
Parameters:
newText - the text with which to replace the range
start - the beginning of the range to replace
end - the end of the range to replace

getTextLength

public int getTextLength()
Return the length of the text document in the MTextPanel.
Returns:
the length of the text document in the MTextPanel

getText

public MConstText getText()
Return the text document in the MTextPanel.
Returns:
the text document in the MTextPanel.

getSelectionStart

public int getSelectionStart()
Return the offset of the start of the selection.

getSelectionEnd

public int getSelectionEnd()
Return the offset of the end of the selection.

setSelectionStart

public void setSelectionStart(int selectionStart)
Set the beginning of the selection range. This is equivalent to select(selectionStart, getSelectionEnd()).
Parameters:
selectionStart - the start of the new selection range

setSelectionEnd

public void setSelectionEnd(int selectionEnd)
Set the end of the selection range. This is equivalent to select(getSelectionStart(), selectionEnd).
Parameters:
selectionStart - the start of the new selection range

setCaretPosition

public void setCaretPosition(int position)
Set the selection range to an insertion point at the given offset. This is equivalent to select(position, position).
Parameters:
position - the offset of the new insertion point

select

public void select(int selectionStart,
                   int selectionEnd)
Set the selection range to the given range. The range start is pinned between 0 and the text length; the range end is pinned between the range start and the end of the text. These semantics are identical to those of java.awt.TextComponent. This method has no effect if the text is not selectable.
Parameters:
selectionStart - the beginning of the selection range
selectionEnd - the end of the selection range

selectAll

public void selectAll()
Select all of the text in the document. This method has no effect if the text is not selectable.

getFormatWidth

public int getFormatWidth()
Return the total format width, in pixels. The format width is the width to which text is wrapped.
Returns:
the format width

paragraphIsLeftToRight

public boolean paragraphIsLeftToRight(int offset)
Return true if the paragraph at the given offset is left-to-right.
Parameters:
offset - an offset in the text
Returns:
true if the paragraph at the given offset is left-to-right

canUndo

public boolean canUndo()
Return true if there is a change which can be undone.
Returns:
true if there is a change which can be undone.

canRedo

public boolean canRedo()
Return true if there is a change which can be redone.
Returns:
true if there is a change which can be redone.

clipboardNotEmpty

public boolean clipboardNotEmpty()
Return true if the clipboard contains contents which could be transfered into the text.
Returns:
true if the clipboard has text content.

getDefaultValues

public AttributeMap getDefaultValues()
Return an AttributeMap of keys with default values. The default values are used when displaying text for values which are not specified in the text.
Returns:
an AttributeMap of default key-value pairs

getCharacterStyleOverSelection

public java.lang.Object getCharacterStyleOverSelection(java.lang.Object key)
This method inspects the character style runs in the selection range (or the typing style at the insertion point). It returns: If a style run does not contain key, its value is considered to be the default style for key, as defined by the default values AttributeMap. Note that if key does not have a default value this method may return null. This method is useful for configuring style menus.
Parameters:
key - the key used to retrieve values for comparison
See Also:
MULTIPLE_VALUES

getParagraphStyleOverSelection

public java.lang.Object getParagraphStyleOverSelection(java.lang.Object key)
This method inspects the paragraph style runs in the selection range (or the typing style at the insertion point). It returns: If a style run does not contain key, its value is considered to be the default style for key, as defined by the default values AttributeMap. Note that if key does not have a default value this method may return null. This method is useful for configuring style menus.
Parameters:
key - the key used to retrieve values for comparison
See Also:
MULTIPLE_VALUES

cut

public void cut()
Remove the selected text from the document and place it on the clipboard. This method has no effect if the text is not editable, or if no text is selected.

copy

public void copy()
Place the selected text on the clipboard. This method has no effect if no text is selected.

paste

public void paste()
Replace the currently selected text with the text on the clipboard. This method has no effect if the text is not editable, or if no text is on the clipboard.

clear

public void clear()
Remove selected text from the document, without altering the clipboard. This method has no effect if the text is not editable.

undo

public void undo()
Undo the most recent text change. This method has no effect if there is no change to undo.

redo

public void redo()
Redo the most recent text change. This method has no effect if there is no change to redo.

getCommandLogSize

public int getCommandLogSize()
Return the number of commands the command log can hold.
Returns:
the number of commands the command log can hold

setCommandLogSize

public void setCommandLogSize(int size)
Set the number of commands the command log can hold. All redoable commands are removed when this method is called.
Parameters:
size - the number of commands kept in the command log

clearCommandLog

public void clearCommandLog()
Remove all commands from the command log.

modifyCharacterStyleOnSelection

public void modifyCharacterStyleOnSelection(StyleModifier modifier)
Modify the character styles on the selected characters. If no characters are selected, modify the typing style.
Parameters:
modifier - the StyleModifier with which to modify the styles

modifyParagraphStyleOnSelection

public void modifyParagraphStyleOnSelection(StyleModifier modifier)
Modify the paragraph styles in paragraphs containing selected characters, or the paragraph containing the insertion point.
Parameters:
modifier - the StyleModifier with which to modify the styles

getKeyRemap

public KeyRemap getKeyRemap()
Return the KeyRemap used to process key events.
Returns:
the key remap used to process key events
See Also:
setKeyRemap(com.ibm.richtext.textpanel.KeyRemap)

setKeyRemap

public void setKeyRemap(KeyRemap remap)
Use the given KeyRemap to map key events to characters. Only key events are affected by the remap; other text entering the control (via the clipboard, for example) is not affected by the KeyRemap.

Do not pass null to this method to leave key events unmapped. Instead, use KeyRemap.getIdentityRemap()

Parameters:
remap - the KeyRemap to use for mapping key events to characters
Throws:
java.lang.NullPointerException - if parameter is null
See Also:
KeyRemap

isModified

public boolean isModified()
Return the modification flag of the current text change.
See Also:
setModified(boolean)

setModified

public void setModified(boolean modified)
Set the modification flag of the current text change.


Copyright (c) 2001 IBM Corporation and others.