Update : This article is now featured at Three20 website! (linky).

Three20 is an open source
iPhone/iPad library that packs a lot of cool
features.   Three20 is popular for its UI components
such as TTNavigator,  TTWebBrowser,
TTPhotoViewer.

Also there is lot more than UI in Three20.  I use Three20
sparingly in my iphone projects. I don’t build my app as a ‘full
blown three20 app’.  I use some components, to save myself
from re-inventing the wheels.  That is what I will focus on
here.

Getting Started

Follow steps from Three20
website on how to incorporate three20 into your iphone/ipad
project

WARNING : Do not skip any steps…

Sample Code

The sample Xcode project is here : http://github.com/sujee/three20-tidbits

Include

  #import "Three20/Three20+Additions.h"

in the file where you want to use the functions

NSString  Additions

code : Three20Core / NSStringAdditions.h

whitespace check

To see if strings only have white space (blank?)

NSLog(@"\n\n====== NSString : white space =======");
NSString *ws = @" \t\n";
NSString *empty = @"    ";
NSString *nws = @"hello";
NSLog(@"'%@' contains only whitespace ? : %d", ws, [ws isWhitespaceAndNewlines]);
NSLog(@"'%@' contains only whitespace ? : %d", nws, [nws isWhitespaceAndNewlines]);        
NSLog(@"'%@' is empty? : %d", empty, [empty isEmptyOrWhitespace]);  

Output:

====== NSString : white space =======
' 	
' contains only whitespace ? : 1
'hello' contains only whitespace ? : 0
'    ' is empty? : 1

strip HTML tags

handy for displaying user-entered data (comment / feedback) on UIWebView. We want to strip the HTML and only show text.

  
NSLog(@"\n\n====== NSString : stripHTML =======");
NSString *html = @"I <b>am</b> an HTML script.  <script type='text/javascript'>alert('surprise')</script>";
NSString *stipped = [html stringByRemovingHTMLTags];
NSLog(@"html : %@", html);
NSLog(@"stripped : %@", stipped);

output:

NSLog(@"\n\n====== NSString : stripHTML =======");
html : I <b>am</b> an HTML script.  <script type='text/javascript'>alert('surprise')</script>
stripped : I am an HTML script.  alert('surprise')

Parsing URL query parameters

Parse URL query paramters and put them in a nice NSDIctionary

  
NSLog(@"\n\n====== NSString : parse URL params =======");
NSURL *url = [NSURL URLWithString:@"http://www.google.com/search?sourceid=chrome&ie=UTF-8&q=pizza"];
NSString *paramString = [url query];
NSDictionary *params = [paramString queryDictionaryUsingEncoding:NSASCIIStringEncoding];
NSLog(@"url : %@", url);
NSLog(@"params:\n%@", params);

Output:

====== NSString : parse URL params =======
url : http://www.google.com/search?sourceid=chrome&ie=UTF-8&q=pizza
params:
{
    ie = "UTF-8";
    q = pizza;
    sourceid = chrome;
}

Creating a URL from parameters

Create a valid query string from a NSDictionary

NSLog(@"\n\n====== NSString : create URL query string =======");
NSString *baseUrl = @"http://www.yahoo.com/search";
NSMutableDictionary *params = [[NSMutableDictionary alloc] init];
[params setValue:@"pizza" forKey:@"q"];
[params setValue:@"json" forKey:@"format"];
NSString *fullURL = [baseUrl stringByAddingQueryDictionary:params];
NSLog(@"query parameters\n%@", params);
NSLog(@"query string is : %@", fullURL);

Output:

====== NSString : create URL query string =======
query parameters
{
    format = json;
    q = pizza;
}
query string is : http://www.yahoo.com/search?q=pizza&format=json

md5 hash

when you want to get md5-hash a string

NSLog(@"\n\n====== NSString : md5 =======");
NSString *s1 = @"hiya three20 world";
NSString *md5 = [s1 md5Hash];
NSLog(@"md5('%@') =>  %@", s1, md5);

Output:

====== NSString : md5 =======
md5('hiya three20 world') =>  6fd98ef06e6041b87dbe8dc978b95c4c

md5Hash is also available for NSData

Version Compare:

is “3.5” > “3.0.1”

  
NSLog(@"\n\n====== NSString : version check =======");
NSString *v1 = @"2.5";
NSString *v2 = @"3.0";
NSString *v3 = @"3.0.1";
NSLog(@"%@ <=> %@  is %d", v2, v1, [v2 versionStringCompare:v1]);
NSLog(@"%@ <=> %@  is %d", v1, v2, [v1 versionStringCompare:v2]);
NSLog(@"%@ <=> %@  is %d", v3, v2, [v3 versionStringCompare:v2]);
NSLog(@"%@ <=> %@  is %d", v3, v3, [v3 versionStringCompare:v3]);

