I l@ve RuBoard
• Table of Contents
• Index
• Reviews
• Examples
• Reader Reviews
• Errata
Java™ Swing, 2nd Edition
By Brian Cole, Robert Eckstein, James Elliott, Marc Loy, David Wood
Publisher : O'Reilly Pub Date : November 2002
ISBN : 0-596-00408-7
Pages : 1278
This second edition of Java Swing thoroughly covers all the features available in Java 2 SDK 1.3 and 1.4. More than simply a reference, this new edition takes a practical approach. It is a book by developers for developers, with hundreds of useful examples, from beginning level to advanced, covering every component available in Swing.
Whether you're a seasoned Java developer or just trying to find out what Java can do, you'll find Java Swing, 2nd edition an indispensable guide.
I l@ve RuBoard
I l@ve RuBoard
• Table of Contents
• Index
• Reviews
• Examples
• Reader Reviews
• Errata
Java™ Swing, 2nd Edition
By Brian Cole, Robert Eckstein, James Elliott, Marc Loy, David Wood
Publisher : O'Reilly
Pub Date : November 2002
ISBN : 0-596-00408-7
Pages : 1278
Copyright Preface
What This Book Covers What's New in This Edition?
On the Web Site Conventions How to Contact Us Acknowledgments
Chapter 1. Introducing Swing Section 1.1. What Is Swing?
Section 1.2. Swing Features
Section 1.3. Swing Packages and Classes
Section 1.4. The Model-View-Controller Architecture Section 1.5. Working with Swing
Section 1.6. The Swing Set Demo Section 1.7. Reading This Book
Chapter 2. Jump-Starting a Swing Application Section 2.1. Upgrading Your AWT Programs Section 2.2. A Simple AWT Application
Section 2.3. Including Your First Swing Component
Section 2.4. Beyond Buttons
Section 2.5. What Is an Internal Frame?
Section 2.6. A Bigger Application
Chapter 3. Swing Component Basics Section 3.1. Understanding Actions Section 3.2. Graphical Interface Events Section 3.3. Graphics Environments
Section 3.4. Sending Change Events in Swing Section 3.5. The JComponent Class
Section 3.6. Responding to Keyboard Input
Chapter 4. Labels and Icons Section 4.1. Labels
Section 4.2. Working with Images Section 4.3. Support for HTML Section 4.4. Icons
Section 4.5. Implementing Your Own Icons Section 4.6. Dynamic Icons
Section 4.7. The ImageIcon Class
Chapter 5. Buttons
Section 5.1. The ButtonModel Interface Section 5.2. The DefaultButtonModel Class Section 5.3. The AbstractButton Class Section 5.4. The JButton Class Section 5.5. The JToggleButton Class
Section 5.6. The JToggleButton.ToggleButtonModel Class Section 5.7. The JCheckBox Class
Section 5.8. The JRadioButton Class Section 5.9. The ButtonGroup Class
Chapter 6. Bounded-Range Components Section 6.1. The Bounded-Range Model Section 6.2. The JScrollBar Class Section 6.3. The JSlider Class Section 6.4. The JProgressBar Class Section 6.5. Monitoring Progress
Chapter 7. Lists, Combo Boxes, and Spinners Section 7.1. Lists
Section 7.2. Representing List Data Section 7.3. Handling Selections Section 7.4. Displaying Cell Elements Section 7.5. The JList Class
Section 7.6. Combo Boxes Section 7.7. The JComboBox Class Section 7.8. Spinners
Section 7.9. Spinner Models Section 7.10. Spinner Editors
Chapter 8. Swing Containers Section 8.1. A Simple Container Section 8.2. The Root Pane
Section 8.3. Basic RootPaneContainers Section 8.4. The JFrame Class Section 8.5. The JWindow Class Section 8.6. The JApplet Class
Chapter 9. Internal Frames
Section 9.1. Simulating a Desktop Section 9.2. The JInternalFrame Class Section 9.3. The JDesktopPane Class Section 9.4. The DesktopManager Interface Section 9.5. Building a Desktop
Chapter 10. Swing Dialogs Section 10.1. The JDialog Class Section 10.2. The JOptionPane Class Section 10.3. Using JOptionPane Section 10.4. Simple Examples Section 10.5. Getting the Results
Section 10.6. A Comparison: Constructors Versus Static Methods Section 10.7. Using Internal Frame Dialogs with JDesktopPane
Chapter 11. Specialty Panes and Layout Managers Section 11.1. The JSplitPane Class
Section 11.2. The JScrollPane Class Section 11.3. The JTabbedPane Class Section 11.4. Layout Managers Section 11.5. The SpringLayout Class Section 11.6. Other Panes
Chapter 12. Chooser Dialogs
Section 12.1. The JFileChooser Class Section 12.2. The File Chooser Package Section 12.3. The Color Chooser Section 12.4. The JColorChooser Class
Section 12.5. Developing a Custom Chooser Panel Section 12.6. Developing a Custom Preview Panel Section 12.7. Developing a Custom Dialog
Chapter 13. Borders
Section 13.1. Introducing Borders Section 13.2. Painting Borders Correctly Section 13.3. Swing Borders
Section 13.4. Creating Your Own Border
Chapter 14. Menus and Toolbars
Section 14.1. Introducing Swing Menus Section 14.2. Menu Bar Selection Models Section 14.3. The JMenuBar Class
Section 14.4. The JMenuItem Class Section 14.5. The JPopupMenu Class Section 14.6. The JMenu Class Section 14.7. Selectable Menu Items Section 14.8. Toolbars
Chapter 15. Tables
Section 15.1. The JTable Class
Section 15.2. Implementing a Column Model Section 15.3. Table Data
Section 15.4. Selecting Table Entries Section 15.5. Rendering Cells Section 15.6. Editing Cells Section 15.7. Next Steps
Chapter 16. Advanced Table Examples Section 16.1. A Table with Row Headers Section 16.2. Large Tables with Paging
Section 16.3. A Table with Custom Editing and Rendering Section 16.4. Charting Data with a TableModel
Chapter 17. Trees
Section 17.1. A Simple Tree Section 17.2. Tree Models Section 17.3. The JTree Class Section 17.4. Tree Nodes and Paths Section 17.5. Tree Selections Section 17.6. Tree Events
Section 17.7. Rendering and Editing Section 17.8. What Next?
Chapter 18. Undo
Section 18.1. The Swing Undo Facility Section 18.2. The UndoManager Class Section 18.3. Extending UndoManager
Chapter 19. Text 101
Section 19.1. The Swing Text Components Section 19.2. The JTextComponent Class Section 19.3. The JTextField Class Section 19.4. A Simple Form
Section 19.5. The JPasswordField Class Section 19.6. The JTextArea Class Section 19.7. How It All Works
Chapter 20. Formatted Text Fields
Section 20.1. The JFormattedTextField Class Section 20.2. Handling Numerics
Section 20.3. The DefaultFormatter Class Section 20.4. The MaskFormatter Class Section 20.5. The InternationalFormatter Class
Section 20.6. The DateFormatter Class Section 20.7. The NumberFormatter Class Section 20.8. The DefaultFormatterFactory Class Section 20.9. Formatting with Regular Expressions Section 20.10. The InputVerifier Class
Chapter 21. Carets, Highlighters, and Keymaps Section 21.1. Carets
Section 21.2. Highlighters Section 21.3. Keymaps
Chapter 22. Styled Text Panes Section 22.1. The JTextPane Class Section 22.2. AttributeSets and Styles Section 22.3. The Document Model Section 22.4. Document Events Section 22.5. Views
Section 22.6. The DocumentFilter Class Section 22.7. The NavigationFilter Class
Chapter 23. Editor Panes and Editor Kits Section 23.1. The JEditorPane Class Section 23.2. Overview of the Editor Kits Section 23.3. HTML and JEditorPane Section 23.4. Hyperlink Events Section 23.5. The HTMLEditorKit Class Section 23.6. Extending HTMLEditorKit Section 23.7. Editing HTML
Section 23.8. Writing HTML Section 23.9. Reading HTML Section 23.10. A Custom EditorKit
Chapter 24. Drag and Drop
Section 24.1. What Is Drag and Drop?
Section 24.2. The Drop API Section 24.3. The Drag Gesture API Section 24.4. The Drag API Section 24.5. Rearranging Trees Section 24.6. Finishing Touches
Chapter 25. Programming with Accessibility Section 25.1. How Accessibility Works Section 25.2. The Accessibility Package Section 25.3. Other Accessible Objects Section 25.4. Types of Accessibility
Section 25.5. Classes Added in SDK 1.3 and 1.4 Section 25.6. The Accessibility Utility Classes Section 25.7. Interfacing with Accessibility
Chapter 26. Look and Feel
Section 26.1. Mac OS X and the Default Look-and-Feel
Section 26.2. How Does It Work?
Section 26.3. Key Look-and-Feel Classes and Interfaces Section 26.4. The MultiLookAndFeel
Section 26.5. Auditory Cues
Section 26.6. Look-and-Feel Customization Section 26.7. Creation of a Custom Look-and-Feel
Chapter 27. Swing Utilities Section 27.1. Utility Classes Section 27.2. The Timer Class Section 27.3. Tooltips
Section 27.4. Rendering Odds and Ends Section 27.5. Event Utilities
Chapter 28. Swing Under the Hood Section 28.1. Working with Focus
Section 28.2. Multithreading Issues in Swing
Section 28.3. Lightweight Versus HeavyweightComponents Section 28.4. Painting and Repainting
Section 28.5. Creating Your Own Component
Appendix A. Look-and-Feel Resources Appendix B. Component Actions Section B.1. JButton Section B.2. JCheckBox
Section B.3. JCheckBoxMenuItem Section B.4. JComboBox Section B.5. JDesktopPane Section B.6. JEditorPane Section B.7. JFormattedTextField Section B.8. JInternalFrame Section B.9. JLabel Section B.10. JList Section B.11. JMenu Section B.12. JMenuBar Section B.13. JMenuItem Section B.14. JOptionPane Section B.15. JPasswordField Section B.16. JPopupMenu Section B.17. JProgressBar Section B.18. JRadioButton
Section B.19. JRadioButtonMenuItem Section B.20. JRootPane
Section B.21. JScrollBar Section B.22. JScrollPane Section B.23. JSlider Section B.24. JSpinner Section B.25. JSplitPane Section B.26. JTabbedPane Section B.27. JTable Section B.28. JTextArea
Section B.29. JTextField Section B.30. JTextPane Section B.31. JToggleButton Section B.32. JToolBar Section B.33. JToolTip Section B.34. JTree Section B.35. JViewport
Section B.36. Non-JComponent Containers Section B.37. Auditory Feedback Actions
Colophon Index I l@ve RuBoard
I l@ve RuBoard
Copyright
Copyright © 2003, 1998 O'Reilly & Associates, Inc.
Printed in the United States of America.
Published by O'Reilly & Associates, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472.
O'Reilly & Associates books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (http://safari.oreilly.com). For more information, contact our corporate/institutional sales department: (800) 998-9938 or corporate@oreilly.com.
Nutshell Handbook, the Nutshell Handbook logo, and the O'Reilly logo are registered trademarks of O'Reilly &
Associates, Inc. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and O'Reilly & Associates, Inc. was aware of a trademark claim, the designations have been printed in caps or initial caps. The association between the image of a spider monkey and the topic of Java Swing is a trademark of O'Reilly & Associates, Inc. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc., in the United States and other countries. O'Reilly & Associates, Inc. is independent of Sun Microsystems, Inc.
While every precaution has been taken in the preparation of this book, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.
I l@ve RuBoard
I l@ve RuBoard
Preface
When Java was first released, its user interface facilities were a significant weakness. The Abstract Window Toolkit (AWT) was part of the JDK from the beginning, but it really wasn't sufficient to support a complex user interface. It supported everything you could do in an HTML form and provided free-standing frames, menus, and a few other objects, but you'd be hard-pressed to implement an application as complex as Quicken or Lotus Notes. AWT also had its share of portability problems; it relied heavily on the runtime platform's native user interface components, and it wasn't always possible to hide differences in the way these components behaved.
JDK 1.1 fixed a number of problems—most notably, it introduced a new event model that was much more efficient and easier to use—but it didn't make any major additions to the basic components. We got a
ScrollPane
and aPopupMenu
, but that was about it. Furthermore, AWT still relied on the native components and therefore continued to have portability problems.In April 1997, Sun's Java group (then called JavaSoft) announced the Java Foundation Classes, or JFC, which supersedes (and includes) AWT. A major part of the JFC was a set of much more complete, flexible, and portable user interface components called "Swing." (The JFC also includes a comprehensive facility for 2D graphics, printing, and Drag and Drop.) With Swing, you can design interfaces with tree components, tables, tabbed dialogs, tooltips, and a growing set of other features that computer users are accustomed to.
In addition to the new components, Swing made three major improvements to the AWT. First, Swing doesn't rely on the runtime platform's native components. It's written entirely in Java and creates its own components. This approach solved most of the portability problems since components don't inherit weird behaviors from the runtime environment or do they work against its grain. Second, because Swing is in complete control of the components, it's in control of the way components look on the screen and gives you more control over how your applications look. You can choose between several pre-built "look-and-feels" (L&Fs), or you can create your own if you want your software to show your personal style (more appropriate for games than for daily productivity software, of course). This feature is called
"Pluggable Look-and-Feel," or PLAF. Third, Swing makes a very clear distinction between the data a component displays (the "model") and the actual display (the "view"). While the fine points of this distinction are appreciated mostly by computer scientists, it has important implications for all developers. This separation means that components are extremely flexible. It's easy to adapt components to display new kinds of data that their original design didn't anticipate or to change the way a component looks without getting tangled up in assumptions about the data it represents.
The first official release of Swing, for use with JDK 1.1, took place in the spring of 1998. Swing (and the rest of JFC) was built into Java 2 and revolutionized Java user interface development. The Swing components continue to evolve with Java, and Java 2 SDK 1.4 is the best version yet. This book shows you how to join the revolution.
I l@ve RuBoard
I l@ve RuBoard
What This Book Covers
This book gives a complete introduction to the entire Swing component set. Of course, it shows you how to use all of the components: how to display them on the screen, register for events, and get information from them. You'd expect that in any Swing book. This book goes much further. It goes into detail about the model-delegate architecture behind the components and discusses all of the data models. Understanding the models is essential when you're working on an application that requires something significantly different from the components' default behavior. For example, if you need a component that displays a different data type or one that structures data in some nonstandard way, you'll need to work with the data models. This book also discusses how to write "accessible" user interfaces and how to create your own look-and-feel.
There are a few topics this book doesn't cover, despite its girth. We assume you know the Java language. For Swing, it's particularly important to have a good grasp of inner classes (both named and anonymous), which are used by Swing itself and in our examples. We assume that you understand the JDK 1.1 event model, Java's mechanism for communicating between asynchronous threads. Swing introduced many new event types, all of which are discussed in this book, but we provide only an overview of the event mechanism as a whole. We also assume that you
understand the older AWT components, particularly the
Component
andContainer
classes, which aresuperclasses of the Swing's
JComponent
. We assume that you understand the AWT layout managers, all of which are usable within Swing applications. If you are new to Java, or would like a review, you can find a completediscussion of these topics in the Java AWT Reference by John Zukowski[1]
or a solid introduction in Learning Java by Pat Niemeyer and Jonathan Knudsen (both published by O'Reilly). We do not assume that you know anything about other JFC topics, like Java 2D—check out Java 2D by Jonathan Knudsen for that; all the drawing and font
manipulation in this book can be done with AWT. (We do cover the JFC Accessibility API, which is supported by every Swing component, as well as the drag-and-drop facility, since this functionality is a requirement for modern user interfaces.)
[1] PDFs for the Java AWT Reference are available at this book's web site, http://www.oreilly.com/catalog/jswing2.
The major Swing classes fall into the following packages:
javax.accessibility
Classes that support accessibility for people who have difficulty using standard user interfaces. Covered in Chapter 25.
javax.swing
The bulk of the Swing components. Covered in Chapter 3-Chapter 14 and Chapter 27-Chapter 28.
javax.swing.border
Classes for drawing fancy borders around components. Covered in Chapter 13.
javax.swing.colorchooser
Classes providing support for the
JColorChooser
component. Covered in Chapter 12.javax.swing.event
Swing events. Covered throughout the book.
javax.swing.filechooser
Classes providing support for the
JFileChooser
component. Covered in Chapter 12.javax.swing.plaf
Classes supporting the PLAF, including classes that implement the Metal and Multi L&Fs. (Implementations of the Windows and Motif L&Fs are packaged under
com.sun.java.swing.plaf
, and the Macintosh Aqua L&F is undercom.apple.mrj.swing
.) Covered in Chapter 26.javax.swing.table
Classes providing support for the
JTable
component (JTable
itself is injavax.swing
). Covered in Chapter 15 and Chapter 16.javax.swing.text
Classes providing support for the text components (such as
JTextField
; the components themselves are in thejavax.swing
package). Covered in Chapter 19-Chapter 23.javax.swing.text.html and javax.swing.text.rtf
"Editor kits" for working with HTML and Microsoft RTF documents. Covered in Chapter 23. The
text.html
package has a subpackage,parser
, which includes tools for parsing HTML.javax.swing.tree
Classes providing support for the
JTree
component (JTree
itself is injavax.swing
). Covered in Chapter 17.javax.swing.undo
Classes that implement undoable operations. Covered in Chapter 18. I l@ve RuBoard
I l@ve RuBoard
What's New in This Edition?
This second edition covers the latest developments in the Java 2 Standard Edition SDK 1.3 and 1.4. We've tried to highlight the changes from 1.2 in case you have to work with older releases for compatibility or political reasons.
For brevity's sake, we refer to Java versions by their SDK version number, describing this or that feature as having been introduced in SDK 1.3 or 1.4. Earlier versions were called Java Development Kits, so in those cases we refer to
JDK 1.1 or 1.2.
This new edition incorporated your feedback from the first edition! The first edition was too heavy on the
documentation side for many readers. The Javadoc for the Swing packages continues to improve, and more and more people are familiar with the patterns of Java classes and methods. With those two facts in mind, we try to focus on the parts of the API that are interesting and useful rather than just including them because they exist. We added many new examples and improved the existing examples. This book is a true and thorough revision of the first edition, not a mere update.
As a quick reference to some of the changes you'll find in the 1.3 and 1.4 releases of the SDK, Table P-1 and Table P-2 list any significant changes to components and briefly describe those changes. We detail these changes throughout the book as we discuss the particular components.
Table P-1. Swing changes in the Java 2 SDK 1.3
Component or
feature In chapter Description of changes or additions
JTree
Chapter 17 Several new properties were added, including the click count to start editing and the selection path.JTable
Chapter 15 Improved general performance and cell rendering.AbstractCellEditor
is now the parent class of theDefaultCellEditor
used by tables.JSplitPane
Chapter 11 A newresizeWeight
property was added, and thedividerLocationProperty
is now bound.JFileChooser
Chapter 12 You can now remove the Ok and Cancel buttons. A new property,acceptAllFileFilterUsed
, was added.JCheckBox
Chapter 5 Added newborderPaintedFlat
property.DefaultButtonModel
Chapter 5 Added newgetGroup( )
method.JInternalFrame
Chapter 9Several fixes and newly public classes and methods. Internal frames are now invisible by default, and the default close operation is now
DISPOSE_ON_CLOSE
.JTabbedPane
Chapter 11 Added newtoolTipTextAt
indexed property.Text components Chapter 19-Chapter 23
Several fixes applied. Several improvements in general HTML support via the
HTMLEditorKit
and related classes. (XHTML documents are still not supported.)JViewport
Chapter 11 NewscrollMode
property added.JComponent
Chapter 3 New print methods added:printComponent( )
,printBorder( )
,printChildren( )
.InputVerifier
Chapter 20 New class added.Keyboard binding Chapter 3, Appendix B
New keyboard binding mechanism added. New classes,
InputMap
andActionMap
, replaceKeymap
functionality.Border
s Chapter 13 NewLineBorder
constructor to support rounded corners added.Action
sChapter 3, Chapter 5, Chapter 14
AbstractAction
class was updated, and new constructors forJCheckBox
,JRadioButton
,JToggleButton
,JMenu
,JMenuItem
,JCheckBoxMenuItem
, andJRadioButtonMenuItem
that useAction
were added.JToolBar
Chapter 14 Support for titling undocked toolbars added.JPopupMenu
Chapter 14 Added newpopupTrigger
boolean property.JFrame
Chapter 11 Added newEXIT_ON_CLOSE
constant for use with thedefaultCloseOperation
property.ListenerList
Chapter 27Added
getListeners( )
method to several model classes, includingAbstractDocument
,AbstractTableModel
,AbstractListModel
,DefaultButtonModel
,DefaultTreeModel
, andDefaultListSelectionModel
.Table P-2. Swing changes in the Java 2 SDK 1.4
Component or feature In chapter Description of changes or additions
JProgressBar
Chapter 6 Added support for indeterminate progress bars.JSpinner
Chapter 7 Added new spinner class.JFormattedTextField
Chapter 20 Added new formatted text field class that validates user input.Focus
Chapter 3,Chapter 28
A new focus model and methodology was introduced.
Several of the old-style focus methods and classes were deprecated as of 1.4.1.
Drag and Drop Chapter 24
New architecture introduced, and
dragEnabled
andtransferHandler
properties added to several components.Box
Chapter 11 Now descends fromJComponent
.JButton
Chapter 5 More control over mnemonic underline location granted.JComboBox
Chapter 7 AddedPopupMenuListener
and support for cell size prototyping.JFileChooser
Chapter 12Added support for modifying the properties of the Open button (such as its text and tooltip). Also added support for selecting multiple files. (The multiple file selection mode was introduced in the 1.2 release but was not implemented until 1.4.)
JInternalFrame
Chapter 9 Long titles are now truncated, and the title bar is rendered with a gradient.Text components
Chapter 19-Chapter 23
Tooltip support was improved. HTML support, including accessibility in documents, was improved (XHTML is still not supported). New
replace( )
method added toAbstractDocument
.JOptionPane
Chapter 10 New input dialog methods added.JPopupMenu
Chapter 14 Now properly supports key bindings.JTabbedPane
Chapter 11Introduced scrollable tabs for panes with a large number of tabs. Mnemonic support for accessing tabs was also added.
JTree
Chapter 17 Null roots are now allowed, and first-letter keyboard navigation was added.JList
Chapter 7 Items can now be arranged horizontally, and first-letter keyboard navigation was added.SwingConstants
Chapter 27 New constants,NEXT
andPREVIOUS
, were added.SwingUtilities
Chapter 27 New methods added, includingcalculateInnerArea(
)
andapplyComponentOrientation( )
LookAndFeel
Chapter 3, Chapter 26, Appendix B
General support for auditory cues was added. Access to Windows desktop properties was also added.
JComponent
Chapter 3requestFocus( )
andrequestFocusInWindow( )
methods are now public.MouseWheelEventMouseWheelListener
Chapter 11 New event and listener for mouse wheels added.JRootPane
Chapter 10 Look-and-feel can now supply window decoration.JScrollBar
Chapter 6 Now properly overridessetUI( )
.JScrollPane
Chapter 11 Now supports mouse wheel events. (This support can be turned off.)RepaintManager
Chapter 28 New method to return aVolatileImage
.SpringLayout
Chapter 11 New class (and supporting classes) added.I l@ve RuBoard
I l@ve RuBoard
On the Web Site
The web site for this book, http://www.oreilly.com/catalog/jswing2/, offers some important materials you'll want to know about. All the examples in this book can be found there, as well as free utilities, PDFs of John Zukowski's Java AWT Reference (foundational for understanding Swing), and selected material from the first edition for those of you working with older SDKs.
The examples are available as a JAR file, a ZIP archive, and a compressed TAR archive. The files named swing were tested against J2SE SDK 1.4 for this edition. The files named swing-1e were tested against JDK 1.2 for the first edition of the book. The files named swing-old were written with the beta releases of Swing and use the
com.java.swing
hierarchies.We also include a few free utilities on the site that you may want to check out:
macmetrics.jar
Lee Ann Rucker's MacMetrics theme. See Section 26.1 for details on this helpful tool that enables developers without access to Mac OS X to see how their applications' interfaces will look on that platform.
oraswing.jar
Our very own utilities bundle with documentation, including:
eel.jar
The Every Event Listener utility for debugging events from the various Swing and AWT components.
relativelayout.jar
A nifty XML-based layout manager.
mapper.jar
A quick helper for discovering the InputMap and ActionMap entries (both bound and unbound) for any given component. This is the utility we used to build Appendix B.
We may add other utilities as we receive feedback from readers, so be sure to check the README file on the site!
We owe a debt of gratitude to John Zukowski and O'Reilly & Associates, who have graciously allowed the classic Java AWT Reference to be placed online at our site. You can download PDFs of the entire book.
The web site also includes some expanded material that we couldn't shoehorn into this edition of the book. For those of you still working with JDK 1.2, we've included a PDF containing the " Keyboard Actions" section from Chapter 3 of the first edition—the approach changed markedly with SDK 1.3. Regardless of your version of Java, if you're planning on extending the
HTMLEditorKit
, you should check out the expanded material online. We cover the basics of this editor kit in Chapter 23, but for those of you who want to dig in deep, you should download PDFs of the two chaptersdevoted to this topic..
I l@ve RuBoard
I l@ve RuBoard
Conventions
This book follows certain conventions for font usage, property tables, and class diagrams. Understanding these conventions up-front makes it easier to use this book.
This book uses the following font conventions:
Italic
Used for filenames, file extensions, URLs, application names, emphasis, and new terms when they are first introduced
Constant width
Used for Java class names, functions, variables, components, properties, data types, events, and snippets of code that appear in text
Constant width bold
Used for commands you enter at the command line and to highlight new code inserted in a running example
Constant width italic
Used to annotate output
This icon designates a note, which is an important aside to the nearby text.
This icon designates a warning relating to the nearby text.
Properties Tables
Swing components are all JavaBeans. Properties provide a powerful way to work with JavaBeans, so we use tables throughout the book to present lists of properties. Table P-3 is an example from the hypothetical JFoo class that shows how we use these tables.
Table P-3. Properties of the fictional JFoo class
Property Data type get is set Default value
opaqueb, o, 1.4 boolean · · · true
bbound, ooverridden, 1.4since 1.4
See also properties from the JComponent class (Table 3-6).
Properties tables tell you the data type; whether it has is, get, and set methods; and its default value, if any. Footnotes to the properties tables tell you, among other things, whether a property is bound, protected, indexed, and/or overridden. We use
"overridden" to mean both actual overridden methods in the case of a concrete parent class and implemented methods in the case of an abstract parent class or an interface. If it is a recent addition, the version of the SDK that added the property is noted (assume 1.2 if there is no footnote).
Table P-3 indicates that a JFoo object has a read/write bound property named opaque with the data type boolean. The property was introduced in the 1.4 release of the SDK. This property has accessor methods with the signatures:
public boolean getOpaque( );
public boolean isOpaque( );
public void setOpaque(boolean opaque);
These methods aren't listed separately when we discuss the class's other methods. Because opaque is a bound property, changing its value generates a PropertyChange-Event. The overridden footnote indicates that the opaque property is also inherited (or possibly implemented for the first time); it is listed here because the JFoo class has altered the property in some way—e.g., the default value was changed, accessor methods were added, or new behavior when accessing or modifying the value was specified. A cross-reference following the table says that JFoo has inherited properties from the JComponent class;
see the discussion of that class for details on these properties.
We've listed default values for properties wherever applicable. (Properties of interfaces, for example, will not have any values listed.) To save space, we omit the new operator in these tables.
One more note about bound properties. The Swing developers introduced some confusion into the notion of a "bound property"
by adding a new lightweight event, ChangeEvent, which is a stateless version of PropertyChangeEvent. In these tables, we adhere strictly to the JavaBeans definition of a bound property: modifying a bound property generates a
PropertyChangeEvent.
Class Diagrams
The class diagrams that appear throughout the book are similar to those in Learning Java and other Java books from O'Reilly.
Solid lines indicate inheritance relationships; dotted lines indicate interface relationships. In Figure P-1, ClassA extends AbstractClass, which implements InterfaceX. There are two interface relationships that we don't show in this way. All Swing classes implement Serializable, and showing this relationship explicitly would clutter the diagram; just assume that any Swing class implements Serializable, unless stated otherwise in the text. Many Swing classes implement the Accessible interface;
rather than cluttering the diagrams, we show that a class implements Accessible with an A icon.
We also use the class diagrams to show information about relations between classes. In Figure P-1, the long, dashed arrow indicates that ClassA uses ClassB. The label on the arrow indicates the nature of the relationship; other common relations are
"contains" and "creates." 1..* indicates the multiplicity of the relationship. Here, an instance of ClassA uses one or more
instances of ClassB. Other multiplicities are 1 (exactly one instance), 0..* (any number of instances), and 0..1 (zero or one instance).
Figure P-1. Class diagram notation
I l@ve RuBoard
I l@ve RuBoard
How to Contact Us
Along with O'Reilly, we have verified the information in this book to the best of our abilities, but you may find that features have changed (or even that we have made mistakes!). Please let us know about any errors you find, as well as your suggestions for future editions, by writing to:
O'Reilly & Associates, Inc.
1005 Gravenstein Highway North Sebastopol, CA 95472
(800) 998-9938 (U.S. and Canada) (707) 829-0515 (international/local) (707) 829-0104 (fax)
You can also contact O'Reilly by email. To be put on the mailing list or request a catalog, send a message to:
info@oreilly.com
We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at:
http://www.oreilly.com/catalog/jswing2/
To ask technical questions or comment on the book, send email to:
bookquestions@oreilly.com
For more information about O'Reilly books, conferences, Resource Centers, and the O'Reilly Network, see O'Reilly's web site at:
http://www.oreilly.com/
I l@ve RuBoard
I l@ve RuBoard
Acknowledgments
We're particularly indebted to our technical reviewers for this second edition: Christian Hessler, John Pyeatt, Maciek Smuga-Otto, and Dave Wood.
Marc Loy
I'll start off the mutual admiration society by thanking my cohorts Jim and Brian. They came to the table after we lost Dave and Bob (from the first edition) to other books, and well, life in general. This update would not have been possible without them. Our editor Deb Cameron has the patience and diligence of some very patient and diligent god.
I continue to be amazed by the support and insight I receive from my colleagues Tom Berry, Damian Moshak, and Brooks Graham. Gratitude for the inspiration to keep writing (even if it is technical) goes to Amy Hammond, my sister and confidante. A special thanks to Kathy Godeken for an early push in the right direction. Words are not enough to thank my partner Ron, so I'll not waste the space.
Brian Cole
Thanks to my family for putting up with me as an author. This goes tenfold for my partner, Beth, for that and more.
Thanks to Deb, who was very understanding about deadlines, and especially to Marc and Jim, who were always willing to lend a hand despite deadlines of their own. Thanks to my employers and coworkers, who were willing to accommodate my schedule. Finally, thanks to the anonymous programmer who discovered that running java with
-Dsun.java2d.noddraw=true
fixes the appalling 1.3 drawing problems common on Win32 systems equipped with some popular types of video cards. You saved me a lot of time.James Elliott
Any list of thanks has to start with my parents for fostering my interest in computing even when we were living in countries that made that a major challenge, and with my partner Joe for putting up with it today when it has flowered into a major obsession. I'd also like to acknowledge my Madison employer, Berbee, for giving me an opportunity to delve deeply into Java and build skills as an architect of reusable APIs; for letting me stay clear of the proprietary, platform-specific tar pit that is engulfing so much of the programming world; for surrounding me with such incredible colleagues; and for being supportive when I wanted to help with this book. Of course, I have Marc to thank for getting me involved in this crazy adventure in the first place, and Deb for helping make sense of it.
I wanted to be sure this edition gave good advice about how to work with Swing on Mac OS X, Apple's excellent, Unix-based environment for Java development, so I asked for some help. Lee Ann Rucker (who should also be thanked for her heroic work of single-handedly implementing the new Mac OS Look-and-Feel while on loan from Sun
to Apple) shared some great ideas and approaches to writing solid, cross-platform Java applications, including the MacMetrics theme described in Chapter 26. Count me among the many people wishing Sun or Apple would put her back on the Mac Java team! Eric Albert, another frequent source of insight on Apple's Java-Dev mailing list, gave me more suggestions and pointed me to his excellent chapter in Early Adopter Mac OS X Java (Wrox Press). Finally, Matt Drance at Apple's Developer Technical Support sent me an early (and helpful) version of his technical note on how to make Java applications as Mac-friendly as possible. There are many others to whom I'm indebted, but I've already used more than my fair share of space, so the rest of you know who you are!
We all want to thank the many members of O'Reilly's production department, who put in lots of work under a tight schedule.
I l@ve RuBoard
I l@ve RuBoard
Chapter 1. Introducing Swing
Welcome to Swing! By now, you're probably wondering what Swing is and how you can use it to spice up your Java applications. Or perhaps you're curious as to how the Swing components fit into the overall Java strategy. Then again, maybe you just want to see what all the hype is about. Well, you've come to the right place; this book is all about Swing and its components. So let's dive right in and answer the first question that you're probably asking right now, which is...
I l@ve RuBoard
I l@ve RuBoard
1.1 What Is Swing?
If you poke around the Java home page (http://java.sun.com/ ), you'll find Swing described as a set of customizable graphical components whose look-and-feel (L&F) can be dictated at runtime. In reality, however, Swing is much more than this. Swing is the next-generation GUI toolkit that Sun Microsystems created to enable enterprise development in Java. By enterprise development , we mean that programmers can use Swing to create large-scale Java
applications with a wide array of powerful components. In addition, you can easily extend or modify these components to control their appearance and behavior.
Swing is not an acronym. The name represents the collaborative choice of its designers when the project was kicked off in late 1996. Swing is actually part of a larger family of Java products known as the Java Foundation Classes ( JFC), which incorporate many of the features of Netscape's Internet Foundation Classes (IFC) as well as design aspects from IBM's Taligent division and Lighthouse Design. Swing has been in active development since the beta period of the Java Development Kit ( JDK) 1.1, circa spring of 1997. The Swing APIs entered beta in the latter half of 1997 and were initially released in March 1998. When released, the Swing 1.0 libraries contained nearly 250 classes and 80 interfaces. Growth has continued since then: at press time, Swing 1.4 contains 85 public interfaces and 451 public classes.
Although Swing was developed separately from the core Java Development Kit, it does require at least JDK 1.1.5 to run. Swing builds on the event model introduced in the 1.1 series of JDKs; you cannot use the Swing libraries with the older JDK 1.0.2. In addition, you must have a Java 1.1-enabled browser to support Swing applets. The Java 2 SDK 1.4 release includes many updated Swing classes and a few new features. Swing is fully integrated into both the developer's kit and the runtime environment of all Java 2 releases (SDK 1.2 and higher), including the Java Plug-In.
1.1.1 What Are the Java Foundation Classes?
The FC is a suite of libraries designed to assist programmers in creating enterprise applications with Java. The Swing API is only one of five libraries that make up the JFC. The JFC also consists of the Abstract Window Toolkit (AWT), the Accessibility API, the 2D API, and enhanced support for Drag and Drop capabilities. While the Swing API is the primary focus of this book, here is a brief introduction to the other elements in the JFC:
AWT
The Abstract Window Toolkit is the basic GUI toolkit shipped with all versions of the Java Development Kit.
While Swing does not reuse any of the older AWT components, it does build on the lightweight component facilities introduced in AWT 1.1.
Accessibility
The accessibility package provides assistance to users who have trouble with traditional user interfaces.
Accessibility tools can be used in conjunction with devices such as audible text readers or braille keyboards to allow direct access to the Swing components. Accessibility is split into two parts: the Accessibility API, which is shipped with the Swing distribution, and the Accessibility Utilities API, which is distributed
separately. All Swing components support accessibility, so this book dedicates an entire chapter (Chapter 25) to accessibility design and use.
2D API
The 2D API contains classes for implementing various painting styles, complex shapes, fonts, and colors.
This Java package is loosely based on APIs that were licensed from IBM's Taligent division. The 2D API classes are not part of Swing, so they are not covered in this book.
Drag and Drop
Drag and Drop (DnD) is one of the more common metaphors used in graphical interfaces today. The user is allowed to click and "hold" a GUI object, moving it to another window or frame in the desktop with predictable results. The DnD API allows users to implement droppable elements that transfer information between Java applications and native applications. Although DnD is not part of Swing, it is crucial to a commercial-quality application. We tackle this topic in Chapter 24.
Figure 1-1 enumerates the various components of the Java Foundation Classes. Because part of the Accessibility API is shipped with the Swing distribution, we show it overlapping Swing.
Figure 1-1. The five APIs of the JFC
1.1.2 Is Swing a Replacement for AWT?
No. Swing is actually built on top of the core AWT libraries. Because Swing does not contain any platform-specific (native) code, you can deploy the Swing distribution on any platform that implements the Java 1.1.5 or above virtual machine. In fact, if you have JDK 1.2 or higher on your platform, then the Swing classes are already available, and there's nothing further to download. If you use a JDK version prior to 1.2, you can download the entire set of Swing libraries as a set of Java Archive (JAR) files from the Swing home page, http://java.sun.com/products/jfc. In either case, it is generally a good idea to visit this URL for any extra packages or L&Fs that may be distributed separately from the core Swing libraries.
Figure 1-2 shows the relationship between Swing, AWT, and the Java Development Kit in the 1.1 and higher JDKs. In JDK 1.1, the Swing classes must be downloaded separately and included as an archive file on the classpath
(swingall.jar).[1] JDK 1.2 (and higher) comes with a Swing distribution.
[1] The standalone Swing distributions contain several other JAR files. swingall.jar is everything (except the contents of multi.jar) wrapped into one lump and is all you normally need to know about. For completeness, the other JAR files are: swing.jar, which contains everything but the individual L&F packages; motif.jar, which contains the Motif (Unix) L&F; windows.jar, which contains the Windows L&F; multi.jar, which contains a special L&F that allows additional (often nonvisual) L&Fss to be used in conjunction with the primary L&F; and beaninfo.jar, which contains special classes used by GUI development tools.
Figure 1-2. Relationships between Swing, AWT, and the JDK in the 1.1 and higher SDKs
Swing contains many more graphical components than its immediate predecessor, AWT 1.1. Many are components that were scribbled on programmer wishlists since Java first debuted—including tables, trees, internal frames, and a plethora of advanced text components. In addition, Swing contains many design advances over AWT. For example, Swing introduced an
Action
class that makes it easier to coordinate GUI components with their functionality. You'll also find that a much cleaner design prevails throughout Swing; this cuts down on the number of unexpected surprises that you're likely to face while coding.Swing depends extensively on the event-handling mechanism of AWT 1.1, although it does not define a
comparatively large amount of events for itself. Each Swing component also contains a variable number of exportable properties. This combination of properties and events in the design was no accident. Each of the Swing components, like the AWT 1.1 components before them, adhere to the popular JavaBeans specification. As you might have guessed, this means that you can import all of the Swing components into various GUI builder tools, which is useful for powerful visual programming.
1.1.3 Rethinking the AWT
To understand why Swing exists, it helps to understand the market forces that drive Java as a whole. The Java Programming Language was developed in 1993 and 1994, largely under the guidance of James Gosling and Bill Joy at Sun Microsystems, Inc. When Sun released the Java Development Kit on the Internet, it ignited a firestorm of
excitement that swept through the computing industry. At first, developers primarily experimented with Java for applets , mini-programs embedded in web browsers. However, as Java matured over the course of the next two years, many developers began using Java to develop full-scale applications.
Or at least they tried. As developers ported Java to more and more platforms, its weak points started to show. The language was robust and scalable, extremely powerful as a networking tool, and served well as an easy-to-learn successor to the more established C++. The primary criticism, however, was that it was an interpreted language, which means that by definition it executed code slower than its native, compiled equivalents. Consequently, many developers flocked to just-in-time (JIT) compilers—highly optimized interpreters—to speed up their large-scale applications. This solved many problems, but one weak point that continually received scathing criticism was the graphical widgets that Java was built on: the Abstract Window Toolkit (AWT). The primary issue here was that AWT provided only the minimal amount of functionality necessary to create a windowing application. For enterprise applications, it quickly became clear that programmers needed something bigger.
After nearly a year of intense scrutiny, the AWT classes were ready for a change. From Java 1.0 to Java 1.1, the AWT reimplemented its event model from a "chain" design to an "event subscriber" design. This meant that instead of propagating events through a predefined hierarchy of components, interested classes simply registered with other components to receive noteworthy events. Because events typically involve only the sender and receiver, this eliminated much of the overhead in propagating them. When component events were triggered, an event object was passed only to those classes interested in receiving them.
Sun developers also began to see that relying on native widgets for the AWT components was proving to be troublesome. Similar components looked and behaved differently on many platforms, and coding for the
ever-expanding differences of each platform became a maintenance nightmare. In addition, reusing the component widgets for each platform limited the abilities of the components and proved to be expensive on system memory.
Clearly, Sun knew that AWT wasn't enough. It wasn't that the AWT classes didn't work; they simply didn't provide the functionality necessary for full-scale enterprise applications. At the 1997 JavaOne Conference in San Francisco, JavaSoft announced the Java Foundation Classes. Key to the design of the JFC was that the new Swing
components would be written entirely in Java and have a consistent L&F across platforms. This allowed Swing and the JFC to be used on any platform that supported Java 1.1 or later; all the user had to do was to include the
appropriate JAR files on the
CLASSPATH
to make each of the components available for use. Since JDK 1.2, Swing has been part of the standard Java distribution; no special action is needed to use Swing components.I l@ve RuBoard
I l@ve RuBoard
1.2 Swing Features
Swing provides many features for writing large-scale applications in Java. Here is an overview of some of the more popular features.
1.2.1 Pluggable Look-and-Feels
One of the most exciting aspects of the Swing classes is the ability to dictate the L&F of each of the components, even resetting the L&F at runtime. L&Fs have become an important issue in GUI development over the past 10 years.
Many users are familiar with the Motif style of user interface, which was common in Windows 3.1 and is still in wide use on Unix platforms. Microsoft created a more optimized L&F in their Windows 95/98/NT/2000 operating systems.
In addition, the Macintosh computer system has its own carefully designed L&F, which most Apple users feel comfortable with.
Swing is capable of emulating several L&Fs and currently supports the Windows, Unix Motif, and "native" Java Metal L&Fs. Mac OS X comes with full support for its own L&F based on Apple's Aqua Human Interface Guidelines, although you can still access Metal if you prefer. In addition, Swing allows the user to switch L&Fs at runtime without having to close the application. This way, a user can experiment to see which L&F is best for her with instantaneous feedback. (In practice, nobody really does this, but it's still pretty cool from a geeky point of view.) And, if you're feeling really ambitious as a developer (perhaps a game developer), you can create your own L&F for each one of the Swing components!
The Metal L&F combines some of the best graphical elements in today's L&Fs and even adds a few surprises of its own. Figure 1-3 shows an example of several L&Fs that you can use with Swing, including the Metal L&F. All Swing L&Fs are built from a set of base classes called the Basic L&F. However, though we may refer to the Basic L&F from time to time, you can't use it on its own. If you're lucky enough to be developing applications in the Mac OS X environment, you'll be familiar with the L&F shown in Figure 1-4.
Figure 1-3. Various L&Fs in the Java Swing environment
1.2.2 Lightweight Components
Most Swing components are lightweight. In the purest sense, this means that components are not dependent on native peers to render themselves. Instead, they use simplified graphics primitives to paint themselves on the screen and can even allow portions to be transparent.
Figure 1-4. The new Mac L&F in OS X
The ability to create lightweight components first emerged in JDK 1.1, although the majority of AWT components did not take advantage of it. Prior to that, Java programmers had no choice but to subclass
java.awt.Canvas
orjava.awt.Panel
if they wished to create their own components. With both classes, Java allocated an opaque peer object from the underlying operating system to represent the component, forcing each component to behave as if it were its own window, thereby taking on a rectangular, solid shape. Hence, these components earned the name"heavyweight" because they frequently held extra baggage at the native level that Java did not use.
Heavyweight components were unwieldy for two reasons:
Equivalent components on different platforms don't necessarily act alike. A list component on one platform, for example, may work differently than a list component on another. Trying to coordinate and manage the differences between components was a formidable task.
The L&F of each component was tied to the host operating system and could not be changed.
With lightweight components, each component renders itself using the drawing primitives of the
Graphics
object (e.g.,drawLine( )
,fillRect( )
, etc.). Lightweight components always render themselves onto the surface of the heavyweight top-level component they are contained in. With the arrival of JDK 1.1, programmers can directly extend thejava.awt.Component
orjava.awt.Container
classes when creating lightweight components. Unlikejava.awt.Canvas
orjava.awt.Panel
, these classes do not depend on a native peer and allow the developer to render quickly to the graphics context of the container. This results in faster, less memory-intensive components than were previously available in Java.Almost all of the Swing components are lightweight; only a few top-level containers are not. This design allows programmers to draw (and redraw) the L&F of their application at runtime, instead of tying it to the L&F of the host operating system. In addition, the design of the Swing components supports easy modification of component behavior. For example, you can tell almost any Swing component whether you wish it to accept or decline focus and how it should handle keyboard input.
1.2.3 Additional Features
Several other features distinguish Swing from the older AWT components:
Swing has wide variety of new components, such as tables, trees, sliders, spinners, progress bars, internal frames, and text components.
Swing components support the replacement of their insets with an arbitrary number of nested borders.
Swing components can have tooltips placed over them. A tooltip is a textual pop up that momentarily appears when the mouse cursor rests inside the component's painting region. Tooltips can be used to give more information about the component in question.
You can arbitrarily bind keyboard events to components, defining how they react to various keystrokes under given conditions.
There is additional debugging support for rendering your own lightweight Swing components.
We discuss each of these features in greater detail as we move through the next three chapters.
1.2.4 How Can I Use Swing?
Not everyone uses Swing for the same reasons. In fact, the Swing libraries have many levels of use, with varying levels of prerequisite knowledge. Here are some potential uses:
Use the Swing components as they are to build your own enterprise applications.
Create your own Swing components—or extend those that already exist.
Override or create a new L&F for one or more of the Swing components.
The first approach is what the vast majority of Swing programmers use. Here, using Swing components is just like using the AWT components. A familiar set of components, containers, and layout managers are all available in the Swing packages to help you get your application up and running quickly. If you're adept at AWT programming, you probably need only a cursory introduction to each component to get started. You will we need to get into broader issues only if you use some of the larger and newer component families, such as tables and text. If you are planning to use each component as a JavaBean for visual programming, you also fall into this category.
Creating your own component, or extending an existing one, requires a deeper understanding of Swing. This includes a firm understanding of Swing architecture, events, and lower-level classes. Also, if you decide to subclass a Swing component, the responsibilities of that component must be adopted and handled accordingly—otherwise, your new component may perform erratically.
Finally, you may wish to change the L&F of one or more Swing components. This is arguably the most complex of the three routes that you can take—it requires a thorough knowledge of the design, architectural fundamentals, and graphical primitives of each lightweight component. In addition, you need to understand how Swing's
UIManager
andUIDefaults
classes work together to "set" each component's L&F.This book strives to help you with each of these issues. Because we anticipate that the vast majority of readers are in the first category, we spend a great deal of time reviewing each component's properties and methods, as well as providing source code for various scenarios that use these components. We try to document and illustrate the useful
parts of the components. The online documentation (called Javadoc) has matured along with the rest of Java; the current stuff is always there first.
Programming your own L&F can get pretty complex; in fact, the source code for an entire L&F would far exceed the size of this book. However, we don't want to leave you in the dark. If you are an experienced Swing programmer already, and you're looking for a concise introduction on how to get started, see Chapter 26. This chapter provides details on working with L&Fs as well as examples of how to code your own L&F for both simple and complex Swing components.
I l@ve RuBoard
I l@ve RuBoard
1.3 Swing Packages and Classes
Here is a short description of each package in the Swing libraries:
javax.accessibility
Contains classes and interfaces that can be used to allow assistive technologies to interact with Swing components.
Assistive technologies cover a broad range of items, from audible text readers to screen magnification. Although the accessibility classes are technically not part of Swing, they are used extensively throughout the Swing components.
We discuss the accessibility package in greater detail in Chapter 25.
javax.swing
Contains the core Swing components, including most of the model interfaces and support classes.
javax.swing.border
Contains the definitions for the abstract border class as well as eight predefined borders. Borders are not components; instead, they are special graphical elements that Swing treats as properties and places around components in place of their insets. If you wish to create your own border, you can subclass one of the existing borders in this package, or you can code a new one from scratch.
javax.swing.colorchooser
Contains support for the JColorChooser component, discussed in Chapter 12.
javax.swing.event
Defines several new listeners and events that Swing components use to communicate asynchronous information between classes. To create your own events, you can subclass various events in this package or write your own event class.
javax.swing.filechooser
Contains support for the JFileChooser component, discussed in Chapter 12.
javax.swing.plaf
Defines the unique elements that make up the pluggable L&F for each Swing component. Its various subpackages
