001: /*
002: * (C) Copyright IBM Corp. 1998-2004. All Rights Reserved.
003: *
004: * The program is provided "as is" without any warranty express or
005: * implied, including the warranty of non-infringement and the implied
006: * warranties of merchantibility and fitness for a particular purpose.
007: * IBM will not be liable for any damages suffered by you as a result
008: * of using the Program. In no event will IBM be liable for any
009: * special, indirect or consequential damages or lost profits even if
010: * IBM has been advised of the possibility of their occurrence. IBM
011: * will not be liable for any third party claims against you.
012: */
013: package com.ibm.richtext.textpanel;
014:
015: import com.ibm.richtext.textlayout.attributes.AttributeMap;
016:
017: import com.ibm.richtext.styledtext.StyleModifier;
018: import com.ibm.richtext.styledtext.MConstText;
019:
020: /**
021: * MTextPanel is implemented by Components which provide selectable
022: * editable styled text.
023: * <p>
024: * Implementations of MTextPanel provide a simple, standard user interface
025: * for text editing. MTextPanel supplies scrollable display, typing,
026: * arrow-key support, character selection, word-
027: * and sentence-selection (by double-clicking and triple-clicking,
028: * respectively), text styles, clipboard operations (cut, copy and paste)
029: * and a log of changes for undo-redo.
030: * <p>
031: * MTextPanel implementations do not provide user interface elements
032: * such as an edit menu or style menu. This support is provided in
033: * different packages, and is implemented with MTextPanel's API.
034: * MTextPanel includes methods for setting selections and styles on text,
035: * and using the clipboard and command-log functionality.
036: * MTextPanel's API for selection and text handling is similar to that
037: * of <tt>java.awt.TextArea</tt> and
038: * <tt>java.awt.TextComponent</tt>.
039: * <p>
040: * MTextPanel supports bidirectional and complex text. In bidirectional
041: * text, offsets at direction boundaries have dual carets. Logical selection
042: * is used, so selections across run directions may not be contiguous in
043: * display.
044: */
045: public interface MTextPanel {
046:
047: static final String COPYRIGHT = "(C) Copyright IBM Corp. 1998-1999 - All Rights Reserved";
048:
049: /**
050: * This value is returned from <tt>getCharacterStyleOverSelection</tt>
051: * and <tt>getParagraphStyleOverSelection</tt> to indicate that the
052: * selection range contains multiple values for a key.
053: * <p>
054: * There is no reason for this Object ever to appear in an AttributeMap
055: * as a value. Obviously, if it does there will be no way to distinguish
056: * between multiple values across the selection and a consistent value of
057: * <tt>MULTIPLE_VALUES</tt> for the key.
058: * @see #getCharacterStyleOverSelection
059: * @see #getParagraphStyleOverSelection
060: */
061: public static final Object MULTIPLE_VALUES = new Object();
062:
063: /**
064: * Add the given TextPanelListener to the listeners which will
065: * receive update notifications from this MTextPanel.
066: * @param listener the listener to add
067: */
068: public void addListener(TextPanelListener listener);
069:
070: /**
071: * Remove the given TextPanelListener from the listeners which will
072: * receive update notifications from this MTextPanel.
073: * @param listener the listener to remove
074: */
075: public void removeListener(TextPanelListener listener);
076:
077: /**
078: * Set the document to <tt>newText</tt>. This operation
079: * modifies the text in the MTextPanel. It does not modify or adopt
080: * <tt>newText</tt>. This method sets the selection an insertion point at
081: * the end of the text.
082: * @param newText the text which will replace the current text.
083: */
084: public void setText(MConstText newText);
085:
086: /**
087: * Append the given text to the end of the document. Equivalent to
088: * <tt>insert(newText, getTextLength())</tt>.
089: * @param newText the text to append to the document
090: */
091: public void append(MConstText newText);
092:
093: /**
094: * Insert the given text into the document at the given position.
095: * Equivalent to
096: * <tt>replaceRange(newText, position, position)</tt>.
097: * @param newText the text to insert into the document.
098: * @param position the position in the document where the
099: * text will be inserted
100: */
101: public void insert(MConstText newText, int position);
102:
103: /**
104: * Replace the given range with <tt>newText</tt>. After this
105: * operation the selection range is an insertion point at the
106: * end of the new text.
107: * @param newText the text with which to replace the range
108: * @param start the beginning of the range to replace
109: * @param end the end of the range to replace
110: */
111: public void replaceRange(MConstText newText, int start, int end);
112:
113: /**
114: * Return the length of the text document in the MTextPanel.
115: * @return the length of the text document in the MTextPanel
116: */
117: public int getTextLength();
118:
119: /**
120: * Return the text document in the MTextPanel.
121: * @return the text document in the MTextPanel.
122: */
123: public MConstText getText();
124:
125: //============
126: // Selection Access
127: //============
128:
129: /**
130: * Return the offset of the start of the selection.
131: */
132: public int getSelectionStart();
133:
134: /**
135: * Return the offset of the end of the selection.
136: */
137: public int getSelectionEnd();
138:
139: /**
140: * Set the beginning of the selection range. This is
141: * equivalent to <tt>select(selectionStart, getSelectionEnd())</tt>.
142: * @param selectionStart the start of the new selection range
143: */
144: public void setSelectionStart(int selectionStart);
145:
146: /**
147: * Set the end of the selection range. This is
148: * equivalent to <tt>select(getSelectionStart(), selectionEnd)</tt>.
149: * @param selectionEnd the end of the new selection range
150: */
151: public void setSelectionEnd(int selectionEnd);
152:
153: /**
154: * Set the selection range to an insertion point at the given
155: * offset. This is equivalent to
156: * <tt>select(position, position)</tt>.
157: * @param position the offset of the new insertion point
158: */
159: public void setCaretPosition(int position);
160:
161: /**
162: * Set the selection range to the given range. The range start
163: * is pinned between 0 and the text length; the range end is pinned
164: * between the range start and the end of the text. These semantics
165: * are identical to those of <tt>java.awt.TextComponent</tt>.
166: * This method has no effect if the text is not selectable.
167: * @param selectionStart the beginning of the selection range
168: * @param selectionEnd the end of the selection range
169: */
170: public void select(int selectionStart, int selectionEnd);
171:
172: /**
173: * Select all of the text in the document. This method has no effect if
174: * the text is not selectable.
175: */
176: public void selectAll();
177:
178: //============
179: // Format Width
180: //============
181:
182: /**
183: * Return the total format width, in pixels. The format width is the
184: * width to which text is wrapped.
185: * @return the format width
186: */
187: public int getFormatWidth();
188:
189: /**
190: * Return true if the paragraph at the given offset is left-to-right.
191: * @param offset an offset in the text
192: * @return true if the paragraph at the given offset is left-to-right
193: */
194: public boolean paragraphIsLeftToRight(int offset);
195:
196: /**
197: * Return true if there is a change which can be undone.
198: * @return true if there is a change which can be undone.
199: */
200: public boolean canUndo();
201:
202: /**
203: * Return true if there is a change which can be redone.
204: * @return true if there is a change which can be redone.
205: */
206: public boolean canRedo();
207:
208: /**
209: * Return true if the clipboard contains contents which could be
210: * transfered into the text.
211: * @return true if the clipboard has text content.
212: */
213: public boolean clipboardNotEmpty();
214:
215: //============
216: // Styles
217: //============
218:
219: /**
220: * Return an AttributeMap of keys with default values. The default
221: * values are used when displaying text for values which are not
222: * specified in the text.
223: * @return an AttributeMap of default key-value pairs
224: */
225: public AttributeMap getDefaultValues();
226:
227: /**
228: * This method inspects the character style runs in the selection
229: * range (or the typing style at the insertion point). It returns:
230: * <ul>
231: * <li>The value of <tt>key</tt>, if the value of <tt>key</tt>
232: * is the same in all of the style runs in the selection, or</li>
233: * <li><tt>MULTIPLE_VALUES</tt>, if two or more style runs have different
234: * values for <tt>key</tt>.</li>
235: * </ul>
236: * If a style run does not contain <tt>key</tt>,
237: * its value is considered to be the default style for <tt>key</tt>,
238: * as defined by the default values AttributeMap. Note that if
239: * <tt>key</tt> does not have a default value this method may return
240: * null.
241: * This method is useful for configuring style menus.
242: * @param key the key used to retrieve values for comparison
243: * @see #MULTIPLE_VALUES
244: */
245: public Object getCharacterStyleOverSelection(Object key);
246:
247: /**
248: * This method inspects the paragraph style runs in the selection
249: * range (or the typing style at the insertion point). It returns:
250: * <ul>
251: * <li>The value of <tt>key</tt>, if the value of <tt>key</tt>
252: * is the same in all of the style runs in the selection, or</li>
253: * <li><tt>MULTIPLE_VALUES</tt>, if two or more style runs have
254: * different values for <tt>key</tt>.</li>
255: * </ul>
256: * If a style run does not contain <tt>key</tt>,
257: * its value is considered to be the default style for <tt>key</tt>,
258: * as defined by the default values AttributeMap. Note that if
259: * <tt>key</tt> does not have a default value this method may return
260: * null.
261: * This method is useful for configuring style menus.
262: * @param key the key used to retrieve values for comparison
263: * @see #MULTIPLE_VALUES
264: */
265: public Object getParagraphStyleOverSelection(Object key);
266:
267: /**
268: * Remove the selected text from the document and place it
269: * on the clipboard. This method has no effect if the text
270: * is not editable, or if no text is selected.
271: */
272: public void cut();
273:
274: /**
275: * Place the selected text on the clipboard. This method has
276: * no effect if no text is selected.
277: */
278: public void copy();
279:
280: /**
281: * Replace the currently selected text with the text on the clipboard.
282: * This method has no effect if the text is not editable, or if no
283: * text is on the clipboard.
284: */
285: public void paste();
286:
287: /**
288: * Remove selected text from the document, without altering the clipboard.
289: * This method has no effect if the
290: * text is not editable.
291: */
292: public void clear();
293:
294: /**
295: * Undo the most recent text change. This method has no effect if
296: * there is no change to undo.
297: */
298: public void undo();
299:
300: /**
301: * Redo the most recent text change. This method has no effect if
302: * there is no change to redo.
303: */
304: public void redo();
305:
306: /**
307: * Return the number of commands the command log can hold.
308: * @return the number of commands the command log can hold
309: */
310: public int getCommandLogSize();
311:
312: /**
313: * Set the number of commands the command log can hold. All
314: * redoable commands are removed when this method is called.
315: * @param size the number of commands kept in the command log
316: */
317: public void setCommandLogSize(int size);
318:
319: /**
320: * Remove all commands from the command log.
321: */
322: public void clearCommandLog();
323:
324: /**
325: * Modify the character styles on the selected characters. If no characters
326: * are selected, modify the typing style.
327: * @param modifier the StyleModifier with which to modify the styles
328: */
329: public void modifyCharacterStyleOnSelection(StyleModifier modifier);
330:
331: /**
332: * Modify the paragraph styles in paragraphs containing selected characters, or
333: * the paragraph containing the insertion point.
334: * @param modifier the StyleModifier with which to modify the styles
335: */
336: public void modifyParagraphStyleOnSelection(StyleModifier modifier);
337:
338: /**
339: * Return the KeyRemap used to process key events.
340: * @return the key remap used to process key events
341: * @see #setKeyRemap
342: */
343: public KeyRemap getKeyRemap();
344:
345: /**
346: * Use the given KeyRemap to map key events to characters.
347: * Only key
348: * events are affected by the remap; other text entering the
349: * control (via the clipboard, for example) is not affected
350: * by the KeyRemap.
351: * <p>
352: * Do not pass <tt>null</tt> to this method to leave key
353: * events unmapped. Instead, use <tt>KeyRemap.getIdentityRemap()</tt>
354: * @param remap the KeyRemap to use for mapping key events to characters
355: * @exception java.lang.NullPointerException if parameter is null
356: * @see KeyRemap
357: */
358: public void setKeyRemap(KeyRemap remap);
359:
360: /**
361: * Return the modification flag of the current text change.
362: * @see #setModified
363: */
364: public boolean isModified();
365:
366: /**
367: * Set the modification flag of the current text change.
368: */
369: public void setModified(boolean modified);
370: }
|