I started iPhone programming with my “Penguin Links” games. It was fun, and I also gained my skills of iPhone programming from it. But game programming is not really what I am good at, and neither my passion. Since late 2011, I started working on another idea.

I love all kinds of products. No matter something I am going to buy or not. I like to check their reviews, pictures, and different stories. My past working experience also gave me some deep knowledge about products in general. However, whenever I am reading the long, dry product reviews from Amazon or some other sites, I always ask myself, why good product reviews always have to be like Ph.D. thesis? Why can’t they be easy to write and consume, but still make their points? That’s where the idea is from: developing a new way to discover and share personal product experience. It should be easy, fun, mobile, and social.

I finished my first prototype iPhone app early last year. With the prototype, I was able to find two friends to work with me together on the real thing. We were also lucky to find a great designer Pek Pongpaet (@pekpongpaet), to design the app UI. In short, it’s a long, tiring and challenging process, full of excitement and frustration. And finally, after postponing our release schedule twice, our app was sent to app store for review just before the Christmas (currently still under review due to the Christmas lock down).

News Feed Page

Explore Page

Activity Page

(Screenshots of TaggTo iPhone App)

The app is called “TaggTo”, because we use “tagg”s to let users mark their comments on product pictures, at the spot where they are talking about. This makes each comment short, precise, and always in context of pictures. Hence better for creation and consumption from mobile devices. We also added the social factor — users can follow their facebook friends, or any users they trust. In their “News Feed” section, they can see all recent “taggs” from their followed users. By putting all these together, we want to make the app not only a place for seeking opinions on products, but also entertaining by looking at all kinds of product pictures and learning what your friends are up to.

We created a new website for the app: www.taggto.com. You can also download our app (we got an enterprise license) directly from our site: www.taggto.com/beta/. And the best part is, we are running a free iPad Mini promotion now. You can get a chance to win the iPad Mini by writing just five taggs. For more details, please check our our site. Please download the app and give it a try. We love to know what you think! And good luck with the iPad Mini!

Finally, let me list the technologies we used in this project. After all, this is a developer’s blog, isn’t it?

iPhone App:

• Crittercism: for tracking crashes
• Flurry: for app analytics
• JSONKit: for json creation and parsing
• MagicalRecord: for Core Data
• Nimbus: general framework, replacing the old Three20.
• ZBar: for barcode scanning
• And many other open source UI components

Actually, I think the title of this blog is a little off. It doesn’t involve anything like socket or TCP/UDP. Be more precisely, it’s a tutorial about how to do web requests by using Three20 framework. My assumption is you already know the basics of the Three20 framework. You can find more details at: http://three20.info. But if you don’t know anything about Three20 yet, don’t be scared. This tutorial actually doesn’t involve much Three20 specific stuff.

No matter you are programming on a iOS game or an application, a common task is to initiate an HTTP request to a web server, and download / upload some information from / to it. It can be done by just using Apple’s iOS framework, but it’s quite tedious. You have to handle all the hairy details of every step. One great alternative is to use “ASIHTTPRequest” — an open source framework created by Ben Copsey. But if you are using Three20 framework in your project already, you don’t have to add this one extra framework. Three20 already provides very solid support to manage web requests.

There are several different kinds of HTTP requests, such as HEAD, OPTION, PUT, … But the most used ones are GET and POST. GET is used for downloading information, and POST can be used to upload information. These two methods will be the focus of this tutorial.

No matter you want to download or upload content, the first thing you need to do is to initiate a web request. To do that in Three20′s world, three classes/protocols are the keys. These classes are: TTURLRequest class, TTURLRequestDelegate protocol, and TTURLResponse protocol. Now let’s look at a really simple example first:

1
2
3
4
5
6

TTURLRequest *request = [TTURLRequest requestWithURL:@"http://www.google.com/robots.txt" delegate:self];
request.httpMethod = @"GET";
request.response = [[[TTURLResponse alloc] init] autorelease];
 
// Send the request
[request send];

You probably can guess from the code, — yes, we are trying to download Google’s “robots.txt” file. To achieve that, we have to create a TTURLRequest object first in line #1, at the same time assign a delegate object; and then in line #3, we created TTURLResponse object to handle the web response.

TTURLRequest

In above example, line #1 shows the most easy way to create a TTURLRequest object, which is responsible for constructing an HTTP request based on parameters you passed in, sending the request to the web server, and then handle the control to the TTURLResponse object. A few things that need your attention in this process:

• Send request: there are two ways to send out a request: asynchronous or synchronous. By default, when you call [request send], the request will be sent out asynchronously. Or you can use [request sendSynchronously] to make the call blocking.
• Time out: this is a really important parameter but usually got ignored. The default time out for a TTURLRequest is 5 mins, which is quite long. You can change the time out like this:
  

  request.timeoutInterval = 15.0f; // in seconds
  
  Remember to use the latest Three20 framework. In earlier versions this property was not there.

• Max download size: by default, Three20 has an arbitrary limit for the size of data you can download for each request: 150k. If you are going to download more data in the request, the limit can be removed by calling:
  
  [[TTURLRequestQueue mainQueue] setMaxContentLength:0];
  
  Personally I think it’s always a good idea to remove the limit (or set it to a much higher value), ’cause 150K is really nothing on today’s Internet. For now, don’t worry about the TTURLRequestQueue class. We’ll come back to it in the second part of the tutorial.
