Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.jgoodies.binding.adapter
Class DocumentAdapter

    java.lang.Object
      com.jgoodies.binding.adapter.DocumentAdapter

All Implemented Interfaces:
  EventListener, DocumentListener, Document

    public final class DocumentAdapter

extends Object
implements Document, DocumentListener

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.

Version:
  $Revision: 1.3 $
Author:
  Karsten Lentzsch
See Also:
  `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

### DocumentAdapter

    public DocumentAdapter(ValueModel subject)

  Constructs a DocumentAdapter on the specified String-typed subject ValueModel. Doesn't filter newline characters.

  Parameters:
    `subject` - the underlying String typed ValueModel
  Throws:
    `NullPointerException` - if the subject is `null`

### DocumentAdapter

    public DocumentAdapter(ValueModel subject,
                           boolean filterNewlines)

  Constructs a DocumentAdapter on the specified String-typed subject ValueModel. The boolean parameter specifies if newline characters shall be filtered or retained.

  Parameters:
    `subject` - the underlying String typed ValueModel
    `filterNewlines` - `true` to filter newline characters, `false` to retain them
  Throws:
    `NullPointerException` - if the subject is `null`

### DocumentAdapter

    public DocumentAdapter(ValueModel subject,
                           Document document)

  Constructs a DocumentAdapter on the specified String-typed subject ValueModel. Doesn't filter newline characters.

  Parameters:
    `subject` - the underlying String-typed ValueModel
    `document` - the underlying Document implementation
  Throws:
    `NullPointerException` - if the subject or document is `null`

### DocumentAdapter

    public DocumentAdapter(ValueModel subject,
                           Document document,
                           boolean filterNewlines)

  Constructs a DocumentAdapter on the specified subject. The subject must return values of type String. The boolean parameter specifies if newline characters shall be filtered or retained.

  Parameters:
    `subject` - the underlying String typed ValueModel
    `document` - the underlying Document implementation
    `filterNewlines` - `true` to filter newline characters, `false` to retain them
  Throws:
    `NullPointerException` - if the subject or document is `null`

Method Detail

### insertUpdate

    public void insertUpdate(DocumentEvent e)

  There was an insert into the document; update the subject.

  Specified by:
    `insertUpdate` in interface `DocumentListener`
  Parameters:
    `e` - the document event

### removeUpdate

    public void removeUpdate(DocumentEvent e)

  A portion of the document has been removed; update the subject.

  Specified by:
    `removeUpdate` in interface `DocumentListener`
  Parameters:
    `e` - the document event

### changedUpdate

    public void changedUpdate(DocumentEvent e)

  An attribute or set of attributes has changed; do nothing.

  Specified by:
    `changedUpdate` in interface `DocumentListener`
  Parameters:
    `e` - the document event

### 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

### 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)`

### 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)`

### 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`

### 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`

### 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:
    `putProperty(Object, Object)`

### 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:
    `getProperty(Object)`

### remove

    public void remove(int offs,
                       int len)
                throws 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 `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 offset,
                             String str,
                             AttributeSet a)
                      throws 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 `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:
    `BadLocationException` - the given insert position is not a valid position within the document
  See Also:
    `DocumentEvent`, `DocumentListener`, `UndoableEditEvent`, `UndoableEditListener`

### 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.

### 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

### 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

### 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

### 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

### 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

### render

    public void render(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 `Document`
  Parameters:
    `r` - a Runnable used to render the model

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2002-2006 JGoodies Karsten Lentzsch. All Rights Reserved.