Java AWT Reference (Java Series) [1 ed.] 1565922409, 9781565922402

Table of contents :
front page
ch00 Preface
New Features of AWT in Java 1.1
Deprecated Methods and JavaBeans
Other Changes in Java
What This Book Covers
Organization
About the Source Code
Obtaining the Example Programs
Other Java Books and Resources
About Java
Conventions Used in This Book
Request for Comments
Acknowledgments
ch01 Abstract Window Toolkit Overview
Components
Static Text
User Input
Event Triggers
Expansion
Peers
Layouts
FlowLayout
GridLayout
BorderLayout
CardLayout
GridBagLayout
Containers
Panels
Windows
Frames
Dialog and FileDialog
ScrollPane
And the Rest
Drawing and Objects
Events
Applets
Clipboards
Printing
Summary
ch02 Simple Graphics
Graphics
Graphics Methods
Point
Point Methods
Dimension
Dimension Methods
Shape
Shape Method
Rectangle
Rectangle Methods
ch03 Fonts and Colors
Fonts
The Font Class
FontMetrics
The FontMetrics Class
Font Display Example
Color
Color Methods
SystemColor
SystemColor Methods
Displaying Colors
ch04 Events
Java 1.0 Event Model
Identifying the Target
Dealing With Events
Passing the Buck
Overriding handleEvent( )
Basic Event Handlers
The Event Class
Variables
Constants
Event Methods
Working With Mouse Buttons in Java 1.0
Comprehensive Event List
The Java 1.1 Event Model
Using the 1.1 Event Model
AWTEvent and Its Children
Event Listener Interfaces and Adapters
AWTEventMulticaster
ch05 Components
Component
Component Methods
Component Events
Labels
Label Methods
Buttons
Button Methods
Button Events
A Simple Calculator
Canvas
Canvas Methods
Canvas Events
Creating Your Own Components
VerticalLabel
Lightweight VerticalLabel
Cursor
Cursor Constants
Cursor Methods
ch06 Containers
Container
Container Methods
Panel
Panel Methods
Panel Events
Insets
Insets Methods
Insets Example
Window
Window Methods
Window Events
Frames
Frame Constants
Frame Constructors
Frame Methods
Frame Events
Building a New Component from a Window
Dialogs
Dialog Constructors and Methods
Dialog Events
Dialog Example
FileDialog
FileDialog Methods
A FileDialog Example
ch07 Layouts
The LayoutManager Interface
Methods of the LayoutManager Interface
The LayoutManager2 Interface
FlowLayout
FlowLayout Methods
BorderLayout
BorderLayout Methods
GridLayout
GridLayout Methods
CardLayout
CardLayout Methods
CardLayout Example
GridBag Layout
GridBagLayout Methods
GridBagConstraints
GridBagConstraints Methods
Combining Layouts
Disabling the LayoutManager
Designing Your Own LayoutManager
LayoutManager Methods
A New LayoutManager: CornerLayout
The sun.awt Layout Collection
HorizBagLayout
VerticalBagLayout
VariableGridLayout
OrientableFlowLayout
Other Layouts Available on the Net
ch08 Input Fields
Text Component
TextComponent Methods
TextComponent Events
TextField
TextField Methods
TextField Events
TextArea
TextArea Variables
TextArea Methods
TextArea Events
Extending TextField
ch09 Pick Me
Choice
Component Methods
Choice Events
Lists
List Methods
List Events
Checkbox
Checkbox Methods
Checkbox Events
CheckboxGroup
CheckboxGroup Methods
ItemSelectable
Methods
ch10 Would You Like to Choose from the Menu
MenuComponent
MenuComponent Methods
MenuContainer
MenuContainer Methods
MenuShortcut
MenuShortcut Methods
MenuItem
MenuItem Methods
MenuItem Events
Menu
Menu Methods
Menu Events
CheckboxMenuItem
CheckboxMenuItem Methods
CheckboxMenuItem Events
MenuBar
MenuBar Methods
MenuBar Events
Putting It All Together
Using Java 1.1 Events
PopupMenu
PopupMenu Methods
ch11 Scrolling
Scrollbar
Scrollbar Methods
Scrollbar Methods
Scrolling An Image
The Adjustable Interface
Constants of the Adjustable Interface
Methods of the Adjustable Interface
ScrollPane
ScrollPane Methods
ScrollPane Events
Using a ScrollPane
ch12 Image Processing
ImageObserver
ImageObserver Interface
Overriding imageUpdate
ColorModel
ColorModel Methods
DirectColorModel
IndexColorModel
ImageProducer
ImageProducer Interface
FilteredImageSource
MemoryImageSource
ImageConsumer
ImageConsumer Interface
PixelGrabber
ImageFilter
ImageFilter Methods
RGBImageFilter
CropImageFilter
ReplicateScaleFilter
AreaAveragingScaleFilter
Cascading Filters
ch13 AWT Exceptions and Errors
AWTException
AWTException Method
Throwing an AWTException
IllegalComponentStateException
IllegalComponentStateException Method
IllegalComponentStateException Example
AWTError
AWTError Method
Throwing an AWTError
ch14 And Then There Were Applets
What's a Java Applet
Applet Methods
AudioClip Interface
Methods
Using an AudioClip
AppletContext Interface
Methods
AppletStub Interface
Methods
Audio in Applications
AudioData
AudioStream
AudioDataStream
ContinuousAudioDataStream
AudioStreamSequence
AudioPlayer
SunAudioClip Class Definition
ch15 Toolkit and Peers
Toolkit
Toolkit Methods
The Peer Interfaces
ch16 Data Transfer
DataFlavor
DataFlavor Methods
Transferable Interface
Methods
ClipboardOwner Interface
Methods
Clipboard
Clipboard Methods
StringSelection
StringSelection Methods
UnsupportedFlavorException
UnsupportedFlavorException Method
Reading and Writing the Clipboard
ch17 Printing
PrintGraphics Interface
Methods
PrintJob Class
Constructor and Pseudo-Constructor
Methods
Component Methods
Printing Example
Printing Arbitrary Content
ch18 java.applet Reference
Introduction to the Reference Chapters
Applet
AppletContext
AppletStub
AudioClip
ch19 java.awt Reference
AWTError
AWTEvent
AWTEventMulticaster
AWTException
Adjustable
BorderLayout
Button
Canvas
CardLayout
Checkbox
CheckboxGroup
CheckboxMenuItem
Choice
Color
Component
Container
Cursor
Dialog
Dimension
Event
EventQueue
FileDialog
FlowLayout
Font
FontMetrics
Frame
Graphics
GridBagConstraints
GridBagLayout
GridLayout
IllegalComponentStateException
Image
Insets
ItemSelectable
Label
LayoutManager
LayoutManager2
List
MediaTracker
Menu
MenuBar
MenuComponent
MenuContainer
MenuItem
MenuShortcut
Panel
Point
Polygon
PopupMenu
PrintGraphics
PrintJob
Rectangle
ScrollPane
Scrollbar
Shape
SystemColor
TextArea
TextComponent
TextField
Toolkit
Window
ch20 java.awt.datatransfer Reference
Clipboard
ClipboardOwner
DataFlavor
StringSelection
Transferable
UnsupportedFlavorException
ch21 java.awt.event Reference
ActionEvent
ActionListener
AdjustmentEvent
AdjustmentListener
ComponentAdapter
ComponentEvent
ComponentListener
ContainerAdapter
ContainerEvent
ContainerListener
FocusAdapter
FocusEvent
FocusListener
InputEvent
ItemEvent
ItemListener
KeyAdapter
KeyEvent
KeyListener
MouseAdapter
MouseEvent
MouseListener
MouseMotionAdapter
MouseMotionListener
PaintEvent
TextEvent
TextListener
WindowAdapter
WindowEvent
WindowListener
ch22 java.awt.image Reference
AreaAveragingScaleFilter
ColorModel
CropImageFilter
DirectColorModel
FilteredImageSource
ImageConsumer
ImageFilter
ImageObserver
ImageProducer
IndexColorModel
MemoryImageSource
PixelGrabber
ReplicateScaleFilter
RGBImageFilter
ch23 java.awt.peer Reference
ButtonPeer
CanvasPeer
CheckboxMenuItemPeer
CheckboxPeer
ChoicePeer
ComponentPeer
ContainerPeer
DialogPeer
FileDialogPeer
FontPeer
FramePeer
LabelPeer
LightweightPeer
ListPeer
MenuBarPeer
MenuComponentPeer
MenuItemPeer
MenuPeer
PanelPeer
PopupMenuPeer
ScrollbarPeer
ScrollPanePeer
TextAreaPeer
TextComponentPeer
TextFieldPeer
WindowPeer
appa Using Properties and Resources
System Properties
Server Properties
Resource Bundles
appb HTML Markup for Applets
The Applet Tag
appc Platform-Specific Event Handling
The Results
Test Program
How to Use the Program
Source Code
Examining Results
appd Image Loading
How Images are Loaded
A Brief Tour of sun.awt.image
index

Citation preview

Preface The Abstract Window Tookit (AWT) provides the user interface for Java programs. Unless you want to construct your own GUI or use a crude text-only interface, the AWT provides the tools you will use to communicate with the user. Although we are beginning to see some other APIs for building user interfaces, like Netscape’s IFC (Internet Foundation Classes), those alternative APIs will not be in widespread use for some time, and some will be platform specific. Likewise, we are beginning to see automated tools for building GUIs in Java; Sun’s JavaBeans effort promises to make such tools much more widespread. (In fact, the biggest changes in Java 1.1 prepare the way for using the various AWT components as JavaBeans.) However, even with automated tools and JavaBeans in the future, an in-depth knowledge of AWT is essential for the practicing Java programmer. The major problem facing Java developers these days is that AWT is a moving target. Java 1.0.2 is being replaced by Java 1.1, with many significant new features. Java 1.1 was released on February 18, 1997, but it isn’t clear how long it will take for 1.1 to be accepted in the market. The problem facing developers is not just learning about the new features and changes in Java 1.1, but also knowing when they can afford to use these new features in their code. In practice, this boils down to one question: when will Netscape Navigator support Java 1.1? Rumor has it that the answer is “as soon as possible”—and we all hope this rumor is correct. But given the realities of maintaining a very complex piece of software, and the fact that Netscape is currently in the beta process for Navigator 4.0, there’s a possibility that “as soon as possible” and “soon” aren’t the same thing. In other words, you should expect Java 1.0.2 to stick around for a while, especially since Web users won’t all replace their browsers as soon as Navigator has 1.1 support.

xv

10 July 2002 22:16

xvi

PREFACE

This state of affairs raises obvious problems for my book. Nothing would have made me happier than to write a book that covered AWT 1.1 only. It would be significantly shorter, for one thing, and I wouldn’t have to spend so much effort pointing out which features are present in which release. But that’s not the current reality. For the time being, programmers still need to know about 1.0.2. Therefore, this book covers both releases thoroughly. There are many examples using 1.0.2; many more examples that require 1.1; and more examples showing you how to update 1.0.2 code to use 1.1’s features. Sun has done a good job of maintaining compatibility between versions: 1.0 code runs under Java 1.1, with very few exceptions. All of the 1.0 examples in this book have been tested under Java 1.1. However, Java 1.1—and particularly, AWT 1.1 — offer many advantages over older releases. If nothing else, I hope this book convinces you that you should be looking forward to the day when you can forget about writing code for Java 1.0.2.

New Features of AWT in Java 1.1 Having spent all this time talking about 1.0.2 and 1.1 and the transitional state we’re currently in and having alluded briefly to the advantages of Java 1.1, you deserve a brief summary of what has changed. Of course, you’ll find the details in the book. Improved event handling Java 1.1 provides a completely new event model. Instead of propagating events to all objects that might possibly have an interest, objects in Java 1.1 register their interest in particular kinds of events and get only the events they’re interested in hearing. The old event model is still supported, but the new model is much more efficient. The new event model is also important in the context of JavaBeans. The old events were pretty much specific to AWT. The new model has been designed as a general purpose feature for communication between software components. Unfortunately, how to use events in this more general sense is beyond the scope of this book, but you should be aware that it’s possible. New components and containers Java 1.1 provides one new component, the PopupMenu, and one new container, the ScrollPane. Pop-up menus are a staple of modern user interfaces; providing them fixes a serious omission. ScrollPane makes it trivial to implement scrolling; in Java 1.0, you had to do scrolling “by hand.” In Java 1.1, you also get menu shortcuts (i.e., the ability to select menu items using the keyboard), another standard feature of modern user interfaces.

10 July 2002 22:16

PREFACE

xvii

Java 1.1 also introduces a LightweightPeer, which means that it is possible to create “lightweight components.” To do so, you subclass Component or Container directly; this wasn’t possible in earlier releases. For simple operations, lightweight components are much more efficient than full-fledged components. Clipboards Java 1.1 lets you read from and write to the system clipboard and create private clipboards for use by your programs. The clipboard facility is a down payment on a larger data transfer facility, which will support drag and drop. (No promises about when drag and drop will appear.) Printing Java 1.1 gives components the ability to print. The rest There are many other new features, including more flexible use of cursors; the ability to use system color schemes, and thus make your program look like other software in the run-time environment; more image filters to play with; and the ability to prescale an image.