• Reporting progress: TTURLRequest class provides several convenient properties for the caller object to monitor the progress of the request, which are:
  • totalBytesDownloaded
  • totalBytesExpected
  • totalBytesLoaded (if this request is for uploading content)
  • isLoading: whether or not the current request is activeWith the help of these properties, you can easily create a download progress bar in the delegate callback method. We will revisit this later in next section.
• HTTP headers: HTTP headers are essentially key value pairs. For example, when you have multiple async HTTP calls at the same time, it’s hard to tell which one comes back first. In this case, you can use the “ETag” HTTP header to identify each of them:
  
  [request.headers setObject:@"firstRequest" forKey:@"ETag"];
  
  And then in the delegate callback, you just need to check the “ETag” header to identify each request. Please note that Three20 API already extracted some commonly used HTTP headers into properties, such as “contentType”. So before you set the header value, make sure to check if it’s already part of the request’s properties.
• HTTP method: In our example above, the HTTP method is set in line #2. The most used two HTTP methods are GET and POST. Usually GET is for downloading, and POST is for uploading.
• Last but not least, remember to encode your parameters before you create the TTURLRequest object. For example, if your URL is “http://www.google.com/search?q=apple’s latest ipad”, it needs to be encoded into: “https://www.google.com/search?q=apple’s%20latest%20ipad”. For how to encode/decode an URL, please check out this post on stackoverflow.com.

TTURLRequestDelegate

The delegate object is the place to implement some real business logics. All methods defined in this protocol is optional, but usually you want to implement at least two methods:

- (void)requestDidFinishLoad:(TTURLRequest*)request — this delegate method is called when the request has finished successfully.
- (void)request:(TTURLRequest*)request didFailLoadWithError:(NSError*)error — this one is called the request has failed. An error message is sent back along with the original TTURLRequest object.

TTURLRequestDelegate is a very important protocol in Three20 framework. You can see it in almost all web request related classes. For example, TTImageView, a view to display image in Three20′s flavor, also implemented the TTURLRequestDelegate. That’s because TTImageView is capable of displaying an image by downloading it from web directly. So it has to implement the TTURLRequestDelegate to handle the HTTP request.

Besides above two methods, other methods also provide some useful information. For example, in previous section we mentioned using TTURLRequest's several properties to monitor the progress of the request. That can be done in the delegate method requestDidUploadData:

1
2
3
4

- (void)requestDidUploadData:(TTURLRequest *)request {
float progress = request.totalBytesLoaded / (float)request.totalBytesExpected;
NSLog(@"Current progress: %f", progress);
}

TTURLResponse

TTURLResponse is the last pice of the puzzle of Three20 network programming. It is actually a protocol with two methods defined:

- (NSError *)request:(TTURLRequest *)request processResponse:(NSHTTPURLResponse *)response data:(id)data
- (NSError *)request:(TTURLRequest *)request processErrorResponse:(NSHTTPURLResponse *)response data:(id)data

The first one is for processing response data from a successful request, and the second one is for a failed request. You can implement your own TTURLResponse instance to handle the response, but in most cases, the provided four classes in Three20 framework should be sufficient.

• TTURLDataResponse: This is the most straightforward one. If you look at the source code of this class, it just simply save the data from the response to its internal readonly property “data”, and then you can use the data to do whatever you want. For example, you can convert the data to a NSString:

  NSString* str = [[NSString alloc] initWithData:response.data encoding:NSUTF8StringEncoding];

• TTURLImageResponse: TTURLImageResponse is similar to the TTURLDataResponse. The only extra work it does is trying to convert the data to an UIImage object, and save it to the internal readonly property “image”. This class is used especially less often because the TTImageView class also provides the same functionality to download images from web, and is more capsulated comparing to the TTURLImageResponse class.

• TTURLJSONResponse and TTURLXMLResponse: I am going to talk about these two classes together because they are really similar to each other. Both are often used for API calls; both handle data in tree structures and have a root object; both already have a parser built-in. In the implementation of - (NSError *)request:(TTURLRequest *)request processResponse:(NSHTTPURLResponse *)response data:(id)data, the built-in parser will try to parse the data into a root object. Depending on the structure of the JSON/XML, it could be a NSArray, or a NSDictionary. So you need to a test it before you start processing the parsing result, something like:

  TTDASSERT([response.rootObject isKindOfClass:[NSDictionary class]]);

  Another caveat is how to convert your object to JSON string so that it can be sent through an HTTP request. The JSON framework used in Three20 is SBJSON. It already knows how to convert a collection to a JSON string. But to convert your own class to a JSON string, you have to implement the “- (id) proxyForJson” method. This method must return a type that SBJSON already knows how to handle — for example, most of the cases you can just convert your object to a NSDictionary. Or you can also just return a NSString if you like.

So far we have covered most of the basic stuff in Three20 network programming. You should have a good idea about how to work with HTTP GET method now. Since one of Three20′s biggest problems is lack of documentation, I hope this tutorial can make this part easier for you. Before I finish this post, do you mind doing a homework? I always believe you will learn more when you actually get your hands dirty. The task is simple:

use Three20 framework to download the content from this URL:

http://www.flickr.com/services/rest/?method=flickr.test.echo&format=json&api_key=0aaaec5a4450a7db6a939e38bf768eed

and then parse the response into a NSDictionary.

In the next post, I’ll talk about more advanced network programming such as uploading a big file, and some neat tricks. Stay tuned.

