JavaTM 2 Platform
Standard Ed. 5.0

javax.swing.text
インタフェース Document

既知のサブインタフェースの一覧:
StyledDocument
既知の実装クラスの一覧:
AbstractDocument, DefaultStyledDocument, HTMLDocument, PlainDocument

public interface Document

Document は swing テキストコンポーネントのモデルとなるテキストのコンテナです。このインタフェースのめざすところはプレーンテキストのテキストフィールドのように非常にシンプルなものから HTML または XML のように複雑なものにまで対応できるようにスケーリングすることです。

コンテンツ

最もシンプルなレベルでは、テキストは線状に伸びる一連の文字として形成されます。国際化に備えて Swing テキストモデルは unicode 文字を使用します。通常、テキストコンポーネントに表示される文字シーケンスはコンポーネントの「コンテンツ」と呼ばれます。

シーケンス内の場所を参照するために 2 文字間の位置座標を使用します。下の図に示すように、テキストドキュメント内の場所は位置として、またはオフセットとして示すことができます。この位置はゼロから始まります。

次の文は、この図について説明しています。

たとえば、前の図のようにドキュメントのコンテンツが「The quick brown fox」というシーケンスの場合、「The」の前の場所は 0 で、「The」の後とそれに続く空白の間の場所は 3 となります。「The」というシーケンスの全文字シーケンスを「範囲」と呼びます。

次のメソッドでコンテンツを構成する文字データへアクセスできます。

構造

テキストが単調なコンテンツとして表されることはほとんどありません。むしろ、通常、テキストはコンテンツと関連した構造になっています。正確にどの構造がモデルになっているかは特定の Document 実装により異なります。単純なテキストフィールドのように構造がないようなシンプルなものもあれば、下の図のようなものもあります。

図は、Book、Chapter、Paragraph の順に示しています。

構造単位、すなわちツリーのノードは Element インタフェースで表せます。各 Element は属性のセットによりタグを付けることができます。こういう名前と値のペアの属性は AttributeSet インタフェースで定義されます。

次のメソッドでドキュメント構造へアクセスできます。

変更

すべてのドキュメントは簡単なテキストの追加および削除ができる必要があります。通常、テキストはキーボードまたはマウスのジェスチャーで挿入、削除ができます。挿入、削除をした結果ドキュメント構造にどういう影響があるかはすべてドキュメントの実装によります。

次のメソッドはドキュメントコンテンツの変化に関係付けられています。

通知

Document に変更が生じた場合は関係者に通知する必要があります。変更通知は JavaBeans に指定されているイベントモデルのガイドラインに準じます。JavaBeans イベントモデルの規定では、いったんイベント通知を送信したら、イベントソースをさらに変更する前にすべてのリスナーに通知する必要があります。また、配信の順序は保証されません。

通知は、2 つの別個のイベント、DocumentEventUndoableEditEvent として提供されます。API を介して Document が変更された場合、登録されているすべての DocumentListenersDocumentEvent が送信されます。Document の実装が元に戻す機能や再実行機能をサポートしている場合、登録されているすべての UndoableEditListenerUndoableEditEvent が送信されます。取り消し可能な編集が取り消された場合、Document から DocumentEvent をトリガして再度変更されたことが示されます。しかしこの場合、その編集は API を介して行われた Document の変更というよりむしろソースの変更であるため、UndoableEditEvent は生成されません。

前の文は、この図について説明しています。

上記の図に関して、左に示されているコンポーネントが青い矩形で表されているドキュメントオブジェクトを変更したと仮定します。ドキュメントは両コンポーネントのビューに DocumentEvent を送信して応答し、履歴バッファを保持しているリスニングロジックに UndoableEditEvent を送ります。

上記の図に関して、右に示されているコンポーネントが青い矩形で表されているドキュメントオブジェクトを変更したと仮定します。ドキュメントは両コンポーネントのビューに DocumentEvent を送信して応答し、履歴バッファを保持しているリスニングロジックに UndoableEditEvent を送ります。

