TweetFollow Us on Twitter

September 93 - DEVELOPING QUICKDRAW GX PRINTING EXTENSIONS

DEVELOPING QUICKDRAW GX PRINTING EXTENSIONS

SAM WEISS

[IMAGE 034-050_Weiss_final_rev1.GIF]

With QuickDraw GX comes a new extensible printing architecture that simply invites you to jump in and tinker. Writing printer drivers has never been easier. But with the advent of printing extensions, you may never have to write a printer driver again! This article tells you what you need to know to create QuickDraw GX printing extensions.

Macintosh system software has long provided hooks that enable developers to add system-level features in the form of INITs (now called system extensions) and cdevs (control panels). QuickDraw GX extends the extension concept to printing viaprinting extensions, plug-in software modules whose sole purpose in life is to modify the behavior of printing. Want to stamp the word "Confidential" on every page printed to a specific printer? Write a printing extension. Want to drive a sheet feeder attachment to a LaserWriter? Write a printing extension. Chances are that if there's something you want to do that the QuickDraw GX printing architecture doesn't already do, you can do it with a printing extension.

In this article, I'll describe the steps you must take to create a QuickDraw GX printing extension. By the end of the article we'll have a working, environmentally friendly extension called 4-Up. As shown in Figure 1, the 4-Up printing extension maps four document pages onto one physical page at print time, saving countless trees in the process!

Notice that I referred to a printing extension as a "software module." I would love to use the currently hip term "component," but I don't want to confuse the issue by implying that printing extensions are implemented as Component Manager components. In fact, printing extensions are a whole new sort of beast. QuickDraw GX includes a new low-level software manager called the Message Manager, which it uses to implement its extensible printing architecture. A printing extension is a client of the Message Manager called amessage handler. The Message Manager manages the construction of a hierarchy of related message handlers into a message class, allows message objectsto be instantiated from message classes, and directs messages among message handlers. I won't be going into too much detail about the Message Manager in this article. But there are times when you'll have to call the Message Manager directly from your printing extension, so you need to be aware of it.

[IMAGE 034-050_Weiss_final_rev2.GIF]

Figure 1 4-Up at Work

Another new manager included in QuickDraw GX is the Collection Manager, which manages the creation of lightweight extensible data structures calledcollections. QuickDraw GX printing makes heavy use of collections. Although we won't need to call the Collection Manager from the 4-Up extension, nearly all serious printing extensions will need to do so.

THE QUICKDRAW GX PRINTING ARCHITECTURE

Before we jump into the technical details of writing a printing extension, it will be helpful to have a general overview of the QuickDraw GX printing process. First, I'll describe how the printing process occurs in several distinct phases, each responsible for a specific subtask of the entire process. Then, I'll explain the flow of control under QuickDraw GX printing, as contrasted with that of the Printing Manager. And finally, I'll discuss how printing extensions fit into the picture.

THE FOUR SEASONS OF PRINTING
Under QuickDraw GX, printing occurs in four distinct phases:

  • Spooling, which takes place in the foreground under the control of the printing application, results in a device-independent print file being stored to disk. This print file is also known as aportable digital documentor PDD, and it can be viewed using the version of TeachText included with QuickDraw GX. Because the contents of the print file are stored in a device-independent format, it can be redirected to a device other than the original target, potentially even a different class of device, for actual printing. For example, a print file originally targeted for a PostScript LaserWriter can be redirected to an ImageWriter. The print file contains enough information to allow the document to be rendered to the best of the printer's ability, regardless of the originally intended target printer.
  • Despooling, which always occurs in the background under the control of the PrinterShare GX background printing task, is the process of reading pages from the print file for imaging. Despooling need not occur on the same machine on which spooling occurred. PrinterShare GX sends print files over the network when the target device is a remote server. Also, users may copy print files to floppy disk, or otherwise manually move them to other machines for printing.
  • Imaging also occurs in the background under the control of PrinterShare GX. Despooling and imaging always happen together, but it's useful to consider them as distinct phases since they accomplish different tasks. While the despooling process is responsible for reading the correct pages from the print file, the imaging process is responsible for translating the device-independent graphics data contained in the file into a format recognized by the target device. This would be PostScript code in the case of a PostScript LaserWriter, and it would be device- resolution bitmaps and appropriate escape sequences in the case of an ImageWriter.
  • Device communicationsencompasses the actual dialog that occurs between the printer driver and the target device. This is a distinct phase, as it may actually take place on a machine other than that on which imaging occurred. For example, if the target device is a remote server, and PrinterShare GX determines that certain necessary resources (such as fonts) aren't available on the server, PrinterShare GX may opt to image the job locally into animage file,which it sends to the server. By definition, image files are device-dependent, nonviewable, and nonredirectable. The image file is "played back" on the server during the device communications phase.

