Safe from the Losing Fight

There comes a time in a man’s life when he must write about glyphs. This is that time.

…but I don’t need a pyramid

Glyphs are essentially pictures. They’re are a lot like hieroglyphs, except with less hiero, and they don’t necessarily involve Egyptians or slave labor. Glyphs are drawn on the screen to represent a character or group of characters. They can also be special symbols, such as the clover used for the command key. Before a string is drawn to the screen, the characters are first converted to glyphs, then the glyphs are drawn to the screen.

Although it’s rarely necessary to drop down to the glyph level, let’s be honest: who doesn’t want a chance to play around with glyphs? After all, all the cool pharaohs are doing it.

Obtaining a glyph

Before you can do anything with a glyph, you have to get one, just like before you can use a pyramid, someone has to be dead, preferably a mummy.

If you just have plain text, getting the glyphs is pretty easy. You just use NSLayoutManager:


NSTextStorage* storage = [[[NSTextStorage alloc] initWithString:string] autorelease];
NSLayoutManager* layout = [[[NSLayoutManager alloc] init] autorelease];
[layout setTextStorage:storage];

unsigned i = 0;
for (i = 0; i < [layout numberOfGlyphs]; ++i) {
NSGlyph glyph = [layout glyphAtIndex:i];

// ... do something with the glyph...
}


string, as passed in to the NSTextStorage object, is the string you want glyphs for.

As I mentioned earlier you can also have glyphs that are special symbols. Typically, these are font specific, and are named. For example, the command key glyph is in the special .Keyboard font, and is named “propellor.” It only takes a couple of lines to get ahold of it:


NSFont* font = [NSFont fontWithName:@".Keyboard" size:13];
NSGlyph glyph = [font glyphWithName:@"propellor"];


I should note that NSGlyph is just an unsigned integer.

Wasn’t that fun? Sure it’s not a large, geometrically shaped, timeless monument in your honor, but what did you want from a blog?

Draw like an Egyptian

Glyphs aren’t that much use unless you can draw them. As the pyramids show, things are the easiest when you make someone else do all the hard work. To that end, the easiest way to draw a glyph is to take advantage of NSAttributedString.

First, I’m going to assume I already have the font and glyph, retrieved from the previous example.

Second, I need to build up a glyph info (NSGlyphInfo) object. Since glyphs are often specific to fonts, I have to include the font as well as the glyph code. What’s not completely obvious is what the “base string” is for. It is essentially a placeholder string, that will be replaced by the specified glyph when it is drawn.

The following code shows how to create a glyph info object for the command key glyph.


NSString* baseString = [NSString stringWithFormat:@"%C", 0xFFFD];
NSGlyphInfo* glyphInfo = [NSGlyphInfo glyphInfoWithGlyph:glyph forFont:font baseString: baseString];


You might be wondering why I chose the 0xFFFD character for a base string. Much like the pyramids, it’s a mystery to me. Some glyphs (like those in the Apple Symbols font) will draw with just about any base string you give it. However, other glyphs, like those in .Keyboard, only draw if you give them a specific base string.

I discovered the 0xFFFD value by dropping in a NSTextView in Interface Builder, running the app, and dropping in a bunch of glyphs using the Character Palette Input Method. Then I called textStorage on the NSTextView (which returns a subclass of NSAttributedString) and dumped out the NSAttributedString.

Now that I have a glyph info object, I can create my NSAttributedString. I just need to specify attributes for the font, NSFontAttributeName, and the glyph itself, via NSGlyphInfoAttributeName.


NSDictionary* attributes = [NSDictionary dictionaryWithObjectsAndKeys: font, NSFontAttributeName, glyphInfo, NSGlyphInfoAttributeName, nil];
NSAttributedString* string = [[NSAttributedString alloc] initWithString: baseString attributes:attributes];


Notice that for the string, I just provide the base string. I could include regular text, which could contain multiple instances of the base string. Each instance of the base string would be replaced by the glyph when drawn.

Now that I have a NSAttributedString, there a couple of things I can do with it. If I have a control of some sort, like, say, a NSTextField, I can just call setAttributedStringValue: and pass in my attributed string, and the control will take care of drawing it. Otherwise, I can take a more direct approach, and call drawAtPoint: or drawInRect: on the NSAttributedString.

If using NSAttributedString isn’t low level enough for you, then you’re a control freak and should seriously seek professional help. But before you go, first consider NSBezierPath.

In this example, let’s assume font is a NSFont that contains all the glyphs I want to use. Also, assume glyphs is an NSArray of NSNumbers containing the glyph codes I want to draw. Note that this means the sample code will only work if all glyphs are from the same font.


NSBezierPath* path = [NSBezierPath bezierPath];
float left = 0;

// First, generate a bezier path with our glyphs
unsigned count = [glyphs count];
unsigned i = 0;
for (i = 0; i < count; ++i) {
NSNumber* glyphNumber = [glyphs objectAtIndex:i];
NSGlyph glyph = [glyphNumber unsignedIntValue];

[path moveToPoint: NSMakePoint(left, -[font descender])];
[path appendBezierPathWithGlyph: glyph inFont: font];

NSSize advancement = [font advancementForGlyph: glyph];
left += advancement.width;
}
[[NSColor blackColor] set];
[path fill];


Since glyphs are font specific, I have to ask the font for glyph measurements, in order to place the glyphs properly.

More interestingly, note that since I have a NSBezierPath, I can do any sort of graphic transform or translation on the glyphs. I can rotate them, change their color, or do my own kerning. If you’re writing your own graphics program, handling text at the glyph level, using NSBezierPaths, is very useful.

Beating a dead mummy

Hopefully this post has given you many insights into what you can do glyphs. Namely, build pyramids. Or attributed strings. Whatever.

Currently most of the business we do at Order N Development is contracting. All of our clients handle us, as contractors, differently. Some seem to be better at managing contractors than others. As a way to improve relations, or potential relations, I’ve put together a list of things to watch out for when managing contractors.

Pickup lines

The first thing potential clients do is approach us and try to determine if we can help them (that’s deep, I know). Unfortunately, the confusion seems to come in when they determine what information we, as an engineering company, need to know.

First, remember we are not your customers or your VC. We do not care, or need to know, that your ultimate goal is to revolutionize the way people make tuna fish sandwiches. We do not need a PowerPoint presentation so laden with buzzwords that it is no longer comprehensible by mere mortals. Please save that information for the venture capitalists, who swoon over that sort of thing, and as a result, vomit up large quantities of money.

It seems like 98% of the potential clients we hear from insist on using the word “revolutionary” somewhere in their introductory email. Don’t get me wrong, it’s good to know that you’re enthusiastic about your product ideas. But we, as potential contractors, aren’t motivated by how revolutionary you think your idea is. We simply want to know what you need done. To this end, it would be better if someone from your development staff contacted us, rather than someone from your marketing staff.

Ultimately, we will want a functional specification to work off of. If you do not have one, we can help you create one, but we still need to know, in clear terms, what you want done. And that means never using the word “revolutionary.”

The first date

After a potential client has selected us and all the appropriate paperwork has been done, I’m ready to start. Unfortunately, I’m not always able to, because IT hasn’t setup VPN, email, access to file servers, code repositories, or whatever. I’m not sure if it’s because the group I’m working for didn’t tell IT everything they needed to know, or if IT simply doesn’t have a good process for bringing contractors on board. What I do know is that some sort of IT snafu happens just about every time.

On one contract, the original IT person did not create my account correctly (as evidenced by every subsequent IT person noting, “What the hell was this guy thinking?”). As a result, it was difficult to gain access to the servers I needed access to. Also, my VPN account was incredibly flaky, and every few weeks I had to spend some quality time with the client’s IT department getting it sorted out. This persisted the entire contract, which was more than six months long. This had an obvious impact on my effectiveness as a contractor.

Although not my first choice, I don’t mind staying on the line with the IT department, charging you my normal hourly rate, while they sort things out. However, if things are already setup by the time I start, then you don’t have to waste any money waiting for IT, and I’m not forcibly subjected to Barry Manilow’s Greatest Hits. Its a win-win.

Getting what you want

Once I start the contract, you should know what you want, and should communicate that to me. More specifically, if I’m to do feature work, there should be a specification, and I should have access to it. If I’m doing bug fixing working, there should be a bug base, and I should have access to it.

This part seems really obvious, but apparently it’s not. I should not have to contact you via phone or IM every other day, asking for a new task to work on. You should not be handing me a single task each time, and telling me to call you when I’m done with the single task. There should be a list of tasks that I can work from, which can be in the form of a spec. Otherwise, a lot of time is wasted waiting for the next assignment. (Yes, people really do this.)

I know I’ve railed about this before, but if I’m working on bugs, they should be reproducible bugs. If your QA team is not producing quality bugs, that sends a clear message to me: “This company is not serious about fixing bugs, so you, as a contractor, shouldn’t be either.” I should not have to fight with your QA to get steps to reproduce a bug. i.e. This should not happen:

Subject: Plugin crashes
Priority: Highest

Description:
The following plugins crash when I used them:
…(list of plugins)…

Comments:
Andy: What are the steps? Where in the plugins are we crashing?
QA: Various places.

That’s a paraphrased bug report from an actual QA. It crashes in “various places.” If your QA can’t be bothered to write down steps they already know, why should I be bothered to try to fix it?

Trust issues

Although not necessarily specific to managing contractors, some clients simply don’t know how to manage people.

I don’t care if you used to be an engineer, or even if you played one on TV, you shouldn’t be micromanaging me. If you’re going over every little thing I do, one of us is redundant. If it is a trust issue, then you should call me and we can work things out. Otherwise, you’re wasting both of our time, and your money.

To the other extreme, someone from your company should be available when I need them. Whether it be to ask technical questions or questions about invoices getting paid, someone should be there. It is very difficult to make progress if I need a technical question answered, and my contact promptly signs off anytime I ask them anything.

I should also note that one extreme, such as micromanaging, does not preclude the other, such as hiding. Some micromanage a single small bug fix, then disappear off of the face of the planet when I need to know where a particular resource is stored.

If you have a micromanaging manager, then that’s something you need to handle internally, as a general issue. However, when you assign a technical contact for me, make sure they are the responsive type.

Wrapping up

Hopefully if you hire a contractor, things will go well for you. Hiring a contractor is difficult because they are often an unknown. However, if you keep the above things in mind, it should increase the chances of having a good relationship with the contractor, and getting what you want. If the contract does fail, it should help assure you that the problem probably wasn’t on your side.

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.