Programmer's Guide to the Java 2D™ API - High Energy Physics

126 Pages·1996·0.84 MB·English

i
Programmer’s Guide to the
Java 2D™ API
Enhanced Graphics and Imaging for Java
JavaTM 2 SDK, Standard Edition, 1.3 Version
November 19, 1999
A Sun Microsystems, Inc. Business
2550 Garcia Avenue
Mountain View, CA 94043 USA
415 960-1300 fax [phone]

iii
(cid:211) 1998, 1999 Sun Microsystems, Inc.
2550 Garcia Avenue, Mountain View, California 94043-1100 U.S.A.
All rights reserved.
RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the U.S. Government is
subjecttorestrictionsofFAR52.227-14(g)(2)(6/87)andFAR52.227-19(6/87),orDFAR252.227-
7015(b)(6/95) and DFAR 227.7202-1(a).
The release described in this document may be protected by one or more U.S. patents, foreign
patents, or pending applications.
Sun,theSunlogo,SunMicrosystems,JDK,Java,andtheJavaCoffeeCuplogoaretrademarksor
registered trademarks of Sun Microsystems, Inc. in the United States and other countries.
THIS PUBLICATION IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND,
EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR
NON-INFRINGEMENT.
THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR
TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE
INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW
EDITIONS OF THE PUBLICATION. SUN MICROSYSTEMS, INC. MAY MAKE
IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S)
DESCRIBED IN THIS PUBLICATION AT ANY TIME

