org.eclipse.swt.custom.StyledTextContent Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of org.eclipse.swt.gtk.linux.ppc64le Show documentation
Standard Widget Toolkit for GTK on ppc64le
The newest version!
/*******************************************************************************
 * Copyright (c) 2000, 2020 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.swt.custom;


/**
 * Clients may implement the StyledTextContent interface to provide a
 * custom store for the StyledText widget content. The StyledText widget
 * interacts with its StyledTextContent in order to access and update
 * the text that is being displayed and edited in the widget.
 * A custom content implementation can be set in the widget using the
 * StyledText.setContent API.
 */
public interface StyledTextContent {

/**
 * Called by StyledText to add itself as an Observer to content changes.
 * See TextChangeListener for a description of the listener methods that
 * are called when text changes occur.
 *
 * @param listener the listener
 * @exception IllegalArgumentException 
 *    ERROR_NULL_ARGUMENT when listener is null
 * 
 */
public void addTextChangeListener(TextChangeListener listener);

/**
 * Return the number of characters in the content.
 *
 * @return the number of characters in the content.
 */
public int getCharCount();

/**
 * Return the line at the given line index without delimiters.
 *
 * @param lineIndex index of the line to return. Does not include
 *	delimiters of preceding lines. Index 0 is the first line of the
 * 	content.
 * @return the line text without delimiters
 * 	For example, if text = "\r\n\r\n", and delimiter = "\r\n", then:
 * 
 * getLine(0) == ""
 * 
getLine(1) == ""
 * 
getLine(2) == ""
 * 
 * 	or if text = "A\nBC\nD", and delimiter = "\n", then:
 * 
 * getLine(0) == "A"
 * 
getLine(1) == "BC"
 * 
getLine(2) == "D"
 * 
 */
public String getLine(int lineIndex);

/**
 * Return the line index at the given character offset.
 *
 * @param offset offset of the line to return. The first character of the
 * 	document is at offset 0.  An offset of {@link #getCharCount()} is valid
 *	and should answer the line index of the last line.
 * @return the line index. The first line is at index 0.  If the character
 * 	at offset is a delimiter character, answer the line index of the line
 * 	that is delimited.
 * 	For example, if text = "\r\n\r\n", and delimiter = "\r\n", then:
 * 
 * getLineAtOffset(0) == 0
 * 
getLineAtOffset(1) == 0
 * 
getLineAtOffset(2) == 1
 * 
getLineAtOffset(3) == 1
 * 
getLineAtOffset(4) == 2
 * 
 * 	or if text = "A\nBC\nD", and delimiter = "\n", then:
 * 
 * getLineAtOffset(0) == 0
 * 
getLineAtOffset(1) == 0
 * 
getLineAtOffset(2) == 1
 * 
getLineAtOffset(3) == 1
 * 
getLineAtOffset(4) == 1
 * 
getLineAtOffset(5) == 2
 * 
getLineAtOffset(6) == 2
 * 
 */
public int getLineAtOffset(int offset);

/**
 * Return the number of lines.  Should answer 1 when no text is specified.
 * The  StyledText widget relies on this behavior for drawing the cursor.
 *
 * @return the number of lines.  For example:
 * 
 * 	text value ==> getLineCount
 * 
	null ==> 1
 * 
	"" ==> 1
 * 
	"a\n" ==> 2
 * 
	"\n\n" ==> 3
 * 
 */
public int getLineCount();

/**
 * Return the line delimiter that should be used by the StyledText
 * widget when inserting new lines. New lines entered using key strokes
 * and paste operations use this line delimiter.
 * Implementors may use System.lineSeparator() to return
 * the platform line delimiter.
 *
 * @return the line delimiter that should be used by the StyledText widget
 *	when inserting new lines.
 */
public String getLineDelimiter();

/**
 * Return the character offset of the first character of the given line.
 * 
 * NOTE: When there is no text (i.e., no lines), getOffsetAtLine(0)
 * is a valid call that should return 0.
 * 
 *
 * @param lineIndex index of the line. The first line is at index 0.
 * @return offset offset of the first character of the line. The first
 * 	character of the document is at offset 0.  The return value should
 * 	include line delimiters.
 * 	For example, if text = "\r\ntest\r\n" and delimiter = "\r\n", then:
 * 
 * getOffsetAtLine(0) == 0
 * 
getOffsetAtLine(1) == 2
 * 
getOffsetAtLine(2) == 8
 * 
 */
public int getOffsetAtLine(int lineIndex);

/**
 * Returns a string representing the content at the given range.
 *
 * @param start the start offset of the text to return. Offset 0 is the
 * 	first character of the document.
 * @param length the length of the text to return
 * @return the text at the given range
 */
public String getTextRange(int start, int length);

/**
 * Remove the specified text changed listener.
 *
 * @param listener the listener which should no longer be notified
 *
 * @exception IllegalArgumentException 
 *    ERROR_NULL_ARGUMENT when listener is null
 * 
 */
public void removeTextChangeListener(TextChangeListener listener);

/**
 * Replace the text with "newText" starting at position "start"
 * for a length of "replaceLength".
 * 
 * Implementors have to notify the TextChangeListeners that were added
 * using addTextChangeListener before and after the content
 * is changed. A TextChangingEvent has to be sent to the
 * textChanging method before the content is changed and a
 * TextChangedEvent has to be sent to the textChanged method
 * after the content has changed.
 * The text change that occurs after the TextChangingEvent
 * has been sent has to be consistent with the data provided in the
 * TextChangingEvent.
 * This data will be cached by the widget and will be used when the
 * TextChangedEvent is received.
 * 

 * The TextChangingEvent should be set as follows:
 * 
 * 
 * event.start = start of the replaced text
 * 
event.newText = text that is going to be inserted or empty String
 *	if no text will be inserted
 * 
event.replaceCharCount = length of text that is going to be replaced
 * 
event.newCharCount = length of text that is going to be inserted
 * 
event.replaceLineCount = number of lines that are going to be replaced
 * 
event.newLineCount = number of new lines that are going to be inserted
 * 
 * NOTE: newLineCount is the number of inserted lines and replaceLineCount
 * is the number of deleted lines based on the change that occurs visually.
 * For example:
 * 
 * (replaceText, newText) ==> (replaceLineCount, newLineCount)
 * 
("", "\n") ==> (0, 1)
 * 
("\n\n", "a") ==> (2, 0)
 * 
("a", "\n\n") ==> (0, 2)
 * 
("\n", "") ==> (1, 0)
 * 
 *
 * @param start start offset of text to replace, none of the offsets include
 *	delimiters of preceding lines, offset 0 is the first character of the
 * 	document
 * @param replaceLength length of text to replace
 * @param text text to replace
 * @see TextChangeListener
 */
public void replaceTextRange(int start, int replaceLength, String text);

/**
 * Set text to "text".
 * Implementors have to send a TextChangedEvent to the
 * textSet method of the TextChangeListeners that were added using
 * addTextChangeListener.
 *
 * @param text the new text
 * @see TextChangeListener
 */
public void setText(String text);
}