org.jdesktop.swingx.autocomplete
Class AutoCompleteDocument

java.lang.Object
  org.jdesktop.swingx.autocomplete.AutoCompleteDocument

All Implemented Interfaces:

Document, StyledDocument

public class AutoCompleteDocument
extends Object
implements StyledDocument

A document that can be plugged into any JTextComponent to enable automatic completion. It finds and selects matching items using any implementation of the AbstractAutoCompleteAdaptor.

Field Summary

Fields inherited from interface javax.swing.text.Document

StreamDescriptionProperty, TitleProperty

Constructor Summary

AutoCompleteDocument(AbstractAutoCompleteAdaptor adaptor, boolean strictMatching)
Creates a new AutoCompleteDocument for the given AbstractAutoCompleteAdaptor.

AutoCompleteDocument(AbstractAutoCompleteAdaptor adaptor, boolean strictMatching, ObjectToStringConverter stringConverter)
Creates a new AutoCompleteDocument for the given AbstractAutoCompleteAdaptor.

AutoCompleteDocument(AbstractAutoCompleteAdaptor adaptor, boolean strictMatching, ObjectToStringConverter stringConverter, Document delegate)
Creates a new AutoCompleteDocument for the given AbstractAutoCompleteAdaptor.

Method Summary

void	addDocumentListener(DocumentListener listener) Registers the given observer to begin receiving notifications when changes are made to the document.
Style	addStyle(String nm, Style parent) Adds a new style into the logical style hierarchy.
void	addUndoableEditListener(UndoableEditListener listener) Registers the given observer to begin receiving notifications when undoable edits are made to the document.
Position	createPosition(int offs) This method allows an application to mark a place in a sequence of character content.
Color	getBackground(AttributeSet attr) Takes a set of attributes and turn it into a background color specification.
Element	getCharacterElement(int pos) Gets the element that represents the character that is at the given offset within the document.
Element	getDefaultRootElement() Returns the root element that views should be based upon, unless some other mechanism for assigning views to element structures is provided.
Position	getEndPosition() Returns a position that represents the end of the document.
Font	getFont(AttributeSet attr) Takes a set of attributes and turn it into a font specification.
Color	getForeground(AttributeSet attr) Takes a set of attributes and turn it into a foreground color specification.
int	getLength() Returns number of characters of content currently in the document.
Style	getLogicalStyle(int p) Gets a logical style for a given position in a paragraph.
Element	getParagraphElement(int pos) Gets the element that represents the paragraph that encloses the given offset within the document.
Object	getProperty(Object key) Gets the properties associated with the document.
Element[]	getRootElements() Returns all of the root elements that are defined.
Position	getStartPosition() Returns a position that represents the start of the document.
Style	getStyle(String nm) Fetches a named style previously added.
String	getText(int offset, int length) Fetches the text contained within the given portion of the document.
void	getText(int offset, int length, Segment txt) Fetches the text contained within the given portion of the document.
void	insertString(int offs, String str, AttributeSet a) Inserts a string of content.
boolean	isStrictMatching() Returns if only items from the adaptor's list should be allowed to be entered.
void	putProperty(Object key, Object value) Associates a property with the document.
void	remove(int offs, int len) Removes a portion of the content of the document.
void	removeDocumentListener(DocumentListener listener) Unregisters the given observer from the notification list so it will no longer receive change updates.
void	removeStyle(String nm) Removes a named style previously added to the document.
void	removeUndoableEditListener(UndoableEditListener listener) Unregisters the given observer from the notification list so it will no longer receive updates.
void	render(Runnable r) Allows the model to be safely rendered in the presence of concurrency, if the model supports being updated asynchronously.
void	setCharacterAttributes(int offset, int length, AttributeSet s, boolean replace) Changes the content element attributes used for the given range of existing content in the document.
void	setLogicalStyle(int pos, Style s) Sets the logical style to use for the paragraph at the given position.
void	setParagraphAttributes(int offset, int length, AttributeSet s, boolean replace) Sets paragraph attributes.

Methods inherited from class java.lang.Object

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

Constructor Detail

AutoCompleteDocument

public AutoCompleteDocument(AbstractAutoCompleteAdaptor adaptor,
                            boolean strictMatching,
                            ObjectToStringConverter stringConverter,
                            Document delegate)

Creates a new AutoCompleteDocument for the given AbstractAutoCompleteAdaptor.

Parameters:

adaptor - The adaptor that will be used to find and select matching items.

strictMatching - true, if only items from the adaptor's list should be allowed to be entered

