COMP 585 Notes

COMP 585 Noteset #4 Menus: JMenuBar, JMenu, JMenuItem JTextPane UndoableEdits UndoManager Keymaps Editor Kits Making Application Features Available Through a Menu System Remember that the purpose of a UI is for the application to make available to the user a simple way to invoke the application’s functions or services. For a GUI, there are components like buttons, text fields, sliders, etc. to capture input, and similar components to display output. Buttons are the most basic GUI input element when all that is needed is a trigger to initiate a task. The user points the mouse at the button and clicks. If the function triggered by the button click is simple, no further input is needed. If the function is complex, the button can trigger the display of a dialog box that gathers more info. Clicking the OK button of the dialog then triggers the actual function. Dialog boxes are an important GUI element that helps limit the complexity of the GUI by hiding some info until it’s needed. Even so, an application that makes available dozens or hundreds of functions to the user cannot provide a button trigger for each. One approach is that the trigger for the function needn’t be on the GUI at all: a hot-key approach. Each function could be assigned to a hot key (including special modifier keys: control, alt, shift, escape, function, etc.) Such an interface is simple, but how intuitive is it for a new user? And if the number of hot keys goes beyond 20 or 30, users may balk and find it too hard to memorize them. The accepted tradition in GUI design is to place the triggers for many of the most common and standardized function into a menu system. A menu system is organized around the following elements: • • • Menu Bar: a horizontal strip near the top of a top-level container (like a JFrame) which lists the names of the available menus. Normally, only menus are attached to a menu bar, but it’s possible to attach other components such as text fields. Menu: a special kind of “list” or “window” that toggles open or closed when its name is clicked on the menu bar. The contents of the menu are some number of menu items. More precisely, a menu operates as a button with an associated popup menu that is displayed when the menu title is clicked (see discussion of popup menu below). Menu Item: an abstract “button” that can be clicked or selected in order to trigger or launch the application feature that the menu item represents. Note that both classes JButton and JMenuItem are direct subclasses of the AbstractButton superclass. Triggering a function by selecting a menu item is similar to triggering a function by clicking a button. The menu system allows the application to make available to the user a great many application features or functions, while not cluttering up the GUI. Related groups of features are kept together in a single menu. In addition, menu items can be given keyboard shortcuts and accelerators that allow the user to trigger the selection of the menu item by means of a special keystroke, without users having to move their hands off of the keyboard to the mouse to open the menu and select the item. In the AWT, the relevant classes are • MenuBar • Menu • MenuItem In Swing, the classes are • JMenuBar • JMenu • JMenuItem Building the basic menu system is very much like assembling a bookcase: • Create a series of menu items. • Give each menu item an action listener to respond when the item is selected. • Create a series of menus. • Attach the menu items to the appropriate menu. • Attach the menus to the menu bar • Attach the menu bar to the frame. Be careful here because there are two methods: setMenuBar() for AWT-based apps and setJMenuBar() for Swing-based apps. Also note that you cannot attach a menu bar to a non-top-level container such as a JPanel. COMP 585 Noteset #4 2 Example // Create Menu Bar JMenuBar mb = new JMenuBar(); // Menu #1: File Menu JMenu mFile = new JMenu("File"); JMenuItem miNew = new JMenuItem("New"); JMenuItem miOpen = new JMenuItem("Open"); JMenuItem miSave = new JMenuItem("Save"); JMenuItem miQuit = new JMenuItem("Quit"); mb.add(mFile); mFile.add(miNew); mFile.add(miOpen); mFile.add(miSave); mFile.add(miQuit); // Menu #2: Edit JMenu mEdit = new JMenuItem miCut JMenuItem miCopy JMenuItem miPaste mb.add(mEdit); Menu JMenu("Edit"); = new JMenuItem("Cut"); mEdit.add(miCut); = new JMenuItem("Copy"); mEdit.add(miCopy); = new JMenuItem("Paste"); mEdit.add(miPaste); // Menu #3: Help JMenu mHelp = new JMenuItem miAbout JMenuItem miHelp mb.add(mHelp); Menu JMenu("Help"); = new JMenuItem("About"); mHelp.add(miAbout); = new JMenuItem("Help"); mHelp.add(miHelp); // attach menu bar to frame JFrame f = new JFrame(); f.setJMenuBar(mb); Finally, an action listener must be registered with each menu item. For example: JMenuItem miSave … miSave.addActionListener(new ActionListener() { public void actionPerformed(ActionEvent e) { save(); } }); Default Menu System Behavior Without any extra programming on the part of the implementer, the menu system has some convenient built-in behaviors at runtime: • A menu opens when its title is clicked on the menu bar. • A menu closes when one of its menu items is selected. • Single-character mnemonics can be defined for both menus and menu items. The mnemonic is automatically displayed as an underlined character. Mnemonics work implicitly with the “ALT” key. The mnemonic (+ALT) for a menu will open the menu. Then the mnemonic for a menu item will select the menu item. In other words, a menu item mnemonic will only trigger the menu item if its menu is currently open. [Note: under MS Windows, standard apps recognize the ALT key press+release, followed by the mnemonic key press+release, whereas mnemonics for Swing menu items require the ALT key and the mnemonic to be pressed simultaneously.] • The programmer can also define accelerators for menu items. An accelerator will trigger its menu item even if the menu containing the item is currently closed or hidden. Accelerators are usually control keys. The accelerator value is automatically displayed on the associated menu item. COMP 585 Noteset #4 3 Mnemonic and Accelerator Examples Here are examples from the Java Swing Tutorial: //Setting the mnemonic when constructing a menu item: menuItem = new JMenuItem("A text-only menu item", KeyEvent.VK_T); //Setting the mnemonic after creation time: menuItem.setMnemonic(KeyEvent.VK_T); //Setting the accelerator: menuItem.setAccelerator(KeyStroke.getKeyStroke( KeyEvent.VK_T, ActionEvent.ALT_MASK)); Menu Item Mnemonics The expression KeyEvent.VK_T is an int constant that represents the “T” key on the keyboard (VK stands for virtual key), which is a numerical code representing a physical key on the keyboard. This code is not the same as the ASCII code for the character ‘T’. In the example: menuItem = new JMenuItem("A text-only menu item", KeyEvent.VK_T); the text “A text-only menu item” appears on the menu item, with the first character “t” underscored. The underscored letter in the text of the menu item identifies it as the mnemonic. Assuming the menu is open, if the mnemonic is pressed on the keyboard, that menu item is selected. The effect is the same as if the user had opened the menu and clicked the item with the mouse. A couple of rules about mnemonics: first, the letter being chosen for the mnemonic should actually appear in the text of the menu item. The mnemonic will still work even if this isn’t the case, but it’s poor GUI design. Second, mnemonics should only be used once per menu. If two items on one menu have the same mnemonic, the mnemonic will always select the first item. Once the first menu or menu item is selected, the arrow keys can be used to move to the other items, but it’s better design for mnemonics to be unique across menu titles or across menu item text within a menu. The menu itself can be given a mnemonic. Entering the mnemonic for a menu (rather than a menu item) has the effect of opening the menu. Once the menu is open, the mnemonics of the menu items for that menu can be entered. Also, in Java Swing it is understood that menu mnemonics require the “ALT” key to be pressed at the same time as the mnemonic (slightly different from standard MS Windows apps). Once the menu is opened, the “ALT” key does not have to be pressed again for the menu item mnemonic. Menu Item Accelerators A menu can be opened in several ways • Click on it with the mouse • Press its mnemonic on the keyboard (plus the ALT key) • Using either of the previous methods, open another menu, then use the arrow keys to move to and open the desired menu. Once a menu is open, a menu item can be selected by pressing its keyboard mnemonic. Accelerators are even more streamlined. A menu item can be given an accelerator, which is usually a regular key representing some letter plus the CTRL key. For edit commands, it is a widely observed convention to assign CTRL-X, CTRL-C, CTRL-V to cut, copy, paste, respectively. JMenuItem miCut = new JMenuItem(“Cut”, KeyEvent.VK_T); miCut.setAccelerator(KeyStroke.getKeyStroke(KeyEvent.VK_X, ActionEvent.CTRL_MASK)); This code sets the mnemonic for the “cut” menu item to “T”, and the accelerator to “CTRL-X”. COMP 585 Noteset #4 4 Conventions for Menus, Menu Items, Mnemonics, and Accelerators Application software development over the past couple of decades has firmly established a set of conventions governing the use of menus. A developer should follow them unless there’s a pressing reason not to. Most users will expect a certain look and feel to the menu system. They will feel negatively toward the product if the menus are whimsically rearranged for no good reason. Menus Most applications will at a minimum provide “File”, “Edit”, and “Help” menus. • File Menu: will usually provide “New”, “Open”, “Close”, “Save”, “Save As”, “Print”, “Quit” items. • Edit Menu: will usually provide “Clear”, “Select All”, “Cut”, “Copy”, “Paste”, “Find”, “Replace”. (Undo and Redo are also strongly encouraged). • Help Menu: “About”, “Documentation” Accelerators Power users will not want to take their hands off the keyboard to execute certain common ops and will be annoyed if accelerators are not implemented for the basics: • Cut: Ctrl-X • Copy: Ctrl-C • Paste: Ctrl-V • Select All: Ctrl-A • Undo: Ctrl-Z • Save: Ctrl-S • Open: Ctrl-O • Print: Ctrl-P Note: these conventions apply most strongly in a MS Windows application context. Applications for other contexts (MacOS, Unix, Linux, SunOS, etc.) will have a different set. For example, some text editors for the Unix/Linux environment could create a set of bindings for an emacs-like environment. This is useful for source code editors or other apps where detailed control of style and other formatting is not relevant. Other Menu Related Controls There are versions of the check box and radio button that can be added to a menu like a menu item: • JCheckBoxMenuItem • JRadioButtonMenuItem Hierarchical Menus Instead of adding a JMenuItem to a JMenu, the programmer can add a second JMenu to an existing JMenu to create a hierarchical submenu or “walking” menu. Popup Menu A popup menu is constructed almost the same as a regular menu, except that it is not attached to the menu bar. Instead it is activated by whatever is defined to be the current popup trigger (usually a mouse right click when the mouse is not hovering above any other control). While the primary menu system is associated with the JFrame for the entire application, the JPopupMenu has a more general potential usage. In the extreme case, each separate JPanel or other component in the overall GUI can have its own associated JPopuMenu. In practice, you only need one or two. For example, a JPopupMenu will be useful for the content pane of the JFrame. Outline of PopupMenu Programming • Create an instance of JPopupMenu for the desired JPanel or other component. • Instantiate JMenuItems and add them to the popup. • Instantiate and register a mouse listener with the container that controls the popup. • Inside the mouseReleased method for the mouse listener, do the following: o Confirm that the mouse event is a popup trigger (ie, the right mouse button was clicked) o Obtain a reference to the component that generated the event o Obtain the x-y coordinates of the event o Call the “show(component,x,y)” method of the popup. Like other menus, the popup menu will close automatically when a menu item is selected. If no item is selected, it can be closed by pressing the “ESC” key. COMP 585 Noteset #4 5 Menu Limitations If a menu contains a large set of items, the position of the menu will be adjusted to try and keep all items visible on the desktop. But if the list of menu items is too long to be displayed on the desktop, then the menu simply runs off the edge of the desktop. There is no default scrolling functionality for a list of menu items. Adding this feature is complex, requiring the programmer to create a viewport and handle mouse events. More on Responding to Mouse Events The most common trigger for a mouse event is to click one of the mouse buttons (left or right). As we’ve already seen, the mouse listeners can then distinguish between mouse click, mouse button down, mouse button up, mouse entering region, mouse exiting region, mouse move, and mouse drag. But a few seemingly obvious details about the mouse event must be tracked down by the programmer. For example, on a mouse button down, the “mousePressed()” method of the mouse listener is called when any mouse button is pressed. What if the programmer wants to distinguish between left and right mouse button actions. Or even more subtle, what if the programmer wants to know about other modifier keys – control key, alt key, etc. – that might have been pressed during the mouse event? To distinguish between mouse buttons, usually it is enough to use the “getButton()” method of class MouseEvent. ... public void mousePressed(MouseEvent e) { int btn = e.getButton(); if (btn==MouseEvent.BUTTON1) { … } else if (btn==MouseEvent.BUTTON3) { … } } For popup menus, there’s a boolean convenience method to indicate if the current event should trigger the popup menu: … if (e.isPopupTrigger()) { … } For detailed info on the state of all mouse buttons and all modifier keys, you must use the method InputEvent.getModifiersEx() which returns a set of bit masks for all modifier keys and all mouse buttons. Here’s an excerpt from the API documentation for this method: public int getModifiersEx() Returns the extended modifier mask for this event. Extended modifiers represent the state of all modal keys, such as ALT, CTRL, META, and the mouse buttons just after the event occurred. For example, if the user presses button 1 followed by button 2, and then releases them in the same order, the following sequence of events is generated: MOUSE_PRESSED: BUTTON1_DOWN_MASK MOUSE_PRESSED: BUTTON1_DOWN_MASK | BUTTON2_DOWN_MASK MOUSE_RELEASED: BUTTON2_DOWN_MASK MOUSE_CLICKED: BUTTON2_DOWN_MASK MOUSE_RELEASED: MOUSE_CLICKED: It is not recommended to compare the return value of this method using == because new modifiers can be added in the future. For example, the appropriate way to check that SHIFT and BUTTON1 are down, but CTRL is up is demonstrated by the following code: int onmask = SHIFT_DOWN_MASK | BUTTON1_DOWN_MASK; int offmask = CTRL_DOWN_MASK; if ((event.getModifiersEx() & (onmask | offmask)) == onmask) { ... } The above code will work even if new modifiers are added. COMP 585 Noteset #4 6 Menus and Ribbon Controls Microsoft introduced a modification to its traditional menu system called a ribbon control starting with Office 2007. Whereas a traditional menu system is a collection of menu item buttons organized onto menus and attached to the menu bar, a ribbon is a combination of a tabbed pane and tool buttons and tool bars. The menus along the menu bar are replaced by tabs of a small tabbed pane, with tabs organized by functional area. Selecting a tab displays a toolbar area with a mixture of controls. The Java Swing package does not include a ribbon control component, but such a control is available through a project called Flamingo, by programmer-blogger Kirill Grouchnikov. The project is several years old, a downloadable package version may or may not be available. COMP 585 Noteset #4 7 Text Components and Models This GUI approach is particularly important for the display of textual information, as in a text editor. Most functions are made available through the menu system. Access to some common functions is duplicated by buttons on the tool bar. The majority of the GUI display area is then devoted to display of application data (the text being edited). Several Swing components are available specifically for textual data: JTextPane and JEditorPane. We will discuss JTextPane first. The JTextPane is one of several components that inherit from JTextComponent: JTextField, JTextArea are some of the others.Textual components share some common properties, but differ with respect to issues such as styled text (text plus info concerning fonts, bold/underline/italic styles, etc.). As with all Swing components, text components follow the delegate-model architecture (a variation of the model-viewcontroller architecture for GUI components). The text entered into a JTextPane is stored in the model associated with the JTextPane. In this case, the model will be a Document subclass. Text being edited is physically stored in a Document object, and the on-screen appearance is controlled by the JTextPane object. Content Types The text components in the Java API provide support for three different text content types: • text/plain (ASCII text, optionally with style attributes stored separately) • text/html (HyperText Markup Language) • text/rtf (Rich Text Format) Edit support for each content type is provided by a “helper” object called an editor kit. Support for text editing is uneven and immature compared to the level of sophistication provided in other APIs. Some content types are better supported than others. Text and Styles In Java, “styled text” is an extension to the “text/plain” content type. Unlike html or rtf, text and style info are stored separately. Text is stored as a single Java string. Each character is an ASCII (or Unicode) character and its position in the string is a simple integer index starting with 0. Style info is stored separately in a collection of AttributeSet objects. The AttributeSet objects apply to a specific range of text within the text string. The linkage is provided by a separate data structure that maps attributes to text ranges, which are indicated by position indexes for starting and ending characters. More discussion of styles is provided below. COMP 585 Noteset #4 8 Text Component Built-In Behavior The JTextPane comes with many useful default behaviors. • A blinking cursor marks the caret position, the point in the document data where the next character entered from the keyboard will be inserted. • The caret position can be adjusted with the arrow keys or by moving it by pointing and clicking the mouse. • Text can be deleted with the delete key. • Text can be selected with mouse click and drag, or by the arrow keys plus shift key. A single word can be selected by double clicking it with the mouse. • Cut, copy, and paste are bound to the ctrl-x, ctrl-c, and ctrl-v keystrokes. • Select all is bound to ctrl-a. Some of the operations not implemented by default are changes to font, pointsize, style, alignment, and undo/redo. COMP 585 Noteset #4 9 JTextPane “Helper” Objects Text editing is complex enough that several helper objects are automatically provided by the JTextPane, similar to the way a JPanel object comes with a layout manager. In the case of the JTextPane, the helper objects include: • A document object of type DefaultStyledDocument. Note that some of the text related classes are defined in package javax.swing.text. This is the model for the component. • An editor kit, which provides a series of Actions, which are useful predefined operations for manipulating the textual data stored in the pane/document. • An input map, which defines how keystrokes are bound to editor operations. Another helper object is the undo manager, UndoManager. This object, however, must be instantiated separately, it is not automatically created with the text pane. It is defined in package javax.swing.undo. Controlling the Edit Programmatically: The JTextPane The state of the text pane and its document, and the text within the document itself, can be manipulated directly by the user through the mouse and keyboard. They can also be manipulated programmatically by calling API methods of class JTextPane. Here is a description of part of the API for class JTextPane: void copy() Transfers the currently selected range in the associated text model to the system clipboard, leaving the contents in the text model. void cut() Transfers the currently selected range in the associated text model to the system clipboard, removing the contents from the model. Action[] getActions() Fetches the command list for the editor. int getCaretPosition() Returns the position of the text insertion caret for the text component. Document getDocument() Fetches the model associated with the editor. Keymap getKeymap() Fetches the keymap currently active in this text component. Insets getMargin() Returns the margin between the text component's border and its text. String getSelectedText() Returns the selected text contained in this TextComponent. int getSelectionEnd() Returns the selected text's end position. int getSelectionStart() Returns the selected text's start position. String getText() Returns the text contained in this TextComponent. String getText(int offs, int len) Fetches a portion of the text represented by the component. void moveCaretPosition(int pos) Moves the caret to a new position, leaving behind a mark defined by the last time setCaretPosition was called. void paste() Transfers the contents of the system clipboard into the associated text model. void read(Reader in, Object desc) Initializes from a stream. void replaceSelection(String content) Replaces the currently selected content with new content represented by the given string. void select(int selectionStart, int selectionEnd) Selects the text between the specified start and end positions. void selectAll() Selects all the text in the TextComponent. void setCaret(Caret c) Sets the caret to be used. void setCaretPosition(int position) COMP 585 Noteset #4 10 Sets the position of the text insertion caret for the TextComponent. void setDocument(Document doc) Associates the editor with a text document. void setSelectionEnd(int selectionEnd) Sets the selection end to the specified position. void setSelectionStart(int selectionStart) Sets the selection start to the specified position. void setText(String t) Sets the text of this TextComponent to the specified text. void write(Writer out) Stores the contents of the model into the given stream. Caret and Selection As you can see from the methods above, the JTextPane provides programmatic control of the caret and selection. The caret has an integer index as its value, which refers to the index of the character within the document that the cursor is currently in front of. The selection is the text within the pane that has been highlighted by the user. It is identified by its start and stop indexes, or by its start index and length or offset. Controlling the Edit Programmatically: The Document Inserting and Deleting Text Each text pane comes with an associated model that holds the actual data. In the case of a text component, the model is called a document. Specifically in the case of the JTextPane, the model is of type DefaultStyledDocument. Methods that manipulate the caret and the selection are defined by the JTextPane class. Methods that insert and remove text are defined by the Document class. The two relevant methods are “remove()” and “insertString()”. They are inherited from class AbstractDocument: public void remove(int offs,int len) throws BadLocationException public void insertString(int offs, String str, AttributeSet a) throws BadLocationException For example, here’s an example implementation of the “cut” operation, which finds the currently selected text and removes it from the document. Note: “tp” is an instance variable that refers to the JTextPane object. DefaultStyledDocument doc = (DefaultStyledDocument)tp.getStyledDocument(); int start = tp.getSelectionStart(); int len = tp.getSelectedText().length(); doc.remove(start,len); This code is typical for text manipulation in that both the text pane and the document objects must be accessed. Caret and selection information is available via the text pane, while inserting and removing text must be performed with respect to the document. When calling the insertString() method, the third parameter defines an AttributeSet. This is used for representing style information. For plain text, this parameter can be left empty (null). COMP 585 Noteset #4 11 Text Components and Menus The text pane and associated document come equipped with a large set of useful API methods to edit the text content of the document. In general, these methods each implement low-level operations on the state of the document. Therefore, the text pane also provides an editor kit which defines a useful collection of higher-level operations such as cut/copy/paste. There is some overlap between operations defined directly by the methods of the API and the operations provided by the editor kit. Also, the editor kit operations have some surprising gaps in functionality with regard to the correct handling of styled text (text with font changes, italic face, bold face, etc.) To give the user of the GUI convenient access to the features of the text pane and editor kit operations, the operations must be carefully (and somewhat tediously) integrated into the menu system. The editor kit collection of Actions somewhat streamlines this process, but the task is still tedious and hard to streamline. COMP 585 Noteset #4 12 Example import import import import java.awt.*; java.awt.event.*; javax.swing.*; javax.swing.text.*; class EditorFrame extends JFrame { JTextPane tp; JScrollPane sp; JPanel mainp; JMenuItem mi1, mi2; public EditorFrame() { tp = new JTextPane(); Font f = tp.getFont(); tp.setFont(new Font(f.getName(),f.getStyle(),18)); sp = new JScrollPane(tp); mainp = new JPanel(); mainp.setLayout(new BorderLayout()); mainp.add(sp,BorderLayout.CENTER); this.setContentPane(mainp); this.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE); this.buildMenus(); } public void buildMenus() { JMenuBar mb = new JMenuBar(); this.setJMenuBar(mb); JMenu m = new JMenu("test menu"); mb.add(m); mi1 = new JMenuItem("item 1"); mi1.addActionListener(new ActionListener() { public void actionPerformed(ActionEvent e) { int x = tp.getCaretPosition(); System.out.println("caret at position " + x); } }); m.add(mi1); mi2 = new JMenuItem("item 2"); m.add(mi2); } public static void createGUI() { EditorFrame f = new EditorFrame(); f.setSize(200,300); f.setVisible(true); } } public class TextTest { public static void main(String[] args) { EditorFrame.createGUI(); } } COMP 585 Noteset #4 13 Keymap The text pane also comes with a keymap (input map) that defines bindings between keystrokes and operations. By using the keymap, the programmer can create key bindings without having to write low level key event listeners. Examples are given below in the section on actions. Using Actions An Action (interface defined in the package top-level Swing package javax.swing) is an object that comes with a built-in action listener. It is useful when you want to link multiple GUI components to the same operation. For example (from the Java Swing tutorial), suppose you want to set up a JButton and a JMenuItem to trigger the same operation. Action leftAction = new LeftAction(); //LeftAction code is shown later button = new JButton(leftAction) menuItem = new JMenuItem(leftAction); In this example, the action is added directly to the menu. It is also possible to add the action to a menu item. The name of the action is used both as the text for the menu item and the text displayed on the button. This is a programmer convenience that helps avoid the need to write multiple identical listeners. The Editor Kit and Predefined Text Actions The JTextPane comes with a preinstalled editor kit. The kit is a programmer convenience which is used primarily for the set of predefined actions that it provides for manipulating text. The actions are defined, but the programmer must add some integration code to make the actions available to the user from the GUI. The most obvious choices are: • • Install the action into the menu system by attaching it to a menu item of some menu. Bind the action to a keystroke (such as CTRL-A). In either case, it would be nice to know what edit actions are available to choose from. You can read the APIs and look at the predefined actions of the editor kit (and those inherited from its superclasses). More directly, you can programmatically query the editor kit and print out a list of all the actions it knows about. Here’s a code example: EditorKit kit = tp.getEditorKit(); Action[] actions = kit.getActions(); for (int i=0; i comparator = new Comparator() { public int compare(Action a1, Action a2) { String firstName = (String) a1.getValue(Action.NAME); String secondName = (String) a2.getValue(Action.NAME); return firstName.compareTo(secondName); } }; Arrays.sort(actions, comparator); int count = actions.length; System.out.println("Count: " + count); for (int i = 0; i < count; i++) { System.out.printf("%28s : %s\n",actions[i].getValue(Action.NAME),actions[i]. getClass().getName()); } } } COMP 585 Noteset #4 15 Undo/Redo Support The JTextPane is the starting point for building a reasonably complete text editor. It comes with a document (the model) and an editor kit (collection of useful predefined text edit actions). The programmer then adds a menu system and attaches edit actions from the editor kit to some menu items, some easy-to-remember keystrokes, or both. One of the useful edit commands that isn’t automatically supplied by the editor kit is undo/redo. The ability to remember undoable edits and then allow the user to undo and redo them requires its own set of support classes, which are organized into their own package: javax.swing.undo. There are three main parts to adding undo/redo support to an application. • • • The application must create an instance of UndoManager. The undo manager acts as a database or repository of all the info that needs to be remembered on each undoable edit, so that it can potentially be undone later. The document which holds the data for the JTextPane must be given an UndoableEditListener. When an undoable edit occurs, the document updates the undo manager with the details on the edit that just occurred. Undo and Redo items should be added to the menu system to make the features of the undo manager available on the GUI. When these items are selected, the undo manager is accessed and info is restored to the document for the JTextPane. Some other minor details regarding application state must also be maintained. For example, since some edits are not undoable, there will be times during the application execution when either or both of Undo and Redo will not be available. The menu items for these actions should be temporarily disabled until the state changes and they become available again. Here is an extended example from the Swing Tutorial: Create an undo manager for the application: UndoManager undo = new UndoManager(); Define undo and redo actions and add them to the menu system: JMenu menu = new JMenu("Edit"); undoAction = new UndoAction(); menu.add(undoAction); redoAction = new RedoAction(); menu.add(redoAction); (class definitions for UndoAction and RedoAction are given below; these are not predefined classes from the API) Define an undoable edit listener class MyUndoableEditListener implements UndoableEditListener { public void undoableEditHappened(UndoableEditEvent e) { undo.addEdit(e.getEdit()); undoAction.updateUndoState(); redoAction.updateRedoState(); } } Register a listener with the document: JTextPane textPane = new JTextPane(); StyledDocument styledDoc = textPane.getStyledDocument(); styledDoc.addUndoableEditListener(new MyUndoableEditListener()); COMP 585 Noteset #4 16 Notice the following points in the above figure: • The undo manager is not directly connected by memory reference to the other components. For example, the JTextPane and Document objects do not store a reference to the undo manager as an instance property. The system is held together via event listeners. • When the user makes an undoable edit on the document, this fires an event (UndoableEditEvent). The listener captures the details of the edit and stores a record of the event in the undo manager. • When the user selects the undo or redo menu items, this fires an event (ActionEvent). The listener then calls the undo() or redo() methods of the undo manager. The effect of the method calls is fetch the details of the previously stored edit from the manager, and undo or redo the edit within the document. The code given below is taken from the Java Swing tutorial section on text components. The author defines custom UndoAction and RedoAction classes (these are not predefined packaged classes). The complexity of this code comes from the following: • • The application must expose the features of the undo manager on the GUI, specifically, the “Undo” and “Redo” items on the “Edit” menu. Not all edits are undoable, so the state of the menu items must be dynamically updated to clearly indicate if an undo or redo operation is possible at a specific time. This is handled by enabling or disabling the menu items as the state of the undo manager dynamically changes. Note the usage of the “canUndo()” and “canRedo()” methods of the undo manager class. Even if the menu items are not enabled/disabled, the listener should execute the check before executing the undo/redo operations to avoid throwing exceptions. And not only does this code enable and disable the menu items, it updates the actual text of the menu item to reflect more specifically what edit is being undone/redone. That is, the menu item displays, not simply a generic “Undo”, but “Undo Change Style to Bold”, or “Undo Insert Text”, and so on. This is a level of polish that may not be needed in all text edit GUIs. COMP 585 Noteset #4 17 class UndoAction extends AbstractAction { public UndoAction() { super("Undo"); setEnabled(false); } public void actionPerformed(ActionEvent e) { try { undo.undo(); } catch (CannotUndoException ex) { System.out.println("Unable to undo: " + ex); ex.printStackTrace(); } updateUndoState(); redoAction.updateRedoState(); } protected void updateUndoState() { if (undo.canUndo()) { setEnabled(true); putValue(Action.NAME, undo.getUndoPresentationName()); } else { setEnabled(false); putValue(Action.NAME, "Undo"); } } } class RedoAction extends AbstractAction { public RedoAction() { super("Redo"); setEnabled(false); } public void actionPerformed(ActionEvent e) { try { undo.redo(); } catch (CannotRedoException ex) { System.out.println("Unable to redo: " + ex); ex.printStackTrace(); } updateRedoState(); undoAction.updateUndoState(); } protected void updateRedoState() { if (undo.canRedo()) { setEnabled(true); putValue(Action.NAME, undo.getRedoPresentationName()); } else { setEnabled(false); putValue(Action.NAME, "Redo"); } } } COMP 585 Noteset #4 18 Compound Edits One significant limitation to the UndoManager is that it does not distinguish major edits from minor edits. During an edit session with a text editor, it is common for the user to enter a chunk of text as a series of keystrokes, then pause, think, reformat, spell check, etc., then return to entering keystrokes. The UndoManager treats each keystroke as an edit. So when the user chooses the undo function, it only deletes one character from the long string of characters just entered. The user must undo repeatedly to remove all the characters from the editor. A solution is to add logic to group multiple small edits together into compound edits, and undo or redo based on these. This is more convenient for the user, but it is not trivial to define the logic that creates compound edits. Here are a couple of links to bloggers who offer their coded solutions: COMP 585 Noteset #4 19 Fonts Most components that display text allow the programmer to change the font for that text. There are some limitations. For example, the content of a JTextField cannot contain styles (bold, italics, underline, etc.). Also, most programs will rely on using the fonts that are available on the user’s target machine, not the fonts that are available on the programmer’s development environment. So most programs will stick to commonly available fonts such as “Serif” or “SansSerif”. For uniform support of fonts across platforms, here’s the blurb from the API page for class Font (package java.awt): Physical fonts are the actual font libraries containing glyph data and tables to map from character sequences to glyph sequences, using a font technology such as TrueType or PostScript Type 1. All implementations of the Java 2 platform must support TrueType fonts; support for other font technologies is implementation dependent. Physical fonts may use names such as Helvetica, Palatino, HonMincho, or any number of other font names. Typically, each physical font supports only a limited set of writing systems, for example, only Latin characters or only Japanese and Basic Latin. The set of available physical fonts varies between configurations. Applications that require specific fonts can bundle them and instantiate them using the createFont method. Logical fonts are the five font families defined by the Java platform which must be supported by any Java runtime environment: Serif, SansSerif, Monospaced, Dialog, and DialogInput. These logical fonts are not actual font libraries. Instead, the logical font names are mapped to physical fonts by the Java runtime environment. The mapping is implementation and usually locale dependent, so the look and the metrics provided by them vary. Typically, each logical font name maps to several physical fonts in order to cover a large range of characters. There are multiple constructors for class Font, but the most common is Font f = new Font(String fname, int style, int pointsize); • • • String fname represents the name of the font family (see below). int style is set to a predefined constant Font.PLAIN, Font.ITALIC, or Font.BOLD. int pointsize is the point size of the file, eg, 10, 12, 18 … How to Find Which Fonts are Available on the Current System A class called GraphicsEnvironment maintains a list of all available font families. During instantiation of a JPanel or other GUI component class, you can execute the following code to get an array of Strings that represent all possible choices of font family names available on the current system. GraphicsEnvironment ge = GraphicsEnvironment.getLocalGraphicsEnvironment(); String[] fonts = ge.getAvailableFontFamilyNames(); for (int i=0; i