Contents
Java 2DTM API Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Enhanced Graphics, Text, and Imaging . . . . . . . . . . . . . . .1
Rendering Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2
Coordinate Systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2
Transforms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5
Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Fills and Strokes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
Composites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
BackwardCompatibilityandPlatformIndependence . . .8
Backward Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
Platform Independence . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
The Java 2D™ API Packages . . . . . . . . . . . . . . . . . . . . . .10
Rendering with Graphics2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Interfaces and Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
Rendering Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
Rendering Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17
Controlling Rendering Quality . . . . . . . . . . . . . . . . . . . . . . .17
Stroke Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
Fill Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
Clipping Paths. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
Transformations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23
Composite Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
Setting Up the Graphics2D Context . . . . . . . . . . . . . . . . .27
Setting Rendering Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
Specifying Stroke Attributes. . . . . . . . . . . . . . . . . . . . . . . . .27
Specifying Fill Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . .29
v
vi
Setting the Clipping Path. . . . . . . . . . . . . . . . . . . . . . . . . . . .32
Setting the Graphics2D Transform . . . . . . . . . . . . . . . . . . . .33
Specifying a Composition Style. . . . . . . . . . . . . . . . . . . . . . .34
Rendering Graphics Primitives . . . . . . . . . . . . . . . . . . . . .36
Drawing a Shape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
Filling a Shape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
Rendering Text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38
Rendering Images. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38
Defining Custom Composition Rules . . . . . . . . . . . . . . . .38
Rendering in a Multi-Screen Environment . . . . . . . . . . .39
Geometries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Interfaces and Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Geometry Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
Constructive Area Geometry . . . . . . . . . . . . . . . . . . . . . . . . .45
Bounds and Hit Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
Combining Areas to Create New Shapes . . . . . . . . . . . . .46
Creating a Custom Shape . . . . . . . . . . . . . . . . . . . . . . . . . .47
Fonts and Text Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Interfaces and Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49
Font Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51
Text Layout Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
Shaping Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
Ordering Text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
Measuring and Positioning Text . . . . . . . . . . . . . . . . . . . . . .56
Supporting Text Manipulation. . . . . . . . . . . . . . . . . . . . . . . .56
Performing Text Layout in a Java™ Application . . . . . . . . .61
Managing Text Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
Laying Out Text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Displaying Dual Carets . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Moving the Caret . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
Hit Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
Highlighting Selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
Querying Layout Metrics. . . . . . . . . . . . . . . . . . . . . . . . . . . .65
vii
Drawing Text Across Multiple Lines . . . . . . . . . . . . . . . . . .66
Implementing a Custom Text Layout Mechanism . . . . .67
Creating Font Derivations . . . . . . . . . . . . . . . . . . . . . . . . .69
Imaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Interfaces and Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . .72
Imaging Interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72
Image Data Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72
Image Operation Classes. . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Sample Model Classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
Color Model Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
Exception Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76
Immediate Mode Imaging Concepts . . . . . . . . . . . . . . . . .76
Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
Using BufferedImages . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
Creating a BufferedImage. . . . . . . . . . . . . . . . . . . . . . . . . . .79
Drawing in an Offscreen Buffer . . . . . . . . . . . . . . . . . . . . . .79
Manipulating BufferedImage Data Directly . . . . . . . . . . . . .82
Filtering a BufferedImage. . . . . . . . . . . . . . . . . . . . . . . . . . .83
Rendering a BufferedImage. . . . . . . . . . . . . . . . . . . . . . . . . .83
Managing and Manipulating Rasters . . . . . . . . . . . . . . . .83
Creating a Raster. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
Parent and Child Rasters . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
Operations on a Raster. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
The WritableRaster Subclass. . . . . . . . . . . . . . . . . . . . . . . . .85
Image Data and DataBuffers . . . . . . . . . . . . . . . . . . . . . . .85
Extracting Pixel Data from a SampleModel . . . . . . . . . .85
ColorModels and Color Data. . . . . . . . . . . . . . . . . . . . . . .86
Lookup Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
Image Processing and Enhancement . . . . . . . . . . . . . . . .87
Using an Image Processing Operation. . . . . . . . . . . . . . . . . .89
Color. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
viii
Color Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94
Describing Colors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97
Mapping Colors through sRGB and CIEXYZ. . . . . . . . . . . .98
Printing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Interfaces and Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . .102
Printing Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102
Supporting Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
Page Painters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
Printable Jobs and Pageable Jobs. . . . . . . . . . . . . . . . . . . . .105
Typical Life-Cycle of a PrinterJob. . . . . . . . . . . . . . . . . . . .106
Dialogs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
Printing with Printables . . . . . . . . . . . . . . . . . . . . . . . . . .108
Using Graphics2D for Rendering. . . . . . . . . . . . . . . . . . . . .109
Printing a File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110
Printing with Pageables and Books . . . . . . . . . . . . . . . . .113
Using a Pageable Job. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
Using Multiple Page Painters. . . . . . . . . . . . . . . . . . . . . . . .115
Preface
This guide describes the features provided by the Java 2D™ API and illustrates
how you can use the Java 2D API classes to enhance your applications. For addi-
tional information about the Java 2D APIs, see:
• The Java Tutorial, 2nd Volume. Available online at:
http://java.sun.com/docs/books/tutorial/2d/index.html
• The2DTextTutorial.AvailableonlinefromtheJavaDeveloperConnection:
http://developer.java.sun.com/developer/onlineTraining/
Graphics/2DText/
• The Java 2D Sample Programs. Available online at:
http://java.sun.com/products/java-media/2D/samples/index.html
• The Java 2D Demo. Available from the Java 2D website:
http://java.sun.com/products/java-media/2D/index.html
This information in this guide is organized into seven chapters:
Overview —introduces the packages and key classes in the Java 2D API.
Rendering with Graphics2D—describes the Java 2D API classes in the
java.awt package and how to set up theGraphics2D rendering context.
Geometries—describes the Java 2D API classes in thejava.awt.geom
package and how to define and manipulate 2D shapes and areas.
Fonts and Text Layout—describes the Java 2D API classes in the
java.awt.font package, how to specify and retrieve font information, and
how to display and manipulate international text using the Java 2D text lay-
out APIs directly.
Imaging—describes the Java 2D API classes in thejava.awt.image,
java.awt.image.codec, andjava.awt.image.renderable packages and
how to display and manipulate images and offscreen buffers.
Color—describes the Java 2D API classes in thejava.awt.color package
and color management.
Printing—describes the Java 2D API classes in thejava.awt.print pack-
age and the Java 2D API printing model.
ix
x Preface, JavaTM 2 SDK, Standard Edition, 1.3 Version