stringConverter - the converter used to transform items to strings

delegate - the Document delegate backing this document

AutoCompleteDocument

public AutoCompleteDocument(AbstractAutoCompleteAdaptor adaptor,
                            boolean strictMatching,
                            ObjectToStringConverter stringConverter)

Creates a new AutoCompleteDocument for the given AbstractAutoCompleteAdaptor.

Parameters:

adaptor - The adaptor that will be used to find and select matching items.

strictMatching - true, if only items from the adaptor's list should be allowed to be entered

stringConverter - the converter used to transform items to strings

AutoCompleteDocument

public AutoCompleteDocument(AbstractAutoCompleteAdaptor adaptor,
                            boolean strictMatching)

Creates a new AutoCompleteDocument for the given AbstractAutoCompleteAdaptor.

Parameters:

strictMatching - true, if only items from the adaptor's list should be allowed to be entered

adaptor - The adaptor that will be used to find and select matching items.

Method Detail

isStrictMatching

public boolean isStrictMatching()

Returns if only items from the adaptor's list should be allowed to be entered.

Returns:

if only items from the adaptor's list should be allowed to be entered

remove

public void remove(int offs,
                   int len)
            throws BadLocationException

Description copied from interface: javax.swing.text.Document

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 Document

Parameters:

offs - the offset from the beginning >= 0

len - the number of characters to remove >= 0

Throws:

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

insertString

public void insertString(int offs,
                         String str,
                         AttributeSet a)
                  throws BadLocationException

Description copied from interface: javax.swing.text.Document

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 Document

Parameters:

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

BadLocationException - the given insert position is not a valid position within the document

See Also:

DocumentEvent, DocumentListener, UndoableEditEvent, UndoableEditListener

addStyle

public Style addStyle(String nm,
                      Style parent)

Adds a new style into the logical style hierarchy. Style attributes resolve from bottom up so an attribute specified in a child will override an attribute specified in the parent.

Specified by:

addStyle in interface StyledDocument

Parameters:

nm - the name of the style (must be unique within the collection of named styles). The name may be null if the style is unnamed, but the caller is responsible for managing the reference returned as an unnamed style can't be fetched by name. An unnamed style may be useful for things like character attribute overrides such as found in a style run.

parent - the parent style. This may be null if unspecified attributes need not be resolved in some other style.

Returns:

the style

getBackground

public Color getBackground(AttributeSet attr)

Takes a set of attributes and turn it into a background color specification. This might be used to specify things like brighter, more hue, etc.

Specified by:

getBackground in interface StyledDocument

Parameters:

attr - the set of attributes

Returns:

the color

getCharacterElement

public Element getCharacterElement(int pos)

Gets the element that represents the character that is at the given offset within the document.

Specified by:

getCharacterElement in interface StyledDocument

Parameters:

pos - the offset >= 0

Returns:

the element

getFont

public Font getFont(AttributeSet attr)

Takes a set of attributes and turn it into a font specification. This can be used to turn things like family, style, size, etc into a font that is available on the system the document is currently being used on.

Specified by:

getFont in interface StyledDocument

Parameters:

attr - the set of attributes

Returns:

the font

getForeground

public Color getForeground(AttributeSet attr)

Takes a set of attributes and turn it into a foreground color specification. This might be used to specify things like brighter, more hue, etc.

Specified by:

getForeground in interface StyledDocument

Parameters:

attr - the set of attributes

Returns:

the color

getLogicalStyle

public Style getLogicalStyle(int p)

Gets a logical style for a given position in a paragraph.

Specified by:

getLogicalStyle in interface StyledDocument

Parameters:

p - the position >= 0

Returns:

the style

getParagraphElement

public Element getParagraphElement(int pos)

Gets the element that represents the paragraph that encloses the given offset within the document.

Specified by:

getParagraphElement in interface StyledDocument

Parameters:

pos - the offset >= 0

Returns:

the element

getStyle

public Style getStyle(String nm)

Fetches a named style previously added.

Specified by:

getStyle in interface StyledDocument

Parameters:

nm - the name of the style

Returns:

the style

removeStyle

public void removeStyle(String nm)

Removes a named style previously added to the document.

Specified by:

removeStyle in interface StyledDocument

Parameters:

nm - the name of the style to remove

setCharacterAttributes

public void setCharacterAttributes(int offset,
                                   int length,
                                   AttributeSet s,
                                   boolean replace)