References

• Three20 Framework: http://three20.info/
• Three20 Framework API Doc: http://facebook.github.com/three20/api/index.html
• ASIHTTPRequest: http://allseeing-i.com/ASIHTTPRequest/
• How to encode/decode an URL: http://stackoverflow.com/questions/6688287/url-decoding-encoding-nsstring
• SBJSON:http://stig.github.com/json-framework
• HTTP Methods: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html
• HTTP Headers: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
• JSON Data Format: http://www.json.org/

In the second half of the year, I shifted my focus to another iPhone apps (not game), which I think I am better at. However, I am still curious about how far my PenguinLinks games can go if they can have some exposure. Nowadays, the most used iOS app promotion technique is probably “Free Promotion”. So I asked several companies in this business, including FreeAppADay, FreeAppParty and a few others. Their offers are from $4000 to $18K per promotion, and usually guarantee top 25 in Game category. Some of them also offer performance based charge, usually $1 per install — please note this is actually a much more expensive one: your app can easily get tens of thousands of downloads when it becomes free, which means you need to pay $1 for each download to the promotion provider. It’s like a no-limit hold’em game.

The Free Promotion

To me, all the options are too expensive. Most importantly, I am not 100% sure how much it can help, specially once my game goes back to paid. So I decided to run a free promotion by myself. Here are what I have done and the result:

• On 12/18, I released version 2.6, with the fix of a few bugs, and also let the game pick up some momentum.
• On 12/22 12AM, my paid game “PenguinLinks Pro 2” went free.
• I twitted it, and also posted the news on my facebook page: http://www.facebook.com/clingmarks, which has almost 1000 fans.
• In the following several days, the news got twitted 25 times on twitter, 17 times on weibo.com (twitter like service in China).
• The news was also picked up by techbargains.com on 12/22 (see screenshot bellow). I don’t know how many downloads this has contributed, but it’s certainly fun to see my game mentioned on one of the most popular tech deal sites.
  
• Results:
• On the first day of the promotion, the rank of my game “PenguinLinks Pro 2″ went up dramatically in most countries:
• US: 28 in Board, 45 in Family, which is the best it ever achieved.
• China: 2 in Board, 3 in Family, 25 in Games, 71 Overall — this was achieved a few days later, actually today, 12/28.
• On the first day of promotin, it received 12.5K downloads total: China — 8.7K, US — 2.4K.
• In the following days of the promotion, downloads from China grow gradually to about 10K and stay there; downloads from all other countries have dropped significantly comparing to day one.
• The reviews for the game has been very positive:
• US: 20 ratings, 4.5 on average;
• China: 272 ratings, 4.5 on average.

Before the promotion, my goal was pushing my game to top 25 in one category in US, and top 25 in Games in China. As of today, it has reached the goal in China, but nowhere near the goal in US. But I am still pretty happy about the result. What I have learned from this promotion are:

• Quality is the ultimate factor of success. You can push an app up to the top, but only apps with great quality stay. Ranks of most the apps will drop like a rock once promotions end. Remember this is just a chance to show, and it doesn’t convert to success directly.
• You can run a “test” free promotion like mine just by yourself. Many services, websites are monitoring price drops in Apple App Store. By making a paid app free, you will naturally gain a lot of free exposures. It will give you a better sense about how far your app can go; and from user feedbacks, you will know what to improve next.
• Are all kinds of expensive-for-developers free promotions really worth it? It all depends on the quality of your app. All the promotions can give you is short time exposures. To stay there, your app must have high quality.
• Last but not least, different markets have different needs. That’s what I am going to talk about next –

Chinese App Market

A few days ago, I read an article on Techcrunch. It mentioned that:

In January, China generated only 18% of the downloads when comparing the U.S. iPhone App Store together with China’s. By November, it was generating 30% of the combined total downloads. And on the iPad, the two stores are almost equal in size in terms of downloads.

I totally felt it in this free promotion.

In August 2010, the first version of my game “PenguinLinks Free” become #2 overall app in the whole app store in China, and stayed there for about a week. At that time, it had about 8K to 10K download per day. 16 months later, with about the same amount of downloads, my game is only #25 in Games, #71 in Overall. #71 to #2, that’s a huge difference. I don’t know how many more downloads it takes to get to #2 overall today. But if somebody tells me it needs a few hundreds of thousand, I won’t be surprised. Just from this one small case, you can see how much the Chinese app market has grown in last 16 months.

Apple also sees the opportunity there. Recently, Apple just started accepting the local currency in China. Also, credit card is not a required payment method anymore in App Store China, since most people there don’t have a credit card capable of foreign transactions. Apple also added a way to pay by cellphone, which is popular in China, Japan and South Korean. All these are important steps to attract more paid customers there. In the next several years, with the introduction of the new iOS devices, this market will grow even bigger, with no doubt.

Grand Canyon

My free promotion started on 12/22, just a few hours before the iTunes Connect locked down. And then, on 12/23, I went to Grand Canyon for a vacation. Yes, it’s cold there. But the stunning view is well worth it. As an indie developer, vacations is as needed as any other career. So take advantage this holiday season, go out, enjoy. And come back refreshed, with more energy and ideas.

And finally, I plan to end my free promotion tomorrow morning. So if you are interested, don’t miss this opportunity. Grab it. You may like it. Who knows?