GO WITH THE FLOW
At the highest level, the flow of control under QuickDraw GX printing remains similar to that in the existing Printing Manager. There are three major players: the application, the printing API, and the printer driver. The printing application calls a layer of printing API routines, each of which either performs some task or calls the appropriate printer driver to perform some task. However, there are two major differences in QuickDraw GX printing. First, the printing API has been greatly expanded. And second, the way in which control is transferred from the API to the driver is completely different. I won't be going into detail about the expanded printing API -- but you'll need to understand the new flow of control in order to write printing extensions.

The existing Printing Manager calls the driver simply by loading the appropriate PDEF (code resource) from the driver, computing the offset to the specified routine, and jumping to it. As shown in Figure 2, QuickDraw GX printing uses an intermediary, the Message Manager, to transfer control to the driver. When the application makes a QuickDraw GX printing call, and the printing API needs to call the driver, it does so by calling the Message Manager to request that a message be sent to the driver. The advantage of this approach is flexibility. The Message Manager allows message handlers to be inserted between the printing API and the driver (which is itself a message handler). Aha! The light goes on! This gives us the ability to extend the behavior of printing, or even fix bugs, without modifying the driver's code. It also serves as the foundation upon which the printing extension mechanism is built.

DON'T SHOOT THE MESSENGER
QuickDraw GX printing defines over a hundred messages. When an application calls the printing API, QuickDraw GX either performs the requested task itself or sends one of these messages (via the Message Manager) to the driver to perform the task. For many tasks, QuickDraw GX provides a default implementation for the associated message, but sends a message to the driver anyway. This gives the driver a chance to do things its own way, or to massage the message parameters before forwarding the message on to the default implementation.

This is where printing extensions come in; they're inserted between the printing API and the driver, thereby having the opportunity tooverrideany message before it gets to the driver. There are two flavors of message overriding, partial and complete.

In a partial message override, the extension will do some work to customize the behavior of the message, but it will still forward the message to the driver. The extension may do its work before forwarding the message (preprocessing), after forwarding the message (post-processing), or both before and after forwarding the message. For example, message preprocessing might involve changing one or more of the message parameters before the driver sees them. Post-processing might involve modifying result parameters returned by the driver. [IMAGE 034-050_Weiss_final_rev3.GIF] Figure 2 The Old Way Versus the QuickDraw GX Way

In a complete message override, the extension is responsible for implementing the message entirely and does not forward the message to the driver. Since any number of extensions may be inserted between the printing API and the driver, complete overrides will also inhibit any other extensions inserted between the driver and the extension performing the override from receiving the message. So before completely overriding a message, think hard and be sure to consult the documentation (Inside Macintosh: Printing Extensions and Printer Drivers, available from Addison-Wesley in September), which gives details regarding which messages are appropriate candidates for complete overrides.

Any message not explicitly overridden by the extension is implicitly forwarded by the Message Manager to the driver -- or if there is another extension loaded before the driver, it will get the next crack at the message.

LESS IS MORE

Now that you have some background on the behind-the-scenes operations of QuickDraw GX printing, we can investigate what it takes to cram four pages into one. The first step is deciding which messages to override. With over a hundred messages to choose from, this may well be the most difficult aspect of printing extension development. If you've ever worked with a large class library like MacApp, you know what I mean. Half the battle is understanding the context within which various messages are sent. QuickDraw GX printing is no different; in fact, you can envision it as a printing class library. As in MacApp, it takes some time to learn your way around. In our case, there are at least four different messages we could override in order to stuff four pages into one: GXSpoolPage, GXDespoolPage, GXImagePage, and GXRenderPage. The one we choose will depend on the desired effect. I chose the GXDespoolPage message, which is sent by QuickDraw GX to read each page from the print file during background printing. QuickDraw GX printing always spools data to a device-independent print file and then releases control back to the foreground application. PrinterShare GX, a background printing process, despools the print file, images it, and sends the result to the target printer. By overriding the GXDespoolPage message, we have no effect on the print file itself and we don't affect spooling performance. Our modifications will be done on the fly during the background despooling/imaging phase of printing. One implication of this strategy is that our extension won't affect what the user sees when viewing the print file on the screen (soft copy); it will affect only what's actually printed (hard copy).

During the background despooling/imaging phase of printing, QuickDraw GX sends the GXDespoolPage message for each page in the print file. QuickDraw GX supplies a default implementation for this message which reads the requested page from the print file and returns it to the caller as a picture shape. The 4-Up extension simply needs to override the GXDespoolPage message and return a picture shape containing the requested page plus the three succeeding pages. Of course, we'll need to scale down the original pages and move them around on the physical page a little. But that's the basic idea.

OK, it sounds great in theory. But we have a problem. Suppose the print file contains 16 pages. We're effectively creating a 4-page document. But QuickDraw GX is going to send the GXDespoolPage message 16 times and expect a valid picture shape to be returned each time. What happens when we run out of pages, after we're called for the fourth time? As you've probably guessed, there's another message we must override called GXCountPages. This message is sent at the beginning of the imaging process to determine how many times the GXDespoolPage message should be sent. In the example given above, we would need to override GXCountPages to return 4 instead of 16.