Changes the content element attributes used for the given range of existing content in the document. All of the attributes defined in the given Attributes argument are applied to the given range. This method can be used to completely remove all content level attributes for the given range by giving an Attributes argument that has no attributes defined and setting replace to true.

Specified by:

setCharacterAttributes in interface StyledDocument

Parameters:

offset - the start of the change >= 0

length - the length of the change >= 0

s - the non-null attributes to change to. Any attributes defined will be applied to the text for the given range.

replace - indicates whether or not the previous attributes should be cleared before the new attributes as set. If true, the operation will replace the previous attributes entirely. If false, the new attributes will be merged with the previous attributes.

setLogicalStyle

public void setLogicalStyle(int pos,
                            Style s)

Sets the logical style to use for the paragraph at the given position. If attributes aren't explicitly set for character and paragraph attributes they will resolve through the logical style assigned to the paragraph, which in turn may resolve through some hierarchy completely independent of the element hierarchy in the document.

Specified by:

setLogicalStyle in interface StyledDocument

Parameters:

pos - the starting position >= 0

s - the style to set

setParagraphAttributes

public void setParagraphAttributes(int offset,
                                   int length,
                                   AttributeSet s,
                                   boolean replace)

Sets paragraph attributes.

Specified by:

setParagraphAttributes in interface StyledDocument

Parameters:

offset - the start of the change >= 0

length - the length of the change >= 0

s - the non-null attributes to change to. Any attributes defined will be applied to the text for the given range.

replace - indicates whether or not the previous attributes should be cleared before the new attributes are set. If true, the operation will replace the previous attributes entirely. If false, the new attributes will be merged with the previous attributes.

addDocumentListener

public void addDocumentListener(DocumentListener listener)

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

Specified by:

addDocumentListener in interface Document

Parameters:

listener - the observer to register

See Also:

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

addUndoableEditListener

public void addUndoableEditListener(UndoableEditListener listener)

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

Specified by:

addUndoableEditListener in interface Document

Parameters:

listener - the observer to register

See Also:

UndoableEditEvent

createPosition

public Position createPosition(int offs)
                        throws 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 Document

Parameters:

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

Returns:

the position

Throws:

BadLocationException - if the given position does not represent a valid location in the associated document

getDefaultRootElement

public 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 Document

Returns:

the root element

getEndPosition

public 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 Document

Returns:

the position

getLength

public int getLength()

Returns number of characters of content currently in the document.

Specified by:

getLength in interface Document

Returns:

number of characters >= 0

getProperty

public Object getProperty(Object key)

Gets the properties associated with the document.

Specified by:

getProperty in interface Document

Parameters:

key - a non-null property key

Returns:

the properties

See Also:

Document.putProperty(Object, Object)

getRootElements

public 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 Document

Returns:

the root element

getStartPosition

public 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 Document

Returns:

the position

getText

public String getText(int offset,
                      int length)
               throws BadLocationException

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

Specified by:

getText in interface 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:

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,
                    Segment txt)
             throws BadLocationException

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

If the partialReturn property on the txt parameter is false, the data returned in the Segment will be the entire length requested and may or may not be a copy depending upon how the data was stored. If the partialReturn property is true, only the amount of text that can be returned without creating a copy is returned. Using partial returns will give better performance for situations where large parts of the document are being scanned. The following is an example of using the partial return to access the entire document:

   int nleft = doc.getDocumentLength();
   Segment text = new Segment();
   int offs = 0;
   text.setPartialReturn(true);   
   while (nleft > 0) {
       doc.getText(offs, nleft, text);
       // do someting with text
       nleft -= text.count;
       offs += text.count;
   }

 

Specified by:

getText in interface 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:

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.

putProperty

public void putProperty(Object key,
                        Object value)

Associates a property with the document. Two standard property keys provided are: StreamDescriptionProperty and TitleProperty. Other properties, such as author, may also be defined.

Specified by:

putProperty in interface Document

Parameters:

key - the non-null property key

value - the property value

See Also:

Document.getProperty(Object)

removeDocumentListener

public void removeDocumentListener(DocumentListener listener)

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

Specified by:

removeDocumentListener in interface Document

Parameters:

listener - the observer to register

See Also:

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

removeUndoableEditListener

public void removeUndoableEditListener(UndoableEditListener listener)

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

Specified by:

removeUndoableEditListener in interface Document

Parameters:

listener - the observer to register

See Also:

UndoableEditEvent

render

public void render(Runnable r)

Allows the model to be safely rendered in the presence of concurrency, 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 Document

Parameters:

r - a Runnable used to render the model