This blog was started back in 2007 (it was not under clingmarks.com domain at that time). From day one, it uses just some very basic wordpress themes. When we had more and more games, we started to think migrating this site to a more professional looking one. But for various reasons, this project had never been on the top of our to-do list.

Last week, finally I decided to do it. My goals are:

• A more professional looking site
• Make it a showcase of our products
• Prettier blog post, with better SEO support
• Fully integrated with Facebook, Twitter and Google+

With our objectives set, we purchased a professional theme for business, and hoped that we just needed to apply it, and everything would be done. But it’s not that simple. The theme is not as flexible as we want, and we also have some specific requests. It actually took me almost a week to work everything out, with the help from the tech support from the theme creator.

On Friday night, we finally figured out all the issues and pushed site to live. The end result is what you are seeing now. I think it’s day and night comparing to our original site. I am very satisfied — just check out this before-and-after here:

Being indie developers is really our passion. That’s what I wrote in the “About Us” page. I am going to quote that page to end this post.

We started by introducing the Penguin Links game on Android Marketplace in March 2009. And it was called “Pair Up”. We did not expect much. The whole practice was really just an Android exercise. However, just a few hours after the initial release, we got the first review! I still remember the excitement we had when we saw that. The first version was very rough, as you can imagine. But users’ feedbacks helped us to get better and better. And a few months later, the “Pair Up” game had become one of the top games in puzzle category, and stayed there for a long time. In last almost three years, this game had more than half million downloads, and thousands of reviews.

At the meantime, we were also working on an iPhone apps, which took longer than we thought. In June 2010, PenguinLinks for iOS was released. However, at that time, the competition at App Store was already very strong, and the games didn’t do as well as we expected. But things changed in the middle of August, 2010. One day when I took out my iPhone to check the number of downloads, I was surprised to see the it has more than doubled from the previous day. But I thought it could be something random. The day after, it doubled again. And tripled again after another day. I knew it must be something big. I checked the downloads by country and found most of them were from China. Then I opened the App Store for China, and saw our game “PenguinLinks Free” was already No. 2 app in the whole app store! Not in one category, not in games, but the whole app store! Our server was so busy (since there was no game center yet at that time, we used our own server to host score board) in those days that it almost crashed. What a fun!

Be frankly, our games were never a big success, such as Angry Bird, Tiny Wings, Jewellust, … But we have enjoyed doing this as much as anybody. The feeling of building something actually used by somebody, loved by somebody, or even criticized by somebody, is just awesome.

We are still working on these projects, on and off — since these are not our fulltime jobs. We may stop working on them someday. But we have had a lot of fun by building this. And hopefully we have brought some fun to our users.

At the meantime, if you want to know more about our products, check out the product page. You can also follow us on Facebook or twitter (please see the footer of this site). Email is always welcome, too. Just drop a line to: support [at] clingmark.com, we’ll get you back.

And finally, thank you ALL for reading this blog, playing our games, leaving feedbacks, … It’s YOU who drives us this far. And we really appreciate that.

To abstract things a bit, what I need to do is, use my production apache server to route the internet traffic based on the request’s domain name: if it’s for the test sub domain, forward to the test server; otherwise serve it locally.

To achieve that, the production apache server needs to act like a proxy server. To change its behavior, I just need to modify the production server’s configuration file at path (on ubuntu server):

/etc/apache2/sites-available/clingmarks.com.conf

All I need to do is to add this section to the end of the original configuration file (the sub domain for my test server is test.clingmarks.com, with IP address 192.168.2.5):

<VirtualHost *>
    ServerName test.clingmarks.com
    ProxyPass / http://192.168.2.5/
    ProxyPassReverse / http://192.168.2.5/
</VirtualHost>

Of course, I also need to add a DNS entry for my sub domain to my domain name registrar, to point to the same IP address as main main domain.

After these changes, the support guy is able to log in my test server from address http://test.clingmarks.com .

The closest match is the Matias Tactile Pro 3. It’s a beautiful keyboard that looks just like the original Apple Extended Keyboard. And it’s completely mac compatible (of course). However, the key switches it uses are ALPS, which is stronger than cherry blue switch — the switch I preferred. So I finally give it up. I kept trying keyboards with different brands, and eventually settled with a DAS keyboard Model S. I know it’s not a mac keyboard, but I like its simple looking, the overall quality (see my P.S. at the end of the post for another story), and the relatively low price (still more expensive than membrane keyboards, though). And it works fine with my mac. But sometime, I still hope that one day, I can find a keyboard I love, with the authentic mac keyboards’ look and feel.

DAS Model S Professional Keyboard

Until I found this post on geekhack.org — an online community for geeks with love for keyboards: http://geekhack.org/showthread.php?23203-Finishing-Touches-for-a-Layout.

The original author, iindigo,  is a genius. He designed a wonderful mac keyboard layout to match exactly the look of the original mac keyboard. All the font, position of each character, are carefully designed so that they look just like the Apple mac keyboard. Then, based on this layout, a set of custom key caps can be ordered to replace the original ones — a big benefit of using mechanical keyboards is that all the key caps are replaceable — to make the keyboard a lot more mac-looking.

And the best part is, iindigo is general enough to share his work with everybody, for free!

So I asked him to send me the layout file. And then I added a few extras based on the layout of the current Apple keyboard. The additional changes are:

• Multimedia symbols on F1-F15.
• Change the original “menu” key to a apple logo key — which will be the “Fn” key. I also make it the only black key to give the whole keyboard a little kick.
• Right-align the right “control” key.
• And just for fun, I added a “pig king” from Angry Bird to the space bar!