履歴バッファがロールバックされると、つまり、最後の UndoableEdit が実行されないと、両ビューに DocumentEvent が送られ、実行されなかった変更が両ビューに反映されます。つまり、右のコンポーネントの変更が削除されます。履歴バッファが再度別の変更をロールバックすると、さらに別の DocumentEvent が両ビューに送られ実行されなかったドキュメントの変更を反映させます。つまり、左のコンポーネントの変更を削除します。

ドキュメントの変化に関係するメソッドは次のとおりです。

プロパティ

通常、Document の実装には実行時に関連したプロパティセットがあります。よく知られた 2 つのプロパティは、Document がどこから出されたものかを記述するときに使用する StreamDescriptionPropertyDocument に名前を付けるときに使用する TitleProperty です。プロパティに関係するメソッドは次のとおりです。

Document クラスの詳細は、「The Swing Connection」、および最も詳細な「The Element Interface」を参照してください。

関連項目:
DocumentEvent, DocumentListener, UndoableEditEvent, UndoableEditListener, Element, Position, AttributeSet

フィールドの概要
static String StreamDescriptionProperty
          ドキュメントを初期化するのに使うストリーム記述のプロパティ名です。
static String TitleProperty
          ドキュメントのタイトルがあれば、そのプロパティ名です。
 
メソッドの概要
 void addDocumentListener(DocumentListener listener)
          ドキュメントに変更が加えられたときに通知の受信を開始するように、指定されたオブザーバを登録します。
 void addUndoableEditListener(UndoableEditListener listener)
          ドキュメントに取り消し可能な編集が加えられたときに通知の受信を開始するように、指定されたオブザーバを登録します。
 Position createPosition(int offs)
          このメソッドを使用すると文字コンテンツのシーケンスの位置にマークを付けられます。
 Element getDefaultRootElement()
          ビューを要素構造に割り当てるほかの特定の機構が提供されていないかぎり、ビューのベースとなるルート要素を返します。
 Position getEndPosition()
          ドキュメントの末尾を表す位置を返します。
 int getLength()
          ドキュメント内の現在のコンテンツの文字数を返します。
 Object getProperty(Object key)
          ドキュメントに関連するプロパティを取得します。
 Element[] getRootElements()
          定義されているすべてのルート要素を返します。
 Position getStartPosition()
          ドキュメントの先頭を表す位置を返します。
 String getText(int offset, int length)
          ドキュメントの指定部分内にあるテキストを取り出します。
 void getText(int offset, int length, Segment txt)
          ドキュメントの指定部分内にあるテキストを取り出します。
 void insertString(int offset, String str, AttributeSet a)
          ドキュメントのコンテンツの文字列を挿入します。
 void putProperty(Object key, Object value)
          プロパティとドキュメントを関連付けます。
 void remove(int offs, int len)
          ドキュメントのコンテンツの一部を削除します。
 void removeDocumentListener(DocumentListener listener)
          指定されたオブザーバを通知リストから登録解除して、それ以上変更の更新を受信しないようにします。
 void removeUndoableEditListener(UndoableEditListener listener)
          指定されたオブザーバを通知リストから登録解除して、それ以上更新を受信しないようにします。
 void render(Runnable r)
          モデルが非同期的な更新をサポートしている場合、並行性が存在する状態でモデルを安全に描画できるようにします。
 

フィールドの詳細

StreamDescriptionProperty

static final String StreamDescriptionProperty
ドキュメントを初期化するのに使うストリーム記述のプロパティ名です。ドキュメントがストリームから初期化され、ストリームについてなんらかの定義がある場合には、これを使います。

関連項目:
定数フィールド値

TitleProperty

static final String TitleProperty
ドキュメントのタイトルがあれば、そのプロパティ名です。

関連項目:
定数フィールド値
メソッドの詳細

getLength

int getLength()
ドキュメント内の現在のコンテンツの文字数を返します。

戻り値:
文字数 >= 0

addDocumentListener

void addDocumentListener(DocumentListener listener)
ドキュメントに変更が加えられたときに通知の受信を開始するように、指定されたオブザーバを登録します。

パラメータ:
listener - 登録するオブザーバ
関連項目:
removeDocumentListener(javax.swing.event.DocumentListener)

