development

A fork of DSActivityView: WTFeedbackView

iPhone developers: you may have seen my DSActivityView open source project. Another developer was inspired by it, and created his own variation, WTFeedbackView, with support for progress bars, among other changes.

Here's his introduction:

WTFeedbackView is a class to display a HUD-like view with either an activity indicator view or a progress view. It's based on DSActivityView by David Sinclair (http://www.dejal.com/developer/dsactivityview), with some significant additions and modifications.

More specifically, WTFeedbackView offers:

  • Client access through a single class, by means of class methods only, for all features;
  • Changes to the text being shown trigger an animation that resizes the HUD view appropriately;
  • Three built-in styles (like DSActivityView):
    • Simple style: displays a transparent view containing an activity indicator view next to the text explaining the ongoing activity;
    • Bezel style: displays a dark semi-transparent view containing either an activity indicator view or a progress view, above the text explaining the ongoing activity;
    • Keyboard style: same as the Bezel style, but covering only the keyboard;
  • Three built-in kinds:
    • Activity kind: displays only an activity indicator view, plus the text explaining the ongoing activity;
    • Progress kind: displays only a progress view, plus the text explaining the ongoing activity;
    • Flexible kind: contains both an activity indicator view and a progress view (plus the text explaining the ongoing activity), but displays only one at a time, on demand. This is useful when the ongoing activity has parts whose lengths are sometimes known and sometimes unknown. Rather than create a new feedback view for each part, a single one can be used, minimizing screen distractions;
  • Easy updating of the progress view, through a class method +updateProgress: (CGFloat) progress;
  • Thread-safety where needed. For instance, +updateProgress: can be safely invoked from a background thread;
  • Possibility to subclass WTFeedbackView to create custom feedback views having the general behavior of WTFeedbackView but looking differently.

Although iPhoneOS 3.x isn't a requirement, WTFeedbackView and the demo were compiled using iPhoneOS 3.1.2. They were *not* tested on any version prior to 3.x, so don't assume they will work with 2.x.

Enjoy!
Wagner

I'm hosting it for him: download now.

iPhone Open Source: detect tap outside a button like table's Delete

This blog post has been replaced by a newer edition.

Please see blog posts on DejalView.

Sorry customers, another development blog post. :)

For a new iPhone app I'm working on (shh), I have a button that I wanted to behave like the Delete button in a table view. You know, when you tap the delete toggle to the left of a cell, a red Delete button appears. And tapping anywhere other than that button will hide it without doing anything else:

Table Delete button
(Contacts app)

I couldn't see any obvious way to do it, so asked on the iPhone Developer forums, and got a helpful reply suggesting a UIWindow subclass, overriding -sendEvent:.

I tried implementing that, but what I really wanted was to override -hitTest:withEvent:, since I wanted to block taps on views other than a specific button, and the documentation says one should always invoke the superclass of -sendEvent:.

Then I noticed that -hitTest:withEvent: is actually defined in UIView, and further experimenting with the table Delete feature showed that it appears to be implemented UITableView, since the cancel tap behavior only occurs in the table, not the navigation bar or toolbar. Besides, implementing in a UIView subclass is more focal, so a better choice.

So here is my UIView subclass to do this. It uses a delegate approach, with a protocol to declare the method:


@class DSView;

@protocol DSViewDelegate
@optional

- (UIView *)view:(DSView *)view hitTest:(CGPoint)point
withEvent:(UIEvent *)event hitView:(UIView *)hitView;

@end

And the actual subclass interface; as conventional, the delegate is not retained:


@interface DSView : UIView
{
id DS_viewDelegate;
}

@property (nonatomic, assign) id viewDelegate;

@end

With the implementation just overriding the hit test method. It simply invokes the superclass then gives the delegate a chance to change it (or perform some other action) if it implements the delegate protocol method:


#import "DSView.h"

@implementation DSView

@synthesize viewDelegate = DS_viewDelegate;

/*
hitTest:withEvent:

Overrides this method to add support for the -view:hitTest:withEvent:hitView view delegate behavior.

Written by DJS 2009-09.
*/

- (UIView *)hitTest:(CGPoint)point withEvent:(UIEvent *)event;
{
UIView *hitView = [super hitTest:point withEvent:event];

if ([self.viewDelegate respondsToSelector:
@selector(view:hitTest:withEvent:hitView:)])
return [self.viewDelegate view:self hitTest:point
withEvent:event hitView:hitView];
else
return hitView;
}

@end

To use this, simply change a container UIView to DSView in the view hierarchy, then set the delegate property to your view controller (via code or IB):

self.view.viewDelegate = self;

Then implement the -view:hitTest:withEvent:hitView: delegate method in your view controller, e.g. as follows — this will cause a tap on some special control to go through as normal, but tapping anywhere else in the view will hide the special control, without passing the tap on to whatever was actually tapped:


- (UIView *)view:(DSView *)view hitTest:(CGPoint)point
withEvent:(UIEvent *)event hitView:(UIView *)hitView;
{
if (hitView == someSpecialControl)
return hitView;

someSpecialControl.hidden = YES;

return nil;
}

I hope this is useful to someone else too.

You can get the code from my Dejal Open Source Subversion repository via this Terminal command:


svn checkout http://dejal.svn.beanstalkapp.com/open/DSView

Or browse the source directly on the web.

If you haven't seen it already, check out DSActivityView, too.

DSActivityView updated

This blog post has been replaced by a newer edition.

Please see blog posts on DejalActivityView.

DSActivityViewI've committed a minor update to the DSActivityView open source project for iPhone. See the DSActivityView introductory post for more information, including a video demo.

This update adds a showNetworkActivityIndicator boolean property. It is NO by default, but if set to YES the network activity indicator in the status bar will be displayed, and automatically hidden when the DSActivityView is removed.

You can toggle this property as needed while the activity view is in use. For example, you might have the network activity indicator appear while fetching some data from the internet, then disable it while parsing it (while the activity view is still visible).

Of course, you can easily show and hide the network activity indicator yourself, but this tweak saves having to remember to disable both it and the DSActivityView.

You can set this property via:


[DSActivityView activityViewForView:self.view].showNetworkActivityIndicator = YES;

or to toggle it on an already-visible activity view:


[DSActivityView currentActivityView].showNetworkActivityIndicator = YES;

You can get the project from my Dejal Open Source Subversion repository via this Terminal command:


svn checkout http://dejal.svn.beanstalkapp.com/open/DSActivityView

Or browse the source directly on the web.

Announcing DSActivityView: open source for iPhone developers

This blog post has been replaced by a newer edition.

Please see blog posts on DejalActivityView.

DSActivityViewI recently wrote a reusable class for a couple of iPhone apps I'm currently working on, called DSActivityView. I decided to release it as open source. Read on for details.

Firstly, I should say that this work was inspired in part by Matt Gallagher's excellent article, Showing a "Loading..." message over the iPhone keyboard. My code only uses the -keyboardView method from his article, but he deserves credit and thanks for that and many other helpful articles. If you're not reading his blog, Cocoa with Love, you're doing yourself a disservice.

Back to my class. Actually, there are three classes: DSActivityView, DSBezelActivityView, and DSKeyboardActivityView. They provide three styles of activity view, and could easily be extended to support more.

DSActivityView

DSActivityViewThis does a simple horizontal-style loading view, intended for situations where you have a blank view while loading data. It can be displayed very easily — for the default "Loading..." label text, simply use:

[DSActivityView activityViewForView:self.view];

The activity view is automatically added as a subview of the specified view (e.g. the current content view). No need to save the result to an ivar. It automatically supports rotation to any orientation, too.

You can specify a custom label via:

[DSActivityView activityViewForView:self.view withLabel:@"Processing..."];

Or specify a custom width, e.g. so you can change the label while it is being displayed without upsetting the geometry, via:

[DSActivityView activityViewForView:self.view withLabel:@"Connecting..." width:100];

Then when you're done with it, simply invoke this to get rid of it:

[DSActivityView removeView];

DSBezelActivityView

DSBezelActivityViewThis is a subclass of DSActivityView, which displays an animated round-rect-enclosed variation: it animates into view by zooming from full-screen, with a gray background fading in to cover the passed view, and animates out by zooming to half size and fading out the background (see below for a movie showing it in action). It is ideal for situations where you have content visible already, but want to do a network operation to validate or send data, or some other time-consuming activity.

Display it via:

[DSBezelActivityView activityViewForView:self.view];

The [DSBezelActivityView activityViewForView:withLabel:] and [DSBezelActivityView activityViewForView:withLabel:width:] variations are also available. To remove with animation, call:

[DSBezelActivityView removeViewAnimated:YES];

DSKeyboardActivityView

DSKeyboardActivityViewThis is a subclass of DSBezelActivityView, which displays over the keyboard, somewhat like the OS 2 Text app used to do. It is useful to simply prevent further typing while validating a field or sending data (though you might also want to disable the field, to prevent pasteboard operations on it). No need to specify a view to use for this, since it uses the keyboard:

[DSKeyboardActivityView activityView];

Plus a [DSKeyboardActivityView activityViewWithLabel:] variation for custom text. Remove it the same as for the bezel style:

[DSKeyboardActivityView removeViewAnimated:YES];

Demo

I've included a demo project that builds an app to show the various options: the three styles, default or custom label text, covering just the content view or whole window, etc. It requires iPhone OS 3. Here's a movie showing the demo app running:

You can get the project from my Dejal Open Source Subversion repository via this Terminal command:

svn checkout http://dejal.svn.beanstalkapp.com/open/DSActivityView

Or browse the source directly on the web.

You can also download a snapshot, though it may not remain up-to-date; using Subversion is the recommended approach.

Follow @dejalopen on Twitter for automated Subversion commit message updates. You may also like to follow @dejaldevdiary for my behind-the-scenes development diary, and @dejal for general Dejal and personal tweets. Finally, there's also a RSS feed for the repository.

I hope these classes are useful. You are welcome to use them in any project, commercial or otherwise. I just ask that you give me credit; see the DSActivityView header for the easy and free licensing terms. If you do use this code in any form, please tell me (or comment here).

If you make improvements, e.g. to add other activity styles or fix bugs, please send them to me so I can share them with the community. Thanks.

Enjoy!

Update: see also an update to optionally support the network indicator, and an update for iOS 4.

Anatomy of a feature

Brent Simmons wrote today about the anatomy of a feature, an article that really resonated with me.

It's tempting to think that adding a feature like this is just about adding the functionality — but there's a bunch more to it than that.

I get a lot of feature requests for my apps, which are certainly very welcome. But I think a lot of people don't quite realize how much work even the most trivial-sounding feature enhancement can be.

Brent gives a very clear and accurate picture of the process many developers, myself included, go through when considering and implementing such changes. Every aspect of them needs to be carefully analyzed and refined. Perhaps someone asks for a specific feature, but I can tell that what they really want is something different — they just came up with what sounded to them like an easy compromise, when the ideal solution might in fact be easier, as well as better for the overall app. Happens all the time.

But as I said, I do really value feature requests (and bug reports). I want my apps to work well and be as helpful as possible to my customers. For that reason, I keep track of such requests for each app, and also keep a running tally of "votes" for each feature (which sometimes requires some interpretation when different people have different takes on something). When lots of people are asking for the same thing, it rises to the top of my list, and I make it a priority for the next release. But only if I can do it in a way that is consistent with the design goals of the app. That's the tricky part.

Good thing I enjoy planning; I spend much more time analyzing and planning features than actually writing them.

Follow @dejaldevdiary for David's Dev Diary

Just thought I'd mention for any Mac or iPhone developers who read my blog, or customers who are interested in a behind-the-scenes look at my development process:

I recently joined the club and created a David's Dev Diary account on Twitter. It is a separate place for me to post a potentially boring diary of my development work. It is focused purely on the technical aspects that I normally wouldn't bother mentioning on my main Twitter account, @dejal.

