javax.swing.text
인터페이스 Document

기존의 서브 인터페이스의 일람:

StyledDocument

기존의 구현 클래스의 일람:

AbstractDocument , DefaultStyledDocument , HTMLDocument , PlainDocument

public interface Document

Document 는 swing 텍스트 컴퍼넌트의 모델이 되는 텍스트의 컨테이너입니다. 이 인터페이스가 목표로 하는 곳(중)은 plaintext의 텍스트 필드와 같이 매우 심플한 것으로부터 HTML 또는 XML 와 같이 복잡한 것에까지 대응할 수 있도록(듯이) 슬캘링 하는 것입니다.

컨텐츠

무엇보다 심플한 레벨에서는, 텍스트는 선상에 성장하는 일련의 문자로서 형성됩니다. 국제화에 대비해 Swing 텍스트 모델은 unicode 문자를 사용합니다. 일반적으로, 텍스트 컴퍼넌트에 표시되는 문자 순서는 컴퍼넌트의 「컨텐츠」라고 불립니다.

순서내의 장소를 참조하기 위해서 2 문자간의 위치 좌표를 사용합니다. 아래의 그림에 나타내도록(듯이), 텍스트 문서내의 장소는 위치로서 또는 오프셋(offset)로서 가리킬 수가 있습니다. 이 정도치는 제로로부터 시작됩니다.

예를 들어, 전의 그림과 같이 문서의 컨텐츠가 「The quick brown fox」라고 하는 순서의 경우, 「The」의 전의 장소는 0 으로, 「The」의 뒤와 거기에 계속되는 공백의 사이의 장소는 3 이 됩니다. 「The」라고 하는 순서의 전문자 순서를 범위라고 부릅니다.

다음의 메소드로 컨텐츠를 구성하는 문자 데이터에 액세스 할 수 있습니다.

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

구조

텍스트가 단조로운 컨텐츠로서 나타내지는 것은 거의 없습니다. 오히려, 일반적으로, 텍스트는 컨텐츠와 관련한 구조가 되어 있습니다. 정확하게 어느 구조가 모델이 되어 있을까는 특정의 Document 구현에 의해 다릅니다. 단순한 텍스트 필드와 같이 구조가 없는 것 같은 심플한 것도 있으면, 아래의 그림과 같은 것도 있습니다.

구조 단위, 즉 트리의 노드는 Element 인터페이스로 나타낼 수 있습니다. 각 Element 는 속성세트에 의해 태그를 붙일 수가 있습니다. 이런 이름과 값의 페어의 속성은 AttributeSet 인터페이스로 정의됩니다.

다음의 메소드로 문서 구조에 액세스 할 수 있습니다.

• getDefaultRootElement
• getRootElements

변경

모든 문서는 간단한 텍스트의 추가 및 삭제를 할 수 있을 필요가 있습니다. 일반적으로, 텍스트는 키보드 또는 마우스의 제스처(gesture)로 삽입, 삭제를 할 수 있습니다. 삽입, 삭제를 한 결과 문서 구조에 어떤 영향이 있을까는 모두 문서의 구현에 의합니다.

다음의 메소드는 문서 컨텐츠의 변화에 관계 붙일 수 있고 있습니다.

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

통지

Document 로 변경이 생겼을 경우는 관계자에게 통지할 필요가 있습니다. 변경 통지는 JavaBeans 로 지정되고 있는 이벤트 모델의 가이드 라인에 준합니다. JavaBeans 이벤트 모델의 규정에서는, 일단 이벤트 통지를 송신하면(자), 이벤트 소스를 한층 더 변경하기 전에 모든 청취자에게 통지할 필요가 있습니다. 또, 전달의 순서는 보증되지 않습니다.

통지는, 2 개의 별개의 이벤트,DocumentEvent 과 UndoableEditEvent 로서 제공됩니다. API 를 개입시켜 Document 가 변경되었을 경우, 등록되어 모든 DocumentListeners 에 DocumentEvent 가 송신됩니다. Document 의 구현이 바탕으로 되돌리는 기능이나 재실행 기능을 지원하고 있는 경우, 등록되어 모든 UndoableEditListener 에 UndoableEditEvent 가 송신됩니다. 취소해 가능한 편집이 삭제되었을 경우, Document 로부터 DocumentEvent 를 트리거해 재차 변경되었던 것(적)이 나타납니다. 그러나 이 경우, 그 편집은 API 를 개입시켜 행해진 Document 의 변경이라고 하는 것보다 오히려 소스의 변경이기 (위해)때문에,UndoableEditEvent 는 생성되지 않습니다.

상기의 그림에 관해서, 왼쪽으로 나타나고 있는 컴퍼넌트가 푸른 구형으로 나타내지고 있는 문서 객체를 변경했다고 가정합니다. 문서는 양컴퍼넌트의 뷰에 DocumentEvent 를 송신해 응답해, 이력 버퍼를 보관 유지하고 있는 리스닝로직크에 UndoableEditEvent 를 보냅니다.

상기의 그림에 관해서, 오른쪽으로 나타나고 있는 컴퍼넌트가 푸른 구형으로 나타내지고 있는 문서 객체를 변경했다고 가정합니다. 문서는 양컴퍼넌트의 뷰에 DocumentEvent 를 송신해 응답해, 이력 버퍼를 보관 유지하고 있는 리스닝로직크에 UndoableEditEvent 를 보냅니다.

이력 버퍼가 롤백(rollback) 되면(자), 즉, 마지막 UndoableEdit 가 실행되지 않으면 양뷰에 DocumentEvent 가 보내져 실행되지 않았던 변경이 양뷰에 반영됩니다. 즉, 오른쪽의 컴퍼넌트의 변경이 삭제됩니다. 이력 버퍼가 재차별의 변경을 롤백(rollback) 하면(자), 한층 더 다른 DocumentEvent 가 양뷰에 보내지고 실행되지 않았던 문서의 변경을 반영시킵니다. 즉, 왼쪽의 컴퍼넌트의 변경을 삭제합니다.

문서의 변화에 관계하는 메소드는 다음과 같습니다.

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

프로퍼티

일반적으로, Document 의 구현에는 실행시에 관련한 프로퍼티 세트가 있습니다. 잘 알려진 2 개의 프로퍼티은,Document 가 어디에서 나온 것인지를 기술할 경우에 사용하는 StreamDescriptionProperty 와 Document 에 이름을 붙일 때 사용하는 TitleProperty 입니다. 프로퍼티에 관계하는 메소드는 다음과 같습니다.

• 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) 모델이 비동기적인 갱신을 지원하고 있는 경우, 병행성이 존재하는 상태로 모델을 안전하게 draw 할 수 있도록(듯이) 합니다.

필드의 상세

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 개의 표준적인 프로퍼티 키는,StreamDescriptionProperty 와 TitleProperty 입니다. 작성자등 다른 프로퍼티도 정의됩니다.

파라미터:

key - null 이외의 프로퍼티 키

value - 프로퍼티의 값

관련 항목:

getProperty(Object)

remove

void remove(int offs,
            int len)
            throws BadLocationException 

문서의 컨텐츠의 일부를 삭제합니다. 이것은, 예외가 throw 되지 않는 한, DocumentEvent.EventType.REMOVE 타입의 DocumentEvent 가 등록되어 모든 DocumentListeners 에 보냅니다. 청취자에게로의 통지는 DocumentListeners 의 removeUpdate 를 호출해 실시합니다.

무리가 없는 동작을 동시에 채우기 위해서(때문에), 변경을 실행하고 나서 이벤트를 송신합니다. 이것은, 삭제 통지가 송신될 때까지는, 문서는 이미 갱신되고 createPosition 가 작성한 마크도 변경되고 있기 때문입니다. 삭제의 경우는, 삭제 범위의 종점은 시점에 수납되고 있어 삭제 범위내의 임의의 마크는 범위의 시점에 수납되고 있습니다.

삭제의 결과 Document 구조가 변경되었을 경우는, 변경에 응해 어느 Elements 가 삽입, 삭제되었는지라고 하는 상세도, 생성된 DocumentEvent 에 포함됩니다. 삭제에 의해 구조가 어떻게 변화할까는 Document 의 구현에 의합니다.

Document 가 바탕으로 되돌리는 기능과 재실행하는 기능을 지원하는 경우는, UndoableEditEvent 도 생성됩니다.

파라미터:

offs - 선두로부터의 오프셋(offset) >= 0

len - 삭제 대상의 문자수 >= 0

예외:

BadLocationException - 삭제 범위의 일부가 문서의 유효한 부분이 아니었던 경우. 예외내의 위치는, 최초로 검출된 부정한 위치

관련 항목:

DocumentEvent , DocumentListener , UndoableEditEvent , UndoableEditListener

insertString

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

컨텐츠의 캐릭터 라인을 삽입합니다. 이것은, 예외가 throw 되지 않는 한, DocumentEvent.EventType.INSERT 타입의 DocumentEvent 를 등록된 DocumentListeners 에 보냅니다. DocumentEvent 의 전달은 DocumentListeners 의 insertUpdate 를 호출해 실시합니다. 생성된 DocumentEvent 의 오프셋(offset)와 길이는, 실제 Document 에 어떠한 변경이 되었는지를 나타냅니다.

