Q What operations cause QuickDraw GX to invalidate its shape caches? We want to
maximize drawing performance in our application, and it would be nice to know ahead
of time when caches will need to be rebuilt.
A As you might imagine, this topic is complex, but we'll try to explain the basics and
give you some ideas about improving performance.
There are several caches associated with a shape, since each object associated with the
shape has a separate cache. (By the way, the caches are in the QuickDraw GX heap and
can be seen using GraphicsBug.) Every time you call GXDrawShape, QuickDraw GX
determines which caches need to be updated, updates them, and then draws the shape.
So the first thing to know is that if you want GXDrawShape to execute as fast as
possible (for instance, if you're drawing several shapes and want the time between
successive GXDrawShape calls to be minimal), you should call GXCacheShape ahead of
time to update the shape's caches, minimizing the work GXDrawShape needs to do.
In general, any time you change information within a shape, you cause QuickDraw GX
to invalidate at least one of the shape's caches. Layout shapes are exceptions to this
rule, however. The cache associated with a layout shape will not be invalidated if all of
the following conditions are met:
If you're drawing non-hairline geometric shapes and want to get them on the screen as
fast as possible, you can set the gxCacheShape attribute of the shape. With this
attribute set, QuickDraw GX will preprocess all the required parts of a shape into
compressed bitmaps. This means the shape is completely ready to be drawn when you
call GXDrawShape: the bits are just blasted to the screen.
Any time you change a view port's clip or mapping, QuickDraw GX will update all of
the caches for the shapes and child view ports associated with that view port. There
isn't any speed advantage to setting the clip or mapping of a shape rather than the clip
or mapping of the shape's view port; the same work has to happen in either case. Note,
though, that if the view port contains other shapes or has child view ports, their
caches will be invalidated, too. You should change the view port's mapping to move a
shape only when you want all shapes within the view port to move the same amount.
Q I'm looking into the possibility of writing a QuickDraw GX printer driver that will
only print to a file, and I've run into a couple of stumbling blocks I hope you can help
with. First, is there a way to create a desktop printer from the Chooser without having
an actual printer attached or selecting a port? Can I get to the Chooser list so that I can
display some kind of dummy or ghost printer? The second issue has to do with the user
interface of the Print dialogs/panels. I would like to set the "Destination: File" radio
button and disable the "Destination: Printer" one for QuickDraw GX application
interfaces.
A There should be no problem creating a printer driver that only prints to a file. And
yes, users will be able to create a desktop printer from such a driver. You can access
the Chooser list: for an example of this, look at the source code file Chooser.c from any
of the QuickDraw GX printer driver samples. You can do whatever you want within the
Chooser to handle and display lists of available printers for the currently selected
printer driver. You'll also need to modify the 'comm' resource to make sure that the
Chooser does the right thing. You should be able to put a "nops" 'comm' resource
reference into the 'look' resource.
You can disable any item in the Print dialog by overriding the GXJobPrintDialog
message and, in your override, getting the destination tag for the appropriate item and
locking it. This will make the item appear disabled in the dialog. PrintingMgr.h
contains all the tags you can lock. You should be sure to set up the item to be
gxVolatileOutputDriverCategory so that your settings go away if the user switches
drivers in the pop-up menu; you can simply OR this with collectionLockMask when
you set the item's attributes.
Q The documentation seems a bit thin on what resource type/ID is needed for ColorSync
profiles in QuickDraw GX printer drivers. Is the appropriate type 'prof' or 'cmat'?
Will QuickDraw GX automatically use one if I stick it in my driver, or do I also have to
override the various profile messages?
A All you need to do is include a 'cmat' resource with ID gxColorMatchingDataID and
specify it in your 'rdip' resource. However, you should also override
GXFindFormatProfile so that inquiring applications can ask you what the format's
profile will be. Additionally, you should override the GXImagePage message if you want
to provide different profiles on a page-by-page basis.
Q I'm working on QuickDraw GX printer drivers. Can you give me some information on
what must be done to support PrGeneral?
A PrGeneral support within your QuickDraw GX printer driver is automatic. The
printing system will automatically maintain the appropriate information within the
QuickDraw GX print record. The only exception to this automatic support is the SetRsl
opcode: if you don't want QuickDraw GX to use the default gxReslType resource when
the SetRsl opcode is used, you need to define a gxReslType resource of your own that
reflects the capabilities of your printer.
Q Our application generates its own custom PostScript TM code when printing to
PostScript printers. We'd like to support QuickDraw GX-style printing and still be
able to continue generating our own custom PostScript code to send directly to the
printer. What's the best way to handle this? I've tried generating empty shapes with
custom PostScript code attached as a tag (using synonyms), but the LaserWriter
QuickDraw GX driver emits its own "wrapper" code around our custom PostScript
code, which could alter the printer's graphics state. Are there any other methods to
achieve this without the possible side effects?
A You're actually very close to sending PostScript code correctly through the
QuickDraw GX printing system without the side effects. As you already know, after a
shape with 'post' tags has been sent to a PostScript printer, QuickDraw GX performs a
PostScript restore. There's no way to prevent this from happening. However, only
shape objects cause this behavior; QuickDraw GX will not perform a PostScript
restore for any other object besides a shape.
The fastest and best method for sending PostScript code is to attach the code with tags
(using synonyms) to only one empty shape. You can attach as many tags as are
required. We recommend that the tags contain 12K of PostScript data each, for optimal
performance. If you're sending PostScript code down to replace the clip or ink or some
other object besides a shape, just attach a 'post' tag to the object your PostScript code
describes; in this case a restore will not occur.
Q How should I download fonts to a PostScript printer under QuickDraw GX? I'm
sending a direct stream of custom PostScript code, but I don't expect the driver to be
able to deduce which fonts need to be included. I've read about the PostScript control
tag that can be attached to a shape, and I know the structure for the tag contains font
information, but the documentation about this tag is sketchy. Can you provide more
details?
Related to this question, what's the best way to cause fonts to be downloaded under the
current Printing Manager? We're using the "draw a single character off the page in
the proper font" trick. I understand this practice is frowned on. Is there an approved
way to do this short of intermixing QuickDraw and PostScript code in PicComments?
A Our thinking has changed regarding the use of the PostScript control tag for
downloading a font. If you want to download a font within your PostScript stream, you
should call GXFlattenFont and pass the font within your 'post' tag. The GX PostScript
engine will unflatten the font and download it when it finds it attached to your 'post'
tag.
The method you're using (drawing a character off the page) is completely supported
under QuickDraw GX. It was the recommended method for a long time. However, the
current recommendation is to use DrawText and pass in text that contains all the
glyphs you want to use. The reason this approach is better for QuickDraw GX is that
only the required information is downloaded, thereby saving memory on the printer.
Q Do I need to override the GXFreeBuffer message in my QuickDraw GX printer driver
if I perform a total override of the GXDumpBuffer message? If I do need to override
GXFreeBuffer, what do I do with the buffer? Should I dispose of it with DisposePtr?
A The documentation is a little confusing about the purpose of the GXFreeBuffer
message. GXFreeBuffer is sent to ensure that the indicated buffer has been processed
and is now available for more data; it doesn't actually dispose of a buffer. The only time
you need to override GXFreeBuffer is if you're doing custom I/O (the customIO flag is
set in your 'iobm' resource). The default implementation of GXFreeBuffer will work
correctly for QuickDraw GX's default buffering mechanism.
GXFreeBuffer allows you to start asynchronous I/O in GXDumpBuffer; then other
buffering routines can be sure that operations on a buffer are completed before they
reuse the buffer (or dispose of it). If you're overriding GXFreeBuffer, you should just
hang out in your override until I/O has completed for the buffer passed, and then
return. If you're doing synchronous I/O, just return immediately, since all I/O must
have completed.
Q When I control the start of a QuickTime movie from within my application, the
movie controller doesn't get updated properly. I'm calling StartMovie to begin the
movie as soon as it becomes visible, and I'm updating the movie controller like this:
theResult := MCDoAction(tmpMovie.fController, mcActionPlay,
@curRate);
However, this doesn't seem to work. What am I doing wrong?
A The MCDoAction call with mcActionPlay doesn't take a pointer to the data in the last
parameter; it takes the data itself. But since the prototype specifies type (void *), to
make the compiler happy it must be cast to a pointer. Many people have fallen into this
trap.
The recommended method to start a movie when you're using the standard movie
controller component is as follows:
// Play normal speed forward, taking into account the possibility // of a movie with a nonstandard PreferredRate. Fixed rate = GetMoviePreferredRate(MyMovie); MCDoAction(MyMovieController, mcActionPlay, (void *)rate);
If you do need to use StartMovie, the correct way to cause the movie controller to
update is to call MCMovieChanged.
Q We're using the Communications Toolbox in our application and have noticed some
strange behavior. Specifically, when a tool is being used, the tool's resource fork is
placed not at the top of the resource chain, but behind the System and application
resource forks. As a result, we're having trouble with tools that use STR# resources
that conflict with those in our application. This results in bad configuration strings or
configuration dialogs with the wrong text. I can easily work around this by changing
the resource IDs in my application, but this doesn't solve the problem in the long run.
Any advice?
A What you're seeing is a part of the "pathology" of the Communications Toolbox and its
tools. Both do a less than perfect job of looking in the correct resource map for string
resources. The result is what you're currently seeing: application strings end up being
placed where tool strings are expected.
There are a couple of workarounds. The first you've cited, which is to make sure that
none of your application's resource ID numbers conflict with the CTB tool's ID
numbers. However, as you also noted, this can be a problem when you're using several
CTB tools, and may not work if the user happens to select a tool that has a conflicting
ID.
The better way to work around the problem is to save a reference to the current
resource file and then set the resource file to the System file. After completing a call
to CMChoose or CMGetConfig, you can reset the resource file to the one you started
with. Here's how to do this:
short oldResFile;
Point dlogBoxPt;
Ptr myConfigString;
/* First save the current resource file. */
oldResFile = CurResFile();
/* Now set the resource file to the System file. */
UseResFile(0);
/* Next call CMChoose to configure your connection tool. */
myErr = CMChoose(&myConnectionHdl, dlogBoxPt, nil);
/* Now call CMGetConfig to get the configuration string from the
connection tool. */
myConfigString = CMGetConfig(myConnectionHdl);
/* And finally, restore the old resource file. */
UseResFile(oldResFile);
Q What is the Human Interface suggestion for removing a digital signature from a
signed document? I see how to add and how to verify, but I can't find any suggestions
for removing signatures.
A Here's the relevant paragraph from the AOCE Human Interface Guidelines
document, which can be found on AppleLink (search the AOCE Talk folder):
Signatures may also be deleted by users. To accomplish this, the user should select the
signature by clicking on its icon and choosing Clear from the application's Edit menu.
Selecting the signature icon and pressing the delete key is a desirable alternative. Note
that signatures must not be cut, copied, or pasted.
To actually remove a signature, just remove the 'dsig' resource from the file. Note
that signed files may have the Finder "locked" bit set. If you remove the signature, you
should also clear this bit.
Q I launch my application by dragging files onto its icon. It then opens the files,
performs some quick operation, and quits. I can put '****' and 'fold' resources in
FREFs to let users drag any file or folder onto the application icon. But when a user
drags an AOCE catalog (or anything inside the catalog) onto the icon, the Finder won't
let the user drop it onto my application. What do I need to do to my application to let
users drop-launch it with AOCE catalogs (or their contents)? I know it's possible: the
"Find in Catalog" application will drop-launch if a user dragged to it from a catalog.
A If you look, you'll see that "Find in Catalog" is a Catalogs Extension template. It's not
an application program; it actually executes as part of the Finder. Unfortunately, you
can't do what you want to with an application. You might want to look at the Catalog
Service Access Modules chapter in Inside Macintosh: AOCE Service Access Modules for
more information on the Catalogs Extension.
Q When users launch my utility application by double-clicking, I present a Standard
File dialog that lets them choose a file to operate on. I'd like them to be able to browse
AOCE catalogs as well as HFS files, but catalogs don't show up in the Standard File
dialog. I could use another dialog for browsing AOCE catalogs, but why use two different
interfaces for the same action (from the user's point of view, that is; the user just
wants to specify an object, wherever it may be)? Is there a way to get catalogs to show
up in the Standard File dialog? Is there any way to browse the file system and the AOCE
catalog system in the same dialog? If the answer is no, is there an analog to Standard
File for AOCE catalogs?
A You can't browse HFS files and AOCE catalogs in the same dialog, since they're two
different file systems. To let the user browse the AOCE catalog system, you need to use
the AOCE Standard Catalog Package Reference routines, which are documented in Inside
Macintosh: AOCE Application Interfaces . There is a routine that's analogous to
StandardGetFile. The AOCE Software Developer's Kit (available through APDA) includes
sample code that shows how to browse AOCE catalogs.
Q I'm writing an application that will watch a user-specified folder and operate on
files or folders that are dropped into it. I need to perform operations on every item in
the folder and its subfolders. What will happen if I begin to walk through a new folder
with PBGetCatInfo while the Finder is still copying files into the subfolder structure?
Can I guarantee that I'll detect all the files?
A There's no way to find out directly when the Finder is done copying items into the
folder, but there is a strategy we can recommend. First, though, you should know that
the recommended way to determine whether items have been added to a folder is to
watch its modification date. So how can you know when all the files have arrived? The
recommended strategy is to poll the parent folder's modification date every few seconds
after you first detect a change, and keep polling until you have a reasonably long
interval during which there's no change in the date (30 seconds is probably about
right). This means, of course, that there's a delay before you act on files dropped into
the folder, but as the Print Monitor shows us, this delay is probably reasonable to the
user.
One more possible gotcha you should know about: to tell whether it's safe to work with
a particular file, it's not enough just to make sure the file isn't open; you need to check
its length. If a file is closed (that is, not busy) but has no length in either its resource
or data fork, you caught the Finder at an uncomfortable time, after it created the file
but before it opened it. So to know if you can operate on a file the Finder might be
copying, you must determine two things: it's not already open, and it has length in its
resource or data fork.
Q Our application uses the Icon Utilities interface, and we want to verify that these
features are present before we use them. We've been unable to do this successfully.
The Macintosh Technical Note "Drawing Icons the System 7 Way" (QuickDraw 18)
doesn't say how to do this, but Inside Macintosh: More Macintosh Toolbox recommends
using Gestalt with the gestaltIconUtilities selector. When we try this, Gestalt returns
an error of -5551 (undefined selector). What are we doing wrong?
A There isn't a Gestalt selector for the Icon Utilities; Inside Macintosh and the header
files are wrong. Even if we were to correct that situation tomorrow (or in the next
system software release), it wouldn't help, since the Icon Utilities are available on
systems where the Gestalt selector isn't. The solution is to use the TrapAvailable
function to see if the _IconDispatch A- trap is available. You can find the source code
for TrapAvailable in Inside Macintosh Volume VI on page 3-8, or in Inside
Macintosh: Overview on page 180.
Q I have a System 7 application that the user can drag files, disks, or folders to. How
can I determine from the Apple event information which type of item (file, disk, or
folder) has been dragged to the application icon?
A When the user drags a file, disk, or folder to an application icon, the Finder uses the
Process Manager to open the application and then sends it an Open Document ('odoc')
event containing a list of alias records for each object dropped. When your application
receives the event, it needs to open each of the objects specified in the event by getting
each alias record from the list and coercing the data for that record to an FSSpec. Once
you have the FSSpec, you can check its parID to determine whether the directory ID is
fsRtParID, indicating that you're looking at a volume. If the parID is anything other
than fsRtParID, use PBGetCatInfo to determine if you have a file or a folder. Here's the
code:
enum {kItsAVolume = 1, kItsAFolder, kItsAFile};
pascal OSErr GetSpecType(FSSpec *myFSS)
{
CInfoPBRec pb;
OSErr myErr;
short objType = 0;
if ((myFSS->parID) == fsRtParID)
objType = kItsAVolume;
else {
pb.hFileInfo.ioNamePtr = (StringPtr) *(myFSS).name;
pb.hFileInfo.ioVRefNum = *(myFSS).vRefNum;
pb.hFileInfo.ioDirID = *(myFSS).parID;
pb.hFileInfo.ioFDirIndex = 0;
myErr = PBGetCatInfoSync(&pb);
if (myErr == noErr) {
/* Check to see if bit 0x10 of ioFlAttrib is set; if it
is, we've got a directory */
if ((pb.hFileInfo.ioFlAttrib & 0x10) != 0)
objType = kItsAFolder;
else
objType = kItsAFile;
}
}
return (objType);
}
Q I'm trying to implement "the perfect component." The goals for this component are
fast dispatching, delegatable, able to rely on delegates, ready for everything, and
surprised by nothing. I've been using develop Issues 12 and 14 and Inside Macintosh:
More Macintosh Toolbox to guide me, but I still have a question that wasn't addressed in
those references.
I'm using the Fast Dispatch method to dispatch my component's calls. I've figured out
how to repair the stack after getting an unsupported routine selector code, but I can't
figure out how to delegate a call. I think I'm recovering the stack correctly, but all the
documentation I've read doesn't even hint at this sort of functionality. I was thinking
that I could use DelegateComponentCall after creating a ComponentParameters record,
or I could calculate the size of the parameters and attempt to set up the stack for a
ComponentCallNow call. However, neither of these is a good solution -- they both take
too many instructions to implement and obviate the advantages of fast dispatching. Is
there such a thing as a DelegateFastComponentCall that I haven't heard of?
A Try the following to delegate a component call:
move.l d0, -(sp) ; push d0 onto stack PUSHDELEGATEGUY ; macro to push component instance move.q #-2,d0 dc.w $a82a
What apparently happened is that the engineers realized how difficult it was to call
DelegateComponentCall when the stack was screwed up. So they created a "special"
delegate call. As you can see, the selector is -2. This is supposed to be documented
somewhere in the Component Manager documentation, but was inadvertently left out.
Q Why aren't my components getting register calls? I've set the appropriate flag. I'm
registering the component from my application.
A Your component won't get called to register at all since it's being registered by an
application. If you removed your component and placed it in the Extensions folder so
that it was registered at system startup, it would receive a register call. The reason
for this is that registration of components happens only when the Component Manager
is first loaded at system startup. After system startup, components can be registered
by applications, but the register routine will not be called.
Q I heard that the new Apple digital camera will introduce a graphics format called
QuickTake. Is this truly a new format or are these just QuickTime compressed PICTs?
If it's a new format, where can I find documentation on it?
A QuickTake stores its pictures as compressed PICT files. There's a new CODEC that's
necessary to decompress the images, but no new file type. The QuickTake 100 Digital
Camera Developer Note contains extensive information about talking to the camera
from both Macintosh and Windows machines. It also documents the picture formats.
The QuickTake Camera Software Development Kit is available from APDA.
The QuickTake application that comes with the camera can save the pictures in a
variety of formats, including PICT (with or without various compressions) and TIFF.
There's also a control panel that allows the user to mount the camera as a read-only
serial RAM disk (similar to MountImage), so your application can directly download
the information from the camera's memory.
Q I'm writing my first action atom for the Installer. I tried writing a skeletal
example, as follows:
resource 'inaa' (30000) {
format2 {
continueBusyCursors, actAfter, dontActOnRemove,
actOnInstall,
'infn', 149,
0,
1000,
"Delete Folder"
}};
#include "ActionAtomHeader.h"
ActionAtomResult ActionAtomFormat2(ActionAtom2PBPtr aa)
{
Debugger();
return (kActionAtomResultContinue);
}
But the action never gets called! I don't have to explicitly refer to the 'inaa' anywhere,
do I? I checked that the resources were copied into the file correctly and had the right
IDs. What am I doing wrong?
A Your action atom is fine. The only mistake you've made is not tying your 'inaa' to a
package ('inpk'). You have to add to your 'inaa' a reference to an active 'inpk'. Once you
do that, it works great. (We had trouble with this one until we found a cool diagram on
page 8 of the Installer documentation that shows how the script resources interrelate;
that diagram is your friend, and seems to encapsulate quite a bit of critical
information.)
Q We're planning a zone name change for the zone that contains some of our
PowerShare servers. Will this require any action on the part of the administrators of
the various servers beyond informing users of the change?
A It depends on whether you're changing the zone names of some or all of the servers.
If you're changing the names of only some servers, it's entirely possible that you don't
have to notify anybody, depending on how you've replicated your folders. For a while
the new servers won't be contacted by any clients since all clients will try to address
them at their old location, but eventually all servers will again start receiving
requests from clients.
If you're changing the zone names of all the servers, the client software won't
recognize that the zone names have changed, so you'll have to throw away your key
chain and add it again after the zone names have changed. The PowerShare servers will
eventually recover and rediscover all the other servers. We recommend that you bring
up the Master Pathfinder first after changing its zone name and then bring up all the
other servers. Once all the servers are up, it should take a few hours at most for
everything to settle down again and for the system to be purring.
Q The function SMPEnumerateBlocks takes a buffer that returns information about the
blocks in a letter. The documentation (Inside Macintosh: AOCE Application Interfaces,
page 3-87) says that the buffer contains "a count byte indicating the number of blocks
in the letter, followed by a block information structure for each block." I can't find
anything that tells me what a "block information structure" is.
It looks to me as if it actually returns the count of blocks in a short, not a byte. Is this
the total number of blocks, or the number of blocks returned by the call? If I have to
call the function again to get information that didn't fit in the buffer, do I get another
count followed by more block information structures, or do I just get an array with
more block information structures without the count (short)?
The block information structure seems to be 16 bytes long, starting with an
OCECreatorType structure. Is this always correct, and what is the other information?
A This is somewhat confusing. The "block information structure" referred to here is
the MailBlockInfo structure defined in the OCEMail.h header file:
struct MailBlockInfo {
OCECreatorType blockType;
unsigned long offset;
unsigned long blockLength;
};
And yes, the count byte returned in the buffer you provide is actually a short (the
documentation is wrong). This value is placed right in front of the first MailBlockInfo
structure each time you make the call. The count indicates the number of blocks that
were put in your buffer for this particular call (not the total), which of course
depends on the size of the buffer you pass; it fits in as many as it can. Check the "more"
parameter to see if your buffer was too small to hold all the blocks, and check the
nextIndex parameter for the sequence number of the next item to be returned.
Q I found what I think is a problem with the TEGetOffset routine: when it returns, a
28-byte handle has been locked for single-styled text. I believe it's a style handle that
gets locked. This seems to be an intermittent bug, occurring only about half the time.
Is there a workaround? Is it safe to just unlock the style handle after calling
TEGetOffset?
A It's a bug all right, and it is the style handle that's getting locked. Here's a
workaround:
static short MyTEGetOffset(Point pt, TEHandle th)
{
TEStyleHandle sh;
short theResult;
char saveState;
if (th == 0L)
return;
sh = GetStyleHandle(th);
saveState = HGetState(sh);
theResult = TEGetOffset(pt,th);
HSetState(sh, saveState);
return theResult;
}
Q I have a question about the Japanese art of bonsai (colloquially known as stunting
trees): What happens if you bonsai a fruit tree? Does the fruit come out dwarfed as
well? Or does the tiny tree produce full-size fruit?
A This was a difficult one to find an answer to. It seems to depend on many factors, not
the least of which is the kind of fruit tree you're talking about. One person we talked to
said he once saw a bonsai lemon tree nine inches tall, with a single, full-size lemon
hanging from a branch. (Actually, the lemon didn't hang; it would have broken the poor
tree. Instead it rested on a small platform built especially for that purpose.) But there
were also reports of a stunted crabapple tree that produced apples the size of peas. Go
figure.
These answers are supplied by the technical gurus in Apple's Developer Support
Center. Special thanks to Pete ("Luke") Alexander, Joel Cannon, Mark ("The Red")
Harlan, Dave Hersey, Dave Johnson, Don Johnson, Scott Kuechle, Jim Luther, Kevin
Mellander, Jim Mensch, Martin Minow, and John Wang for the material in this Q & A
column. If you need more answers, take a look at the Macintosh Q & A Technical Notes
on this issue's CD. *