Deprecated Methods and JavaBeans One of the biggest changes in Java 1.1 doesn’t concern the feature set at all. This was the addition of many new methods that differ from a method of Java 1.0 in name only. There are hundreds of these, particularly in AWT. The new method names show an important future direction for the AWT package (in fact, all of Java). The new names obey the naming conventions used by JavaBeans, which means that all AWT classes are potentially Beans. These conventions make it possible for an application builder to analyze what a component does based on its public methods. For example, the method setFont() changes the value of the component’s Font property. In turn, this means that you will eventually be able to build user interfaces and, in some cases, entire applications, inside some other tool, without writing any Java code at all. An application builder will be able to find out what it needs to know about any component by looking at the component itself, and letting you customize the component and its interactions with others. Comments in the JDK source code indicate that the older method names have been “deprecated,” which means that you should consider the old names obsolete and avoid using them; they could disappear in a future release. Reworking AWT to comply with JavaBeans is both necessary and inevitable. Furthermore, it’s a good idea to get into the habit of following the same conventions for your own code; the advantages of JavaBeans are much greater than the inconvenience of changing your coding style.

10 July 2002 22:16

xviii

PREFACE

Other Changes in Java Other new features are scattered throughout the rest of the Java classes, most notably, improvements in the networking and I/O packages and support for internationalization. Some new features were added to the language itself, of which the most important is “inner classes.” For the most part, I don’t discuss these changes; in fact, I stay away from them and base non-AWT code on the 1.0.2. release. Though these changes are important, covering the new material in AWT is enough for one book. If I used a new feature at this point, I would feel that I owed you an explanation, and this book is already long enough. A future edition will update the code so that it doesn’t rely on any older features.

What This Book Covers The Java AWT Reference is the definitive resource for programmers working with AWT. It covers all aspects of the AWT package, in versions 1.0.2 and 1.1. If there are any changes to AWT after 1.1 (at least two patch releases are expected), we will integrate them as soon as possible. Watch the book’s Web site http://www.ora.com/catalog/javawt/ for details on changes. Specifically, this book completely covers the following packages: java.awt (1.0 and 1.1) java.awt.image (1.0 and 1.1) java.awt.event (new to 1.1) java.awt.datatransfer (new to 1.1) java.awt.peer (1.0 and 1.1) java.applet (1.0 and 1.1)

The book also covers some aspects of the sun.awt package (some interesting and useful layout managers) and the sun.audio package (some more flexible ways of working with audio files). It also gives a brief overview of the behind-the-scenes machinery for rendering images, much of which is in the sun.awt.image package.

Organization The Java AWT Reference is divided into two large parts. The first part is a thorough guide to using AWT. Although this guide is organized by class, it was designed to flow logically, rather than alphabetically. I know that few people read a book like this from beginning to end, but if you want to, it’s possible. With a few exceptions, you should be able to read the early chapters without knowing the material that’s covered in the later chapters. You’ll want to read this section to find out how any chunk of the AWT package works in detail.

10 July 2002 22:16

PREFACE

xix

The second part is a set of documentation pages typical of what you find in most reference sets. It is organized alphabetically by package, and within each package, alphabetically by class. It is designed to answer questions like “What are the arguments to the FilteredImageSource constructor?” The reference section provides brief summaries, rather than detailed discussions and examples. When you use a typical reference book, you’re usually trying to look up some detail, rather than learn how something works from scratch. In other words, this book provides two views of AWT: terse summaries designed to help you when you need to look something up quickly, and much more detailed explanations designed to help you understand how to use AWT to the fullest. In doing so, it goes well beyond the standard reference manual. A reference manual alone gives you a great view of hundreds of individual trees; this book gives you the trees, but also gives you the forest that allows you to put the individual pieces in context. There are dozens of complete examples, together with background information, overview material, and other information that doesn’t fit into the standard reference manual format.

About the Source Code The source code for the programs presented in this book is available online. See http://www.ora.com/catalog/javawt/ for downloading instructions.

Obtaining the Example Programs The example programs in this book are available electronically in a number of ways: by FTP, Ftpmail, BITFTP, and UUCP. The cheapest, fastest, and easiest ways are listed first. If you read from the top down, the first one that works for you is probably the best. Use FTP if you are directly on the Internet. Use Ftpmail if you are not on the Internet but can send and receive electronic mail to Internet sites (this includes CompuServe users). Use BITFTP if you send electronic mail via BITNET. Use UUCP if none of the above works.

FTP To use FTP, you need a machine with direct access to the Internet. A sample session is shown, with what you should type in boldface. % ftp ftp.ora.com Connected to ftp.ora.com. 220 FTP server (Version 6.21 Tue Mar 10 22:09:55 EST 1992) ready. Name (ftp.ora.com:yourname): anonymous 331 Guest login ok, send domain style e-mail address as password. Password: [email protected] (use your user name and host here) 230 Guest login ok, access restrictions apply. ftp> cd /published/oreilly/java/awt

10 July 2002 22:16

xx

PREFACE 250 CWD command successful. ftp> binary (Very important! You must specify binary transfer for compressed files.) 200 Type set to I. ftp> get examples.tar.gz 200 PORT command successful. 150 Opening BINARY mode data connection for examples.tar.gz. 226 Transfer complete. ftp> quit 221 Goodbye. %

The file is a compressed tar archive; extract the files from the archive by typing: % zcat examples.tar.gz | tar xvf -

System V systems require the following tar command instead: % zcat examples.tar.gz | tar xof -

If zcat is not available on your system, use separate gunzip and tar commands. % gunzip examples.tar.gz % tar xvf examples.tar

Ftpmail Ftpmail is a mail server available to anyone who can send electronic mail to, and receive it from, Internet sites. This includes any company or service provider that allows email connections to the Internet. Here’s how you do it. You send mail to [email protected]. (Be sure to address the message to ftpmail and not to ftp.) In the message body, give the FTP commands you want to run. The server will run anonymous FTP for you and mail the files back to you. To get a complete help file, send a message with no subject and the single word “help” in the body. The following is a sample mail session that should get you the examples. This command sends you a listing of the files in the selected directory and the requested example files. The listing is useful if there’s a later version of the examples you’re interested in. % mail [email protected] Subject: reply-to [email protected] open cd /published/oreilly/java/awt dir mode binary uuencode get examples.tar.gz quit .

10 July 2002 22:16

Where you want files mailed

PREFACE

xxi

A signature at the end of the message is acceptable as long as it appears after “quit.” BITFTP BITFTP is a mail server for BITNET users. You send it electronic mail messages requesting files, and it sends you back the files by electronic mail. BITFTP currently serves only users who send it mail from nodes that are directly on BITNET, EARN, or NetNorth. BITFTP is a public service of Princeton University. Here’s how it works.

To use BITFTP, send mail containing your FTP commands to BITFTP@PUCC. For a complete help file, send HELP as the message body. The following is the message body you send to BITFTP: FTP ftp.uu.net NETDATA USER anonymous PASS [email protected] Put your Internet email address here (not your BITNET address) CD /published/oreilly/java/awt DIR BINARY GET examples.tar.gz QUIT

Once you’ve got the desired file, follow the directions under FTP to extract the files from the archive. Since you are probably not on a UNIX system, you may need to get versions of uudecode, uncompress, atob, and tar for your system. VMS, DOS, and Mac versions are available. The VMS versions are on gatekeeper.dec.com in /pub/VMS. UUCP UUCP is standard on virtually all UNIX systems and is available for IBM-compatible PCs and Apple Macintoshes. The examples are available by UUCP via modem from UUNET; UUNET’s connect-time charges apply.

If you or your company has an account with UUNET, you have a system somewhere with a direct UUCP connection to UUNET. Find that system, and type: uucp uunet\!˜/published/oreilly/java/awt/examples.tar.gz yourhost\!˜/yourname/

The backslashes can be omitted if you use the Bourne shell (sh) instead of csh. The file should appear some time later (up to a day or more) in the directory /usr/spool/uucppublic/yourname. If you don’t have an account, but would like one so that you can get electronic mail, contact UUNET at 703-204-8000. Once you’ve got the desired file, follow the directions under FTP to extract the files from the archive.

10 July 2002 22:16

xxii

PREFACE

Other Java Books and Resources This book is part of a series of Java books from O’Reilly & Associates that covers everything you wanted to know, and then some. The Java AWT Reference is paired with the Java Fundamental Class Reference to document the entire Core Java API. Other books in the series provide an introduction (Exploring Java) and document the virtual machine ( Java Virtual Machine), the language ( Java Language Reference), multithreaded programming ( Java Threads), and network programming ( Java Network Programming), with more to come. Java in a Nutshell is another popular Java book in the Nutshell series from O’Reilly. For a complete up-to-date list of the available Java resources, refer to http://www.ora.com/info/java/. In addition to the resources from O’Reilly, Sun’s online documentation on Java is maintained at http://www.javasoft.com/nav/download/index.html. Information on specific Java-capable browsers can be found at their respective Web sites, which are listed in Table 1. More are sure to be on the way. (Some browsers are platform specific, while others are multi-platform.) Table 1: Popular Web Browsers that Support Java Browser

Location

Netscape Navigator

http://home.netscape.com/comprod/products/navigator/

Microsoft’s Internet Explorer

http://www.microsoft.com/ie

Sun’s HotJava

http://www.javasoft.com/HotJava/

Oracle’s PowerBrowser

http://www.oracle.com/products/websystem/powerbrowser

Apple’s Cyberdog

http://cyberdog.apple.com/

Newsgroups also serve as a discussion area for Java-related topics. The comp.lang.java group has formally split into several others. The new groups are: comp.lang.java.advocacy comp.lang.java.announce comp.lang.java.beans comp.lang.java.databases comp.lang.java.gui comp.lang.java.help

comp.lang.java.machine comp.lang.java.programmer comp.lang.java.security comp.lang.java.setup comp.lang.java.softwaretools comp.lang.java.tech

For folks without time to dig through all the noise, Digital Espresso provides a periodic digest of the newsfeed at http://www.io.org./˜mentor/DigitalEspresso.html. A list of

10 July 2002 22:16

PREFACE

xxiii

Java FAQs is at http://www-net.com/java/faq/; one of the most interesting is Cafe Au Lait, at http://sunsite.unc.edu/javafaq/. (Cafe Au Lait is written by Elliotte Rusty Harold, author of Java Network Programming.) Local Java user groups are another good resource. (Having founded one myself, I’m biased.) What they offer varies greatly, but unless you look at one, you are potentially leaving out a vast resource for knowledge and experience. Lists of area user groups are available from JavaSoft at http://www.javasoft.com/Mail/usrgrp.html; also check out the Sun User Group’s Special Interest Group for Users of Java at http://www.sug.org/Java/groups.html. In addition to the usual monthly meetings and forums, some maintain a mailing list for technical exchanges. Security is a major issue with Java. If you are interested in reading more about Java security issues, Princeton University’s Safe Internet Programming Web site at http://www.cs.princeton.edu/sip/News.html is an excellent resource.

About Java Java is one of 13,000 islands that makes up Indonesia, whose capital is Jakarta (see Figure 1). It is home to about 120 million people with an area about 50,000 square miles. While on the island, you can hear traditional music such as gamelan or angklung. The island also has a dangerous volcano named Merapi, which makes up part of the Pacific “Ring of Fire.” In 1891, fossils from Pithecanthropus erectus, better known as “Java man” (homo javanensis) were discovered on the island by Eugene Dubois. Java’s main export is a coffee that is considered spicy and full bodied, with a strong, slightly acidic flavor. O’Reilly has shown good taste in staying away from the pervasive coffee theme in its book titles and cover designs. (However, if you’re ever in Sebastopol, check out the coffee at AromaRoasters in Santa Rosa.)

Conventions Used in This Book Italic is used for: •

Pathnames, filenames, and program names

•

Internet addresses, such as domain names and URLs

Typewriter Font is used for:

•

10 July 2002 22:16

Anything that might appear in a Java program, including keywords, method names, variables names, class names, and interface names

xxiv

PREFACE

BRUNEI

MALAYSIA

MALAYSIA

Jakarta

I N D O N E S I A

JAVA

Indian Ocean AUSTRALIA

Figure 1: Map of Java, Indonesia

•

Command lines and options that should be typed verbatim on the screen

•

Tags that might appear in an HTML document

To sort out the potential for confusion between different versions, I use the following dingbats throughout the book: ★ Identifies a method, variable, or constant that is new in Java 1.1. ✩ Identifies a method from Java 1.0 that has been deprecated. Deprecated methods are available for compatibility but may disappear in a future release. These methods are tagged with the @deprecated flag, which causes the Java 1.1 compiler to display a warning message if you use them.

Request for Comments We invite you to help us improve the book. If you have an idea that could make this a more useful resource, or if you find a bug in an example program or an error in the text, please let us know by sending email to [email protected]. As Java continues to evolve, we may find it necessary to issue errata for this book or to release updated examples or reference information. This information will be found at the book’s Web site http://www.ora.com/catalog/javawt/.

10 July 2002 22:16

PREFACE

xxv