삽입의 결과 Document 구조가 변경되었을 경우는, 변경에 응해 어느 Elements 가 삽입, 삭제되었는지라고 하는 상세도, 생성된 DocumentEvent 에 포함됩니다. 삽입에 의해 구조가 어떻게 변화할까는 Document 의 구현에 의합니다.

Document 가 바탕으로 되돌리는 기능과 재실행하는 기능을 지원하는 경우는, UndoableEditEvent 도 생성됩니다.

파라미터:

offset - 컨텐츠를 삽입하는 문서내의 오프셋(offset). 0 이상. 지정 위치나 그 뒤의 변경을 추적한다 모든 위치가 이동

str - 삽입하는 캐릭터 라인

a - 삽입된 컨텐츠에 관련짓는 속성. 속성이 없는 경우는 null 도 가능

예외:

BadLocationException - 지정된 삽입 위치가 문서내의 유효한 위치가 아닌 경우

관련 항목:

DocumentEvent , DocumentListener , UndoableEditEvent , UndoableEditListener

getText

String  getText(int offset,
               int length)
               throws BadLocationException 

문서의 지정 부분내에 있는 텍스트를 가져옵니다.

파라미터:

offset - 텍스트의 바람직한 개시 위치를 나타내는, 문서의 오프셋(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 someting with text
       nleft -= text.count;
       offs += text.count;
   }

 

파라미터:

offset - 텍스트의 바람직한 개시 위치를 나타내는, 문서의 오프셋(offset). 0 이상

length - 바람직한 캐릭터 라인의 길이 >= 0

txt - 텍스트를 돌려주는 앞의 Segment 객체

예외:

BadLocationException - 범위의 일부가 문서의 유효한 부분이 아니었던 경우. 예외내의 위치는, 최초로 검출된 부정한 위치

getStartPosition

Position  getStartPosition()

문서의 선두를 나타내는 위치를 돌려줍니다. 반환된 위치는, 변경을 추적해 문서의 선두에 항상 위치하기 위해서 이용할 수 있습니다.

반환값:

위치

getEndPosition

Position  getEndPosition()

문서의 말미를 나타내는 위치를 돌려줍니다. 반환된 위치는, 변경을 추적해 문서의 말미에 항상 위치하기 위해서 이용할 수 있습니다.

반환값:

위치

createPosition

Position  createPosition(int offs)
                        throws BadLocationException 

이 메소드를 사용한다고 문자 컨텐츠의 순서의 위치에 마크를 붙일 수 있습니다. 이 마크를 사용해 컨텐츠 중(안)에서 행해진 삽입이나 삭제와 같은 변경을 추적할 수 있습니다. 삽입에 관한 정책는, 삽입 위치가 제로가 아닌 한, 항상 삽입은 가장 일반적인 케이스인 현재의 위치보다 앞에 둔다고 하는 것입니다. 삽입 위치가 제로의 경우는, 원래의 위치에 이어 삽입됩니다.

파라미터:

offs - 문서의 선두로부터의 오프셋(offset) >= 0

반환값:

위치

예외:

BadLocationException - 지정된 위치가, 관련지을 수 있었던 문서내의 유효한 위치를 나타내지 않는 경우

getRootElements

Element [] getRootElements()

정의 떠날 수 있어 모든 루트 요소를 돌려줍니다.

일반적으로 문서 구조는 1 개 뿐입니다만, 인터페이스는 텍스트 데이터에 관해서 구조 프로젝션을 임의의 수만큼 구축할 수 있도록(듯이) 지원하고 있습니다. 문서는, 복수의 문서 구조를 지원하는 복수의 루트 요소를 가질 수가 있습니다. 다음에, 예를 몇개인가 가리킵니다.

• 텍스트의 방향
• 자구 토큰 스트림
• 구문나무
• 네이티브 이외의 형식에의 변환
• 변경의 스펙
• 주석

반환값:

루트 요소

getDefaultRootElement

Element  getDefaultRootElement()

루트 요소를 돌려줍니다. 요소의 구조에 뷰를 할당하는 다른 기구가 제공되지 않는 한, 이 루트 요소가 뷰의 베이스가 됩니다.

반환값:

루트 요소

render

void render(Runnable  r)

모델이 비동기적인 갱신을 지원하고 있는 경우, 병행성이 존재하는 상태로 모델을 안전하게 draw 할 수 있도록(듯이) 합니다. 지정된 실행 가능 파일은, 그 실행중으로 아무 변경도 없게 모델을 안전하게 읽어내는 방법으로 실행됩니다. 실행 가능 파일은, 그것 자신으로 변경을 더할 수 없습니다.

파라미터:

r - 모델을 draw 하기 위해서 사용하는 Runnable