Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 102 lines (71 sloc) 7.558 kb
9c6d6a2 @joehewitt First commit
joehewitt authored
1 Three20
2 =======
3
c2049af @joehewitt * README tweaks
joehewitt authored
4 Three20 is a collection of iPhone UI classes, like a photo viewer, and general utilities, like an HTTP disk cache. Three20 is derived from the [Facebook iPhone app][], which is one of the most downloaded iPhone apps ever.
d7bbd11 @joehewitt * Rename "href" to "url" and "stroke" to "border"
joehewitt authored
5
6 [![](http://farm4.static.flickr.com/3447/3378092101_40a62a04b2_m.jpg)](http://farm4.static.flickr.com/3447/3378092101_b064d8e339_o.jpg)
7 [![](http://farm4.static.flickr.com/3432/3378117315_846547cfba_m.jpg)](http://farm4.static.flickr.com/3432/3378117315_3bf905bdb6_o.jpg)
8 [![](http://farm4.static.flickr.com/3462/3378171111_ec1208541d_m.jpg)](http://farm4.static.flickr.com/3462/3378171111_666173111d_o.jpg)
9 [![](http://farm4.static.flickr.com/3646/3378998444_d0534d337f_m.jpg)](http://farm4.static.flickr.com/3646/3378998444_8d3b1eeef8_o.jpg)
10 [![](http://farm4.static.flickr.com/3552/3378940896_7b23cca98e_m.jpg)](http://farm4.static.flickr.com/3552/3378940896_8ccb5ea1c8_o.jpg)
11 [![](http://farm4.static.flickr.com/3592/3378941824_2fab2317c7_m.jpg)](http://farm4.static.flickr.com/3592/3378941824_6b7928e391_o.jpg)
12
13 Adding Three20 to your project
14 ==============================
15
16 Three20 is compiled as a static library, and the easiest way to add it to your project is to use Xcode's "dependent project" facilities. Here is how:
17
c2049af @joehewitt * README tweaks
joehewitt authored
18 1. Clone the three20 git repository: `git clone git://github.com/joehewitt/three20.git`. Make sure
19 you store the repository in a permanent place because Xcode will need to reference the files
20 every time you compile your project.
d7bbd11 @joehewitt * Rename "href" to "url" and "stroke" to "border"
joehewitt authored
21
c2049af @joehewitt * README tweaks
joehewitt authored
22 2. Locate the "Three20.xcodeproj" file under "three20/src". Drag Three20.xcodeproj and drop it onto
d7bbd11 @joehewitt * Rename "href" to "url" and "stroke" to "border"
joehewitt authored
23 the root of your Xcode project's "Groups and Files" sidebar. A dialog will appear -- make sure
20638f8 @joehewitt * Add a missing step to README instructions
joehewitt authored
24 "Copy items" is unchecked and "Reference Type" is "Relative to Project" before clicking "Add".
d7bbd11 @joehewitt * Rename "href" to "url" and "stroke" to "border"
joehewitt authored
25
26 3. Now you need to link the Three20 static library to your project. Click the "Three20.xcodeproj"
27 item that has just been added to the sidebar. Under the "Details" table, you will see a single
c2049af @joehewitt * README tweaks
joehewitt authored
28 item: libThree20.a. Check the checkbox on the far right of libThree20.a.
d7bbd11 @joehewitt * Rename "href" to "url" and "stroke" to "border"
joehewitt authored
29
8cdcbb0 @joehewitt * Add another detail to the install instructions
joehewitt authored
30 4. Now you need to add Three20 as a dependency of your project, so Xcode compiles it whenever
d7bbd11 @joehewitt * Rename "href" to "url" and "stroke" to "border"
joehewitt authored
31 you compile your project. Expand the "Targets" section of the sidebar and double-click your
32 application's target. Under the "General" tab you will see a "Direct Dependencies" section.
33 Click the "+" button, select "Three20", and click "Add Target".
34
20638f8 @joehewitt * Add a missing step to README instructions
joehewitt authored
35 5. Now you need to add the bundle of images and strings to your app. Locate "Three20.bundle" under
36 "three20/src" and drag and drop it into your project. A dialog will appear -- make sure
37 "Create Folder References" is selected, "Copy items" is unchecked, and "Reference Type" is
38 "Relative to Project" before clicking "Add".
39
40 6. Finally, we need to tell your project where to find the Three20 headers. Open your
c2049af @joehewitt * README tweaks
joehewitt authored
41 "Project Settings" and go to the "Build" tab. Look for "Header Search Paths" and double-click
8cdcbb0 @joehewitt * Add another detail to the install instructions
joehewitt authored
42 it. Add the relative path from your project's directory to the "three20/src" directory. Then
43 go to "Other Linker Flags" under the "Linker" section, and add "-ObjC" to the list of flags.
7bab43f @joehewitt * Minor code style tweaks and documentation updates
joehewitt authored
44
45 7. You're ready to go. Just #import "Three20/Three20.h" anywhere you want to use Three20 classes
46 in your project.
d7bbd11 @joehewitt * Rename "href" to "url" and "stroke" to "border"
joehewitt authored
47
48 What's in Three20?
49 ==================
50
51 Photo Viewer
52 ------------
53
c2049af @joehewitt * README tweaks
joehewitt authored
54 [TTPhotoViewController][] emulates Apple's Photos app with all of its flick n' pinch delight. You can supply your own "photo sources", which works similiarly to the data sources used by UITableView. Unlike Apple's Photos app, it isn't limited to photos stored locally. Your photos can be loaded from the network, and long lists of photos can be loaded incrementally.
d7bbd11 @joehewitt * Rename "href" to "url" and "stroke" to "border"
joehewitt authored
55
56 Message composer
57 ----------------
58
59 [TTMessageController][] emulates the message composer in Apple's Mail app. You can customize it to send any kind of message you want. Include your own set of message fields, or use the standard "To:" and "Subject:". Recipient names can be autocompleted from a data source that you provide.
60
61 Web image views
62 -----------------------
63
64 [TTImageView][] makes it as easy to display an image as it is in HTML. Just supply the URL of the image, and TTImageView loads it and displays it efficiently. TTImageView also works with the HTTP cache described below to avoid hitting the network when possible.
65
66 Internet-aware table view controllers
67 ---------------------------------------
68
69 [TTTableViewController][] and [TTTableViewDataSource][] help you to build tables which load their content from the Internet. Rather than just assuming you have all the data ready to go, like UITableView does by default, TTTableViewController lets you communicate when your data is loading, and when there is an error or nothing to display. It also helps you to add a "More" button to load the next page of data, and optionally supports reloading the data by shaking the device.
70
71 Better text fields
72 ------------------
73
74 [TTTextEditor][] is a UITextView which can grow in height automatically as you type. I use this for entering messages in Facebook Chat, and it behaves similarly to the editor in Apple's SMS app.
75
76 [TTPickerTextField][] is a type-ahead UITextField. As you type it searches a data source, and it adds bubbles into the flow of text when you choose a type-ahead option. I use this in TTMessageController for selecting the names of message recipients.
77
78 HTTP disk cache
79 --------------
80
81 [TTURLRequest][] is a replacement for NSURLRequest which supports a disk cache (NSURLRequest can only cache in RAM). It has some other nice features too. HTTP posts are as easy as supplying a dictionary of parameters. The TTURL loading system can also be suspended and resumed at any time, which is a great performance helper. Network threads often fight with the UI thread, so you can suspend the network any time your app is momentarily graphically intensive.
82
83 URL-based Navigation
84 --------------------
85
86 [TTNavigationCenter][] is for those grizzled old web developers like myself who want to organize their app by "pages" which can be displayed by visiting a URL.
87
88 Your view controllers can simply register URL patterns that they handle, and when those URLs are visited the controllers will be created and displayed. You can also register generic actions that are called when a URL is visited.
89
90 TTNavigationCenter also persists and restores the full path of navigation controllers and modal view controllers, so your users can quite the app and come back exactly where they left off.
91
92 [Facebook iPhone app]: http://phobos.apple.com/WebObjects/MZStore.woa/wa/viewSoftware?id=284882215&mt=8
93 [TTPhotoViewController]: http://github.com/joehewitt/three20/blob/master/src/Three20/TTPhotoViewController.h
94 [TTMessageController]: http://github.com/joehewitt/three20/blob/master/src/Three20/TTMessageController.h
95 [TTImageView]: http://github.com/joehewitt/three20/blob/master/src/Three20/TTImageView.h
96 [TTTableViewController]: http://github.com/joehewitt/three20/blob/master/src/Three20/TTTableViewController.h
97 [TTTableViewDataSource]: http://github.com/joehewitt/three20/blob/master/src/Three20/TTTableViewDataSource.h
98 [TTURLRequest]: http://github.com/joehewitt/three20/blob/master/src/Three20/TTURLRequest.h
99 [TTTextEditor]: http://github.com/joehewitt/three20/blob/master/src/Three20/TTTextEditor.h
100 [TTPickerTextField]: http://github.com/joehewitt/three20/blob/master/src/Three20/TTPickerTextField.h
101 [TTNavigationCenter]: http://github.com/joehewitt/three20/blob/master/src/Three20/TTNavigationCenter.h
Something went wrong with that request. Please try again.