Acknowledgments I am grateful to many people who helped me along while working on this book, especially my wife, Lisa, and her patience during this whole process. A special thanks goes to our Old English sheep dog, Sir Dudley Fuzzybuns McDuff for gladly sharing the house with me during the entire process. I am grateful to the people at Sun who helped me become involved with Java so early on: Pete Seymour, Anne Pettitt, Tom McGinn, and Jen Sullivan-Volpe. I am also grateful to my employers, Rapid Systems Solutions (when I started) and the MageLang Institute (when I finished), who let me work on the book. Another thanks goes out to Dale Carnegie Training and John Captain, whose human relations class helped me feel comfortable with public speaking, without which I would not have become immersed in Java so quickly. Particular thanks are owed to the technical reviewers: Yadu Zambre, Andy Cohen, David Flanagan, Jen Sullivan-Volpe, and Dan Jacobs. All of them performed an invaluable service with their thorough reviews and helped spot my errors and omissions. It seemed everyone contributed many bits of text that eventually found their way into the final product. Random thanks go out to the many people on the Internet who I never met but provided valuable information, from the newsgroups and mailing lists: Simon “FISH” Morris, Mike Gallant, Eric Link, and many others whose names I did not write down. Bits and pieces of various figures were borrowed from David Flanagan’s book, Java in a Nutshell, and Patrick Niemeyer’s and Joshua Peck’s book, Exploring Java. The class hierarchy diagrams come from David’s book. These diagrams were based on similar diagrams by Charles L. Perkins. His original efforts are available at http://rendezvous.com/java/. For the gang at O’Reilly who gave me the opportunity to write this work, I thank everyone who helped along the way. For series editor, Mike Loukides, thanks for all your time and effort, especially with the early drafts. Best of luck to Mike and Judy with their new bundle of joy, Alexandra. Special thanks to Jonathan Knudsen who updated the reference section for the new release. Thanks to Nancy Crumpton and John Files for book production and project management, and to Trina Jackson, Paula Ferguson, and Andy Oram who helped during the review stages. Thanks also to the O’Reilly Tools group, Ellen Siever, Erik Ray, and Lenny Muellner; to Seth Maislin, the indexer; and David Futato and Danny Marcus who handled the proofreading and QCs. The final product is much better because of their help.

10 July 2002 22:16

10 July 2002 22:16

In this chapter: • Components • Peers • Layouts • Containers • And the Rest • Summary

1 Abstract Window Toolkit Overview

For years, programmers have had to go through the hassles of porting software from BSD-based UNIX to System V Release 4–based UNIX, from OpenWindows to Motif, from PC to UNIX to Macintosh (or some combination thereof), and between various other alternatives, too numerous to mention. Getting an application to work was only part of the problem; you also had to port it to all the platforms you supported, which often took more time than the development effort itself. In the UNIX world, standards like POSIX and X made it easier to move applications between different UNIX platforms. But they only solved part of the problem and didn’t provide any help with the PC world. Portability became even more important as the Internet grew. The goal was clear: wouldn’t it be great if you could just move applications between different operating environments without worrying about the software breaking because of a different operating system, windowing environment, or internal data representation? In the spring of 1995, Sun Microsystems announced Java, which claimed to solve this dilemma. What started out as a dancing penguin (or Star Trek communicator) named Duke on remote controls for interactive television has become a new paradigm for programming on the Internet. With Java, you can create a program on one platform and deliver the compilation output (byte-codes/class files) to every other supported environment without recompiling or worrying about the local windowing environment, word size, or byte order. The first generation of Java programs consisted mostly of fancy animation applets that ran in a web browser like Netscape Navigator, Internet Explorer, or HotJava. We’re beginning to see the next generation now: powerful distributed applications in areas ranging from commerce to medical imaging to network management. All of these applications require extreme portability: Joe’s Online Bait Shop doesn’t have the time or

1

10 July 2002 22:16

2

CHAPTER 1: ABSTRACT WINDOW TOOLKIT OVERVIEW

energy to port its “Online Bait Buyer” program to every platform on the Internet but doesn’t want to limit its market to a specific platform. Java neatly solves their problem. Windowing systems present the biggest challenges for portability. When you move an application from Windows to the Macintosh, you may be able to salvage most of the computational guts, but you’ll have to rewrite the window interface code completely. In Java, this part of the portability challenge is addressed by a package called AWT, which stands for Abstract Window Toolkit (although people have come up with many other expansions). AWT provides the magic of maintaining the local look and feel of the user’s environment. Because of AWT, the same application program can look appropriate in any environment. For example, if your program uses a pull-down list, that list will look like a Windows list when you run the program under Windows; a Macintosh list when you run the program on a Mac; and a Motif list when you run the program on a UNIX system under Motif. The same code works on all platforms. In addition to providing a common set of user interface components, AWT provides facilities for manipulating images and generating graphics. This book is a complete programmer’s guide and reference to the java.awt package (including java.awt.image, java.awt.event, java.awt.datatransfer, and java.awt.peer). It assumes that you’re already familiar with the Java language and class libraries. If you aren’t, Exploring Java, by Pat Niemeyer and Josh Peck, provides a general introduction, and other books in the O’Reilly Java series provide detailed references and tutorials on specific topics. This chapter provides a quick overview of AWT: it introduces you to the various GUI elements contained within the java.awt package and gives you pointers to the chapters that provide more specific information about each component. If you’re interested in some of the more advanced image manipulation capabilities, head right to Chapter 12, Image Processing. The book ends with a reference section that summarizes what you need to know about every class in AWT. In using this book, you should be aware that it covers two versions of AWT: 1.0.2 and 1.1. The Java 1.1 JDK ( Java Developer’s Kit) occurred in December 1996. This release includes many improvements and additions to AWT and is a major step forward in Java’s overall functionality. It would be nice if I could say, “Forget about 1.0.2, it’s obsolete — use this book to learn 1.1.” However, I can’t; at this point, since browsers (Netscape Navigator in particular) still incorporate 1.0.2, and we have no idea when they will incorporate the new release. As of publication, Navigator 4.0 is in beta test and incorporates 1.0.2. Therefore, Java release 1.0.2 will continue to be important, at least for the foreseeable future.

10 July 2002 22:16

1.1

COMPONENTS

3

In this summary, we’ll point out new features of Java 1.1 as they come up. However, one feature deserves mention and doesn’t fit naturally into an overview. Many of the methods of Java 1.0.2 have been renamed in Java 1.1. The old names still work but are “deprecated.” The new names adhere strictly to the design patterns discussed in the JavaBeans documentation:* all methods that retrieve the value of an object’s property begin with “get,” all methods that set the value of a property begin with “set,” and all methods that test the value of some property begin with “is.” For example, the size() method is now called getSize(). The Java 1.1 compiler issues warnings whenever you used a deprecated method name.

1.1 Components Modern user interfaces are built around the idea of “components”: reusable gadgets that implement a specific part of the interface. They don’t need much introduction: if you have used a computer since 1985 or so, you’re already familiar with buttons, menus, windows, checkboxes, scrollbars, and many other similar items. AWT comes with a repertoire of basic user interface components, along with the machinery for creating your own components (often combinations of the basic components) and for communicating between components and the rest of the program. The next few sections summarize the components that are part of AWT. If you’re new to AWT, you may find it helpful to familiarize yourself with what’s available before jumping into the more detailed discussions later in this book.

1.1.1 Static Text The Label class provides a means to display a single line of text on the screen. That’s about it. They provide visual aids to the user: for example, you might use a label to describe an input field. You have control over the size, font, and color of the text. Labels are discussed in Section 5.2. Figure 1-1 displays several labels with different attributes.

1.1.2 User Input Java provides several different ways for a user to provide input to an application. The user can type the information or select it from a preset list of available choices. The choice depends primarily on the desired functionality of the program, the user-base, and the amount of back-end processing that you want to do.

* http://splash.javasoft.com/beans/spec.html

10 July 2002 22:16

4

CHAPTER 1: ABSTRACT WINDOW TOOLKIT OVERVIEW

Figure 1–1: Multiple Label instances

1.1.2.1 The TextField and TextArea classes Two components are available for entering keyboard input: TextField for single line input and TextArea for multi-line input. They provide the means to do things from character-level data validation to complex text editing. These are discussed in much more detail in Chapter 8, Input Fields. Figure 1-2 shows a screen that contains various TextField and TextArea components.

Figure 1–2: TextField and TextArea elements

1.1.2.2 The Checkbox and CheckboxGroup classes The remaining input-oriented components provide mechanisms for letting the user select from a list of choices. The first such mechanism is Checkbox, which lets you select or deselect an option. The left side of the applet in Figure 1-3 shows a checkbox for a Dialog option. Clicking on the box selects the option and makes

10 July 2002 22:16

1.1

COMPONENTS

5

the box change appearance. A second click deselects the option. The CheckboxGroup class is not a component; it provides a means for grouping checkboxes into a mutual exclusion set, often called a set of radio buttons. Selecting any button in the group automatically deselects the other buttons. This behavior is useful for a set of mutually exclusive choices. For example, the right side of the applet in Figure 1-3 shows a set of checkboxes for selecting a font. It makes sense to select only one font at a time, so these checkboxes have been put in a CheckboxGroup.

Windows

Motif

Figure 1–3: Examples of Checkbox and CheckboxGroup

The appearance of a checkbox varies from platform to platform. On the left, Figure 1-3 shows Windows; the right shows Motif. On most platforms, the appearance also changes when a checkbox is put into a CheckboxGroup.

1.1.2.3 The Choice class Checkbox and CheckboxGroup present a problem when the list of choices becomes long. Every element of a CheckboxGroup uses precious screen real estate, which limits the amount of space available for other components. The Choice class was designed to use screen space more efficiently. When a Choice element is displayed

on the screen, it takes up the space of a single item in the list, along with some extra space for decorations. This leaves more space for other components. When the user selects a Choice component, it displays the available options next to or below the Choice. Once the user makes a selection, the choices are removed from the screen, and the Choice displays the selection. At any time, only one item in a Choice may be selected, so selecting an item implicitly deselects everything else. Section 9.1 explores the details of the Choice class. Figure 1-4 shows examples of open (on the right of the screens) and closed (on the left) Choice items in Windows 95 and Motif.

10 July 2002 22:16

6

CHAPTER 1: ABSTRACT WINDOW TOOLKIT OVERVIEW

Windows

Motif

Figure 1–4: Open and closed Choice items

1.1.2.4 The List class Somewhere between Choice and CheckboxGroup in the screen real estate business is a component called List. With a List, the user is still able to select any item. However, the programmer recommends how many items to display on the screen at once. All additional choices are still available, but the user moves an attached scrollbar to access them. Unlike a Choice, a List allows the user to select multiple items. Section 9.2 covers the List component. Figure 1-5 shows List components in different states.

Figure 1–5: List components in different states

10 July 2002 22:16

1.1

COMPONENTS

7

1.1.2.5 Menus Most modern user interfaces use menus heavily; therefore, it’s no surprise that Java supports menus. As you’d expect, Java menus look like the menus in the windowing environment under which the program runs. Currently, menus can only appear within a Frame, although this will probably change in the future. A Menu is a fairly complex object, with lots of moving parts: menu bars, menu items, etc. Java 1.1 adds hot keys to menus, allowing users to navigate a menu interface using keyboard shortcuts. The details of Menu are explored in Chapter 10, Would You Like to Choose from the Menu? Figure 1-6 shows frames with open menus for both Windows and Motif. Since tear-off menus are available on Motif systems, its menus look and act a little differently. Figure 1-6 also includes a tear-off menu. The shortcuts (Ctrl+F8) are newly supported in Java 1.1.

Windows

Motif

Tear-off

Figure 1–6: Examples of menus

1.1.2.6 The PopupMenu class The PopupMenu class is new to Java 1.1. Pop-up menus can be used for context-sensitive, component-level menus. Associated with each Component can be its own popup menu. The details of creating and working with the PopupMenu class and the fun time you have catching their events are covered in Chapter 10, Would You Like to Choose from the Menu? Figure 1-7 shows an example of a pop-up menu.

1.1.3 Event Triggers Java provides two components whose sole purpose is to trigger actions on the screen: Button and Scrollbar. They provide the means for users to signal that they are ready to perform an operation. (Note that all components except labels generate events; I’m singling out buttons and scrollbars because their only purpose is to generate events.)

10 July 2002 22:16

8

CHAPTER 1: ABSTRACT WINDOW TOOLKIT OVERVIEW

Figure 1–7: A Pop-up menu

1.1.3.1 The Scrollbar class Most people are familiar with scrollbars. In a word processor or a web browser, when an image or document is too large to fit on the screen, the scrollbar allows the user to move to another area. With Java, the Scrollbar per forms similarly. Selecting or moving the scrollbar triggers an event that allows the program to process the scrollbar movement and respond accordingly. The details of the Scrollbar are covered in Section 11.1. Figure 1-8 shows horizontal and vertical scrollbars.

Figure 1–8: Horizontal and vertical scrollbars

Note that a scrollbar is just that. It generates events when the user adjusts it, but the program using the scrollbar is responsible for figuring out what to do with the events, such as displaying a different part of an image or the text, etc. Several of

10 July 2002 22:16

1.1

COMPONENTS

9

the components we’ve discussed, like TextArea and List, have built-in scrollbars, saving you the trouble of writing your own code to do the actual scrolling. Java 1.1 has a new container called a ScrollPane that has scrolling built in. By using a scroll pane, you should be able to avoid using scroll bars as a positioning mechanism. An example of ScrollPane appears later in this chapter.

1.1.3.2 The Button class A button is little more than a label that you can click on. Selecting a button triggers an event telling the program to go to work. Section 5.3 explores the Button component. Figure 1-9 shows Button examples.

Figure 1–9: Various buttons

The Java Management API includes a fancier button (ImageButton) with pictures rather than labels. For the time being, this is a standard extension of Java and not in the Core API. If you don’t want to use these extensions, you’ll have to implement an image button yourself.

1.1.4 Expansion 1.1.4.1 The Canvas class The Canvas class is just a blank area; it doesn’t have any predefined appearance. You can use Canvas for drawing images, building new kinds of components, or creating super-components that are aggregates of other components. For example, you can build a picture button by drawing a picture on a Canvas and detecting mouse click events within the area of the Canvas. Canvas is discussed in Section 5.5.

10 July 2002 22:16

10

CHAPTER 1: ABSTRACT WINDOW TOOLKIT OVERVIEW

1.2 Peers Java programs always have the look and feel of the platform they are running on. If you create your program on a UNIX platform and deliver it to Microsoft Windows users, your program will have Motif’s look and feel while you’re developing it, but users will see Microsoft Windows objects when they use it. Java accomplishes this through a peer architecture, shown in Figure 1-10. Native Platform Objects

