Cocoa with Love

Creating iPhone and Mac icons using Inkscape (Part 2 of 2)

2009-11-06T22:59:00.001-08:00

In this part, I expand on the simple techniques presented in the first part by adding different line, effect and texture styles. I'll also present some Mac application icons and simple texturing.

Introduction

This series covers the creation of the following different icon styles:

The first icon was created in the first part of the series. I'll go through the creation of the remaining variations on the checkbox/checkmark theme in this post.

I'll assume that you've read the first part or are familiar with the techniques involved.

Icon 2: A brighter, more colorful iPhone icon

Goals in this section

Use a radial gradient
Learn to adjust all of the common stroke properties
Learn to adjust a multi-effect filter

The icon developed in Part 1 is very simple — really just a couple white lines over a typical iPhone icon background — which is appropriate for a serious application but might not stand out as prominently against other icons.

In this variation, I'll have the background reach a bright point behind the checkbox element and change the effect on the lines so that the lines look embossed into this bright point — visually integrating the background and the overlayed element.

I'll also introduce a complimentary (opposite hues) color scheme with an azure blue and a red.

A radial background

Starting with a 57x57 document as created in Part 1, add a rectangle filling the document area.

Set the fill to a radial fill and edit the gradient. In the Gradient Editor, click "Add Stop" twice to make the gradient a four part gradient. Top to bottom, the four gradient colors should be:

RGBA=(192,255,250,255)
RGBA=(99,164,184,255), Offset 0.26
RGBA=(5,74,119,255), Offset 0.62
RGBA=(0,40,80,255)

We now have a bright spot in the center of the background.

Over the top of this, paste (or recreate) the starburst effect from Part — X,Y=(-15.7,-15.7) should center it perfectly.

In the Fill and Stroke palette, set the opacity of the starburst to 100%.

Now, to make the starburst smoother, open the Filter Editor (from the Filters menu) and find the starburst's blur effect (it should be selected in the filter column when the starburst itself is selected). Select the Gaussian Blur effect and set the standard deviation to 0.75.

Different stroke properties for the checkbox and checkmark

Create the checkbox and checkmark in the same way that they were created in the first part or copy them in. If you copy them in, select both the checkbox and the checkmark and choose Filters→Remove Filters to remove the shadow and bevel effect applied in the first part.

Remove the corner radius from the checkbox (select it using the rectangle tool and set the Rx and Ry to zero). In the Fill and Stroke Editor, select the Stroke Style Tab and set the Line Width to 4.0 "px" and the Join Style to rounded. The result of these steps is to create a slightly thicker line that is curved on the corners within its width.

Select the checkmark and set the stroke color to RGBA=(255,42,42,255) and the stroke width to 4.0 "px".

A customized "Cutout glow"

With both checkbox and checkmark selected, choose Filters→Shadows and Glows→Cutout Glow. Go to the Filter Editor and find this Cutout Glow filter. This filter will have 5 effect rows. Select the Offset row and set the X,Y offset to (0.8,0.8). Select the Gaussian Blur row and set the Standard Deviation to 1.0.

Now follow the instructions from the "Apply the gloss effect and round corners" subsection of the previous post to complete the icon.

Icon 3: A cartoonish style

Goals in this section

Directly edit paths for greater control
See a Path Effect (Spiro Spline) in action

This variation will forego the starburst effect and instead go for a smoother, more "cartoonish" approach. The checkbox and checkmark will then need to be more distinctive as they will be the only significant graphical elements

Creating a path

