javax.swing.text
介面 Document

所有已知子介面：

StyledDocument

所有已知實作類別：

AbstractDocument, DefaultStyledDocument, HTMLDocument, PlainDocument

public interface Document

Document 是一個作為 swing 文本元件模型的文本容器。此介面的目標是為了滿足不同的文檔處理需要，從非常簡單的文檔（純文本 textfield）到非常複雜的文檔（例如，HTML 或 XML 文檔）。

內容

在最簡單的級別，文本可用一個線性的字元序列模型表示。為支持國際化，Swing 文本模型使用 unicode 字元。顯示在文本元件中的字元序列一般稱為元件的內容。

要參考序列中的位置，使用的是兩個字元之間的坐標。如下圖所示，文本文檔中位置可稱為一個位置或一個偏移量。位置是從零開始的。

此例中，如前圖所示，如果文檔的內容為序列 "The quick brown fox" ，"The" 之前的位置為 0，位於 "The" 之後、它後面的空白之前的位置為 3。序列 "The" 中的整個字元序列稱為一個範圍。

下列方法提供對組成內容的字元資料的存取。

• getLength()
• getText(int, int)
• getText(int, int, Segment)

結構

只將文本表示為一般的內容並不常見。更多的情況下，文本都通常具有與其關聯的某種結構。具體建構成哪種結構取決於特定的 Document 實作。它可以簡單到沒有結構（即簡單的文本欄位），也可以是類似下面的圖。

結構單位（即階層樹的節點）由 Element 介面參考。每個 Element 都可用一組屬性標記。這些屬性（名稱/值對）由 AttributeSet 介面定義。

下面的方法提供對文檔結構的存取。

• getDefaultRootElement
• getRootElements

可變

所有的文檔都需要能夠添加和移除簡單的文本。通常，通過鍵盤或鼠標動作添加和移除文本。插入和移除對文檔結構有何影響完全取決於文檔的實作。

下列方法與文檔內容的變化相關：

• insertString(int, String, AttributeSet)
• remove(int, int)
• createPosition(int)

通知

Document 的改變必須傳送給相關的觀察者。更改通知遵守為 JavaBeans 指定的事件模型大綱。在 JavaBeans 事件模型中，一旦指派了一個事件通知，必須在事件源發生進一步的更改之前通知所有的偵聽器。此外，無法保證傳送的順序。

通知以兩個獨立的事件提供，DocumentEvent 和 UndoableEditEvent。如果通過 Document 的 api 對其進行改變，將對所有註冊的 DocumentListeners 發送一個 DocumentEvent。如果 Document 實作支持撤消/重複功能，UndoableEditEvent 將發送到所有註冊的 UndoableEditListener 上。如果對可撤消的編輯進行撤消，應從 Document 觸發 DocumentEvent 以指示又進行了更改。但是這種情況下不應產生任何 UndoableEditEvent，因為編輯實際上是更改的源，而不是通過其 api 對 Document 進行的改變。

上圖中假設左面顯示的元件改變了藍色矩形表示的文本物件。文檔通過對兩個元件視圖指派 DocumentEvent 進行回應，並向偵聽邏輯發送 UndoableEditEvent，以保留歷史緩衝區。

現在假定右面顯示的元件改變相同的文檔。同樣，文檔對兩個元件視圖指派 DocumentEvent 並對保留歷史緩衝區的偵聽邏輯發送 UndoableEditEvent。

如果歷史緩衝區因此回滾（即撤消上一個 UndoableEdit），將對兩個視圖發送 DocumentEvent，導致二者都反映出對文檔的撤消改動（即移除右面的元件的改動）。如果歷史緩衝區再次回滾另一個更改，將對兩個視圖發送另外的 DocumentEvent，導致它們反映出對文檔的撤消改動，即移除左面的元件的改動。

與觀察文檔的改動相關的方法有：

• addDocumentListener(DocumentListener)
• removeDocumentListener(DocumentListener)
• addUndoableEditListener(UndoableEditListener)
• removeUndoableEditListener(UndoableEditListener)

屬性

文檔實作通常具有在運行時與之關聯的某組屬性。兩個最常見的屬性是 StreamDescriptionProperty 和 TitleProperty，前者可描述 Document 的來源，後者可用於命名 Document。與這些屬性相關的方法有：

• getProperty(Object)
• putProperty(Object, Object)

有關 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)

將屬性與文檔關聯。提供兩個標準屬性鍵：StreamDescriptionProperty 和 TitleProperty。也可以定義其他屬性，如 author。

參數：

key - 非 null 屬性鍵

value - 屬性值

另請參見：

getProperty(Object)

remove

void remove(int offs,
            int len)
            throws BadLocationException

移除文檔的部分內容。這將導致對註冊的 DocumentListener 發送型別為 DocumentEvent.EventType.REMOVE 的 DocumentEvent，除非拋出異常。通過在 DocumentListener 上調用 removeUpdate 方法，通知被發送到偵聽器。

為確保共時情況下的合理行為，事件在改動發生之後指派。這意味著在指派移除通知之前，文檔已經更新並且由 createPosition 創建的任何標記已更改。對於移除的情況，移除範圍的結束折疊至範圍的開始，移除範圍內的任何標記都折疊至範圍的開始。

如果移除導致 Document 結構更改，產生的 DocumentEvent 中還將包含更改所涉及的插入和移除 Element 的細節。移除對結建構成的更改則具體取決於 Document 的實作。

如果 Document 支持撤消/重複，還將產生 UndoableEditEvent。

參數：

offs - 起始位置的偏移量，該值 >= 0

len - 要移除的字元數，該值 >= 0

拋出：

BadLocationException - 移除範圍的有些部分不是文檔的有效部分。異常中的位置為遇到的第一個損壞位置。

另請參見：

DocumentEvent, DocumentListener, UndoableEditEvent, UndoableEditListener

insertString

void insertString(int offset,
                  String str,
                  AttributeSet a)
                  throws BadLocationException

插入內容字元串。這將導致對註冊的 DocumentListener 發送型別為 DocumentEvent.EventType.INSERT 的 DocumentEvent，除非拋出異常。通過在 DocumentListener 上調用 insertUpdate 方法傳送 DocumentEvent。產生的 DocumentEvent 的偏移量和長度將指示對 Document 實際進行的更改。

如果插入導致 Document 結構更改，有關更改涉及的插入和移除的 Element 的細節將包含在產生的 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 的字元串形式返回文本。

拋出：

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 - 文檔中代表所需文本起始位置的偏移量，該值 >= 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()

返回定義的所有根元素。

通常只有一個文檔結構，但是此介面支持在文本資料上建構任意數的結構投影。文檔可以有多個根元素以支持多文檔結構。一些範例如下：

• 文本方向。
• 詞法解析標記串流。
• 解析階層樹。
• 轉換為本機格式以外的格式。
• 修改規範。
• 註釋。

返回：

根元素

getDefaultRootElement

Element getDefaultRootElement()

返回視圖賴以存在的根元素，除非提供了向元素結構指定視圖的其他機制。

返回：

根元素

render

void render(Runnable r)

如果模型支持非同步更新，則允許在共時情況下安全呈現模型。給定的可運行程序的執行方式是，在可運行程序執行時安全讀取模型且不作任何更改。可運行程序本身不 作任何改變。

參數：

r - 用於呈現模型的 Runnable