WRITING THE CODE

Now that we know which messages to override, we can write some code. Writing the code for a printing extension consists of implementing message overrides. In the 4 - Up extension, we'll override two messages, GXCountPages and GXDespoolPage. Coding a message override is fairly straightforward, similar to coding a callback routine for other Toolbox managers. The most important part is ensuring that we declare the function with the expected calling interface.

OVERRIDING GXCOUNTPAGES
The GXCountPages message has the following interface:

OSErr GXCountPages (gxSpoolFile thePrintFile, long* numPages);

In fact, all messages share certain common interface elements. For example,all messages must return a result of type OSErr. This is important because all printing code is segmented. If the segment dispatcher fails to load your extension's code segment, it must be able to report the error condition to the caller. If your particular override doesn't do anything that can fail, simply return noErr.

Now that we know the interface to the GXCountPages message, we can implement our override. Since we're squeezing four pages into one, we can determine the number of actual pages with the following simple formula:

physicalPages = (originalPages + 3) / 4

Trick #1. Determining the value of originalPages is one of two tricky things we need to do in this extension. Your first thought might be to retrieve the document's page count from thecurrent job,which is an implicit parameter to every message. The current job is an abstract object of type gxJob, which you can think of as a replacement for the print record in the existing Printing Manager. It contains all sorts of information relating to the document being printed. We can get a reference tothe current job by calling GXGetJob, a QuickDraw GX printing routine, and then access information such as the document's page count from the job.

Although this technique would work for simple cases, it won't work if another printing extension is present and also modifying the result returned by the GXCountPages message. Consider the case where the user is running our 4-Up extension and another 2-Up extension. Ideally, the result should be an 8-to-1 mapping; both extensions would do their work, each oblivious to the other's existence, yet the final output would be the result of a cooperative effort!

The correct technique is to forward the GXCountPages message to the next message handler, and use the result we get back as the value for originalPages. Note that the value we get may actually be the result of modifications made by other extensions, but we don't care! That's the beauty and flexibility inherent in the messaging architecture. Forwarding the GXCountPages message is as easy as calling the predefined routine Forward_GXCountPages. Here's the full implementation of our GXCountPages override:

OSErr FourUpCountPages (gxSpoolFile thePrintFile, long* numPages) {
    OSErr   anErr;
    long    originalPages;

    anErr = Forward_GXCountPages(thePrintFile, &originalPages);
    nrequire (anErr, FailedForward_GXCountPages);
    
    *numPages = (originalPages + 3) / 4;
    return noErr;
    
FailedForward_GXCountPages:
    return anErr;
}

Note the use of the nrequire exception-handling macro. It displays an error string and jumps to the FailedForward_GXCountPages label if anErr is nonzero. See the article "Living in an Exceptional World" indevelopIssue 11 for more information.

OVERRIDING GXDESPOOLPAGE
The meat of the 4-Up extension is contained in the GXDespoolPage override. The GXDespoolPage message has the following interface:

OSErr GXDespoolPage (gxSpoolFile thePrintFile, long pageNumber,
    gxFormat pageFormat, gxShape *pagePicture,
    Boolean *formatChanged);

Normally, the default implementation of this message will be executed, resulting in the page identified by pageNumber being read from the print file specified by thePrintFile. Additionally, the page's associated format will be read into pageFormat, and the Boolean formatChanged will be set to true if the format being returned is different from the format returned by the last invocation of the GXDespoolPage message. Formats are abstract objects that contain formatting information for one or more pages in a document. We'll need to query the page format for its dimensions so that we can properly place our four scaled-down pages onto the physical page.

Our GXDespoolPage override must do the following work:

  1. Using pageNumber, compute the actual page numbers for the pages we must read. Remember, when QuickDraw GX asks for page 2, we'll be returning pages 5, 6, 7, and 8. Page numbers start at 1.
  2. Read up to four pages from the print file, being careful not to read past the last remaining page.
  3. Query the page's format for its dimensions. We'll be fairly unsophisticated and ignore all but the first format for each group of four pages. As a result, we won't handle all cases correctly -- for example, mixed portrait and landscape pages. This is left as an exercise for the reader.
  4. Scale down and translate each page to the correct size and position.
  5. Add the modified pages to a new picture shape, and return it.

This may seem like a lot of work. Fortunately, we can rely on the default implementation of GXDespoolPage for much of it. Here's the code:

OSErr FourUpDespoolPage (gxSpoolFile thePrintFile, long pageNumber,
                         gxFormat pageFormat, gxShape* pagePicture,
                         Boolean* formatChanged) {
    OSErr       anErr;
    long        firstPage, lastPage, numPages, whichPage;
    gxShape fourUpPage, thePages[4];
    gxShape*    atPage;
    
    /* Determine actual page numbers of the pages to despool. */
    lastPage = pageNumber * 4;
    firstPage = lastPage - 3;

    /* Determine page number for last page in spool file so that we
       can constrain our despooling loop to a valid range if fewer
       than four pages remain in the file. */
    anErr = ForwardMessage(gxCountPages, thePrintFile, &numPages);
    nrequire (anErr, FailedForward_GXCountPages);
    
    if (lastPage > numPages)
        lastPage = numPages;
    
    /* Create picture shape to hold subpages. */
    fourUpPage = GXNewShape(gxPictureType);
    anErr = GXGetGraphicsError(nil);
    nrequire (anErr, FailedGXNewShape);
    
    /* Despool backwards so that pageFormat ends up containing the
       format for the first page in the group. */
    atPage = &thePages[lastPage-firstPage]; /* Last page in group */
    numPages = 0;  /* Track number of successfully despooled pages */
    for (whichPage = lastPage; whichPage >= firstPage; --whichPage) {
        anErr = Forward_GXDespoolPage(thePrintFile, whichPage,
            pageFormat, atPage--, formatChanged);
        nrequire (anErr, FailedForward_GXDespoolPage);
        ++numPages;
    }
    
    /* Map the despooled pages onto a single physical page. */
    {
        gxRectangle pageRect;
        fixed           tx, ty;
        gxMapping   aMapping;
        
        /* Get the dimensions of the physical page. */
        GXGetFormatDimensions(pageFormat, &pageRect, nil);
        
        /* Compute x and y translation factors. */
        tx = (pageRect.right - pageRect.left) >> 1;
        ty = (pageRect.bottom - pageRect.top) >> 1;
        
        /* Initialize the mapping to scale by 50%. */
        GXResetMapping(&aMapping);
        aMapping.map[0][0] = fixed1/2;
        aMapping.map[1][1] = fixed1/2;

        /* Map the pages onto the physical page. */
        GXMapShape(thePages[0], &aMapping);

        if (numPages > 1) {
            GXMoveMapping(&aMapping, tx, 0);
            GXMapShape(thePages[1], &aMapping);
            if (numPages > 2) {
                GXMoveMapping(&aMapping, -tx, ty);
                GXMapShape(thePages[2], &aMapping);
                if (numPages > 3) {
                    GXMoveMapping(&aMapping, tx, 0);
                    GXMapShape(thePages[3], &aMapping);
                }
            }
        }
        
        /* Place the mapped pages into a single picture. */
        GXSetPictureParts(fourUpPage, 1, 0, numPages, thePages, nil,
            nil, nil);
        anErr = GXGetGraphicsError(nil);
        nrequire (anErr, FailedGXSetPictureParts);

        /* GXSetPictureParts cloned the pages, so we must dispose of
           our references to them. */
        for (atPage = &thePages[numPages-1];
             atPage >= thePages; --atPage)
            GXDisposeShape(*atPage);
    }
    
    /* Return the 4-up page. */
    *pagePicture = fourUpPage;
    
    /* Since we don't know whether the format for "actual page number
        5" is the same as that for "actual page number 1," we
        always set formatChanged to true. A more sophisticated
        extension could do the right thing here. */
    *formatChanged = true;
    
    ncheck (anErr);
    return noErr;

/*------------------------
Exception-handling code
------------------------*/

FailedGXSetPictureParts:
FailedForward_GXDespoolPage:
    for (atPage = &thePages[numPages-1];
         atPage >= thePages; --atPage)
        GXDisposeShape(*atPage);
    GXDisposeShape(fourUpPage);
FailedGXNewShape:
FailedForward_GXCountPages:
    return anErr;
}

Trick #2. This code is pretty easy to follow, but one line demands further explanation. Remember earlier I said that there were two "tricky things" our extension would have to do. The first was correctly determining the number of original pages in the document. The second trick occurs early in the above code, in the line

anErr = ForwardMessage(gxCountPages, thePrintFile, &numPages);

We need to know the actual page number for the last page in the document so that we can make sure not to read a nonexistent page. Since the last page's page number is equal to the number of pages in the document, your first thought might be to send the GXCountPages message. QuickDraw GX supplies the Send_GXCountPages routine to do this, and we would call it like so:

anErr = Send_GXCountPages(thePrintFile, &numPages);

However, this would not produce the desired result. Since this would invoke our own GXCountPages override, as well as those of all other message handlers that override GXCountPages, the result would be the total number of physical pages actually printed, not the total number of logical pages we must despool.

What we really want to do is forward the GXCountPages message. But here's the potential gotcha! We can't use QuickDraw GX's supplied Forward_GXCountPages routine to do it.

Here's why: The Message Manager provides two routines for forwarding a message. The ForwardMessage routine takes a selector, which indicates the message to be forwarded, and zero or more message-specific parameters. ForwardThisMessage takes only the message-specific parameters and assumes you want to forward thecurrentmessage. The current message is the one corresponding to the override you're currently executing -- that is, the override from which you're calling ForwardThisMessage. The problem with calling Forward_GXCountPages from within the GXDespoolPage override is that all QuickDraw GX's Forward_XXX routines are simply inline aliases to ForwardThisMessage, with the message-specific parameters added for type-checking purposes. Since it's far more common to forward the current message than it is to forward an arbitrary message, QuickDraw GX assumes the common case and provides only the corresponding aliases. Therefore, if we were to call Forward_GXCountPages from within our GXDespoolPage override, we would actually forward the GXDespoolPage message with a bogus parameter list!