Output:

====== NSString : version check =======
3.0 <=> 2.5  is 1
2.5 <=> 3.0  is -1
3.0.1 <=> 3.0  is 1
3.0.1 <=> 3.0.1  is 0

NSDate Additions

file :
Three20Core/NSDateAdditions.h

There is lot of goodies here.  My favorite is ‘relative
time’… like ‘2 hours ago’,   ‘few minutes ago’
…etc

Also it has handy functions to create various dates with ease (check the header file)

  
NSLog(@"\n\n====== NSDate : format =======");
NSDate *todayMidnight = [NSDate dateWithToday];
NSLog(@"today midnight date is : %@", [todayMidnight formatDate]);

NSDate *timeNow = [[NSDate alloc] init];
NSDate *fewDaysBack = [[NSDate alloc] initWithTimeIntervalSinceReferenceDate:[timeNow timeIntervalSinceReferenceDate] - (3600*24 * 4)];

NSLog(@"\n\n====== NSDate : relative time =======");
NSLog(@"today midnight was : %@", [todayMidnight formatRelativeTime]);
NSLog(@"just now was : %@", [timeNow formatRelativeTime]);
NSLog(@"few days back was (short format) : %@ ago", [fewDaysBack formatShortRelativeTime]);

Output:

====== NSDate : format =======
today midnight date is : Thursday, August 19, 2010

====== NSDate : relative time =======
today midnight was : 23 hours ago
just now was : just a moment ago
few days back was (short format) : 4d ago

Network Activity Indicator

file : Three20Network/TTGlobalNetwork.h

When you have multiple network requests going on (different threads ..etc), here is a handy function to keep the network indicator spinning straight….

  
TTNetworkRequestStarted();
//.....
TTNetworkRequestStopped();

Common UI stuff

file : Three20UICommon/TTGlobalUICommon.h

Some goodies here…. I will just post the header file. Functions for checking OS Version and if running iPad..etc

 
/**
 * @return the current runtime version of the iPhone OS.
 */
float TTOSVersion();

/**
 * Checks if the link-time version of the OS is at least a certain version.
 */
BOOL TTOSVersionIsAtLeast(float version);

/**
 * @return TRUE if the keyboard is visible.
 */
BOOL TTIsKeyboardVisible();

/**
 * @return TRUE if the device has phone capabilities.
 */
BOOL TTIsPhoneSupported();

/**
 * @return TRUE if the device is iPad.
 */
BOOL TTIsPad();

/**
 * @return the current device orientation.
 */
UIDeviceOrientation TTDeviceOrientation();

/**
 * On iPhone/iPod touch
 * Checks if the orientation is portrait, landscape left, or landscape right.
 * This helps to ignore upside down and flat orientations.
 * 
 * On iPad:
 * Always returns Yes.
 */
BOOL TTIsSupportedOrientation(UIInterfaceOrientation orientation);

/**
 * @return the rotation transform for a given orientation.
 */
CGAffineTransform TTRotateTransformForOrientation(UIInterfaceOrientation orientation);

/**
 * @return the application frame with no offset.
 *
 * From the Apple docs:
 * Frame of application screen area in points (i.e. entire screen minus status bar if visible)
 */
CGRect TTApplicationFrame();

/**
 * @return the toolbar height for a given orientation.
 *
 * The toolbar is slightly shorter in landscape.
 */
CGFloat TTToolbarHeightForOrientation(UIInterfaceOrientation orientation);

/**
 * @return the height of the keyboard for a given orientation.
 */
CGFloat TTKeyboardHeightForOrientation(UIInterfaceOrientation orientation);

/**
 * A convenient way to show a UIAlertView with a message.
 */
void TTAlert(NSString* message);

TTImageView

file : Three20UI/TTImageView.h

This is a drop-in replacement for any UIImageView, where image has to be loaded from a URL. All you do is feed a URL and it does the rest (starts downloading the image, shows placeholder image while downloading, and displays the image)! Self-contained. Also uses TTCache, so if the image has already been downloaded, it will not downloaded it, will just use from cache… cool!

  
// create TTImageView,
// this can be done programatically, or change the class name
// to 'TTImageView' in Interface Builder
TTImageView *imgView = [[TTImageView alloc] init];
// default image is displayed unitll the image is downloaded
imgView.defaultImage = [UIImage imageNamed:@"place-holder.png"];
// give it a URL to load image from
imgView.urlPath = @"image url path";

// now set the imageView to where ever you want
// self.imageView = imgView