I submitted an order for the custom key caps on www.wasdkeyboards.com, a website that specializes in custom keyboards, and keyboard parts. After just a day, I was told the key caps were ready to pick up (yes, I am luck enough to be close to them). WASD keyboards was also kind enough to offer me to change all the keys in their office, so that I can use their wire key cap puller — just to make things easier.

When I walked into WASD Keyboards’ office, my key caps are already there, nicely laid out on a table, just like on a keyboard:

At the first look, I was a little worried that the letters seemed a bit too thin, and not dark enough on the keys. But overall, the laser etched letters/symbols are very crisp, and look nice on the white key caps. WASD’s staffs were very nice, too. Not only they let me do the key switching in their office, they also showed me how to lubricate the stabilizers of the bigger keys (this is my first time changing all the keys of a mechanical keyboard). The whole thing turned out a little longer than I thought. But once it was finished, I was really amazed by the overall look of this “new” keyboard. The font is perfect, not thin at all; the white key caps on the black base provide a great contrast. It just looks beautiful!

Once I got back to home, I created a custom configuration file for KeyRemap4Macbook, to remap all the “Fx” keys to their corresponding multimedia keys. Now, after all these effort, I finally have a good-looking, mac compatible mechanical keyboard! I know it is still not a mac keyboard, but the feeling of creating something new, is just more satisfying than anything!

OK, enough talk. Now let’s look at the pictures. I also attached the design layout and my KeyRemap4Macbook configuration file at the end.

P.S.:

• Usually DAS keyboards’ quality is pretty good. But the one I received has a stucked key. And the return/exchange experience is just suboptimal. I should have bought it from Amazon or Newegg instead of from DAS’ website directly. Eventually I chose to live with it instead of go through more hassles to exchange it. After all it’s the not-often-used F12 key.
• For anybody who is interested in, and new to mechanical keyboards, here is the must-read guide: Mechanical Keyboard Guide.

Keyboard with new key caps

Keyboard without key caps

Opt, Cmd, Shift and Return

Multimedia keys

The "pig king" space bar

Keyboard layout

2/11/2012 Update: Since this blog was published, I got so many requests for the my design layout file that I decided to put it here for everybody to download under Creative Commons license. You are free to modify it. But if you want to redistribute it, please mention my site or this post. NO RESALE OR COMMERCIAL USE!

Adobe Illustrator File: Yuchen’s_Mac_Keyboard_Outlines_final.ai

Custom Mac Keyboard Layout For Mechanical Keyboards by iindigo, yuchen is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.
Based on a work at www.clingmarks.com.

Finally, here is my configuration file for KeyRemap4Macbook:

<?xml version="1.0"?>
<root>
  <list>
  	<item>
  		<name>Remap Num to Clear</name>
  		<identifier>private.remap_num_to_clear</identifier>
  		<autogen>--KeyToKey-- KeyCode::PC_KEYPAD_NUMLOCK, KeyCode::KEYPAD_CLEAR</autogen>
  	</item>
  	<item>
  		<name>Remap Application to Fn</name>
  		<identifier>private.remap_application_to_fn</identifier>
  		<autogen>--KeyToKey-- KeyCode::PC_APPLICATION, KeyCode::FN</autogen>
  	</item>
 
    <item>
      <name>Remap Volume Keys</name>
      <appendix>Up, Down, Mute</appendix>
      <identifier>remap.volumeKeys</identifier>
      <autogen>--KeyToConsumer-- KeyCode::PC_PRINTSCREEN, ModifierFlag::FN,
      							ConsumerKeyCode::VOLUME_MUTE</autogen>
      <autogen>--KeyToConsumer-- KeyCode::PC_SCROLLLOCK, ModifierFlag::FN,
      							ConsumerKeyCode::VOLUME_DOWN</autogen>
      <autogen>--KeyToConsumer-- KeyCode::PC_PAUSE, ModifierFlag::FN,
      							ConsumerKeyCode::VOLUME_UP</autogen>
    </item>
 
    <item>
      <name>Remap Brightness Keys</name>
      <appendix>Darker, Brighter</appendix>
      <identifier>remap.brightnesskeys</identifier>
      <autogen>--KeyToConsumer-- KeyCode::F1, ModifierFlag::FN,
      							ConsumerKeyCode::BRIGHTNESS_DOWN</autogen>
      <autogen>--KeyToConsumer-- KeyCode::F2, ModifierFlag::FN,
      							ConsumerKeyCode::BRIGHTNESS_UP</autogen>
    </item>
 
    <item>
      <name>Remap Music Play Keys</name>
      <appendix>Previous, Play/Pause, Next</appendix>
      <identifier>remap.musickeys</identifier>
      <autogen>--KeyToConsumer-- KeyCode::F9, ModifierFlag::FN,
      							ConsumerKeyCode::MUSIC_PREV</autogen>
      <autogen>--KeyToConsumer-- KeyCode::F10, ModifierFlag::FN,
      							ConsumerKeyCode::MUSIC_PLAY</autogen>
      <autogen>--KeyToConsumer-- KeyCode::F11, ModifierFlag::FN,
      							ConsumerKeyCode::MUSIC_NEXT</autogen>
    </item>
 
    <item>
      <name>Remap Eject Key</name>
      <appendix>Eject</appendix>
      <identifier>remap.ejectkey</identifier>
      <autogen>--KeyToConsumer-- KeyCode::F12, ModifierFlag::FN,
      							ConsumerKeyCode::EJECT</autogen>
    </item>
  </list>
</root>

Three20 is an open source iOS library, contributed by Joe Hewitt, the developer of original Facebook iPhone app. It is a big package, with very rich functionalities. Many familiar UI elements you see from the facebook app can be found here: the Laucher View (the startup screen with icons for different functionalities), photo album, … Some UIKit classes are also enhanced, which makes them easier to use (once you have learned it), and also more powerful.

However, everything comes with a cost. And three20 is not perfect either. The most complained issues are the complexity of this framework, not-well-managed dependencies, and lack of documentation. There are some basic information on its official website — three20.info, but far from enough for such an advanced framework. Most people, including myself, learned this framework by try-and-error, google search and the community’s help. There are also some alternative projects that try to provide similar functionalities while fixing three20′s shortcomings — such as nimbus, but so far none of them has provided the same level of functionalities as three20 does.

To make things easier for myself, and for other three20 newcomers, I decided to start this blog series for three20. Each of the post will cover one topic in three20. And as the title says, they are just my learning notes. I’ll include a lot links to other resources and also try to explain it briefly. So here we go!

Today the topic is “URL based navigation”. Be frankly, I think this is one of the smartest idea in three20. In an iOS app, we need to deal with view transitions all the time. And it’s tedious. The procedure is always the same: find out which view to transit to, decide what animation effect to be used in this transition, pass any parameter if needed. Three20′s “URL based navigation” makes this a lot easier, and more intuitive. The whole idea is to treat view transitions in iOS apps similar to web view transitions in a browser. In a web browser, you don’t care how to navigate to he next page — you just click on links (URLs). That is basically the idea of “URL based navigation”.

In three20, to implement “URL based navigation”, first you define a mapping table which maps urls to view controllers. And when you need to go to another view, just call

TTOpenURL(URL);

where the “URL” is mapped to the view you are going to. Now you know the basic idea of this topic, following are the resources I found useful:

• Basics of “URL based navigation”

 

• URL-based navigation and state persistence

 

• Difference between “toViewController”, “toSharedViewController” and “toModalViewController”

 

• Passing multiple parameters in URL based navigation

 

• Mapping a URL to a method call:

  [map from:@"tt://urlToDoSomething" toSharedViewController:[MyViewController class] selector:@selector(doSomething)];

• Specify transition animation:

  [[TTNavigator navigator] openURL:@"tt://login" animated:YES transition:UIViewAnimationTransitionFlipFromLeft];

Other Three20 Resources:

• Joe Hewitt: http://joehewitt.com/
• Joe Hewitt on three20: http://joehewitt.com/2009/03/23/the-three20-project
• Threee20 official website: http://three20.info/
• Three20 forums: http://forums.three20.info/
• Three20 on github: https://github.com/facebook/three20
• Nimbus (Three20 alternative): https://github.com/jverkoey/nimbus

1. www.raywenderlich.com
   • Posting Freq: High
   • Pros: This is by far my favorite iOS tutorial blog site. Ray and his co-bloggers did a wonderful job in all aspects, from explaining simple concepts to showing you how to make a fully functional complex games. Everything is made crystal clear. I specially like their style of “tutorial series”: which covers a big topic in several posts. Currently the topic is “iOS 5 Storyboard”.
   • Cons: My only wish for them is to cover more UIKit stuff. After all, not everybody is using cocos2d for his/her project.
2. MKBlog
   • Posting Freq: High
   • Pros: I discovered his blog when I started learning In App Purchase. And then has been following him. His posts covers many different areas and with a lot of attention to details. Very helpful.
   • Cons: Since this blog is also his personal blog, sometime there are some posts not related to iOS programming. While I still enjoy reading them, they are certainly not part of the techy posts.
3. iDevBlogADay
   • Posting Freq: Very High
   • Pros: Well, I think I don’t need to say much about this, . We all love it.
   • Cons: Not all blogs are in the same quality level. This is understandable since people has different priorities and sometime may not in the mood of writing.
4. Cocoa With Love
   • Post Freq: Low
   • Pros: Very, very good tutorials. The depth of their posts is one the best. Some posts provided very unique solutions to interesting problems.
   • Cons: I just hope they write more often, otherwise it will be a 5 star!
5. Cocoa is my girlfriend
   • Post Freq: Medium
   • Pros: Similar to “Cocoa with love” (both are about Love, isn’t it? ), this blog has awesome tutorial with great details. The author is also the author of the book “Core Data: Apple’s API for Persisting Data under Mac OS X” and “Core Animation: Simplified Animation Techniques for Mac and iPhone Development“.
   • Cons: Same, more posts will be great!
6. Use Your Loaf
   • Post Freq: Medium
   • Pros: Very good posts, with a lot of examples and well written.
7. nachbaur.com
   • Post Freq: Low
   • Pros: They don’t post often, but when they do, you can find some really good stuff, such as the Core Animation series.
8. Other iOS programming blogs I read:
   • Cocoanetics
   • iPhone Development
   • iPhone Development Blog

So what blogs do you read? Please share that with us in the comments!

At 10AM, I checked it again. Still no luck. So I logged into ITC’s website, and wanted to check the sale status from there. When I clicked on the “Sales and Trends”, first I got a SSL certificate alert. I ignored it, and let the browser continue. After a few seconds, I saw a shocking view on my browser:

When I saw this, the first thing went through my mind is I was on a wrong website. But I checked the url, and yes, it was “reportingitc.apple.com”. Then I remembered the warning about the SSL cert. So obviously the DNS of this domain (reportingitc.apple.com) was pointing to somewhere else — in this case, it was infoblox. Was ITC hacked? it might be. But I doubt it. The hacker has no reason to point the site to infoblox, which is another legitimate company. I think it’s more like something wrong at Apple internally.

A few hours later, ITC was back to normal. As usual, there was no update about this several-hour outage.

We all know Apple making excellent products, with the reputation of great attentions to details. But ITC shows another side of Apple — inefficient, reckless,  and maybe even unprofessional. For even small websites, they would put a note when the sites are going down for maintenance. But Apple often doesn’t. For any website, with such an embarrassing event, it would worth a explanation or apology. But none from Apple. I don’t even want to mention the quality of the ITC site, which is so last generation — that could be one of the reasons why they have so many down time.

Apple is a very capable company, both technically and business-wise. They have done many things right. But ITC is certainly not one of them. To me, only one thing can explain this: lack of attention. Yes, App Store is important to Apple. But developers not necessarily are. So a basic website is provided to support developers, with basic functionalities, and basic support. In short, to Apple, ITC is too trivia to care.

I really hope Android market can catch up more so that Apple may have a stronger sense of competition, which might leads to more resource on developer support. Hence better ITC. But at the meantime, I just want to let Apple know, please, please be serious about ITC.

P.S.: As many other pointed out, Apple did send out an email a few days before about this maintenance downtime. However, that outage clearly started earlier and ended later. Also, no matter what kind outage it is, the DNS error like that was simply unacceptable. What’s more, isn’t “no down time” should be the standard for modern websites? Even with releases. When do we see downtime on Google, Amazon, facebook, … ? Apple just took a lower standard on this.

In most of the cases, particle emitter generates particles randomly — random color, random size, random direction — with the control of some key parameters. But it is not always like that. Sometimes we want the generated particles to follow a certain path, such as water trace, a group of firefly, or sparkles in the wind. That’s what I am going to talk about this time — how to generate random particles along a path. Before we start, let’s take a look at the end result first.

As you can see in the demo, at first the particles ran around the character “2″; then in the second demo I created a path manually by clicking on all the vertices, and the particle emitter generated particles along the path I just created.

The details of how to create a particle emitter itself is not the focus of this post. There are plenty of good tutorials online about that. Actually my system is based on 71squared’s tutorial, which in my opinion is the one of the best tutorials in this category (link to tutorial). Their “Particle Designer” is also a great tool to simplify the process to create beautiful particles. If you haven’t read their tutorial but want to learn more about particle system, I strongly suggest you to go through it first. This blog is an improvement on top of the particle system implemented by 71squared.

Now let’s get to the details.

Every a fraction of a second, the particle system will update the positions of all live particles, and generate new particles at its predefined source location (with variances). New particles are generated one by one sequentially. To make them appear along a path (assuming CGPath in this post), we need to figure out at a certain timestamp, which point on the path should be the source location.

In the most straightforward case — when the path is a straight line, it is simple: we know the current moment and total duration, hence we know how many percent of time has passed; using this percentage, we can locate a point between the start point and the end point, which will be the source location to generate the particle for this moment.

It’s the same for other types of paths. The only difficult part is, since most the paths are polygonal lines, how to locate the point based on the percentage of elapsed time?

Imagine the polygonal line is a rope, and mark all the vertex points as red; now straighten the rope, you have a straight line with many red dots on it. Each dot has its own percentage value based on its distance to the start point and the total length of the rope. Once we are given a percentage value (P), by comparing with each of the vertex, we can eventually find two adjacent vertices with a smaller percentage value (P1), and a greater value (P2). Then we can get the location of the point at this moment:

x =  P / (P2 - P1) * (X2 - X1) + X1
y = P / (P2 - P1) * (Y2 - Y1) + Y1

So the steps to generate particles along a path are:

1. Once given a path, find all it’s vertices;
2. Get the percentage value for each vertex;
3. Locate the point based on the current percentage value and vertices;
4. Generate particle at this point.

Now let’s get to the programming part.

1. Find vertices of a CGPath

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

typedef struct {
    CGPoint point;
    CGPoint previousPoint;
    float portionFinished;
} CGPathControlPoint;
 
CGPathControlPoint *controlPoints;
 
- (void) setAnimationPath:(CGPathRef)path {
    if (animationPath) {
        CGPathRelease(animationPath);
    }
    if (controlPoints) {
        free(controlPoints);
    }
 
    animationPath = CGPathRetain(path);
 
    NSMutableArray* points = [NSMutableArray array];
	CGPathApply(animationPath, points, extractPointsApplier);
 
    totalControlPoints = [points count];
    if (totalControlPoints > 0) {
        controlPoints = calloc(totalControlPoints, sizeof(CGPathControlPoint));
 
        if (controlPoints == NULL) {
            NSLog(@"not enough memory to save cgpath information");
            return;
        } else {
            CGPoint prevPoint = CGPointMake(0.0, 0.0);
            float totalDistance = 0;
 
            for (int i = 0; i < totalControlPoints; i++) {
                CGPoint point = [[points objectAtIndex:i] CGPointValue];
 
                float thisDistance = 0.0f;
                if (i != 0) {
                    thisDistance = sqrtf(
                                         (point.x - prevPoint.x) * (point.x - prevPoint.x)
                                         + (point.y - prevPoint.y) * (point.y - prevPoint.y)
                                         );
                }
                totalDistance += thisDistance;
 
                controlPoints[i] = (CGPathControlPoint) {point, prevPoint, totalDistance};
 
                prevPoint = point;
            }
 
            for (int i = 0; i < totalControlPoints; i++) {
                CGPathControlPoint p = controlPoints[i];
 
                if (i == 0 && totalControlPoints > 1) {
                    CGPathControlPoint nextP = controlPoints[1];
                    CGPoint prevP = CGPointMake(2.0 * p.point.x - nextP.point.x, 2.0 * p.point.y - nextP.point.y);
 
                    controlPoints[0] = (CGPathControlPoint) {p.point, prevP, p.portionFinished / totalDistance};
                } else {
                    controlPoints[i] = (CGPathControlPoint) {p.point, p.previousPoint, p.portionFinished / totalDistance};
                }
            }
        }
    }
}

At first, I defined a new struct called “CGPathControlPoint”, which includes the current CGPoint and its percentage value. The previous point is also kept there for the purpose of calculating the emission angle, which is not a topic in this blog, so you can ignore that field for now.

Then I defined an array of control points “controlPoints”. Our goal is find all the vertices in a CGPath, and put them in this array. The magic happens at line #20:

CGPathApply(animationPath, points, extractPointsApplier);

CGPathApply is an iOS built-in method since version 2.0. What it does is, “for each element in a graphics path, calls a custom applier function”. In our case, the custom callback function is “extractPointsApplier”. Basically I created an array first (line 19), and the CGPathApply function will extract all vertices from the CGPath, and apply them to the callback function, which puts them back to the array. Here is the code for the callback function:

1
2
3
4
5
6
7
8
9

static void extractPointsApplier(void* info, const CGPathElement* element)
{
    NSMutableArray* points = (NSMutableArray*) info;
 
    if (element->points && element->type != kCGPathElementCloseSubpath) {
        CGPoint p = *(element->points);
        [points addObject:[NSValue valueWithCGPoint:p]];
    }
}

In above method, each CGPathElement is actually a vertex. It contains the CGPoint itself and a point type, which includes:

1
2
3
4
5
6
7
8

enum CGPathElementType {
   kCGPathElementMoveToPoint,
   kCGPathElementAddLineToPoint,
   kCGPathElementAddQuadCurveToPoint,
   kCGPathElementAddCurveToPoint,
   kCGPathElementCloseSubpath
};
typedef enum CGPathElementType CGPathElementType;

The callback function put all points in the array except the ones with type “kCGPathElementCloseSubpath”, because that usually means a duplicate point from the last vertex, just with different type.

2. Get percentage value for each vertex
After the call to CGPathApply, we have an array with all the vertices on the path. Then it’s easy to calculate the distances between two vertices and the total distance. On list 1, after line #20, is the implementation to find out the percentage value (portionFinished) for each vertex.

3. Locate the point
At each moment when we generate particles, we know exactly the elapsed time and total duration (or how many particles has generated and the max number of particles). Hence we know the percentage we have finished. Based on that percentage and the vertices we have extracted, it’s easy to figure out the current location:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

- (CGPathControlPoint) getPointByFinishedPortion: (float) portion {
    if (portion <= 0) {
        return controlPoints[0];
    } else if (portion >= 1) {
        return controlPoints[totalControlPoints - 1];
    } else {
        for (int i = 0; i < totalControlPoints; i++) {
            CGPathControlPoint cp = controlPoints[i];
            if (portion < cp.portionFinished) {
                CGPathControlPoint prevP = controlPoints[i - 1];
                float r = portion - prevP.portionFinished;
 
                float total = cp.portionFinished - prevP.portionFinished;
                r = r / total;
 
                float x = (cp.point.x - prevP.point.x) * r + prevP.point.x;
                float y = (cp.point.y - prevP.point.y) * r + prevP.point.y;
 
                return (CGPathControlPoint) {CGPointMake(x, y), prevP.point, 0.0};
            }
        }
 
        // should not happen
        return controlPoints[0];
    }
}

I think the code is pretty self-explained, so I won’t go though each line of them here.

4. Generate particles
Finally it’s time to generate particles. Again, I won’t cover actually how to generate particles here. Please refer 71squared’s tutorial and sample program for detail. The only different part is, in “addParticle” method, I added following lines:

1
2
3

if (animationType == kAnimatePath) {
        [self initParticle:particle atCGPathControlPoint:[self getPointByFinishedPortion:((float)particleCount / (float)maxParticles)]];
}

Basically the percentage value is calculated based on the generated particle count and the max number of particles, and then the current point is retrieved by using the function in step 3. In the method “initParticle:atCGPathControlPoint:”, a particle is generated at the control point, instead of the predefined source location. In this way, a particle is generated at each moment at different location. When they are put together, it looks like the particles are running along the path, just like what we have demoed in the video.

Finally I’ll put my demo project and some useful links here. Hopefully this post is helpful to you.

Links:

1. Xcode Project
2. http://www.youtube.com/watch?v=66qQ21ZVOoc
3. 71squared Tutorial For Particle Emitter
4. 71squared’s Particle Designer