Start with the background rectangle from the "brighter, more colorful iPhone icon" created above (if you created a cloned version for the round corners, don't copy the cloned version as it will behave strangely).

Select the Bezier Path tool (11th icon down in the Tool Area). We'll draw the rough loop first.

You can use the Bezier Path tool in one of two ways: simple click-and-release to create corner points and straight line segments or click and drag to create curve points (the dragging then affects the curvature of each point).

For simplicity here, I'll show you how to create the path using corner points and we'll apply the curve as a second step. When you're more comfortable with the Bezier Tool, this can be done as a single step.

Create a point at the 12 o'clock position, then 9, 6, 3 and then underneath the original 12. Then another inside the second twelve and then inside the 3, 6, 9, and between the first and second 12's. Then close the path by clicking on the first point.

Bezier path creation: If you make a mistake with the path, you can either fix it later or press escape to cancel the whole path. Pressing the return-key will end the path without closing it.

Adjusting path control point properties

Using the Node Tool (2nd icon down in the Tool Area) ensure the path you just created is selected. Drag a selection box around the nodes at 3, 6 and 9 o'clock (don't select the nodes at 12 o'clock). In the toolbar at the top, select the "Make selected nodes smooth" button (should be 8th from the left in the toolbar immediately above the window).

Applying a path effect

Leaving the path selected, choose the Path→Path Effect Editor menu item. In the Path Effect Editor palette, select "Spiro Spline" from the popup menu and click the "Add" button. The "Spiro Spline" is an effect that makes smooth curved paths much easier than regular Bezier curves.

Once this is done, you can tweak the nodes in the path (using the Node Tool) until it is the exact shape desired.

In the Fill and Stroke Editer, remove any stroke, apply a faded yellow to faded orange linear gradient fill from left to right across the checkbox loop and it is done.

Stroke to path

Create the checkmark as for the previous icons but set the Stroke Width to 6 "px" and the Style Join and Cap to square corners. With the path selected, choose the menu item Path→Stroke to Path. This will turn the line into a filled path. Set the stroke of this path to "no stroke" and set the fill to an orange to red linear gradient fill from left to right across the checkmark.

Now we need to adjust the checkmark to have a looser aesthetic. Select the Node Tool and the checkmark. Drag the lines in the short stem upwards slightly and the lines in the long stem inwards slightly. Adjust the control points at the ends of each stem so that they are flared outwards a little.

Follow the instructions from "Bevel effect and shadow" from Part 1 to apply these effects. Follow the instructions from the "Apply the gloss effect and round corners" subsection of the previous post to complete the icon.

Icon 4: A document-based Mac icon

Goals in this section

See the common components of a Mac document-based application icon
Use multiple overlapping gradients to achieve softer gradients
Add a texture to a background by filling with text

In terms of colors and effects, Mac icons tend to be far more subdued than iPhone icons. Where iPhone icons are only shown on the Home screen but are small and need to stand out, Mac icons may sit in the Dock for extended periods and shouldn't be distracting during this time.

For this reason, Mac icon colors tend to be slightly more subdued than iPhone icon colors and are frequently much lighter overall.

While Mac icons are typically larger (an average of around 64x64) they can also be shown at smaller resolutions. The approach to satisfying the size range is normally to compose the icon from two key parts:

An object or item that is easily recognizable in silhouette or at small sizes
Texture or subtler elements that fade away at smaller sizes but add structure and context at larger sizes

Mac icons must also handle a range of different background colors as they may be shown against people's desktop backgrounds, white folder backgrounds or against the near black of a vertical Dock. To achieve good contrast against the background, most icons are generally light in color but with a subtle shadow behind them — not for 3D effect but to contrast with lighter backgrounds. Many icons also incorporate a frame or boundary into the representation which further adds to the strength of the icon's silhouette.

A rotated background

To start the icon, create a 64x64 px document. This size will help us optimize for the expected screen resolution.

Into this, draw a 44 by 50 rectangle. Give it an azure to deep blue linear gradient from left to right and a white 3px stroke.

Using the Selection Tool (first in the Tool Area), select the rectangle. Initially, this will show the resizing arrows around the shape. Click a second time to switch these arrows to the rotating arrows (don't double click as that will switch to the Node Tool). Click and drag one of the corner arrows to rotate the rectangle by 8° (the rotated angle should be visible in the status bar at the bottom of the window while dragging but the exact angle isn't important).

Some effects and another gradient

On its own, a single gradient isn't a very impressive effect. The trick in making a background effect that is both attractive and subtle, is normally to layer a few different effects on top of each other.

With the rectangle selected, select "Path"→"Union". This may seem like a weird thing to do but it actually recreates the object using a path at the rotated orientation. We do this because Effects in Inkscape (like the shadow we're just about to apply) look bad (pixelated) when rotated. Recreating the object at this rotation means the effect will not have a rotation applied.

Copy and paste this rotated rectangle and put the copy next to the original. Apply a drop shadow to the original with 50% opacity, Offset of (1,1) and radius of 1.5.

Now remove the stroke from the copy. You'll notice that without the white stroke covering 1.5 px of the copy, the gradient region of the copy actually looks slightly bigger than the original. We need this shape to be the same size as the colored area of the original, so use the Selection Tool and with the rezize arrows, adjust the two to match (set the color to a flat fill like red and overlap the two objects to make it easier).

Now set the second object to have a top to bottom (parallel to its rotated axis) linear gradient fill with four color points:

RGBA=(168,247,249,255)
RGBA=(144,198,215,0), Offset 0.30
RGBA=(95,144,175,0), Offset 0.70
RGBA=(18,49,106,255)

Since this second gradient is transparent in the middle, it will show the first gradient in varying amounts through the middle. Overlapping the two should result in a softer gradient that vaguely resembles diffuse lighting across a slightly convex surface.

A light text-based texture

The formatting of the following paragraph is not an mistake.

The Text Tool is two icons above the Gradient Tool. Click on the document to create a text object and type the text shown and formatted as above. With the text object selected, choose the Zapfino font from the font popup menu in the top toolbar. I like Zapfino because when zoomed out, it seems ornate and indistinct.

Now use the Selection Tool to scale and position the text object over the other gradient rectangles.

To add a gloss effect over everything, create a 53 by 28 rectangle, with a flat RGBA=(255,255,255,60) fill and no stroke and rotate and position it over the top half of the existing shapes.

The "representative" element

For the representative element, I'll use a checkmark in an orange circle. Create a checkmark line (same as in previous icons) set a white 5 px stroke on the checkmark.

Create a 43 by 43 circle (unlike the Rectangle Tool, you can't specify the size of a circle with the Circle Tool selected. If you want to do this, you'll need to use the Selection Tool). Set a red-orange to yellow-orange radial gradient on the object and no stroke.

Using the Gradient Tool, drag the center control point of the gradient to the bottom-right corner of the circle's bounding box, the endpoint of the horizontal stem to the bottom-left corner and the vertical endpoint to the top-right corner.

With the circle selected, use the menu item Filters→ABCs→Diffuse Light. Then use the Filter Editor to set the Gaussian Blur effect of this filter to a Standard Deviation of 1.0. Then apply a drop shadow to the circle.

Finally, position everything together and the icon is complete.

Icon 5: A circular Mac icon

Goals in this section

See the common components of a Mac "appliance" application icon
Apply effects to a path to make the boundary shape more interesting and more distinct from the background
Create a texture using an effect

A circular icon is constructed in the same way as a rectangular backed icon. The only significant differences are:

gradients tend to be various kinds of radial gradient to give a convex feel to the round shape
the overlayed element will be more centered so it helps if it is less solid (thinner and lighter)

Compose a round icon

Since you've seen how to put together basic shapes and radial fills before, I'll just show you the components I used to create this icon as a graphic:

Notice how bright the elements all are: Mac icons are normally quite bright — you want to avoid a "muddy" effect with too many dark colors.

When composing elements, if one of them is at the wrong depth (overlaps other objects wrong) you can change the depth by selecting the object and using the Page Up/Page Down keys (or by using the "Object"→"Raise"/"Lower" menu items).

Make the checkmark look interesting

The checkmark must stand alone in this icon, which means that it should have a few special effects applied to it so that it doesn't look sterile and boring. I applied the following effects to the checkmark:

Filters→Non-realistic 3D shaders→Comics
Filters→Shadows and Glows→Inner Glow. For this filter, I changed the Flood color to a medium blue and reduced the Gaussian Blur (now the second blur in the Effects list for this object after the Comics blur from the previous effect) to a Standard Deviation of 1.0.
A drop shadow.

To texture the circle, I used the RGBA=(176,112,42,140) circle (middle element shown above) and applied a Filters→Image effects, transparent→Marbled ink effect. This gives a slightly moon cratered look that matches the somewhat planetoid shape of the object.

Conclusion

You can download an Inkscape SVG file containing all the icons and their compositions (482kB).

This two part series has been outside the normal domain of programming information that I provide. However, applications programmers will regularly find themselves needing to create, edit or adjust artwork-related assets in their applications. I hope I've given some useful tips on the way artwork assets are composed and ways you can make your artwork look good, even if it is very simple.

With iPhone or Mac icons, they are typically composed from the same elements:

A background gradient (or two).
A texture or additional effect.
A gloss or lighting highlight.
A foreground element or symbol representing your application which, after the other elements are applied, need only be very simple.

With gradients and effects, it is helpful to use a few so that your icon seems rich on close inspection but to keep each one very subtle since they shouldn't distract or make the icon harder to perceive (in a quick glance, the user shouldn't even see the effects you've added).

Icons do not need to be complex; the most professional icons are often very basic. Lack of artistic skill need not be a hinderance if you keep it simple.

Creating iPhone and Mac icons using Inkscape (Part 1 of 2)

2009-11-03T01:17:00.001-08:00

In this two part series, I'll give a beginner's guide to creating iPhone and Mac application icons using Inkscape — a free, vector illustration program. In this first part, I'll talk about the common styles and traits of icons on the Mac and iPhone and give a step-by-step guide to creating the first iPhone icon in Inkscape.

Introduction

This series will cover the creation of the following different icons:

Only the first icon will be created in this part. The remaining four will be covered in the second part.

It may seem strange to be covering icon creation in a Cocoa programming blog but the icon is an important part of an application and Cocoa is primarily an application programming environment. While larger development teams have dedicated graphic artists to create icons and other artwork assets, the reality is that on smaller teams or on solo projects, a programmer may need to create icons themselves.

The goal of this series is to show non-graphics professionals how to create graphics of an acceptable level for their applications that follow the established visual trends for iPhone and Mac apps.

A vector approach

This post is partly a response to Elite By Design's "Design The iTunes Icon For The iPhone And iPod Touch" which produced an iTunes-style icon at 125x125 pixels in Photoshop.

I wanted to show an alternative approach to the one suggested in that article. This alternative approach has the following advantages:

Entirely vector artwork, so it will scale from 57x57 pixels up to 512x512 pixels as required for App Store submissions.
Rounded corners and gloss are applied to a separate clone of the base artwork so the submission to Apple can be non-prerendered if you choose.
Created using free software as non-professional artists don't always have access to Photoshop.

In addition to detailing iPhone icon creation, the second part will also cover basic Mac icon design.

Established styles

I continue to be surprised when I look at screenshots of the Windows 7 taskbar.

These are the first four icons that a Windows 7 user sees and they are the strangest collection of graphics I've ever seen. They share no obvious visual style; they are all drawn with different perspective, they all have different weights, some are glossy while others are matte, some have line edges while others are self-edged (no lines) and they don't share a color palette.

Icon styles on the Mac

By contrast, icons on the Mac tend to have more in common:

Ignoring the "Finder" icon (which is actually the "Mac OS" icon and predates Mac OS X by about 5 years), these icons come in three distinct styles:

Document applications (rectangular background angled 5-10° left).
Appliance applications (round — or at least non-rectangular — background).
Utilities (orthogonal rectangular background).

Originally, Apple had the guideline that utilities should look like they were "items sitting on a shelf" but only the disk utitilies still follow that guideline.

In addition to these three categories, the icons tend to:

Have approximately the same weight (fill roughly the same amount of their visual area).
Use soft gradients, sometimes (but not always) with a light gloss or highlight.
Use a generally bright but slightly desaturated palette of grays, azure blues, desaturated reds and sandy yellows (utility apps tend to use more blacks and darker colors).
Indicate their function or concept with an overlayed or nested element.
Are self-edged and have almost no internal lines (the outline of the icon is sometimes edged for contrast)

Of course, none of these are immutable but following them will make it easier to create a simple icon that looks like it belongs on the Mac.

Icon styles on the iPhone

The iPhone has a style that is distinct from the Mac:

Aside from the obvious round cornered background and top-down gloss effect, iPhone icons tend to use:

Strongly saturated colors
A bright gradient or colorburst in the background
White silhouetted representative elements over the background

There is certainly variation and some icons that follow their own rules entirely (the "Notes" and "App Store" icons have little in common other than the rounded corners) but the easiest path to creating an icon that looks like it belongs on the iPhone is to incorporate these elements.

Inkscape

The tool that I will use to create the icons is Inkscape. Inkscape is a GPL-licensed SVG-based vector illustration program that you can download from inkscape.org. It is available in a Universal binary for Mac OS X 10.3.9 and newer.

A nice multi-purpose icon but clearly not designed with "standard Mac app" as its primary goal.

You will need X11 installed and pre-Snow Leopard users will need an updated version of X11 (download new versions from here: http://xquartz.macosforge.org/).

Yes, Inkscape is an X11 program, which means that Open/Save dialogs are non-standard, windows may not come to the front when you expect them too and keyboard shortcuts are all Control-X instead of Command-X. Despite this, Inkscape is generally a good program — certainly far better than most X11 applications on the Mac.

If you prefer a different illustration program, most of the techniques in this guide will apply. The Filter Effects and the Path Effects are probably the points that will be most different but I'm sure you can find alternatives.

Page area

Let's start with a blank document in Inkscape.

A new document will appear when you start Inkscape or you can create a new document from the "File"→"New"→"Default" menu.

Go to the "File"→"Document Properties". Set the Default Units to "px" and the custom document size to 57 by 57.

The reason why we set the units and use the actual pixel sizes in a vector program is this will let us align points to whole value boundaries and avoid unnecessary anti-aliasing. For example, drawing a shape with its edge at Y=0.5 will cause the actual shape border to anti-alias across two different pixels when we render at 57x57 pixels but if we set the shape border's Y coordinates to 1.0, it won't have this problem.

The page area will now look tiny in the window. You can zoom in using the middle mouse button (click and drag with the middle mouse button to pan) or the "+" key. Alternately, you can zoom the document area to fill the window by pressing the "5" key.

Zooming: you will need to be comfortable with zooming in the program. The "+" and "-" keys will zoom in and out at any time. The 3 key will zoom to the selection and 4 will show all drawn elements. Clicking and dragging the middle mouse button will pan the document, clicking the middle mouse button will zoom and shift-middle mouse will zoom out.

Creating the glossy round rectangle

The Tool Area is the column of buttons down the left side of the window. The 5th tool from the top is the rectangle tool.

Red round rectangle

Using the rectangle tool, drag out a rectangle to fill the document area.

Open the Fill and Stroke palette (menu item "Object"→"Fill and Stroke" or Control-Shift-F). With the rectangle we created selected in the window, select the Stroke tab of the Fill and Stroke Palette. Make certain there is no stroke (the "X" icon should be selected). Select the Fill tab of the palette. Set a solid color fill (the solid square icon) and use the sliders to set a bright red fill (this is just so that we can see the shape easily).

Quick colors: you can also set solid fill and stroke colors on the selected object by left clicking (fill) or shift-left-clicking (stroke) a swatch at the bottom of the window.

We now need to edit the rectangle properties. Using the rectangle tool again, click the rectangle to select it (if it isn't already selected). In rectangle edit mode, a toolbar will appear at the top of the window labelled "Change" with coordinates "W", "H", "Rx" and "Ry". Set the "W" and "H" to 57 — this will make the rectangle exactly 57 pixels wide and high (if the rectangle auto-locked to the edges of the document, these values may already be set). Set the "Rx" and "Ry" to 10 — this will set the corner radii to 10 (a round rect).

Numerical accuracy: I'm going to quote a lot of coordinates and color values in this post but this is only so I can communicate what I'm doing. Most of the time, you do not need to be pixel accurate and can do things more approximately if you prefer.

Using the selection tool (the first tool in the Tool Area) select the rectangle. The object's "X" and "Y" coordinates will appear in the toolbar at the top. Set these to zero. The rectangle is now exactly the size of the document with round corners.

The gloss round rectangle

Copy the red round rectangle object (select it and press Control-C) and paste it (Control-V) somewhere else (when pasted, the object will be centered where the mouse is, so place the mouse over a different part of the document).

Copy and Paste bug: if the Copy and Paste fails (you get a bitmap instead of a proper editable object or nothing seems to happen), then you may be seeing a bug in Inkscape due to recent X11 changes. To work around this bug, go to the X11 preferences and on the Pasteboard tab, disable "Update Pasteboard when CLIPBOARD changes". Alternatively, you can use "Edit"→"Duplicate" to duplicate without copying.

With the copy selected, go to the Fill tab of the Fill and Stroke palette. Set a radial fill for the object (4th icon from the left at the top). If you've set the red color, then the radial gradient will initially look like a red dot fading outwards.

Click the "Edit" button in the Fill tab to edit the gradient. In the "Gradient Editor" that appears, the popup menu at the top will contain two items (the opaque red color and the fully transparent red color). Hit the "Add Stop" button twice to add two extra items in the gradient.

Edit the topmost item in the list of colors (the opaque red color) and set it to white with an alpha value of 86. Set the second item to white with an alpha of 75. Set the third to black with an alpha of 60. Set the final item to white aith an alpha of 0.

You also need to set the offset of the two middle colors. The black color should have an offset of 0.63. The white color should have an offset of 0.62.

This round rectangle should now look like a faint gray donut. Select it and set its "X" and "Y" coordinates to (0,0) (so that it perfectly overlaps the original red round rectangle).

With the faint gray donut selected, choose the Gradient Tool (second last in the Tool Area — if your vertical screen resolution isn't very high, you may need to select the Gradient Tool from the popup menu at the bottom of the Tool Area). An "L" shape of control points should appear over the donut.

Drag the control point that appears in the middle of the donut to the middle of the top edge of the round rect (it should lock onto the point with the text "Handle to bounding box").

Drag the round control point at the end of the horizontal arm of the "L" to X=-50. You can see the "X" value of the cursor at the bottom right of the window. Hold down the "Control" key while doing this to ensure that the "Y" value remains the same. Similarly, drag the round control point at the end of the vertical arm to Y=12.

On the Stroke tab of the Fill and Stroke palette, set a linear gradient stroke (third icon from the left at the top) for the gloss object. On the Stroke Style tab, set the line width to 1.0 px.

On the Stroke tab, edit the gradient. Set the start color to white and the end color to RGBA=(255,255,255,0). Using the Gradient Tool, select the gloss object. There should now be an extra set of control points in a horizontal line across the middle of the object corresponding to the stroke's gradient. Drag the start point of this line (square control point) to the top right corner of the object and the end point of the line (circular control point) to a position three quarters the way up the right-hand side of the object.

Since the stroke added to the gloss object changed the size of the object, you will need to re-set the size of the gloss object to 57x57 at X,Y=(0,0).

You should now have a glossy red round rectangle in the style of an iPhone icon. If you know what you're doing in Inkscape, you can move these objects to another layer and hide them now however, it's probably easiest just to save this document and copy these objects when they are needed later.

The first iPhone icon

Blue-green background

Create a 57 by 57 rectangle at X,Y=(0,0) again, using the same approach as the red rectangle from the previous section but leave the corners square (you may need to explicitly set Rx and Ry to zero since it may remember the radius from before).

Set the fill of this rectangle to a linear gradient (third icon from the left at the top of the Fill tab in the Fill and Stroke palette). Edit the gradient and set the start point to RGBA=(15,112,126,255) and the end point to RGBA=(0,0,53,255).

Using the Gradient Tool from the Tool Area, select the rectangle and drag the gradient starting point (the square control point) to the center of the bottom edge of the rectangle. Drag the gradient end point (the round control point) to the center of the top edge of the rectangle.

Gradient colors: almost every gradient you use should involve a hue shift. When you want an actual 3D or lighting effect, you can also apply a luminance shift. The gradient here shifts from blue into the green direction as it lightens (a common choice). The other most common gradient would probably be from a darker red or orange towards a lighter yellowy orange. Hues on the green side of yellow or purple hues are rarely ever used.

Starburst object

Now, using the Stars and Polygons tool from the Tool Area (8th from the top) and drag out a shape (it will probably appear as a 5 point star — if it isn't a star, click the star icon in the top toolbar). With the Stars and Polygons tool and the object still selected, you should be able to edit the properties of the star. Set the number of corners to 350, the spoke ratio to 0.3 and the Randomized property to 0.015. Choose the Select and Transform tool (first tool in the Tool Area) and select the star. You can now set the width and height both to 87 and the X,Y to (-15,-15).

In the Fill and Stoke palette, set the opacity of the star to 50%.

Then, set a radial fill on the star from a start color of RGBA=(255,255,255,0) to an end color of RGBA=(0,235,255,255). This radial gradient fades out in the middle which will help the checkbox stand out from the background more.

A blur effect on the starburst

With the star object still selected, select the menu item "Filters"→"ABCs"→"Simple Blur". Then select the "Filters"→"Filter Editor..." menu item. This will display the Filter Editor palette.

Space limitations: If the Fill and Stroke Palette is still showing when the Filter Editor appears, you'll notice that they don't fit well together down the right margin. I recommend you either close the Fill and Stroke Editor or drag the Filter Editor off into its own window.

There should be one filter listed in the list of filters — this is the filter you just created. When you select the filter in the list, the Effect "Gaussian Blur" will appear in the Effect column at the right. Select the Gaussian Blur and the "Effect Parameters" tab will appear at the bottom. Set the "Standard Deviation" to 0.25.

You can also apply "Blur" using the Fill and Stroke palette. The blur radius at the bottom of this palette is 2.74 times the Standard Deviation applied here (no, I'm not really sure why the difference is 2.74 times).

The checkbox and checkmark objects

Now create a 29x29 round rectangle with corner radius 4 at X,Y=(14,14). This is the checkbox. This time, set no fill (the "X" icon on the Fill tab of the Fill and Stroke palette) and set a plain stroke (second icon from the left at the top of the Stroke tab) with a white color. On the "Stroke Style" tab, set the width to 3.0 "px". While here, set the "Cap" to round. It won't matter as much for this object, but we're just about to draw a line and we want it to have round endcaps.

Select the Bezier Line tool (11th icon down in the Tool Area). Click the mouse and release to create points at X,Y = (19.5,30), (28.5,20) and (47,48). Press the return key when done to finish the path. This is the checkmark. Now select the Node Tool (second icon from the top of the Tool Area) and select the checkmark. Click and hold the mouse in the middle of each line segment and drag up slightly to give the lines a slight curve. You can use the control points to tweak the effect if you're not happy.

Bevel effect and shadow

Select the checkmark and the checkbox. From the Filters menu select "Bevels"→"Ridged Border". Then from the Filters menu select "Shadows and Glows"→"Drop Shadow", set the blur to 2.0, the opacity to 35%, the offset to (3,3), hit the "Apply" button and close the Drop shadow dialog.

Speed tip: when zoomed in on objects using effects, the rendering can get slow. To disable effects or to drop entirely into wireframe mode, choose "No Filters" or "Outline" from the "View"→"Display Mode" menu or press Control-Keypad5. The "Ridged border" effect is especially slow in the current version of Inkscape — I recommend zooming out before you apply it and turning effects off before you zoom in close.

If you want to fully integrate the checkmark and the checkbox, you can convert the checkbox object to a path, the checkmark stroke to a path and then create a union of the two. I'll leave that to you if you're interested.

Apply the gloss effect and round corners

Select the green gradient background, the starburst, the checkbox and the checkmark and group them all together (Control-G or menu "Object"→"Group"). This will let you select them all in one go (ungroup with Control-Shift-G or double-click the group to select objects within the group without ungrouping).

With the group selected, from the Edit menu select "Clone"→"Create Clone". This will create a copy that continues to update when the original updates. Move the clone to X,Y=(-115.7,-15.7) (this coordinate include extra padding of approximately 2.74 times the starburst's blur standard deviation of 0.25 which is the amount that a blur will expand an object's boundary).

Now we need the red glossy round rectangle. If you saved them in a different document, copy them into this document now. Select the red background and gloss (drag a rectangle around both using the Selection Tool) and set the X,Y coordinates of the two of them to (100,0). This may make the two objects hidden behind the cloned group objects so press the "Home" key (or select Raise to Top from the Object menu).

Drag the gloss and the red rectangle off of the objects they are covering (it doesn't matter where you put them). Select the cloned group and the red round rectangle but not the gloss gradient. Undo the two object moves. This should leave the cloned objects and the red round rectangle selected but all of the objects on top of each other. From the Object menu, select "Clip"→"Set". This should clip the cloned group to the boundary of the red round rectangle, and make the red round rectangle disappear.

Clipping: when clipping in Inkscape, the topmost object is always used as the clipping boundary and all other selected objects are clipped to its boundary.

Export the bitmap

Congratulations, your iPhone icon is complete.

You can export the prerendered (cloned, glossed and rounded) version to a PNG by selecting the gloss gradient that's over the clipped shape and selecting "Export Bitmap" from the "File" menu. Make sure that "Selection" is highlighted in the window that appears and set the width and height of the exported image to whatever size you want. Use the Browse button to select a location then hit the export button.

If you want to send the non-prerendered version to Apple, then select the uncloned group and export from that. 57x57 for the application icon and 512x512 for the high resolution version in your App Store submission.

Resampling: You may get a better effect on the small icon if you export at a larger size and use another program (Preview, GIMP, etc) to scale it down. This may give better anti-aliasing performance — particularly if your resizing program uses Lanczos resampling.

If you'd like your icon as a PDF, SVG or a number of other vector graphics types, you can choose "Save As..." and save to the format of your choice.

Conclusion

You can download an Inkscape SVG file containing the final icon (122kb). Note: Safari and other programs will open SVG files but the effects (shadows, blurs, etc) will only appear if the SVG is opened in Inkscape.

In the second part, I will go through the steps for other icons, showing different stylistic options and explaining more of the effects and graphical elements you can use to create your icons. I'll look closer at filter effects in Inkscape, creating more sophisticated line paths, using gradients in multiple directions to achieve softer effects and creating simple textures to fill blank areas.

Memory and thread-safe custom property methods

2009-10-25T04:26:00.001-07:00

Objective-2.0 property methods are a nice convenience but if you need to override a property implementation — particularly an atomic, retained or copied object setter property — there are some potential bugs you can create if you don't follow the rules carefully. I'll show you the pitfalls and the correct way to implement a property accessor. I'll also show a way to directly invoke hidden runtime functions to let Objective-C perform atomic getting and setting safely for you.

Custom getter and setter methods for implicitly atomic types

For implicitly atomic types or for types where memory management doesn't apply, custom getter and setter methods in Objective-C are easy. These "easy" situations include:

Basic value types (char, short, int, float, long, double, etc).
Objective-C objects in a garbage collected environment
Assigned (non-retained) pointers

For these types, it is pretty hard to get a custom getter or setter method wrong. For the following property declaration:

@property SomeAtomicType somePropertyVariable;

the custom getter and setter simply look like this:

- (SomeAtomicType)somePropertyVariable
{
    return somePropertyVariable;
}
- (void)setSomePropertyVariable:(SomeAtomicType)aValue
{
    somePropertyVariable = aValue;
}

Common mistakes in accessor methods for non-atomic types

Non-atomic types require greater care. These types include:

Objective-C objects in a manually managed memory environment
structs and other compound types

Given how simple custom getter and setter methods are for atomic types, it is easy to be complacent about implementing methods for these types. However, following the wrong approach can lead to memory crash bugs and lack of proper thread safety.

To illustrate how simple it can be to introduce bugs while implementing a custom setter method, consider the following declared property:

@property NSString (copy) someString;

A hasty implementation of the setter might be:

- (void)setSomeString:(NSString *)aString
{
    [someString release];
    someString = [aString copy];
}

This implementation actually contains two bugs:

This method is not atomic.
The someString object changes twice: once on release and again when it is assigned the copied object's address. This method is not atomic and therefore violates the declaration (which omits the nonatomic keyword and therefore requires atomicity).
The assignment contains a potential memory deallocation bug.
If someString is ever assigned its own value, it will release it before copying it, causing potential use of a released variable. The code: self.someString = someString; is an example of this potential issue.

Don't feel too bad if you've ever made these mistakes. I spent some time looking at clang's synthesized method implementations when I was researching this post and I noticed that they've forgotten to handle struct accessor methods in an atomic manner when required.

Safe implementations of custom accessor methods for non-atomic types

To address this second issue, Apple's Declared Properties documentation suggests that your setter methods should look like this:

- (void)setSomeString:(NSString *)aString
{
    if (someString != aString)
    {
        [someString release];
        someString = [aString copy];
    }
}

This only fixes the memory issue, it doesn't fix the atomicity issue. To handle that, the only simple solution is to used a @synchronized section:

- (void)setSomeString:(NSString *)aString
{
    @synchronized(self)
    {
        if (someString != aString)
        {
            [someString release];
            someString = [aString copy];
        }
    }
}

This approach will also work for retain properties as well (simply replace the copy method with a retain.

To maintain atomicity, you also need a retain/autorelease pattern and lock on any getter methods too:

- (NSString *)someString
{
    @synchronized(self)
    {
        id result = [someString retain];
    }
    return [result autorelease];
}

The @synchronized section is only required around the retain since that will prevent a setter releasing the value before we can return it (the autorelease is then safely done outside the section).

For struct and other compound data types, we don't need to retain or copy, so only the @synchronized section is required:

- (NSRect)someRect
{
    @synchronized(self)
    {
        return someRect;
    }
}
- (void)setSomeRect:(NSRect)aRect
{
    @synchronized(self)
    {
        someRect = aRect;
    }
}

A faster, shorter way to implement custom accessors

There are two negative points to the custom accessor methods listed above:

They need to be coded exactly to avoid bugs.
The @synchronized section on self is coarse-grained and slow.

There is another way to implement these methods that doesn't require as much careful coding and uses much more efficient locking: use the same functions that the synthesized methods use.

The following functions are implemented in the Objective-C runtime:

id objc_getProperty(id self, SEL _cmd, ptrdiff_t offset, BOOL atomic);
void objc_setProperty(id self, SEL _cmd, ptrdiff_t offset, id newValue, BOOL atomic,
    BOOL shouldCopy);
void objc_copyStruct(void *dest, const void *src, ptrdiff_t size, BOOL atomic,
    BOOL hasStrong);

While these functions are implemented in the runtime, they are not declared, so if you want to use them, you must declare them yourself (the compiler will then find their definitions when you compile).

These methods are much faster than using a @synchronized section on the whole object because (as shown in their Apple opensource implementation) they use a finely grained, instance variable only spin lock for concurrent access (although the copy struct function uses two locks following an interface design mixup).

When you declare these functions, you can also declare the following convenience macros:

#define AtomicRetainedSetToFrom(dest, source) \
    objc_setProperty(self, _cmd, (ptrdiff_t)(&dest) - (ptrdiff_t)(self), source, YES, NO)
#define AtomicCopiedSetToFrom(dest, source) \
    objc_setProperty(self, _cmd, (ptrdiff_t)(&dest) - (ptrdiff_t)(self), source, YES, YES)
#define AtomicAutoreleasedGet(source) \
    objc_getProperty(self, _cmd, (ptrdiff_t)(&source) - (ptrdiff_t)(self), YES)
#define AtomicStructToFrom(dest, source) \
    objc_copyStruct(&dest, &source, sizeof(__typeof__(source)), YES, NO)

I like to include the "To/From" words so I can remember the ordering of the source and destination parameters. You can remove them if they bother you.

With these macros, the someString "copy" getter and setter methods above would become:

- (NSString *)someString
{
    return AtomicAutoreleasedGet(someString);
}
- (void)setSomeString:(NSString *)aString
{
    AtomicCopiedSetToFrom(someString, aString);
}

and the someRect accessor methods shown above would become:

- (NSRect)someRect
{
    NSRect result;
    AtomicStructToFrom(result, someRect);
    return result;
}
- (void)setSomeRect:(NSRect)aRect
{
    AtomicStructToFrom(someRect, aRect);
}

Conclusion

Most of the accessor methods I've shown here are atomic but in reality, most Objective-C object accessors are declared nonatomic.

Even if your properties are declared nonatomic, the memory management rules still apply. These rules are important to follow since they can lead to some very obscure and hard to track down memory bugs.

The macros I've provided are all for atomic properties. For non-atomic properties the boilerplate assignment code is probably simple enough to remember. If not, you could also use a macro:

#define NonatomicRetainedSetToFrom(a, b) do{if(a!=b){[a release];a=[b retain];}}while(0)
#define NonatomicCopySetToFrom(a, b) do{if(a!=b){[a release];a=[b copy];}}while(0)

Update: following comments below, I realize I omitted to qualify the situations in which these accessors are thread-safe. Specifically:

These setter methods are only thread-safe if the parameters passed to them are immutable. For mutable parameters, you may need to ensure thread safety between mutations on the parameter and the assignment of the property.
Atomic accessors only provide thread safety to an instance variable if they are the sole way you access the instance variable. If non-property access is required, you must ensure shared thread safety between property accessor methods and the non-property access.
Atomic assignment for the "implicitly atomic" types I listed does not mean that all CPUs/cores see the same thing (since each CPU/core could have its own cache of the value) — it only ensures that value is wholly set without possibility of interruption. If you require all CPUs/core to be synchronized and see the same value at a given moment, then even the "implicitly atomic" types may require volatile qualifiers or a @synchronized section around the assignment to flush caches.

How blocks are implemented (and the consequences)

2009-10-18T02:12:00.001-07:00

This post is a look at how clang implements blocks and how this implementation leads to a number of strange behaviors including local variables that end up global, Objective-C objects allocated on the stack instead of the heap, C variables that behave like C++ references, Objective-C objects in non-Objective-C languages, copy methods that don't copy and retain methods that don't retain.

What blocks are to the compiler

Blocks are addressable sections of code implemented inline (inside other functions). The inline-edness can be convenient but the real reason why blocks are different to regular functions and function pointers is that they can reference local variables from the scope of the function surrounding their implementation without the invoker of the block needing to know of the surrounding scope variables' existence.

A block is implemented internally using two pieces:

compiled code in the .text segment of the executable
a data structure that predominantly contains the values of the variables that the block uses from its surrounding scope

The compiled code lives in its own separate location and does not actually reside inside inside the code of its surrounding scope. In implementation, the code is a function like any other. If you run:

otool -tV MyCompiledExecutable

then you'll see your blocks appearing immediately after their surrounding functions with names like ___surroundingFunction_block_invoke_21.

So it is not the code which makes blocks special, it is the separate data structure. It is this data structure that I will focus on for the remainder of this post.

The block data structure

Clang's basic documentation on block implementations indicates that the data structure describing the block looks something like this:

struct Block_literal {
    void *isa;

    int flags;
    int reserved; // is actually the retain count of heap allocated blocks

    void (*invoke)(void *, ...); // a pointer to the block's compiled code

    struct Block_descriptor {
        unsigned long int reserved; // always nil
        unsigned long int size; // size of the entire Block_literal
        
        // functions used to copy and dispose of the block (if needed)
        void (*copy_helper)(void *dst, void *src);
        void (*dispose_helper)(void *src); 
    } *descriptor;

    // Here the struct contains one entry for every surrounding scope variable.
    // For non-pointers, these entries are the actual const values of the variables.
    // For pointers, there are a range of possibilities (__block pointer,
    // object pointer, weak pointer, ordinary pointer)
};

Of course, the reality is that this structure is never explicitly declared like this in clang. Clang is a compiler — a code generator — and the format of this structure is generated programmatically from the CodeGenFunction::BuildBlockLiteralTmp method.

Stack blocks and global blocks

Since the biggest difference between a function pointer and a block is the ability to use variables from the surrounding scope, it is interesting to look at what happens when a block does not reference anything in the surrounding scope.

Normally, the Block_literal data appears on the stack (like a regular struct would in its surrounding function). With no references to the surrounding scope, clang configures the Block_literal as a global block instead. This causes the block to appear in a fixed global location instead of on the stack (the flags value has the BLOCK_IS_GLOBAL flag set to indicate this at runtime but it's not immediately clear to me if this is ever used).

The implication of this is that global blocks are never actually copied or disposed, even if you invoke the functions to do so. This optimisation is possible because without any references to the surrounding scope, no part of the block (neither its code nor its Block_literal) will ever change — it becomes a shared constant value.

Blocks are always objects

If you're familiar with how Objective-C objects are declared, the isa field in the Block_literal above should be familiar — blocks are Objective-C objects. This may not seem strange in Objective-C but the reality is that even in pure C or C++, blocks are still Objective-C objects and the runtime support for blocks handles the retain/release/copy behaviors for the block in an Objective-C messaging manner.

Clang uses the class names _NSConcreteStackBlock and _NSConcreteGlobalBlock to refer to the classes for block literals but in CoreFoundation projects, this will map onto NSStackBlock and NSGlobalBlock. If you copy an NSStackBlock, it will return an NSMallocBlock (indicating its changed allocation location).

Blocks are slightly weird objects

The interesting point to note about NSStackBlock is that it is a stack allocated Objective-C object. If you have ever tried to allocate an Objective-C object on the stack (not as a pointer but statically allocated) you'll know that the compiler normally forbids this.

The reason why blocks are placed on the stack by default is speed. In the common case where the lifetime of the block is less than that of the stack function that contains it, this is a very good optimisation.

The implication of stack blocks being allocated on the stack, is that a stack block cannot simply be retained — it will become invalid once the function that contains it is popped from the stack. If you invoke retain on a stack block, it will have no effect (the retain count of the block will remain at 1).

For this reason, if you need to return a block from a function or method, you must [[block copy] autorelease] it, not simply [[block retain] autorelease] it.

__block values can move magically

Scope variables used in a block are normally passed to the block by const value (the compiler won't let you change the value but even if it did, the change wouldn't affect the value of the variable outside the block).

To alter this behavior, the type specifier __block was added. Any variable declared __block is passed by reference into the block (value on the outside will be changed after the block is invoked).

In the implementation, __block variables are initially allocated on the stack but if any block which references them is copied, they are moved onto the heap (malloced). This leads to the following strange situation...

int (^function())()
{
    __block int x = 0;
    
    int (^block)() = ^{
        x += 1;
        return x;
    };
    
    NSLog(@"x's location is on the stack: %p", &x);
    block = [[block copy] autorelease];
    NSLog(@"x's location is now on the heap: %p", &x);
    
    return block;
}

In this example, x's address changes when the copy is invoked. This is because when we declare a __block variable, a pointer to the real variable is created and any attempt to use the variable dereferences it. When copy is invoked, the location pointed to by the pointer changes to the new heap location, so any use of x causes a dereference to this new location.

This makes __block similar to to a reference parameter in C++ since C++ references are also transparently dereferenced pointers.

NSMallocBlock never actually copies

Copying a block doesn't really give you a copy of the block — if the block is already an NSMallocBlock, a copy simply increases the retain count of the block (this retain count is an internal reserved field — the retainCount returned from the object will remain at 1). This is perfectly appropriate since the scope of the block cannot change after it is created (therefore the block is constant) but it does mean that invoking copy on a block is not the same thing as recreating it.

Assume the following code is in the same program as the previous example.

int (^someBlock)() = counterBlock();
int (^someBlockCopy)() = [[someBlock copy] autorelease];
int (^anotherBlock)() = counterBlock();

The block returned from counterBlock() counts the number of times that it is invoked by saving the count in the __block variable x.

In this example though, someBlock and someBlockCopy share the same x variable — they are not actually separate copies. However, anotherBlock does have its own separate x value.

If you need a genuinely separate copy, recreate the block, don't copy it.

Blocks retain their NSObject scope variables

Blocks will retain any NSObject that they use from their enclosing scope when they are copied.

The biggest implication of this is that you must remember to avoid retain cycles if the block will be held beyond a simple stack lifetime.

A pointed out elsewhere, you can suppress this retain of NSObjects by assigning the object to a __block variable outside the block and only ever using the __block variable inside the block.

You can also do the reverse of this and force a pointer that isn't an NSObject derived class to be retained when copied. Do this by declaring the pointer with __attribute__((NSObject)). Of course, the situations where you'd want to do this are exceedingly rare.

Conclusion

Blocks are very simple to use in the case where you declare one inline and immediately pass into another function but once you need to copy or hold onto a block for a while, there are a number of quirks, some of which I've covered in this post.

Sadly at this time, Apple's documentation on blocks is fairly basic and lacking in detail. This is what led me to start looking at clang's source code.

Of course, you don't need to stare at someone else's C++ code to learn about blocks. There are other sources of lighter, more approachable documentation on the topic. In addition to sources that I've already linked, there's also:

Mike Ash's colorfully titled "Friday Q&A 2008-12-26" — an excellent run-down of potential use-cases for blocks in Objective-C.
Joachim Bengtsson's Programming with C Blocks — a good general summary of most aspects of blocks
Jim Dovey's Blocks Episode 2: Life Cycles — a look at stack and heap allocation of blocks with diagrams
clang's BlockLanguageSpec

Objective-C's niche: why it survives in a world of alternatives

2009-10-12T01:47:00.001-07:00

Objective-C remains an impediment for many programmers coming to the Mac or iPhone platforms — few programmers have ever experienced it before learning Cocoa, forcing two learning curves at once for new Cocoa developers. How did Apple end up with such a weird language? And for a company known to replace CPU architectures and their entire operating system, why does Apple persist with Objective-C? The answer lies in the methods.

Virtual methods

Most compiled, object-oriented languages (like C++, Java and C♯) adhere closely to the object-oriented approaches first introduced in Simula 67 — in particular the concept of virtual methods and how they enable methods to be overridden.

Origins in Algol: In much the same way that Objective-C is often called a "pure superset" of C, Simula 67 was a "pure superset" of Algol 60. While Fortran is sometimes remembered as the first high-level language to gain popularity (and disdain), Algol 60 was the first programming language to actually resemble a modern language as it contained the for, if/else, while, return and other procedural contructs that are expected now in programming languages. While Algol was rarely used past the 1970's, Pascal and its descendants closely resemble Algol in syntax.

In a compiled language, a regular function (non-overrideable) ends up as a basic memory address. When the function is invoked, the CPU jumps to the memory address.

Simula 67 introduced virtual method tables to adapt this for object-orientation. Instead of basic memory addresses, methods are compiled to row numbers in a table. To get the memory address, the method table is retrieved from the class of the object and the CPU jumps to the address at the specified row.

Since different objects have different classes, they will have different addresses in their method tables, hereby allowing sublcasses to have different implementations of methods (method overrides) to their base classes.

Message passing

While virtual method tables do introduce a level of indirection that allows method behavior to change from object to object, the offsets into the table and hence the tables themselves all need to be created at compile-time.

History of message passing: As with object-orientation itself, message passing was inspired by Simula 67 but Simula's message passing (called "Simulation") wasn't for method invocations — it was instead used for discrete event simulation (mostly queueing and list processing). Smalltalk expanded upon this idea by using message passing for method invocation. Smalltalk subsequently inspired the Actor Model (used in distributed processing) and remote procedure calls (RPC). Originally, Smalltalk messages were conceived to have a large amount of metadata (more like the full headers on an email) but eventually, this was simplified down to an approach syntactically similar to Objective-C's current implementation (minus square brackets).

Message passing presents an alternative way of solving the method dispatch problem. Instead of the virtual method's compile-time offsets and tables which don't consult the object (except for its type), message passing sends a unique message identifier to the object itself and the object determines at runtime what action to take.

There are two important differences here:

Runtime resolution — so the connection between message identifier and action can be changed at runtime.
Involvement of the object itself, not just its class.

On a technical level, the difference between a virtual method table and passing a message identifier is relatively minor (since both are really table lookups and both are actually performed at runtime). The difference ends up being conceptual:

Virtual method table languages generally make it hard or impossible to change the virtual method table contents or pointers at runtime.
Type safety is essential in a virtual method table language since the compiler may alter table lookups based on type, particularly in cases of multiple inheritance. In message passing systems, type safety is irrelevant to method invocation.

Why this matters

The short answer is that this dynamic message handling in Objective-C makes it much easier to work within a large framework that you didn't create because you can examine, patch and modify elements of that framework on the fly. The most common situation where this is likely to occur is when dealing with an application framework.

The biggest reason for this is that you can add or change methods on existing objects, without needing to subclass them, while they are running. Approaches for this include categories, method swizzling and isa-swizzling.

This makes the following situations possible:

You want to add a convenience method to someone else's object (a quick search of my own posts reveals that about a dozens of my own posts involve adding convenience methods to Cocoa classes, e.g. Safely fetching an NSManagedObject by URI).
You want to change the behavior of a class you didn't (and can't) allocate because it is created by someone else (this is how Key-Value Observing is implemented in Cocoa).
You want to treat objects generically and handle potential differences with runtime introspection.
You want to substitute an object of a completely different class to the expected class (this is used in Cocoa by NSProxy to turn a regular object into a distributed object).

These points may seem somewhat mild but they are central to maximizing code reuse when working within someone else's framework: if you need existing code to work differently, you don't need to reimplement the whole class and you don't need to change how it is allocated.

Languages using virtual method tables can adopt some of these ideas (like the boost::any class or C♯ 4.0's dynamic member lookup) but these features have additional restrictions and don't apply to all objects, meaning that they can't be used on purely arbitrary objects (such as those you don't control or didn't create) and so don't help when interacting with someone else's framework.

Simply put: dynamic message passing instead of virtual method invocations makes Objective-C a much better language for working with a large library or framework that someone has written.

The tradeoff

The downside to dynamic message invocation is that it is only as fast as virtual method invocation when the message lookup is cached, otherwise it is invariably slower.

Also, in keeping with the philosophy of a purely dynamic messaging system, Objective-C does not use templates or template metaprogramming and does not have non-dynamic (i.e. non-virtual) methods. This means that Objective-C methods will miss out on the compiler optimizations possible when employing these techniques. Also, since modern programming in C++ is substantially focussed on these features, it can difficult to adapt programs using these ideas to Objective-C.

Theoretically, Objective-C could implement these features but they are in opposition to the underlying concepts of flexibility and dynamic behavior in Objective-C — and would shut-down all advantages from the previous section if they were used.

Conclusion

It's not a coincidence that I write an Objective-C/Cocoa blog, I'm obviously an advocate of the two. In my opinion, Objective-C is the best language for programming situations where you must make extensive use of a framework written by someone else (particularly an application framework). The success of Objective-C in this situation is due to the combination of:

speed and precision (from its compiled C roots)
dynamic flexibility (due to using message passing for method invocations)

To frame this conclusion, I'll state that I've written major projects using C/WIN32, C++/PowerPlant, C++/MFC, and Java/Swing/AWT. I've also dabbled in smaller projects using C♯/.Net. In all of these cases I have found the application frameworks to be less flexible and less reusable because they lack the dynamic modifiability of Objective-C.

As I've stated, I do view Objective-C's strength in the area of application frameworks as a niche (albeit a very large niche). If I were writing a compiler, OS kernel, or a low-level/high-performance library, then I would use C++ (I wouldn't use pure C because I'd miss my abstractions) — but these are situations where metaprogramming, greater inlining and faster method invocations would trump flexibility concerns. Of course, if you have a project that needs to satisfy all these criteria: then there's always Objective-C++.

The ugly side of blocks: explicit declarations and casting.

2009-10-05T20:20:00.001-07:00

Blocks are a welcome addition to C/Objective-C/C++/Objective-C++ with Snow Leopard but they carry with them the worst aspect of Standard C: function pointer declaration and casting syntax. In this post, I'll show you how to understand declarations and casting syntax for blocks and function pointers, even in the worst of scenarios.

Simple block declarations and casting

Used as intended (simple inline code implementations) blocks are fairly elegant. This is due to one advantage they offer: in simple cases, you do not need to specify the return type — it can be inferred from the return statement in the block itself.

So declaring a block that returns an int can be as simple as:

int (^alwaysReturnIntZero)() = ^{ return 0; };

In this case though, an unqualified integral value is correctly assumed to be an int. If we want the block to return an NSInteger, we need to either cast the return type or not rely on type inference and declare the return fully:

NSInteger (^alwaysReturnNSIntegerZero)() = ^ NSInteger (){ return 0; };

Notice that the block literal (righthand side) does not follow the structure as the block declaration (lefthand side). The block literal uses a straightforward "caret, return type, parameter list" order but the block declaration uses the C function pointer declaration syntax, which can grow more complex (as I'll show later). At this point though, the two are of similar complexity.

Casting a block looks much like declaring a block, minus the name of the variable from the declaration.

long long (^alwaysReturnLongLongZero)() = (long long (^)())alwaysReturnNSIntegerZero;

If you look at what is done here, all that is needed to create a cast for a value to the variable type, is to copy the variable's declaration, put parentheses around the copied declaration and remove the variable name.

Function pointers

Blocks borrow their syntax from standard C function pointers. In almost all cases, the only difference between a block declaration or cast and a function pointer declaration or cast is the "^" character is used for the block and the "*" character is used for the function pointer. e.g.:

long long (*fnAlwaysReturnLongLongZero)() = (long long (*)())fnAlwaysReturnNSIntegerZero;

Of course, functions cannot be declared inline, so you cannot have function literals in the same way as you can have block literals. However, all other syntactic traits remain the same.

Reading declarations correctly

Unfortunately, blocks follow the typical C declaration rules which become outright confusing when you try to return something. Before it all gets complicated, I'm going to explain something simple about C declarations.

Consider how a pointer is declared:

int *myVariable;

If you're reading this blog at all, you should know that this statement creates a pointer named myVariable which points to an int.

But the operator used here is a "dereference", it is not the "make a pointer" (address of) operator. The correct way to read this line is:

Declare a variable:
myVariable
It can be dereferenced (and by implication is therefore a pointer)
*myVariable
If it is deferenced, then the value yielded from the dereference should be treated as an int:
int *myVariable;.

Let's look at the alwaysReturnIntZero declaration from above again and we'll apply this same reading to it.

int (^alwaysReturnIntZero)() = ^{ return 0; };

Declare a variable:
alwaysReturnIntZero
It can be dereferenced to yield block information (and by implication is therefore a block pointer):
^alwaysReturnIntZero
Its block implementation takes no parameters and returns an int:
int (^alwaysReturnIntZero)()

This approach to reading a declaration is quite simple but you'll need to it to follow the next section.

Declaring a block that returns a block

Imagine you wanted to use a block to compare a double to an int and return true if the double is greater than the int or false if the double is equal or smaller. In the simple case, that might look like this:

bool (^compareDoubleToInt)(int i, double j) = ^{ return j > i; };

Easy enough but imagine now that you want to break this into two pieces:

A first block which takes only the int and returns a second block, pre-configured to use this int.
The second block then takes the double, compares it to its pre-configured int and returns the result.

The first block is then a factory block which creates instances of the second block that operate like the compareDoubleToInt shown above for a single, pre-configured value of i.

The complete implemention of this would be:

bool (^(^newDoubleToIntComparison)(int))(double) =
    ^(int i)
    {
        return Block_copy(^ (double j)
        {
            return j > i;
        });
    };

Pay careful attention to the "new" in the name — this serves to notify that you must use Block_destroy on any blocks created in this fashion when you're done.

If everything about the syntax on that first line (the declaration) makes immediate sense to you, then you may consider yourself skilled at syntactic recursion.

The reason most people find this hard to read is that verbally, we would describe this scenario in a very different order:

Declare a variable:
newDoubleToIntComparison
It can be dereferenced to yield block information (and by implication is therefore a block pointer):
^newDoubleToIntComparison
The block takes an int parameter:
(^newDoubleToIntComparison)(int)
Its return value can be dereferenced to yield block information (and by implication the return value is therefore a block pointer):
(^(^newDoubleToIntComparison)(int))
This returned block takes a double parameter
(^(^newDoubleToIntComparison)(int))(double)
And the returned block returns a bool
bool (^(^newDoubleToIntComparison)(int))(double);

If C declarations read from left-to-right, it would be far less confusing. Instead, we have a situation where blocks that return blocks are recursively nested inside each other.

Of course, most people mitigate this by typedef'ing absolutely function pointer they ever use. Doing this for the previous block declaration changes it to:

typedef bool (^IsDoubleBiggerBlock)(double);
IsDoubleBiggerBlock (^newDoubleToIntComparison)(int);

Functions or methods that return blocks

It may also be helpful to see the subtle difference between declaring a block that returns a block and the definition of of a function returns a block.

Replacing the factory block with a factory function in the previous example would lead to:

bool (^NewDoubleToIntComparisonFunction(int i))(double)
{
    return (bool (^)(double))Block_copy(^ (double j)
    {
        return j > i;
    });
};

This function takes a single int as its parameter and yet the last component on the function prototype line is (double). The int parameter that the function actually takes and the name of the function are nested inside of the return type (the return type comprises the double parameter to the right, the caret character and the bool return value to the left).

Also notice that you need to cast the output of Block_copy to have it recognized as the correct return type.

As with the variable declarations, this nested behaviour is normally considered too annoying, so typedefs are employed to simplify:

typedef bool (^IsDoubleBiggerBlock)(double);
IsDoubleBiggerBlock NewDoubleToIntComparisonFunction(int i)
{
    return (IsDoubleBiggerBlock)Block_copy(^ (double j)
    {
        return j > i;
    });
};

This has the huge advantage that it puts the function's parameter back where it belongs — as the last component on the function prototype line.

An Objective-C method that returns a block is a much simpler situation since the method does not become nested within the return type in the same way. Instead, the return type looks identical to the cast of the returned copied block and the rest of the method remains distinct.

- (bool (^)(double))newDoubleToIntComparison:(int)i
{
    return (bool (^)(double))Block_copy(^ (double j)
    {
        return j > i;
    });
}

Conclusion

The declaration of C function pointers is widely regarded as the worst syntax in the language. There is a good reason for this: the information in a function pointer's declaration flows from the most significant components which are nestled on the inside of the declaration to the least significant components which encircle the outside. They could flow left-to-right like a sentence but instead they flow outwards from an identifier somewhere in the middle.

Sadly, blocks follow in this tradition. All you can do to mitigate the torment is use typedef'd declarations judiciously and try to keep your blocks simple. They're not really intended for large numbers of parameters and complex return values, anyway.

Apologies for Atom/RSS feed issues. Here are the real articles...

2009-10-05T03:59:00.001-07:00

Last week, I updated a large number of old articles (to ensure the code still builds). During the course of these updates, I accidentally duplicated two old articles. Once I noticed, I deleted the duplicates but unfortunately, the duplicates appeared as new posts in many Atom/RSS feeds with a broken/missing link to the actual post.

If you're looking for the actual location of these articles, you can find them here:

Optimizing the loading of a very large table on the iPhone

2009-09-28T18:51:00.001-07:00

In this post, I look at a UITableView on the iPhone which loads its data from a server and look at how its performance scales from single rows to tens of thousands of rows. I'll examine which aspects of the iPhone scale well and which become a burden as a displayed dataset moves from trivially sized to large sizes.

Introduction

Last week, I received an email asking if StreamToMe would be able to handle 20,000 files in a media collection. This person probably meant "20,000 files categorized into subfolders" but the performance geek in me immediately thought that 20,000 files in a single directory was a far more interesting question.

It's easy to find programs on the iPhone that become slower and less responsive when dealing with tables that only contain a few hundred rows. In my own experience, I've rarely tested with more than a couple hundred items in a UITableView. I had no idea what a UITableView would do with 20,000 items.

Purely looking at data sizes, it seems like it should work: the 128MB versions of the iPhone (all devices prior to the 3Gs) allow applications to use between 24MB and 64MB of RAM before they are killed for excess memory use. This should allow for between 1-3kB per row within available memory — far more than I need.

Of course, this won't be a synthetic test with efficient but trivial rows: this is a program with real data, transferred from a server, parsed, constructed and displayed, which must remain capable of media playback after everything else is loaded into memory.

Generating test data

I wanted real test data so I decided to replicate a small MP3 file on the server. I used a 1 kilobyte file containing a single tone that plays for 4 seconds. I used UUID strings appended with ".mp3" for filenames so that file sorting algorithms would still have some real work to do.

for (NSInteger i = 0; i < MAX_FILES; i++)
{
    NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];
    
    CFUUIDRef uuid = CFUUIDCreate(NULL);
    NSString *uuidString = (NSString *)CFUUIDCreateString(NULL, uuid);
    CFRelease(uuid);
    [uuidString autorelease];

    NSString *filePath =
        [directoryPath stringByAppendingPathComponent:
            [NSString stringWithFormat:@"%@.mp3", uuidString]];
    [[NSFileManager defaultManager]
        createFileAtPath:filePath
        contents:mp3Data
        attributes:nil];
    
    if ((i % 1000) == 0)
    {
        NSLog(@"%ld files remaining.", MAX_FILES - i);
    }
    
    [pool drain];
}

Using this code, I created directories with 1, 10, 100, 1000, 10,000, 20,000, 100,000 and 1,000,000 files to see how far I would get with the application.

A few interesting points came out of this work, unrelated to the iPhone itself:

Yes, you can now create more than 65536 files in a directory. I remember when Macs couldn't create more than 65536 files on the entire disk.
Curiously, when you select files and use the "Copy" menu item in the Finder, the maximum number of items is still 65536.
Don't try to drag 10,000 (or more) items from one window to another — I gave up watching the beachball on this action and hard-booted.
-[NSFileManager createFileAtPath:contents:attributes:] is a little slower than other approaches because it creates the file in a temporary location and moves it to the target location (a single create at the target location would have been faster).
if you try to create a million MP3s on your computer, be prepared to wait 3 hours while it churns away and then have the Spotlight metadata indexer slow your computer down for a further few hours.

Initial results

Which data sets will load and how long will they take? With no preparation of StreamToMe in anticipation of this test, I immediately pointed it at the test directories.

Number of files	Total time from touch event to display of directory
1	131ms
10	128ms
100	424ms
1,000	3,108ms
10,000	30,587ms
20,000	64,191ms*
100,000	N/A
1,000,000	N/A

The asterisk here indicates that the 20,000 row run was not able to reliably play the audio files after loading (it would sometimes quit due to low memory). The one hundred thousand and million row tests both failed to load at all.

All tests performed on an iPhone 3G connected via 802.11g to a Mac Pro Quad 2.66Ghz (the iPhone was also connected to the Mac Pro via USB for logging purposes). Times are taken from a single cold run.

Initial analysis

Scaling

Looking first at the way the results scale, this table shows the expected behavior with the iPhone's memory arrangement:

The iPhone has a 16k data cache so tests that operate within this limit (fewer than a couple hundred rows) are more bound by the network latency and fixed-duration setup costs than any row-specific work performed. This leads to better than linear (less than O(n)) scaling for the 1, 10 and 100 tests.
Tests that exceed the 16k data limit (one thousand through twenty thousand) scale almost perfectly linearly as they push a consistent amount of data through main memory.
There is no virtual memory on the iPhone, so you don't see a greater than linear increase in time as memory runs out (thrashing) — instead, there's an abrupt point at which things simply fail. More memory will not make a iPhone faster in the same way that it will make a memory constrained Mac faster.

Speed

Looking at performance, it's a little disappointing — no one would want to wait over a minute for their file list to load. Where is that time taken? Looking at timing results for the 20,000 row test:

6,563ms on the server, loading the directory listing and formatting the response.
3,111ms transferring data.
12,771ms on the client parsing the response from the server.
32,098ms on the client converting the parsed response into row-ready classes
9,453ms in autorelease pool cleanup

Memory use

The memory footprint with 20,000 files loaded is around 6.8MB with peak memory use of 38.2MB. This leads to two questions:

With final memory so low, why is the program behaving as though its memory is constrained?
What is causing the peak memory to be so high? If it were much lower, 100,000 rows might be possible.

Code changes and improvements

stat is the biggest constraint on filesystem lookups

The first change I made was on the server. 6.5 seconds to load 20,000 files is too slow. The key constraining factor here is reading the basic metadata for tens of thousands of small files. The low level file function stat (or in this case, lstat) is the limiting factor.

Technically, I wasn't using lstat but -[NSFileManager contentsOfDirectoryAtPath:error:] was invoking it for every file and then -[NSFileManager fileExistsAtPath:isDirectory:] was invoking it again to see if each file was a directory.

In 10.6, you can replace -[NSFileManager contentsOfDirectoryAtPath:error:] with -[NSFileManager contentsOfDirectoryAtURL:includingPropertiesForKeys:options:error:] so that these two commands can be rolled into one (halving the number of calls to lstat). I want to keep 10.5 compatibility, so instead, I wrote my own traversal using readdir and lstat directly.

This change doubled the directory reading speed of the server.

Lowering memory footprint

In Cocoa, peak memory is often caused by autoreleased memory that accumulates during loops. You can address this by inserting NSAutoreleasePool allocations and drains into your loops but this is slow. The best approach is to eliminate autoreleased memory in memory constrained areas. I did this throughout the parsing and conversion code on the iPhone.

There was also some unnecessary copying of memory (from the network data buffer to an NSString and back to a UTF8 string) that I removed (by passing the network data buffer directly as the UTF8 string).

More than simply lowering the memory footprint, these changed almost doubled the speed of parsing on the iPhone.

Memory fragmentation

Even after lowering peak memory usage, I still encountered out of memory errors when trying to allocate larger objects, even though my memory usage was only 16MB.

After some investigation, I realized that my parser was fragmenting memory by allocating smaller and larger string fragments in a leapfrogging effect so that consecutive strings in the final data structure were not actually adjacent in memory. Even though memory usage was only around 50%, there was not a single, contiguous 2MB space within this for media loading and playback due to the scattered pattern of string, array and dictionary allocations following parsing.

The simplest solution (one that didn't involve rewriting the parser) was to copy the parsed data every few rows into properly contiguous locations, releasing the old non-contiguous locations. After this, memory allocation issues went away.

Of course, this did result in a minor increase in parsing time but the improved memory performance was worth the minor performance cost.

Moving work out of critical loops

Finally, I looked at the conversion of parsed data into classes representing each row. This work was primarily assigning strings to properties of an object and couldn't be easily avoided.

Of course, in an ideal case, parsing and object construction would be an integrated process but since the parser is generic and wasn't written for this program, it doesn't produce data in the best format, requiring this extra "converting" pass through the data. For development time constraints, I didn't consider integrating these two components although this is certainly a point where further speed improvements could be gained.

During this process, I also created an NSInvocation for each object to handle its user-interface action when tapped in the table (media rows play the file, folder rows open the folder) and assigned a named UIImage (either the file or the folder icon) to the object.

Since there are only two images and two possible actions, these objects could be created outside the loop and either minimally modified for each row (with different parameters in the case of the NSInvocation) or assigned as-is (in the case of the UIImage).

These seemingly tiny changes (in addition to the memory changes mentioned above) resulted in a better than tenfold performance increase for the converting stage (which had been the most time consuming stage).

Results revisited

With these changes, the results became.

Number of files	New time taken	Old time taken
1	135ms	131ms
10	137ms	128ms
100	250ms	424ms
1,000	845ms	3,108ms
10,000	7,998ms	30,587ms
20,000	14,606ms	64,191ms*
100,000	84,594ms	N/A
1,000,000	N/A	N/A

The 20,000 row test case now runs more than 4 times faster and the 100,000 test case completes successfully and can play the audio files once loaded.

Running one million rows in the simulator

The million row test set involved 121MB of data sent over the network — it was never going to work on a 128MB iPhone.

Without the memory constraints of the iPhone, I ran a million rows in the simulator. It took 7.5 minutes to load (almost entirely bound by lstat).

After around 800,000 rows (40 pixels high each), UITableView can no longer address each pixel accurately with single precision CGFloats used on the iPhone, so every second row was misplaced by 16 pixels or so making the result almost unreadable beyond that point. In short: UITableView isn't really meant to handle a million rows.

Conclusion

The iPhone can handle tables with 100,000 rows — and it continues to scroll as smoothly as though it were only 100 rows.

Optimization doesn't mean writing assembly code and bleeding from your fingernails. A couple hours work resulted in a 4 times performance increase and dramatically better memory usage from very simple code rearrangement.

The biggest improvements to the performance came from three points:

replacing autoreleased objects with tight alloc and release pairs in just two loops (in some cases removing the allocation entirely)
removing the NSInvocation generation and UIImage lookup work from the key construction loop
reducing the calls to lstat on the server (although this wasn't part of iPhone UITableView optimization per se)

And increasing available productive memory actually involved performing more allocations — reallocating discontiguous collections of objects to contiguous memory locations. There was also the typical elimination of unnecessary copying.

StreamToMe Version 1.1 available

2009-09-22T17:59:00.001-07:00

The latest version of StreamToMe — for streaming audio and video from your Mac to your iPhone/iPod Touch — is now available on the App Store. It has only been one month since I released version 1.0 but I have lots of new changes to share.

New Features

You will need to download the latest version of ServeToMe to take advantage of these new features.

The "Seek to anywhere" update

StreamToMe version 1.1 adds a number of requested features, most prominent of which is "seek to anywhere". You no longer need to wait for the end of the file to be encoded before you jump ahead — you can seek to anywhere at anytime and it will "just work".

Remote WiFi and 3G access

StreamToMe now supports connections via 3G and from non-local WiFi locations. Bitrates between 96k and 1600k are chosen by the iPhone based on the available data rate. These lower bitrates are also available on local WiFi connections for situations where interference means a lower bitrate is required.

A remote connection requires that you have configured your Mac's network to make ServeToMe's port accessible remotely. This configuration is left to you since it is dependent on how you are connected to the internet, your modem/router and firewalls.

Password protection

To protect access to your files (especially when made available over the internet) you can now password protect the server.

Minor changes and fixes

Of course, there are numerous little fixes and changes too:

Fixed playback of many common MOV codecs, so many more Quicktime MOV files will be supported.
The server now only encodes video as needed, resulting in much lower average CPU usage.
Fixes for occasional broken socket (network dropout) problems on Snow Leopard.
Fixes for session ID problems that caused "The requested file couldn't be converted for streaming" to be incorrectly sent for supported files.
Scroll indexes now used for large directories.
Shinier file and folder icons.

Still coming...

I can't deliver everything all at once but the following frequently requested features are still planned for a future version:

Windows support for ServeToMe
Alternate audio tracks
Subtitles
Thumbnail previews

Screenshots

Here are some screenshots of the updated application in action:

WhereIsMyMac, a Snow Leopard CoreLocation project

2009-09-21T06:08:00.001-07:00

In Snow Leopard, you can ask for the computer's location. Without a GPS, how accurate could that be? The answer in my case is: very accurate. In this post, I'll show you how to write a CoreLocation app for the Mac that shows the current location in Google Maps, so you can see exactly where your computer thinks it is.

Where Is My Mac?

In this post, I present the following sample project:

You can download the Xcode 3.2 project here: WhereIsMyMac.zip (33kB). Mac OS X 10.6 is required.

The program shows your current location, centered in the map. The zoom level is set so that the accuracy radius reported by CoreLocation is exactly half the width of the window.

So how accurate is it? For me, my actual location was within about 50 meters of the detected location.

First, I'll talk about the extremely simple code involved. Afterwards, I'll discuss how CoreLocation gets this information.

Implementation

If you haven't already used CoreLocation on the iPhone, it's really simple: just turn it on and let it update you when it has location information.

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification
{
    // Turn on CoreLocation
    locationManager = [[CLLocationManager alloc] init];
    locationManager.delegate = self;
    [locationManager startUpdatingLocation];
}

Then all you need to do is receive the location updates and load the map at the new location when received. We do this in the CLLocationManagerDelegate methods.

- (void)locationManager:(CLLocationManager *)manager
    didUpdateToLocation:(CLLocation *)newLocation
    fromLocation:(CLLocation *)oldLocation
{
    // Ignore updates where nothing we care about changed
    if (newLocation.coordinate.longitude == oldLocation.coordinate.longitude &&
        newLocation.coordinate.latitude == oldLocation.coordinate.latitude &&
        newLocation.horizontalAccuracy == oldLocation.horizontalAccuracy)
    {
        return;
    }

    // Load the HTML for displaying the Google map from a file and replace the
    // format placeholders with our location data
    NSString *htmlString = [NSString stringWithFormat:
        [NSString 
            stringWithContentsOfFile:
                [[NSBundle mainBundle]
                    pathForResource:@"HTMLFormatString" ofType:@"html"]
            encoding:NSUTF8StringEncoding
            error:NULL],
        newLocation.coordinate.latitude,
        newLocation.coordinate.longitude,
        [WhereIsMyMacAppDelegate latitudeRangeForLocation:newLocation],
        [WhereIsMyMacAppDelegate longitudeRangeForLocation:newLocation]];
    
    // Load the HTML in the WebView and set the labels
    [[webView mainFrame] loadHTMLString:htmlString baseURL:nil];
    [locationLabel setStringValue:[NSString stringWithFormat:@"%f, %f",
        newLocation.coordinate.latitude, newLocation.coordinate.longitude]];
    [accuracyLabel setStringValue:[NSString stringWithFormat:@"%f",
        newLocation.horizontalAccuracy]];
}

Notice here that I load the HTML from a file, then use it as a format string, replacing the % sequences. This means that I need to escape the two percent characters in the file that need to remain percents (this is done by turning them into double percents).

The only other relevant code is the code to convert from meters (the unit for accuracy in CoreLocation) to Longitude and Latitude (used to specify the zoom factor to Google Maps).

This too is pretty simple: it's just a scale factor for the latitude and a scale plus a trigonometric function for the longitude:

+ (double)latitudeRangeForLocation:(CLLocation *)aLocation
{
    const double M = 6367000.0; // mean meridional radius of curvature of Earth
    const double metersToLatitude = 1.0 / ((M_PI / 180.0) * M);
    const double accuracyToWindowScale = 2.0;
    
    return aLocation.horizontalAccuracy * metersToLatitude * accuracyToWindowScale;
}

+ (double)longitudeRangeForLocation:(CLLocation *)aLocation
{
    double latitudeRange =
        [WhereIsMyMacAppDelegate latitudeRangeForLocation:aLocation];
    
    return latitudeRange * cos(aLocation.coordinate.latitude * M_PI / 180.0);
}

People who are extremely fussy about distance to latitude conversions don't use a constant meridional radius of curvature for Earth (since Earth is an oblate ellipsoid, this value varies from around 6,330,000 to almost 6,400,000) but a constant value is sufficient for most purposes.

The accuracyToWindowScale value is used so that the accuracy range reported by CoreLocation ends up as half the window width (instead of 100% of the window width).

Where does CoreLocation get this information?

The documentation is somewhat vague on where CoreLocation gets this information. Apple imply that there are a few different sources of information that may be used, depending on what is available.

My first thought was: maybe it is using my IP address to determine my location.

Looking up my IP address using two different online IP geocoding services revealed the exact center of Australia as my location from my IP address — almost 2000 kilometers from where I actually am.

My second thought was maybe it is geocoding my address in Address Book. That's not the answer either, since that address is out-of-date and is at least 5 kilometers away.

The answer is that I have WiFi on my Mac. Apple uses the WiFi networks you can see from your current location and correlates that against a database of known locations of WiFi networks (yes, companies drive down streets and record the approximate street addresses of WiFi networks).

So my neighbouring networks: "SweetCheeks", "TheSherriff", "MrBojangles" and "Netgear5" are revealing my location (although I doubt the names are important — its probably the WiFi MAC addresses that are tracked).

Conclusion

You can download the Xcode 3.2 project here: WhereIsMyMac.zip (33kB). Mac OS X 10.6 is required

The only use I've seen for CoreLocation in Snow Leopard so far is setting the Time Zone automatically in the Date & Time System Preferences panel. This doesn't require a great deal of accuracy but it turns out that CoreLocation is capable of much more.

Of course, I'm only reporting on the accuracy that I see, which is anecdotal evidence only. I'd be interested to know how accurate (or inaccurate) this is for other people.

As you can see in this sample application, the code involved is very simple. Even if it isn't accurate for everyone, it would make a good option in many applications.

Building for earlier OS versions from Snow Leopard

2009-09-16T03:10:00.001-07:00

It is very easy, when developing on a new operating system, to create projects that won't run on any previous OS version. To ensure backwards compatibility, there are Xcode and gcc options that allow you to build while maintaining support for earlier OS versions. In this post, I'll look at the ways in which this compatibility is controlled and some of the new ways it can go wrong on Snow Leopard.

The cost of backwards compatibility

Customers are regularly unhappy at programmers for dropping support for older operating systems as soon as possible. As with most decisions like this, the reason tends to be a little bit feature-driven and a little bit economic: development support costs increase for every supported version of the OS older than the most recent supported version.

Supporting older operating systems requires:

When creating a build on a newer OS, you must be careful to write the entire program relying only on behaviors that existing on your earliest targetted OS.
A test system running an earlier version of the OS to verify that point 1 succeeded.

Point 1 tends to be where most programmers rule out support for earlier systems. I know that as much as 20% of the Mac user-base are still running Mac OS X 10.3.9 and 10.4.11 but I'm unlikely to ever support these operating systems again in one of my releases because these markets aren't big enough to warrant giving up features like Obj-C 2.0's fast iteration, NSOperationQueue or CoreAnimation which have changed how I write programs.

Point 2 can also be a serious impediment for small developers who simply don't maintain a series of test machines for their software. Larger developers can simply buy extra machines or buy time in Apple's Compatibility Labs but even large companies need to weigh this cost against the potential return.

Easy part: building against earlier SDKs in Xcode

With Snow Leopard now installed on my main development machine though, I'm forced to go through the backwards compatibility rigamarole just to ensure Leopard compatibility. As fast as the uptake of Snow Leopard was, it still isn't the dominant Mac OS X version — it is far too soon for me to demand users upgrade (although Gus Mueller has already ripped that band-aid off with the 10.6-only release of Acorn 2).

While I'm talking about Mac OS X here, these settings are the same when building for different iPhone OS versions.

Building against earlier SDKs in Xcode is the easy part. There are two settings involved:

Base SDK (the OS version whose headers you'll use and the newest OS version from which you'll use optional features)
Mac OS X Deployment Target (the oldest OS version supported)

The Base SDK controls what SDK you actually link against and the Mac OS X Deployment Target controls the minimum OS version allowed. In simple cases, just set both of these to the same value.

You set the Base SDK in the Project settings:

and further down the settings list, the Mac OS X Deployment Target:

Weak linking (using newer features if they are available)

Weak linking allows you to link against a newer SDK but deploy on an older operating system.

You should use weak linking in cases where you:

want the program to run on a earlier version of the operating system
want to use a feature from a newer OS version if it is available

Set the Base SDK to the newer OS version that contains the newer features you will use if available and set the Mac OS X Deployment Target to the older version.

This causes everything newer than the Mac OS X Deployment Target to be weak linked — meaning that you will try to link against the newer features if available but can live without them if they are not available.

If a program is run on an older OS than the Base SDK:

unavailable weak linked functions will have NULL function pointers
unavailable weak linked class names will return nil from NSClassFromString
unavailable weak linked methods will return NO from the containing objects' respondsToSelector: method.

The important point to remember is that anything weak-linked should be checked to ensure it is non-zero before use.

For example, suppose to wanted to set the Dock to autohide on Mac OS X 10.6 (using the new Snow Leopard -[NSApplication setPresentationOptions:] method) but you want your application to also run on Mac OS X 10.5 and leave the Dock as-is, you could set the Base SDK to Mac OS X 10.6, the Deployment Target to Mac OS X 10.5 and run the following code:

if ([[NSApplication sharedApplication]
    respondsToSelector:@selector(setPresentationOptions:)])
{
    [[NSApplication sharedApplication]
        setPresentationOptions:NSApplicationPresentationAutoHideDock];
}

Command-line building for earlier OS versions

You might think POSIX/Open Source libraries that are written to be cross-platform and don't link directly against an Mac OS X specific libraries shouldn't need to change from OS version to OS version.

However, most C/C++ libraries do link against libc (which is a part of libSystem on Mac OS X). Since libSystem is a dynamic library and changes between OS versions, this means that you must be mindful of exactly what version of libSystem you build against.

A common example of getting this wrong is the following linker error:

Undefined symbols:
  "_fopen$UNIX2003", referenced from:
      _some_function in somefile.o

You will get this and similar errors when trying to link two different components which are themselves linked against different versions of libSystem. In this case, the application was linked against Base SDK Mac OS X 10.5 but the static library was linked against the current libSystem.B.dylib in Mac OS X 10.6.

Obviously, fopen is a Standard C function and it is in every version of libSystem but different versions of libSystem have subtly different versions of the function. To fix the bug, you must ensure that all components you link together themselves link against the same versions of the standard libraries.

In the example above, the solution is to rebuild the static library from the source using the following gcc link-line options:

-isysroot /Developer/SDKs/MacOSX10.5.sdk -mmacosx-version-min=10.5

That's right, it's the same settings as in Xcode but on the command line — the Base SDK (isysroot) and the Mac OS X Deployment Target (mmacosx-version-min).

Once you've built an executable or a dynamic library, you can use otool to check that they're not linking against any unexpected dynamic libraries (which may not be present on older OS versions) with the following command:

otool -L myAppExecutable

This reports the required dynamic libraries and their version numbers.

Run the same command on the dynamic libraries in your targetted SDK directory to check their version numbers against the library numbers required by your executable.

Be wary of changed gcc

In Mac OS X 10.5, if you didn't specify an architecture, gcc would build a 32-bit binary. In Snow Leopard, this has changed: if no architecture is specified, a 64-bit binary will be built.

You'll need to pay attention to this, particularly for auto-configured builds which may need to coaxing now to build 32-bit binaries.

Of course, this is an easy thing to do: just specify "-arch i386" or "-arch x86_64" or both on the gcc compile command line — but you will need to remember.

This problem can manifest in an annoying way: a file not found error when linking, even when there is a file of the desired name in the search path. If this occurs, be sure to check that the file in the search path contains the right architecture for your build.

Check an architecture with the following:

file libSomeLibrary.dylib

If you're trying to build a 32-bit binary and you only see:

libSomeLibrary.dylib (for architecture x86_64):	Mach-O 64-bit executable x86_64

Then you need to rebuild libSomeLibrary.dylib or find a 32-bit version.

Conclusion

Programmers don't like supporting earlier OS versions because it means more work and fewer cool features to play with. Despite this, there are often economic reasons to put in the effort and forgo the more modern features to support earlier OS versions.

You will want to choose an OS version when you start a project, since removing OS-specific features can be hugely time consuming — it is always easier to drop support later rather than gain support.

Set the Base SDK, set the Deployment Target and make certain all your components remain in-sync on these points. Remember to double check the build target and architecture for all components you build for yourself and always be wary of dynamic libraries.

Creating alpha masks from text on the iPhone and Mac

2009-09-09T05:02:00.001-07:00

Alpha masks are a powerful way to create graphical effects in your program. In this post, I'll show you how to create an alpha mask from a text string and use that mask to create text-based effects with an image. I'll also show you how to do this on the iPhone and the Mac, so you can see the differences between these platforms in this area.

Introduction

In this post I will present the following sample application:

The program shows the current time, updating every second, on the Mac or iPhone. Within the bounds of the text, the image of the space shuttle is displayed at 100% opacity. Everywhere else, it displays at 30% opacity.

This is done by drawing the image of the shuttle over a white background using an alpha mask — where the mask is white (100% opaque) for the text and dark gray (30% opaque) for the background.

Download the TextMasking-iPhone.zip (37kB) and the TextMasking-Mac.zip (42kB) projects.

Clipping regions in Core Graphics

Clipping and masking are the two key ways of limiting the effect that drawing has in CoreGraphics.

With a clipping region, we create a hard boundary. When a clipping region is used, every pixel drawn inside the region is fully shown (completely opaque), and no pixels outside the region are affected (completely transparent). For example, the following code:

CGContextBeginPath(context);
CGContextAddRect(context, CGRectMake(10, 10, 80, 80));
CGContextAddRect(context, CGRectMake(20, 20, 40, 40));
CGContextEOClip(context);

will ensure that subsequent drawing only has an effect if it is inside the rectangle (x=10, y=10, width=80, height=80) but outside the rectangle (x=20, y=20, width=10, height=10).

The "EO" in CGContextEOClip stands for "Even-Odd". When you use this function instead of CGContextClip, subsequent nested regions (an even or an odd number of nestings) continue to toggle clipping on and off. That is why the second CGContextAddRect is excluded from the clipping region. If I had used CGContextClip, the nested rectangle would have no effect (it is already inside the clipping region).

Clipping with image masks in Core Graphics

A mask affects the opacity/transparency of drawn pixels like a clipping region but the affected areas are specified by the color values in an image, not from a region. This is the approach used in the sample applications. A mask is used instead of a clipping region for two reasons:

A mask allows varying levels of transparency, not just on or off (for the partially transparent regions in the image).
On the iPhone, it's very difficult to get the region outline of text characters (on the Mac you can use appendBezierPathWithGlyph:inFont:), making a clipping region from a text boundary impractical.

Creating a mask

The Mac and the iPhone differ significantly on how the mask image must be created.

On the iPhone, it is possible to copy the current graphics context to an image before it is drawn to screen and use that as the mask.

On the Mac this doesn't work. The Mac requires that masking images be grayscale without an alpha channel — you could copy the current graphics context in the same way but it can't be used as a mask image. We'll need to create a context that meets these specific requirements.

On the iPhone:

Drawing the text to the current graphics context and copying that to an image on the iPhone:

CGContextRef context = UIGraphicsGetCurrentContext();

// Draw a dark gray background
[[UIColor darkGrayColor] setFill];
CGContextFillRect(context, rect);

// Draw the text upside-down
CGContextSaveGState(context);
CGContextTranslateCTM(context, 0, rect.size.height);
CGContextScaleCTM(context, 1.0, -1.0);
[[UIColor whiteColor] setFill];
[text drawInRect:rect withFont:[UIFont fontWithName:@"HelveticaNeue-Bold" size:124]];
CGContextRestoreGState(context);

// Create an image mask from what we've drawn so far
CGImageRef alphaMask = CGBitmapContextCreateImage(context);

The only tricky part here is that the image will be flipped when we draw it back again, so we need to draw the text upside-down — other than that, the iPhone has it easy here.

On the Mac

Since the Mac must have the bitmap image as a CGColorSpaceCreateDeviceGray(); image without an alpha channel, we can't just copy a screen context to use as our mask. Instead, we need to create a new context with the settings we require and perform all drawing there.

This has one advantage: we can set the context to flipped:NO so that we don't need to draw upside-down to have it render correctly.

// Create a grayscale context for the mask
CGColorSpaceRef colorspace = CGColorSpaceCreateDeviceGray();
CGContextRef maskContext =
CGBitmapContextCreate(
    NULL,
    self.bounds.size.width,
    self.bounds.size.height,
    8,
    self.bounds.size.width,
    colorspace,
    0);
CGColorSpaceRelease(colorspace);

// Switch to the context for drawing
NSGraphicsContext *maskGraphicsContext =
    [NSGraphicsContext
        graphicsContextWithGraphicsPort:maskContext
        flipped:NO];
[NSGraphicsContext saveGraphicsState];
[NSGraphicsContext setCurrentContext:maskGraphicsContext];

// Draw a black background
[[NSColor darkGrayColor] setFill];
CGContextFillRect(maskContext, rect);

// Draw the text right-way-up (non-flipped context)
[text
    drawInRect:rect
    withAttributes:
        [NSDictionary dictionaryWithObjectsAndKeys:
            [NSFont fontWithName:@"HelveticaNeue-Bold" size:124], NSFontAttributeName,
            [NSColor whiteColor], NSForegroundColorAttributeName,
        nil]];

// Switch back to the window's context
[NSGraphicsContext restoreGraphicsState];

// Create an image mask from what we've drawn so far
CGImageRef alphaMask = CGBitmapContextCreateImage(maskContext);

Using the mask

Using the mask is much easier than creating it:

Save the state of the current context (so that we can go back to a non-masked state when we're done).
Apply the mask using CGContextClipToMask.
Perform whatever drawing we want masked.
Restore the saved context state to remove the mask again.

The iPhone version is:

// Draw a white background (clear the window)
[[UIColor whiteColor] setFill];
CGContextFillRect(context, rect);

// Draw the image, clipped by the mask
CGContextSaveGState(context);
CGContextClipToMask(context, rect, alphaMask);
[[UIImage imageNamed:@"shuttle.jpg"] drawInRect:rect];
CGContextRestoreGState(context);
CGImageRelease(alphaMask);

The Mac version substitutes NSColor and NSImage for UIColor and UIImage but is otherwise the same.

Conclusion

Download the TextMasking-iPhone.zip (37kB) and the TextMasking-Mac.zip (42kB) projects.

Clipping and masking are two of the most powerful operations available when drawing in code but as highly abstract concepts they can be difficult to use for the first time since a mistake normally results in nothing happening (a difficult scenario from which to learn).

I have only briefly shown region-based clipping. If you don't need the partial transparency offered by masks and can draw your shapes as a region then it is faster than a mask (since it doesn't need to allocate or load the mask image). Obviously, the option you choose should be based on the output you require.

The examples shown here don't cache anything — they allocate and dispose of all data structures every time the drawRect: method is called. In a proper program, you should not allocate the mask image every time you draw. You can allocate the mask once and simply set the context back to it to update it.

An NSSplitView delegate for priority based resizing

2009-09-01T21:09:00.001-07:00

The default resizing mechanism in NSSplitView is proportional resizing — if the NSSplitView changes size, each column resizes by an equal percent. This works badly in the common case where the columns in a split view are used to separate a side panels from a main view area (for example the "source list" in iTunes or the file tree in Xcode). In this post, I'll show you a delegate class that configures a split view for this side panel and main view behavior — resizing the views in a split view based on a priority list.

Snow Leopard?

Every Mac programming blog that I read is overflowing this week with Snow Leopard information. To celebrate this exciting event, I proudly ignore the trend and present code that (aside from a little Objective-C 2.0 syntax) would run on Mac OS 10.0.

Proportional versus priority-based resizing

For a three section NSSplitView, the default proportional resizing behaves like this:

In proportional resizing, as the window grows, each column grows by the same percentage.

By comparison, priority-based resizing works like this:

Priority-based resizing nominates 1 view as the most important. This is normally the window's "main" view. This highest priority view is the only view that grows in size as the window grows.

You can download the sample project ColumSplitView.zip (60kb) to see the priority resizing at work.

Proportional resizing in reverse

The flip side to priority resizing is that the highest priority view is also the first to compress to zero. For this reason, the priority-based resizing should also implement minimum sizes so that the main view never actually reaches zero size.

Once the highest priority view reaches minimum, remaining views are collapsed by priority until all views are at their minimum size. The window or enclosing scroll view's minimum size should be constrained so that the split view is never forced past the point where columns are all at minimum size.

Controlling an NSSplitView

NSSplitView takes a delegate. The delegate methods are where we control the minimum sizes of sections and which views expand or collapse by what amount.

The class I'll present will be a dedicated delegate class named PrioritySplitViewDelegate that allows you to configure priorities and minimum sizes for the NSSplitView's subviews. This generic delegate can then be constructed, configured and attached to the NSSplitView in your controller code.

@interface PrioritySplitViewDelegate : NSObject
{
    NSMutableDictionary *lengthsByViewIndex;
    NSMutableDictionary *viewIndicesByPriority;
}

- (void)setMinimumLength:(CGFloat)minLength
    forViewAtIndex:(NSInteger)viewIndex;
- (void)setPriority:(NSInteger)priorityIndex
    forViewAtIndex:(NSInteger)viewIndex;

@end

Some usage cautions about this design: the delegate does not know in advance how many sections the split view will have, so it will let you specify priorities or minimum sizes for views that don't exist.

Specifying a priority for every view is mandatory so if you forget to specify a priority for a view, an exception will be thrown when the NSSplitView is resized. Minimum sizes are optional but will be zero if not specified. Keep these points in mind when using this class.

Implementation

Constraining the coordinates in the splitView:constrainMinCoordinate:ofSubviewAt: and splitView:constrainMaxCoordinate:ofSubviewAt: happens when the user drags the boundary between two split view sections. In these methods, we need to ensure that the view which is getting smaller does not exceed its minimum size.

When dragging the boundary between two columns to the left, this means that the minimum coordinate is that which would collapse the left view to its minimum size.

- (CGFloat)splitView:(NSSplitView *)sender
    constrainMinCoordinate:(CGFloat)proposedMin ofSubviewAt:(NSInteger)offset
{
    NSView *subview = [[sender subviews] objectAtIndex:offset];
    NSRect subviewFrame = subview.frame;
    CGFloat frameOrigin;
    if ([sender isVertical])
    {
        frameOrigin = subviewFrame.origin.x;
    }
    else
    {
        frameOrigin = subviewFrame.origin.y;
    }
    
    CGFloat minimumSize =
        [[lengthsByViewIndex objectForKey:[NSNumber numberWithInteger:offset]]
            doubleValue];
    
    return frameOrigin + minimumSize;
}

The splitView:constrainMaxCoordinate:ofSubviewAt: is similar. You can download the sample project to see the implementation of this method.

Finally, we need to handle the priority resizing itself. This happens in the implementation of the delegate method splitView:resizeSubviewsWithOldSize:. This method is invoked when the split view is resized (normally because the enclosing window has resized).

A brief description of the work involved is:

Iterate over the list of views, sorted by priority.
As each view is reached, attempt to apply the entire size change to this view.
If applying the size to the view would cause it to become smaller than its minimum size, apply as much as possible and proceed to the next view by priority.

The size change for the split view is named delta in the following code taken from the splitView:resizeSubviewsWithOldSize: method.

for (NSNumber *priorityIndex in
    [[viewIndicesByPriority allKeys] sortedArrayUsingSelector:@selector(compare:)])
{
    NSNumber *viewIndex = [viewIndicesByPriority objectForKey:priorityIndex];
    NSInteger viewIndexValue = [viewIndex integerValue];
    if (viewIndexValue >= subviewsCount)
    {
        continue;
    }
    
    NSView *view = [subviews objectAtIndex:viewIndexValue];
    
    NSSize frameSize = [view frame].size;
    NSNumber *minLength = [lengthsByViewIndex objectForKey:viewIndex];
    CGFloat minLengthValue = [minLength doubleValue];
    
    if (isVertical)
    {
        frameSize.height = sender.bounds.size.height;
        if (delta > 0 ||
            frameSize.width + delta >= minLengthValue)
        {
            frameSize.width += delta;
            delta = 0;
        }
        else if (delta < 0)
        {
            delta += frameSize.width - minLengthValue;
            frameSize.width = minLengthValue;
        }
    }
    else
    {
        frameSize.width = sender.bounds.size.width;
        if (delta > 0 ||
            frameSize.height + delta >= minLengthValue)
        {
            frameSize.height += delta;
            delta = 0;
        }
        else if (delta < 0)
        {
            delta += frameSize.height - minLengthValue;
            frameSize.height = minLengthValue;
        }
    }
    
    [view setFrameSize:frameSize];
    viewCountCheck++;
}

The "continue" skips invalid priorities. You might replace this in your own code with an NSAssert instead, depending on how you like to handle minor errors.

The other point to notice is that we don't break out of the loop once the delta is fully applied — we still need to run setFrameSize: on each view to apply any size change in the perpendicular direction (vertically for columns or horizontally for rows).

This fragment doesn't show it but the code includes a second iteration over all the views, in order, which sets the origins of each view following the resize so they are all positioned correctly for their new sizes.

Hitting the minimum size

If all views are at their minimum and the split view cannot contract any further, the current implementation throws an exception giving the minimum size. This is so that you can configure the containing view (often a window) to respect this minimum and never try to make the NSSplitView smaller than this. If you don't like this behavior, you can remove the NSAssert3 statement in the setMinimumLength:forViewAtIndex: method.

Conclusion

You can download the sample project ColumSplitView.zip (60kb) to see the full PrioritySplitViewDelegate class.

The advantage to the PrioritySplitViewDelegate class is that it is generic: you don't need to write this code each time and it handles the common case of using an NSSplitView to contain columns and a main view. It offers an easy plug in solution for managing a split view in this arrangement.

It could probably be improved by changing the setMinimumLength:forViewAtIndex: and setPriority:forViewAtIndex: methods to something that prevents you from providing the wrong values for indices or number of lengths or priorities but the NSAsserts in the splitView:resizeSubviewsWithOldSize: method will pick up the most critical errors you might make.

StreamToMe iPhone App Released

2009-08-21T08:04:00.001-07:00

StreamToMe is an iPhone app I've written that streams video in most common formats from your Mac to the iPhone/iPod Touch — without prior conversion or copying. It supports the TV out cable for the iPhone, turning your iPhone+Mac into a wireless media center. I'm excited that it's finally on the App Store because I've been using it non-stop during development and I'm really happy with it.

Use your Mac to stream it

Your Mac can store hundreds of gigabytes and play almost any video format (Xvid, Flash Video, WMV, MPG, MP4 and more), in almost any size (from QCIF to 1080p), but your iPhone cannot. Take advantage of this power; run the free ServeToMe app on your Mac and make it do all the hard work by live-transcoding video to your iPhone.

Then to watch video all you need to do is open the StreamToMe app on your iPhone or iPod Touch, select the video and 5 seconds later it's playing. No prior conversion, no archive of iPhone-encodes, no waiting, no copying, no syncing.

Download StreamToMe from the iTunes App Store and enjoy!

For more information, see the StreamToMe product page or the StreamToMe FAQ.

Adding shadow effects to UITableView using CAGradientLayer

2009-08-21T02:59:00.001-07:00

Shadows can be a useful effect, drawing attention to the content of your view by separating the view from the background. They also look cool. In this post, I'll show you how to add shadows to a UITableView using three CAGradientLayers — one above the first row, one after the last row and one for under the navigation bar.

ShadowedTableView app

In this post, I'll present the following sample app:

In this screenshot, the rows are dragged downwards to reveal the three different shadows: under the navigation bar, above the first row and under the last row.

Download the sample project ShadowedTableView.zip (26kB). Last updated 2009-08-23.

CAGradientLayer

The CAGradientLayer was a handy addition in iPhone SDK 3.0 — it allows you to create an efficient, linear gradient in just a couple lines. In this sample app, is it used to draw the opaque gradients on the table rows as well as the transparent gradients of the shadows.

While not as flexible as CGContextSetShadow (which can draw shadows around multiple shapes simultaneously or curved edges), CAGradientLayer is very fast, so it shouldn't have a noticeable effect on the speed of your application.

Since CAGradientLayer requires iPhone SDK 3.0, if you need a similar effect on earlier versions of iPhone OS, you'll need to use CGGradientCreateWithColorComponents to draw the contents of a CALayer yourself or perhaps use a UIImageView (an image view is another alternative if you need non-straight edges).

Required steps

Adding the shadows can be done using a UITableView subclass. In this subclass, we need to perform the following steps:

Create the three CAGradientLayers
Place them and make sure they stay underneath the table's rows
Update the positions of the gradients when the table scrolls or grows

We can perform all these steps by overriding the layoutSubviews method.

Constructing the gradients

The construction of the CAGradientLayers is done lazily (i.e. as needed) in layoutSubviews (removing the need to override any constructors.

The three gradients are all constructed using the following method. The inverse parameter is used to generate the smaller gradient that fades-out upwards (for the shadow above the first table row).

- (CAGradientLayer *)shadowAsInverse:(BOOL)inverse
{
    CAGradientLayer *newShadow = [[[CAGradientLayer alloc] init] autorelease];
    CGRect newShadowFrame =
        CGRectMake(0, 0, self.frame.size.width,
            inverse ? SHADOW_INVERSE_HEIGHT : SHADOW_HEIGHT);
    newShadow.frame = newShadowFrame;
    CGColorRef darkColor =
        [UIColor colorWithRed:0.0 green:0.0 blue:0.0 alpha:
            inverse ? (SHADOW_INVERSE_HEIGHT / SHADOW_HEIGHT) * 0.5 : 0.5].CGColor;
    CGColorRef lightColor =
        [self.backgroundColor colorWithAlphaComponent:0.0].CGColor;
    newShadow.colors =
        [NSArray arrayWithObjects:
            (id)(inverse ? lightColor : darkColor),
            (id)(inverse ? darkColor : lightColor),
        nil];
    return newShadow;
}

Notice that the gradient goes from 50% black to 0% of the table's background color. It is important to use the table's actual background color, even though it may seem as though the 0% opacity on it would make it invisible. The mathematics of the gradient will cause the middle color to be 12.5% black + 12.5% background color, so the background color does have an effect on the gradient.

Placing the gradients

The simplest gradient to place is the one under the navigation bar — we just put it at the top of the UITableView.

The only tricky part is that the view, as a child of the UITableView will scroll downwards when the view scrolls (we want it to stay still and not scroll). To fix this issue, we'll offset the view by the same amount as the scroll offset (to keep it in place) and perform this frame adjustment inside a CATransaction with animation disabled (so that these offsets are not visible).

[CATransaction begin];
[CATransaction setValue:(id)kCFBooleanTrue forKey:kCATransactionDisableActions];

//
// Stretch and place the origin shadow
//
CGRect originShadowFrame = originShadow.frame;
originShadowFrame.size.width = self.frame.size.width;
originShadowFrame.origin.y = self.contentOffset.y;
originShadow.frame = originShadowFrame;

[CATransaction commit];

The gradients on the rows are a little trickier. First, we only want to add them if the rows are visible. Second, we want to make them child layers of their respective rows so that if the rows animate, the shadows will follow them.

Update 2009-08-23: adding the shadows as children of the cells themselves is a new addition to improve performance during animation from the original post (which arranged the rows directly in the UITableView.

NSIndexPath *firstRow = [indexPathsForVisibleRows objectAtIndex:0];
if ([firstRow section] == 0 && [firstRow row] == 0)
{
    UIView *cell = [self cellForRowAtIndexPath:firstRow];
    if (!topShadow)
    {
        topShadow = [[self shadowAsInverse:YES] retain];
        [cell.layer insertSublayer:topShadow atIndex:0];
    }
    else if ([cell.layer.sublayers indexOfObjectIdenticalTo:topShadow] != 0)
    {
        [cell.layer insertSublayer:topShadow atIndex:0];
    }

    CGRect shadowFrame = topShadow.frame;
    shadowFrame.size.width = cell.frame.size.width;
    shadowFrame.origin.y = -SHADOW_INVERSE_HEIGHT;
    topShadow.frame = shadowFrame;
}
else
{
    // Remove the shadow if it isn't visible
    [topShadow removeFromSuperlayer];
    [topShadow release];
    topShadow = nil;
}

This is the placement of the top shadow (the one above the first row). We only attend to it if the first row is visible and when we do, we always ensure that it is the 0-th sublayer of the appropriate cell.

Other tidbits

The sample project also contains the GradientView class which is a very simple subclass of UIView that sets the UIView's layerClass to CAGradientLayer and uses that to draw a gradient across the view. This is the view that is set as the UITableViewCell's backgroundView to draw the views in this sample project.

The project also contains the ClearLabelsCellView which is a UITableViewCell subclass that overrides setSelected:animate: to fix the fact that this method always sets the default textLabel and detailTextLabel backgroundColor to white — instead setting it to clearColor so you can combine the default text labels with non-white cell backgrounds.

- (void)setSelected:(BOOL)selected animated:(BOOL)animated
{
    [super setSelected:selected animated:animated];

    self.textLabel.backgroundColor = [UIColor clearColor];
    self.detailTextLabel.backgroundColor = [UIColor clearColor];
}

Conclusion

Download the sample project ShadowedTableView.zip (26kB). Last updated 2009-08-23.

The ShadowedTableView is self-contained so you can drop it easily into a project.

In its current form, it only works well for full-width, rectangular, contiguous tables — so it works well for "plain" tables but is not suited to "grouped" tables. It also looks best if the table row separator is set to "none".

Animating a window to fullscreen on the Mac

2009-08-14T06:47:00.001-07:00

Many Mac OS X applications animate their regular application windows to fullscreen but since there's no dedicated method for the task, there's no standard Apple documentation that covers the operation. If you look for examples on the web, you'll find numerous examples that perform this operation using old APIs or methods intended for permanently fullscreen games (the wrong approach for an application window). In this post I'll show you my preferred approach for making an application window fullscreen, with continuous display and smooth animation.

Introduction

The sample app for this post has one window:

When you choose the "Toggle Fullscreen" menu item, the content area of the window (not the window's frame) will animate to fill the entire screen (the Dock and menubar will hide).

You can download the Xcode 3.1 project here: FullscreenImage.zip (277kB).

Fullscreen windows

There are two basic types of fullscreen on the Mac:

Screen takeover — where one view gains exclusive control of the screen.
Basic fullscreen window — where a regular window occupies the whole screen without occlusions.

The first is normally recommended for games where you never want the window to be interrupted. For an example of this type of window, see my earlier post An Asteroids-Style Game in Core Animation: Part 1.

The second option has the advantage that it can be interrupted by other windows. For example: Exposé, Command-Tab and notification windows will continue to function. This is the approach that I will detail in this post.

Animating a window to fullscreen

Zooming a window to the full size of the screen can be done using the setFrame:display:animate: method:

[mainWindow
    setFrame:[mainWindow frameRectForContentRect:[[mainWindow screen] frame]]
    display:YES
    animate:YES];

This will smoothly zoom a window to fill the available screen area.

On its own though, it has a few limitations:

It doesn't hide the menubar or Dock — so it doesn't actually fill the screen.
It doesn't hide the frame of the window, so the frame remains visible around the outside.
It doesn't change the window's level so panels and other window may still overlap the expanded window.

Hiding the menubar and Dock

There are two different ways to hide the menubar and the Dock. They are:

SetSystemUIMode(kUIModeAllHidden, kUIOptionAutoShowMenuBar);

and

[NSMenu setMenuBarVisible:NO];

Despite the wording of the NSMenu method, it does also hide the Dock.

The first method has more options — the biggest of which is the kUIOptionAutoShowMenuBar which will reshow the menubar if you move the mouse to the top of the screen — but unfortunately, this method is Carbon, not Cocoa, so it requires you to link against the Carbon frameworks.

I prefer the NSMenu method for its simplicity and Cocoa linkage. This does mean that if you want to show the menubar, you'd need to create an NSTrackingArea or something similar to detect when the mouse is over the menubar and show it again.

Update 2009-09-20: In Snow Leopard, you can use the -[NSApplication setPresentationOptions:] method to handle all that SetSystemUIMode could do and more, all with standard Cocoa linkage.

The other consideration with hiding the menubar is that you should only do it if the window you are resizing is actually on the [[NSScreen screens] objectAtIndex:0] (the screen that shows the menubar). i.e.:

if ([[mainWindow screen] isEqual:[[NSScreen screens] objectAtIndex:0]])
{
    [NSMenu setMenuBarVisible:NO];
}

Hiding the window frame

The next issue to address is the window frame: we need to hide it. The problem is that you can't hide the frame of an existing window.

Instead, what we do is create a new, borderless window and swap the contentView from the old window into the new window.

fullscreenWindow = [[FullscreenWindow alloc]
    initWithContentRect:[mainWindow contentRectForFrameRect:[mainWindow frame]]
    styleMask:NSBorderlessWindowMask
    backing:NSBackingStoreBuffered
    defer:YES
    screen:[mainWindow screen]];
[fullscreenWindow setLevel:NSFloatingWindowLevel];
[fullscreenWindow setContentView:[mainWindow contentView]];
[fullscreenWindow setTitle:[mainWindow title]];
[fullscreenWindow makeKeyAndOrderFront:nil];

There are three other points to notice in this code:

The window level is NSFloatingWindowLevel (so that the window will appear above NSPanels and similar windows).
The window title is set to match the old window (so that the new window will appear the same in Exposé).
The window is actually a subclass so we can override the method canBecomeKeyWindow to return YES (since it returns NO by default for NSBorderlessWindowMask windows).

Other minor points

When swapping the contentView between windows, the destination window should not be onscreen (orderedOut:) otherwise flicker can occur.

If you run the whole process while the window is miniaturized in the Dock, numerous screen glitches will occur. It's best to deminiaturize before you start (this must happen before you hide the Dock).

Conclusion

You can download the Xcode 3.1 project here: FullscreenImage.zip (277kB).

The whole code is one method in the sample app — an easy copy and paste into any application.

Safe, threaded design and inter-thread communication

2009-08-09T00:36:00.001-07:00

The Foundation framework provides all the tools you need for inter-thread communication — without needing to handling locks and synchronization yourself. I'll show you Cocoa's tools for inter-thread communication, notifications and easy synchronization — including far simpler code for posting NSNotifications on the main thread than the Cocoa documentation suggests.

Introduction

Multi-threaded code has a reputation for being difficult to write and prone to deadlocks, race conditions and unpredictable behaviors.

While this remains true if you are forced to handle locking yourself, Foundation provides all the tools you require to manage typical multi-threaded situations so that you can avoid the risks of locks entirely.

This post comes from my shock at Apple's suggestion (in their Delivering Notifications To Particular Threads) that something as simple as sending an NSNotification from one thread to another should take dozens of lines of code and a dedicated class for the purpose.

It isn't that difficult. Sending data between threads (including notifications) is a one line job.

Rules for safe simple threading

Simple thread safety in Cocoa requires just two rules:

Every variable or object must nominally belong to a thread (although may be completely handed over to a different thread) and must not be used in multiple threads without handover (unless it is on the list of explicity thread-safe classes).
All communication between threads (after thread startup) should use performSelector:onThread:withObject:waitUntilDone: and both the receiver and the "object" should belong (or be handed over) to the target thread.

The only limitation with this approach is that any thread that receives communication must be running an NSRunLoop. Since communication after construction is normally one-way (from worker thread back to the main thread) this is rarely a significant limitation. Other threads can invoke the [NSRunLoop currentRunLoop]'s runMode:beforeDate to process the run loop and receive messages.

A lot of multi-threaded code does not follow these rules. A lot of multi-threaded code uses a careful system of locks, synchronized sections, volatile variables and atomic operations to allow single objects to be accessed simultaneously from multiple threads. This does work but generally speaking: you don't want to design code this way. It's tricky, confusing and prone to errors. To illustrate, you can have a look at how many changes I had to make to my AudioStreamer code between the first and second versions — rock-solid, manually-locked code is annoying and difficult to write.

Instead, as much as possible, you should write your code to keep all objects compartmentalized to individual threads and to restrict communication between threads to method invocations using performSelector:onThread:withObject:waitUntilDone:. To explain how this works, I'll show a simple example of something running in a separate thread and show how it can perform all its inter-thread communication using existing Foundation methods to automatically handle all thread safety issues.

Scenario: writing to a network NSFileHandle in a worker thread

One of the simplest situations where you may want multithreading is writing to a network socket's NSFileHandle. This is a synchronous operation (blocks until complete) so it is a good idea to perform this in a worker thread so that the main thread of your program can remain responsive.

The following class is an NSOperation subclass. If you don't know about NSOperation, it's an object that you can add to an NSOperationQueue to have the object's main method run in a separate thread (see Apple's Threading Programming Guide). While NSThread's detachNewThreadSelector:toTarget:withObject: is the best way to launch a single worker thread, NSOperations are the best way to run a series threaded tasks (or has been since serious bugs in it were fixed in 10.5.7).

This class' init method takes an NSFileHandle and an NSData object on construction and writes the data to the file handle in its main method.

@interface FileWriteOperation : NSOperation
{
    NSFileHandle *fileHandle;
    NSData *data;
}
@end

@implementation FileWriteOperation

- (id)initWithFileHandle:(NSFileHandle *)aFileHandle data:(NSData *)aData
{
    self = [super init];
    if (self != nil)
    {
        fileHandle = [aFileHandle retain];
        data = [aData retain];
    }
    return self;
}

- (void)main
{
    NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];
    @try
    {
        [fileHandle writeData:data];
        // At this point, the write has succeeded
    }
    @catch (NSException *e)
    {
        // At this point, the write has failed
    }
    @finally
    {
        [pool drain];
    }
}

- (void)dealloc
{
    [fileHandle closeFile];
    [fileHandle release];
    [data release];
    [super dealloc];
}

@end

The NSOperation is created and its thread is launched as follows:

// Assume the operationQueue, fileHandle and fileData already exist
[operationQueue
    addOperation:
        [[[FileWriteOperation alloc]
            initWithFileHandle:fileHandle
            data:fileData]
        autorelease]];

To follow the first rule of thread-safety, after the FileWriteOperation is constructed, the fileHandle value passed into its initWithFileHandle:data: method cannot be used again outside the NSOperationQueue's worker thread.

Communicating success or failure

The above class works but doesn't have any way of communicating the result. What would be good is if we could send a writeFinishedWithSuccess:YES at the "write has succeeded" line and a writeFinishedWithSuccess:NO at the "write has failed" line.

The unsafe way of doing this is to invoke a method on another object sending the result:

    [responseHandler writeFinishedWithSuccess:YES]; // BAD!!

If responseHandle belongs to another thread, then this method could cause any number of race conditions and other multi-threading issues.

The solution though is exceptionally simple:

    [responseHandler
        performSelectorOnMainThread:@selector(writeFinishedWithSuccess:)
        withObject:[NSNumber numberWithBool:YES]
        waitUntilDone:NO];

This assumes that responseHandler is a nominally "main thread" object. You can use the performSelector:onThread:withObject:waitUntilDone: method and specify a different thread if you need to send the response elsewhere.

You'll notice that the parameter has to be an object in this case ([NSNumber numberWithBool:YES] instead of simply YES) and any parameter that you pass to another thread should not be used again in the current thread.

Delivering Notifications To Particular Threads

Of course, the FileWriteOperation class shown above doesn't have a responseHandle object that it can notify when it is done, so I'd rather use an NSNotification sent to the NSNotificationCenter and if any object wants to receive the notification, it can.

The NSNotificationCenter itself is thread-safe but it delivers the notifications on the thread in which you invoke postNotification: so if you expect the observers of that notification to belong to a different thread, you've just broken those objects' thread safety.

Normally it is a good idea to deliver all notifications on the main thread. We can do this as follows:

    [[NSNotificationCenter defaultCenter]
        performSelectorOnMainThread:@selector(postNotification:)
        withObject:
            [NSNotification
                notificationWithName:@"FileWriteOperationSucceeded"
                object:self]];

Some classes follow a different behavior of delivering notifications to the thread on which they were constructed (not necessarily the main thread). To follow this behavior, simply save the [NSThread currentThread] on construction and perform the postNotification: selector on that thread.

You may have noticed that the notification is passing "self" from one thread to another — breaking the thread ownership of "self". This is only really safe in one of the following cases:

Handover — the parameter will never be used on this thread again.
In this case, if "self" is complete on the worker thread (for example at the bottom of the main method shown above). In this case, the object is passing itself back to the other thread.
Thread-safe — if the class or specific methods are guaranteed to be thread-safe.
In this case, if the only methods invoked on self are retain, release and the default pointer comparison isEqual: method (these are the methods invoked when removing from an NSMutableArray). These are guaranteed thread-safe methods.

If neither of these are true then you can't pass self (or any other parameter) safely between threads.

Conclusion

The purpose of this article is to communicate two ideas:

Carefully locking and synchronizing makes programming hard but if you design your objects to be used on only one thread at a time, then they are thread-safe without the need for locks or synchronzation (if needed, split your objects into components for separate threads).
Use inter-thread communication to keep objects in separate threads up-to-date with each other. In Cocoa, this is very simple but you do need to ensure that all parameters you pass are either thread-safe objects or handover objects.

Frankly, Apple has made of meal of the Delivering Notifications To Particular Threads code. I would be happy to see it completely changed — you should never need something so complex just to deliver notifications to another thread.

Of couse, there are always situations where you can't run an NSRunLoop to process performSelector:onThread:withObject:waitUntilDone: messages. There are also situations where you feel that one of your object s must be multi-threaded (rather than single thread exclusive). Either of these cases requires will require a synchronized or locked solution but my recommendation is to try to find an NSRunLoop and thread exclusive solution first as these are significantly easier to manage and prone to fewer potential problems.

Control and configuration of applications through Info.plist

2009-08-03T23:36:00.001-07:00

The Info.plist file is home to the metadata about your application used by the operating system. Most Cocoa programmers know that it stores the bundle identifier, icon name and version number of an application but the Info.plist can also control access to essential iPhone hardware resources and can change the very nature of your Mac OS X applications. In this post, I'll cover basic Info.plist usage and also explain some of the rarer settings.

The default fields: identifiers, icons and version numbers

The Info.plist is the main source of metadata that the operating system has to learn information about your application. Everything that the operating system may need to know (names, icons, supported file types, URL types, NSApplication subclasses) may all be specified in the Info.plist.

The file itself is familiar to almost all Cocoa programmers since Xcode inserts one automatically into every project created from an application template.

Probably the most common settings are:

CFBundleIdentifier — the identifier for your application, normally in the form "com.[company].[application]". The iPhone tries to fill in the application name from the Project's product name but will fail if you ever try to build for a device if there are spaces or differences in capitalization so you may just want to set this manually.
CFBundleIconFile — almost every application I ship names its icon "Icon.[png/icns]". Why Apple can't put a default value here, I don't know.
CFBundleVersion — this isn't the only version number since you can embed a different version in the Project Settings. If you don't have a formal build system in place though, you'll need to make certain that this number is always different every time you give a build to someone to test (a crash log is useless if you can't guarantee which version it came from).

How Xcode builds the Info.plist

Most of the other settings that are in the Info.plist by default have either good initial values (like the NSMainNibFile value which is automatically set to the name of the Nib file that the template itself includes), are largely pointless (like the CFBundleSignature which is a campy Mac OS 9 throwback) or are generated from values defined in the Project settings (like the CFBundleName).

The reason why the fields in the Info.plist can be generated from "Project settings" fields is that their values are filled in when the Info.plist file is "built" by Xcode.

Building the Info.plist file is actually the first stage in building for an application — the file is build immediately after creating the directory structure for the bundle. You can control the Info.plist's build settings in the "Packaging" section of the Target settings — including setting a different Info.plist for each target if needed.

While most stages of a build are handled by an external process (like gcc or ibtool), if you look through the Build Results window log, you'll notice that the Info.plist is built by a tool that identifies itself as <com.apple.tools.info-plist-utility>. This isn't actually a separate tool — it is described as "abstract" by the "Built-in compilers.pbcompspec" in the DevToolCore.framework and is implemented internally by the XCInfoPlistUtilityCommandInvocation class in the DevToolCore.framework. Xcode passes the arguments into this class (like it would for any other build stage) and the class parses the arguments and handles all the work itself.

Reading from the Info.plist in your program

While the Info.plist is primary metadata that your program advertises to the operating system and external programs, your program can easily read any of the fields in the Info.plist for its own purposes using the NSBundle's infoDictionary. For example, the URL to an iPhone app's own page on the iTunes App Store would be:

NSURL *appURL =
    [NSURL URLWithString:[NSString stringWithFormat:@"http://www.itunes.com/app/%@",
        [[[[NSBundle mainBundle] infoDictionary] objectForKey:@"CFBundleDisplayName"]
            stringByAddingPercentEscapesUsingEncoding:NSUTF8StringEncoding]]];

Technically, you can store anything you want in the Info.plist file but generally your own data would be better put in a separate file so you don't slow the operating system down when it needs to open and parse the Info.plist file to extract the data it needs.

Essential iPhone Info.plist entries

Aesthetic settings

A number of fields are required in the Info.plist to control aesthetic options for an iPhone application. These include:

UIPrerenderedIcon — set this to disable the gloss highlight that the Springboard applies to your application's icon.
UIInterfaceOrientation — use this to start your application in a non-portrait orientation.
UIStatusBarStyle — use this to enable black or transparent status bars.

Avoiding WiFi disconnections

Any iPhone application that requires a WiFi connection must set UIRequiresPersistentWiFi to <true/>, otherwise the iPhone will abruptly disconnect the WiFi connection after 30 minutes of use. No warning, no error: 30 minutes and you'll lose WiFi without this flag.

Invoking your iPhone application by URL

The CFBundleURLTypes key allows you to specify URL schemes that will cause the iPhone to switch to your application. No, you can't override the schemes for the built-in applications.

If your application is launched using a URL type named scheme, then you can also provide a different startup image "Default-scheme.png" instead of the regular "Default.png".

Essential Mac OS X Info.plist entries

Changing the application type

You can create an application with no UI — no appearance in the Dock, no menubar and can't be the frontmost application — by setting the LSBackgroundOnly flag in the Info.plist.

Realistically though, you're more likely to make your application LSUIElement. The reason why this flag is better, is that your application can be frontmost if you open a window but the other traits of LSBackgroundOnly remain (no appearance in the Dock and no menubar).

Why would you want an application with no appearance in the Dock? If you're making an NSStatusBar application (little applications that run as icons in the right of the menubar).

The following code adds an entry to the status bar when the application starts:

- (void)applicationDidFinishLaunching:(NSNotification *)notification
{
    statusItem = [[[NSStatusBar systemStatusBar]
        statusItemWithLength:NSSquareStatusItemLength] retain];
    
    [statusItem setMenu:statusMenu];
    [statusItem setHighlightMode:YES];
    [statusItem setToolTip:@"My Status Bar App"];
    [statusItem setTitle:nil];
    [statusItem setImage:[NSImage imageNamed:@"StatusBarIcon"]];
}

Accepted document types

Document types accepted by an application can be set by editing the Info.plist file (the CFBundleDocumentTypes dictionary) although this is easier to do on the Properties tab of the Target settings.

Conclusion

Looking back over the range of topics that I've covered, you can see that the Info.plist controls a very diverse range of application settings and capabilities. There are many more options that I haven't listed here so if you're trying to specify default localizations, change the NSApplication subclass, set environment variables for your application, specify a minimum OS versions and more, have a look at Runtime Configuration Guidelines: Property List Key Reference for other fields.

Rules to avoid retain cycles

2009-07-27T17:20:00.001-07:00

Normally in Objective-C, if you follow the basic rule of maintaining a positive retain count for everything you need to hold onto and releasing when you're done, memory management will "just work" — until you create a retain cycle and suddenly no objects in the cycle will ever be freed. In this post, I'll explain retain cycles, common cases where they occur and the solutions to these problems.

Memory Management

All memory in a computer program must be allocated before it can be used and if you want to reuse that memory later for another purpose, it must be deallocated when you are done with it.

In garbage collected environments, programmers don't need to handle the allocation and deallocation themselves; the allocation, retaining, releasing and deallocation are handled automatically — but these steps still occur. Unfortunately, this automatic work is CPU and memory hungry; garbage collection is slower and takes more memory than manual memory management.

So, on the iPhone and in performance critical Mac OS X applications, we still have to handle memory management ourselves and that means methodically following the rules of Objective-C memory management:

If you want to "own" an object, you must alloc, copy or retain it.
Always release or autorelease when you are done with an object.

Unfortunately, if a retain cycle occurs, these rules are not enough to guarantee memory is freed correctly.

Object hierarchies and retain cycles

A quick explanation of retain cycles requires that I quickly summarize how hierarchies of objects are tied together. Specifically: objects in a hierarchy are created, owned and freed in a chain along the hierarchy.

In this example, "Some Object" owns Parent which in turn owns the Child.

When the hierarchy is no longer needed, "Some Object" sends a release to the Parent. The Parent's retainCount hits zero, causing its dealloc method to run. In its dealloc method, it sends a release to the Child, successfully freeing the chain. This is the correct behavior.

The problem of retain cycles occurs when the Child needs a pointer to the Parent for any reason and it chooses to retain the Parent. This alters the diagram to the following:

In this diagram, when "Some Object" sends a release to the Parent, the retainCount does not reach zero (since the Child's retain of the Parent has incremented the retainCount for itself). Since the Parent's retainCount does not reach zero, its dealloc method never gets called and so it never sends a release to the Child.

This is a retain cycle: with the Parent retaining the Child and the Child retaining the Parent, they continue to exist, cut off from the rest of the objects in the program but keeping themselves alive. They have leaked.

Avoiding retain cycles rule #1: An object must never retain its parent

The first rule to avoid retain cycles is that an object must never retain its parent. This changes the previous diagram to the following:

This is the easy case: an object should never retain its parent when it makes a pointer to the parent.

Notice that the term "weak pointer" is used. A weak pointer is one that does not retain its target.

Of course, now that the child doesn't retain the parent, the child must be aware of any situation where the parent becomes invalid (freed) and not use its pointer to the parent in that case.

So, either:

The parent must set the parent pointer in the child to nil when the relationship is broken.

The design must guarantee that the parent pointer is always valid for the child's lifetime (or if the parent uses autorelease to free children, valid except in the child's dealloc method).

These two options apply to weak pointers in general: once the target becomes invalid, the pointer must be set to nil or the design must otherwise prevent invalid use.

Generally speaking, the option of setting to nil is much safer. The only downside is that it requires a way of detecting the pending release of the target and nominating an object whose role it is to make that detection and update the pointer accordingly. It is easy here where the parent (the target of the weak pointer) knows about the child and is also the hierarchical manager of the child but not all retain cycles are one-to-one like this.

Avoiding retain cycles rule #2: no hierarchical ancestor can be retained

It may seem obvious but this is where retain cycles can be subtle: an object must not retain any of its parent's parents, or any of their parents.

This rule applies to many different situations. Some important considerations in Cocoa:

If an object retains an NSArray, NSDictionary or NSSet that collection must not retain the object or any of its parents.
If an object retains an NSInvocation where one of the arguments is the object or one of its ancestors, the NSInvocation may not retain its arguments.

If you want to store a collection of objects that may include one or more parents, you may want to consider one of the collections capable of non-retained pointers ("weak" collections):

A CFArray, CFDictionary or CFSet with NULL for the callbacks structure. i.e.:
CFArrayCreateMutable(NULL, 0, NULL);.
+[NSPointerArray pointerArrayWithWeakObjects] (Mac OS X only)
+[NSMapTable mapTableWithWeakToWeakObjects] (Mac OS X only)
+[NSMapTable hashTableWithWeakObjects] (Mac OS X only)

In the rare situation where you must put a parent into a collection which retains its contents (like NSArray) you can wrap the contents in a non-retained object NSValue. i.e.:

[arrayOfParents addObject:[NSValue valueWithNonretainedObject:aParent]];

Despite this non-retain requirement for direct ancestors, it is okay to retain non-direct ancestors. However, once an object retains a non-direct ancestor, it becomes a direct ancestor to the object it retains.

For example, consider a situation where one child of a parent retains another:

Before the "senior" child retained the other, they were both level siblings. Once one child retains another, it becomes a direct ancestor to the other. This now "junior" child may not retain its senior sibling without creating a loop. Any connection from this "junior" child back to the "senior" child must follow the "weak pointer" rules.

If you have lots of sibling nodes that you'd like to connect in complex ways, it's best to leave the ownership to the parent and connect all the siblings using non-retained pointers.

Avoiding retain cycles rule #3: "Connection" objects should not retain their target

Any object which connects itself to an arbitrary target object, without knowing their relationship, must not retain its target.

Connection objects include:

objects with a target and action (like a button)
objects that take a delegate
observees (objects to which observers are added)

Lets consider this by looking at the example of a button in a user-interface. A button connects the view hierarchy (through the button's superview) to the target of its action (it invokes the action method on its target when clicked).

A button must not retain its target. The reason for this becomes clear when you consider that a connection may need to point to a parent object:

This diagram models the common situation where button invokes a method on the controller. The "Parent" is the view controller, the "Child" is the view which contains the button and the "Object with connection" is the button.

Clearly, if the button retained its target, there would be a retain cycle.

Obviously though, this creates a management problem: the button's controller must ensure that its target is updated if the target disappears (since the button object won't notice on its own).

Responsibility for maintaining connections invariably lies with that object's manager — following the design of your code, you must decide which object is responsible for managing the connection and it must detect when the connection becomes invalid and set it to nil or delete the connection entirely.

Fortunately, in most situations the solution is straightforward: the target is ultimately the owner and controller of the connection object, so the target just needs to release its children correctly when it is released and the connection will never persist past the lifetime of the target.

Avoiding retain cycles rule #4: use "close" methods to break cycles

If you have a hierarchy that is difficult to work out, it may be easier to retain any object you wish, and implement a "close" method to address the problem of cycles. A "close" method is one that is guaranteed to be sent to an object when its primary function is complete.

An example of this is a retain cycle between two NSViews. If you want to create retain cycles between two views, then go ahead. All you need to remember to do is disconnect each view in its willRemoveSubview: method.

The willRemoveSubview: acts to warn each view about a pending removal from the display (an end to its primary function) and the method is sent regardless of retain count — so you can use it to break any possible retain cycles so that the object will be dealloc'd as normal when its parents release it.

Avoiding retain cycles rule #5: temporary retains must be temporary

Any of these rules can be broken for short periods of time — however the rule must by "unbroken" automatically, without further intervention, for example: when an animation or other triggered process completes.

This is particularly useful for actions expected to delete, disrupt, sort or rearrange hierarchies temporarily. You must remain mindful that this could inflate memory use if you hold on for too long, so only use this approach sparingly.

An example of a temporary broken rule is the NSURLConnection delegate. By default, a delegate should not be retained as it is the target of an arbitrary connection (see Rule #3). However, an NSURLConnection's use of its delegate is guaranteed to complete automatically (either by connection complete or by timeout) so this object can safely retain its delegate. To be a good citizen in this situation, the NSURLConnection also provides the cancel method which acts as a "close" and will release the delegate sooner if desired (although the release is deferred through the run loop; it is not synchronous to the method invocation).

Conclusion

You may be tempted to retain every object you use out of fear that it will disappear while you're using it. Unfortunately, you can't simply retain everything — you must be aware of the hierarchical structure and think about what you are retaining and why.

I've listed 5 rules here but if you want a simpler message to remember: an object may only retain something indefinitely if it is hierarchically senior. If you don't know which object is senior, you must work it out before you retain. If there is no clear senior object — you should redesign so that there is.

Temporary files and folders in Cocoa

2009-07-23T00:09:00.001-07:00

If you need to use temporary files in your application and you search the Cocoa documentation for "temporary file", you're unlikely to find anything that explains how to create one. Since temporary files and folders are subject to a number of security issues and race conditions when done wrong, it is important to know the correct way to create them. I'll show you some code that you can copy and paste into your applications to create temporary files and folders safely.

Introduction

With large amounts of RAM on modern computers and alternatives such as the cache directories and application support directories, genuine temporary files are not needed in most Cocoa applications. Even when they are needed, for atomic write operations or for Core Data databases, Cocoa libraries often create them automatically.

Eventually though, you're likely to encounter a situation where you need to create a temporary file yourself. You need to be careful when creating temporary files because:

Predictable temporary file locations can be a security hole in your applications.
On Mac OS X, multiple users on the computer may have their own copies of your application open, so the creation must be atomic (safe when concurrent).

In addition to this, you must be able to find the correct directories to place your files, be aware of the lifetime of files in these locations and manage cleanup correctly when you are done.

Required steps

Choosing the right enclosing directory

The directory for temporary files needs to be writeable by the current user. This means that the directory will need to be user-specific.

The correct directory is almost always the one returned by the Foundation function NSTemporaryDirectory. This directory is unique for each user (so each user has write permissions to it).

If you choose this directory though, it is important to know that it is cleaned out automatically every 3 days but otherwise persists between application launches and reboots. This directory is in a hashed location (not predictable in advance) and is therefore safe against security issues associated with predicatable locations.

If you need a location that can persist longer than 3 days, you probably want to use the Application Support directory or a Cache directory instead. Both of these locations are permanent (until your application deletes the contents) but Application Support is considered "important data" and backed up by Time Machine, whereas Cache is considered "user deletable at any time" and is not backed up. The backup point is important: don't store large amounts of temporary data in a location that will fill someone's backup drive.

These alternate directories are obtained using the Foundation function NSSearchPathForDirectoriesInDomains with a first parameter of NSApplicationSupportDirectory or NSCachesDirectory, a second parameter of NSUserDomainMask (occasionally a different value if you need a directory shared between users on the system or network — but this is uncommon). This function returns an array but you'll normally get just one result if you use NSUserDomainMask and you'll need to append your bundle identifier to get a location unique to your application.

// an alternative to the NSTemporaryDirectory
NSString *path = nil;
NSArray *paths = NSSearchPathForDirectoriesInDomains(
    NSCachesDirectory, NSUserDomainMask, YES);
if ([paths count])
{
    NSString *bundleName =
        [[[NSBundle mainBundle] infoDictionary] objectForKey:@"CFBundleIdentifier"];
    path = [[paths objectAtIndex:0] stringByAppendingPathComponent:bundleName];
}

This path value can be used instead of the NSTemporaryDirectory() invocations in the code samples below.

Creating and opening a file or subdirectory

To avoid concurrency issues (race conditions), you need to choose a name for any file or directory placed directly in the temporary directory that is unique but which also can't be stolen by another process between choosing the name and creating/opening the file or directory. Even though NSTemporaryDirectory() is unique for each user, you still must avoid potential conflicts within the user's account.

To do this, we use the POSIX function mkstemp for files and mkdtemp for directories. The former will return an already open file descriptor for the file and the latter will have already created the directory for us.

We could simply generate a universally unique identifier (UUID) and use that for the filename but these IDs are guessable which can create security problems in obscure cases where we don't also check for a name conflict — better to use something that looks for a collision, in the extremely unlikely case that it occurs. If you must use a UUID filename instead of mkstemp for some reason, be certain that it is for non-critical data.

Creating a temporary file:

NSString *tempFileTemplate =
    [NSTemporaryDirectory() stringByAppendingPathComponent:@"myapptempfile.XXXXXX"];
const char *tempFileTemplateCString =
    [tempFileTemplate fileSystemRepresentation];
char *tempFileNameCString = (char *)malloc(strlen(tempFileTemplateCString) + 1);
strcpy(tempFileNameCString, tempFileTemplateCString);
int fileDescriptor = mkstemp(tempFileNameCString);

if (fileDescriptor == -1)
{
	// handle file creation failure
}

// This is the file name if you need to access the file by name, otherwise you can remove
// this line.
tempFileName =
    [[NSFileManager defaultManager]
        stringWithFileSystemRepresentation:tempFileNameCString
        length:strlen(tempFileNameCString)];

free(tempFileNameCString);
tempFileHandle =
    [[NSFileHandle alloc]
        initWithFileDescriptor:fileDescriptor
        closeOnDealloc:NO];

It is important to handle all reading and writing from the temporary file using this fileDescriptor or something created directly from the fileDescriptor like the NSFileHandle in this example. This guarantees the operation remains safe for concurrency — if the fileDescriptor is closed before use, a race condition could occur.

The "X"s in the file name are replaced by the unique hash for the file's name. You'll probably want to replace the "myapptempfile" name with something appropriate, although it isn't required (the file is guaranteed unique regardless).

Also notice the use of fileSystemRepresentation and stringWithFileSystemRepresentation:length: to convert to and from the C strings — this is helpful to handle weird path quirks on different filesystems.

Creating a temporary folder:

NSString *tempDirectoryTemplate =
    [NSTemporaryDirectory() stringByAppendingPathComponent:@"myapptempdirectory.XXXXXX"];
const char *tempDirectoryTemplateCString =
    [tempDirectoryTemplate fileSystemRepresentation];
char *tempDirectoryNameCString =
    (char *)malloc(strlen(tempDirectoryTemplateCString) + 1);
strcpy(tempDirectoryNameCString, tempDirectoryTemplateCString);

char *result = mkdtemp(tempDirectoryNameCString);
if (!result)
{
    // handle directory creation failure
}

NSString *tempDirectoryPath =
    [NSString
        stringWithFileSystemRepresentation:tempFileNameCString
        length:strlen(result)];
free(tempDirectoryNameCString);

You can now use the tempDirectoryPath as the container for any files. As with the previous example, you probably want to replace "myapptempdirectory" with something appropriate to your application and usage.

Conclusion

You could simply create a file in the /tmp directory but this approach is filled with many problems — write permissions, concurrency issues, security issues and duration or persistence issues.

Fortunately, the code to create a temporary file or temporary directory is consistent — you can normally use these code samples without modification. The only choices you need to make is whether to use an alternative directory (like the Application Support directory or the Caches directory).

A simple, extensible HTTP server in Cocoa

2009-07-13T18:17:00.001-07:00

HTTP is one of the simpler protocols to implement for communication between computers. On the iPhone, since there are no APIs for data synchronization or file sharing, embedding an HTTP server is one of the best ways to transfer data from your iPhone application to a computer. In this post I'll show you how to write your own simple but extensible HTTP server. The server classes will also work on Mac OS X (Cocoa un-Touched).

Introduction

In this post I will present the following sample application:

The application is very simple: you can edit text and save it to a file (it is always saved to the same file).

While the application is running, it also runs an HTTP server on port 8080. If the path "/" is requested, it will return the content of the saved file. All other requests return a 501 error.

To transfer the text file from the iPhone application, just enter the IP address of the phone followed by ":8080" in any web browser.

HTTPServer and HTTPResponseHandler classes

The approach I use for an HTTP server involves two classes: the server (which listens for connections and reads data up to the end of the HTTP header) and the response handler (which sends the response and may choose to read from the connection past the header).

The key design choice for me was simplicity of each new response implementation: the server and response classes are designed so that a new response implementation need only implement three methods:

canHandleRequest:method:url:headerFields: — to decide if the implementation can handle a specific request
startResponse — to begin writing (or completely write) the response
load — all subclasses should implement the standard +[NSObject load] method to register themselves with the base class

It is just a tiny HTTP server but the approach should allow you to quickly integrate HTTP communications into any application.

Opening a socket for listening

Most server communications, HTTP included, begin by creating a socket for listening.

Sockets in Cocoa can be created and configured entirely using the BSD sockets code but it's often marginally easier to use the CoreFoundation CFSocket API where possible. Unfortunately, that only makes it marginally easier — we still have a large block of boilerplate code to throw down just to open a socket.

From the -[HTTPServer start] method:

socket = CFSocketCreate(kCFAllocatorDefault, PF_INET, SOCK_STREAM,
    IPPROTO_TCP, 0, NULL, NULL);
if (!socket)
{
    [self errorWithName:@"Unable to create socket."];
    return;
}

int reuse = true;
int fileDescriptor = CFSocketGetNative(socket);
if (setsockopt(fileDescriptor, SOL_SOCKET, SO_REUSEADDR,
    (void *)&reuse, sizeof(int)) != 0)
{
    [self errorWithName:@"Unable to set socket options."];
    return;
}

struct sockaddr_in address;
memset(&address, 0, sizeof(address));
address.sin_len = sizeof(address);
address.sin_family = AF_INET;
address.sin_addr.s_addr = htonl(INADDR_ANY);
address.sin_port = htons(HTTP_SERVER_PORT);
CFDataRef addressData =
    CFDataCreate(NULL, (const UInt8 *)&address, sizeof(address));
[(id)addressData autorelease];

if (CFSocketSetAddress(socket, addressData) != kCFSocketSuccess)
{
    [self errorWithName:@"Unable to bind socket to address."];
    return;
}

This is a large block of code but it's really only doing one thing: opening a socket to listen for TCP connections on the port specified by HTTP_SERVER_PORT (which is 8080 for this application).

There is some additional work because I like to specify SO_REUSEADDR. This lets us reclaim the port if it is open but idle (a common occurrence if we restart the program immediately after a crash or killing the application).

Receiving incoming connections

After the socket is setup, Cocoa handles a little more of the work so things get easier.

We can receive each incoming connection by constructing an NSFileHandle from the fileDescriptor above and listening for connection notifications

From the -[HTTPServer start:] method (immediately below the previous code):

listeningHandle = [[NSFileHandle alloc]
    initWithFileDescriptor:fileDescriptor
    closeOnDealloc:YES];

[[NSNotificationCenter defaultCenter]
    addObserver:self
    selector:@selector(receiveIncomingConnectionNotification:)
    name:NSFileHandleConnectionAcceptedNotification
    object:nil];
[listeningHandle acceptConnectionInBackgroundAndNotify];

When receiveIncomingConnectionNotification: is invoked, each new incoming connection will get its own NSFileHandle. If you're keeping track, that was:

1 file handle (listeningHandle) manually created from the socket fileDesriptor to listen on the socket for new connections.
1 file handle automatically created for each new connection received through listeningHandle. We'll continue to listen to these new handles (the keys in the incomingRequests dictionary) to record the data for each connection.

So, now that we've received a new, automatically created file handle, we create a CFHTTPMessageRef (which will store the incoming data) we receive over the file handle. We store these as the objects in incomingRequests dictionary to allow easy access to the CFHTTPMessageRef for each file handle

The CFHTTPMessageRef is both storage and the parser for the incoming data. We can invoke CFHTTPMessageIsHeaderComplete() every time we add data to check when the HTTP headers are complete and we can spawn a response handler.

The response handler is spawned in the -[HTTPServer receiveIncomingDataNotification:] method:

if(CFHTTPMessageIsHeaderComplete(incomingRequest))
{
    HTTPResponseHandler *handler =
        [HTTPResponseHandler
            handlerForRequest:incomingRequest
            fileHandle:incomingFileHandle
            server:self];
    
    [responseHandlers addObject:handler];
    [self stopReceivingForFileHandle:incomingFileHandle close:NO];

    [handler startResponse];
    return;
}

The server stops listening to the file handle for the connection at this point but it doesn't close it, since the file handle is passed to the HTTPResponseHandler so that the HTTP response can be sent back over the same file handle.

Flexible response handling

Exactly which subclass the +[HTTPResponseHandler handlerForRequest:fileHandle:server:] method chooses to return determines the entire content of the response. It does this by iterating over a priority ordered array of the registered handlers and asking each one if it wants to handle the request.

+ (Class)handlerClassForRequest:(CFHTTPMessageRef)aRequest
    method:(NSString *)requestMethod
    url:(NSURL *)requestURL
    headerFields:(NSDictionary *)requestHeaderFields
{
    for (Class handlerClass in registeredHandlers)
    {
        if ([handlerClass canHandleRequest:aRequest
            method:requestMethod
            url:requestURL
            headerFields:requestHeaderFields])
        {
            return handlerClass;
        }
    }
    
    return nil;
}

For this to work, all HTTPResponseHandlers need to be registered with the base class. The easiest way to do this is to add an implementation of the +[NSObject load] method to every subclass:

+ (void)load
{
    [HTTPResponseHandler registerHandler:self];
}

In the sample application, the only response handler other than the default is the AppTextFileResponse. This class chooses to handle the response when the requestURL is equal to "/".

From the AppTextFileResponse class:

+ (BOOL)canHandleRequest:(CFHTTPMessageRef)aRequest
    method:(NSString *)requestMethod
    url:(NSURL *)requestURL
    headerFields:(NSDictionary *)requestHeaderFields
{
    if ([requestURL.path isEqualToString:@"/"])
    {
        return YES;
    }
    
    return NO;
}

AppTextFileResponse then handles the entire response synchronously (before returning from the startResponse method) by writing the text file saved by the application as the response body.

- (void)startResponse
{
    NSData *fileData =
        [NSData dataWithContentsOfFile:[AppTextFileResponse pathForFile]];

    CFHTTPMessageRef response =
        CFHTTPMessageCreateResponse(
            kCFAllocatorDefault, 200, NULL, kCFHTTPVersion1_1);
    CFHTTPMessageSetHeaderFieldValue(
        response, (CFStringRef)@"Content-Type", (CFStringRef)@"text/plain");
    CFHTTPMessageSetHeaderFieldValue(
        response, (CFStringRef)@"Connection", (CFStringRef)@"close");
    CFHTTPMessageSetHeaderFieldValue(
        response,
        (CFStringRef)@"Content-Length",
        (CFStringRef)[NSString stringWithFormat:@"%ld", [fileData length]]);
    CFDataRef headerData = CFHTTPMessageCopySerializedMessage(response);

    @try
    {
        [fileHandle writeData:(NSData *)headerData];
        [fileHandle writeData:fileData];
    }
    @catch (NSException *exception)
    {
        // Ignore the exception, it normally just means the client
        // closed the connection from the other end.
    }
    @finally
    {
        CFRelease(headerData);
        [server closeHandler:self];
    }
}

The [server closeHandler:self]; invocation tells the server to remove this HTTPResponseHandler from the set of active handlers. The server will invoke endReponse when it removes this handler (which is where we close the connection — since this handler does not support keep-alive).

Work not implemented

The biggest task not handled in this implementation is parsing the HTTP request body.

The reason for this is that a general HTTP body solution is very complicated. The body's size may be specified by the Content-Length header but it need not be — so knowing where the body ends can be difficult. The body may also be encoded in one of about a dozen different Transfer-Encodings, including chunk, quoted-printable, base64, gzip — each of which require different processing.

However, I have never needed to implement a generic solution. It is normally easiest to determine what is needed for your specific needs and handle the HTTP body in accordance with those needs. You can handle the request body by overriding -[HTTPRequestHandler receiveIncomingDataNotification:]. The default implementation ignores all data it receives after the HTTP request headers.

Data handling note: the first time the -[HTTPRequestHandler receiveIncomingDataNotification:] method is called, the initial bytes of the HTTP body will already have been read from the fileHandle and appended to the request instance variable. If you need to read the body, either continue reading into the request object, or remember to include this initial data.

Another task not handled are Keep-Alive connections. These also need to be handled in -[HTTPRequestHandler receiveIncomingDataNotification:] and I've left a big comment on the method about what would be involved. The reality is that it's probably easier to set the Connection header field to close for every response to tell the client that you're not going to handle Keep-Alive (see the startResponse code sample above for an example).

The HTTPReseponseHandler priority does not take the requested Content-Type into account. If this is an important consideration for you, you might want to change how +[HTTPResponseHandler handlerClassForRequest:method:url:headerFields:] selects its handler.

Finally, this server does not handle SSL/TLS. It is intended for local network transfers where the network itself is relatively secure. If you are transferring over the open internet and want a secure connection, there's a lot to change and manage at the socket level. You could try it yourself but if security is really important, you probably shouldn't risk writing your own server — if you can arrange it, use a mature, TLS-enabled HTTP server and only handle the client-side in your application. Client-side security in Cocoa is very easy — it is automatic and transparent in CFReadStream and NSURLConnection.

Conclusion

Download the sample app TextTransfer.zip (45kB) which includes the HTTPServer and HTTPResponseHandler classes.

Just because mainstream HTTP servers are large, complex pieces of software, doesn't mean an HTTP server is necessarily large and complex — the core implementation here is only two classes, yet is flexible and configurable.

Of course, the end result is not intended for use as a complete web server solution, however it should work well as a small communications portal into your custom iPhone or Mac applications.

HashValue: an object for holding MD5 and SHA hashes

2009-07-06T03:41:00.001-07:00

Hash values are small, convenient values that you can generate from larger blocks of data for easy indexing, sorting and tracking. The traditional approach for generating MD5 and SHA hashes on Unix platforms to is to use command-line programs like openssl and md5. Apple provide easier approaches in the CommonCrypto library: here's how to use it, along with an NSValue subclass to wrap the result for interoperability with other Cocoa classes.

Introduction to hashes

A hash value is a small, convenient number used to track or sort an arbitrary block of data.

A real-world example of a hash value is the initial letter in a word. You can use the initial letter of a word to lookup that word in a dictionary. If two words have different starting letters, they cannot be equal but if two words have the same starting letter, that doesn't guarantee they are the same.

For fast searching, you can immediately see the problem with only using an initial letter: if all you had to look up a word was its initial letter, you'd still have thousands of words to go through that all start with the same letter. You could use the first four letters but some combinations will be rare (like "aard") but others will contain hundreds of matches (like "stra").

In computing, we rarely ever use the first values in a block of data to track that block of data. Starting values of blocks of data are too often the same or similar — especially in the common case where we are sorting data that already has traits in common.

Instead, we use hash functions that use relatively complex mathematics to generate values from the source data that are well spread, even for source data that is nearly identical. Fortunately, you don't need to know the underlying mathematics, all you need to know is that a hash value can be used to:

check if two blocks of data are the same
sort data into hash tables
checksum data (make certain your data hasn't changed)

Though these are the main purposes for which you should use hashes, MD5 and SHA hashes were actually developed for cryptography, not basic data handling. Nevertheless, for encryption and password handling in your own applications, I recommend using the Keychain (Security.framework) rather than manually using cryptographic hashes.

Generating an MD5

MD5 is one of the most common hash functions. While it is no longer considered safe for security, its use as a checksum is very common.

The traditional Unix approach is to use the md5 program on the command-line:

matt$ md5 -s "Some data value."
MD5 ("Some data value.") = db7116c8634ad7fe3bd90bee94274ee0

The 32 character hexadecimal string is a human readable representation of the 16 byte output of the MD5 function.

On the Mac and iPhone, we can generate this value as follows:

#import <CommonCrypto/CommonDigest.h>

char input[] = "Some data value.";
char result[16];
CC_MD5(input, strlen(input), result);

However, we frequently want the human-readable hexadecimal string. The following will produce an identical ouput to the previous command-line invocation:

printf("MD5 (\"%s\") = %02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x\n",
    input,
    result[0], result[1], result[2], result[3], 
    result[4], result[5], result[6], result[7],
    result[8], result[9], result[10], result[11],
    result[12], result[13], result[14], result[15]);

Producing other kinds of hash works in the same way. e.g. For SHA256, use CC_SHA256 instead of CC_MD5 and increase the size of the result to 32 from 16.

The HashValue class

Since hash values are frequently used to track blocks of data in a program, it would be nice to have an Objective-C class that wraps the hash values so we can use them in NSDictionary objects as keys for our data.

If we consider a hash value simply as a small C struct, i.e:

typedef struct
{
    char value[CC_MD5_DIGEST_LENGTH];
} HashValueMD5Hash;

typedef struct
{
    char value[CC_SHA256_DIGEST_LENGTH];
} HashValueShaHash;

then the easiest way to make it a fully fledged Objective-C object is to create an NSValue from it:

char input[] = "Some data value.";
HashValueMD5Hash result;
CC_MD5(input, strlen(input), &result);

NSValue *myHashValue = [NSValue valueWithBytes:&result objCType:@encode(HashValueMD5Hash)];

That's an okay solution but if you're generating a lot of hashes in your program, it would be good to have a class that:

has an optimized construction method that can generate the hash directly from NSData
abstracts away the C struct so you can deal exclusively with the Objective-C objects
overrides the description method to easily generate human-readable strings

So I wrote the HashValue class.

@interface HashValue : NSObject <NSCoding, NSCopying>
{
    unsigned char value[HASH_VALUE_STORAGE_SIZE];
    HashValueType type;
}

- (id)initMD5HashWithBytes:(const void *)bytes length:(NSUInteger)length;
+ (HashValue *)md5HashWithData:(NSData *)data;
- (id)initSha256HashWithBytes:(const void *)bytes length:(NSUInteger)length;
+ (HashValue *)sha256HashWithData:(NSData *)data;

- (const void *)value;
- (HashValueType)type;

@end

Despite being a class that wraps a value, there's no explicit reason to make it a subclass of NSValue. Since subclassing NSValue has inherent difficulties (you need to carefully override a lot of inherited methods) I've made the class a basic subclass of NSObject.

The init method implementations are fairly simple:

- (id)initMD5HashWithBytes:(const void *)bytes length:(NSUInteger)length
{
    self = [super init];
    if (self != nil)
    {
        CC_MD5(bytes, length, value);
        type = HASH_VALUE_MD5_TYPE;
    }
    return self;
}

The description method is overridden to provide the human-readable hexadecimal string:

- (NSString *)description
{
    NSInteger byteLength;
    if (type == HASH_VALUE_MD5_TYPE)
    {
        byteLength = sizeof(HashValueMD5Hash);
    }
    else if (type == HASH_VALUE_SHA_TYPE)
    {
        byteLength = sizeof(HashValueShaHash);
    }

    NSMutableString *stringValue =
        [NSMutableString stringWithCapacity:byteLength * 2];
    NSInteger i;
    for (i = 0; i < byteLength; i++)
    {
        [stringValue appendFormat:@"%02x", value[i]];
    }
    
    return stringValue;
}

Most of the other methods in the class are basic accessors or NSCopying, NSCoding and NSObject methods. The copying methods in particular are essential so that the object can be used as a key in an NSDictionary.

I will highlight one other method:

- (NSUInteger)hash
{
    return *((NSUInteger *)value);
}

You may wonder why it's necessary to have a hash method on a class that is itself a hash value. Hash methods in Cocoa are used for the same indexing and sorting tasks I identified above: sorting and finding objects in NSSet and NSDictionary. In Cocoa the default hash method calculates its hash value from the memory address of the object. Because we have overridden isEqual: to compare the object's internal value, we also need to override the hash method to also reflect this change. This is a basic requirement of hashes — equal objects must return the same hash value (imagine the confusion if two identically spelled words were sorted to different locations in a dictionary).

It may seem a little odd to simply return the first few bytes of the value as our new hash (after I explained that the first few bytes is rarely the best hash) but this case is an exception to the rule: our data is already "well-spread" and every bit in our hash is as well-spread as the next.

Conclusion

You can download the HashValue class as a .zip file (2kB)

Hash values are used everywhere. Git uses SHA1 to track file changes in its repository, BitTorrent uses MD5s to identify torrents and many download programs use hashes to checksum downloaded data.

The CommonCrypto library (part of Foundation on the Mac and iPhone through libSystem) makes generating common hash functions very simple.

As with all data manipulation, I think a nice Cocoa class around the data makes it easier to use. I have only added MD5 and SHA256 to this particular implementation but it should be very simple to add other CommonCrypto hashes to the class should you require them.

Custom views in Interface Builder using IBPlugins

2009-07-02T02:23:00.001-07:00

If you have custom views configured in code, it can be time consuming to configure them for each instance and make them look right in context. To make the process smoother, you can create Interface Builder plugins and configure your objects in Interface Builder. While the Xcode documentation explains how to do this, it is long, thorough and confusing. Here is the simplified set of steps that I use to create Interface Builder plugins quickly.

Introduction

Apple do have extensive documentation on Interface Builder Plugin creation. However, their documentation is thorough enough that may be overwhelming the first time you want to write an Interface Builder plugin.

I also find the workflow in Apple's IBPluginGuide very different to my typical workflow. I think this is because I normally just want an existing class to show up in Interface Builder so I can tweak one or two attributes — the processes for creating a redistributable library of components is more than I need.

So I was inspired to write this post: a shorter, workflow-optimised version of the same process described in the IBPluginGuide — using Interface Builder to configure a custom button.

A custom buttom

Consider the button in the following window:

A big, drab, gray button. Maybe gray is an acceptable default but it doesn't really match this window. This post will make it easy to adjust this color in Interface Builder.

The large gray button here uses a custom button cell which draws the button using the Gloss Gradient from one of my earlier posts. The drawing code is:

- (void)drawWithFrame:(NSRect)cellFrame inView:(NSView *)controlView
{
    NSBezierPath *roundRectPath =
        [NSBezierPath
            bezierPathWithRoundedRect:NSInsetRect(cellFrame, 2, 2)
            xRadius:5
            yRadius:5];

    NSGraphicsContext *graphicsContext = [NSGraphicsContext currentContext];
    [graphicsContext saveGraphicsState];
    [roundRectPath addClip];

    DrawGlossGradient(
        [graphicsContext graphicsPort],
        self.buttonColor, // <-- this determines the color of the button
        cellFrame);

    if ([self isHighlighted])
    {
        [[NSColor colorWithCalibratedRed:0.0 green:0.15 blue:0.35 alpha:0.5]
            set];
        [roundRectPath fill];
    }
    [graphicsContext restoreGraphicsState];

    [[NSColor lightGrayColor] set];
    [roundRectPath setLineWidth:2.0];
    [roundRectPath stroke];

    [self drawInteriorWithFrame:cellFrame inView:controlView];
}

This is all fine except that the color of the button is determined by the self.buttonColor property and if we have to choose this in code (continually changing the value, fixing, continuing, refreshing and repeating) it could get very time consuming.

A better solution would be to edit the button's color in Interface Builder. That way, we will be able to use color sliders to update the button drawn in the complete context of the window, in real-time.

Creating the IBPlugin project

My process normally starts by creating a custom view component. In this case, I have already created a class named CustomButtonCell in the project for my main application (AppWithButton). After creating the class, I have decided it would be a good idea to have an Interface Builder Plug-In.

A quick point about class requirements: every property we want to configure in Interface Builder must be encoded and decoded for the object using implementations of the NSCoder protocol methods initWithCoder: and encodedWithCoder: overrides. Download the project linked below to see how this is done.

1. Create and name the project

"Interface Builder Plug-In" is a project template in Xcode. In the New Project window, it's in the "Mac OS X -> Standard Apple Plug-ins" section.

An important point to consider is the name for the project — it should not be the same as the custom view component (in this case, CustomButtonCell) because the template will create a class with the name and it can't conflict with the existing view component.

I chose "ButtonPlugin" and saved the new project in the folder for my existing AppWithButton project.

2. Make the new project use the existing CustomButtonCell

Delete the default files and insert our own

The template creates a custom view in the ButtonPlugin project. I never use this (since I want to use my existing view). So I delete the ButtonPluginView.m, ButtonPluginView.h references and files.

I add my CustomButtonCell.m and CustomButtonCell.h files to the ButtonPlugin project but I don't copy or move the files — I leave the files at their current locations in AppWithButton project but drag them into the ButtonPlugin's Source Tree.

Make certain these new files get built

You need to check that the CustomButtonCell.m is added to the Compile Sources build phase of the ButtonPluginFramework Target and the CustomButtonCell.h is added to the Copy Headers build phase of the ButtonPluginFramework. Neither should appear in the ButtonPlugin target.

Then, select the "CustomButtonCell.h" file from the "Copy Headers" build phase and in the Detail View, change the "Role" from "Project" to "Public". This is a pretty obscure thing to do. I normally don't have the Detail View visible — if you don't know which view is the Detail View, it's time to learn because there is no other way to change this value in Xcode.

Change the Role of the "CustomButtonCell.h" to "public" in the Detail View

Rename the file ButtonPluginViewIntegration.m to CustomButtonCellIntegration.m and replace every occurrence of ButtonPluginView in this file to CustomButtonCell.

3. Prepare all the other files in the project

Make the following file changes:

Find the ButtonPluginView.classdescription and rename this file to CustomButtonCell.classdecription (same as our custom cell).
In the contents of this file, change the ClassName to match the actual class name CustomButtonCell and change the SuperClass to be NSButtonCell (again, matching the actual super class for our custom button cell).
In ButtonPlugin.m (the top level class in the ButtonPlugin project), set the bundle identifier to something appropriate. I used com.mattgallagher.ButtonPlugin — this needs to be unique among Interface Builder plugins, so you pick an appropriate value each time.
Set the bundle identifier in the Info.plist and the ButtonPlugin-Info.plist to the same com.mattgallagher.ButtonPlugin value.

4. Configure the display of the button cell for the Interface Builder Library panel

Open the ButtonPluginLibrary.nib. This file contains the "Library Object Template" view (an instance of IBLibraryObjectTemplate). You can find it in the "Library Objects" view at the top level.

Delete the library template that doesn't apply

The Library Object Template will contain a "Template" and an "Example" square. The "Template" version is for NSView subclasses but our CustomButtonCell needs to be embedded in another object (an NSButton) so we will use the "Example" square — so delete the "Template" square.

Set our custom class in the library template

If you click on the button in the "Example" square then click again, it will select the NSButtonCell inside the button (these clicks should be slower than a double-click, since a double-click will edit the text of the NSButton instead of selecting the NSButtonCell inside). With the NSButtonCell selected:

Type Command-6 to select the correct inspector panel.
Enter the custom class name in the "Class" field of the inspector — in our case, we need this to be CustomButtonCell.
Set the button cell class for the NSButton to the right of the "Example" box in the same way.

Select the Library Object Template (ButtonPluginLibrary.nib window -> Library Objects -> Library Object Template) and:

Type Command-1 to select the correct inspector panel.
Fill in the "Label", "Summary" and "Description" for your Library Object as you choose. I like to delete the Path and leave it blank but you can add a path if you want to categorize your custom classes.

5. Configure the Interface Builder Inspector panel

Back in the ButtonPlugin project again, open the ButtonPluginInspector.xib.

Set all the controls in the Inspector panel how we want them

I deleted everything in the "Inspector View" window except 1 label and the NSColorWell. I moved these controls to the top of the view and then made the view 35 pixels high.

Connect the controls so they act on our object

To make the color selector do something, I used bindings. Select the NSColorWell and:

Type Command-4 to select the correct inspector panel.
Under the "Value" subheading, bind to File's Owner (make sure the checkbox is selected too).
Set the Model Key Path to inspectedObjectsController.selection.buttonColor.

This binding needs one other change to work. Back in the ButtonPlugin project, open the CustomButtonCellIntegration.m file. Change the [[keyPaths objectForKey:IBAttributeKeyPaths... line to:

[[keyPaths objectForKey:IBAttributeKeyPaths]
    addObjectsFromArray:[NSArray arrayWithObjects:@"buttonColor", nil]];

This tells Interface Builder to track and monitor the buttonColor property on the CustomButtonCell class. It does not actually perform the value changing (the binding we established will change the value directly) but it will make certain that this value will be tracked for undos and can be edited correctly.

Using the IBPlugin

At this point, you can run the ButtonPlugin project and it will launch Interface Builder with the plugin visible. The only problem is that the plugin won't be visible if you launch Interface Builder in any other way.

Build Settings

The following steps will make the ButtonPlugin project build the ButtonPlugin.framework and ButtonPlugin.ibplugin and install it in your Library.

Double click the ButtonPlugin project item in the ButtonPlugin project Source Tree to edit the project settings. Select the "Build" tab, then choose "Configuration: All Configurations". Then make the following changes:

Set the "Deployment Location" checkbox to checked.
Set the "Installation Build Products Location" to "$(HOME)/Library/Frameworks".
Set the "Installation Directory" to "/".

Double-click the "ButtonPlugin" target in the Source Tree to edit that target's settings. Select the "Build" tab, then choose "Configuration: All Configurations". Then make the following change:

Set the "Installation Directory" to "/ButtonPlugin.framework/Resources.

And now it's installed

With these changes made, build and run the ButtonPlugin project and it will install the ButtonPlugin.framework in your ~/Library/Frameworks directory and load it in Interface Builder. From now until you remove the framework from your library, it will remain in Interface Builder and you can use it at any time.

I realize that this configures the app to install the "Debug" build in the user's library, over the top of the "Release" build (if the Release build is already built) but this is really just for local use, so I don't really care. If you do care, you might not want to apply these settings to all configurations. For me: this is faster to implement and easier to manage.

Integration with the original AppWithButton project

After setting up the Interface Builder plugin, instance of CustomButtonCell in your existing .xib and .nib files will not instantly update. You'll probably need to create new versions of the cell by dragging them out from the Library.

In this example, I have chosen to not link the original AppWithButton project with the ButtonPlugin.framework. This is because I don't want to distribute either the framework or the plugin — they are both for my purposes only.

If you wanted to link them, you could remove the CustomButtonCell.m and CustomButtonCell.h files from the original project and replace them with the ButtonPlugin.framework. According to the Xcode documentation, this arrangement would allow you to avoid installing the ButtonPlugin.framework in your ~/Library/Frameworks directory (Interface Builder would automatically find the plugin for any .nib or .xib file in the project). That's a nice idea but it has never worked for me, so I never bother.

Set a build dependency to keep ButtonPlugin up-to-date

Instead, I like to drag the ButtonPlugin.xcodeproj file into the AppWithButton Source Tree and edit the AppWithButton target, go to the "General" tab and add the ButtonPlugin.xcodeproj as a Direct Dependency.

The reason for this is that if I change the CustomButtonCell class and rebuild, it will automatically rebuild the Interface Builder plugin accordingly (you need to restart Interface Builder to see the changes).

The AppWithButton window in Interface Builder, adjusting the color of the button in real-time.

Conclusion

You can download the complete AppWithButton project zip file (including the ButtonPlugin project) (385kB).

It takes quite a few steps to set up an Interface Builder plugin. Fortunately, they're all simple, if a little menial.

Notice how little code was actually written though: bindings and Objective-C 2.0 properties make this whole process considerably easier — there is no actual code written to set the buttonColor (except in the NSCoder method implementations) since the bindings do it all for us.

Once you're practiced at making plugins in this way, the effort to create one may be justified, even just to tweak simple properties like this.

Do I know how to do this for Cocoa Touch classes for iPhone development? No. I imagine it's possible but you'd need to completely change the IBPlugin project from the template and I've never tried.

Verifying that a string contains an email address using NSPredicate

2009-06-23T05:33:00.001-07:00

To celebrate the official release of iPhone OS 3.0 this week, I will show you how to verify that an NSString contains a syntactically valid email address using NSPredicate — a class that joins the iPhone SDK 3.0 as part of the Core Data additions. This code will work on Mac OS X too since, as with the rest of Core Data, NSPredicate has been part of Mac OS X since 10.4 (Tiger).

Before I begin...

I gave an interview to Anthony Agius of MacTalk.com.au this week. You can download the MP3 from their website. I'm hesitant to listen to my own voice but I think I talked about what it's like to be an independent Mac/iPhone developer in Melbourne, Australia.

Back to predicates

In programming, a predicate is a condition that returns true or false if the object it processes has the properties that the predicate describes. The key difference between a predicate and a regular boolean expression is that a predicate only considers the properties of one object, where a boolean expression may consider multiple, unrelated objects.

Many programmers are familiar with predicates as used in SQL database queries. For example a query to extract the complete row from the "people" database table for every person named "John Smith" might look like this in SQL:

SELECT * FROM people WHERE firstname = 'John' AND lastname = 'Smith'

Everything after the "WHERE" is the predicate — it looks at properties of the row only and is either true (the row will be extracted) or false (the row will be ignored).

Using NSPredicate to evaluate predicates

In Cocoa, NSPredicate works in much the same way as the "WHERE" clause of SQL. The main reason that NSPredicate is being brought to the iPhone is that NSPredicate fulfils the same role in Core Data that "WHERE" clauses fulfil in SQL — to allow the persistent store to fetch objects that satisfy specific criteria.

Imagine we had an NSDictionary created using the following method:

- (NSDictionary *)personRowWithFirstname:(NSString *)aFirstname
    lastname:(NSString *)aLastname
{
    return
        [NSDictionary dictionaryWithObjectsAndKeys:
            aFirstname, @"firstname",
            aLastname, @"lastname",
        nil];
}

we could test if a given row created by this method matched the predicate "firstname = 'John' AND lastname = 'Smith'" with the following:

// given an NSDictionary created used the above method named "row"...
NSPredicate *johnSmithPredicate =
    [NSPredicate predicateWithFormat:@"firstname = 'John' AND lastname = 'Smith'"];
BOOL rowMatchesPredicate = [johnSmithPredicate evaluateWithObject:row];

The string format used to construct an NSPredicate in Cocoa is very similar to the syntax of the "WHERE" clause in SQL. You can also construct this NSPredicate in code by building it from two NSComparisonPredicates and an NSCompoundPredicate.

A more common use of NSPredicate is filtering — extracting rows that match an NSPredicate from a larger collection:

// given an NSArray of rows named "rows" and the above "johnSmithPredicate"...
NSArray *rowsMatchingPredicate = [rows filteredArrayUsingPredicate:johnSmithPredicate];

This is then more like an SQL query where we have selected matching rows from the larger table of data.

Note: NSPredicate handles filtering only. If you'd like to replicate SQL's "ORDER BY" clause, you can apply NSSortDescriptor as a separate step.

Verifying an email address

The "LIKE" comparison operator in NSPredicate (NSLikePredicateOperatorType) is commonly used as a convenient means of testing if an NSString matches a Regular Expression. It's advantage over full libraries with greater options and replacement capability is that it is already in Cocoa — no libraries, no linkage, no hassle.

To test if an NSString matches a regular expression, we can use the following code:

NSPredicate *regExPredicate =
    [NSPredicate predicateWithFormat:@"SELF MATCHES %@", regularExpressionString];
BOOL myStringMatchesRegEx = [regExPredicate evaluateWithObject:myString];

The only question that remains is: what is a regular expression that can be used to verify that an NSString contains a syntactically valid email address?

NSString *emailRegEx =
    @"(?:[a-z0-9!#$%\\&'*+/=?\\^_`{|}~-]+(?:\\.[a-z0-9!#$%\\&'*+/=?\\^_`{|}"
    @"~-]+)*|\"(?:[\\x01-\\x08\\x0b\\x0c\\x0e-\\x1f\\x21\\x23-\\x5b\\x5d-\\"
    @"x7f]|\\\\[\\x01-\\x09\\x0b\\x0c\\x0e-\\x7f])*\")@(?:(?:[a-z0-9](?:[a-"
    @"z0-9-]*[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?|\\[(?:(?:25[0-5"
    @"]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-"
    @"9][0-9]?|[a-z0-9-]*[a-z0-9]:(?:[\\x01-\\x08\\x0b\\x0c\\x0e-\\x1f\\x21"
    @"-\\x5a\\x53-\\x7f]|\\\\[\\x01-\\x09\\x0b\\x0c\\x0e-\\x7f])+)\\])";

This regular expression is adapted from a version at regular-expressions.info and is a complete verification of RFC 2822.

This adaptation involved escaping all backslashes with another backslash (otherwise the NSString will try to interpret them before they are used in the Regular Expression) and escaping the ampersands (&) so it isn't interpreted as a Unicode escape sequence and caret (^) characters because — actually I have no idea why except that the expression wouldn't parse without it.

The linked regular-expressions.info page recommends using slightly different regular expressions that force the top-level domain to be a country code or a known top-level domain. With the number of top-level domains due to increase in the near future, I'm not sure this is a good constraint to impose — since this check isn't intended to verify that the provided domain name is valid.

Since this regular expression NSString is so long, I've split it over 7 lines. This is an underused feature in Standard C languages — if you split a string into pieces but put nothing except whitespace between the pieces, the compiler will treat it as one continuous string. You don't need to write an extremely long string on a single long line.

Conclusion

Just a few lines of code this week but I thought it would be good to draw attention to one of the minor additions making its way to the iPhone in SDK 3.0. I use NSPredicate all the time on Mac OS to perform searches, extract subarrays and perform quick Regular Expression tests. Without it, the only alternatives on the iPhone were methodical array iterations and manual comparisons in code.

Revisiting an old post: Streaming and playing an MP3 stream

2009-06-17T00:39:00.001-07:00

Given the attention it received and the number of bugs I know it contained, I wanted to revisit an old post of mine: Streaming and playing an MP3 stream. In this post, I'll talk about the problems the original contained, how I fixed those problems and I'll present the updated result.

Introduction

Last September, I wrote a post titled "Streaming and playing an MP3 stream". The post was largely an experiment — I just wanted to see if I could play a streaming MP3 by quickly adapting Apple's AudioFileStreamExample to accept an HTTP data stream.

Unexpectedly, the post became one of my most popular. The attention quickly revealed the limitations in my approach:

The blend of Objective-C and C was muddled and led to a situation where neither were being used cleanly.
The boolean flags I copied from the original example were a bad way to describe the playback state and lots of situations were not covered by these flags.
Sending notifications to the user-interface on a thread that isn't the main thread causes problems.
The extra thread I added (the download thread) was never thread-safe.

I've finally decided to take the time to present a solution to these issues and present an approach which is a little more robust and a little easier to extend if needed.

You can download the complete AudioStreamer project as a zip file (around 110kB) which contains Xcode projects for both iPhone and Mac OS. You can also browse the source code repository.

Limited scope

One point should be clarified before I continue: this class is intended for streaming audio. By streaming, I don't simply mean "an audio file transferred over HTTP". Instead, I mean a continuous HTTP source without an end that continues indefinitely (like a radio station, not a single song).

Yes, this class will handle fixed-length files transferred over HTTP but it is not ideal for the task.

This class does not handle:

Buffering of data to a file
Seeking within downloaded data
Feedback about the total length of the file
Parsing of ID3 metadata

These things often can't be done on streaming data, so this class doesn't try. See the "Adding other functionality" section for hints about how the class could be reorganised to handle some of these features.

Taking code out of C functions

Since I had borrowed the AudioFileStream and AudioQueue callback functions from Apple's example, they were Standard C.

My first change was to make these 6 callback functions (7 including the CFReadStream callback) little more than wrappers around Objective-C methods:

void MyPacketsProc(
    void *inClientData,
    UInt32 inNumberBytes,
    UInt32 inNumberPackets,
    const void *inInputData,
    AudioStreamPacketDescription *inPacketDescriptions)
{
    // this is called by audio file stream when it finds packets of audio
    AudioStreamer* streamer = (AudioStreamer *)inClientData;
    [streamer
        handleAudioPackets:inInputData
        numberBytes:inNumberBytes
        numberPackets:inNumberPackets
        packetDescriptions:inPacketDescriptions];
}

At a compiled code level, this is a step backwards: all I've done is slowed the program down by an extra Objective-C message send.

Technically, a C function that takes a "context" pointer (like the inClientData pointer here) is not significantly different to a method. What a method does is makes data hiding and data abstracted actions easier. Within a method, you can easily access the instance variables of an object and you don't need to explicitly pass context into each function.

This is the cliché argument in favor of object-orientation — but it isn't why I reorganized these functions and methods.

The honest reason why I did it is aesthetics: it is easier to read a class that is implemented using Objective-C methods alone — it's more consistent. I chose to move towards an Objective-C aesthetic and away from the Standard C aesthetic of the CoreAudio sample code to promote consistent formatting, consistent means of accessing state variables, consistent ways of invoking methods and consistent ways of synchronizing access to the class.

Describing state

With the majority of code now inside the class, I was in a better position to start handling changes through methods rather than direct member access.

My original approach to state came from Apple's original example. This example had just one piece of state: a bool named finished (which indicated that the run loop should exit).

The problem with this flag is how simple it is. It is unable to distinguish between the following:

End of file, normal automatic stop.
The user has asked the AudioStreamer to stop but the AudioQueue thread has not yet responded.
An error has occurred before the AudioQueue thread is created and we must exit.
We are stopping the AudioQueue for temporary reasons (clearing it, changing device, seeking to a new point) but we don't want the loop to stop.

For Apple's example, there was no problem: the first case was the only one that ever occurred.

As a hasty solution, I had added started and failed flags but these really only covered the first and third case adequately.

In the end, I realized that the AudioStreamer needed much more descriptive state where every combination of progress within each thread had a different position:

typedef enum
{
    AS_INITIALIZED = 0,
    AS_STARTING_FILE_THREAD,
    AS_WAITING_FOR_DATA,
    AS_WAITING_FOR_QUEUE_TO_START,
    AS_PLAYING,
    AS_BUFFERING,
    AS_STOPPING,
    AS_STOPPED,
    AS_PAUSED
} AudioStreamerState;

and when stopping, one of the following values would also be needed:

typedef enum
{
    AS_NO_STOP = 0,
    AS_STOPPING_EOF,
    AS_STOPPING_USER_ACTION,
    AS_STOPPING_ERROR,
    AS_STOPPING_TEMPORARILY
} AudioStreamerStopReason;

In this way, the state always describes where every thread is and the stop reason explains why a transition is occurring.

Combining this with an error code that replaces the old failed flag, I now have a complete desription of the state.

By cleaning up the state of the object, I was able to make the object capable of state transitions that weren't previously possible including pausing/unpausing and returning to the AS_INITIALIZED state after a stop (instead of requiring that the class be released after stopping).

Notifications

In the old version of the project the only way for the user-interface to follow the playback state was to observe the isPlaying property on the object which reflected the kAudioQueueProperty_IsRunning property of the AudioQueue.

This observing was handled through KeyValueObserving. I'm a big fan of KeyValueObserving for its simplicity and ubiquity but this was not the correct place to use it.

KeyValueObserving always invokes the observer methods in the same thread as the change. Since all changes in AudioStreamer happen in secondary threads, this means that the observer methods were getting invoked in secondary threads.

Why is this bad? A minor drawback is simply the unexpectedness for the observer but the biggest reason was that the sole purpose of observing this property was to update the user-interface and the user-interface on the iPhone cannot be updated from any thread except the main thread. Even on the Mac, performing updates off the main thread can have unexpected and glitchy results.

The solution is to retain the NSNotificationCenter of the thread that first calls start on the object and use this center to send messages as follows:

NSNotification *notification =
    [NSNotification
        notificationWithName:ASStatusChangedNotification
        object:self];
[notificationCenter
    performSelector:@selector(postNotification:)
    onThread:[NSThread mainThread]
    withObject:notification
    waitUntilDone:NO];

Don't invoke postNotification: directly from the secondary thread as, like most methods, it is not thread safe and it could be in use from the main thread.

Thread safety

Despite adding an extra thread on top of Apple's AudioFileStreamExample, I never really spent any time thinking about thread safety — a reckless approach to stability. In my defence Apple's example wasn't exactly cautious with its threads and would quit while the AudioQueue's thread was still playing the last buffer.

The most efficient approach to threading is to carefully enter @synchronized (or NSLock or pthread_mutex_lock) in a tight region around any use of a shared variable.

Unfortunately for the AudioStreamer class, almost everything in the class is shared. Instead, I decided to go for the decidedly less efficient approach of running almost everything in the class within a @synchronized section, emerging only at points when control must be yielded to other threads.

The drawback is that the code rarely runs simultaneously on multiple threads (although threading here is for blocking and I/O, not for multi-threaded performance reasons so that's not a probem). The advantage with this heavy-handed locking approach is that the only threading condition that may cause problems are deadlocks.

When do deadlocks occurs? Only when you're waiting for another thread to do something while you're inside the synchronized section needed by that other thread. The simple solution: never wait for another thread inside a synchronized section.

AudioStreamer has three situations where 1 thread waits for another:

The run loop (the AudioFileStream thread waits for any kind of control communication from the main thread or playback finished notification from the AudioQueue thread).
The enqueueBuffer method (AudioFileStream thread waits for the AudioQueue thread to free up a buffer).
Synchronous AudioQueueStop invocations (waits for the AudioQueue to release all buffers).

The first two points are easy: perform these actions (any any method invocation which invokes them) outside of the @synchronized section.

The final point is harder: the synchronous stop must be performed inside the @synchronized section to prevent multiple AudioQueueStop actions occurring at once. To address this, the release of buffers by the AudioQueue (in handleBufferCompleteForQueue:buffer:) must perform its work without entering the @synchronized section (although it's allowed to use the queueBuffersMutex as normal since that isn't used by anything else during a synchronous stop).

Of course, every time the @sychronized section is re-entered, a check must be performed to see if "control communication" has occurred (the class checks this by invoking the isFinishing method and exiting if it returns YES).

Adding other functionality

Get metadata

The easiest source of metadata comes from the HTTP headers. Inside the handleReadFromStream:eventType: method, use CFReadStreamCopyProperty to copy the kCFStreamPropertyHTTPResponseHeader property from the CFReadStreamRef, then you can use CFHTTPMessageCopyAllHeaderFields to copy the header fields out of the response. For many streaming audio servers, the stream name is one of these fields.

The considerably harder source of metadata are the ID3 tags. ID3v1 is always at the end of the file (so is useless when streaming). ID3v2 is located at the start so may be more accessible.

I've never read the ID3 tags but I suspect that if you cache the first few hundred kilobytes of the file somewhere as it loads, open that cache with AudioFileOpenWithCallbacks and then read the kAudioFilePropertyID3Tag with AudioFileGetProperty you may be able to read the ID3 data (if it exists). Like I said though: I've never actually done this so I don't know for certain that it would work.

Stream fixed-length files

The biggest variation you may want to make to the class is to download fixed-length files, rather than streaming audio.

To handle this, the best approach is to remove the download from the class entirely. Download elsewhere and when "enough" (an amount you should determine on your own) of the file is downloaded, start a variation of the class that plays by streaming from a file on disk.

To adapt the class for streaming from a file on disk, remove the CFHTTPMessageRef and CFReadStreamRef code from openFileStream and replace it with NSFileHandle code that uses waitForDataInBackgroundAndNotify to asynchronously stream the file in the same way that CFReadStreamRef streamed the network data.

Once you're streaming from a file, you'll probably want to permit seeking within the file. I've already put hooks within the file to seek (set the seekNeeded flag to true and set the seekTime to the time in seconds to which you want to seek) — however, the mechanics of seeking within the file would be dependent on how you access the file.

Incidentally, the AudioFileStreamSeek function seems completely broken. If you can't get it to work (as I couldn't) just seek to a new point in the file, set discontinuous to true and let AudioFileStream deal with it.

Handling data interruptions

At the moment, if the AudioQueue has no more buffers to play, the state will transition to AS_BUFFERING. At this point, no specific action is taken to resolve this situation — it assumes that the network will eventually resume and requeue enough buffers.

I actually expect there will be cases where this action is insufficient — you may need to ensure that the AudioQueue is paused until enough buffers are filled before resuming or even restart the download entirely. I haven't experimented much since it is easiest with streaming audio just to stop and start new.

Incidentally, if you're curious to know how many audio buffers are in use at any given time, uncomment the NSLog line in the handleBufferCompleteForQueue:buffer: method. This will log how many 1 kilobyte audio buffers are queued waiting for playback (when the queue reaches zero, the AudioStreamer enters the AS_BUFFERING state).

Conclusion

You can download the complete AudioStreamer project as a zip file (around 110kB) which contains Xcode projects for both iPhone and Mac OS. You can also browse the source code repository.

The functionality of this new version has not changed greatly — my purposed was to present a version that is more stable and tolerant of unexpected situations, rather than add new features.

As before, the AudioStreamer class should work on Mac OS X 10.5 and on the iPhone (SDK 2.0 and greater).

The source repository is hosted on github so you can browse, fork or track updates as you choose. I will likely update again in future (I can't imagine I've written this much code without causing more problems) and this way, you can see the changes I've made.

I hope this post has shown you a number of problems that can happen when code is written hastily. This doesn't mean you should always avoid hastily written code (timeliness and proof of concepts are important) but it does mean you should be practised at refactoring code and not simply slap poor fixes onto code that doesn't cleanly solve a problem in the first place.