INSIDE MACINTOSH QuickDraw GX Graphics Addison-Wesley Publishing Company Reading, Massachusetts Menlo Park, California New York Don Mills, Ontario Wokingham, England Amsterdam Bonn Sydney Singapore Tokyo Madrid San Juan Paris Seoul Milan Mexico City Taipei Apple Computer, Inc. Simultaneously published in the United © 1994 Apple Computer, Inc. States and Canada. All rights reserved. No part of this publication may be LIMITED WARRANTY ON MEDIA AND reproduced, stored in a retrieval REPLACEMENT system, or transmitted, in any form or ALL IMPLIED WARRANTIES ON THIS by any means, mechanical, electronic, MANUAL, INCLUDING IMPLIED photocopying, recording, or otherwise, WARRANTIES OF MERCHANTABILITY without prior written permission of AND FITNESS FOR A PARTICULAR Apple Computer, Inc. Printed in the PURPOSE, ARE LIMITED IN DURATION United States of America. TO NINETY (90) DAYS FROM THE DATE No licenses, express or implied, are OF THE ORIGINAL RETAIL PURCHASE granted with respect to any of the OF THIS PRODUCT. technology described in this book. Apple retains all intellectual property Even though Apple has reviewed this rights associated with the technology manual, APPLE MAKES NO WARRANTY described in this book. This book is OR REPRESENTATION, EITHER EXPRESS intended to assist application OR IMPLIED, WITH RESPECT TO THIS developers to develop applications only MANUAL, ITS QUALITY, ACCURACY, for Apple Macintosh computers. MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, Every effort has been made to ensure THIS MANUAL IS SOLD “AS IS,” AND that the information in this manual is YOU, THE PURCHASER, ARE ASSUMING accurate. Apple is not responsible for THE ENTIRE RISK AS TO ITS QUALITY printing or clerical errors. AND ACCURACY. Apple Computer, Inc. IN NO EVENT WILL APPLE BE LIABLE 20525 Mariani Avenue FOR DIRECT, INDIRECT, SPECIAL, Cupertino, CA 95014 INCIDENTAL, OR CONSEQUENTIAL 408-996-1010 DAMAGES RESULTING FROM ANY Apple, the Apple logo, LaserWriter, and DEFECT OR INACCURACY IN THIS Macintosh are trademarks of Apple MANUAL, even if advised of the possibility Computer, Inc., registered in the United of such damages. States and other countries. THE WARRANTY AND REMEDIES SET QuickDraw and TrueType are FORTH ABOVE ARE EXCLUSIVE AND IN trademarks of Apple Computer, Inc. LIEU OF ALL OTHERS, ORAL OR Adobe Illustrator, Adobe Photoshop, WRITTEN, EXPRESS OR IMPLIED. No and PostScript are trademarks of Adobe Apple dealer, agent, or employee is Systems Incorporated, which may be authorized to make any modification, registered in certain jurisdictions. extension, or addition to this warranty. FrameMaker is a registered trademark Some states do not allow the exclusion or of Frame Technology Corporation. limitation of implied warranties or liability Helvetica and Palatino are registered for incidental or consequential damages, so trademarks of Linotype Company. the above limitation or exclusion may not ITC Zapf Dingbats is a registered apply to you. This warranty gives you trademark of International Typeface specific legal rights, and you may also have Corporation. other rights which vary from state to state. Optrotech is a trademark of Orbotech Corporation. ISBN 0-201-40673-X Library of Congress Cataloging-in-Publication Data 1 2 3 4 5 6 7 8 9-CRW-9897969594 First Printing, March 1994 Inside Macintosh. QuickDraw GX graphics. p. cm. Includes index. ISBN 0-201-40673-X 1. Macintosh (Computer)—Programming. 2. Computer graphics. 3. QuickDraw GX. I. Apple Computer, Inc. II. Title: QuickDraw GX graphics. QA76.8.M3I53 1994 006.6’765—dc20 93-48597 CIP Contents Figures, Tables, and Listings xi Preface About This Book xxiii What to Read xxv Chapter Organization xxvi Conventions Used in This Book xxvi Special Fonts xxvi Types of Notes xxvii Numerical Formats xxvii Type Definitions for Enumerations xxvii Illustrations xxviii Development Environment xxviii Developer Products and Support xxviii Chapter 1 Introduction to QuickDraw GX Graphics 1-1 About QuickDraw GX Graphics 1-4 Geometric Shapes 1-7 Geometric Shape Types 1-8 Geometric Shape Geometries 1-9 Geometric Shape Fills 1-10 Geometric Styles, Inks, and Transforms 1-11 Geometric Operations 1-14 Bitmap Shapes 1-17 Picture Shapes 1-20 Chapter 2 Geometric Shapes 2-1 About Geometric Shapes 2-5 The Geometric Properties of Shape Objects 2-7 Shape Type 2-7 Shape Geometry 2-9 Shape Fill 2-12 The Geometric Shape Types 2-16 Empty Shapes and Full Shapes 2-16 Point Shapes 2-16 Line Shapes 2-17 Curve Shapes 2-18 Rectangle Shapes 2-20 iii Polygon Shapes 2-22 Path Shapes 2-25 Using Geometric Shapes 2-27 Creating and Drawing Empty Shapes and Full Shapes 2-28 Creating and Drawing Points 2-29 Creating and Drawing Lines 2-36 Creating and Drawing Curves 2-41 Creating and Drawing Rectangles 2-43 Creating and Drawing Polygons 2-45 Creating Polygons With a Single Contour 2-46 Creating Polygons With Multiple Contours 2-49 Creating Polygons With Crossed Contours 2-50 Creating and Drawing Paths 2-55 Creating Paths With a Single Contour 2-57 Creating Paths Using Only Off-Curve Points 2-59 Creating Paths With Multiple Contours 2-60 Converting Between Geometric Shape Types 2-65 Converting Shapes to Points, Lines, and Rectangles 2-66 Converting Shapes to Curve Shapes 2-71 Converting Shapes to Polygons and Paths 2-74 Replacing Geometric Points 2-79 Editing Polygon Parts 2-82 Editing Paths Parts 2-91 Editing Shape Parts 2-93 Applying Functions Described Elsewhere to Geometric Shapes 2-100 Shape-Related Functions Applicable to Geometric Shapes 2-100 Other Functions Applicable to Geometric Shapes 2-103 Geometric Shapes Reference 2-103 Data Types 2-104 The Point Structure 2-104 The Line Structure 2-105 The Curve Structure 2-105 The Rectangle Structure 2-106 Polygon Structures 2-106 Path Structures 2-107 Functions 2-108 Creating Geometric Shapes 2-109 Getting and Setting Shape Geometries 2-119 Editing Shape Geometries 2-135 Drawing Geometric Shapes 2-157 Summary of Geometric Shapes 2-163 Constants and Data Types 2-163 Functions 2-164 iv Chapter 3 Geometric Styles 3-1 About Geometric Styles 3-5 Shapes and Styles 3-5 Incorporating Stylistic Variations Into Shape Geometries 3-8 Style Properties 3-11 Default Style Objects 3-12 Curve Error 3-14 The Geometric Pen 3-15 Style Attributes 3-17 Pen Placement 3-18 Grids 3-20 Interactions Between Caps, Joins, Dashes, and Patterns 3-22 Caps 3-23 Joins 3-25 Dashes 3-27 Patterns 3-31 Interactions Between Caps, Joins, Dashes, and Patterns 3-33 Using Geometric Styles 3-35 Associating Styles With Shapes 3-36 Constraining Shape Geometries to Grids 3-40 Constraining Shapes to Device Grids 3-42 Using Curve Error When Converting Paths to Polygons 3-45 Using Curve Error When Reducing Shapes 3-49 Manipulating Pen Width and Placement 3-51 Adding Caps to a Shape 3-57 Adding Standard Caps to a Shape 3-59 Adding Joins to a Shape 3-61 Adding Standard Joins to a Shape 3-64 Dashing a Shape 3-66 Adjusting Dashes to Fit Contours 3-70 Insetting Dashes 3-73 Breaking and Bending Dashes 3-74 Wrapping Text to a Contour 3-80 Determining Dash Positions 3-81 Adding a Pattern to a Shape 3-86 Determining Pattern Positions 3-88 Combining Caps, Joins, Dashes, and Patterns 3-91 Geometric Styles Reference 3-96 Constants and Data Types 3-96 Style Objects 3-97 Style Attributes 3-98 The Cap Structure 3-99 Cap Attributes 3-101 The Join Structure 3-101 Join Attributes 3-102 v The Dash Structure 3-103 Dash Attributes 3-105 The Pattern Structure 3-106 Pattern Attributes 3-107 Functions 3-108 Getting and Setting Style Attributes 3-109 Getting and Setting Curve Error 3-114 Getting and Setting the Pen Width 3-119 Getting and Setting Caps 3-123 Getting and Setting Joins 3-129 Getting and Setting Dashes 3-134 Getting and Setting Patterns 3-142 Summary of Geometric Styles 3-149 Constants and Data Types 3-149 Functions for Manipulating Geometric Style Properties 3-151 Chapter 4 Geometric Operations 4-1 About Geometric Operations 4-4 Contours and Contour Direction 4-4 Reducing and Simplifying Shape Geometries 4-9 The Primitive Form of Shape Geometries 4-12 Geometric Information 4-16 Touching and Containing 4-18 Geometric Arithmetic 4-21 Using Geometric Operations 4-23 Determining and Reversing Contour Direction 4-23 Breaking Shape Contours 4-28 Eliminating Unnecessary Geometric Points 4-30 Simplifying Shapes 4-33 Converting a Shape to Primitive Form 4-38 Finding Geometric Information About a Shape 4-41 Finding the Length of a Contour 4-42 Finding the Point at a Certain Distance Along a Contour 4-42 Finding the Bounding Rectangle and Center Point of a Shape 4-43 Finding the Area of a Shape 4-45 Setting a Shape’s Bounding Rectangle 4-47 Insetting Shapes 4-50 Determining Whether Two Shapes Touch 4-53 Determining Whether One Shape Contains Another 4-58 Performing Geometric Arithmetic With Shapes 4-60 Geometric Operations Reference 4-67 Constants and Data Types 4-67 Contour Directions 4-67 vi Functions 4-68 Determining and Reversing Contour Direction 4-68 Breaking Shape Contours 4-72 Reducing and Simplifying Shapes 4-74 Incorporating Style Information Into Shape Geometries 4-79 Finding Geometric Information About Shapes 4-83 Getting and Setting Shape Bounds 4-90 Insetting Shapes 4-94 Determining Whether Two Areas Touch 4-95 Determining Whether One Shape Contains Another 4-100 Performing Geometric Arithmetic With Shapes 4-104 Summary of Geometric Operations 4-117 Constants and Data Types 4-117 Functions 4-117 Chapter 5 Bitmap Shapes 5-1 About Bitmap Shapes 5-3 Bitmap Geometries 5-5 Bitmap Styles and Inks 5-8 Bitmap Transforms 5-10 Bitmaps and View