removeDocumentListener

void removeDocumentListener(DocumentListener listener)
指定されたオブザーバを通知リストから登録解除して、それ以上変更の更新を受信しないようにします。

パラメータ:
listener - 登録するオブザーバ
関連項目:
addDocumentListener(javax.swing.event.DocumentListener)

addUndoableEditListener

void addUndoableEditListener(UndoableEditListener listener)
ドキュメントに取り消し可能な編集が加えられたときに通知の受信を開始するように、指定されたオブザーバを登録します。

パラメータ:
listener - 登録するオブザーバ
関連項目:
UndoableEditEvent

removeUndoableEditListener

void removeUndoableEditListener(UndoableEditListener listener)
指定されたオブザーバを通知リストから登録解除して、それ以上更新を受信しないようにします。

パラメータ:
listener - 登録するオブザーバ
関連項目:
UndoableEditEvent

getProperty

Object getProperty(Object key)
ドキュメントに関連するプロパティを取得します。

パラメータ:
key - null 以外のプロパティキー
戻り値:
プロパティ
関連項目:
putProperty(Object, Object)

putProperty

void putProperty(Object key,
                 Object value)
プロパティとドキュメントを関連付けます。提供される 2 つの標準的なプロパティキーは、StreamDescriptionPropertyTitleProperty です。作成者など他のプロパティも定義されます。

パラメータ:
key - null 以外のプロパティキー
value - プロパティの値
関連項目:
getProperty(Object)

remove

void remove(int offs,
            int len)
            throws BadLocationException
ドキュメントのコンテンツの一部を削除します。これは、例外がスローされないかぎり、DocumentEvent.EventType.REMOVE タイプの DocumentEvent を登録されているすべての DocumentListeners に送ります。リスナーへの通知は DocumentListeners の removeUpdate を呼び出して行います。

無理のない動作を同時に満たすために、変更を実行してからイベントを送信します。これは、削除通知が送信されるときまでには、ドキュメントは既に更新され createPosition が作成したマークも変更されているからです。削除の場合は、削除範囲の終点は始点に収納されており、削除範囲内の任意のマークは範囲の始点に収納されています。

図は、「The quick brown fox.」からの「quick」の削除を示しています。

削除の結果 Document 構造が変更された場合は、変更に応じてどの Elements が挿入、削除されたのかという詳細も、生成された DocumentEvent に格納されます。削除によって構造がどのように変化するかは Document の実装によります。

Document が元に戻す機能と再実行する機能をサポートする場合は、UndoableEditEvent も生成されます。

パラメータ:
offs - 先頭からのオフセット >= 0
len - 削除対象の文字数 >= 0
例外:
BadLocationException - 削除範囲の一部がドキュメントの有効部分でなかった場合。例外内の位置は、最初に検出された不正な位置
関連項目:
DocumentEvent, DocumentListener, UndoableEditEvent, UndoableEditListener

insertString

void insertString(int offset,
                  String str,
                  AttributeSet a)
                  throws BadLocationException
ドキュメントのコンテンツの文字列を挿入します。これは、例外がスローされないかぎり、DocumentEvent.EventType.INSERT タイプの DocumentEvent を登録された DocumentListeners に送ります。DocumentEvent の配信は DocumentListeners の insertUpdate を呼び出して行います。生成された DocumentEvent のオフセットと長さは、実際 Document にどのような変更がされたのかを示します。

図は、「The quick brown fox」への「quick」の挿入を示しています。

挿入の結果 Document 構造が変更された場合は、変更に応じてどの Elements が挿入、削除されたのかという詳細も、生成された DocumentEvent に格納されます。挿入によって構造がどのように変化するかは Document の実装によります。

Document が元に戻す機能と再実行する機能をサポートする場合は、UndoableEditEvent も生成されます。

パラメータ:
offset - コンテンツを挿入するドキュメントに対するオフセット >= 0。指定位置やその後の変更を追跡するすべての位置が移動
str - 挿入する文字列
a - 挿入されたコンテンツに関連している属性。属性がない場合は null
例外:
BadLocationException - 指定された挿入の位置が、ドキュメント内の有効な位置ではない場合
関連項目:
DocumentEvent, DocumentListener, UndoableEditEvent, UndoableEditListener