Follow @dejaldevdiary on Twitter for all the highly exciting technical details (and maybe a hint or two about what's coming up... e.g. I'm currently working on a secret new iPhone app).

For a list of other developers writing diaries, check out the Dev Diaries website.

Not enough time!

I'm feeling vexed. I have several projects I'd like to work on, but just don't have the time at present.

I have big plans for Simon, Time Out, Caboodle, and my other apps. Each has a long list of great feature enhancements for the next several versions.

Plus I'm working on a semi-secret new project that includes an iPhone app and Mac app that sync via a web app. That is somewhat vexing in itself; it takes time to develop quality software, so that time delays updates to my other products. (I do plan on sneaking in some updates soon, though.)

To top it off, I also do contract work for a client in New Zealand, and am currently working on a major update for that, with a fixed deadline that pushes other work aside. I might do an iPhone app for them, too.

I work seven days a week, doing Dejal customer support mostly in the mornings and development in the afternoons and evenings. But I wish I had more hours in the day so I could do more — or more precisely, get things done more quickly. I'll get to everything eventually, but just not as quickly as I'd like.

I have a really high-tech scheduling system, consisting of printed pages for each quarter of the year, and Post-It notes of different colors for each project:

Schedule

(The gaps are reserved for safety margins, if things take longer than expected, as they often do, and for bug-fix updates.)

This is mounted near the ceiling on the wall in front of me, so I can easily see it whenever desired. It is frustrating when I have to move the Post-Its around due to things taking longer than expected, though... and more so when I have to push a project off the end of the year.

It should be noted that these Post-Its only represent significant updates and new projects; bug-fix updates and very minor updates can be snuck in at any time, as needed.

But enough moaning... I've got work to do!

Developers should iPhone-optimize their sites

A while ago I wrote how the Dejal site is iPhone-optimized: when you view it on an iPhone or iPod touch, the website content is reformatted to fit neatly in the 320-pixel-wide display:

I would suggest that any developers who write iPhone software should do this too. So here's some technical info on what I did. This isn't necessarily the best solution, but it works for me, and isn't very difficult.

Firstly, of course, you need to be able to detect whether you're running on an iPhone or elsewhere. The standard way to do this is by looking at the "user agent" value of the HTTP session. In PHP, you can simply look at the $_SERVER['HTTP_USER_AGENT'] global variable. I have the following function in a utility PHP file included on every page (via the header code):

    function getIsIPhonePlatform()
    {
        global $private_is_iphone_platform;
        
        if (isset($private_is_iphone_platform))
            return $private_is_iphone_platform;
        
        $user_agent = $_SERVER['HTTP_USER_AGENT'];
        $private_is_iphone_platform = stristr($user_agent, 'iPhone') || 
            stristr($user_agent, 'iPod') ||
            stristr($_GET['platform'], 'iPhone');
        
        return $private_is_iphone_platform;
    }

This function returns whether or not the user agent is an iPhone or iPod touch, either by returning the state if already known, or determining it if not. It also allows testing the iPhone-optimized pages from your Mac by adding "platform=iphone" to a page's URL parameters (try it; it's fun!).

Not everyone would want the pages optimized, though: a great thing about the iPhone is MobileSafari does an excellent job of rendering "real" web pages. So I also added a checkbox at the bottom of every page to toggle iPhone-optimized mode off and on. The state is recorded in cookie. So I have another function to read that, on the iPhone platform:

    function getIsIPhoneOptimized()
    {
        global $private_is_iphone_optimized;
        
        if (isset($private_is_iphone_optimized))
            return $private_is_iphone_optimized;
        
        $private_is_iphone_optimized = getIsIPhonePlatform();
        
        if ($private_is_iphone_optimized && isset($_COOKIE['iphone_optimized']))
            $private_is_iphone_optimized = $_COOKIE['iphone_optimized'];
       
        return $private_is_iphone_optimized;
    }
Then the checkbox is actually output (in the footer's include file) via somewhat messy code that uses PHP to output the JavaScript to set the cookie and reload the page when the checkbox is toggled, and the checkbox itself:
    function outputIPhoneOptimizationCheckbox()
    {
        if (getIsIPhonePlatform())
        {
            $query_params = $_SERVER['QUERY_STRING'];
            
            if ($query_params != '')
                $query_params = '?' . $query_params;
            
            echo('<script type="text/javascript">' . "\n");
            echo('<!--' . "\n\n");
            echo('function iphoneOptimizedToggled()' . "\n");
            echo('{' . "\n");
            echo('  document.cookie=\'iphone_optimized=' .
                !getIsIPhoneOptimized() . '; path=/\';' . "\n");
            echo('  window.location.reload(true);' . "\n");
            echo('}' . "\n\n");
            echo('-->' . "\n");
            echo('</script>' . "\n\n");
            
            echo('<p><input type="checkbox" id="iphone_optimized_checkbox"
                onclick="iphoneOptimizedToggled()"');
            
            if (getIsIPhoneOptimized())
                echo(' checked="checked"');
            
            echo(' /><span id="iphone_optimized_label"
                onclick="iphoneOptimizedToggled()">
                Display site optimized for iPhone</span></input>' . "\n");
            echo('</p>');
        }
    }
And finally, the getIsIPhoneOptimized() function is called in the header to use iPhone-optimized or normal style sheets. This is actually a simplification; it actually uses several style sheets, including some common ones and some platform-dependent ones. It also sets the viewport appropriately for each platform — that is a key aspect for iPhone optimization:
    if (getIsIPhoneOptimized())
    {
        echo('<link rel="stylesheet" href="/iphone/header.css"
            type="text/css" media="all" />' . "\n");
        echo('<meta name="viewport"
            content="width=device-width, user-scalable=no" />' . "\n");
    }
    else
    {
        echo('<link rel="stylesheet" href="/mac/header.css"
            type="text/css" media="all" />' . "\n");
        echo('<meta name="viewport" content="width=900" />' . "\n");
    }
Of course, configuring the CSS appropriately is another story, but not too difficult... and very site-specific. Feel free to explore my CSS files if desired: I hope this is helpful. There are a number of other aspects, like fitting images in the available space, supporting movies that can play on the iPhone, and more. If there's interest, I might write more about this in the future.

Apple, please support iPhone trial apps

iPhone App StoreThe new in-app purchasing feature in iPhone OS 3.0, as discussed in the keynote, promises to be a great addition. But it seems one of the most popular uses of this feature has been deliberately blocked: a shareware-like trial model.

They said in the keynote that "free apps will always be free"... which sounds good on the surface, but eliminates one of the most popular software distribution models.

It would be great if users could download an app for free, try it for a while to evaluate (perhaps with feature restrictions or a time limit), then use in-app purchasing to buy the full edition.

Apple and developers would still get paid, but users would be able to better evaluate whether or not they want to purchase the product. With high quality products, that would lead to more overall sales — and people would vote with their dollars to encourage quality apps.

Without such a mechanism, the only way to let users try a product before buying is to release two editions, e.g. a free Lite edition and a paid Pro edition. While that has some merit in itself, it adds additional hassles for the users (e.g. transferring data between the two apps, since each app sandboxes its own data) and having to find the Pro edition, buy and download it, re-configure it, and probably delete the Lite edition.

With in-app purchasing available, there should be no technical barrier to allowing free trial apps that can be purchased after trying them out.

Developers, if you want this option, please tell Apple — file a bug report duplicating mine, rdar://problem/6699761 (this link only works for Apple employees).

The iPhone App Store is broken

iPhone App StoreWell, maybe not broken, but definitely showing some cracks.

The iPhone App Store is a great concept. One central place to get all applications for the iPhone; everything is there, and only there, available right on your iPhone.

But is it everything? Of course, Apple rightly filters out malware and illegal applications... but they have caused some controversy of late by refusing entry to generally useful applications. Worse, they've rejected a couple of apps recently because they "duplicate existing functionality".

One such is a podcasting app, which they say duplicates the iPod app... but seems to have offered other benefits. Another is a Gmail reader, which apparently is more convenient than using Apple's Mail or Safari to access Gmail.

Notice something in common there? Both rejected apps would have competed with Apple's own apps. Yet Apple has no problem with dozens of flashlight and sudoku apps. So it seems to a plain-and-simple anti-competitive move on Apple's part. That is not playing nicely, and potentially illegal. Governments tend to frown on that kind of behavior.

Why do I care?

I haven't written any iPhone apps yet... but I'd like to, in due course. I've written up a rough design for one new app, and would likely want to write companions for some of my Mac apps, like Dejal Simon. However, episodes like these make me and many other developers hesitate to begin, or continue.

Writing software is hard; it can take months to write even a relatively small application properly. What if we come up with a great idea, spend months of time designing, developing and polishing it, then submit it to the App Store, only to have it rejected based on some unannounced policy, or whim? That would be a huge waste of time and effort, which makes developers like me concerned about whether it's worth starting.

What Apple needs to do is provide a clear, detailed description of the iPhone App Store policies, and stick with it. Perhaps offer a contact point for discussions early on, to ensure that an app concept is worth pursuing.

And preferably make the policies as open as possible — none of this anti-competitive behavior. If someone writes an alternative email app or web browser, let them release it. If it is superior to Apple's, it will flourish, and everyone will benefit (including Apple, via their sales cut). If it isn't any good, it'll fade into obscurity.

It's really in Apple's interest to do this, to ensure developers put the effort into building quality apps for the platform. Apple, the ball is in your court. Make it right.

Mac OS X versions for Simon

Since a few people have asked, regarding my announcement yesterday that Simon version 2.4 now requires a minimum of Tiger (Mac OS X 10.4), here's the current breakdown of OS versions for Simon:

  • 63% are on 10.5.2
  • 30% are on 10.4.11
  • 3% are on 10.3.9
  • 4% are on other OS versions (10.4.x or 10.5.x)

So a few people will be affected by this change, but a relatively small number. And that's always dropping, as more people buy new machines or get around to upgrading their OS.

For people stuck on 10.3.9, I'm sorry for the inconvenience... but it had to happen eventually, and Simon 2.3.5 is a fine version.

Interestingly, Simon is a little ahead of the curve when it comes to Leopard adoption. For my other products (excluding Narrator 2, which requires Leopard), the percentage averages to about 56% on 10.5.2, 40% on 10.4.11, 3% on 10.3.9, and 1% on others. So I could drop 10.3.9 support for those too, though I won't until necessary. It'll definitely happen eventually, but not for a while.

A professional press release via prMac

On Monday I did a major upgrade of Dejal Narrator, my app to read out stories in multiple voices, to version 2.0. I usually send out press releases when I do major and minor product releases, but have previously just written and sent the releases myself, using a collection of email addresses I've gathered over the years.

But for this release, I decided to try something different. I had tried free distributions via prMac.com in the past, often while doing my own releases too. It seemed like a good service, but the three-day delay for free releases lacked the immediacy I wanted. So this time I put it to a real test: I used their Writing Service to craft a press release using their experience and skills to get the message across, and paid for the Extended Distribution to get the release out immediately and to a wider audience.

So how'd it work for me? Ray from prMac was prompt and friendly, quickly crafting a release that captured the essence of the product. There was opportunity to review and tweak the wording, but very few changes were needed. Then on release day, I submitted it for posting, which was done soon afterwards. I quickly noticed lots of sites mentioning Narrator, that normally don't pick up my press releases (such as Macworld). The prMac service definitely has a much wider range of publishers than my self-created list.

I'm not sure if it's related or not, but I was very pleasantly surprised to discover that the Apple Downloads software listing site selected Narrator as a "Staff Pick"... not only showing it as the "Featured Download" on the Home & Learning category page, but as the "Featured Download" at the top of the All Categories page, for a couple of days (it's been bumped now, though). Quite the honor! I'm willing to give prMac the credit for gaining Apple's attention like that. You can't buy publicity like such a prominent spot on Apple's site, but for a few dollars you can buy an excellent press release distribution. I plan on using prMac again for future releases.

Narrator as Apple's Featured Download

Migrating from disk images to ZIP archives

For many years, I've been releasing my Mac OS X software on disk images. For a long time, they seemed the most elegant way to provide software to people: they provide a single downloadable container that can be saved in a compressed state, and they can include a pretty background image that explains how to install the app.

A more recent innovation was to include an alias (actually a symbolic link) of the Applications folder, with an arrow in the background indicating to drag the application to that folder to install:

Simon disk image

But all that complicates the release process for me, and for my customers.

For me, when I do a release build I need to copy the build to a standard location then run FileStorm, an application that builds the disk image, then upload the resulting disk image. Doesn't sound too hard, except that FileStorm tended to misbehave for me all too often, resulting in incorrectly laid-out disk images and other problems, requiring several attempts to get it right. It also had compatibility issues with Leopard, forcing me to run it on a Tiger machine, which had other complications.

For my customers, disk images have more hassles. After downloading, they are usually mounted automatically by the OS, though sometimes that didn't work for some people. The images are "internet enabled", so people downloading via Safari get only the contents of the disk images, while people using other browsers get the disk image window as above. Then they need to find it and drag the application to install it... but some people run it directly off the disk image, then wonder where it went after they've dismounted the disk image (or restarted their computer). Plus the disk image has to be dismounted, another hassle.

There's got to be a better way... and there is. The humble ZIP archive.

A ZIP archive is a simple compressed file. They can be created and expanded using built-in commands in the Finder. So for me, creating one is a trivial operation; no more messing around with FileStorm. And they are more convenient for my customers too. After downloading, the archive is automatically expanded, with the application appearing in the download folder. They can then easily install it by dragging to the Applications folder, or try it directly from the downloads folder if preferred — without it mysteriously vanishing after a restart.

So, as I release new versions of my apps, I have been switching to the ZIP archive format. Downloads work exactly the same from my site, but the result is much more convenient for everyone.

As always, I welcome feedback on this. So far, I haven't had any complaints, though one potential problem has come up: one person with an incorrectly installed copy of StuffIt had difficulty expanding the archive by double-clicking on it. The solution was simply to tell the Finder to use the built-in archive expander instead (which is called "BOMArchiveHelper" on Tiger or "Archive Utility" on Leopard).

Cocoa: custom attachment in a text view

I recently posted a query to CocoaDev asking for help with inserting a custom attachment cell into a text view. I had spent quite some time investigating and experimenting, and searches showed several people who had the same question, but no satisfactory answers. Some comments I read suggested subclassing NSTextView, which I tried, but not very satisfactorily.

Fortunately, Douglas Davidson was kind enough to point me in the right direction, combined with helpful off-list discussion with another developer who was working on much the same problem.

I thought I'd share my solution here, in case it helps anyone else. It turned out to be easier than I'd expected. Note: this is written for Leopard with Garbage Collection, so doesn't have releases etc.

Firstly, a file wrapper is used to create a placeholder TIFF with a special "sub-extension" to identify it. I could store any kind of data, but I use a placeholder image so if the user pastes the text into another app, it shows up as something nicer than a generic document icon. The identifier is a unique reference to the data that the attachment represents:

- (NSFileWrapper *)fileWrapperWithIdentifier:(NSString *)identifier;
{
    NSString *wrapName = [[identifier stringByAppendingPathExtension:@"myspecialmarker"] stringByAppendingPathExtension:@"tiff"];
    NSSize size = {100, 18};
    NSData *data = [[NSImage imageNamed:@"AttachmentPlaceholder"] TIFFRepresentation];
    NSFileWrapper *wrapper = [[NSFileWrapper alloc] initRegularFileWithContents:data];
   
    [wrapper setFilename:wrapName];
    [wrapper setPreferredFilename:wrapName];
   
    return wrapper;
}

This method inserts the attachment with the above wrapper and my custom cell:

- (void)insertMarkerWithIdentifier:(NSString *)identifier;
{
   NSFileWrapper *wrapper = [self fileWrapperWithIdentifier:identifier];
   NSTextAttachment *attachment = [[NSTextAttachment alloc] initWithFileWrapper:wrapper];
   MyAttachmentCell *cell = [MyAttachmentCell new];

   cell.identifier = identifier;
   [attachment setAttachmentCell:cell];

   [[myTextView textStorage] appendAttributedString:[NSAttributedString attributedStringWithAttachment:attachment]];
}

I use a couple of text view delegate methods to write the cell's file wrapper to the pasteboard as file contents, allowing it to be copied, dragged, and saved to disk with the text:

- (NSArray *)textView:(NSTextView *)aTextView writablePasteboardTypesForCell:(id <NSTextAttachmentCell>)cell
             atIndex:(NSUInteger)charIndex;
{
   return [NSArray arrayWithObject:NSFileContentsPboardType];
}

- (BOOL)textView:(NSTextView *)aTextView
       writeCell:(id <NSTextAttachmentCell>)cell
         atIndex:(NSUInteger)charIndex
    toPasteboard:(NSPasteboard *)pboard type:(NSString *)type;
{
   if (type == NSFileContentsPboardType)
       [pboard writeFileWrapper:[[cell attachment] fileWrapper]];

   return YES;
}

And to convert the attachment back to my custom cell after pasting/dragging/loading it, the text storage delegate (which is set via [[myTextView textStorage] setDelegate:self];). It looks for TIFF attachments that have my special marker "sub-extension" but aren't using my custom cell, and replaces their cell with my custom one:

- (void)textStorageWillProcessEditing:(NSNotification *)note;
{
   NSAttributedString *text = [myTextView textStorage];

   if ([note object] != text)
       return;

   NSUInteger length = [text length];
   NSRange effectiveRange = NSMakeRange(0, 0);
   id attachment;

   while (NSMaxRange(effectiveRange) < length)
   {
       attachment = [text attribute:NSAttachmentAttributeName atIndex:NSMaxRange(effectiveRange) effectiveRange:&effectiveRange];

       if (attachment)
       {
           if ([attachment isKindOfClass:[NSTextAttachment class]] &&
               ![[attachment attachmentCell] isKindOfClass:[MyAttachmentCell class]] &&
               [[[[attachment fileWrapper] preferredFilename] pathExtension] isEqualToString:@"tiff"] &&
               [[[[[attachment fileWrapper] preferredFilename] stringByDeletingPathExtension] pathExtension] isEqualToString:@"myspecialmarker"])
           {
               MyAttachmentCell *cell = [MyAttachmentCell new];
               [cell setIdentifier:[[[[attachment fileWrapper] preferredFilename] stringByDeletingPathExtension] stringByDeletingPathExtension]];
               [attachment setAttachmentCell:cell];
           }
       }
   }
}

The custom attachment cell is a subclass of NSTextAttachmentCell, to simply draw in a custom way.

I hope this is helpful to others.

I'm the MacTech Spotlight for October 2007

MacTech magazine has a monthly feature at the back of each recent issue called "MacTech Spotlight", where they devote a page to Q&As with a developer or other personality in the Mac community. They've talked with Paul Kafasis of Rogue Amoeba, Wolf Rentszch of Red Shed, and several others.

This month was my turn.

I haven't seen how the article turned out yet (my copy's in the mail), but hopefully it'll be okay. :) I talked about how I originally got into computers and programming, how Dejal got started, what I like about Apple and Mac OS X, how I come up with product ideas, and more.

For those interested, MacTech offers discounts on subscriptions - 60% off the cover price, or a limited-time offer of a six-month sub for only $9.95.

Choosing big cats

LeopardWhenever a developer does a major new release, one of the many issues that they need to consider is which OS versions to support. It's always a tradeoff: having the apps continue to work with older versions allows more people to use the product, whereas the more it is restricted, the more new OS features can be leveraged.

Let's explore the second point first. Each time Apple does an OS upgrade, they make some cosmetic UI changes, add new bundled apps, and so forth, but they also introduce new or improved development frameworks, APIs, and tools. For example, in Tiger (10.4) Apple introduced Core Data, a sophisticated database-driven data modeling and storage API, among others. While it is possible to use some new functionality by checking for its availability, some are more fundamental, so just have to be done without to maintain support for older OS versions.

Apple's Non-Disclosure Agreement forbids me to talk about the new features in their upcoming OS, Leopard (10.5), other than what has been publicly announced. But it should be clear from the available information that Leopard is one of their most significant OS updates, with numerous UI changes, and for developers, Objective-C 2.0, which includes fundamentally different memory management and other improvements.

Being able to leverage the new technologies in Leopard will offer a huge advantage in terms of the features that can be added, and the efficiency of the underlying code. To maintain compatibility with Tiger, a developer would either have to forgo these features, or write lots of code to emulate them. Certainly doable... but is it worth it?

That brings us to the other side of the equation: how many people would benefit from a release that supports an older OS? Thankfully, history provides some guidance. Of course, it should be pointed out that every market is different, and people find software in lots of ways. Lots of people, probably the majority, just pick up a few boxed software products when they buy their Mac at a local Apple store or other retailer, and never explore beyond that. They only need a few core apps, many of which come bundled with the Mac, and that's all they want.

While I'd love to bring my products to the attention of these people, the ones that most interest me are those who actively seek out third-party indie apps to enhance their Macs. This subset tend to be early adopters, often upgrading their computers every few years, and thus getting the new OS then, or they go out and buy the OS as soon as it is released, or perhaps after an update or two, to ensure it is stable. In fact, one could hypothesize that there is a strong correlation between the speed of upgrading the OS and that of upgrading third-party apps. Or put another way, if someone isn't interested in keeping the OS up-to-date, they are probably less interested in keeping third-party apps up-to-date, or even trying third-party apps.

I have tracked OS versions of people using my products, as many other developers do, and these numbers support this hypothesis. For fascinating interactive charts showing the OS versions and other attributes of the Omni Group's customers, see their update charts.

So, there seems to be little benefit in maintaining support for older OS versions, and several benefits from being able to leverage the new technologies.

As for my own products, I do plan to require Leopard when I next do major upgrades of each product, but they will be phased in over time. I will continue doing updates that support 10.3.9 and later in the meantime. Even after the major upgrades, the older releases will continue to be available for customers who aren't ready to upgrade their OS. Hopefully that will keep most people happy, while allowing me to move forward.

Be your own customer

A comment by Chris Smolinski of Black Cat Systems on the Mac Small/Software Business mailing list (there doesn't seem to be any consensus if it's "Small" or "Software") inspired me to share my views on this: "Be your own customer."

This was in response to a question on how to get good ideas for software, with the popular opinion being that scratching your own itch can lead to great product opportunities. Find something that irritates you about existing products, or something you want to do that isn't covered by an app already, and create a solution.

I can vouch for this approach. Although my products started out in various ways, most of them started because there weren't any satisfactory solutions at the time. For example, Simon began as a way for me to watch for website updates, and became more sophisticated as it became popular. There weren't any easy-to-use Mac products for site monitoring at the time - and the ones that did exist don't anymore. Similarly, I created Time Out to improve my health, since I can suffer from eyestrain when staring at a computer for hours on end. BlogAssist was written specifically for my wife, who was really into LiveJournal blogging at the time... but I find I use it a lot, too. All of the products have grown and evolved over the years based on customer feedback, but also my own ideas, since I use them myself on a daily basis (e.g. I used BlogAssist's Services window four times to create the links in this post).

When you are your own customer, or "eat your own dog food", to use that colorful and somewhat unpleasant phrase, you notice little irritations in your initial implementation, and can do something about it. Chances are, your paying and potential customers are also noticing such issues. They can can also be a great source of ideas for better ways to do things that you may not have thought of, perhaps because you're so used to a certain way of doing things.

So if you're a developer looking for the next big hit, or just something to get you started, look inside yourself for your inspiration. Sure, an idea has to have some market appeal to be a success, but even seemingly niche products can be successful if you do a good job. Put your heart into it, and people will respect that. Keep working on it, and using it yourself, and word will spread.

I'm sick of users

There have been a few interesting posts in the blogosphere discussing the word "users", notably one by Josh Bernoff. He argues against using this word, suggesting that the word "users" should be replaced with "customers", "owners", "members", etc:

Users put up with computers. People just do stuff.

I completely agree. I have long disliked the word "users", and try to avoid it. I don't think of the people using my software as "users", but rather as "customers". I write software designed to solve problems, help people achieve tasks, maintain health, monitor sites, and more. They are written by people, for people, for real-world situations.

As I say in my About page, my customers are my friends. I really believe that; it's not just a catchy phrase, but a basic philosophy. When someone writes to me with a question, a problem, or a suggestion, I read it and reply personally, trying to put myself in their shoes and figure out how best to help them. I want them to be happy, not as a user of a product, but as a customer of my company, an existing or potential friend of myself. But my thoughts on customer service is a subject for a future blog post.

Unfortunately, a long history in the computer industry inflicts itself on me when I'm not looking, so the Dejal site does use the word "user" in a few places. For example, I have "User Guides" for my software, and I may use the term in other places. I'm not sure what would be a better term for that, though... "Customer Guide" doesn't sound right. Maybe I should just call it "Simon Guide", "Time Out Guide", etc?

So developers, please consider what words best describe your relationship with your customers. Are they anonymous automatons struggling to use your software, or are they genuine people who find your products useful to help them in their daily activities?

Future and current customers: please remember that I'm a person too, not an faceless corporate entity. I invite you to tell me what you like and dislike about my work, how I can change things to help you better, or simply what you do with my products. I care, I really do! Let's be friends!

Prompt PayPal payment processing, part 3

Here's the remainder of the PHP code for the recent automation of my PayPal-based store, using PayPal's Instant Payment Notification (IPN) service. See part 1 for the introduction and part 2 for the start of the code.

So now we've got a valid transaction, so can begin to process it. As I previously said, I use a shopping cart, so I need to loop over the cart contents. I call the getPayPalShoppingCartValue() function (provided in part 2) to get values specific to a product; shared values can be copied easily. This should all work without a shopping cart, too. I save the values into a $license associative array, which is equivalent to a Cocoa NSDictionary.

    $count = $transaction['num_cart_items'];
   
    if ($count < 1)
        $count = 1;
   
    // Process each shopping cart item as a separate license:
    for ($index = 0; $index < $count; $index++)
    {
        // Construct the license:
        $license = array();
       
        $license['Parser'] = 'PayPal';
        $license['Parameters'] = $transaction;
        $license['Name'] = $transaction['first_name'] . " " . $transaction['last_name'];
        $license['Email'] = $transaction['payer_email'];
        $license['Postal'] = $transaction['address_street'] . ", " . $transaction['address_city'] . ", ";
        $license['Postal'] .= $transaction['address_state'] . " " . $transaction['address_zip'] . ", " . $transaction['address_country'];
        $license['PaymentAmount'] = getPayPalShoppingCartValue($transaction, 'mc_gross', $index);
        $license['TotalAmount'] = $transaction['mc_gross'];
        $license['Quantity'] = getPayPalShoppingCartValue($transaction, 'quantity', $index);
        $license['ProcessorNote'] = $transaction['payment_date'];
        $license['ProcessorTransID'] = $transaction['txn_id'];
        $license['ProcessorName'] = 'PayPal';
        $license['PaymentMethod'] = 'PayPal';
       
        $ref = getPayPalShoppingCartValue($transaction, 'option_selection1', $index);
       
        if (!$ref)
            $ref = 'paypal';
       
        $license['Referrer'] = $ref;
        $license['Special'] = getPayPalShoppingCartValue($transaction, 'option_selection2', $index);
       
        if ($testMode)
            $license['Test'] = 1;
       
        $license['ServerReferrer'] = $_SERVER['HTTP_REFERER'];
        $license['ServerIP'] = $_SERVER['REMOTE_ADDR'];
        $license['ServerAgent'] = $_SERVER['HTTP_USER_AGENT'];
       
        $itemName = getPayPalShoppingCartValue($transaction, 'item_name', $index);
        $isDonation = strcontains($itemName, 'Donation', true);
       
        setLicenseProduct($license, $itemName);

The setLicenseProduct() function simply maps the shopping cart's item name to my own product identifier.

Time to actually add the license. This is done with another function to be left as an exercise for the reader, addLicense(). It takes the $license array we just constructed, adds it to the license database, and returns (by reference) any error. If the sale was a donation for a freeware product or a pending sale, though, the add is bypassed, since a donation doesn't need a license, and a pending sale (if it reaches here) shouldn't be issued one.

We then construct an email to the customer, with different wording for freeware, pending, or normal sales. I'm omitting most of that, since it's specific to your situation:

        // Add the license, unless it's a donation or pending:
        if ($isDonation || $isPending || addLicense($license, $error))
        {
            $productName = $license['ProductName'];
            $version = $license['Version'];
            $name = $license['Name'];
            $email = $license['Email'];
           
            // Donations and pending transactions will use the item name for the product name,
            // as the latter is set in updateLicense(), which isn't called for them:
            if (!$productName)
                $productName = $itemName;
           
            if ($isDonation)
                $body = "Greetings.  Thank you for the $productName!  I appreciate it.\n\n\n";
            else if ($isPending)
            {
                $body = "Greetings.  Thank you for purchasing a $productName.\n\n\n";
                $body .= "Your PayPal transaction is still pending, so you will receive your license when the payment is complete.\n\n\n";
            }
            else
            {
                $body = "Greetings.  Thank you for purchasing $productName.\n\n\n";
                $body .= "Licensed Name: $name\n";
                $body .= "Licensed Email: $email\n";
                $body .= "License Kind: " . $license['KindName'] . "\n";
                $body .= "$productName $version Serial Number: " . $license['Serial'] . "\n\n\n";
                // Instructions on adding the license omitted...
            }
           
            // Info on forums, FAQ, email contacts, etc omitted...
           
            $headers = "From: MyCompany <sales@mycompany.com>\r\n";
            $headers .= "Bcc: MyCompany <sales@mycompany.com>\r\n";
            $headers .= "X-Mailer: PHP/" . phpversion() . "\r\n";
           
            if ($isDonation)
                $subject = $productName;
            else if ($isPending)
                $subject = "$productName purchase";
            else
                $subject = "$productName license";
           
            mail("$name <$email>", $subject, $body, $headers);
        }
        else if ($error)
            exitWithError('PayPal', $error, $license);
    }
   
    header("Content-Type: text/text");
    echo("Transaction completed.");
}

And we're done! I hope this is helpful. This all seems to work fine for me, but if you spot any bugs or have any suggestions for improvements, please let me know. If you have any questions, I'd be happy to elaborate more. I'd be keen to hear from people who use this code, too.

Prompt PayPal payment processing, part 2

As discussed in part 1, I recently automated my PayPal-based store, using PayPal's Instant Payment Notification (IPN) service.

For those interested in the technical details, perhaps implementing this for your own store, here's my code. This is written in PHP, but other languages can be used too.

Firstly, a couple of utility functions. For getPayPalShoppingCartValue(), given the PayPal transaction data, a key, and the (zero-based) index, this returns the corresponding value. Tries the key with the index appended, with an underscore and the index appended, or by itself; the documentation is somewhat inconsistent on how it is applied, though I think an underscore is usually used. All this code should still work fine if you aren't using the shopping cart, too.

function getPayPalShoppingCartValue(&$transaction, $key, $index = 0)
{
    $value = $transaction[$key . ($index + 1)];
   
    if (!$value)
        $value = $transaction[$key . '_' . ($index + 1)];
   
    if (!$value)
        $value = $transaction[$key];
   
    return $value;
}

Next, the exitWithError() function emails me the details of an error, for diagnostic purposes, then exits the script. You can optionally pass an array and it will be included in the email. It also outputs the error (normally wouldn't be seen). It calls another existing function of mine (not provided here) that returns the array as an ASCII property list; there are other ways to output it too. Of course, you should replace the mycompany.com email addresses with your own.

function exitWithError($parser, $error = '', $array = null)
{
    $body = "An error occurred with the $parser parser:\n\n$error\n\n";
   
    if ($array)
        $body .= arrayToASCIIPropertyList($array);
   
    $headers = "From: MyCompany <info@mycompany.com>\r\n";
    $headers .= "X-Mailer: PHP/" . phpversion() . "\r\n";
   
    mail("info@mycompany.com", "Store error: $error", $body, $headers);
   
    header("Content-Type: text/text");
    echo("$parser error: $error");
   
    exit();
}

On to the main code. I actually have this in a function in my code, as it is just one processor function among others, but if you only have one, it can be at the top level of the script.

function handlePayPal()
{
    // Copy to a local variable for convenience, and since the post back to PayPal might wipe it:
    $transaction = $_POST;
   
    // Test mode is activated by passing test=1 to my PayPal Store.  It then uses PayPal's sandbox site instead:
    $testMode = $transaction['test_ipn'] == 1;
   
    if ($testMode)
    {
        mail("MyCompany <sales@mycompany.com>", "PayPal IPN starting", arrayToASCIIPropertyList($transaction), "From: MyCompany <sales@mycompany.com>\r\n");
       
        $paypalDomain = 'www.sandbox.paypal.com';
        $receiverEmail = 'paypal_sandbox_biz@mycompany.com';
    }
    else
    {
        $paypalDomain = 'www.paypal.com';
        $receiverEmail = 'paypal@mycompany.com';
    }

The above sets up things based on whether the purchase was via the PayPal sandbox or your live store. The sandbox is a great way to create fake customer and seller accounts for testing without spending real money. You can initiate this test mode by changing the action on your form from <https://www.paypal.com/cgi-bin/webscr> to <https://www.sandbox.paypal.com/cgi-bin/webscr>. You also need to change the form's "business" field to the sandbox receiver email address.

Next up, we post the received data back to PayPal, so they can confirm that they actually sent it. We construct and post urlencoded form data to their server, then fetch the response. If it's VERIFIED, we're good:

    // Read the post from PayPal system and add 'cmd':
    $req = 'cmd=_notify-validate';
   
    foreach ($_POST as $key => $value)
    {
        $value = urlencode(stripslashes($value));
        $req .= "&$key=$value";
    }
   
    // Post back to PayPal system to validate:
    $header .= "POST /cgi-bin/webscr HTTP/1.0\r\n";
    $header .= "Host: $paypalDomain:80\r\n";
    $header .= "Content-Type: application/x-www-form-urlencoded\r\n";
    $header .= "Content-Length: " . strlen($req) . "\r\n\r\n";
   
    $fp = fsockopen($paypalDomain, 80, $errno, $errstr, 30);
   
    if (!$fp)
        exitWithError('PayPal', 'Unable to connect to the PayPal server.', $transaction);
   
    fputs($fp, $header . $req);
   
    $verified = false;
   
    // Read the response:
    while (!feof($fp))
    {
        $line = fgets($fp, 1024);
       
        if (strcmp($line, "VERIFIED") == 0)
            $verified = true;
    }
   
    fclose($fp);
   
    // Ensure PayPal verified the post:
    if (!$verified)
        exitWithError('PayPal', 'Received a transaction that PayPal did not verify as valid.', $transaction);

We then do some further checks, to ensure the payment went to the correct address, and the transaction has an acceptable status. I wrote this before realizing that pending transactions probably don't reach this point anyway (I think PayPal holds off notifying till they are completed), but it doesn't hurt to leave the pending logic in here:

    // Ensure the payment went to me:
    if ($transaction['receiver_email'] != $receiverEmail)
        exitWithError('PayPal', 'The receiver email was not correct.', $transaction);
   
    $transStatus = $transaction['payment_status'];
    $isPending = ($transStatus == 'Pending');
   
    if (!$isPending && $transStatus != 'Completed')
        exitWithError('PayPal', "The transaction status was $transStatus.", $transaction);

So now we've got a valid transaction, so can begin to process it. Continue to part 3 with the remainder of the code!

Syndicate content