|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.jgoodies.binding.adapter.DocumentAdapter
public final class DocumentAdapter
Converts the ValueModel interface into the Document interface, which is the model interface for Swing text components. It is used to bind String values to text components, for example a JTextField. At construction time the document is updated with the subject's contents.
Instead of extending AbstractDocument or the specialized
PlainDocument this class holds a reference to a Document
instance and forwards all Document messages to the corresponding
method in the reference. By default the delegate is initialized as
an instance of PlainDocument; the two parameter constructor allows
to provide any other Document implementation. The latter can be useful
if the text component uses a custom Document, for example a custom
IntegerDocument
or MaskedDocument
.
This DocumentAdapter provides limited support for handling
subject value modifications while updating the subject.
If a Document change initiates a subject value update, the subject
will be observed and a property change fired by the subject will be
handled - if any. In most cases, the subject will notify about a
change to the text that was just set by this DocumentAdapter.
However, in some cases the subject may decide to modify this text,
for example to ensure upper case characters.
Since at this moment, this adapter's Document is still write-locked,
the Document update is performed later using
SwingUtilities#invokeLater
.
Note:
Such an update will typically change the Caret position in
JTextField's and other JTextComponent's that use this DocumentAdapter
as model. Hence, the subject value modifications can be used with
commit-on-focus-lost text components, but typically not with a
commit-on-key-typed component. For the latter case, you may consider
using a custom DocumentFilter
.
Constraints:
The ValueModel must be of type String
.
Examples:
ValueModel lastNameModel = new PropertyAdapter(customer, "lastName", true); JTextField lastNameField = new JTextField(); lastNameField.setDocument(new DocumentAdapter(lastNameModel)); ValueModel codeModel = new PropertyAdapter(shipment, "code", true); JTextField codeField = new JTextField(); codeField.setDocument(new DocumentAdapter(codeModel), new MaskedDocument(...));
TODO: Consider changing the event source for DocumentEvents from the delegate to this DocumentAdapter. DocumentListeners may expect that the event source is the one they are registered with.
ValueModel
,
Document
,
PlainDocument
Field Summary |
---|
Fields inherited from interface javax.swing.text.Document |
---|
StreamDescriptionProperty, TitleProperty |
Constructor Summary | |
---|---|
DocumentAdapter(ValueModel subject)
Constructs a DocumentAdapter on the specified String-typed subject ValueModel. |
|
DocumentAdapter(ValueModel subject,
boolean filterNewlines)
Constructs a DocumentAdapter on the specified String-typed subject ValueModel. |
|
DocumentAdapter(ValueModel subject,
Document document)
Constructs a DocumentAdapter on the specified String-typed subject ValueModel. |
|
DocumentAdapter(ValueModel subject,
Document document,
boolean filterNewlines)
Constructs a DocumentAdapter on the specified subject. |
Method Summary | |
---|---|
void |
addDocumentListener(DocumentListener listener)
Registers the given observer to begin receiving notifications when changes are made to the document. |
void |
addUndoableEditListener(UndoableEditListener listener)
Registers the given observer to begin receiving notifications when undoable edits are made to the document. |
void |
changedUpdate(DocumentEvent e)
An attribute or set of attributes has changed; do nothing. |
Position |
createPosition(int offs)
This method allows an application to mark a place in a sequence of character content. |
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. |
int |
getLength()
Returns number of characters of content currently in 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. |
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 offset,
String str,
AttributeSet a)
Inserts a string of content. |
void |
insertUpdate(DocumentEvent e)
There was an insert into the document; update the subject. |
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 |
removeUndoableEditListener(UndoableEditListener listener)
Unregisters the given observer from the notification list so it will no longer receive updates. |
void |
removeUpdate(DocumentEvent e)
A portion of the document has been removed; update the subject. |
void |
render(Runnable r)
This allows the model to be safely rendered in the presence of currency, if the model supports being updated asynchronously. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public DocumentAdapter(ValueModel subject)
subject
- the underlying String typed ValueModel
NullPointerException
- if the subject is null
public DocumentAdapter(ValueModel subject, boolean filterNewlines)
subject
- the underlying String typed ValueModelfilterNewlines
- true
to filter newline characters,
false
to retain them
NullPointerException
- if the subject is null
public DocumentAdapter(ValueModel subject, Document document)
subject
- the underlying String-typed ValueModeldocument
- the underlying Document implementation
NullPointerException
- if the subject or document is null
public DocumentAdapter(ValueModel subject, Document document, boolean filterNewlines)
subject
- the underlying String typed ValueModeldocument
- the underlying Document implementationfilterNewlines
- true
to filter newline characters,
false
to retain them
NullPointerException
- if the subject or document is null
Method Detail |
---|
public void insertUpdate(DocumentEvent e)
insertUpdate
in interface DocumentListener
e
- the document eventpublic void removeUpdate(DocumentEvent e)
removeUpdate
in interface DocumentListener
e
- the document eventpublic void changedUpdate(DocumentEvent e)
changedUpdate
in interface DocumentListener
e
- the document eventpublic int getLength()
getLength
in interface Document
public void addDocumentListener(DocumentListener listener)
addDocumentListener
in interface Document
listener
- the observer to registerDocument.removeDocumentListener(javax.swing.event.DocumentListener)
public void removeDocumentListener(DocumentListener listener)
removeDocumentListener
in interface Document
listener
- the observer to registerDocument.addDocumentListener(javax.swing.event.DocumentListener)
public void addUndoableEditListener(UndoableEditListener listener)
addUndoableEditListener
in interface Document
listener
- the observer to registerUndoableEditEvent
public void removeUndoableEditListener(UndoableEditListener listener)
removeUndoableEditListener
in interface Document
listener
- the observer to registerUndoableEditEvent
public Object getProperty(Object key)
getProperty
in interface Document
key
- a non-null
property key
putProperty(Object, Object)
public void putProperty(Object key, Object value)
StreamDescriptionProperty
and
TitleProperty
.
Other properties, such as author, may also be defined.
putProperty
in interface Document
key
- the non-null
property keyvalue
- the property valuegetProperty(Object)
public void remove(int offs, int len) throws BadLocationException
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.
remove
in interface Document
offs
- the offset from the beginning >= 0len
- the number of characters to remove >= 0
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.DocumentEvent
,
DocumentListener
,
UndoableEditEvent
,
UndoableEditListener
public void insertString(int offset, String str, AttributeSet a) throws BadLocationException
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.
insertString
in interface Document
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 inserta
- the attributes to associate with the inserted
content. This may be null if there are no attributes.
BadLocationException
- the given insert position is not a valid
position within the documentDocumentEvent
,
DocumentListener
,
UndoableEditEvent
,
UndoableEditListener
public String getText(int offset, int length) throws BadLocationException
getText
in interface Document
offset
- the offset into the document representing the desired
start of the text >= 0length
- the length of the desired string >= 0
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.public void getText(int offset, int length, Segment txt) throws BadLocationException
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;
}
getText
in interface Document
offset
- the offset into the document representing the desired
start of the text >= 0length
- the length of the desired string >= 0txt
- the Segment object to return the text in
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.public Position getStartPosition()
getStartPosition
in interface Document
public Position getEndPosition()
getEndPosition
in interface Document
public Position createPosition(int offs) throws BadLocationException
createPosition
in interface Document
offs
- the offset from the start of the document >= 0
BadLocationException
- if the given position does not
represent a valid location in the associated documentpublic Element[] getRootElements()
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:
getRootElements
in interface Document
public Element getDefaultRootElement()
getDefaultRootElement
in interface Document
public void render(Runnable r)
render
in interface Document
r
- a Runnable used to render the model
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |