I’m pleased to announce the release of Stone Hill Invoicer 2. The entire application has been been rewritten, right down to it’s core. Of course, that’s not all. If you’ve used previous versions of Invoicer, you’ll see lots of new stuff: quotes, uninvoiced items, a decent address book, folders, more powerful smart folders, Stone Hill Time Card integration, better searching, multiple companies, and an even cleaner and simpler design.

If you’ve never used it before, here are a few key facts:

1. If Stone Hill Invoicer had a MySpace page, it would say “Influences: iTunes, Mail, Brent Simmons and his Weblog, WWPD.”
2. Stone Hill Invoicer uses 12 pieces of open source code, including one that was written just for it.
3. Stone Hill Invoicer got popovers a couple weeks before the iPad was introduced, but it doesn’t expect you to believe that.
4. The best way to get to know Stone Hill Invoicer better is to download it and give it a try.

If you’ve got any questions or comments, I’d be pleased to answer them.

I’ve done something a little different this time around. In previous versions of Stone Hill I shipped a standard Apple Help Book. This is an HTML help book with a few special tweaks that you can bundle up with your app so that it’s available through the Apple Help Viewer. In this version, the “Stone Hill 2.0 Help” menu item opens your default web browser and directs you to a blog that I set up specially for the app.

There’s only one disadvantage compared to a help book for my app: it’s not local.

So what about the guy on a fourteen hour flight to Paris? Will he be unable to work because he doesn’t have a local copy? For Google Docs, I buy that argument. For an invoicing app’s help system? Not so much. I’d like to imagine I write good enough apps that you don’t need the help system, but even if you do, a lack of access to it for a few hours is unlikely to kill your ability to be productive.

But what advantages does an online help system bring? Even if the man on the airplane is mythical, there have to be a few advantages to make it a good idea.

1. It’s a lot easier on me

There are no good tools to generate help books. They’re a pain to update and a pain to work with. Writing entries in MarsEdit is a thousand times better than building a static site with mildly specialized HTML.

2. I really like the idea of being able to leave comments on documentation

I get the occasional email that mentions some tip or way of doing something that a customer came up with, asking if I want to put it in the help documentation. Assuming it’s a great tip, and I have the time to dust off the help docs and repackage them and reupload the app, that’s still a huge turnaround time for something that’s as simple as a comment on a blog post.

With the online help system, I’ve left comments enabled. Sure, I’ll have to put in a minute or two a day to deal with spam, but a few good tips and tricks from users will more than make up for that.

3. Updating the help without updating the app

I can’t justify making the user download a new copy of the app just to get a new revision of the help book. Especially if I want to make lots of little revisions as I see the support mail come in. In previous versions I’ve had to separate help and the FAQ, when really they’re the same thing, I just feel able to update one and not the other.

4. The Leopard and Snow Leopard help viewer isn’t very good

I’m sure there’s a very good reason for it somewhere, but a help viewer that insists on sitting on top of all other windows means that I can’t keep it open and use the app I need help with. On my Powerbook this was a huge issue. On my development machine (20″ + 23″ screens) it’s less of a problem, but still annoys me.

Your browser is an excellent document viewer. We should use it for that.

5. Now I can link users directly to a piece of documentation

In the past, I’ve actually copied and pasted entire help book entries, because the help entry describes exactly what’s being asked, they just didn’t check for it. With the help entries online, I can now include a link in the email, saving me from having to reformat any pictures and text in the file.

Popovers

When the iPad announcement came out, I’ll admit I was thrilled about popovers. Those are those little bubbles that act like temporary panels when you press some button to summon them up.

A couple weeks earlier I’d used MAAttachedWindow to implement popovers in my app. In several places, the previous version of the app needed to use a sheet to present a more detailed view. That’s a lousy thing to do unless it’s really required. The user has to shift their focus, deal with a modal dialog, and then remember what they were doing.



An old modal sheet used to edit the billing address on an invoice

With a popover the user sees details immediately related to what they’re working on without changing their focus. Clicking away from the dialog immediately dismisses it. When their attention shifts to another part of the document, they don’t need to perform the initial manual step of dismissing what they were previously working on.

A new popover, displaying the same information, but in a way that doesn’t break the users workflow.

All in all, these work great on the desktop. They let me get rid of at least a half dozen modal sheets.

That being said, during initial testing, I found that users were confused by the lack of ‘Ok’ and ‘Cancel’ buttons on the popovers. Clicking elsewhere to dismiss it wasn’t an intuitive action, though they didn’t expect to have to dismiss the popovers when switching focus to another task. I added ‘Done’ and ‘Cancel’ buttons to my popovers. This increased the size of the popover, but provided the user with an immediate cue for how to dismiss them.

When I was experimenting, one of the big problems was that they weren’t very visible against the app.  There was no real way of indicating that they were modal.

That being said, I’m convinced that these help an application look more visually balanced, and it’s just a matter of getting the implementation right.  I plan on revisiting this at some point.

Nag Screens in the Sidebar

There’s a fine line between annoying your users with nag screens and not getting paid for your software.  In Stone Hill, I decided to try a bit of a different way of walking that line.

The nagsceen is unobtrusive.  In unregistered copies, there’s a couple of items in the source list: “Buy Stone Hill Invoicer” and “Register Stone Hill Invoicer”.  Clicking on the “Buy Stone Hill Invoicer” item shows a decent sized sales pitch.

The ‘upgrade nag screen’.  This only shows when you click the “Buy Stone Hill Invoicer” item in the sourcelist.

During beta testing, one of my users asked where the purchase button was.  He’d checked under the application menu and couldn’t find it.  Fair enough.  I ended up adding a menu item that shows the same screen under the application menu.

This strikes me as being in the same vein as Panic’s top–of-the-window nag counters.

Sidebar Search via the Global Search Box

One of the things that always drove me nuts about Stone Hill was that the search function only worked on some screens.  In version two, using the search from one of the document screens filters the customer and inventory lists.  Though I considered creating a special iPhone style search box at the top of each table that would initially be scrolled out of view, it seems like a better idea to keep the global search box as the only place to search from.

Feedback has been positive about this so far, but this method may have discoverability issues.

A customer list filtered by search text

A couple years ago I blogged about some code that I use in Locations to find a routers name and MAC address. A recent bug report brought that code back to my attention. I’d made a couple of assumptions, like assuming that en0 was always ethernet, and not being able to detect when the user was on a VPN. Skip down a bit to find the updated code.

The resulting code takes less resources, is more robust, and is shorter. This is definitely a case of looking back at my code and wondering “What moron wrote this?” It’s a wonderful feeling.

Code – Finding the Router’s MAC Address

Code – Finding the Router’s SSID

Attribution
All source is released free of charge. You may incorporate it into any of your applications. I assume no liability for any action that may come from you using this source. If you do use this in your application, I’d like a mention in your about box, but I don’t require it. Don’t forget to drop me an email at warwick@codehackers.net so I know when to stroke my ego.

When I was a kid, I wanted to be either a toy inventor or a writer. These days I’m lucky enough to be someone who writes toys.

I’m working on Stone Hill Invoicer, adding some new functionality to the .rtfd editor where users can customize how their invoices print. One of the support emails that pops up once in a while is asking why it’s so hard to add and delete columns to tables. Until now, I’ve just been using a standard NSTextView, so I’ve been apologetic and put it on my list of things to take care of for 2.0.

This post presents some code for a subclass which add in additional contextual menu items to the standard NSTextView menu when over a table. Here are the old and new menus for comparison:

Download

If you’d like to use this subclass, download the header and implementation files and integrate them into your project. Remember to select your NSTextView in interface builder and change it to a CHTextView.

Attribution
All source is released free of charge. You may incorporate it into any of your applications. I assume no liability for any action that may come from you using this source. If you do use this in your application, I’d like a mention in your about box, but I don’t require it. Don’t forget to drop me an email at warwick@codehackers.net so I know when to stroke my ego.

Cocoa Scripting Guide

An in-depth look at how scripting works from a conceptual level. A long read, but worth it.

Simple Scripting Properties

A simple example for XCode 3 and Leopard which shows a small Applescript implementation that actually works. Excellent to tear apart and learn from.

Applescript Terminology and Apple Event Codes

Lists Applescript terminology and associated codes.

If you need to retrieve library information from iTunes there are a couple ways to do it. You can make a request via Applescript but that requires iTunes to be open. Alternately you can use the “iTunes Music Library.xml” file. Below is a method I put together this morning to do that.

While I was putting this together, I came across a link from Jay Tuley. He pointed out that the the library xml file has two possible locations that you have to account for.

He also make a quick reference to the occasional user doing fun things with Finder aliases and moving that XML file. Why you’d want to move that file, I’ve got no idea. I do know that this morning I had no idea how to resolve an alias or do anything with FSRefs. Now I know a little more. The iTunes related code calls a second little function I put together which returns an NSURL with the aliases resolved given a POSIX path.

Enough talking. Here’s the code:

Edit: As always, go ahead and use the code however you want, commercially or otherwise. I don’t mind a mention in your about box (and an email if I get one), but I don’t require it.

I just finished a large update to one of my apps. It’s only 8000 lines of code, but quick coding and late night enthusiasm had compressed it into a few poorly thought out classes. Adding features was criminal. When I decided to streamline the UI, I started with a clean project and brought code over. Sometimes the only way to clean house is to move.

Prototype mode is a sweet place to be. My favourite features are born here. I can’t rid myself of it, but I have come up with a few strategies to help mitigate the damage.

Be Inspired Somewhere Else

I prototype in Interface Builder, sprinkling code as needed. If I add to my current project I take shortcuts to see results quicker. Building in another project means that I’ll integrate it later. By that time, I’m ready to listen to the better angels of my nature.

Use Plugins When Applicable

When I started writing Locations Pro I decided to make every action it’s own plugin. Using bundles forced me to think my API through, giving each bundle a common structure. It also kept my code isolated in smaller blocks which were less daunting to clean up.

Get Rolling With Cleanup

My biggest problem with getting started in the morning is the part where I actually get started. If I don’t slip right into it I find my day devolves into staring at an empty NetNewsWire. Starting with little cleanup tasks gets me rolling. The side effect is better code.