Carbon: How to print to PDF
Andy on Nov 27th 2006
Although I’ve written more about Cocoa than Carbon, my professional gig is usually the opposite. My experience is in (often large) commercial shrink wrap software, which, at this point, is usually written in Carbon. Because of this, I recently had to opportunity to discover what it takes to print to PDF in a Carbon application. Of course, by “opportunity” I mean excruciating, unending pain.
It turns out that you only need one API to change your print loop to dump out to a PDF:
extern OSStatus PMSessionSetDestination( PMPrintSession printSession, PMPrintSettings printSettings, PMDestinationType destType, CFStringRef destFormat, CFURLRef destLocation);
It’s defined in PMCore.h, and even has documentation for it in the headers. You simply pass in the print session and settings, then specify kPMDestinationFile for the destination type, kPMDocumentFormatPDF for the destination format, and then a CFURLRef for the location of the PDF file.
Easy huh?
Unless you have to go find this API for yourself. i.e. You want to print to a PDF, but don’t know what API will actually do that. You see, the Print Manager documentation is part of Apple’s patented Don’t Document a Damn Thing initiative. And as I can attest, it’s a resounding success.
I searched through the headers (which still draws bizarre stares from Windows people. “You mean Apple doesn’t like developers enough to even provide real documentation?”), but couldn’t find anything that actually did what I needed. I googled for it too, but to no avail. I eventually found the API by digging through an email list archive.
Carbon documentation is apparently highly classified information at Apple. No one is supposed to know about it, let alone talk about it. It’s approximately at the same level of secrecy as the Freemason’s secret handshake. Except that I assume Apple would dispatch someone to take you out if you discovered any information on the Carbon API’s. That’s the only reason I can determine for the sparseness of documentation.
Unless you buy the other reason I’ve heard: Cocoa is the way of the future, so it doesn’t benefit Apple to document the old APIs. I mean, obviously, since I can’t figure out how to do something in Carbon, I should just port this 500kloc+ application to Cocoa. After all, we all saw Steve port an entire application by just checking a little box. And remember that demo where they build an entire word processor without writing a line of code? Why can’t you be that good?
What I’m thankful for this year: bitterness.
Filed in Macintosh, Programming | 8 responses so far
Scott Anguish Nov 28th 2006 at 03:03 am 1
PMSessionSetDestination is documented in the Printing Manager doc - and it appears to have been since 2002. And the same documentation file discusses both PDF and saving to a file.
Heck, there is even a chapter in the book “Supporting Printing in Your Carbon Application” called “Saving a Document as a PDF File”. I’m not sure how much easier to find that could be. And seems to have been there for quite a while as well according to the Revision History
Scott Anguish Nov 28th 2006 at 03:11 am 2
I did a quick google search on
Save as PDF File Carbon Mac OS X
and the chapter with the example code was the second link. The first was the porting guide for Windows (which also covers this, although lacks the source and specific wording, but does point to the Carbon Printing Manager book).
Scott Stevenson Nov 29th 2006 at 04:11 am 3
I can’t figure out how to do something in Carbon, I should just port this 500kloc+ application to Cocoa
But the first 499k lines just setup the main window.
Andy Nov 29th 2006 at 01:38 pm 4
This will teach me to post about not being able to find documentation. Or maybe it will teach me to whine about it before I find it, that way someone does the work for me.
I actually did try google several times. I even now just tried “Save as PDF File Carbon Mac OS X”, and none of the links on the first page show how to programmatically print to a PDF file. The second link just seems to mention that it’s possible (as does the first link), but with no links or discussion on how it’s actually done. Maybe I’m missing something obvious here?
I will admit that I was able to find the “Saving a Document as a PDF file” page after it was mentioned, and it was quite useful and documented the necessary API. However, I was only able to find it by searching for the API, PMSessionSetDestination.
Andy Nov 29th 2006 at 01:46 pm 5
But the first 499k lines just setup the main window
The interesting story behind this was, at the start of Mac OS X 10.0, Apple actually trying to get Macromedia to port their applications to Cocoa. At least, that’s what some of the Apple reps were telling some of the Macromedia engineers.
I’m not sure if that was an official direction Apple was going in, but talking to the engineers about it seems like the last thing you want to do in that situation. They’re the ones who know how much work it would be to make it happen.
Of course, sometimes Apple seems oblivious to how much work something is going to be when they really want it. There was that one time they were wanting Spotlight plugins… oy.
Scott Anguish Nov 29th 2006 at 03:27 pm 6
Interesting… that search does now bring up another set of links (the first one is the same, but the second is different)
So I tried “Save as PDF Carvon” in Xcode… second link is still the right document, with the example code.
Scott Stevenson Nov 30th 2006 at 03:57 am 7
The interesting story behind this was, at the start of Mac OS X 10.0, Apple actually trying to get Macromedia to port their applications to Cocoa
If you were given the chance to go back in time with everything you know now, would you try to convince the Macromedia folks to just go the Cocoa route?
Andy Dec 2nd 2006 at 04:29 pm 8
No, the Cocoa route simply wasn’t viable then. Now, you can mix and match Cocoa and Carbon windows, but then it wasn’t possible. That meant the transition from Carbon to Cocoa would have to be total, and simply wasn’t feasible economically or timewise.
These days, I would recommend adding Cocoa windows for new features (instead of using Carbon windows), for the apps that could handle that. However, because of internal framework architectures, some applications wouldn’t be able to even take advantage of that. Their framework would dictate an entire transition to Cocoa, which is questionable, even with Adobe’s resources.
Futhermore, some internal frameworks are too low level to sit on top of Cocoa, so from a technical standpoint, aren’t feasible.