getText

String getText(int offset,
               int length)
               throws BadLocationException
ドキュメントの指定部分内にあるテキストを取り出します。

パラメータ:
offset - テキストの望ましい先頭を表す、ドキュメントに対するオフセット >= 0
length - 望ましい文字列の長さ >= 0
戻り値:
長さ >= 0 の String 内のテキスト
例外:
BadLocationException - 指定範囲の一部がドキュメントの有効部分でなかった場合。例外内の位置は、最初に検出された不正な位置

getText

void getText(int offset,
             int length,
             Segment txt)
             throws BadLocationException
ドキュメントの指定部分内にあるテキストを取り出します。

txt パラメータの partialReturn プロパティが false の場合、Segment で返されたデータは、要求された長さ全体になり、データの格納方法によってコピーになる場合とならない場合があります。partialReturn プロパティが true の場合は、コピーを作成しなくても返すことが可能なテキストの量だけが返されます。部分的に返すことで、ドキュメントの大部分をスキャンする場合のパフォーマンスが向上します。部分的に返す方法でドキュメント全体にアクセスする例を次に示します。



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

 

パラメータ:
offset - テキストの望ましい先頭を表す、ドキュメントに対するオフセット >= 0
length - 望ましい文字列の長さ >= 0
txt - テキストを返す先の Segment オブジェクト
例外:
BadLocationException - 指定範囲の一部がドキュメントの有効部分でなかった場合。例外内の位置は、最初に検出された不正な位置

getStartPosition

Position getStartPosition()
ドキュメントの先頭を表す位置を返します。返された位置は、変更を追跡してドキュメントの先頭に常に位置するために利用できます。

戻り値:
位置

getEndPosition

Position getEndPosition()
ドキュメントの末尾を表す位置を返します。返された位置は、変更を追跡してドキュメントの末尾に常に位置するために利用できます。

戻り値:
位置

createPosition

Position createPosition(int offs)
                        throws BadLocationException
このメソッドを使用すると文字コンテンツのシーケンスの位置にマークを付けられます。このマークを使用してコンテンツの中で行われた挿入や削除のような変更を追跡できます。挿入に関してのポリシーは、挿入位置がゼロでない限り、常に挿入は最も一般的なケースである現在の位置よりも前にするということです。挿入位置がゼロの場合は、元の位置に続けて挿入されます。

パラメータ:
offs - ドキュメントの先頭からのオフセット >= 0
戻り値:
位置
例外:
BadLocationException - 指定された位置が、関連するドキュメント内の有効な位置を表さない場合

getRootElements

Element[] getRootElements()
定義されているすべてのルート要素を返します。

一般的にドキュメント構造は 1 つだけですが、インタフェースはテキストデータに関して構造プロジェクションを任意の数だけ構築できるようにサポートしています。ドキュメントは、複数のドキュメント構造をサポートする複数のルート要素を持つことができます。以下に、例をいくつか示します。

戻り値:
ルート要素

getDefaultRootElement

Element getDefaultRootElement()
ビューを要素構造に割り当てるほかの特定の機構が提供されていないかぎり、ビューのベースとなるルート要素を返します。

戻り値:
ルート要素

render

void render(Runnable r)
モデルが非同期的な更新をサポートしている場合、並行性が存在する状態でモデルを安全に描画できるようにします。指定された実行可能ファイルは、その実行中に何の変更もなくモデルを安全に読み取る方法で実行されます。実行可能ファイルは、それ自身で変更を加えることはできません。

パラメータ:
r - モデルを描画するために使用する Runnable

JavaTM 2 Platform
Standard Ed. 5.0

バグの報告と機能のリクエスト
さらに詳しい API リファレンスおよび開発者ドキュメントについては、Java 2 SDK SE 開発者用ドキュメントを参照してください。開発者向けの詳細な解説、概念の概要、用語の定義、バグの回避策、およびコード実例が含まれています。

Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。