ch.randelshofer.gui.text
Class DocumentProxy

java.lang.Object
  ch.randelshofer.gui.text.DocumentProxy

All Implemented Interfaces:

java.lang.Cloneable, java.util.EventListener, javax.swing.event.DocumentListener, javax.swing.event.UndoableEditListener, javax.swing.text.Document

Direct Known Subclasses:

StyledDocumentProxy

public class DocumentProxy
extends java.lang.Object
implements javax.swing.text.Document, java.lang.Cloneable, javax.swing.event.DocumentListener, javax.swing.event.UndoableEditListener

This class is designed to be less memory expensive than a standard Document object. This class tries to represent the document in form of a char array. If the document is in use, the char array is converted into a PlainDocument. If the document is no longer in use, then the PlainDocument is converted back into a char array.

Version:

2.1 2004-04-04 Creates now a styled document with a proportional font instead of with a fixed width font.
2.0 2003-10-31 Use a char array instead of a String.
1.0.2 2002-05-13 Clone did still not work properly.
1.0.1 2002-02-02 Clone did not work properly.
1.0 2001-10-09

Author:

Werner Randelshofer, Hausmatt 10, CH-6405 Immensee, Switzerland

Field Summary

Fields inherited from interface javax.swing.text.Document

StreamDescriptionProperty, TitleProperty

Constructor Summary

DocumentProxy()
Creates new DocumentProxy.

Method Summary

void	addChangeListener(javax.swing.event.ChangeListener listener) Registers the given observer to begin receiving notifications when changes are made to the document.
void	addDocumentListener(javax.swing.event.DocumentListener listener) Registers the given observer to begin receiving notifications when changes are made to the document.
void	addUndoableEditListener(javax.swing.event.UndoableEditListener listener) Registers the given observer to begin receiving notifications when undoable edits are made to the document.
void	changedUpdate(javax.swing.event.DocumentEvent e) Gives notification that an attribute or set of attributes changed.
java.lang.Object	clone() Returns a clone of this object.
protected javax.swing.text.Document	createDocumentModel()
javax.swing.text.Position	createPosition(int offs) This method allows an application to mark a place in a sequence of character content.
void	fireChangedUpdate(javax.swing.event.DocumentEvent evt) Notify all listeners that have registered interest for notification on this event type.
void	fireInsertUpdate(javax.swing.event.DocumentEvent evt) Notify all listeners that have registered interest for notification on this event type.
void	fireRemoveUpdate(javax.swing.event.DocumentEvent evt) Notify all listeners that have registered interest for notification on this event type.
void	fireStateChanged() Notify all listeners that have registered interest for notification on this event type.
void	fireUndoableEditHappened(javax.swing.undo.UndoableEdit edit) Notify all listeners that have registered interest for notification on this event type.
protected void	flushDocumentModel()
javax.swing.text.Element	getDefaultRootElement() Returns the root element that views should be based upon, unless some other mechanism for assigning views to element structures is provided.
protected javax.swing.text.Document	getDocumentModel()
javax.swing.text.Position	getEndPosition() Returns a position that represents the end of the document.
int	getLength() Returns number of characters of content currently in the document.
java.lang.Object	getProperty(java.lang.Object key) Gets properties associated with the document.
javax.swing.text.Element[]	getRootElements() Returns all of the root elements that are defined.
javax.swing.text.Position	getStartPosition() Returns a position that represents the start of the document.
java.lang.String	getText()
java.lang.String	getText(int offset, int length) Fetches the text contained within the given portion of the document.
void	getText(int offset, int length, javax.swing.text.Segment txt) Fetches the text contained within the given portion of the document.
boolean	hasDocumentListeners() Counts all registered DocumentListeners and all registered UndoableEditListeners.
void	insertString(int offset, java.lang.String str, javax.swing.text.AttributeSet a) Inserts a string of content.
void	insertUpdate(javax.swing.event.DocumentEvent e) Gives notification that there was an insert into the document.
void	putProperty(java.lang.Object key, java.lang.Object value) Puts a new property on the list.
void	remove(int offs, int len) Removes a portion of the content of the document.
void	removeChangeListener(javax.swing.event.ChangeListener listener) Unregisters the given observer from the notification list so it will no longer receive updates.
void	removeDocumentListener(javax.swing.event.DocumentListener listener) Unregisters the given observer from the notification list so it will no longer receive change updates.
void	removeUndoableEditListener(javax.swing.event.UndoableEditListener listener) Unregisters the given observer from the notification list so it will no longer receive updates.
void	removeUpdate(javax.swing.event.DocumentEvent e) Gives notification that a portion of the document has been removed.
void	render(java.lang.Runnable r) This allows the model to be safely rendered in the presence of currency, if the model supports being updated asynchronously.
void	setText(java.lang.String text)
void	undoableEditHappened(javax.swing.event.UndoableEditEvent e) An undoable edit happened

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DocumentProxy

public DocumentProxy()

Creates new DocumentProxy.

Method Detail

createPosition

public javax.swing.text.Position createPosition(int offs)
                                         throws javax.swing.text.BadLocationException

