Literals 组件功能
JTextComponent类是 Swing 文本组件的基础。此类为所有后代提供以下可定制的功能:
-
一个称为* document *的模型,用于 管理 组件的内容。
-
一个视图,在屏幕上显示该组件。
-
一种称为“编辑器套件”的控制器,可以读写文本并使用actions实现编辑功能。
-
支持无限的撤消和重做。
-
可插入的插入符号以及对插入符号的支持会更改侦听器和导航过滤器。
请参阅名为TextComponentDemo
的示例以探索这些功能。尽管TextComponentDemo
示例包含JTextPane
的自定义实例,但本节中讨论的功能由所有JTextComponent
子类继承。
上方的文本组件是自定义的文本窗格。下部的文本组件是JTextArea
的实例,该实例用作日志,报告对文本窗格内容所做的所有更改。窗口底部的状态行根据是否选择了文本来报告选择的位置或插入符号的位置。
Try this:
-
单击启动按钮以使用Java™Web 开始(下载 JDK 7 或更高版本)运行 TextComponentDemo。另外,要自己编译和运行示例,请查阅example index。
-
使用鼠标选择文本,然后将光标放在文本窗格中。有关选择和光标的信息显示在窗口底部。
-
通过在键盘上 Importing 来 Importing 文本。您可以使用键盘上的箭头键或四个 emacs 键绑定来移动插入符号:Ctrl-B(向后一个字符),Ctrl-F(向后一个字符),Ctrl-N(向下一行)和 Ctrl- P(上一行)。
-
打开“编辑”菜单,然后使用其菜单项在文本窗格中编辑文本。在窗口底部的文本区域中进行选择。由于文本区域不可编辑,因此只有“编辑”菜单的某些命令(如“复制到剪贴板”)起作用。不过,请务必注意,菜单在两个文本组件上均起作用。
-
使用“样式”菜单中的项目将不同的样式应用于文本窗格中的文本。
以TextComponentDemo
示例为参考,本节涵盖以下主题:
将文本操作与菜单和按钮相关联
所有 Swing 文本组件均支持标准的编辑命令,例如剪切,复制,粘贴和插入字符。每个编辑命令由Action
对象表示和实现。 (要了解有关操作的更多信息,请参见如何使用动作。)通过操作,您可以将命令与 GUI 组件(如菜单项或按钮)相关联,从而围绕文本组件构建 GUI。
您可以在任何文本组件上调用getActions
方法,以接收包含该组件支持的所有操作的数组。也可以将动作数组加载到HashMap
中,以便您的程序可以按名称检索动作。这是TextComponentDemo
示例中的代码,该代码采用文本窗格中的操作并将其加载到HashMap
中。
private HashMap<Object, Action> createActionTable(JTextComponent textComponent) {
HashMap<Object, Action> actions = new HashMap<Object, Action>();
Action[] actionsArray = textComponent.getActions();
for (int i = 0; i < actionsArray.length; i++) {
Action a = actionsArray[i];
actions.put(a.getValue(Action.NAME), a);
}
return actions;
}
这是从哈希 Map 中按动作名称检索动作的方法:
private Action getActionByName(String name) {
return actions.get(name);
}
您可以在程序中逐字使用这两种方法。
以下代码显示了剪切菜单项是如何创建的以及与从文本组件中删除文本的操作相关联。
protected JMenu createEditMenu() {
JMenu menu = new JMenu("Edit");
...
menu.add(getActionByName(DefaultEditorKit.cutAction));
...
该代码使用前面显示的便捷方法按名称获取操作。然后将动作添加到菜单。这就是您需要做的。菜单和动作负责其他所有事项。请注意,操作的名称来自DefaultEditorKit。该工具包提供了用于基本文本编辑的操作,并且是 Swing 提供的所有编辑器工具包的超类。因此,它的功能可用于所有文本组件,除非 thay 被定制覆盖。
为了提高效率,文本组件共享操作。 getActionByName(DefaultEditorKit.cutAction)
返回的Action
对象由窗口底部不可编辑的JTextArea
共享。这种共享 Feature 有两个重要方面:
-
通常,您不应修改从编辑器工具包获得的
Action
对象。如果这样做,更改将影响程序中的所有文本组件。 -
Action
对象可以对程序中的其他文本组件进行操作,有时超出您的预期。在此示例中,即使无法编辑,JTextArea
与JTextPane
共享动作。 (在文本区域中选择一些文本,然后选择“剪切到剪贴板”菜单项.由于文本区域不可编辑,您会听到蜂鸣声.)如果您不想共享,请自己实例化Action
对象。DefaultEditorKit
定义了许多有用的Action
子类。
这是创建“样式”菜单并将其放入“粗体”菜单项的代码:
protected JMenu createStyleMenu() {
JMenu menu = new JMenu("Style");
Action action = new StyledEditorKit.BoldAction();
action.putValue(Action.NAME, "Bold");
menu.add(action);
...
StyledEditorKit
提供Action
子类,以实现样式文本的编辑命令。您将注意到,此代码不是从编辑器工具包获取操作,而是创建BoldAction
类的实例。因此,此操作不会与任何其他文本组件共享,并且更改其名称不会影响任何其他文本组件。
将文本操作与按键关联
除了将动作与 GUI 组件相关联之外,您还可以通过使用文本组件的 ImportingMap 将动作与按键相关联。ImportingMap 在如何使用键绑定中描述。
TextComponentDemo
示例中的文本窗格支持默认情况下不提供的四个键绑定。
-
Ctrl-B 将插入符号向后移动一个字符
-
Ctrl-F 将插入符号向前移动一个字符
-
Ctrl-N 可以将插入符号向下移动一行
-
Ctrl-P 将插入符号上移一行
以下代码将 Ctrl-B 键绑定添加到文本窗格。添加上面列出的其他三个绑定的代码是相似的。
InputMap inputMap = textPane.getInputMap();
KeyStroke key = KeyStroke.getKeyStroke(KeyEvent.VK_B,
Event.CTRL_MASK);
inputMap.put(key, DefaultEditorKit.backwardAction);
首先,代码获取文本组件的 ImportingMap。接下来,它找到一个表示 Ctrl-B 键序列的KeyStroke对象。最后,该代码将击键绑定到Action
,后者将光标向后移动。
实现撤消和重做
实现撤消和重做有两个部分:
第 1 部分:记住不可编辑
为了支持撤消和重做,文本组件必须记住发生的每个编辑,编辑的 Sequences 以及撤消每个编辑所需的内容。该示例程序使用UndoManager类的实例来 管理 其不可撤消的编辑列表。在声明成员变量的位置创建撤消 管理 器:
protected UndoManager undo = new UndoManager();
现在,让我们看一下程序如何发现不可撤消的编辑并将其添加到撤消 管理 器中。
只要对文档内容进行了不可撤消的编辑,文档就会通知感兴趣的侦听器。实现撤消和重做的重要步骤是在文本组件的文档上注册一个可撤消的编辑侦听器。以下代码将MyUndoableEditListener
的实例添加到文本窗格的文档中:
doc.addUndoableEditListener(new MyUndoableEditListener());
我们的示例中使用的可撤消编辑监听器将编辑添加到撤消 管理 器的列表中:
protected class MyUndoableEditListener
implements UndoableEditListener {
public void undoableEditHappened(UndoableEditEvent e) {
//Remember the edit and update the menus
undo.addEdit(e.getEdit());
undoAction.updateUndoState();
redoAction.updateRedoState();
}
}
请注意,此方法更新两个对象:undoAction
和redoAction
。这些是分别附加到“撤消”和“重做”菜单项上的动作对象。下一步显示了如何创建菜单项以及如何执行这两个操作。有关不可撤消的编辑侦听器和不可撤消的编辑事件的一般信息,请参阅如何编写不可撤销的编辑侦听器。
Note:
默认情况下,每个可撤消的编辑都撤消单个字符 Importing。可以将编辑分组,以便将一系列按键组合到一个不可撤消的编辑中。以这种方式对编辑进行分组将需要您定义一个类,该类从文档中拦截可撤消的编辑事件,并在适当时进行合并,然后将结果转发给可撤消的编辑侦听器。
第 2 部分:实现撤消和重做命令
实现撤消和重做的第一步是创建要放入“编辑”菜单中的动作。
JMenu menu = new JMenu("Edit");
//Undo and redo are actions of our own creation
undoAction = new UndoAction();
menu.add(undoAction);
redoAction = new RedoAction();
menu.add(redoAction);
...
撤消和重做操作分别通过自定义AbstractAction
子类UndoAction
和RedoAction
实现。这些类是示例的主类的内部类。
当用户调用undo
命令时,UndoAction
类的actionPerformed
方法被调用:
public void actionPerformed(ActionEvent e) {
try {
undo.undo();
} catch (CannotUndoException ex) {
System.out.println("Unable to undo: " + ex);
ex.printStackTrace();
}
updateUndoState();
redoAction.updateRedoState();
}
此方法调用撤消 管理 器的undo
方法,并更新菜单项以反映新的撤消/重做状态。
同样,当用户调用redo
命令时,RedoAction
类的actionPerformed
方法被调用:
public void actionPerformed(ActionEvent e) {
try {
undo.redo();
} catch (CannotRedoException ex) {
System.out.println("Unable to redo: " + ex);
ex.printStackTrace();
}
updateRedoState();
undoAction.updateUndoState();
}
此方法与撤消类似,不同之处在于它调用撤消 管理 器的redo
方法。
UndoAction
和RedoAction
类中的许多代码专用于启用和禁用当前状态的相应操作,并更改菜单项的名称以反映要撤消或重做的编辑。
Note:
TextComponentDemo
示例中的撤消和重做实现来自 JDK 软件随附的NotePad
演示。许多程序员也可以无需修改就复制撤消/重做的实现。
概念:关于文档
像其他 Swing 组件一样,文本组件从其数据视图中分离其数据(称为* model *)。如果您还不熟悉 Swing 组件使用的模型视图拆分,请参阅Using Models。
文本组件的模型称为* document *,是实现Documentinterface的类的实例。文档为文本组件提供以下服务:
-
包含文本。文档将文本内容存储在
Element
对象中,该对象可以表示任何逻辑文本结构,例如段落或共享样式的文本行。我们此处不描述Element
个对象。 -
提供对通过
remove
和insertString
方法编辑文本的支持。 -
通知文档侦听器和可撤消的编辑侦听器有关文本的更改。
-
管理
Position
对象,这些对象即使在文本被修改的情况下也可以跟踪文本中的特定位置。 -
允许您获取有关文本的信息,例如其 Long 度,以及作为字符串 的文本段。
Swing 文本包包含Document
,StyledDocument的子interface,该子interface增加了对使用样式标记文本的支持。一个JTextComponent
子类JTextPane
要求其文档是StyledDocument
而不是Document
。
javax.swing.text
软件包提供了以下文档类层次结构,它们为各种JTextComponent
子类实现了专用文档:
PlainDocument
是文本字段,密码字段和文本区域的默认文档。 PlainDocument
提供了一个基本的文本容器,其中所有文本均以相同的字体显示。即使编辑器窗格是样式化的文本组件,默认情况下它也会使用PlainDocument
的实例。标准JTextPane
的默认文档是DefaultStyledDocument
的实例,该实例是没有特定格式的样式化文本的容器。但是,任何特定的编辑器窗格或文本窗格使用的文档实例取决于绑定到它的内容的类型。如果使用setPage
方法将文本加载到编辑器窗格或文本窗格中,则该窗格使用的文档实例可能会更改。有关详情,请参阅如何使用编辑器窗格和文本窗格。
尽管可以设置文本组件的文档,但是通常更容易允许它自动设置,并且在必要时使用文档过滤器来更改文本组件的数据设置方式。您可以通过安装文档过滤器或通过使用自己的文档组件替换文本组件的文档来实现某些自定义。例如,TextComponentDemo
示例中的文本窗格具有文档过滤器,该过滤器限制了该文本窗格可以包含的字符数。
实现文档过滤器
要实现文档过滤器,请创建DocumentFilter的子类,然后使用AbstractDocument
类中定义的setDocumentFilter
方法将其附加到文档。尽管可能存在不从AbstractDocument
降级的文档,但默认情况下,Swing 文本组件的文档使用AbstractDocument
子类。
TextComponentDemo
应用程序具有一个文档过滤器DocumentSizeFilter,该过滤器限制了文本窗格可以包含的字符数。这是创建过滤器并将其附加到文本窗格的文档的代码:
...//Where member variables are declared:
JTextPane textPane;
AbstractDocument doc;
static final int MAX_CHARACTERS = 300;
...
textPane = new JTextPane();
...
StyledDocument styledDoc = textPane.getStyledDocument();
if (styledDoc instanceof AbstractDocument) {
doc = (AbstractDocument)styledDoc;
doc.setDocumentFilter(new DocumentSizeFilter(MAX_CHARACTERS));
}
为了限制文档中允许的字符,DocumentSizeFilter
会覆盖DocumentFilter
类的insertString
方法,该方法在每次将文本插入到文档中时都会调用。它还会覆盖replace
方法,该方法最有可能在用户粘贴新文本时被调用。通常,当用户键入或粘贴新文本或调用setText
方法时,可能会导致文本插入。这是insertString
方法的DocumentSizeFilter
类的实现:
public void insertString(FilterBypass fb, int offs,
String str, AttributeSet a)
throws BadLocationException {
if ((fb.getDocument().getLength() + str.length()) <= maxCharacters)
super.insertString(fb, offs, str, a);
else
Toolkit.getDefaultToolkit().beep();
}
replace
的代码相似。 DocumentFilter
类定义的方法的FilterBypass参数只是一个对象,该对象使文档可以以线程安全的方式进行更新。
由于前面的文档过滤器与文档数据的添加有关,因此它仅覆盖insertString
和replace
方法。大多数文档过滤器也会覆盖DocumentFilter
的remove
方法。
监听文档中的更改
您可以在文档上注册两种不同类型的侦听器:文档侦听器和可撤消的编辑侦听器。本小节介绍了文档侦听器。有关可撤消的编辑侦听器的信息,请参阅实现撤消和重做。
文档将对文档的更改通知已注册的文档侦听器。当从文档中插入文本或从中删除文本时,或文本样式更改时,请使用文档侦听器来创建响应。
每当对文本窗格进行更改时,TextComponentDemo
程序就使用文档侦听器来更新更改日志。下面的代码行将MyDocumentListener
类的实例注册为文本窗格文档中的侦听器:
doc.addDocumentListener(new MyDocumentListener());
这是MyDocumentListener
类的实现:
protected class MyDocumentListener implements DocumentListener {
public void insertUpdate(DocumentEvent e) {
displayEditInfo(e);
}
public void removeUpdate(DocumentEvent e) {
displayEditInfo(e);
}
public void changedUpdate(DocumentEvent e) {
displayEditInfo(e);
}
private void displayEditInfo(DocumentEvent e) {
Document document = (Document)e.getDocument();
int changeLength = e.getLength();
changeLog.append(e.getType().toString() + ": "
+ changeLength + " character"
+ ((changeLength == 1) ? ". " : "s. ")
+ " Text length = " + document.getLength()
+ "." + newline);
}
}
侦听器实现三种方法来处理三种不同类型的文档事件:插入,删除和样式更改。 StyledDocument
实例可以触发所有三种类型的事件。 PlainDocument
个实例仅触发插入和删除事件。有关文档侦听器和文档事件的一般信息,请参见如何编写文档监听器。
请记住,此文本窗格的文档过滤器限制了文档中允许的字符数。如果您try添加超出文档过滤器允许范围的文本,则文档过滤器将阻止更改,并且不会调用侦听器的insertUpdate
方法。仅当更改已发生时,才会将更改通知文档侦听器。
您可能需要在文档侦听器中更改文档的文本。 但是,绝对不要从文档侦听器中修改文本组件的内容. 如果这样做,程序可能会死锁。相反,您可以使用格式化的文本字段或提供文档过滤器。
聆听插入符号和选择的更改
TextComponentDemo
程序使用插入符号侦听器显示插入符号的当前位置,或者如果选择了文本,则显示选择范围。
在此示例中,插入符号侦听器类是JLabel
子类。这是创建插入标记侦听器标签并使之成为文本窗格的插入标记侦听器的代码:
//Create the status area
CaretListenerLabel caretListenerLabel = new CaretListenerLabel(
"Caret Status");
...
textPane.addCaretListener(caretListenerLabel);
插入标记侦听器必须实现一个方法caretUpdate
,每次插入标记移动或选择更改时都会调用该方法。这是caretUpdate
的CaretListenerLabel
实现:
public void caretUpdate(CaretEvent e) {
//Get the location in the text
int dot = e.getDot();
int mark = e.getMark();
if (dot == mark) { // no selection
try {
Rectangle caretCoords = textPane.modelToView(dot);
//Convert it to view coordinates
setText("caret: text position: " + dot +
", view location = [" +
caretCoords.x + ", " + caretCoords.y + "]" +
newline);
} catch (BadLocationException ble) {
setText("caret: text position: " + dot + newline);
}
} else if (dot < mark) {
setText("selection from: " + dot + " to " + mark + newline);
} else {
setText("selection from: " + mark + " to " + dot + newline);
}
}
如您所见,此侦听器更新其文本标签以反映插入符或选择的当前状态。侦听器从插入符事件对象获取要显示的信息。有关插入符号侦听器和插入符号事件的一般信息,请参见如何编写插入符侦听器。
与文档侦听器一样,插入符号侦听器是被动的。它对插入符号或选择中的更改做出反应,但不更改插入符号或选择本身。如果要更改插入标记或选择,请使用导航过滤器或自定义插入标记。
实现导航过滤器类似于实现文档过滤器。首先,编写NavigationFilter的子类。然后使用setNavigationFilter
方法将子类的实例附加到文本组件。
您可以创建一个自定义插入符号,以自定义插入符号的外观。要创建自定义插入记号,请编写实现Caretinterface的类-也许可以通过扩展DefaultCaret类来实现。然后在文本组件上提供类的实例作为setCaret
方法的参数。
概念:关于编辑器套件
文本组件使用EditorKit
将文本组件的各个部分绑在一起。编辑器工具包提供了视图工厂,文档,插入符号和操作。编辑器工具包还读取和写入特定格式的文档。尽管所有文本组件都使用编辑器工具包,但是某些组件隐藏了它们。您无法设置或获取文本字段或文本区域使用的编辑器套件。编辑器窗格和文本窗格提供getEditorKit
方法来获取当前的编辑器工具包,并提供setEditorKit
方法来对其进行更改。
对于所有组件,JTextComponent
类都提供了 API,供您间接调用或自定义某些编辑器工具包功能。例如,JTextComponent
提供read
和write
方法,它们调用编辑器工具包的read
和write
方法。 JTextComponent
还提供了方法getActions
,该方法返回组件支持的所有操作。
Swing 文本包提供以下编辑器工具包:
-
- 读取和写入纯文本,并提供一组基本的编辑命令。有关文本系统如何处理换行符的详细信息,请参见
DefaultEditorKit
API 文档。简要地说,' n'字符在内部使用,但是在写文件时使用文档或平台行分隔符。所有其他编辑器工具包都是DefaultEditorKit
类的后代。
- 读取和写入纯文本,并提供一组基本的编辑命令。有关文本系统如何处理换行符的详细信息,请参见
-
- 读取和写入样式文本,并为样式文本提供最少的操作集。此类是
DefaultEditorKit
的子类,并且是JTextPane
默认使用的编辑器工具包。
- 读取和写入样式文本,并为样式文本提供最少的操作集。此类是
-
- 读取,写入和编辑 HTML。这是
StyledEditorKit
的子类。
- 读取,写入和编辑 HTML。这是
上面列出的每个编辑器工具包都已向JEditorPane
类注册,并与该工具包读取,写入和编辑的文本格式相关联。将文件加载到编辑器窗格中时,该窗格将根据其注册的工具包检查文件的格式。如果找到支持该文件格式的已注册工具包,则窗格将使用该工具包读取文件,显示和编辑它。因此,编辑器窗格有效地将其自身转换为该文本格式的编辑器。您可以通过为其创建编辑器套件,然后使用JEditorPane
的registerEditorKitForContentType
来扩展JEditorPane
以支持您自己的文本格式,以将您的套件与文本格式相关联。