Win32 / Motif / Mac / …

Peer Interfaces

Java Components

User Subclasses

Figure 1–10: Peer architecture

There are several layers of software between your Java program and the actual screen. Let’s say you are working with a scrollbar. On your screen, you see the scrollbar that’s native to the platform you’re using. This system-dependent scrollbar is the “peer” of the Java Scrollbar object. The peer scrollbar deals with events like mouse clicks first, passing along whatever it deems necessary to the corresponding Java component. The peer interface defines the relationship between each Java component and its peer; it is what allows a generic component (like a Scrollbar) to work with scrollbars on different platforms. Peers are described in Chapter 15, Toolkit and Peers. However, you rarely need to worry about them; interaction between a Java program and a peer takes place behind the scenes. On occasion, you need to make sure that a component’s peer exists in order to find out about platform-specific sizes. This process usually involves the addNotify() method.

1.3 Layouts Layouts allow you to format components on the screen in a platform-independent way. Without layouts, you would be forced to place components at explicit locations on the screen, creating obvious problems for programs that need to run on multiple platforms. There’s no guarantee that a TextArea or a Scrollbar or any other component will be the same size on each platform; in fact, you can bet they won’t be. In an effort to make your Java creations portable across multiple platforms, Sun created a LayoutManager inter face that defines methods to reformat

10 July 2002 22:16

1.3

LAYOUTS

11

the screen based on the current layout and component sizes. Layout managers try to give programs a consistent and reasonable appearance, regardless of the platform, the screen size, or actions the user might take. The standard JDK provides five classes that implement the LayoutManager interface. They are FlowLayout, GridLayout, BorderLayout, CardLayout, and GridBagLayout. All of these layouts are covered in much greater detail in Chapter 7, Layouts. This chapter also discusses how to create complex layouts by combining layout managers and how to write your own LayoutManager. The Java 1.1 JDK includes the LayoutManager2 inter face. This interface extends the LayoutManager inter face for managers that provide constraint-based layouts.

1.3.1 FlowLayout The FlowLayout is the default layout for the Panel class, which includes its most famous subclass, Applet. When you add components to the screen, they flow left to right (centered within the applet) based upon the order added and the width of the applet. When there are too many components to fit, they “wrap” to a new row, similar to a word processor with word wrap enabled. If you resize an applet, the components’ flow will change based upon the new width and height. Figure 1-11 shows an example both before and after resizing. Section 7.2 contains all the FlowLayout details.

Big

Narrow

Figure 1–11: A FlowLayout before and after resizing

1.3.2 GridLayout The GridLayout is widely used for arranging components in rows and columns. As with FlowLayout, the order in which you add components is relevant. You start at row one, column one, move across the row until it’s full, then continue on to the next row. However, unlike FlowLayout, the underlying components are resized to

10 July 2002 22:16

12

CHAPTER 1: ABSTRACT WINDOW TOOLKIT OVERVIEW

fill the row-column area, if possible. GridLayout can reposition or resize objects after adding or removing components. Whenever the area is resized, the components within it are resized. Figure 1-12 shows an example before and after resizing. Section 7.4 contains all the details about GridLayout.

Big

Narrow

Figure 1–12: A GridLayout before and after resizing

1.3.3 BorderLayout BorderLayout is one of the more unusual layouts provided. It is the default layout for Window, along with its children, Frame and Dialog. BorderLayout provides five

areas to hold components. These areas are named after the four different borders of the screen, North, South, East, and West, with any remaining space going into the Center area. When you add a component to the layout, you must specify which area to place it in. The order in which components are added to the screen is not important, although you can have only one component in each area. Figure 1-13 shows a BorderLayout that has one button in each area, before and after resizing. Section 7.3 covers the details of the BorderLayout.

1.3.4 CardLayout The CardLayout is a bit on the strange side. A CardLayout usually manages several components, displaying one of them at a time and hiding the rest. All the components are given the same size. Usually, the CardLayout manages a group of Panels (or some other container), and each Panel contains several components of its own. With a little work, you can use the CardLayout to create tabbed dialog boxes or property sheets, which are not currently part of AWT. CardLayout lets you assign names to the components it is managing and lets you jump to a component by name. You can also cycle through components in order. Figure 1-11, Figure 1-12, and Figure 1-13 show multiple cards controlled by a single CardLayout. Selecting the Choice button displays a different card. Section 7.5 discusses the details of CardLayout.

10 July 2002 22:16

1.4

CONTAINERS

13

Big

Narrow

Figure 1–13: A BorderLayout

1.3.5 GridBagLayout GridBagLayout is the most sophisticated and complex of the layouts provided in the development kit. With the GridBagLayout, you can organize components in

multiple rows and columns, stretch specific rows or columns when space is available, and anchor objects in different corners. You provide all the details of each component through instances of the GridBagConstraints class. Figure 1-14 shows an example of a GridBagLayout. GridBagLayout and GridBagConstraints are discussed in Section 7.6 and Section 7.7.

Figure 1–14: A GridBagLayout

1.4 Containers A Container is a type of component that provides a rectangular area within which other components can be organized by a LayoutManager. Because Container is a subclass of Component, a Container can go inside another Container, which can go inside another Container, and so on, like Russian nesting dolls. Subclassing Container allows you to encapsulate code for the components within it. This allows you to create reusable higher-level objects easily. Figure 1-15 shows the components in a layout built from several nested containers.

10 July 2002 22:16

14

CHAPTER 1: ABSTRACT WINDOW TOOLKIT OVERVIEW

Label

North Text Area

Button

GridLayout Panel

Button

BorderLayout Panel

Button

FlowLayout Panel

Button

Button

Button

East

South

Figure 1–15: Components within containers

1.4.1 Panels A Panel is the basic building block of an applet. It provides a container with no special features. The default layout for a Panel is FlowLayout. The details of Panel are discussed in Section 6.2. Figure 1-16 shows an applet that contains panels within panels within panels.

Figure 1–16: A multilevel panel

1.4.2 Windows A Window provides a top-level window on the screen, with no borders or menu bar. It provides a way to implement pop-up messages, among other things. The default layout for a Window is BorderLayout. Section 6.4 explores the Window class in greater detail. Figure 1-17 shows a pop-up message using a Window in Microsoft Windows and Motif.

10 July 2002 22:16

1.4

CONTAINERS

Windows

15

Motif

Figure 1–17: Pop-up windows

1.4.3 Frames A Frame is a Window with all the window manager’s adornments (window title, borders, window minimize/maximize/close functionality) added. It may also include a menu bar. Since Frame subclasses Window, its default layout is BorderLayout. Frame provides the basic building block for screen-oriented applications. Frame allows you to change the mouse cursor, set an icon image, and have menus. All the details of Frame are discussed in Section 6.5. Figure 1-18 shows an example Frame.

Figure 1–18: A frame

10 July 2002 22:16

16

CHAPTER 1: ABSTRACT WINDOW TOOLKIT OVERVIEW

1.4.4 Dialog and FileDialog A Dialog is a Window that accepts input from the user. BorderLayout is the default layout of Dialog because it subclasses Window. A Dialog is a pop-up used for user interaction; it can be modal to prevent the user from doing anything with the application before responding. A FileDialog provides a prebuilt Dialog box that interacts with the filesystem. It implements the Open/Save dialog provided by the native windowing system. You will primarily use FileDialog with applications since there is no guarantee that an applet can interact with the local filesystem. (Netscape Navigator will throw an exception if you try to use it.) The details of Dialog are revealed in Section 6.6, while FileDialog is discussed in Section 6.7. Figure 1-19 shows sample Dialog and FileDialog boxes.

Dialog

Motif FileDialog

Windows FileDialog

Figure 1–19: Examples of Dialog and FileDialog boxes

10 July 2002 22:16

1.5

AND THE REST

17

1.4.5 ScrollPane Java 1.1 introduces the ScrollPane container. In version 1.0, if you want to have a scrolling area (for example, to display an image that won’t fit onto the screen), you create a panel using BorderLayout that contains scrollbars on the right and bottom, and display part of the image in the rest of the screen. When the user scrolls, you capture the event, figure out what part of the image to display, and update the screen accordingly. Although this works, its performance is poor, and it’s inconvenient. With version 1.1 of Java, you can tell the ScrollPane what needs to scroll; it creates the scrollbars and handles all the events automatically. Section 11.4 covers the ScrollPane; Figure 1-20 shows a ScrollPane. Chapter 11, Scrolling, covers the Adjustable inter face that Scrollbar implements and ScrollPane utilizes.

Figure 1–20: A ScrollPane

1.5 And the Rest Several of the remaining classes within java.awt are important to mention here but did not fit well into a general category. The following sections are a grab bag that summarize the remaining classes.

1.5.1 Drawing and Graphics Java provides numerous primitives for drawing lines, squares, circles, polygons, and images. Figure 1-21 shows a simple drawing. The drawing components of AWT are discussed in Chapter 2, Simple Graphics. The Font, FontMetrics, Color, and SystemColor classes provide the ability to alter the displayed output. With the Font class, you adjust how displayed text will appear. With FontMetrics, you can find out how large the output will be, for the

10 July 2002 22:16

18

CHAPTER 1: ABSTRACT WINDOW TOOLKIT OVERVIEW

specific system the user is using. You can use the Color class to set the color of text and graphics. SystemColor is new to Java 1.1; it lets you take advantage of desktop color schemes. These classes are discussed in Chapter 3, Fonts and Colors.

Figure 1–21: A simple drawing

AWT also includes a number of classes that support more complex graphics manipulations: displaying images, generating images in memory, and transforming images. These classes make up the package java.awt.image, which is covered in Chapter 12.

1.5.2 Events Like most windows programming environments, AWT is event driven. When an event occurs (for example, the user presses a key or moves the mouse), the environment generates an event and passes it along to a handler to process the event. If nobody wants to handle the event, the system ignores it. Unlike some windowing environments, you do not have to provide a main loop to catch and process all the events, or an infinite busy-wait loop. AWT does all the event management and passing for you. Probably the most significant difference between versions 1.0.2 and 1.1 of AWT is the way events work. In older versions of Java, an event is distributed to every component that might conceivably be interested in it, until some component declares that it has handled the event. This event model can still be used in 1.1, but there is also a new event model in which objects listen for particular events. This new model is arguably a little more work for the programmer but promises to be much more efficient, because events are distributed only to objects that want to hear about them. It is also how JavaBeans works.

10 July 2002 22:16

1.6

SUMMARY

19

In this book, examples that are using the older (1.0.2) components use the old event model, unless otherwise indicated. Examples using new components use the new event model. Don’t let this mislead you; all components in Java 1.1 support the new event model. The details of Event for both version 1.0.2 and 1.1 can be found in Chapter 4, Events.

1.5.3 Applets Although it is not a part of the java.awt package, the Core Java API provides a framework for applet development. This includes support for getting parameters from HTML files, changing the web page a browser is displaying, and playing audio files. Chapter 14, And Then There Were Applets, describes all the details of the java.applet package. Because audio support is part of java.applet, portable audio playing is limited to applets. Chapter 14 also shows a nonportable way to play audio in applications. Additional audio capabilities are coming to the Java Core API in the announced extensions.

1.5.4 Clipboards In Java 1.1, programs can access the system clipboard. This process makes it easier to transfer (cut, copy, and paste) data between various other sources and your Java programs and introduces developers to the concepts involved with JavaBeans. Chapter 16, Data Transfer, describes the java.awt.datatransfer package.

1.5.5 Printing Java 1.1 adds the ability to print. Adding printing to an existing program is fairly simple: you don’t have to do much beside adding a Print menu button. Chapter 17, Printing, describes these capabilities.

1.6 Summary The java.awt package provides a great deal of functionality and flexibility. The package goes well beyond the basics presented in this chapter. Do not be intimidated by the vast libraries available to you in Java. With the help of this book, you should get an excellent grasp of the java.awt, java.awt.image, java.awt.datatransfer, java.awt.event, and java.applet packages, along with some pieces of the proprietary sun.awt and sun.audio packages. Do not feel the need to read this book cover to cover. Pick the section that interests you most, where you feel you do not fully understand something, or where you have an immediate question to be answered and dive right in.

10 July 2002 22:16

2

In this chapter: • Graphics • Point • Dimension • Shape • Rectangle • Polygon • Image • MediaTracker

Simple Graphics This chapter digs into the meat of the AWT classes. After completing this chapter, you will be able to draw strings, images, and shapes via the Graphics class in your Java programs. We discuss geometry-related classes— Polygon, Rectangle, Point, and Dimension, and the Shape inter face—you will see these throughout the remaining AWT objects. You will also learn several ways to do smooth animation by using double buffering and the MediaTracker. After reading this chapter, you should be able to do simple animation and image manipulation with AWT. For most applications, this should be sufficient. If you want to look at AWT’s more advanced graphics capabilities, be sure to take a look at Chapter 12, Image Processing.

2.1 Graphics The Graphics class is an abstract class that provides the means to access different graphics devices. It is the class that lets you draw on the screen, display images, and so forth. Graphics is an abstract class because working with graphics requires detailed knowledge of the platform on which the program runs. The actual work is done by concrete classes that are closely tied to a particular platform. Your Java Virtual Machine vendor provides the necessary concrete classes for your environment. You never need to worry about the platform-specific classes; once you have a Graphics object, you can call all the methods of the Graphics class, confident that the platform-specific classes will work correctly wherever your program runs. You rarely need to create a Graphics object yourself; its constructor is protected and is only called by the subclasses that extend Graphics. How then do you get a

20

10 July 2002 22:17