This method allows an application to mark a place in a sequence of character content. This mark can then be used to tracks change as insertions and removals are made in the content. The policy is that insertions always occur prior to the current position (the most common case) unless the insertion location is zero, in which case the insertion is forced to a position that follows the original position.

Specified by:

createPosition in interface javax.swing.text.Document

Parameters:

offs - the offset from the start of the document >= 0

Returns:

the position

Throws:

javax.swing.text.BadLocationException - if the given position does not represent a valid location in the associated document

getDefaultRootElement

public javax.swing.text.Element getDefaultRootElement()

Returns the root element that views should be based upon, unless some other mechanism for assigning views to element structures is provided.

Specified by:

getDefaultRootElement in interface javax.swing.text.Document

Returns:

the root element

getEndPosition

public javax.swing.text.Position getEndPosition()

Returns a position that represents the end of the document. The position returned can be counted on to track change and stay located at the end of the document.

Specified by:

getEndPosition in interface javax.swing.text.Document

Returns:

the position

getLength

public int getLength()

Returns number of characters of content currently in the document.

Specified by:

getLength in interface javax.swing.text.Document

Returns:

number of characters >= 0

getProperty

public java.lang.Object getProperty(java.lang.Object key)

Gets properties associated with the document. Allows one to store things like the document title, author, etc.

Specified by:

getProperty in interface javax.swing.text.Document

Parameters:

key - a non-null property

Returns:

the properties

getRootElements

public javax.swing.text.Element[] getRootElements()

Returns all of the root elements that are defined.

Typically there will be only one document structure, but the interface supports building an arbitrary number of structural projections over the text data. The document can have multiple root elements to support multiple document structures. Some examples might be:

• Text direction.
• Lexical token streams.
• Parse trees.
• Conversions to formats other than the native format.
• Modification specifications.
• Annotations.

Specified by:

getRootElements in interface javax.swing.text.Document

Returns:

the root element

getStartPosition

public javax.swing.text.Position getStartPosition()

Returns a position that represents the start of the document. The position returned can be counted on to track change and stay located at the beginning of the document.

Specified by:

getStartPosition in interface javax.swing.text.Document

Returns:

the position

getText

public java.lang.String getText(int offset,
                                int length)
                         throws javax.swing.text.BadLocationException

Fetches the text contained within the given portion of the document.

Specified by:

getText in interface javax.swing.text.Document

Parameters:

offset - the offset into the document representing the desired start of the text >= 0

length - the length of the desired string >= 0

Returns:

the text, in a String of length >= 0

Throws:

javax.swing.text.BadLocationException - some portion of the given range was not a valid part of the document. The location in the exception is the first bad position encountered.

getText

public void getText(int offset,
                    int length,
                    javax.swing.text.Segment txt)
             throws javax.swing.text.BadLocationException

Fetches the text contained within the given portion of the document.

Specified by:

getText in interface javax.swing.text.Document

Parameters:

offset - the offset into the document representing the desired start of the text >= 0

length - the length of the desired string >= 0

txt - the Segment object to return the text in

Throws:

javax.swing.text.BadLocationException - Some portion of the given range was not a valid part of the document. The location in the exception is the first bad position encountered.

insertString

public void insertString(int offset,
                         java.lang.String str,
                         javax.swing.text.AttributeSet a)
                  throws javax.swing.text.BadLocationException

Inserts a string of content. This will cause a DocumentEvent of type DocumentEvent.EventType.INSERT to be sent to the registered DocumentListers, unless an exception is thrown. The DocumentEvent will be delivered by calling the insertUpdate method on the DocumentListener. The offset and length of the generated DocumentEvent will indicate what change was actually made to the Document.

If the Document structure changed as result of the insertion, the details of what Elements were inserted and removed in response to the change will also be contained in the generated DocumentEvent. It is up to the implementation of a Document to decide how the structure should change in response to an insertion.

If the Document supports undo/redo, an UndoableEditEvent will also be generated.

Specified by:

insertString in interface javax.swing.text.Document

Parameters:

offset - the offset into the document to insert the content >= 0. All positions that track change at or after the given location will move.

str - the string to insert

a - the attributes to associate with the inserted content. This may be null if there are no attributes.

Throws:

javax.swing.text.BadLocationException - the given insert position is not a valid position within the document

See Also:

DocumentEvent, DocumentListener, UndoableEditEvent, UndoableEditListener

putProperty

public void putProperty(java.lang.Object key,
                        java.lang.Object value)

Puts a new property on the list.

Specified by:

putProperty in interface javax.swing.text.Document

Parameters:

key - the non-null property key

value - the property value

remove

public void remove(int offs,
                   int len)
            throws javax.swing.text.BadLocationException

Removes a portion of the content of the document. This will cause a DocumentEvent of type DocumentEvent.EventType.REMOVE to be sent to the registered DocumentListeners, unless an exception is thrown. The notification will be sent to the listeners by calling the removeUpdate method on the DocumentListeners.

To ensure reasonable behavior in the face of concurrency, the event is dispatched after the mutation has occurred. This means that by the time a notification of removal is dispatched, the document has already been updated and any marks created by createPosition have already changed. For a removal, the end of the removal range is collapsed down to the start of the range, and any marks in the removal range are collapsed down to the start of the range.

If the Document structure changed as result of the removal, the details of what Elements were inserted and removed in response to the change will also be contained in the generated DocumentEvent. It is up to the implementation of a Document to decide how the structure should change in response to a remove.

If the Document supports undo/redo, an UndoableEditEvent will also be generated.

Specified by:

remove in interface javax.swing.text.Document

Parameters:

offs - the offset from the begining >= 0

len - the number of characters to remove >= 0

Throws:

javax.swing.text.BadLocationException - some portion of the removal range was not a valid part of the document. The location in the exception is the first bad position encountered.

See Also:

DocumentEvent, DocumentListener, UndoableEditEvent, UndoableEditListener

addDocumentListener

public void addDocumentListener(javax.swing.event.DocumentListener listener)

Registers the given observer to begin receiving notifications when changes are made to the document.

Specified by:

addDocumentListener in interface javax.swing.text.Document

Parameters:

listener - the observer to register

See Also:

Document.removeDocumentListener(javax.swing.event.DocumentListener)

addUndoableEditListener

public void addUndoableEditListener(javax.swing.event.UndoableEditListener listener)

Registers the given observer to begin receiving notifications when undoable edits are made to the document.

Specified by:

addUndoableEditListener in interface javax.swing.text.Document

Parameters:

listener - the observer to register

See Also:

UndoableEditEvent

addChangeListener

public void addChangeListener(javax.swing.event.ChangeListener listener)

Registers the given observer to begin receiving notifications when changes are made to the document.

Parameters:

listener - the observer to register

See Also:

Document.removeDocumentListener(javax.swing.event.DocumentListener)

removeDocumentListener

public void removeDocumentListener(javax.swing.event.DocumentListener listener)

Unregisters the given observer from the notification list so it will no longer receive change updates.

Specified by:

removeDocumentListener in interface javax.swing.text.Document

Parameters:

listener - the observer to register

See Also:

Document.addDocumentListener(javax.swing.event.DocumentListener)

removeUndoableEditListener

public void removeUndoableEditListener(javax.swing.event.UndoableEditListener listener)

Unregisters the given observer from the notification list so it will no longer receive updates.

Specified by:

removeUndoableEditListener in interface javax.swing.text.Document

Parameters:

listener - the observer to remove

See Also:

UndoableEditEvent

removeChangeListener

public void removeChangeListener(javax.swing.event.ChangeListener listener)

Unregisters the given observer from the notification list so it will no longer receive updates.

Parameters:

listener - the observer to remove

See Also:

UndoableEditEvent

render

public void render(java.lang.Runnable r)

This allows the model to be safely rendered in the presence of currency, if the model supports being updated asynchronously. The given runnable will be executed in a way that allows it to safely read the model with no changes while the runnable is being executed. The runnable itself may not make any mutations.

Specified by:

render in interface javax.swing.text.Document

Parameters:

r - a Runnable used to render the model

setText

public void setText(java.lang.String text)

getText

public java.lang.String getText()

getDocumentModel

protected javax.swing.text.Document getDocumentModel()

createDocumentModel

protected javax.swing.text.Document createDocumentModel()

flushDocumentModel

protected void flushDocumentModel()

fireUndoableEditHappened

public void fireUndoableEditHappened(javax.swing.undo.UndoableEdit edit)

Notify all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method.

fireStateChanged

public void fireStateChanged()

Notify all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method.

fireInsertUpdate

public void fireInsertUpdate(javax.swing.event.DocumentEvent evt)

Notify all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method.

fireRemoveUpdate

public void fireRemoveUpdate(javax.swing.event.DocumentEvent evt)

Notify all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method.

fireChangedUpdate

public void fireChangedUpdate(javax.swing.event.DocumentEvent evt)

Notify all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method.

hasDocumentListeners

public boolean hasDocumentListeners()

Counts all registered DocumentListeners and all registered UndoableEditListeners.

clone

public java.lang.Object clone()

Returns a clone of this object.

Overrides:

clone in class java.lang.Object

removeUpdate

public void removeUpdate(javax.swing.event.DocumentEvent e)

Gives notification that a portion of the document has been removed. The range is given in terms of what the view last saw (that is, before updating sticky positions).

Specified by:

removeUpdate in interface javax.swing.event.DocumentListener

Parameters:

e - the document event

insertUpdate

public void insertUpdate(javax.swing.event.DocumentEvent e)

Gives notification that there was an insert into the document. The range given by the DocumentEvent bounds the freshly inserted region.

Specified by:

insertUpdate in interface javax.swing.event.DocumentListener

Parameters:

e - the document event

changedUpdate

public void changedUpdate(javax.swing.event.DocumentEvent e)

Gives notification that an attribute or set of attributes changed.

Specified by:

changedUpdate in interface javax.swing.event.DocumentListener

Parameters:

e - the document event

undoableEditHappened

public void undoableEditHappened(javax.swing.event.UndoableEditEvent e)

An undoable edit happened

Specified by:

undoableEditHappened in interface javax.swing.event.UndoableEditListener