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

변경

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

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

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

필드의 상세

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 something 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)

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

파라미터:

r - 모델을 렌더링 하기 위해서 사용하는 Runnable