|
JavaTM 2 Platform Standard Ed. 5.0 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
public interface Document
Document は swing テキストコンポーネントのモデルとなるテキストのコンテナです。このインタフェースのめざすところはプレーンテキストのテキストフィールドのように非常にシンプルなものから HTML または XML のように複雑なものにまで対応できるようにスケーリングすることです。
コンテンツ
最もシンプルなレベルでは、テキストは線状に伸びる一連の文字として形成されます。国際化に備えて Swing テキストモデルは unicode 文字を使用します。通常、テキストコンポーネントに表示される文字シーケンスはコンポーネントの「コンテンツ」と呼ばれます。
シーケンス内の場所を参照するために 2 文字間の位置座標を使用します。下の図に示すように、テキストドキュメント内の場所は位置として、またはオフセットとして示すことができます。この位置はゼロから始まります。
たとえば、前の図のようにドキュメントのコンテンツが「The quick brown fox」というシーケンスの場合、「The」の前の場所は 0 で、「The」の後とそれに続く空白の間の場所は 3 となります。「The」というシーケンスの全文字シーケンスを「範囲」と呼びます。
次のメソッドでコンテンツを構成する文字データへアクセスできます。
構造
テキストが単調なコンテンツとして表されることはほとんどありません。むしろ、通常、テキストはコンテンツと関連した構造になっています。正確にどの構造がモデルになっているかは特定の Document 実装により異なります。単純なテキストフィールドのように構造がないようなシンプルなものもあれば、下の図のようなものもあります。
構造単位、すなわちツリーのノードは Element インタフェースで表せます。各 Element は属性のセットによりタグを付けることができます。こういう名前と値のペアの属性は AttributeSet インタフェースで定義されます。
次のメソッドでドキュメント構造へアクセスできます。
変更
すべてのドキュメントは簡単なテキストの追加および削除ができる必要があります。通常、テキストはキーボードまたはマウスのジェスチャーで挿入、削除ができます。挿入、削除をした結果ドキュメント構造にどういう影響があるかはすべてドキュメントの実装によります。
次のメソッドはドキュメントコンテンツの変化に関係付けられています。
通知
Document に変更が生じた場合は関係者に通知する必要があります。変更通知は JavaBeans に指定されているイベントモデルのガイドラインに準じます。JavaBeans イベントモデルの規定では、いったんイベント通知を送信したら、イベントソースをさらに変更する前にすべてのリスナーに通知する必要があります。また、配信の順序は保証されません。
通知は、2 つの別個のイベント、DocumentEvent と UndoableEditEvent として提供されます。API を介して Document が変更された場合、登録されているすべての DocumentListeners に DocumentEvent が送信されます。Document の実装が元に戻す機能や再実行機能をサポートしている場合、登録されているすべての UndoableEditListener に UndoableEditEvent が送信されます。取り消し可能な編集が取り消された場合、Document から DocumentEvent をトリガして再度変更されたことが示されます。しかしこの場合、その編集は API を介して行われた Document の変更というよりむしろソースの変更であるため、UndoableEditEvent は生成されません。
上記の図に関して、左に示されているコンポーネントが青い矩形で表されているドキュメントオブジェクトを変更したと仮定します。ドキュメントは両コンポーネントのビューに DocumentEvent を送信して応答し、履歴バッファを保持しているリスニングロジックに UndoableEditEvent を送ります。
上記の図に関して、右に示されているコンポーネントが青い矩形で表されているドキュメントオブジェクトを変更したと仮定します。ドキュメントは両コンポーネントのビューに DocumentEvent を送信して応答し、履歴バッファを保持しているリスニングロジックに UndoableEditEvent を送ります。
履歴バッファがロールバックされると、つまり、最後の UndoableEdit が実行されないと、両ビューに DocumentEvent が送られ、実行されなかった変更が両ビューに反映されます。つまり、右のコンポーネントの変更が削除されます。履歴バッファが再度別の変更をロールバックすると、さらに別の DocumentEvent が両ビューに送られ実行されなかったドキュメントの変更を反映させます。つまり、左のコンポーネントの変更を削除します。
ドキュメントの変化に関係するメソッドは次のとおりです。
プロパティ
通常、Document の実装には実行時に関連したプロパティセットがあります。よく知られた 2 つのプロパティは、Document がどこから出されたものかを記述するときに使用する StreamDescriptionProperty と Document に名前を付けるときに使用する 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)
モデルが非同期的な更新をサポートしている場合、並行性が存在する状態でモデルを安全に描画できるようにします。 |
| フィールドの詳細 |
|---|
static final String StreamDescriptionProperty
static final String TitleProperty
| メソッドの詳細 |
|---|
int getLength()
void addDocumentListener(DocumentListener listener)
listener - 登録するオブザーバremoveDocumentListener(javax.swing.event.DocumentListener)void removeDocumentListener(DocumentListener listener)
listener - 登録するオブザーバaddDocumentListener(javax.swing.event.DocumentListener)void addUndoableEditListener(UndoableEditListener listener)
listener - 登録するオブザーバUndoableEditEventvoid removeUndoableEditListener(UndoableEditListener listener)
listener - 登録するオブザーバUndoableEditEventObject getProperty(Object key)
key - null 以外のプロパティキー
putProperty(Object, Object)
void putProperty(Object key,
Object value)
StreamDescriptionProperty と TitleProperty です。作成者など他のプロパティも定義されます。
key - null 以外のプロパティキーvalue - プロパティの値getProperty(Object)
void remove(int offs,
int len)
throws BadLocationException
無理のない動作を同時に満たすために、変更を実行してからイベントを送信します。これは、削除通知が送信されるときまでには、ドキュメントは既に更新され createPosition が作成したマークも変更されているからです。削除の場合は、削除範囲の終点は始点に収納されており、削除範囲内の任意のマークは範囲の始点に収納されています。
削除の結果 Document 構造が変更された場合は、変更に応じてどの Elements が挿入、削除されたのかという詳細も、生成された DocumentEvent に格納されます。削除によって構造がどのように変化するかは Document の実装によります。
Document が元に戻す機能と再実行する機能をサポートする場合は、UndoableEditEvent も生成されます。
offs - 先頭からのオフセット >= 0len - 削除対象の文字数 >= 0
BadLocationException - 削除範囲の一部がドキュメントの有効部分でなかった場合。例外内の位置は、最初に検出された不正な位置DocumentEvent,
DocumentListener,
UndoableEditEvent,
UndoableEditListener
void insertString(int offset,
String str,
AttributeSet a)
throws BadLocationException
挿入の結果 Document 構造が変更された場合は、変更に応じてどの Elements が挿入、削除されたのかという詳細も、生成された DocumentEvent に格納されます。挿入によって構造がどのように変化するかは Document の実装によります。
Document が元に戻す機能と再実行する機能をサポートする場合は、UndoableEditEvent も生成されます。
offset - コンテンツを挿入するドキュメントに対するオフセット >= 0。指定位置やその後の変更を追跡するすべての位置が移動str - 挿入する文字列a - 挿入されたコンテンツに関連している属性。属性がない場合は null
BadLocationException - 指定された挿入の位置が、ドキュメント内の有効な位置ではない場合DocumentEvent,
DocumentListener,
UndoableEditEvent,
UndoableEditListener
String getText(int offset,
int length)
throws BadLocationException
offset - テキストの望ましい先頭を表す、ドキュメントに対するオフセット >= 0length - 望ましい文字列の長さ >= 0
BadLocationException - 指定範囲の一部がドキュメントの有効部分でなかった場合。例外内の位置は、最初に検出された不正な位置
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 - テキストの望ましい先頭を表す、ドキュメントに対するオフセット >= 0length - 望ましい文字列の長さ >= 0txt - テキストを返す先の Segment オブジェクト
BadLocationException - 指定範囲の一部がドキュメントの有効部分でなかった場合。例外内の位置は、最初に検出された不正な位置Position getStartPosition()
Position getEndPosition()
Position createPosition(int offs)
throws BadLocationException
offs - ドキュメントの先頭からのオフセット >= 0
BadLocationException - 指定された位置が、関連するドキュメント内の有効な位置を表さない場合Element[] getRootElements()
一般的にドキュメント構造は 1 つだけですが、インタフェースはテキストデータに関して構造プロジェクションを任意の数だけ構築できるようにサポートしています。ドキュメントは、複数のドキュメント構造をサポートする複数のルート要素を持つことができます。以下に、例をいくつか示します。
Element getDefaultRootElement()
void render(Runnable r)
r - モデルを描画するために使用する Runnable
|
JavaTM 2 Platform Standard Ed. 5.0 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。