-
- 既知のすべてのサブインタフェース:
StyledDocument
- 既知のすべての実装クラス:
AbstractDocument
,DefaultStyledDocument
,HTMLDocument
,PlainDocument
public interface Document
Document
はswingテキスト・コンポーネントのモデルとなるテキストのコンテナです。 このインタフェースのめざすところはプレーン・テキストのテキスト・フィールドのように非常にシンプルなものからHTMLまたはXMLのように複雑なものにまで対応できるようにスケーリングすることです。Content
もっともシンプルなレベルでは、テキストは線状に伸びる一連の文字として形成されます。 国際化に備えてSwingテキスト・モデルはunicode文字を使用します。 通常、テキスト・コンポーネントに表示される文字シーケンスはコンポーネントのコンテンツと呼ばれます。
シーケンス内の場所を参照するために2文字間の位置座標を使用します。 下の図に示すように、テキスト・ドキュメント内の場所は位置として、またはオフセットとして示すことができます。 この位置はゼロから始まります。
たとえば、前の図のようにドキュメントのコンテンツが「The quick brown fox」というシーケンスの場合、「The」の前の場所は0で、「The」の後とそれに続く空白の間の場所は3となります。 「The」というシーケンスの全文字シーケンスを範囲と呼びます。
次のメソッドでコンテンツを構成する文字データへアクセスできます。
構造
テキストが単調なコンテンツとして表されることはほとんどありません。 むしろ、通常、テキストはコンテンツと関連した構造になっています。 正確にどの構造がモデルになっているかは特定のDocument実装により異なります。 単純なテキスト・フィールドのように構造がないようなシンプルなものもあれば、下の図のようなものもあります。
構造単位、すなわちツリーのノードはElementインタフェースで表せます。 各Elementは属性のセットによりタグを付けることができます。 こういう名前と値のペアの属性はAttributeSetインタフェースで定義されます。
次のメソッドでドキュメント構造へアクセスできます。
Mutations
すべてのドキュメントは簡単なテキストの追加および削除ができる必要があります。 通常、テキストはキーボードまたはマウスのジェスチャで挿入、削除ができます。 挿入、削除をした結果ドキュメント構造にどういう影響があるかはすべてドキュメントの実装によります。
次のメソッドはドキュメント・コンテンツの変化に関係付けられています。
insertString(int, java.lang.String, javax.swing.text.AttributeSet)
remove(int, int)
createPosition(int)
Notification
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が両ビューに送られ、実行されなかったドキュメントの変更を反映させます。つまり、左のコンポーネントの変更を削除します。
ドキュメントの変化に関係するメソッドは次のとおりです。
addDocumentListener(DocumentListener)
removeDocumentListener(DocumentListener)
addUndoableEditListener(UndoableEditListener)
removeUndoableEditListener(UndoableEditListener)
プロパティ
通常、Documentの実装には実行時に関連したプロパティ・セットがあります。 よく知られた2つのプロパティは、
Document
がどこから出されたものかを記述するときに使用するStreamDescriptionPropertyとDocument
に名前を付けるときに使用するTitlePropertyです。 プロパティに関係するメソッドは次のとおりです。Document
クラスの詳細は、The Swing Connection、およびもっとも詳細なThe Element Interfaceを参照してください。
-
-
フィールドのサマリー
フィールド 修飾子と型 フィールド 説明 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)
モデルが非同期的な更新をサポートしている場合、並行性が存在する状態でモデルを安全に描画できるようにします。
-
-
-
メソッドの詳細
-
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つの標準的なプロパティ・キーは、StreamDescriptionProperty
およびTitleProperty
です。 作成者などほかのプロパティも定義されます。- パラメータ:
key
-null
以外のプロパティ・キーvalue
- プロパティ値- 関連項目:
getProperty(Object)
-
remove
void remove(int offs, int len) throws BadLocationException
ドキュメントのコンテンツの一部を削除します。 これは、例外がスローされないかぎり、DocumentEvent.EventType.REMOVEタイプのDocumentEventを登録されているすべてのDocumentListenersに送ります。 リスナーへの通知はDocumentListenersのremoveUpdateを呼び出して行います。無理のない動作を同時に満たすために、変更を実行してからイベントを送信します。 これは、削除通知が送信されるときまでには、ドキュメントはすでに更新され
createPosition
が作成したマークも変更されているからです。 削除の場合は、削除範囲の終点は始点に収納されており、削除範囲内の任意のマークは範囲の始点に収納されています。削除の結果Document構造が変更された場合は、変更に応じてどのElementsが挿入、削除されたのかという詳細も、生成されたDocumentEventに格納されます。 削除によって構造がどのように変化するかはDocumentの実装によります。
Documentが元に戻す機能と再実行する機能をサポートする場合は、UndoableEditEventも生成されます。
- パラメータ:
offs
- 先頭からのオフセット>= 0len
- 削除対象の文字数>= 0- 例外:
BadLocationException
- 削除範囲の一部がドキュメントの有効な部分でなかった場合。 例外内の位置は、最初に検出された不正な位置。- 関連項目:
DocumentEvent
,DocumentListener
,UndoableEditEvent
,UndoableEditListener
-
insertString
void insertString(int offset, String str, AttributeSet a) throws BadLocationException
コンテンツの文字列を挿入します。 これは、例外がスローされないかぎり、DocumentEvent.EventType.INSERTタイプのDocumentEventを登録されたDocumentListenerに送ります。 DocumentEventの配信はDocumentListenerのinsertUpdateを呼び出して行います。 生成されたDocumentEventのオフセットと長さは、実際Documentにどのような変更がされたのかを示します。挿入の結果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
- テキストの望ましい開始位置を表す、ドキュメントのオフセット>= 0length
- 望ましい文字列の長さ>= 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 someting with text nleft -= text.count; offs += text.count; }
- パラメータ:
offset
- テキストの望ましい開始位置を表す、ドキュメントのオフセット>= 0length
- 望ましい文字列の長さ>= 0txt
- テキストを返す先の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
-
-