2.1

GRAPHICS

21

Graphics object to work with? The sole parameter of the Component.paint() and Component.update() methods is the current graphics context. Therefore, a Graphics object is always available when you override a component’s paint() and update() methods. You can ask for the graphics context of a Component by calling Component.getGraphics(). However, many components do not have a drawable graphics context. Canvas and Container objects return a valid Graphics object;

whether or not any other component has a drawable graphics context depends on the run-time environment. (The latest versions of Netscape Navigator provide a drawable graphics context for any component, but you shouldn’t get used to writing platform-specific code.) This restriction isn’t as harsh as it sounds. For most components, a drawable graphics context doesn’t make much sense; for example, why would you want to draw on a List? If you want to draw on a component, you probably can’t. The notable exception is Button, and that may be fixed in future versions of AWT.

2.1.1 Graphics Methods Constructors protected Graphics () Because Graphics is an abstract class, it doesn’t have a visible constructor. The way to get a Graphics object is to ask for one by calling getGraphics() or to use the one given to you by the Component.paint() or Component.update() method. The abstract methods of the Graphics class are implemented by some windowing system–specific class. You rarely need to know which subclass of Graphics you are using, but the classes you actually get (if you are using the JDK) are sun.awt.win32.Win32Graphics ( JDK1.0), sun.awt.window.WGraphics ( JDK1.1), sun.awt.motif.X11Graphics, or sun.awt.macos.MacGraphics.

Pseudo-constructors In addition to using the graphics contexts given to you by getGraphics() or in Component.paint(), you can get a Graphics object by creating a copy of another Graphics object. Creating new graphics contexts has resource implications. Certain platforms have a limited number of graphics contexts that can be active. For instance, on Windows 95 you cannot have more than four in use at one time. Therefore, it’s a good idea to call dispose() as soon as you are done with a Graphics object. Do not rely on the garbage collector to clean up for you. public abstract Graphics create () This method creates a second reference to the graphics context. It is useful for clipping (reducing the drawable area).

10 July 2002 22:17

22

CHAPTER 2: SIMPLE GRAPHICS

public Graphics create (int x, int y, int width, int height) This method creates a second reference to a subset of the drawing area of the graphics context. The new Graphics object covers the rectangle from (x, y) through (x+width-1, y+height-1) in the original object. The coordinate space of the new Graphics context is translated so that the upper left corner is (0, 0) and the lower right corner is (width, height). Shifting the coordinate system of the new object makes it easier to work within a portion of the drawing area without using offsets.

Drawing strings These methods let you draw text strings on the screen. The coordinates refer to the left end of the text’s baseline. public abstract void drawString (String text, int x, int y) The drawString() method draws text on the screen in the current font and color, starting at position (x, y). The starting coordinates specify the left end of the String’s baseline. public void drawChars (char text[], int offset, int length, int x, int y) The drawChars() method creates a String from the char array text starting at text[offset] and continuing for length characters. The newly created String is then drawn on the screen in the current font and color, starting at position (x, y). The starting coordinates specify the left end of the String’s baseline. public void drawBytes (byte text[], int offset, int length, int x, int y) The drawBytes() method creates a String from the byte array text starting at text[offset] and continuing for length characters. This String is then drawn on the screen in the current font and color, starting at position (x, y). The starting coordinates specify the left end of the String’s baseline. public abstract Font getFont () The getFont() method returns the current Font of the graphics context. See Chapter 3, Fonts and Colors, for more on what you can do with fonts. You cannot get meaningful results with getFont() until the applet or application is displayed on the screen (generally, not in init() of an applet or main() of an application). public abstract void setFont (Font font) The setFont() method changes the current Font to font. If font is not available on the current platform, the system chooses a default. To change the current font to 12 point bold TimesRoman: setFont (new Font ("TimesRoman", Font.BOLD, 12));

10 July 2002 22:17

2.1

GRAPHICS

23

public FontMetrics getFontMetrics () The getFontMetrics() method returns the current FontMetrics object of the graphics context. You use FontMetrics to reveal sizing properties of the current Font —for example, how wide the “Hello World” string will be in pixels when displayed on the screen. public abstract FontMetrics getFontMetrics (Font font) This version of getFontMetrics() returns the FontMetrics for the Font font instead of the current font. You might use this method to see how much space a new font requires to draw text. For more information about Font and FontMetrics, see Chapter 3.

Painting public abstract Color getColor () The getColor() method returns the current foreground Color of the Graphics object. All future drawing operations will use this color. Chapter 3 describes the Color class. public abstract void setColor (Color color) The setColor() method changes the current drawing color to color. As you will see in the next chapter, the Color class defines some common colors for you. If you can’t use one of the predefined colors, you can create a color from its RGB values. To change the current color to red, use any of the following: setColor (Color.red); setColor (new Color (255, 0, 0)); setColor (new Color (0xff0000));

public abstract void clearRect (int x, int y, int width, int height) The clearRect() method sets the rectangular drawing area from (x, y) to (x+width-1, y+height-1) to the current background color. Keep in mind that the second pair of parameters is not the opposite corner of the rectangle, but the width and height of the area to clear. public abstract void clipRect (int x, int y, int width, int height) The clipRect() method reduces the drawing area to the intersection of the current drawing area and the rectangular area from (x, y) to (x+width-1, y+height-1). Any future drawing operations outside this clipped area will have no effect. Once you clip a drawing area, you cannot increase its size with clipRect(); the drawing area can only get smaller. (However, if the clipRect() call is in paint(), the size of the drawing area will be reset to its original size on subsequent calls to paint().) If you want the ability to draw to the entire area, you must create a second Graphics object that contains a copy of the drawing area before calling clipRect() or use setClip(). The following code is a simple applet that demonstrates clipping; Figure 2-1 shows the result.

10 July 2002 22:17

24

CHAPTER 2: SIMPLE GRAPHICS import java.awt.*; public class clipping extends java.applet.Applet { public void paint (Graphics g) { g.setColor (Color.red); Graphics clippedGraphics = g.create(); clippedGraphics.drawRect (0,0,100,100); clippedGraphics.clipRect (25, 25, 50, 50); clippedGraphics.drawLine (0,0,100,100); clippedGraphics.dispose(); clippedGraphics=null; g.drawLine (0,100,100,0); } }

clipping area

Figure 2–1: Clipping restricts the drawing area

The paint() method for this applet starts by setting the foreground color to red. It then creates a copy of the Graphics context for clipping, saving the original object so it can draw on the entire screen later. The applet then draws a rectangle, sets the clipping area to a smaller region, and draws a diagonal line across the rectangle from upper left to lower right. Because clipping is in effect, only part of the line is displayed. The applet then discards the clipped Graphics object and draws an unclipped line from lower left to upper right using the original object g. public abstract void setClip(int x, int y, int width, int height) ★ This setClip() method allows you to change the current clipping area based on the parameters provided. setClip() is similar to clipRect(), except that it is not limited to shrinking the clipping area. The current drawing area becomes the rectangular area from (x, y) to (x+width-1, y+height-1); this area may be larger than the previous drawing area.

10 July 2002 22:17

2.1

GRAPHICS

25

public abstract void setClip(Shape clip) ★ This setClip() method allows you to change the current clipping area based on the clip parameter, which may be any object that implements the Shape inter face. Unfortunately, practice is not as good as theory, and in practice, clip must be a Rectangle; if you pass setClip() a Polygon, it throws an IllegalArgumentException.* (The Shape inter face is discussed later in this chapter.) public abstract Rectangle getClipBounds () ★ public abstract Rectangle getClipRect () ✩ The getClipBounds() methods returns a Rectangle that describes the clipping area of a Graphics object. The Rectangle gives you the (x, y) coordinates of the top left corner of the clipping area along with its width and height. (Rectangle objects are discussed later in this chapter.) getClipRect() is the Java 1.0 name for this method.

public abstract Shape getClip () ★ The getClip() method returns a Shape that describes the clipping area of a Graphics object. That is, it returns the same thing as getClipBounds() but as a Shape, instead of as a Rectangle. By calling Shape.getBounds(), you can get the (x, y) coordinates of the top left corner of the clipping area along with its width and height. In the near future, it is hard to imagine the actual object that getClip() returns being anything other than a Rectangle. public abstract void copyArea (int x, int y, int width, int height, int delta_x, int delta_y) The copyArea() method copies the rectangular area from (x, y) to (x+width, y+height) to the area with an upper left corner of (x+delta_x, y+delta_y). The delta_x and delta_y parameters are not the coordinates of the second point but an offset from the first coordinate pair (x, y). The area copied may fall outside of the clipping region. This method is often used to tile an area of the graphics context. copyArea() does not save the contents of the area copied.

Painting mode There are two painting or drawing modes for the Graphics class: paint (the default) and XOR mode. In paint mode, anything you draw replaces whatever is already on the screen. If you draw a red square, you get a red square, no matter what was underneath; this is what most programmers have learned to expect. The behavior of XOR mode is rather strange, at least to people accustomed to modern programming environments. XOR mode is short for eXclusive-OR mode. * It should be simple for Sun to fix this bug; one would expect clipping to a Polygon to be the same as clipping to the Polygon’s bounding rectangle.

10 July 2002 22:17

26

CHAPTER 2: SIMPLE GRAPHICS

The idea behind XOR mode is that drawing the same object twice returns the screen to its original state. This technique was commonly used for simple animations prior to the development of more sophisticated methods and cheaper hardware. The side effect of XOR mode is that painting operations don’t necessarily get the color you request. Instead of replacing the original pixel with the new value, XOR mode merges the original color, the painting color, and an XOR color (usually the background color) to form a new color. The new color is chosen so that if you repaint the pixel with the same color, you get the original pixel back. For example, if you paint a red square in XOR mode, you get a square of some other color on the screen. Painting the same red square again returns the screen to its original state. public abstract void setXORMode (Color xorColor) The setXORMode() method changes the drawing mode to XOR mode. In XOR mode, the system uses the xorColor color to determine an alternate color for anything drawn such that drawing the same item twice restores the screen to its original condition. The xorColor is usually the current background color but can be any color. For each pixel, the new color is determined by an exclusive-or of the old pixel color, the painting color, and the xorColor. For example, if the old pixel is red, the XOR color is blue, and the drawing color is green, the end result would be white. To see why, it is necessary to look at the RGB values of the three colors. Red is (255, 0, 0). Blue is (0, 0, 255). Green is (0, 255, 0). The exclusive-or of these three values is (255, 255, 255), which is white. Drawing another green pixel with a blue XOR color yields red, the pixel’s original color, since (255, 255, 255) ˆ (0, 0, 255) ˆ (0, 255, 0) yields (255, 0, 0).* The following code generates the display shown in Figure 2-2. import java.awt.*; public class xor extends java.applet.Applet { public void init () { setBackground (Color.red); } public void paint (Graphics g) { g.setColor (Color.green); g.setXORMode (Color.blue); g.fillRect (10, 10, 100, 100); g.fillRect (10, 60, 100, 100); } }

Although it’s hard to visualize what color XOR mode will pick, there is one important special case. Let’s say that there are only two colors: a background color (the * ˆ is the Java XOR operator.

10 July 2002 22:17

2.1

GRAPHICS

27

first fillRect()

second fillRect()

Figure 2–2: Drawing in XOR mode

XOR color) and a foreground color (the painting color). Each pixel must be in one color or the other. Painting “flips” each pixel to the other color. Foreground pixels become background, and vice versa. public abstract void setPaintMode () The setPaintMode() method puts the system into paint mode. When in paint mode, any drawing operation replaces whatever is underneath it. Call setPaintMode() to return to normal painting when finished with XOR mode.

Drawing shapes Most of the drawing methods require you to specify a bounding rectangle for the object you want to draw: the location of the object’s upper left corner, plus its width and height. The two exceptions are lines and polygons. For lines, you supply two endpoints; for polygons, you provide a set of points. Versions 1.0.2 and 1.1 of AWT always draw solid lines that are one pixel wide; there is no support for line width or fill patterns. A future version should support lines with variable widths and patterns. public abstract void drawLine (int x1, int y1, int x2, int y2) The drawLine() method draws a line on the graphics context in the current color from (x1, y1) to (x2, y2). If (x1, y1) and (x2, y2) are the same point, you will draw a point. There is no method specific to drawing a point. The following code generates the display shown in Figure 2-3.

10 July 2002 22:17

28

CHAPTER 2: SIMPLE GRAPHICS g.drawLine (5, 5, 50, 75); g.drawLine (5, 75, 5, 75); g.drawLine (50, 5, 50, 5);

// line // point // point

points

Figure 2–3: Drawing lines and points with drawLine()

public void drawRect (int x, int y, int width, int height) The drawRect() method draws a rectangle on the drawing area in the current color from (x, y) to (x+width, y+height). If width or height is negative, nothing is drawn. public abstract void fillRect (int x, int y, int width, int height) The fillRect() method draws a filled rectangle on the drawing area in the current color from (x, y) to (x+width-1, y+height-1). Notice that the filled rectangle is one pixel smaller to the right and bottom than requested. If width or height is negative, nothing is drawn. public abstract void drawRoundRect (int x, int y, int width, int height, int arcWidth, int arcHeight) The drawRoundRect() method draws a rectangle on the drawing area in the current color from (x, y) to (x+width, y+height). However, instead of perpendicular corners, the corners are rounded with a horizontal diameter of arcWidth and a vertical diameter of arcHeight. If width or height is a negative number, nothing is drawn. If width, height, arcWidth, and arcHeight are all equal, you get a circle. To help you visualize the arcWidth and arcHeight of a rounded rectangle, Figure 2-4 shows one corner of a rectangle drawn with an arcWidth of 20 and a arcHeight of 40. public abstract void fillRoundRect (int x, int y, int width, int height, int arcWidth, int arcHeight) The fillRoundRect() method draws a filled rectangle on the drawing area in the current color from (x, y) to (x+width-1, y+height-1). However, instead of having perpendicular corners, the corners are rounded with a horizontal

