javax.swing.text

The text content for any component is stored in a model object called a Document. Chapter 20, and Chapter 21, cover the complex Swing document model in considerable detail. This model allows you to represent highly structured text supporting multiple fonts and colors, and even embedded Icons and Components. 组件的文本内容存储在Document中,覆盖了复杂的Swing文件对象模型,这个模型允许你表现高度结构化的文本,支持多种字体和颜色,甚至是内嵌图片或组件 Swing text components allow you to customize certain aspects of the look-and-feel without much work. This includes the creation of custom carets (cursor) and custom highlighting, as well as the definition of custom key bindings, allowing you to associate Actions with special key combinations. These features are covered in Chapter 22. 文本组件(Text Component)允许你在进行少量工作的同时定制look and feel,包括定义某种鼠标样式,定义高亮显示,同样也包括自定义快捷键,并将特殊的操作关联到这些快捷键上 As usual, each text component delegates its painting tasks to a UI delegate. Unlike the other Swing UI delegates, the TextUI relies heavily on a large number of additional classes that extend a common base class called View. These classes are responsible for the details of layout, including issues such as alignment and text wrapping. We'll cover all of these classes in detail in Chapter 23. 每个文本组件把显示的任务代理给UI代理对象,不同于其他的SwingUI代理,TextUI严重依赖大量的附加类,这些类都从View继承而.这些类负责来显示文字,包括文本对齐,换行. Finally, all of this is tied together by something called an EditorKit. EditorKits allow you to define how your documents will be input and output via streams, what view objects should be used in which situations, and what special actions your editor will support.EditorKits (and TextActions) are covered in Chapter 24. 最后,所有上面说的这些机制,是通过EditorKit来连接在一起的,EditorKit允许你定义文档输入输出的方式,在什么情况下该使用哪种View对象,你的编辑器支持什么样的操作.EditorKit(和TextActions)将在24章讲述 JTextComponent is an abstract class that serves as the base class for all text-based Swing components. It defines a large number of properties and methods that apply to its subclasses. In this introductory chapter, we'll pass quickly over many of these properties, as they require an understanding of the underlying model and view aspects of the text framework. JEditorPane is an extension of JTextComponent capable of displaying various types of content, such as HTML and RTF. It is not intended to be used as a full-featured web browser, but can be used to view simple HTML and is ideal for integrating online help into Java applications. JEditorPanes work closely with EditorKit objects which are plugged into the editor pane to customize it for a particular content type. Without an EditorKit telling it how to work, a JEditorPane can't function. In this chapter, we are going to ignore this complexity and just look at how we might use a JEditorPane as a very simple web browser. We'll get into the details of JEditorPane and EditorKit in Chapter 24. JTextPane is a complex extension of JEditorPane that provides functionality typical of a basic word processor, including features such as multicolored text, multiple fonts and text styles, imagembedding, and more. There's a great deal to discuss with respect to JTextPane and the many classes it interacts with. Document Model and Events The Document Model http://java.sun.com/docs/books/tutorial/uiswing/components/text.html Document objects are partitioned by Element s that describes the structural pieces of a Document, such as paragraphs or sections of specially formatted text (e.g., italics). Elements are made up of child Elements, forming a tree with a "root" Element as the base and arbitrary levels of child Elements below it. Each Document defines one or more Elements as its root Elements, from which the entire structure of the Document can be determined. Typically, only a single root Element is defined. However, more complex document types might contain multiple root elements, to support multiple ways of structuring the same document content. The key thing to understand is that the Document contains the data; the Elements just give it structure. Document + Element1 + Element2 The ElementIterator Class This class, first introduced in the JDK1.2 beta4 release, provides a strategy for iterating over some or all of the elements that make up a document. It's used by the AbstractWriter class (see Chapter 24), but could be used for other purposes as well. ElementIterator orders the elements depth-first, meaning that the root element (or whatever element you specify as a starting point) will be the first element returned. The root's first child is then returned, followed by the first child of that child, and so on until a leaf is reached. Once a leaf is reached, the next leaf is returned, and so on, until the last leaf of a child is reached, at which point the next sibling of that child is returned (and continues with its descendants). Common use of this class would look like this: ElementIterator it = new ElementIterator(myDocument); Element e = it.first(); do { // do something with "e" e = it.next(); } while (e != null); The AbstractDocument Class Locking AbstractDocument(翻译中的AD) implements a basic locking mechanism which ensures that at any given time, there is either a single writer of the document, or zero or more readers. That is, if no one is writing to the document, anyone is allowed to begin reading it or writing to it. Once someone begins writing, no one is able to read until the writer has finished. Ad实现了一个基础的锁机制：任何时间，只能有一个写锁或（0或多个）读锁。也就是说，如果没有人给ad写东西，任何人都可以写或读；如果有人写，一直到写完了才可以读。 Certain methods that technically "read" the document (such as getText()) do not actually obtain a read lock to do so. The only method that obtains a read lock is the render() method, meaning that you are not guaranteed document stability during other access methods. 但有些方法仅仅“读取”ad的内容，而不加锁（如getText()），只有render()方法，才会给ad加读锁，也就是说，当在使用其他方法来访问ad的时候不能保证document对象的完整性。 This locking scheme is supported by the methods described next. It's important to understand how this works if you decide to implement your own document type. If you decide to use the existing document types, it's not too important to understand all the details. 这样的锁机制被下面的方法所支持，如果要实现你自己的文档类型的话，这些机制对你很重要。如果要使用已有的文档类型，那就不那么重要了 此处省略掉这些方法的介绍，详见p627 The AbstractDocument.AbstractElement Class The AbstractDocument.LeafElement Class This is a public inner class used to refer to a block of text in the document. LeafElements do not contain child elements. This class is a concrete subclass of AbstractDocument.AbstractElement. 20.1.13 The AbstractDocument.BranchElement Class This is a public inner class used to represent composite Elements, which contain other Elements. It is a concrete subclass of AbstractDocument.Abstract-Element. 20.1.17 The AbstractDocument.AttributeContext Interface This inner-interface of AbstractDocument defines a set of methods for managing attributes in one or more documents. The idea is that replicating AttributeSets throughout a Document could be very expensive. Implementations of this interface (see the StyleContext class in Chapter 21) are intended to provide intelligent management of attribute sets, eliminating costly duplication. 维护一个或多个文档的属性，由于属性的复制十分耗费资源，所以这个接口的实现会提供一些非常聪明的维护方式，消除昂贵的复制 20.1.19 Model Summary So Far In this chapter, we've defined all of the abstractions that make up the Swing document model. Before going on, let's briefly review the interfaces and classes we've covered so far. Document This is the root of the text model. Each Swing text component references a Document model that stores its text. We also looked at AbstractDocument, an abstract class that implements Document and defines some default behavior, including document locking. Element Documents are partitioned by Elements. An Element contains a pair of offsets into a document, referencing a collection of text with a common set of attributes. AbstractDocument defines three inner classes that implement this interface: AbstractElement, LeafElement, and BranchElement. AttributeSet Each Element of a Document is defined, in part, by an arbitrary set of attributes called an AttributeSet. Attribute values in an AttributeSet are arbitrary Objects, accessible by unique keys (also Objects). MutableAttributeSet An extension of AttributeSet that allows attributes to be added and removed. We also looked at of SimpleAttributeSet, a default implementation of MutableAttributeSet that uses a Hashtable to implement the interface. Position A Position is simply an unchanging point within a document. It is more stable than an offset, since it moves with its attached text. Segment A Segment is a simple container for an array of characters used to allow fast access to some segment of text. AbstractDocument.Content This is where an AbstractDocument's content is actually stored. The StringContent class showed a default implementation of this interface, currently used by all text components. GapContent provides an alternate, more efficient implementation. AbstractDocument.AttributeContext An interface that allows AttributeSets to be managed across multiple documents for efficiency purposes. 20.1.20 The PlainDocument Class PlainDocument is an extension of AbstractDocument used for simple documents that do not need to manage complex formatting styles. The JTextField, JPasswordField, and JTextArea classes use PlainDocument as their default model. It's worth noting that PlainDocument provides more power than these components typically need. As an extension of AbstractDocument, it supports the use of AttributeSets, allowing the document to contain different fonts, colors, font styles, etc. These attributes are ignored when rendering the simple text components that use this document type. The Elements that make up a PlainDocument correspond to distinct lines of text that end in new line characters (/n). Each line of text maps to a single LeafElement. All of these LeafElements are then contained by a single BranchElement (the document's root element). PlainDocument（pd）是对ad的一个实现类，可以用作不需要太复杂的样式的文本需求，JtextField、JpasswordField和JtextArea都是使用pd来作为默认的模型。以pd的功能来说，完全可以满足这些个控件的要求。作为ad的实现，支持AttributesSets，允许文档包含不同的字体，颜色等。这些属性在pd用作上述控件的模型时是被忽略的。换行符分割的字符串形成了pd的Elements，每行的文本都是一个LeafElement（叶元素），而包含这些叶元素的元素是一个BranchElement（支元素），也就是pd的根元素 Filter Text 过滤文字，如果需要对JtextField的文字进行顾虑，可以考虑overridePlainDocument的 insertString()方法，生成一个新的Document，把这个document对象传递给JtextField的构造即可 Document Event (abstract)JtextComponent，文字编辑的最顶层支持：见jdkdoc： file://localhost/G:/java/doc/j2sdk-1_4_2-doc/docs/api/javax/swing/text/JTextComponent.html JEditorPane,html/rtf/plain的支持,EditorKit JTextPane,styledtext? Styled Documents and JtextPane Style This interface, an extension of MutableAttributeSet, adds two things not provided by its super-interface. The first is a name—every Style may (optionally) be given a name. The second is the ability to add and remove ChangeListeners. These listeners should be notified when changes are made to the definition of a Style. StyledDocument This interface, an extension of Document, adds a variety of methods for working with Styles and defines methods to provide access to the set of Style objects that describe the Document. New methods include setLogicalStyle(), to define the Style for the paragraph containing a given offset, addStyle(), to create a new Style, and many more. StyleContext This implementation of AbstractDocument.AttributeContext provides an efficient mechanism for managing attributes and Styles shared by multiple Elements or Documents.It actually stores the Styles it manages as attributes in an instance of an inner class called NamedStyle. In addition, this class is responsible for the creation of new Style objects, which are always created as new NamedStyle objects. StyleContext.NamedStyle This public inner class implements the Style interface using its enclosing StyleContext for efficient management of attributes. Its resolving parent is always another Style. StyleConstants This class contains definitions for a wide variety of pre-defined attributes used to define Styles. It also contains many convenient static methods to extract specific attributes from a given AttributeSet, e.g., isBold() is a static method that takes an AttributeSet, checks to see if the StyleConstants.Bold key is in the set, and returns its value (or false if it's not in the set). DefaultStyledDocument This is the class used by text components like JTextPane that want to show text using a variety of textual styles. It uses a StyleContext to manage its Styles. It also uses several inner classes, defined below. DefaultStyledDocument.ElementBuffer This public inner class is used to manage changes to the Element structure of a DefaultStyledDocument. DefaultStyledDocument.ElementSpec This public inner class is used to provide a specification of an Element to be created. ElementSpecs are created by DefaultStyledDocument (e.g., in insertUpdate()) and passed to an ElementBuffer, which uses them to determine how the Element structure needs to be updated. Note that a containment relation should be shown from DefaultStyledDocument.ElementSpec to AttributeSet (one of the things that makes up an ElementSpec is a set of attributes), but was omitted to keep the diagram as readable as possible. DefaultStyledDocument.SectionElement This protected inner class is an extension of AbstractDocument.BranchElement, used to DefaultStyledDocument Element structure. provide an additional level of nesting in the An instance of this class serves as the document's root Element. TabStop Class 21.1.4 The TabSet Class It is often useful to define a series of TabStops that should be applied to a given block of text. TabSet allows you to do this, and defines a few convenient methods for looking up the TabStops TabSets are immutable—once the TabStops are defined (in the constructor), contained in the set. they cannot be added or removed. StyleContext The StyledContext.NamedStyle Class The StyledDocument Interface DefaultStyledDocument is the implementation of StyledDocument that JTextPane uses by default. It defines a default Element structure, as shown in Figure 21.4. This structure consists of a default root Element, which is an instance of a protected inner class called SectionElement. The section contains Elements representing paragraphs (instances of AbstractElement.BranchElement) that contain character Elements (instances of AbstractElement.LeafElement). A character Element contains a collection of text with a common set of attributes. Dsd是对Sd的一个实现，在JtextPane中使用的。他定义了一个默认的元素结构，在图中可以看到。这个结构包含一个默认的根（内部类SectionElement的实例），这个根包含表示段落的元素（BranchElement），在段落元素中包含字符元素（LeafElement）。字符元素包含有公用属性的一些文本 对于“The Beginning and the end”这个文本，可以有上面的结构，枝节点和叶节点，包含一些属性 Chapter 22. Carets, Highlighters, and Keymaps JTextComponent UI Properties Caret Defines how the cursor is displayed. This includes the size and shape of the cursor, the blink rate (if any), etc. Highlighter Defines how selected text is highlighted. Typically this is done by painting a solid rectangle "behind" the text, but this is up to the implementation of this interface. Highlighter also defines two inner-interfaces that we'll look at. Keymap Defines the Actions performed when certain keys are pressed. For example, pressing CTRL-C may copy some text and CTRL-V may paste the cut or copied text at the current cursor location. This is considered a look-and-feel feature because different native look-and-feels have different default keymaps. 使用caret.install(JTextComponent c) Highliter.install( JtextComponent ) 22.1.2.9 An XOR Caret Text Views  Each JTextComponent has an associated Document model and TextUI.  Each TextUI defines a root View, which may contain other Views as necessary.  Each TextUI also contains a reference to an EditorKit (see Chapter 24 for details).  Each View is responsible for rendering a single Element of the Document model.  The ViewFactory interface defines how new Views should be created for different types of Elements. Views use ViewFactory objects to create their children.  The BasicTextUI (not shown; used by all Swing L&Fs) implements ViewFactory. Its root view (an inner class, not shown) uses the ViewFactory defined by the component's EditorKit, if the kit defines one. If not, the UI itself is used as the factory. Overview of the view classes