September 93 - GETTING STARTED WITH QUICKDRAW GX
GETTING STARTED WITH QUICKDRAW GX
PETE ("LUKE") ALEXANDER
A beta version of QuickDraw GX comes to you on this issue's CD. As you contemplate the
vast scope of it all, you may wonder how you're ever going to get your arms around
this new imaging technology. Not to worry -- this article will get you started. It walks
you through the steps to getting QuickDraw GX up and drawing and presents a simple
"GX-hip" application shell that incorporates the basics for you to experiment with.
QuickDraw GX offers developers a totally new and markedly improved way of imaging
on the Macintosh. Yes, you'll have to learn the new system, but look at what you get:
The API is simpler and the human interface is better. The amount of control your
application can exercise over text and graphics has been greatly increased. Your
application will be able to produce consistent output no matter what the output device.
And extensive support for color is built in throughout the system.
With the beta version of QuickDraw GX in hand, you're no doubt eager to create a
QuickDraw GX application and start drawing. This article covers just about everything
you need to know to get started: initializing QuickDraw GX, using windows, creating and
manipulating QuickDraw GX shapes, printing, and debugging. By way of illustration,
we discuss the QuickDraw GX shell that you'll find on this issue's CD. But before we do
that, let's take a quick look under the hood at the major features of QuickDraw GX and
how it fits into the Macintosh architecture.
QUICKDRAW GX: A QUICK LOOK UNDER THE HOOD
QuickDraw GX coexists happily with QuickDraw, thank goodness. It doesn't replace
QuickDraw, but instead "moves in next door," so you still live with a Macintosh
Toolbox based on QuickDraw. You can run QuickDraw-based applications on a
QuickDraw GX system. These applications won't even notice that QuickDraw GX is
installed, but they'll be able to take advantage of some of the QuickDraw GX printing
features, including improved background printing to all devices, desktop printers,
print job queuing, and better type management.
QuickDraw GX has three major pieces: graphics, typography, and printing. You can
visualize the relationship of these three different pieces to each other and to
QuickDraw as shown in Figure 1.
Figure 1 QuickDraw and the Pieces of QuickDraw GX
GRAPHICSThe basic building block of QuickDraw GX graphics is theshape. A shape is
an object that contains, among other things, a geometry of some type and a fill
property that specifies how the geometry should be interpreted when drawn (such as
framed or filled).
There are four basic types of shapes, classified by the nature of the geometry they
contain: geometric shapes, typographic shapes, bitmap shapes, and pictures.
• A geometric shape contains a primitive geometry: a point, a line, a curve,
a rectangle, a polygon (a series of points connected by straight lines), or a
path (a series of points connected by straight or curved lines). In addition,
there are two other special geometric shape types: empty (no geometry at all)
and full (covers the entire coordinate system).
• A typographic shape contains text, glyphs (renditions of individual
characters or character combinations over which your application has direct
control), or layouts (pieces of text for which QuickDraw GX automatically
chooses and positions glyphs, given certain information by the application).
• A bitmap shape contains a reference to a block of memory containing a bit
image, as well as information on how to interpret the bits: the pixel size,
color space, color set, and color profile.
• A picture contains a list of other shapes. The shapes in the list can be
other pictures, so that a picture is actually a hierarchical database of shapes.
Besides containing a geometry, a shape contains references to three other objects that
describe how it should be rendered. These objects are the style, the transform, and the
ink.
outside, or on the geometry), the kind of start and end cap (such as round,
pointy, or square), and ways to dash, join, and pattern shapes. For a text
shape, the style also defines the font, size, variation, and text face.
• The transformcontrols the skew, scale, perspective, and clipping of the
geometry. It also specifies where to draw it and how to hit-test it.
• The inktells the system which color to draw the geometry in. Ink also
includes information about the color matching and transfer mode.
Some of these objects in turn contain references to other objects. For example, a
transform points to a list of view port objects that describe where to draw the
geometry. A view port is like a QuickDraw grafPort in that it defines an area of local
space as a drawing environment. Unlike a grafPort, though, a view port doesn't contain
state information about the drawing environment (pen, color, transfermode, and so
on). A view port contains the mapping used to convert from the view port's local space
to a global space described by aview group. A view port object points in turn to a list
of view device objects, which describe the clip shape, mapping, and bitmap associated
with a physical device such as a monitor.
A shape can also have one or moreattributes, which modify the shape's behavior. These
attributes enable your application to specify how a shape is edited or how QuickDraw
GX stores the shape. For example, if you set the shape attribute
gxMapTransformShape, this tells QuickDraw GX that you want it to manipulate the
transform referenced by the shape, instead of directly manipulating the data contained
within the geometry of the shape.
Figure 2 depicts the shape object and what it references. The owner count is the
number of other objects within the application that reference that object. The tag list
is a list of tag objects, which are simply containers for any data the application
associates with the owning object.
Figure 2 The Shape Object and What It References
TYPOGRAPHY
QuickDraw GX has a sophisticated typographic model that's fully integrated with
graphics. The ability to do kerning, tracking, and justification, as well as ligatures and
ornamental forms of various characters, is provided by the line layout routines,
supported by the QuickDraw GX smart font format. The line layout routines work with
the typographic information contained in the TrueType GX and Type 1 GX fonts to give
you a ton of control over how text is placed on a page.
Because QuickDraw GX typography is fully integrated with graphics, you can rotate,
skew, and change the perspective of typographic shapes the same way you can
geometric shapes. You can use the text shape to draw a line of text with one style. The
glyph shape enables you to draw text in several styles and graphically manipulate each
glyph. The layout shape uses the information contained in a TrueType GX or Type 1 GX
font to automatically kern, justify, and track, and to support ligatures, final forms
(special forms found at the ends of words), and ornamental forms of the various
glyphs contained within the layout shape.
Note that although QuickDraw GX supports all existing Macintosh font formats (Type
1, bitmap, and TrueType), to take full advantage of its extensive line layout
capabilities you must use TrueType GX or Type 1 GX fonts.
PRINTING
QuickDraw GX improves printing for both users and developers. Users get an improved
human interface, and developers get much more control and functionality. From the
application's point of view, QuickDraw GX offers true device independence: you can
send the same data to all supported devices and the output will be rendered
appropriately on each device.
QuickDraw GX introduces three new printing concepts: desktop printers, portable
digital documents, and printing extensions.
Users can createdesktop printerswith the Chooser. These are represented as icons on
the desktop and are full Finder citizens; users can drag and drop print files and
documents to them. Users can also manage the print queue and redirect print files and
documents by dragging them to and from desktop printers, and can share desktop
printers with other users via PrinterShare GX.
document on a screen or printer, so you can open, review, and print the file on any
system running QuickDraw GX without the application or fonts used to create the
document. When a PDD file is created, only the glyphs used in the document are saved
along with it; since the document can't very well be edited, the PDD is secure for
transporting fonts. When you print, you can save the print job as a PDD with or
without the fonts required. If you know that the person you're sending the PDD file to
has the fonts you used, you can choose not to save the fonts with the PDD.
Printing extensionsare small standalone pieces of code that modify the behavior of
printing and give users vastly increased control, at a system rather than a program
level, over how a printed page looks. For example, through a printing extension the
user can direct a printer to print "Confidential" diagonally across each page, no matter
what program is doing the printing. The user selects a printing extension from a list
displayed in the expanded Print, By Page Setup, and Document Setup dialogs (which
appear when More Choices is clicked in the regular dialogs).
The API for QuickDraw GX printing gives you easy access to information about the page
size and orientation of a print job and enables you to keep the user from changing these
settings.
QuickDraw GX supports raster, vector, and PostScriptTM devices. The bad news is that
if your system is running QuickDraw GX, you won't be able to use any non-QuickDraw
GX printer drivers. The good news is that because QuickDraw GX provides
system-level support for developing printer drivers, it's a whole lot easier to develop
printer drivers for QuickDraw GX than it is for the old QuickDraw-based printing
architecture -- you can plan on months of development time as opposed to years. And
in many cases you may find that a printing extension, which is easier yet to develop,
will suffice to implement the desired functionality; for more information, see the
article "Developing QuickDraw GX Printing Extensions" later in this issue.
PROGRAMMING AMENITIES
QuickDraw GX offers you some truly useful programming goodies: libraries of handy
high-level routines, extensive error-handling capabilities, and a powerful new
debugging tool called GraphicsBug.
THE QUICKDRAW GX LIBRARIES
As you cruise around the QuickDraw GX folder on this issue's CD, you'll notice a folder
named Libraries. Open it and you'll find libraries of code for many common graphics,
line layout, and printing tasks. These provide sample code that most applications will
need in order to create a QuickDraw GX application. But unlike Macintosh Toolbox code,
this library code can be modified or extended by you to meet your own particular
needs. All the library code is based on core QuickDraw GX calls.
ERROR HANDLING IN QUICKDRAW GX
The goal of QuickDraw GX's error-handling capabilities is to never allow QuickDraw
GX to crash your Macintosh, and to inform you anytime QuickDraw GX can't complete
an operation. QuickDraw GX uses two different models for handling errors: one for
graphics and layout errors and another for printing errors. We'll discuss graphics and
layout errors here. Printing errors are described later in this article, under "Basic
Printing in QuickDraw GX.
There's both a debugging and a nondebugging version of the combined graphics and
layout portions of QuickDraw GX. The debugging version provides extensive