10 July 2002 22:17

2.1

GRAPHICS

29

10 pixels wide

20 pixels high

Figure 2–4: Drawing rounded corners

diameter of arcWidth and a vertical diameter of arcHeight for the four corners. Notice that the filled rectangle is one pixel smaller to the right and bottom than requested. If width or height is a negative number, nothing is filled. If width, height, arcWidth, and arcHeight are all equal, you get a filled circle. Figure 2-4 shows how AWT generates rounded corners. Figure 2-5 shows the collection of rectangles created by the following code. The rectangles in Figure 2-5 are filled and unfilled, with rounded and square corners. g.drawRect (25, g.fillRect (25, g.drawRoundRect g.fillRoundRect

10, 50, 75); 110, 50, 75); (100, 10, 50, 75, 60, 50); (100, 110, 50, 75, 60, 50);

public void draw3DRect (int x, int y, int width, int height, boolean raised) The draw3DRect() method draws a rectangle in the current color from (x, y) to (x+width, y+height); a shadow effect makes the rectangle appear to float slightly above or below the screen. The raised parameter has an effect only if the current color is not black. If raised is true, the rectangle looks like a button waiting to be pushed. If raised is false, the rectangle looks like a depressed button. If width or height is negative, the shadow appears from another direction. public void fill3DRect (int x, int y, int width, int height, boolean raised) The fill3DRect() method draws a filled rectangle in the current color from (x, y) to (x+width, y+height); a shadow effect makes the rectangle appear to float slightly above or below the screen. The raised parameter has an effect

10 July 2002 22:17

30

CHAPTER 2: SIMPLE GRAPHICS

Figure 2–5: Varieties of rectangles

only if the current color is not black. If raised is true, the rectangle looks like a button waiting to be pushed. If raised is false, the rectangle looks like a depressed button. To enhance the shadow effect, the depressed area is given a slightly deeper shade of the drawing color. If width or height is negative, the shadow appears from another direction, and the rectangle isn’t filled. (Different platforms could deal with this differently. Try to ensure the parameters have positive values.) Figure 2-6 shows the collection of three-dimensional rectangles created by the following code. The rectangles in the figure are raised and depressed, filled and unfilled. g.setColor (Color.gray); g.draw3DRect (25, 10, 50, 75, true); g.draw3DRect (25, 110, 50, 75, false); g.fill3DRect (100, 10, 50, 75, true); g.fill3DRect (100, 110, 50, 75, false);

public abstract void drawOval (int x, int y, int width, int height) The drawOval() method draws an oval in the current color within an invisible bounding rectangle from (x, y) to (x+width, y+height). You cannot specify the oval’s center point and radii. If width and height are equal, you get a circle. If width or height is negative, nothing is drawn. public abstract void fillOval (int x, int y, int width, int height) The fillOval() method draws a filled oval in the current color within an invisible bounding rectangle from (x, y) to (x+width-1, y+height-1). You cannot specify the oval’s center point and radii. Notice that the filled oval is one pixel smaller to the right and bottom than requested. If width or height is negative, nothing is drawn.

10 July 2002 22:17

2.1

GRAPHICS

31

Figure 2–6: Filled and unfilled 3D rectangles

Figure 2-7 shows the collection of ovals, filled and unfilled, that were generated by the following code: g.drawOval g.fillOval g.drawOval g.fillOval

(25, 10, 50, 75); (25, 110, 50, 75); (100, 10, 50, 50); (100, 110, 50, 50);

Figure 2–7: Filled and unfilled ovals

public abstract void drawArc (int x, int y, int width, int height, int startAngle, int arcAngle) The drawArc() method draws an arc in the current color within an invisible bounding rectangle from (x, y) to (x+width, y+height). The arc starts at startAngle degrees and goes to startAngle + arcAngle degrees. An angle of 0 degrees is at the 3 o’clock position; angles increase counter-clockwise. If

10 July 2002 22:17

32

CHAPTER 2: SIMPLE GRAPHICS

arcAngle is negative, drawing is in a clockwise direction. If width and height are equal and arcAngle is 360 degrees, drawArc() draws a circle. If width or height is negative, nothing is drawn.

public abstract void fillArc (int x, int y, int width, int height, int startAngle, int arcAngle) The fillArc() method draws a filled arc in the current color within an invisible bounding rectangle from (x, y) to (x+width-1, y+height-1). The arc starts at startAngle degrees and goes to startAngle + arcAngle degrees. An angle of 0 degrees is at the 3 o’clock position; angles increase counter-clockwise. If arcAngle is negative, drawing is in a clockwise direction. The arc fills like a pie (to the origin), not from arc endpoint to arc endpoint. This makes creating pie charts easier. If width and height are equal and arcAngle is 360 degrees, fillArc() draws a filled circle. If width or height is negative, nothing is drawn. Figure 2-8 shows a collection of filled and unfilled arcs that were generated by the following code: g.drawArc g.fillArc g.drawArc g.fillArc

(25, 10, 50, 75, 0, 360); (25, 110, 50, 75, 0, 360); (100, 10, 50, 75, 45, 215); (100, 110, 50, 75, 45, 215);

Figure 2–8: Filled and unfilled arcs

public void drawPolygon (Polygon p) The drawPolygon() method draws a path for the points in polygon p in the current color. Section 2.6 discusses the Polygon class in detail. The behavior of drawPolygon() changes slightly between Java 1.0.2 and 1.1. With version 1.0.2, if the first and last points of a Polygon are not the same, a call to drawPolygon() results in an open polygon, since the endpoints are not connected for you. Starting with version 1.1, if the first and last points are not the same, the endpoints are connected for you.

10 July 2002 22:17

2.1

GRAPHICS

33

public abstract void drawPolygon (int xPoints[], int yPoints[], int numPoints) The drawPolygon() method draws a path of numPoints nodes by plucking one element at a time out of xPoints and yPoints to make each point. The path is drawn in the current color. If either xPoints or yPoints does not have numPoints elements, drawPolygon() throws a run-time exception. In 1.0.2, this exception is an IllegalArgumentException; in 1.1, it is an ArrayIndexOutOfBoundsException. This change shouldn’t break older programs, since you are not required to catch run-time exceptions. public abstract void drawPolyline (int xPoints[], int yPoints[], int numPoints) ★ The drawPolyline() method functions like the 1.0 version of drawPolygon(). It plays connect the dots with the points in the xPoints and yPoints arrays and does not connect the endpoints. If either xPoints or yPoints does not have numPoints elements, drawPolygon() throws the run-time exception, ArrayIndexOutOfBoundsException. Filling polygons is a complex topic. It is not as easy as filling rectangles or ovals because a polygon may not be closed and its edges may cross. AWT uses an evenodd rule to fill polygons. This algorithm works by counting the number of times each scan line crosses an edge of the polygon. If the total number of crossings to the left of the current point is odd, the point is colored. If it is even, the point is left alone. Figure 2-9 demonstrates this algorithm for a single scan line that intersects the polygon at x values of 25, 75, 125, 175, 225, and 275.

x=25

x=75

x=125

x=175

x=225

x=275

Figure 2–9: Polygon fill algorithm

The scan line starts at the left edge of the screen; at this point there haven’t been

10 July 2002 22:17

34

CHAPTER 2: SIMPLE GRAPHICS

any crossings, so the pixels are left untouched. The scan line reaches the first crossing when x equals 25. Here, the total number of crossings to the left is one, so the scan line is inside the polygon, and the pixels are colored. At 75, the scan line crosses again; the total number of crossings is two, so coloring stops. public void fillPolygon (Polygon p) The fillPolygon() method draws a filled polygon for the points in Polygon p in the current color. If the polygon is not closed, fillPolygon() adds a segment connecting the endpoints. Section 2.6 discusses the Polygon class in detail. public abstract void fillPolygon (int xPoints[], int yPoints[], int nPoints) The fillPolygon() method draws a polygon of numPoints nodes by plucking one element at a time out of xPoints and yPoints to make each point. The polygon is drawn in the current color. If either xPoints or yPoints does not have numPoints elements, fillPolygon() throws the run-time exception IllegalArgumentException. If the polygon is not closed, fillPolygon() adds a segment connecting the endpoints.* Figure 2-10 shows several polygons created by the following code, containing different versions of drawPolygon() and fillPolygon(): int[] xPoints[] = {{50, 25, 25, 75, 75}, {50, 25, 25, 75, 75}, {100, 100, 150, 100, 150, 150, 125, 100, 150}, {100, 100, 150, 100, 150, 150, 125, 100, 150}}; int[] yPoints[] = {{10, 35, 85, 85, 35, 10}, {110, 135, 185, 185, 135}, {85, 35, 35, 85, 85, 35, 10, 35, 85}, {185, 135, 135, 185, 185, 135, 110, 135, 185}}; int nPoints[] = {5, 5, 9, 9}; g.drawPolygon (xPoints[0], yPoints[0], nPoints[0]); g.fillPolygon (xPoints[1], yPoints[1], nPoints[1]); g.drawPolygon (new Polygon(xPoints[2], yPoints[2], nPoints[2])); g.fillPolygon (new Polygon(xPoints[3], yPoints[3], nPoints[3]));

Drawing images An Image is a displayable object maintained in memory. To get an image on the screen, you must draw it onto a graphics context, using the drawImage() method of the Graphics class. For example, within a paint() method, you would call g.drawImage(image, . . . , this) to display some image on the screen. In other situations, you might use the createImage() method to generate an offscreen Graphics object, then use drawImage() to draw an image onto this object, for display later. * In Java 1.1, this method throws ArrayIndexOutOfBoundsException, not IllegalArgumentException.

10 July 2002 22:17

2.1

GRAPHICS

Java 1.0

35

Java 1.1

Figure 2–10: Filled and unfilled polygons

This begs the question: where do images come from? We will have more to say about the Image class later in this chapter. For now, it’s enough to say that you can call getImage() to load an image from disk or across the Net. There are versions of getImage() in the Applet and Toolkit classes; the latter is for use in applications. You can also call createImage(), a method of the Component class, to generate an image in memory. What about the last argument to drawImage()? What is this for? The last argument of drawImage() is always an image observer — that is, an object that implements the ImageObserver inter face. This interface is discussed in detail in Chapter 12. For the time being, it’s enough to say that the call to drawImage() starts a new thread that loads the requested image. An image observer monitors the process of loading an image; the thread that is loading the image notifies the image observer whenever new data has arrived. The Component class implements the ImageObserver inter face; when you’re writing a paint() method, you’re almost certainly overriding some component’s paint() method; therefore, it’s safe to use this as the image observer in a call to drawImage(). More simply, we could say that any component can serve as an image observer for images that are drawn on it. public abstract boolean drawImage (Image image, int x, int y, ImageObserver observer) The drawImage() method draws image onto the screen with its upper left corner at (x, y), using observer as its ImageObserver. Returns true if the object is fully drawn, false otherwise. public abstract boolean drawImage (Image image, int x, int y, int width, int height, ImageObserver observer) The drawImage() method draws image onto the screen with its upper left corner at (x, y), using observer as its ImageObserver. The system scales image to fit into a width height area. The scaling may take time. This method returns true if the object is fully drawn, false otherwise.

10 July 2002 22:17

36

CHAPTER 2: SIMPLE GRAPHICS

With Java 1.1, you don’t need to use drawImage() for scaling; you can prescale the image with the Image.getScaledInstance() method, then use the previous version of drawImage(). public abstract boolean drawImage (Image image, int x, int y, Color backgroundColor, ImageObserver observer) The drawImage() method draws image onto the screen with its upper left corner at (x, y), using observer as its ImageObserver. backgroundColor is the color of the background seen through the transparent parts of the image. If no part of the image is transparent, you will not see backgroundColor. Returns true if the object is fully drawn, false otherwise. public abstract boolean drawImage (Image image, int x, int y, int width, int height, Color backgroundColor, ImageObserver observer) The drawImage() method draws image onto the screen with its upper left corner at (x, y), using observer as its ImageObserver. backgroundColor is the color of the background seen through the transparent parts of the image. The system scales image to fit into a width x height area. The scaling may take time. This method returns true if the image is fully drawn, false otherwise. With Java 1.1, you can prescale the image with the AreaAveragingScaleFilter or ReplicateScaleFilter described in Chapter 12, then use the previous version of drawImage() to display it. The following code generated the images in Figure 2-11. The images on the left come from a standard JPEG file. The images on the right come from a file in GIF89a format, in which the white pixel is “transparent.” Therefore, the gray background shows through this pair of images. import java.awt.*; import java.applet.*; public class drawingImages extends Applet { Image i, j; public void init () { i = getImage (getDocumentBase(), "rosey.jpg"); j = getImage (getDocumentBase(), "rosey.gif"); } public void paint (Graphics g) { g.drawImage (i, 10, 10, this); g.drawImage (i, 10, 85, 150, 200, this); g.drawImage (j, 270, 10, Color.lightGray, this); g.drawImage (j, 270, 85, 150, 200, Color.lightGray, this); } }

public abstract boolean drawImage(Image img, int dx1, int dy1, int dx2, int dy2, int sx1, int sy1, int sx2, int sy2, ImageObserver observer) ★ The drawImage() method draws a portion of image onto the screen. It takes the part of the image with corners at (sx1, sy1) and (sx2, sy2); it places this

10 July 2002 22:17

2.1

GRAPHICS

37