This doesn't mean we can't forward arbitrary messages, but to pull it off we do have to call the Message Manager directly. In the above code, we call ForwardMessage and pass the constant gxCountPages, defined by QuickDraw GX, as the message selector. Warning:You don't get type checking when you call the Message Manager's sending and forwarding functions directly, so be careful out there!

THE JUMP TABLE
The only code left to write is the jump table for our code segment. As you'll see in the next section, QuickDraw GX determines which messages an extension overrides and the location of the associated override code from special resources within the extension. Since these resources specify the location of the extension's overrides in terms of byte offsets from the beginning of a specified code segment, it's easiest to begin each code segment with a simple assembly language jump table. That way, the extension's entry points are always well defined, independent of any changes we make to the code in the future. Also, QuickDraw GX requires that each code segment begin with a long word set to 0, and this is easily accomplished from assembly language. Since we're overriding only two messages, and our code is small, we'll have just a single segment, with the following jump table:

FourUpEntry PROC    EXPORT
    DC.L    0       ; long word required by QuickDraw GX

    IMPORT  FourUpCountPages
    JMP     FourUpCountPages 
    
    IMPORT  FourUpDespoolPage
    JMP     FourUpDespoolPage

    ENDPROC
    END

PUTTING IT ALL TOGETHER

Writing code is great, but it's useless if it never runs. There are several things we must do if our printing extension is to be recognized, loaded, and executed by QuickDraw GX.

BE RESOURCEFUL
There are four required resources (besides the code) that must be present in every printing extension. All resources, including your own, should have their sysHeap and purgeable bits set, unless otherwise noted. Except for code resources, which have IDs starting at 0, all resources should have IDs in the range reserved for printing extensions. This range extends from 0x9600 to 0x97FF (-27136 to -26625 decimal). The predefined constant gxPrintingExtensionBaseID (equal to -27136) is provided for your use. All the required resources have predefined constants for their types and IDs. For the actual values, see the appropriate header files.

The four required resources give QuickDraw GX the following important information:

  • 'over' resource: which messages you override and where to find the associated override code
  • 'eopt' resource: during which phases of printing your extension needs to run, and if and when it modifies the contents of the page
  • 'load' resource: where in the message handler chain your extension should load, relative to other printing extensions
  • 'scop' resource: which driver and printer types your extension is compatible with

The remainder of this section gives all the gory details for each of the required resources, including examples.

The 'over' resource. The override resource lists the messages you're overriding and where the associated override code is located. Printing extension code resources always have type 'pext' and should have IDs starting at 0 for maximum performance. Given the above jump table, and the fact that we override only universal printing messages, we have a single override resource that looks like this:

#define fourUpCodeSegmentID 0
#define gxCountPagesOffset  4
                            /* first entry follows zero long word */
#define gxDespoolPageOffset 8
                           /* jump table entries are 4 bytes long */


resource 'over' (-27136, purgeable, sysHeap) {
    {
        gxCountPages, fourUpCodeSegmentID, gxCountPagesOffset;
        gxDespoolPage, fourUpCodeSegmentID, gxDespoolPageOffset
    };
};

If your extension overrides imaging messages, you'll need separate override resources for each distinct class of imaging messages you override. For example, PostScript message overrides would go in a separate table, and vector overrides in yet another table. You can choose any ID within the printing extension range for these tables. You let QuickDraw GX know the override resource ID with a mapping resource whose type is the same as the driver type for the imaging messages you're overriding, and whose ID is equal to gxPrintingExtensionBaseID. There are predefined constants for these values. For example, if your extension overrides the PostScript message gxPostscriptEjectPage, you would have the following two resources:

resource 'post' (-27136, purgeable, sysHeap) {
    -27135 /* ID of our PostScript 'over' resource */
};

resource 'over' (-27135, purgeable, sysHeap) {
    {
    gxPostscriptEjectPage, postscriptSegmentID,
        gxPostscriptEjectPageOffset;
    };
};

The 'eopt' resource. The extension optimization resource provides QuickDraw GX with additional information that helps it perform optimally under certain conditions. This resource consists of a bit field containing predefined flags that tell the system when the extension executes, whether it needs to communicate with the device directly, and if and when it makes changes to the page. The 4-Up extension runs during the despooling/imaging phase and changes the page during the GXDespoolPage message. It doesn't need to communicate with the device.

Using the predefined resource template, our 'eopt' resource looks like this:

resource 'eopt' (-27136, purgeable, sysHeap) {
    gxExecuteDuringImaging, gxDontNeedDeviceStatus,
    gxChangePageAtGXDespoolPage, gxDontChangePageAtGXImagePage,
    gxDontChangePageAtGXRenderPage
};

The 'load' resource. The extension load resource tells QuickDraw GX your default loading order preference. The first extension's message handler is loaded directly above the driver. Subsequent extensions are loaded one above the other. The last extension to be loaded is the first to override a given message, and therefore has the most control. Most extensions should use the predefined constant gxExtensionLoadAnywhere, which indicates that the extension has no loading preference. If you prefer to load first, use the constant gxExtensionLoadFirst; if you prefer to load last, use gxExtensionLoadLast. You should regard this resource as a hint, not as a guarantee. For one thing, several extensions may indicate that they want to load last. Obviously, only one will win. More important, the user can reorder the extensions in any way desired, and that ordering always takes priority over the default ordering.

Our 'load' resource looks like this:

resource 'load' (-27136, purgeable, sysHeap) {
    gxExtensionLoadAnywhere
};

The 'scop' resource. The extension scope resource tells QuickDraw GX the scope of your extension's compatibility with the various driver types that are supported by QuickDraw GX. Built-in support exists for raster devices, such as the ImageWriter and LaserWriter SC, vector devices, such as plotters, and PostScript devices. If your extension is PostScript-only, you would specify that in a 'scop' resource. An example of a PostScript-only extension might be one that drives a sheet feeder attachment to a LaserWriter, which understands PostScript commands for selecting bins.

You may have up to three separate 'scop' resources. The main 'scop' resource lists the types of drivers that the extension is compatible with. It has an ID of gxPrintingExtensionBaseID. The currently supported types are 'rast', 'post', 'vect', and 'univ', for raster, PostScript, vector, and universal, respectively. For example, an extension compatible with PostScript and vector drivers, but not with raster drivers, would have the following 'scop' resource:

resource 'scop' (-27136, purgeable, sysHeap) {
    {
        'post'; /* compatible with all PostScript devices */
        'vect'; /* compatible with all vector devices */
    };
};

The second 'scop' resource has an ID of gxPrintingExtensionBaseID+1 and lists the specific printer types that the extension is compatible with. A printer's type is defined by the creator type of its resource file. For example, the LaserWriter SC has the creator type 'lwsc'. If your extension isn't generally compatible with a class of devices but does support a particular device, you should list it here. For example:

resource 'scop' (-27135, purgeable, sysHeap) {
    {
        'lwsc'; /* compatible with LaserWriter SC */
    };
};

The third 'scop' resource has an ID of gxPrintingExtensionBaseID+2 and lists the specific printer types that the extension isnot compatible with. If your extension is generally compatible with a class of devices but doesn't support a particular device, you should list it here. For example:

resource 'scop' (-27134, purgeable, sysHeap) {
    {
        'dpro'; /* incompatible with DraftPro plotter */
    };
};

Taken together, the above three 'scop' resources would indicate that the extension is compatible with all PostScript devices, all vector devices except for the DraftPro plotter, and additionally the LaserWriter SC printer.

If your extension is not driver-specific, you can indicate that it has universal scope. 4 - Up is one such extension, so we have a single 'scop' resource that looks like this:

resource 'scop' (-27136, purgeable, sysHeap) {
    { 
        'univ';
        /* universal scope => compatible with all devices */
    };
};

Note that if this 'scop' resource had instead included 'post', 'vect', and 'rast', the extension would indeed be loaded for all three device types. However, should a fourth device type be defined in the future, the extension would not support it. Thus, if your extension truly has universal scope, you should use the 'univ' type rather than enumerating all known device types.

BUILDING THE BEASTWe've written the code, we've added the necessary resources. All that's left is to build it properly. The two most important things to remember are:

  • Link the code so that it's given the proper resource type ('pext') and ID (zero- based).
  • Set the file's type to 'pext' and the creator type to something unique. This is very important! Your extension's creator type should not be all lowercase (lowercase types are reserved by Apple) and you should register it with the Developer Support Center (AppleLink DEVSUPPORT) to ensure uniqueness. When QuickDraw GX encounters two printing extensions with the same creator type, it will reject all but the first it finds. Your Link and Rez step will look something like this:
    Link  -ra =resSysHeap,resPurgeableð
        -t 'pext' ð
        -c '4-Up' ð
        -rt pext=0 ð
        -sg 4-Up ð
        -m FourUpEntry ð
        {CObjs} ð
        -o "4-Up";
    Rez -rd -o "4-Up" 4-Up.r -append

BUT WAIT! THERE'S MORE!

There you have it -- a completely functional printing extension, with minimal effort. Hopefully, by now you're brimming with ideas for extensions you can write. The mechanism is extremely powerful, and I've barely scratched the surface in this article. Serious extensions will need to override the dialog messages to install panels and gather user settings, call the Collection Manager to satisfy persistent storage needs (that is, save user settings across the spooling/imaging threshold), and call the Message Manager to manage dynamic contexts (global state that persists from one message to the next).