Figure 2–11: Scaled and unscaled images

rectangular snippet on the screen with one corner at (dx1, dy1) and another at (dx2, dy2), using observer as its ImageObserver. (Think of d for destination location and s for source image.) This method returns true if the object is fully drawn, false otherwise. drawImage() flips the image if source and destination endpoints are not the

same corners, crops the image if the destination is smaller than the original size, and scales the image if the destination is larger than the original size. It does not do rotations, only flips (i.e., it can produce a mirror image or an image rotated 180 degrees but not an image rotated 90 or 270 degrees). public abstract boolean drawImage(Image img, int dx1, int dy1, int dx2, int dy2, int sx1, int sy1, int sx2, int sy2, Color backgroundColor, ImageObserver observer) ★ The drawImage() method draws a portion of image onto the screen. It takes the part of the image with corners at (sx1, sy1) and (sx2, sy2); it places this rectangular snippet on the screen with one corner at (dx1, dy1) and another at (dx2, dy2), using observer as its ImageObserver. (Think of d for destination location and s for source image.) backgroundColor is the color of the background seen through the transparent parts of the image. If no part of the image is transparent, you will not see backgroundColor. This method returns true if the object is fully drawn, false otherwise. Like the previous version of drawImage(), this method flips the image if source and destination endpoints are not the same corners, crops the image if the

10 July 2002 22:17

38

CHAPTER 2: SIMPLE GRAPHICS

destination is smaller than the original size, and scales the image if the destination is larger than the original size. It does not do rotations, only flips (i.e., it can produce a mirror image or an image rotated 180 degrees but not an image rotated 90 or 270 degrees). The following code demonstrates the new drawImage() methods in Java 1.1. They allow you to scale, flip, and crop images without the use of image filters. The results are shown in Figure 2-12. // Java 1.1 only import java.awt.*; import java.applet.*; public class drawingImages11 extends Applet { Image i, j; public void init () { i = getImage (getDocumentBase(), "rosey.gif"); } public void paint (Graphics g) { g.drawImage (i, 10, 10, this); g.drawImage (i, 10, 85, i.getWidth(this)+10, i.getHeight(this)+85, i.getWidth(this), i.getHeight(this), 0, 0, this); g.drawImage (i, 270, 10, i.getWidth(this)+270, i.getHeight(this)*2+10, 0, 0, i.getWidth(this), i.getHeight(this), Color.gray, this); g.drawImage (i, 10, 170, i.getWidth(this)*2+10, i.getHeight(this)+170, 0, i.getHeight(this)/2, i.getWidth(this)/2, 0, this); } }

Miscellaneous methods public abstract void translate (int x, int y) The translate() method sets how the system translates the coordinate space for you. The point at the (x, y) coordinates becomes the origin of this graphics context. Any future drawing will be relative to this location. Multiple translations are cumulative. The following code leaves the coordinate system translated by (100, 50). translate (100, 0); translate (0, 50);

Note that each call to paint() provides an entirely new Graphics context with its origin in the upper left corner. Therefore, don’t expect translations to persist from one call to paint() to the next.

10 July 2002 22:17

2.1

GRAPHICS

39

Figure 2–12: Flipped, mirrored, and cropped images

public abstract void dispose () The dispose() method frees any system resources used by the Graphics context. It’s a good idea to call dispose() whenever you are finished with a Graphics object, rather than waiting for the garbage collector to call it automatically (through finalize()). Disposing of the Graphics object yourself will help your programs on systems with limited resources. However, you should not dispose the Graphics parameter to Component.paint() or Component.update(). public void finalize () The garbage collector calls finalize() when it determines that the Graphics object is no longer needed. finalize() calls dispose(), which frees any resources that the Graphics object has used. public String toString () The toString() method of Graphics returns a string showing the current font and color. However, Graphics is an abstract class, and classes that extend Graphics usually override toString(). For example, on a Windows 95 machine, sun.awt.win32.Win32Graphics is the concrete class that extends Graphics. The class’s toString() method displays the current origin of the Graphics object, relative to the original coordinate system: sun.awt.win32.Win32Graphics[0,0]

10 July 2002 22:17

40

CHAPTER 2: SIMPLE GRAPHICS

2.2 Point The Point class encapsulates x and y coordinates within a single object. It is probably one of the most underused classes within Java. Although there are numerous places within AWT where you would expect to see a Point, its appearances are surprisingly rare. Java 1.1 is starting to use Point more heavily. The Point class is most often used when a method needs to return a pair of coordinates; it lets the method return both x and y as a single object. Unfortunately, Point usually is not used when a method requires x and y coordinates as arguments; for example, you would expect the Graphics class to have a version of translate() that takes a point as an argument, but there isn’t one. The Point class does not represent a point on the screen. It is not a visual object; there is no drawPoint() method.

2.2.1 Point Methods Variables The two public variables of Point represent a pair of coordinates. They are accessible directly or use the getLocation() method. There is no predefined origin for the coordinate space. public int x The coordinate that represents the horizontal position. public int y The coordinate that represents the vertical position.

Constructors public Point () The first constructor creates an instance of Point with an initial x value of 0 and an initial y value of 0. public Point (int x, int y) The next constructor creates an instance of Point with an initial x value of x and an initial y value of y. public Point (Point p) The last constructor creates an instance of Point from another point, the x value of p.x and an initial y value of p.y.

10 July 2002 22:17

2.3

DIMENSION

41

Locations public Point getLocation () ★ The getLocation() method retrieves the current location of this point as a new Point. public void setLocation (int x, int y) ★ public void move (int x, int y) ✩ The setLocation() method changes the point’s location to (x, y). move() is the Java 1.0 name for this method.

public void setLocation (Point p) ★ This setLocation() method changes the point’s location to (p.x, p.y). public void translate (int x, int y) The translate() method moves the point’s location by adding the parameters (x, y) to the corresponding fields of the Point. If the original Point p is (3, 4) and you call p.translate(4, -5), the new value of p is (7, -1).

Miscellaneous methods public int hashCode () The hashCode() method returns a hash code for the point. The system calls this method when a Point is used as the key for a hash table. public boolean equals (Object object) The equals() method overrides the Object.equals() method to define equality for points. Two Point objects are equal if their x and y values are equal. public String toString () The toString() method of Point displays the current values of the x and y variables. For example: java.awt.Point[x=100,y=200]

2.3 Dimension The Dimension class is similar to the Point class, except it encapsulates a width and height in a single object. Like Point, Dimension is somewhat underused; it is used primarily by methods that need to return a width and a height as a single object; for example, getSize() returns a Dimension object.

10 July 2002 22:17

42

CHAPTER 2: SIMPLE GRAPHICS

2.3.1 Dimension Methods Variables A Dimension instance has two variables, one for width and one for height. They are accessible directly or through use of the getSize() method. public int width The width variable represents the size of an object along the x axis (left to right). Width should not be negative; however, there is nothing within the class to prevent this from happening. public int height The height variable represents the size of an object along the y axis (top to bottom). Height should not be negative; however, there is nothing within the class to prevent this from happening.

Constructors public Dimension () This constructor creates a Dimension instance with a width and height of 0. public Dimension (Dimension dim) This constructor creates a copy of dim. The initial width is dim.width. The initial height is dim.height. public Dimension (int width, int height) This constructor creates a Dimension with an initial width of width and an initial height of height.

Sizing public Dimension getSize () ★ The getSize() method retrieves the current size as a new Dimension, even though the instance variables are public. public void setSize (int width, int height) ★ The setSize() method changes the dimension’s size to width height. public void setSize (Dimension d) ★ The setSize() method changes the dimension’s size to d.width d.height.

Miscellaneous methods public boolean equals (Object object) The equals() method overrides the Object.equals() method to define equality for dimensions. Two Dimension objects are equal if their width and height values are equal.

10 July 2002 22:17

2.5

RECTANGLE

43

public String toString () The toString() method of Dimension returns a string showing the current width and height settings. For example: java.awt.Dimension[width=0,height=0]

2.4 Shape The new Shape inter face defines a single method; it requires a geometric object to be able to report its bounding box. Currently, the Rectangle and Polygon classes implement Shape; one would expect other geometric classes to implement Shape in the future. Although Component has the single method defined by the Shape inter face, it does not implement the interface.

2.4.1 Shape Method public abstract Rectangle getBounds() ★ The getBounds() method returns the shape’s bounding Rectangle. Once you have the bounding area, you can use methods like Graphics.copyArea() to copy the shape.

2.5 Rectangle The Rectangle class encapsulates x and y coordinates and width and height (Point and Dimension information) within a single object. It is often used by methods that return a rectangular boundary as a single object: for example, Polygon.getBounds(), Component.getBounds(), and Graphics.getClipBounds(). Like Point, the Rectangle class is not a visual object and does not represent a rectangle on the screen; ironically, drawRect() and fillRect() don’t take Rectangle as an argument.

2.5.1 Rectangle Methods Variables The four public variables available for Rectangle have the same names as the public instance variables of Point and Dimension. They are all accessible directly or through use of the getBounds() method. public int x The x coordinate of the upper left corner.

10 July 2002 22:17

44

CHAPTER 2: SIMPLE GRAPHICS

public int y The y coordinate of the upper left corner. public int width The width variable represents the size of the Rectangle along the horizontal axis (left to right). Width should not be negative; however, there is nothing within the class to prevent this from happening. public int height The height variable represents the size of the Rectangle along the vertical axis (top to bottom). Height should not be negative; however, there is nothing within the class to prevent this from happening.

Constructors The following seven constructors create Rectangle objects. When you create a Rectangle, you provide the location of the top left corner, along with the Rectangle’s width and height. A Rectangle located at (0,0) with a width and height of 100 has its bottom right corner at (99, 99). The Point (100, 100) lies outside the Rectangle, since that would require a width and height of 101. public Rectangle () This Rectangle constructor creates a Rectangle object in which x, y, width, and height are all 0. public Rectangle (int width, int height) This Rectangle constructor creates a Rectangle with (x, y) coordinates of (0,0) and the specified width and height. Notice that there is no Rectangle(int x, int y) constructor because that would have the same method signature as this one, and the compiler would have no means to differentiate them. public Rectangle (int x, int y, int width, int height) The Rectangle constructor creates a Rectangle object with an initial x coordinate of x, y coordinate of y, width of width, and height of height. Height and width should be positive, but the constructor does not check for this. public Rectangle (Rectangle r) This Rectangle constructor creates a Rectangle matching the original. The (x, y) coordinates are (r.x, r.y), with a width of r.width and a height of r.height.

10 July 2002 22:17

2.5

RECTANGLE

45

public Rectangle (Point p, Dimension d) This Rectangle constructor creates a Rectangle with (x, y) coordinates of (p.x, p.y), a width of d.width, and a height of d.height. public Rectangle (Point p) This Rectangle constructor creates a Rectangle with (x, y) coordinates of (p.x, p.y). The width and height are both zero. public Rectangle (Dimension d) The last Rectangle constructor creates a Rectangle with (x, y) coordinates of (0, 0). The initial Rectangle width is d.width and height is d.height.

Shaping and sizing public Rectangle getBounds() ★ The getBounds() method returns a copy of the original Rectangle. public void setBounds (int x, int y, int width, int height) ★ public void reshape (int x, int y, int width, int height) ✩ The setBounds() method changes the origin of the Rectangle to (x, y) and changes the dimensions to width by height. reshape() is the Java 1.0 name for this method.

public void setBounds (Rectangle r) ★ The setBounds() method changes the origin of the Rectangle to (r.x, r.y) and changes the dimensions to r.width by r.height. public Point getLocation() ★ The getLocation()retrieves the current origin of this rectangle as a Point. public void setLocation (int x, int y) ★ public void move (int x, int y) ✩ The setLocation() method changes the origin of the Rectangle to (x, y). move() is the Java 1.0 name for this method.

public void setLocation (Point p) ★ The setLocation() method changes the Rectangle’s origin to (p.x, p.y). public void translate (int x, int y) The translate() method moves the Rectangle’s origin by the amount (x, y). If the original Rectangle’s location (r) is (3, 4) and you call r.translate (4, 5), then r’s location becomes (7, 9). x and y may be negative. translate() has no effect on the Rectangle’s width and height.

10 July 2002 22:17

46

CHAPTER 2: SIMPLE GRAPHICS

public Dimension getSize () ★ The getSize() method retrieves the current size of the rectangle as a Dimension. public void setSize() (int width, int height) ★ public void resize (int width, int height) ✩ The setSize() method changes the Rectangle’s dimensions to width x height. resize() is the Java 1.0 name for this method.

public void setSize() (Dimension d) ★ The setSize() method changes the Rectangle’s dimensions to d.width x d.height. public void grow (int horizontal, int vertical) The grow() method increases the Rectangle’s dimensions by adding the amount horizontal on the left and the right and adding the amount vertical on the top and bottom. Therefore, all four of the rectangle’s variables change. If the original location is (x, y), the new location will be (x-horizontal, y-vertical) (moving left and up if both values are positive); if the original size is (width, height), the new size will be (width+2*horizontal, height+2*vertical). Either horizontal or vertical can be negative to decrease the size of the Rectangle. The following code demonstrates the changes: import java.awt.Rectangle; public class rect { public static void main (String[] args) { Rectangle r = new Rectangle (100, 100, 200, 200); System.out.println (r); r.grow (50, 75); System.out.println (r); r.grow (-25, -50); System.out.println (r); } }

This program produces the following output: java.awt.Rectangle[x=100,y=100,width=200,height=200] java.awt.Rectangle[x=50,y=25,width=300,height=350] java.awt.Rectangle[x=75,y=75,width=250,height=250]