Extensions can also customize the Finder's desktop printer menu, save printer-wide settings in desktop printers, and manage user interface interactions via the built-in alert and status mechanisms. Perhaps a future article will explore these and other topics. For now, you should have enough information to get more than your feet wet!

SAM WEISS (AppleLink S.WEISS), famous for the PrintSpy INIT (which surfaced in the former Soviet Union when the KGB was dismantled), has been working on QuickDraw GX printing in one form or another for the last five years. In this capacity, he can often be found in his office managing collections, sending messages, rewriting the core, or cutting his own hair. But in his spare time, Sam enjoys sharing his favorite hobby (musical electronic fishkeeping) with his one-year- old daughter Talia, whose first word was DoubleDespoolDatFileDaDa-Plecostomous. When asked about life after QuickDraw GX, Sam appeared confused and muttered something about having a few philosophers over for dinner. *

THANKS TO OUR TECHNICAL REVIEWERS Dennis Farnden, Dave Hersey, Sean Parent*

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Adobe Acrobat Reader 20.012.20041 - View...
Adobe Acrobat Reader allows users to view PDF documents. You may not know what a PDF file is, but you've probably come across one at some point. PDF files are used by companies and even the IRS to... Read more
Adobe Acrobat DC 20.012.20041 - Powerful...
Acrobat DC is available only as a part of Adobe Creative Cloud, and can only be installed and/or updated through Adobe's Creative Cloud app. Adobe Acrobat DC with Adobe Document Cloud services is... Read more
Sketch 68 - Design app for UX/UI for iOS...
Sketch is an innovative and fresh look at vector drawing. Its intentionally minimalist design is based upon a drawing space of unlimited size and layers, free of palettes, panels, menus, windows, and... Read more
Bean 3.3.1 - Fast and uncluttered word p...
Bean is no longer being actively developed, but will be updated as necessary to patch bugs and maintain OS X compatibility Bean is lean, fast, and uncluttered. If you get depressed at the thought... Read more
RetroArch 1.9.0 - Game emulator.
RetroArch is most popularly known for being a program with which you can play many emulators and games, which have all been customized and tailor-ported to the libretro API. It is designed to be fast... Read more
NetNewsWire 5.0.4 - RSS and Atom news re...
NetNewsWire is the best way to keep up with the sites and authors you read most regularly. Let NetNewsWire pull down the latest articles, and read them in a distraction-free and Mac-like way. Native... Read more
EarthDesk 7.4.5 - $24.99
EarthDesk replaces your static desktop picture with a rendered image of Earth showing correct sun, moon, and city illumination. With an Internet connection, EarthDesk displays near-real-time global... Read more
BetterTouchTool 3.401 - Customize multi-...
BetterTouchTool adds many new, fully customizable gestures to the Magic Mouse, Multi-Touch MacBook trackpad, and Magic Trackpad. These gestures are customizable: Magic Mouse: Pinch in / out (zoom)... Read more
Vienna 3.5.6 :e12c952d: - RSS and Atom n...
Vienna is a freeware and Open-Source RSS/Atom newsreader with article storage and management via a SQLite database, written in Objective-C and Cocoa, for the OS X operating system. It provides... Read more
WhatsApp 2.2031.5 - Desktop client for W...
WhatsApp is the desktop client for WhatsApp Messenger, a cross-platform mobile messaging app which allows you to exchange messages without having to pay for SMS. WhatsApp Messenger is available for... Read more

Latest Forum Discussions

See All

Scrappers receives a major update that a...
Q-Games' Scrappers has received a fairly sizeable new update that adds fresh gameplay features and a host of quality-of-life tweaks. [Read more] | Read more »
Motorball is a car football game from No...
A few years back Noodlecake Studios announced that they would be dipping in the multiplayer gaming realm with two different games. The first of those, Golf Blitz, released a while back and has proven to be very popular. Now, the second has arrived... | Read more »
SINoALICE's latest update introduce...
SINoALICE's latest update has now arrived, adding several fan-favourite characters from popular RPG series NieR. Young Nier, Kaine, and Young Emil are available in-game as part of a limited-time crossover event set to run until August 20th. [Read... | Read more »
Rocat Jumpurr is an intense roguelite pl...
Rocat Jumpurr is a roguelite platformer from developer Mousetrap Games. You might already be familiar with it if you follow the Big Indie Pitch, where it won first place during this year's Pocket Gamer Connects London competition. Following its... | Read more »
PUBG Mobile's Play As One campaign...
Back in mid-July, we reported that PUGB Mobile had teamed up with Direct Relief to help raise money for the charity's COVID-19 response project. It focused on an in-game running challenge for players, which lead to the PUBG Mobile donating $2... | Read more »
Marvel Contest of Champions' latest...
Marvel Contest of Champions' latest motion comic has arrived, and it shows off new fighters Air-Walker and Dragon Man. Both characters are set to arrive in-game this month. [Read more] | Read more »
Clash Royale: The Road to Legendary Aren...
Supercell recently celebrated its 10th anniversary and their best title, Clash Royale, is as good as it's ever been. Even for lapsed players, returning to the game is as easy as can be. If you want to join us in picking the game back up, we've put... | Read more »
Global Spy is an intriguing 2D spy sim f...
Developer Yuyosoft Innovations' Global Spy launched last month for iOS and Android, though if you missed it at the time, we're here to tell you why it's well worth a go. This one's all about international espionage, tracking down elusive spies,... | Read more »
Distract Yourself With These Great Mobil...
There’s a lot going on right now, and I don’t really feel like trying to write some kind of pithy intro for it. All I’ll say is lots of people have been coming together and helping each other in small ways, and I’m choosing to focus on that as I... | Read more »
Hyena Squad is sci-fi turn-based strateg...
Wave Light Games has just revealed its latest release, Hyena Squad, a turn-based RPG set in a space station infested by gross aliens and the living dead. The announcement was first reported on by Touch Arcade. [Read more] | Read more »

Price Scanner via MacPrices.net

Apple drops prices on clearance 27″ 5K iMacs,...
Apple has dropped prices on Certified Refurbished 2019 27″ iMacs to a new low of $1439 and up to $520 off their original MSRP. Apple’s one-year warranty is standard and shipping is free. The... Read more
Price drop: Clearance 8-core iMac Pro for $38...
Apple has dropped their price on Certified Refurbished 27″ 3.2GHz 8-Core iMac Pros to $3819 including free shipping. Their price is $1180 off the original MSRP of new models. A standard Apple one-... Read more
Monday sale: New 13″ 2.0GHz MacBook Pros for...
Amazon has new 2020 13″ 2.0GHz/512GB MacBook Pros back in stock on sale today for $200 off Apple’s MSRP. Shipping is free. Be sure to purchase the MacBook Pro from Amazon, rather than a third-party... Read more
Sale! Apple’s 16″ MacBook Pros for up to $349...
Apple Authorized Reseller Adorama has new 2019 16″ MacBook Pros in stock on sale today for $100-$349 off Apple’s MSRP, each including free shipping. Their prices for 8-core models ($349 off) are the... Read more
Save hundreds of dollars on a custom-configur...
Save up to $920 on a custom-configured 16″ MacBook Pro with these Certified Refurbished models that Apple has restocked today. Each MacBook Pro features a new outer case, free shipping, and includes... Read more
New 2020 12.9″ iPad Pros on sale for up to $8...
Apple reseller Expercom has new 2020 Apple 12.9″ iPad Pros on sale today for $60-$85 off MSRP, with prices starting at $939. These are the same iPad Pros sold by Apple in their retail and online... Read more
Woot offers numerous 2018-2020 MacBook Pros a...
Amazon-owned Woot has many open-box return MacBook Airs and MacBook Pros available today at prices starting at $879. Shipping is free for Prime members. Here’s what they have as of this post, and... Read more
Apple restocks refurbished 2020 13″ MacBook A...
Apple has restocked Certified Refurbished 2020 13″ MacBook Airs starting at only $849 and up to $200 off the cost of new Airs. Each MacBook features a new outer case, comes with a standard Apple one-... Read more
Apple restocks clearance 2019 13″ 2.4GHz MacB...
Apple has restocked Certified Refurbished 2019 13″ 2.4GHz 4-Core Touch Bar MacBook Pros starting at $1359 and up to $560 off original MSRP. Apple’s one-year warranty is included, shipping is free,... Read more
Apple restocks refurbished iPhone XR models s...
Apple has restocked Certified Refurbished, unlocked, iPhone XR models in the refurbished section of their online store starting at $539. Each iPhone comes with Apple’s standard one-year warranty,... Read more

Jobs Board

Cub Foods - *Apple* Valley - Now Hiring Par...
Cub Foods - Apple Valley - Now Hiring Part Time! United States of America, Minnesota, Apple Valley New Retail Post Date 6 days ago Requisition # 122305 Sign Up Read more
Director of *Apple* Enterprise Operations -...
## Description JOB SUMMARY: The Director of Apple Enterprise Operations is responsible for developing and managing the overall strategy, operation and management of Read more
Cub Foods - *Apple* Valley - Now Hiring Par...
Cub Foods - Apple Valley - Now Hiring Part Time! United States of America, Minnesota, Apple Valley New Retail Post Date 5 days ago Requisition # 122305 Sign Up Read more
Blue *Apple* Cafe Student Worker - Fall - P...
…to enhance your work experience. Student positions are available at the Blue Apple Cafe. Employee meal discount during working hours is provided. Duties include food Read more
Cub Foods - *Apple* Valley - Now Hiring Par...
Cub Foods - Apple Valley - Now Hiring Part Time! United States of America, Minnesota, Apple Valley New Retail Post Date 4 days ago Requisition # 122305 Sign Up Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.