public void add (int newX, int newY) The add() method incorporates the point (newX, newY) into the Rectangle. If this point is already in the Rectangle, there is no change. Otherwise, the size of the Rectangle increases to include (newX, newY) within itself.

10 July 2002 22:17

2.5

RECTANGLE

47

public void add (Point p) This add() method incorporates the point (p.x, p.y) into the Rectangle. If this point is already in the Rectangle, there is no change. Otherwise, the size of the Rectangle increases to include (p.x, p.y) within itself. public void add (Rectangle r) This add() method incorporates another Rectangle r into this Rectangle. This transforms the current rectangle into the union of the two Rectangles. This method might be useful in a drawing program that lets you select multiple objects on the screen and create a rectangular area from them. We will soon encounter a method called union() that is almost identical. add() and union() differ in that add() modifies the current Rectangle, while union() returns a new Rectangle. The resulting rectangles are identical.

Intersections public boolean contains (int x, int y) ★ public boolean inside (int x, int y) ✩ The contains() method determines if the point (x, y) is within this Rectangle. If so, true is returned. If not, false is returned. inside() is the Java 1.0 name for this method.

public boolean contains (Point p) ★ The contains() method determines if the point (p.x, p.y) is within this Rectangle. If so, true is returned. If not, false is returned. public boolean intersects (Rectangle r) The intersects() method checks whether Rectangle r crosses this Rectangle at any point. If it does, true is returned. If not, false is returned. public Rectangle intersection (Rectangle r) The intersection() method returns a new Rectangle consisting of all points that are in both the current Rectangle and Rectangle r. For example, if r = new Rectangle (50, 50, 100, 100) and r1 = new Rectangle (100, 100, 75, 75), then r.intersection (r1) is the Rectangle (100, 100, 50, 50), as shown in Figure 2-13. public Rectangle union (Rectangle r) The union() method combines the current Rectangle and Rectangle r to form a new Rectangle. For example, if r = new Rectangle (50, 50, 100, 100) and r1 = new Rectangle (100, 100, 75, 75), then r.union (r1) is the Rectangle (50, 50, 125, 125). The original rectangle is unchanged. Figure 2-14 demonstrates the effect of union(). Because fillRect() fills to width-1

10 July 2002 22:17

48

CHAPTER 2: SIMPLE GRAPHICS

and height-1, the rectangle drawn appears slightly smaller than you would expect. However, that’s an artifact of how rectangles are drawn; the returned rectangle contains all the points within both.

Figure 2–13: Rectangle intersection

Figure 2–14: Rectangle union

Miscellaneous methods public boolean isEmpty () The isEmpty() method checks whether there are any points within the Rectangle. If the width and height of the Rectangle are both 0 (or less), the Rectangle is empty, and this method returns true. If either width or height is greater than zero, isEmpty() returns false. This method could be used to check the results of a call to any method that returns a Rectangle object.

10 July 2002 22:17

2.6

POLYGON

49

public int hashCode () The hashCode() method returns a hash code for the rectangle. The system calls this method when a Rectangle is used as the key for a hash table. public boolean equals (Object object) The equals() method overrides the Object’s equals() method to define what equality means for Rectangle objects. Two Rectangle objects are equal if their x, y, width, and height values are equal. public String toString () The toString() method of Rectangle displays the current values of the x, y, width, and height variables. For example: java.awt.Rectangle[x=100,y=200,width=300,height=400]

2.6 Polygon A Polygon is a collection of points used to create a series of line segments. Its primary purpose is to draw arbitrary shapes like triangles or pentagons. If the points are sufficiently close, you can create a curve. To display the Polygon, call drawPolygon() or fillPolygon().

2.6.1 Polygon Methods Variables The collection of points maintained by Polygon are stored in three variables: public int npoints The npoints variable stores the number of points. public int xpoints[] The xpoints array holds the x component of each point. public int ypoints[] The ypoints array holds the y component of each point. You might expect the Polygon class to use an array of points, rather than separate arrays of integers. More important, you might expect the instance variables to be private or protected, which would prevent them from being modified directly. Since the three instance variables are public, there is no guarantee that the array sizes are in sync with each other or with npoints. To avoid trouble, always use addPoints() to modify your polygons, and avoid modifying the instance variables directly.

10 July 2002 22:17

50

CHAPTER 2: SIMPLE GRAPHICS

Constructors public Polygon () This constructor creates an empty Polygon. public Polygon (int xPoints[], int yPoints[], int numPoints) This constructor creates a Polygon that consists of numPoints points. Those points are formed from the first numPoints elements of the xPoints and yPoints arrays. If the xPoints or yPoints arrays are larger than numPoints, the additional entries are ignored. If the xPoints or yPoints arrays do not contain at least numPoints elements, the constructor throws the run-time exception ArrayIndexOutOfBoundsException.

Miscellaneous methods public void addPoint (int x, int y) The addPoint() method adds the point (x, y) to the Polygon as its last point. If you alter the xpoints, ypoints, and npoints instance variables directly, addPoint() could add the new point at a place other than the end, or it could throw the run-time exception ArrayIndexOutOfBoundsException with a message showing the position at which it tried to add the point. Again, for safety, don’t modify a Polygon’s instance variables yourself; always use addPoint(). public Rectangle getBounds () ★ public Rectangle getBoundingBox () ✩ The getBounds() method returns the Polygon’s bounding Rectangle (i.e., the smallest rectangle that contains all the points within the polygon). Once you have the bounding box, it’s easy to use methods like copyArea() to copy the Polygon. getBoundingBox() is the Java 1.0 name for this method.

public boolean contains (int x, int y) ★ public boolean inside (int x, int y) ✩ The contains() method checks to see if the (x, y) point is within an area that would be filled if the Polygon was drawn with Graphics.fillPolygon(). A point may be within the bounding rectangle of the polygon, but contains() can still return false if not within a closed part of the polygon. inside() is the Java 1.0 name for this method.

public boolean contains (Point p) ★ The contains() method checks to see if the point p is within an area that would be filled if the Polygon were drawn with Graphics.fillPolygon().

10 July 2002 22:17

2.7

IMAGE

51

public void translate (int x, int y) ★ The translate() method moves all the Polygon’s points by the amount (x, y). This allows you to alter the location of the Polygon by shifting the points.

2.7 Image An Image is a displayable object maintained in memory. AWT has built-in support for reading files in GIF and JPEG format, including GIF89a animation. Netscape Navigator, Internet Explorer, HotJava, and Sun’s JDK also understand the XBM image format. Images are loaded from the filesystem or network by the getImage() method of either Component or Toolkit, drawn onto the screen with drawImage() from Graphics, and manipulated by several objects within the java.awt.image package. Figure 2-15 shows an Image.

Figure 2–15: An Image

Image is an abstract class implemented by many different platform-specific classes.

The system that runs your program will provide an appropriate implementation; you do not need to know anything about the platform-specific classes, because the Image class completely defines the API for working with images. If you’re curious, the platform-specific packages used by the JDK are: •

sun.awt.win32.Win32Image on Java 1.0 Windows NT/95 platforms

•

sun.awt.windows.WImage on Java 1.1 Windows NT/95 platforms

•

sun.awt.motif.X11Image on UNIX/Motif platforms

•

sun.awt.macos.MacImage on the Macintosh

This section covers only the Image object itself. AWT also includes a package named java.awt.image that includes more advanced image processing utilities. The classes in java.awt.image are covered in Chapter 12.

10 July 2002 22:17

52

CHAPTER 2: SIMPLE GRAPHICS

2.7.1 Image Methods Constants public static final Object UndefinedProperty In Java 1.0, the sole constant of Image is UndefinedProperty. It is used as a return value from the getProperty() method to indicate that the requested property is unavailable. Java 1.1 introduces the getScaledInstance() method. The final parameter to the method is a set of hints to tell the method how best to scale the image. The following constants provide possible values for this parameter. public static final int SCALE_DEFAULT ★ The SCALE_DEFAULT hint should be used alone to tell getScaledInstance() to use the default scaling algorithm. public static final int SCALE_FAST ★ The SCALE_FAST hint tells getScaledInstance() that speed takes priority over smoothness. public static final int SCALE_SMOOTH ★ The SCALE_SMOOTH hint tells getScaledInstance() that smoothness takes priority over speed. public static final int SCALE_REPLICATE ★ The SCALE_REPLICATE hint tells getScaledInstance() to use ReplicateScaleFilter or a reasonable alternative provided by the toolkit. ReplicateScaleFilter is discussed in Chapter 12. public static final int SCALE_AREA_AVERAGING ★ The SCALE_AREA_AVERAGING hint tells getScaledInstance() to use AreaAveragingScaleFilter or a reasonable alternative provided by the toolkit. AreaAveragingScaleFilter is discussed in Chapter 12.

Constructors There are no constructors for Image. You get an Image object to work with by using the getImage() method of Applet (in an applet), Toolkit (in an application), or the createImage() method of Component or Toolkit. getImage() uses a separate thread to fetch the image. The thread starts when you call drawImage(), prepareImage(), or any other method that requires image information. getImage() returns immediately. You can also use the MediaTracker class to force an image to load before it is needed. MediaTracker is discussed in the next section.

10 July 2002 22:17

2.7

IMAGE

53

Characteristics public abstract int getWidth (ImageObserver observer) The getWidth() method returns the width of the image object. The width may not be available if the image has not started loading; in this case, getWidth() returns –1. An image’s size is available long before loading is complete, so it is often useful to call getWidth() while the image is loading. public abstract int getHeight (ImageObserver observer) The getHeight() method returns the height of the image object. The height may not be available if the image has not started loading; in this case, the getHeight() method returns –1. An image’s size is available long before loading is complete, so it is often useful to call getHeight() while the image is loading.

Miscellaneous methods public Image getScaledInstance (int width, int height, int hints) ★ The getScaledInstance() method enables you to generate scaled versions of images before they are needed. Prior to Java 1.1, it was necessary to tell the drawImage() method to do the scaling. However, this meant that scaling didn’t take place until you actually tried to draw the image. Since scaling takes time, drawing the image required more time; the net result was degraded appearance. With Java 1.1, you can generate scaled copies of images before drawing them; then you can use a version of drawImage() that does not do scaling, and therefore is much quicker. The width parameter of getScaledInstance() is the new width of the image. The height parameter is the new height of the image. If either is –1, the scaling retains the aspect ratio of the original image. For instance, if the original image size was 241 by 72 pixels, and width and height were 100 and –1, the new image size would be 100 by 29 pixels. If both width and height are –1, the getScaledInstance() method retains the image’s original size. The hints parameter is one of the Image class constants. Image i = getImage (getDocumentBase(), "rosey.jpg"); Image j = i.getScaledInstance (100, -1, Image.SCALE_FAST);

public abstract ImageProducer getSource () The getSource() method returns the image’s producer, which is an object of type ImageProducer. This object represents the image’s source. Once you have the ImageProducer, you can use it to do additional image processing; for example, you could create a modified version of the original image by using a FilteredImageSource. Image producers and image filters are covered in Chapter 12.

10 July 2002 22:17

54

CHAPTER 2: SIMPLE GRAPHICS

public abstract Graphics getGraphics () The getGraphics() method returns the image’s graphics context. The method getGraphics() works only for Image objects created in memory with Component.createImage (int, int). If the image came from a URL or a file (i.e., from getImage()), getGraphics() throws the run-time exception ClassCastException. public abstract Object getProperty (String name, ImageObserver observer) The getProperty() method interacts with the image’s property list. An object representing the requested property name will be returned for observer. observer represents the Component on which the image is rendered. If the property name exists but is not available yet, getProperty() returns null. If the property name does not exist, the getProperty() method returns the Image.UndefinedProperty object. Each image type has its own property list. A property named comment stores a comment String from the image’s creator. The CropImageFilter adds a property named croprect. If you ask getProperty() for an image’s croprect property, you get a Rectangle that shows how the original image was cropped. public abstract void flush() The flush() method resets an image to its initial state. Assume you acquire an image over the network with getImage(). The first time you display the image, it will be loaded over the network. If you redisplay the image, AWT normally reuses the original image. However, if you call flush() before redisplaying the image, AWT fetches the image again from its source. (Images created with createImage() aren’t affected.) The flush() method is useful if you expect images to change while your program is running. The following program demonstrates flush(). It reloads and displays the file flush.gif every time you click the mouse. If you change the file flush.gif and click on the mouse, you will see the new file. import java.awt.*; public class flushMe extends Frame { Image im; flushMe () { super ("Flushing"); im = Toolkit.getDefaultToolkit().getImage ("flush.gif"); resize (175, 225); } public void paint (Graphics g) { g.drawImage (im, 0, 0, 175, 225, this); } public boolean mouseDown (Event e, int x, int y) { im.flush(); repaint(); return true; }

10 July 2002 22:17

2.7

IMAGE

55

public static void main (String [] args) { Frame f = new flushMe (); f.show(); } }

2.7.2 Simple Animation Creating simple animation sequences in Java is easy. Load a series of images, then display the images one at a time. Example 2-1 is an application that displays a simple animation sequence. Example 2-2 is an applet that uses a thread to run the application. These programs are far from ideal. If you try them, you’ll probably notice some flickering or missing images. We discuss how to fix these problems shortly. Example 2–1: Animation Application import java.awt.*; public class Animate extends Frame { static Image im[]; static int numImages = 12; static int counter=0; Animate () { super ("Animate"); } public static void main (String[] args) { Frame f = new Animate(); f.resize (225, 225); f.show(); im = new Image[numImages]; for (int i=0;i

The special parameter name ARCHIVES is reserved for sending JAR files. JAR files can also be specified using the ARCHIVES parameter to the tag.* Here’s an example: