teacup 1.3.4 → 2.0.0

data/README.md

@@ -1,19 +1,23 @@
 Teacup
 ======
 
-A community-driven DSL for creating user interfaces on the iphone.
+A community-driven DSL for creating user interfaces on iOS.
 
 [![Build Status](https://travis-ci.org/rubymotion/teacup.png)](https://travis-ci.org/rubymotion/teacup)
 
-Using teacup, you can easily create and style layouts while keeping your code
-dry.  The goal is to offer a rubyesque (well, actually a rubymotion-esque) way
-to create interfaces programmatically.
+Using Teacup, you can create and style layouts and keeping your code dry.  The
+goal is to offer a rubyesque (well, actually a rubymotion-esque) way to create
+interfaces programmatically.
 
-**Check out a working sample app [here][Hai]!**
+**Check out some sample apps!**
 
-[Hai]: https://github.com/rubymotion/teacup/tree/master/samples/Hai
+* “[Hai][Hai]”
+* “[AutoLayout][AutoLayout]”
+* “[OnePage][OnePage]”
 
-#### Installation
+[Hai]: https://github.com/rubymotion/teacup/tree/master/samples/Hai
+[AutoLayout]: https://github.com/rubymotion/teacup/tree/master/samples/AutoLayout
+[OnePage]: https://github.com/rubymotion/teacup/tree/master/samples/OnePage
 
 **Quick Install**
 
@@ -25,16 +29,6 @@ and in your Rakefile
 require 'teacup'
 ```
 
-**Better Install**
-
-However, it is recommended that you use [Bundler][] and [rvm][] to manage your
-gems on a per-project basis, using a gemset.  See the
-[Installation wiki page][Installation] for more help on doing that.
-
-[Bundler]: http://gembundler.com/
-[rvm]: https://rvm.io/
-[Installation]: https://github.com/rubymotion/teacup/wiki/Installation
-
 #### 10 second primer
 
 1.  Create a `UIViewController` subclass:
@@ -55,441 +49,1302 @@ gems on a per-project basis, using a gemset.  See the
       stylesheet :main_screen
 
       layout do
-        subview(UIButton, :finished_button)
+        subview(UIButton, :hi_button)
       end
     end
     ```
-4.  Create the stylesheet (Usually in app/styles/)
+4.  Create the stylesheet (in `app/styles/` or somewhere near the controller)
 
     ```ruby
     Teacup::Stylesheet.new :main_screen do
-      style :finished_button,
+      style :hi_button,
         origin: [10, 10],
         title: 'Hi!'
     end
     ```
 
-Teacup implements the `viewDidLoad` method and instantiates any views you
-declare in the `layout` block.  Make sure to call `super` if you implement
-`viewDidLoad`, or you can use the "teacup-esque" `layoutDidLoad` method.
 
-#### Styling Without Implicitly Adding the View
-In the situation where you'd like to utilize the styles of Teacup without having your view
-automatically added in `viewDidLoad`.  You can accomplish this by calling the `layout` method instead of the block.
+Teacup
+------
+
+Teacup's goal is to facilitate the creation and styling of your `UIViews`
+hierarchy. Say "Goodbye!" to Xcode & XIB files!
+
+Teacup is composed of two systems:
+
+- Layouts
+  A DSL to create `UIViews` and to organize them in a hierarchy.  You assign the
+  style name and style classes from these methods.
+
+- Stylesheets
+  Store the "styles" that get applied to your views.  The stylesheet DSL is
+  meant to resemble CSS, but is targeted at iOS, and so the precedence rules are
+  very different.
+
+Teacup supports [Pixate][] and [NUI][], too, so you can use those systems for
+styling and Teacup to manage your view hierarchy and apply auto-layout
+constraints.  Teacup can also integrate with the [motion-layout][] gem!
+
+### Table of Contents
+
+* [Layouts](#layouts)
+* [Stylesheets](#stylesheets)
+  * [Using and re-using styles in a Stylesheet](#using-and-re-using-styles-in-a-stylesheet)
+  * [Style via Stylename](#style-via-stylename)
+  * [Extending Styles](#extending-styles)
+  * [Style via UIView Class](#style-via-uiview-class)
+  * [Importing stylesheets](#importing-stylesheets)
+  * [Style via UIAppearance](#style-via-uiappearance)
+* [More Teacup features](#more-teacup-features)
+  * [Styling View Properties](#styling-view-properties)
+  * [Orientation Styles](#orientation-styles)
+  * [UIView animation additions](#uiview-animation-additions)
+  * [Style Handlers](#style-handlers)
+  * [Frame Calculations](#frame-calculations)
+  * [Auto-Layout](#auto-layout)
+  * [Motion-Layout](#motion-layout)
+  * [Stylesheet extensions](#stylesheet-extensions)
+    * [Autoresizing Masks](#autoresizing-masks)
+    * [Device detection](#device-detection)
+    * [Rotation helpers](#rotation-helpers)
+* [Showdown](#showdown)
+* [The Nitty Gritty](#the-nitty-gritty)
+* [Advanced Teacup Tricks](#advanced-teacup-tricks)
+  * [UITableViewCell](#uitableviewcell)
+  * [Sweettea](#sweettea)
+* [Misc notes](#misc-notes)
+* [The Dummy](#the-dummy)
+
+Layouts
+-------
+
+The `Teacup::Layout` module is mixed into `UIViewController` and `UIView` so
+that these two classes can take advantage of the view-hierarchy DSL.
+
+You saw an example in the primer, using the `UIViewController` class method
+`layout`.  This is a helper function that stores the layout code.  A more direct
+example might look like this:
 
 ```ruby
-# Custom Navigation Title still styled by Teacup
-@custom_label = layout(UILabel, :custom_title)
-self.navigationItem.titleView = @custom_label
+# controller example
+class MyController < UIViewController
+
+  def viewDidLoad
+    # we will modify the controller's `view`, assigning it the stylename `:root`
+    layout(self.view, :root) do
+      # these subviews will be added to `self.view`
+      subview(UIToolbar, :toolbar)
+      subview(UIButton, :hi_button)
+    end
+  end
+
+end
 ```
 
-Additionally, you can use the `style` method on a view to apply your styling inline (e.g. `@label.style(styles)`).
+You can use very similar code in your `UIView` subclasses.
 
-#### Showdown
+```ruby
+# view example
+#
+# if you use teacup in all your projects, you can bundle your custom views with
+# their own stylesheets
+def MyView < UIView
+
+  def initWithFrame(frame)
+    super.tap do
+      self.stylesheet = :my_stylesheet
+      subview(UIImageView, :image)
+    end
+  end
+
+end
+```
 
-Cocoa
+The `layout` and `subview` methods are the work horses of the Teacup view DSL.
+
+* `layout(uiview|UIViewClass, stylename, style_classes, additional_styles, &block)`
+  - `uiview|UIViewClass` - You can layout an existing class or you can have
+    teacup create it for you (it just calls `new` on the class, nothing
+    special).  This argument is required.
+  - `stylename` (`Symbol`) - This is the name of a style in your stylesheet. It
+    is optional
+  - `style_classes` (`[Symbol,...]`) - Other stylenames, they have lower
+    priority than the `stylename`.
+  - `additional_styles` (`Hash`) - You can pass other styles in here as well,
+    either to override or augment the settings from the `Stylesheet`.  It is
+    common to use this feature to assign the `delegate` or `dataSource`.
+  - `&block` - See discussion below
+  - Returns the `uiview` that was created or passed to `layout`.
+  - only the `uiview` arg is required.  You can pass any combination of
+    stylename, style_classes, and additional_styles (some, none, or all).
+* `subview(uiview|UIViewClass, stylename, style_classes, additional_styles, &block)`
+  - Identical to `layout`, but adds the view to the current target
+
+The reason it is so easy to define view hierarchies in Teacup is because the
+`layout` and `subview` methods can be "nested" by passing a block.
 
 ```ruby
-class SomeController < UIViewController
+subview(UIView, :container) do  # create a UIView instance and give it the stylename :container
+  subview(UIView, :inputs) do  # create another container
+    @email_input = subview(UITextField, :email_input)
+    @password_input = subview(UITextField, :password_input)
+  end
+  subview(UIButton.buttonWithType(UIButtonTypeRoundedRect), :submit_button)
+end
+```
 
-  def viewDidLoad
+These methods are defined in the `Layout` module. And guess what!?  It's easy
+to add your *own view helpers*!  I refer to this as a "partials" system, but
+really it's just Ruby code (and isn't that the best system?).
 
-    @field = UITextField.new
-    @field.frame = [[10, 10], [200, 50]]
-    @field.textColor = UIColor.redColor
-    view.addSubview(@field)
+```ruby
+# the methods you add here will be available in UIView, UIViewController, and
+# any of your own classes that `include Teacup::Layout`
+module Teacup::Layout
 
-    @search = UITextField.new
-    @search.frame = [[10, 70], [200, 50]]
-    @search.placeholder = 'Find something...'
-    @search.textColor = UIColor.redColor
-    view.addSubview(@search)
+  # creates a button and assigns a default stylename
+  def button(*args, &block)
+    # apply a default stylename
+    args = [:button] if args.empty?
 
-    true
+    # instantiate a button and give it a style class
+    subview(UIButton.buttonWithType(UIButtonTypeCustom), *args, &block)
   end
 
-  # code to enable orientation changes
-  def shouldAutorotateToInterfaceOrientation(orientation)
-    if orientation == UIInterfaceOrientationPortraitUpsideDown
-      return false
-    end
-    true
+  # creates a button with an icon image and label
+  def button_with_icon(icon, title)
+    label = UILabel.new
+    label.text = title
+    label.sizeToFit
+
+    image_view = UIImageView.new
+    image_view.image = icon
+    image_view.sizeToFit
+
+    button = UIButton.buttonWithType(UIButtonTypeCustom)
+    button.addSubview(image_view)
+    button.addSubview(label)
+
+    # code could go here to position the icon and label, or at could be handled
+    # by the stylesheet
+
+    subview(button)
   end
 
-  # perform the frame changes depending on orientation
-  def willAnimateRotationToInterfaceOrientation(orientation, duration:duration)
-    case orientation
-    when UIInterfaceOrientationLandscapeLeft, UIInterfaceOrientationLandscapeRight
-      @field.frame = [[10, 10], [360, 50]]
-      @search.frame = [[10, 70], [360, 50]]
-    else
-      @field.frame = [[10, 10], [200, 50]]
-      @search.frame = [[10, 70], [200, 50]]
-    end
+end
+```
+###### example use of the helper methods
+```
+class MyController < UIViewController
+
+  layout do
+    @button1 = button()
+    @button2 = button(:blue_button)
+    @button3 = button_with_icon(UIImage.imageNamed('email_icon'), 'Email')
   end
 
 end
 ```
 
-Teacup
+The `UIViewController##layout` method that has been used so far is going to be
+the first or second thing you add to a controller when you are building an app
+with Teacup.  It's method signature is
 
 ```ruby
-# Stylesheet
+UIViewController.layout(stylename=nil, styles={}, &block)
+```
 
-Teacup::Stylesheet.new(:some_view) do
+* `stylename` is the stylename you want applied to your controller's `self.view`
+  object.
+* `styles` are *rarely* applied here, but one common use case is when you assign
+  a custom view in `loadView`, and you want to apply settings to it.  I find it
+  cleaner to move this code into the body of the `layout` block, though.
+* `&block` is the most important - it is the layout code that will be called
+  during `viewDidLoad`.
+
+After the views have been added and styles have been applied Teacup calls the
+`layoutDidLoad` method.  If you need to perform some additional initialization
+on your views, you should do it in this method.  If you use the `layout` block
+the styles have not yet been applied.  Frames will not be set, text and titles
+will be empty, and images will not have images.  This all happens at the *end*
+of the `layout` block.
 
-  style :root,
-    landscape: true  # enable landscape rotation (otherwise only portrait is enabled)
-                     # this must be on the root-view, to indicate that this view is
-                     # capable of handling rotations
+Stylesheets
+-----------
 
-  style :field,
-    left:   10,
-    top:    10,
-    width:  200,
-    height: 50,
-    landscape: {
-      width: 360  # make it wide in landscape view
-    }
+This is where you will store your styling-related code. Migrating code from your
+controller or custom view into a stylesheet is very straightforward. The method
+names map 1::1.
 
-  style :search, extends: :field,
-    left: 10,
-    top: 70,
-    placeholder: 'Find something...'
+```ruby
+# classic Cocoa/UIKit
+def viewDidLoad
+  self.view.backgroundColor = UIColor.grayColor
+  #         ^.............^
+end
 
-  style UITextField,                # Defining styles based on view class instead
-    textColor: UIColor.redColor     # of style name.
+# in Teacup
+def viewDidLoad
+  self.stylesheet = :main
+  self.view.stylename = :root
+end
 
+Teacup::Stylesheet.new :main do
+  style :root,
+    backgroundColor: UIColor.grayColor
+#   ^.............^
 end
+```
 
-# Controller
+Nice! We turned three lines of code into nine!  Well, obviously the benefits
+come in when we have *lots* of style code, and when you need to do app-wide
+styling.
 
-class SomeController < UIViewController
+You can store stylesheets in any file.  It is common to use `app/styles.rb` or
+`app/styles/main.rb`, if you have more than a few of 'em.  The
+`Teacup::Stylesheet` constructor accepts a stylesheet name and a block, which
+will contain your style declarations.
 
-  # the stylesheet determines the placement and design of your views.  You can
-  # also implement a stylesheet method, or assign the stylesheet name to the
-  # UIViewController later.
-  stylesheet :some_view
+```ruby
+Teacup::Stylesheet.new :main_menu do
+  style :ready_to_play_button,
+    backgroundColor: UIColor.blackColor,
+    frame: [[20, 300], [50, 20]]
+end
 
-  # think of this as a nib file that you are declaring in your UIViewController.
-  # it is styled according to the :root styles, and can add and style subviews
-  layout :root do
-    subview(UITextField, :field)
-    @search = subview(UITextField, :search)
-  end
+Teacup::Stylesheet[:main_menu]  # returns this stylesheet
+```
+
+Any method that accepts a single value can be assigned in a stylesheet.  Please
+don't abuse this by hiding application logic in your stylesheets - these are
+meant for *design*, not behavior.
+
+### Using and re-using styles in a Stylesheet
 
-  # you have to enable the auto-rotation stuff by implementing a
-  # shouldAutorotateToInterfaceOrientation method
-  def shouldAutorotateToInterfaceOrientation(orientation)
-    # but don't worry, we made that painless, too!
-    autorotateToOrientation(orientation)
+- Styles are be applied via stylename (`style :label`) or class (`style UILabel`)
+- Styles can extend other styles (`style :big_button, extends: :button`)
+- A stylesheet can import other stylesheets (`import :app`)
+- The special Appearance stylesheet can be used to apply styles to `UIAppearance`
+  (`Teacup::Appearance.new`)
+
+Let's look at each in turn.
+
+### Style via Stylename
+
+This is the most common way to apply a style.
+
+```ruby
+class MainController < UIViewController
+
+  stylesheet :main  # <= assigns the stylesheet named :main to this controller
+
+  layout do
+    subview(UILabel, :h1)  # <= :h1 is the stylename
   end
 
+end
+
+Teacup::Stylesheet.new :main do  # <= stylesheet name
+
+  style :h1,  # <= style name
+    font: UIFont.systemFontOfSize(20)  # <= and this style is applied
+
 end
 ```
 
-The orientation styling is really neat.  I think you'll find that you will be
-more inspired to enable multiple orientations because the code is so much more
-painless.
+When the stylesheet is applied (at the end of the `layout` block, when all the
+views have been added), its `font` property will be assigned the value
+`UIFont.systemFontOfSize(20)`.
 
-Stylesheets
------------
+But we didn't assign any text!
 
-The basic format for a `style` is a name and a dictionary of "styles".  These
-are usually just methods that get called on the target (a `UIView` or `CALayer`,
-most likely), but they can also perform introspection, using "handlers".
+We can tackle this a couple ways.  You can apply "last-minute" styles in the
+`layout` and `subview` methods:
 
-Basics
-======
+```ruby
+layout do
+  subview(UILabel, :h1,
+    # the `subview` and `layout` methods can apply styles
+    text: "Omg, it's full of stars"
+    )
+end
+```
 
-Create a stylesheet in any code file, usually `styles.rb` or `styles/main.rb`,
-if you have a ton of 'em.  The `Teacup::Stylesheet` constructor accepts a
-stylesheet name and a block, which will contain your style declarations.
+In this case though we just have static text, so you can assign the text using
+the stylesheet:
 
 ```ruby
-Teacup::Stylesheet.new :main_menu do
-  style :ready_to_play_button,
-    backgroundColor: UIColor.blackColor,
-    frame: [[20, 300], [50, 20]]  # [[x, y], [w, h]]
+Teacup::Stylesheet.new :main do
+
+  style :h1,
+    font: UIFont.systemFontOfSize(20)
+
+  style :main_header,
+    text: "Omg, it's full of stars",
+    font: UIFont.systemFontOfSize(20)
+
 end
 ```
 
-Any method that accepts a single value can be assigned here.  Please don't abuse
-this by hiding application logic in your stylesheets - these are meant for
-*design*, not behavior.  That said, if you're coding by yourself - go for it! ;)
+### Extending Styles
 
-Stylesheets
-===========
+Not very DRY though is it!?  We have to use a new style (`:main_header`) because
+not all our labels say "OMG", but we want to use our font from the `:h1` style.
+We can tell the `:main_header` style that it `extends` the `:h1` style:
+
+```ruby
+layout do
+  subview(UILabel, :main_header)
+end
+
+Teacup::Stylesheet.new :main do
+
+  style :h1,
+    font: UIFont.systemFontOfSize(20)
+
+  style :main_header, extends: :h1,
+    text: "Omg, it's full of stars"
+
+end
+```
+
+A common style when writing stylesheets is to use instance variables to store
+settings you want to tweak.
+
+```ruby
+Teacup::Stylesheet.new :main do
+  @hi_font = UIFont.systemFontOfSize(20)
 
-The `Teacup::Stylesheet` class has methods that create a micro-DSL in the
-context of a `style` declaration.  You can view the source (most of them are
-very short methods) in `lib/teacup/stylesheet_extensions/*.rb`.
+  style :h1,
+    font: @hi_font
+  style :main_header, extends: :h1,
+    text: "Omg, it's full of stars"
+end
+```
+
+### Style via UIView Class
+
+If you need to apply styles to *all* instances of a `UIView` subclass, you can
+do so by applying styles to a class name instead of a symbol.  This feature is
+handy at times when you might otherwise use `UIAppearance` (which teacup also
+supports!).
 
 ```ruby
-# autoresizingMask
-style :spinner,
-  center: [320, 460],
-  autoresizingMask: flexible_left|flexible_right|flexible_top|flexible_bottom
+Teacup::Stylesheet.new :app do
 
+  style UILabel,
+    font: UIFont.systemFontOfSize(20)
 
-# device-specific geometries - app_size, screen_size, and device/device? methods
-style :root,
-  origin: [0, 0],
-  size: app_size  # doesn't include the status bar - screen_size does
+  style UITableView,
+    backgroundColor: UIColor.blackColor
 
-if device? iPhone
-  style :image, image: UIImage.imageNamed "my iphone image"
-elsif device? iPad
-  style :image, image: UIImage.imageNamed "my ipad image"
 end
+```
+
+### Importing stylesheets
+
+We've touched on the ability to write styles, extend styles, and apply styles to
+a class.  Now we can introduce another feature that is even more useful for
+applying styles to your entire app: import a stylesheet.
+
+When you import a stylesheet, you receive all of its `style`s *and* you gain
+access to its instance variables. This way you can define colors and margins and
+such in a "parent" stylesheet.
+
+```ruby
+Teacup::Stylesheet.new :app do
+
+  @header_color = UIColor.colorWithRed(7/255.0, green:16/255.0, blue:95/255.0, alpha: 1)
+  @background_color = UIColor.colorWithRed(216/255.0, green:226/255.0, blue:189/255.0, alpha: 1)
+
+  style :root,
+    backgroundColor: @background_color
+
+  style :header,
+    textColor: @header_color
 
-# the device method can be OR'd with the devices.  The return value is always a
-# number, so make sure to compare to 0
-if device|iPhone > 0
-  # ...
 end
-# so yeah, you might as well use `device? iPhone`, in my opinion.
 
+Teacup::Stylesheet.new :main do
+  import :app
 
-# rotations - use the identity and pi methods
-style :button,
-  layer: {
-    transform: spin identity, 2*pi
-  }
+  style :subheader, extends: :header  # <= the :header style is imported from the :app stylesheet
+
+  style :button,
+    titleColor: @header_color  # <= @header_color is imported, too
+end
 ```
 
-Orientations
-============
+### Style via UIAppearance
 
-Teacup stylesheets can be given orientation hashes.  The supported orientations
-are:
+And lastly, the `UIAppearance protocol` is supported by creating an instance of
+`Teacup::Appearance`.  There is debatable benefit to using [UIAppearance][],
+because it will apply styles to views that are outside your control, like the
+camera/image pickers and email/message controllers.  Using `import` instead will
+not apply styles to those views.
+
+But, it does come in handy sometimes... so here it is!
+
+```ruby
+Teacup::Appearance.new do
 
-- `portrait` - upright or upside down
-- `upside_up`
-- `upside_down`
-- `landscape` - on either side
-- `landscape_left` - "left" refers to the home button, e.g. the button is on the left.
-- `landscape_right` - home button is on the right
+  # UINavigationBar.appearance.setTintColor(UIColor.blackColor)
+  style UINavigationBar,
+    tintColor: UIColor.blackColor
 
-An example should suffice:
+  # UINavigationBar.appearanceWhenContainedIn(UINavigationBar, nil).setTintColor(UIColor.blackColor)
+  style UIBarButtonItem, when_contained_in: UINavigationBar,
+    tintColor: UIColor.blackColor
+
+  # UINavigationBar.appearanceWhenContainedIn(UIToolbar, UIPopoverController, nil).setTintColor(UIColor.blackColor)
+  style UIBarButtonItem, when_contained_in: [UIToolbar, UIPopoverController],
+    tintColor: UIColor.blackColor
+
+end
+```
+
+That block is called using the `UIApplicationDidFinishLaunchingNotification`,
+but that notification is not called until the *end* of the
+`application(application,didFinishLaunchingWithOptions:launchOptions)` method.
+This is sometimes after your views have been created, and so they will not be
+styled. If that is the case, call `Teacup::Appearance.apply` before creating
+your `rootViewController`.
+
+### Now go use Teacup!
+
+You have enough information *right now* to go play with Teacup.  Check out the
+example apps, write your own, whatever.  But read on to hear about why Teacup is
+more than just writing `layouts` and applying styles.
+
+Teacup as a utility
+-------------------
+
+When you are prototyping an app it is useful to bang out a bunch of code
+quickly, and here are some ways that Teacup might help.
+
+You can use all the methods above without having to rely on the entirety of
+Teacup's layout and stylesheet systems. By that I mean *any* time you are
+creating a view hierarchy don't be shy about using Teacup to do it.
+
+`UIView` has the `style` method, which can be used to group a bunch of
+customizations anywhere in your code. You don't *have* to pull out a stylesheet
+to do it.
 
 ```ruby
-style :ready_to_play_button,
-  portrait: {
-    frame: [[20, 300], [50, 20]]
-  },
-  landscape: {
-    frame: [[60, 300], [50, 20]]  # button moves over 40 pixels because of the wider screen
-  }
+# Custom Navigation Title created and styled by Teacup
+self.navigationItem.titleView = layout(UILabel,
+  text:'Title',
+  font: UIFont.systemFontOfSize(12),
+  )
+
+# Customize contentView in a UITableViewCell dataSource method
+def tableView(table_view, cellForRowAtIndexPath:index_path)
+  cell_identifier = 'MyController - cell'
+  cell = table_view.dequeueReusableCellWithIdentifier(cell_identifier)
+
+  unless cell
+    cell = UITableViewCell.alloc.initWithStyle(UITableViewCellStyleDefault,
+                        reuseIdentifier: cell_identifier)
+    layout(cell.contentView) do
+      subview(UIImageView, :image)
+    end
+  end
+
+  return cell
+end
+
+# Use the `style` method on a view to apply your styling. This is a one-shot
+# styling.
+@label.style(textColor: UIColor.blueColor, text: 'Blue Label')
 ```
 
-That code is repetive, though, let's shorten it up by using precedence and some
-aliases for setting the `frame`:
+More Teacup features
+--------------------
+
+There are a few (OK, a bunch) more features that Teacup provides that deserve
+discussion:
+
+- Styling View Properties
+- Orientation Styles
+- UIView Additions
+- Style Handlers
+- Frame Calculations
+- Auto-Layout & [Motion-Layout][motion-layout]
+- Stylesheet Extensions
+
+### Styling View Properties
+
+Styling a UIView is fun, but a UIView is often composed of many objects, like
+the `layer`, or maybe an `imageView` or `textLabel` and so on.  You can style
+those, too!
 
 ```ruby
-style :ready_to_play_button,
-  top: 300,
-  width: 50,
-  height: 20,
-  portrait: {
-    left: 20
+# UITableViewCells have a contentView, a backgroundView, imageView, textLabel,
+# detailTextLabel, and a layer! whew!
+style :tablecell,
+  layer: {  # style the layer!
+    shadowRadius: 3
   },
-  landscape: {
-    left: 60
+  backgroundView: {  # style the background!
+    backgroundColor: UIColor.blackColor
+  },
+  imageView: {  # style the imageView!
+    contentMode: UIViewContentModeScaleAspectFill
   }
 ```
 
-Styles declared in an orientation hash will override the "generic" styles
-declared directly above it, so the above could also be written as:
+### Orientation Styles
+
+There's more to stylesheets than just translating `UIView` setters.  Teacup can
+also apply orientation-specific styles.  These are applied when the view is
+created (using the current device orientation) and when a rotation occurs.
 
 ```ruby
-style :ready_to_play_button,
-  top: 300,
-  width: 50,
-  height: 20,
-  left: 20
-  landscape: {
-    left: 60  #  overrides left: 20
-  }
+Teacup::Stylesheet.new :main do
+
+  # this label hides when the orientation is landscape (left or right)
+  style :label,
+    landscape: {
+      hidden: true
+    },
+    portrait: {
+      hidden: false
+    }
+
+end
 ```
 
-Handlers
-========
+Combine these styles with [Frame Calculations][calculations] to have you view
+frame recalculated automatically.
+
+### UIView animation additions
+
+We've already seen the Teacup related properties:
+
+- `stylename`, the primary style name
+- `style_classes`, secondary style names
+- `style`, apply styles directly
+
+Each of these has a corresponding method that you can use to facilitate
+animations.
+
+- `animate_to_stylename(stylename)`
+- `animate_to_styles(style_classes)`
+- `animate_to_style(properties)`
+
+### Style Handlers
+
+*This feature is used extensively by [sweettea][] to make a more intuitive
+stylesheet DSL*
 
-Above, we saw that we can assign `view.frame.x` by using the `left` property.
-There *is* no `UIView#left` method, so this must be handled somewhere special...
+Teacup is, by itself, pretty useful, but it really does little more than map
+Hash keys to `UIView` setters.  That's great, because it keeps the system easy
+to understand.  But there are some methods in UIKit that take more than one
+argument, or could benefit from some shorthands.
 
-Not **that** special, it turns out.  This used to be an internal translation,
-but the list of "translations" was getting out of hand, and we realized that we
-could break this out into a new feature.  **Handlers**.  Here is the `handler`
-for the `left` property:
+This is where Teacup's style handlers come in.  They are matched against a
+`UIView` subclass and one or more stylenames, and they are used to apply that
+style when you use it in your stylesheet.
 
 ```ruby
-Teacup.handler UIView, :left { |view, x|
-  f = view.frame
-  f.origin.x = x
-  view.frame = f
-}
+# this handler adds a `:title` handler to the UIButton class (and subclasses).
+Teacup.handler UIButton, :title do |target, title|
+  target.setTitle(title, forState: UIControlStateNormal)
+end
+
+# ...
+subview(UIButton,
+  title: 'This is the title'  # <= this will end up being passed to the handler above
+  )
+
+layout(UINavigationItem,
+  title: 'This is the title'  # <= but this will not!  the handler above is restricted to UIButton subclasses
+  )
 ```
 
-How about setting the title of a `UIButton`?
+[Other built-in handlers][other-handlers] are defined in `z_handlers.rb`.
+Another useful one is the ability to make view the same size as its parent, and
+located at the origin.
 
 ```ruby
-Teacup.handler UIButton, :title { |target, title|
-  target.setTitle(title, forState: UIControlStateNormal)
-}
+style :container,
+  frame: :full  # => [[0, 0], superview.frame.size]
 ```
 
-You can also make aliases for long method names, or to shorten a style you use a
-lot.  You can alias two ways - give multiple names in a `Teacup.handler` method,
-or use `Teacup.alias`.
+### Frame Calculations
+
+*These are super cool, just don't forget your autoresizingMasks*
+
+When positioning views you will often have situations where you want to have a
+view centered, or 8 pixels to the right of center, or full width/height. All of
+these relationships can be described using the `Teacup.calculate` method, which
+is called automatically in any method that modifies the `frame` or `center`.
+
+    frame, origin, size
+    top/y, left/x, right, bottom, width, height
+    center_x/middle_x, center_y/middle_y, center
 
 ```ruby
-# the actual `left` handler offers an alias `x`
-Teacup, handler UIView, :left, :x { |view, x|
-  f = view.frame
-  f.origin.x = x
-  view.frame = f
-}
+Teacup::Stylesheet.new :main do
+
+  style :button,
+    left: 8, top: 8,  # easy enough!
+    width: '100% - 16',  # woah!  (O_o)
+    height: 22
+
+  style :top_half,
+    frame: [[0, 0], ['100%', '50%']]
+  style :bottom_half,
+    frame: [[0, '50%'], ['100%', '50%']]
 
-# but I speak japanese, and I want it to be called "hidari" instead, and I want
-# top to be "ue".
-Teacup.alias UIView, :hidari => :left, :ue => :top
+end
 ```
 
-extends:
-=======
+When this code executes, the string `'100% - 16'` is translated into the formula
+`1.00 * target.superview.frame.size.width - 16`.  If the property is related to
+the height or y-position, it will be calculated based on the height.
 
-You might have a view where all the buttons or text fields have similar colors
-or font.  You can have them extend a common style declaration.
+The frame calculations must be a string of the form `/[0-9]+% [+-] [0-9]+/`.  If
+you need more "math-y-ness" than that, you can construct strings using interpolation.
 
 ```ruby
+margin = 8
+
 style :button,
-  font: UIFont.systemFontOfSize(20)
+  left: margin, top: margin,
+  width: "100% - #{margin * 2}",
+  height: 22
+
+# just for fun, let's see what it would take to add a margin between these two views.
+style :top_half,
+  frame: [[0, 0], ['100%', "50% - #{margin / 2}"]]
+style :bottom_half,
+  frame: [[0, "50% + #{margin / 2}"], ['100%', "50% - #{margin / 2}"]]
+```
 
-style :ok_button, extends: :button,
-  title: "OK"
+One more example: The real power of the frame calculations comes when you
+remember to set springs and struts. You can have a view "pinned" to the bottom
+if you remember to set the `autoresizingMask`.
 
-style :cancel_button, extends: :button,
-  title: "Cancel"
+```ruby
+Teacup::Stylesheet.new :main do
+
+  style :button,
+    # fixed width / height
+    height: 22, width: 200,
+    center_x: '50%',
+    top: '100% - 30',  # includes an 8px margin from the bottom
+    autoresizingMask: (UIViewAutoresizingFlexibleLeftMargin |
+                       UIViewAutoresizingFlexibleRightMargin |
+                       UIViewAutoresizingFlexibleTopMargin)
+    # see the autoresizing extension below for an even better way to write this.
+end
 ```
 
-Precedence is important.  We said that "orientation" overrides "generic", but
-that is only at the local `style` declaration level.  If you declare a property
-in `style` that is set in an orientation hash in an extended style, *your*
-property will win.
+### Auto-Layout
+
+*This is another much bigger topic than it is given space for here*
+
+Teacup includes an Auto-Layout constraint DSL that you can use in your
+stylesheets.  These methods are added to the `Stylesheet` class, so unless you
+are in the context of a stylesheet, you will have to create your constraints in
+longhand (you can still use the `Teacup::Constraint` class to help you!).
+
+I won't sugar-coat it: Auto-Layout is hard.  Much harder than using frames and
+springs and struts.  And honestly, I recommend you try using the
+`Teacup.calculate` features mentioned above, they will take you far.
+
+But at the end of the day, once you really understand the auto-layout system
+that Apple released in iOS 6, you can build your UIs to be responsive to
+different devices, orientations, and sizes. UIs built with auto-layout do not
+usually need to adjust anything during a rotation.  The constraints take *care*
+of it all.  It's impressive.
+
+Here's a quick example that creates this shape.  The edges are bound to the
+superview's frame.
+
+    +-----+----------------+
+    |     |                |
+    |  A  |     B          |
+    |     |          +-----| <\
+    |     |          |  C  |  |_ 50% of B's height, minus 10 pixels
+    +-----+----------+-----+ </
+    ^--+--^          ^--+--^
+       |_fixed (100)    |_fixed (100)
 
 ```ruby
-style :button,
-  portrait: {
-    width: 40
-  },
-  landscape: {
-    width: 45
-  }
+Teacup::Stylesheet.new do
+  style :A,
+    constraints: [
+      # these first three are all fixed, so super easy
+      constrain_left(0),
+      constrain_width(100),
+      constrain_top(0),
+      # here we go, here's a real constraint
+      constrain(:bottom).equals(:superview, :bottom),
+    ]
+
+  style :B,
+    constraints: [
+      # B.left == A.right
+      constrain(:left).equals(:A, :right),
+      # B.height == A.height
+      constrain(:height).equals(:A, :height),
+      constrain(:right).equals(:superview, :right),
+    ]
+
+  style :C,  # <= this looks like a very grumpy style :C
+    constraints: [
+      constrain_width(100),
+      # pin to bottom-right corner
+      constrain(:right).equals(:superview, :right),
+      constrain(:bottom).equals(:superview, :bottom),
+      # 50% B.height - 10
+      constrain(:height).equals(:B, :height).times(0.5).minus(10),
+    ]
+
+end
+```
+
+Writing views this way will either make your brain hurt, or make the math-nerd
+in you chuckle with glee.  In this example you could go completely with just
+frame calculation formulas and springs and struts.  Your frame code would still
+be cluttered, just cluttered in a different way.
+
+### Motion-Layout[motion-layout]
 
-style :ok_button, extends: :button,
-  title: "OK",
-  width: 40  # width will always be 40, even in landscape
+If you are using [Nick Quaranto][qrush]'s [motion-layout][] gem, you can use it from within
+any class that includes `Teacup::Layout`.  Then benefit is that the Teacup
+stylenames assigned to your views will be used in the dictionary that the
+ASCII-based system relies on.
+
+```ruby
+layout do
+  subview(UIView, :view_a)
+  subview(UIView, :view_b)
+  subview(UIView, :view_c)
+
+  # if you need to apply these to a different view, or if you want to assign
+  # different names to use in the ASCII strings
+  # auto(layout_view=self.view, layout_subviews={}, &layout_block)
+
+  auto do
+    metrics 'margin' => 20
+    vertical "|-[view_a]-margin-[view_b]-margin-[view_c]-|"
+    horizontal "|-margin-[view_a]-margin-|"
+    horizontal "|-margin-[view_b]-margin-|"
+    horizontal "|-margin-[view_c]-margin-|"
+  end
+end
 
-style :cancel_button, extends: :button,
-  title: "Cancel"
-  # width will be 40 or 45, depending on orientation
 ```
 
-import
-======
+### Stylesheet extensions
 
-Each `UIView` or `UIViewController` can have only one stylesheet attached to it.
-If you want to break up a stylesheet into multiple sheets, you will use `import`
-to do it.
+Auto-Layout is just one Stylesheet extension, there are a few others.  And if
+you want to write your own, just open up the `Teacup::Stylesheet` class and
+start adding methods.
+
+#### Autoresizing Masks
+
+If you've used the SugarCube `uiautoresizingmask` methods, you'll recognize
+these.  They are handy, and hopefully intuitive, shorthands for common springs
+and struts.
+
+In previous versions of Teacup these were available without needing the
+`autoresize` prefix.  The old methods are still available, but deprecated.
 
 ```ruby
-Teacup::Stylesheet.new :base do
-  style :button,
-    font: UIFont.systemFontOfSize(20)
+# keeps the width and height in proportion to the parent view
+style :container,
+  autoresizingMask: autoresize.flexible_width | autoresize.flexible_height
+
+# the same, but using block syntax
+style :container,
+  autoresizingMask: autoresize { flexible_width | flexible_height }
+
+# the same again, using a shorthand
+style :container,
+  autoresizingMask: autoresize.fill
+```
+
+The autoresize methods are grouped into four categories: `flexible, fill, fixed,
+and float`. The flexible methods correspond 1::1 with the `UIViewAutoresizing*`
+constants.
+
+The `fill` methods (`fill,fill_top,fill_bottom,fill_left,fill_right`) will
+stretch the width, or height, or both.  The location specifies where the view is
+pinned, so `fill_top` will stretch the width and bottom margin, but keep it the
+same distance from the top (not necessarily *at* the top, but a fixed distance).
+`fill_right` will pin it to the right side, stretch the height, and have a
+flexible left margin.
+
+The `fixed` methods pin the view to one of nine locations:
+
+    top_left    |  top_middle   |    top_right
+    ------------+---------------+-------------
+    middle_left |     middle    | middle_right
+    ------------+---------------+-------------
+    bottom_left | bottom_middle | bottom_right
+
+The `float` methods fill in the last gap, when you don't want your view pinned
+to any corner, and you don't want it to change size.
+
+    float_horizontal | float_vertical == fixed_middle
+
+#### Device detection
+
+Because the stylesheets are defined in a block, you can perform tests for device
+and screen size before setting styles.  For instance, on an ipad you might want
+to have a larger margin than on the iphone.
+
+The `Stylesheet` device methods will help you create these conditions:
+
+```ruby
+Teacup::Stylesheet.new do
+  if device_is? iPhone
+    margin = 8
+  elsif device_is? iPad
+    margin = 20
+  end
+
+  style :container,
+    frame: [[margin, margin], ["100% - #{margin * 2}", "100% * #{margin * 2}"]]
 end
+```
 
-Teacup::Stylesheet.new :main do
-  import :base
+Multiple calls to `style` will *add* those styles, not replace.  So this code
+works just fine:
 
-  style :ok_button, extends: :button,
-    top: 10
+```ruby
+Teacup::Stylesheet.new do
+  style :logo,
+    origin: [0, 0]
+
+  if device_is? iPhone
+    style :logo, image: UIImage.imageNamed "small logo"
+  elsif device_is? iPad
+    style :logo, image: UIImage.imageNamed "big logo"
+  end
 end
+```
+
+#### Rotation helpers
 
-Teacup::Stylesheet.new :register do
-  import :base
+Because you can animate changes to the stylename or style_classes, you can make
+it pretty easy to apply rotation effects to a `UIView` or `CALayer`.  The
+`style_classes` property is especially useful for this purpose.
+
+```ruby
+style :container,
+  frame: :full
+
+# UIView transforms
+
+style :rotated,
+  transform: transform_view.rotate(pi / 2)  # pi and transform_view are methods on Stylesheet
+
+style :not_rotated,
+  transform: transform_view.rotate(0)
+
+# CALayer transforms
+
+style :rotated,
+  layer: { transform: transform_layer.rotate(pi / 2) }
+
+style :not_rotated,
+  layer: { transform: transform_layer.rotate(0) }
+```
+
+These work even better when used with the [geomotion][] methods that extend
+`CGAffineTransform` and `CATransform3D`.
+
+```ruby
+style :goofy,
+  transform: CGAffineTransform.rotate(pi / 2).translate(100, 0).scale(2)
+style :regular,
+  transform: CGAffineTransform.identity
+
+# CALayer uses CATransform3D objects
+style :regular,
+  layer: {
+    transform: CATransform3D.rotate(pi / 2)
+  }
+```
+
+### Showdown
+
+As a recap, here is a translation of traditional Cocoa code done using Teacup.
+
+No cool tricks here, just some plain ol' Cocoa.
+
+```ruby
+#
+# Traditional Cocoa
+#
+class SomeController < UIViewController
+
+  def viewDidLoad
+    @field = UITextField.new
+    @field.frame = [[10, 10], [200, 50]]
+    @field.textColor = UIColor.redColor
+    view.addSubview(@field)
+
+    @search = UITextField.new
+    @search.frame = [[10, 70], [200, 50]]
+    @search.placeholder = 'Find something...'
+    @search.textColor = UIColor.redColor
+    view.addSubview(@search)
+  end
+
+  # perform the frame changes depending on orientation
+  def willAnimateRotationToInterfaceOrientation(orientation, duration:duration)
+    case orientation
+    when UIInterfaceOrientationLandscapeLeft, UIInterfaceOrientationLandscapeRight
+      @field.frame = [[10, 10], [360, 50]]
+      @search.frame = [[10, 70], [360, 50]]
+    else
+      @field.frame = [[10, 10], [200, 50]]
+      @search.frame = [[10, 70], [200, 50]]
+    end
+  end
+
+end
+
+#
+# Teacup
+#
+
+class SomeController < UIViewController
+
+  stylesheet :some_view
+
+  layout :root do
+    subview(UITextField, :field)
+    @search = subview(UITextField, :search)
+  end
+
+end
+
+Teacup::Stylesheet.new(:some_view) do
+
+  style :root,       # enable landscape rotation (otherwise only portrait is enabled)
+    landscape: true  # this must be on the root-view, to indicate that this view is
+                     # capable of handling rotations
+
+  style :field,
+    left:   10,
+    top:    10,
+    width:  200,
+    height: 50,
+    landscape: {
+      width: 360  # make it wide in landscape view
+    }
+
+  style :search, extends: :field,
+    left: 10,
+    top: 70,
+    placeholder: 'Find something...'
+
+  style UITextField,                # Defining styles based on view class instead
+    textColor: UIColor.redColor     # of style name.
 
-  style :submit_button, extends: :button,
-    top: 50
 end
 ```
 
-UIView classes
-==============
+The Nitty Gritty
+----------------
+
+#### Regarding Style Precedence
+
+You need to be careful when extending styles and using orientation styles
+because the precedence rules take some getting used to.  The goal is that you
+can have all your style code in the stylesheets.  But you also need to be able
+to animate your views, and rotating the device should not go reseting
+everything.
+
+So here's what happens.
+
+When your controller is loaded, `viewDidLoad` is called, and that's where Teacup
+creates the view hierarchy and applies the styles.  It is at the *end* of the
+method that the styles are applied - not until all the views have been added.
+The current device orientation will be used so that orientation-specific styles
+will be applied.
+
+Now Teacup goes quiet for a while.  Your app chugs along... until the user
+rotates the device.
+
+If you have orientation-specific styles, they will get applied. But the
+*original* styles (the "generic" styles) **will not**.
+
+However, there's a way around *that, too.*  If you call `restyle!` on a
+`UIView`, that will reapply all the original stylesheet styles - orientation
+*and* generic styles.
+
+With me so far?  Orientation styles are reapplied whenever the device is
+rotated. But generic styles are only applied in `viewDidLoad` and when
+`restyle!` is called explicitly.
+
+How does the `:extends` property affect things?
+
+If your stylesheet defines orientation-specific styles and "generic" styles, the
+orientation-specific styles win.  But if you *extend* a style that has
+orientation-specific styles, your local generic styles will win.
+
+The more "local" styles always win - and that applies to styles that you add
+using the `subview/layout` methods, too. The only time it doesn't really apply
+is if you apply styles using `UIView#style` or `UIView#apply_stylename`.  Those
+are one-shot (they can get overwritten when `restyle!` is called).
 
-You can style entire classes of `UIView`s!  These get merged in last (lowest
-precedence), but they are a great way to get site-wide styles.  Put these in a
-base stylesheet, and import that stylesheet everywhere.  The Apple
-`UIAppearance` protocol/classes do this same thing, but in much more code ;-)
+There are also times when you either want (or must) override (or add to) the
+stylesheet styles.  For instance, if you want to assign the `delegate` or
+`dataSource` properties, this cannot be done from a `Stylesheet`.  But that's
+okay, because we have a chance to add these styles in the `subview` and `layout`
+methods.
 
 ```ruby
-Teacup::Stylesheet.new :base do
-  style UIButton,
-    font: UIFont.systemFontOfSize(20)
+layout do
+  subview(UITableView, delegate: self)
 end
+```
 
-Teacup::Stylesheet.new :main do
-  style :ok_button,  # no need to use extends
-    top: 10
+Styles applied here are one-shot.  It is the exact same as assigning the
+`stylename` and `style_classes` and then calling `style`.  Because the
+stylesheet is not necessarily applied immediately, these styles could be
+overwritten before they take effect.
+
+```ruby
+layout do
+  table_view = subview(UITableView, :tableview, delegate: self,
+    font: UIFont.boldSystemFontOfSize(10)  # the stylesheet could override this during rotation
+    )
 end
 
-Teacup::Stylesheet.new :register do
-  style :submit_button,  # no need to use extends
-    top: 50
+def layoutDidLoad
+  table_view.apply_stylename(:tableview_init)  # this will only get applied once
 end
 ```
 
-Precedence, and Style
-==========
+The idea here is that the closer the style setting is to where the view is
+instantiated, the higher the precedence.
 
-1. Within a `style` declaration, orientation-specific properties override generic properties
-2. Imported properties will be merged in, but no values from (1) will be overridden
-3. Extended styles will be merged in, but no values from (1) or (2) will be overridden
-4. Styles applied to an ancestor will be merged in, but no values from (1) or (2) or (3) will be overridden
+More examples!
 
-These rules are maintained in the `Style` class.  It starts by creating a Hash
-based on the `style` declaration, then merges the orientation styles, if
-applicable (orientation styles override).  Next it merges imports, then
-extends, and finally the class ancestors.  At each "merge" except orientation
-merges, it is a recursive-soft-merge, meaning that Hashes will be merged, but
-existing keys will be left alone.
+```ruby
+class MyController < UIViewController
+  stylyesheet :my_sheet
+  layout do
+    subview(UILabel, :label, text: 'overrides')
+  end
+end
+Teacup::Stylesheet.new :my_sheet do
+  style :generic_label,
+    text: 'portrait',
+    # these get applied initially, but after being rotated they will not get
+    # applied again
+    font: UIFont.boldSystemFontOfSize(10),
+    textColor: UIColor.grayColor,
+    landscape: {
+      font: UIFont.boldSystemFontOfSize(12),
+      textColor: UIColor.whiteColor,
+    }  # this style should add a `portrait` setting that restores the font and color
+
+  style :label, extends: :generic_label,
+    font: UIFont.systemFontOfSize(10),  # this will override all the font settings
+end
+```
 
-Unless you are going to be hacking on teacup, you do not need to understand the
-nitty-gritty - just remember the precedence rules.
+Advanced Teacup Tricks
+----------------------
 
-Development
------------
+There are times when you might wish teacup "just worked", but please remember:
+Teacup is not a "blessed" framework built by Apple engineers. We have access to
+the same APIs that you do. That said, here are some use-cases where you can most
+definitely *use* teacup, but you'll need to do a little more leg work.
 
-*Current version*: v0.2.0 (or see `lib/teacup/version.rb`)
+### Trust your parent view - by using springs and struts
 
-*Last milestone*: Release layout and stylesheet DSL to the world.
+*...not autolayout*
 
-*Next milestone*: Provide default styles, that mimic Interface Builder's object library
+It's been mentioned a few times in this document that Teacup will create & style
+views in the `viewDidLoad` method.  That means that the `superview` property of
+the controller's view will, necessarily, *not* be set yet.  `viewDidLoad` is
+called after the view is instantiated (in `loadView`), and it hasn't been added
+as a subview yet.
 
-**Changelog v0.2.0:**
+Auto-Layout is based on the relationship between two views - often a container
+and child view.  It's an amazing system, but if that parent view *isn't
+available*, well, you're not gonna have much success.
 
-- Stylesheets are no longer constants. Instead, they can be fetched by name: `Teacup::Stylesheet[:iphone]`
-- Stylesheets can be assigned by calling the `stylesheet :stylesheet_name` inside a view controller.
-- Ability to style based on view class.
-- Support for orientation-based styles.
+In the case of a UIViewController your "container" is the `self.view` property,
+which by default has sensible springs setup so that it stretches to fill the
+superview. It's not until you go messing with the `self.view` property, or are
+not in the context of a `UIViewController` that things get hairy.
 
+If this is the case, you should get some pretty obvious warning messages,
+something along the lines of `Could not find :superview`.
 
-teacup, being a community project, moves in "spurts" of decision making and
-coding.  We will announce when we are in "proposal mode".  That's a good time to
-jump into the project and offer suggestions for its future.
+### UITableViewCell
 
-And we're usually hanging out over at the `#teacuprb` channel on `irc.freenode.org`.
+If you are using your controller as your tableview dataSource this is not a big
+deal, the `subview` and `layout` methods continue to work as you expect them to.
+
+I don't know about you, but I often write helper classes for tableviews that
+appear on many screens in an app.  You should not shy away from adding teacup's
+`Layout` module to these helper classes.
+
+```ruby
+class TableHelper
+  include Teacup::Layout
+
+  stylesheet :table_helper
+
+  def tableView(table_view, cellForRowAtIndexPath:index_path)
+    cell_identifier = 'MyController - cell'
+    cell = table_view.dequeueReusableCellWithIdentifier(cell_identifier)
+
+    unless cell
+      cell = UITableViewCell.alloc.initWithStyle(UITableViewCellStyleDefault
+                          reuseIdentifier: cell_identifier)
+
+      layout(cell.contentView) do
+        subview(UIImageView, :image)
+      end
+      # cell.contentView and all child classes will "inherit" the :table_helper stylesheet
+    end
+
+    return cell
+  end
+
+end
+```
+
+### [Sweettea][]
+
+*SugarCube + Teacup = Sweettea*
+
+SugarCube was born of a desire to make Teacup stylesheets more readable, less
+cluttered with Apple's verbose method names and constants.  Sweettea takes this
+a step further, by implementing a wealth of Teacup handlers that translate
+Symbols to constants and provide useful shorthands.
+
+```ruby
+style :button,
+  normal: { image: 'button-white' },
+  highlighted: { image: 'button-white-pressed' },
+  title: 'Submit',
+  shadow: {
+    opacity: 0.5,
+    radius: 3,
+    offset: [3, 3],
+    color: :black,
+  },
+  font: 'Comic Sans'
+
+style :label,
+  font: :bold,
+  alignment: :center,
+  color: :slateblue
+```
+
+Sweettea also offers some convenient styles that you can extend in your base
+class.  You might want to either specify the Sweettea version you are using in
+your Gemfile, or copy the stylesheet so that changes to Sweettea don't affect
+your project.  Once that projet is at 1.0 you can rely on the styles not
+changing.
+
+```ruby
+# buttons! :tan_button, :black_button, :green_button, :orange_button,
+# :blue_button, :white_button, :gray_button
+style :submit_button, extends: :white_button
+
+# label sets more sensible defaults than a "raw" UILabel (like clear background)
+style :header, extends: :label
+
+# inputs!  these are not styled, they just setup keyboard and autocomplete
+# settings
+# :name_input, :ascii_input, :email_input, :url_input, :number_input,
+# :phone_input, :secure_input
+style :login_input, extends: :email_input
+style :password_input, extends: :secure_input
+```
+
+Misc notes
+----------
+
+Multiple calls to `style` with the same stylename combines styles, it doesn't
+replace the styles.
+
+------
+
+Styles are not necessarily applied immediately.  They are applied at the end of
+the outermost `layout/subview` method, including the `UIViewController##layout`
+block.  If you call `stylename=` or `stylesheet=` *outside* a `layout/subview`
+block, your view will be restyled immediately.
+
+------
+
+Restyling a view calls `restyle!` on all child views, all the way down the tree.
+Much care has been taken to call this method sparingly within Teacup.
+
+------
+
+Any styles that you apply in a `layout/subview` method are *not* retained, they
+are applied immediately, and so the stylesheet can (and usually do) override
+those styles if there is a conflict.  Only styles stored in a stylesheet are
+reapplied (during rotation or in `restyle!`).
+
+------
+
+Stylesheets should not be modified once they are created - they cache styles by
+name (per orientation).
+
+------
+
+You can add and remove a `style_class` using `add_style_class` and
+`remove_style_class`, which will call `restyle!` for you if `style_classes`
+array was changed.
+
+------
+
+If you need to do frame calculations outside of the stylesheet code, you should
+do so in the `layoutDidLoad` method.  This is not necessary, though!  It is
+usually cleaner to do the frame calculations in stylesheets, either using
+[geomotion][], frame calculations, or auto-layout.
+
+------
+
+Within a `subview/layout` block views are added to the last object in
+`Layout#superview_chain`.  Views are pushed and popped from this array in the
+`Layout#layout` method, starting with the `top_level_view`.  If you include
+`Teacup::Layout` on your own class, you do not *have* to implement
+`top_level_view` unless you want to use the `subview` method to add classes to a
+"default" target.
+
+------
+
+When `UIView` goes looking for its `stylesheet` it does so by going up the
+responder chain.  That means that if you define the stylesheet on a parent view
+or controller, all the child views will use that same stylesheet by default.  It
+also means you can assign a stylesheet to a child view without worrying what the
+parent view's stylesheet is.
+
+Caveat!  If you implement a class that includes `Teacup::Layout`, you can assign
+it a `stylesheet`. *That* stylesheet will be used by views created using
+`layout` or `subview` even though your class is probably not part of the
+responder chain.  Saying that `UIView` inherits its `stylesheet` from the
+responder chain is not accurate; it actually uses `teacup_responder`, which
+defaults to `nextResponder`, but it is assigned to whatever object calls the
+`layout` method on the view.
+
+------
+
+If you use `Teacup::Appearance` but it is not styling the first screen of your
+app (but, strangely, *does* style all other screens), try calling
+`Teacup::Appearance.apply` before creating you create the `rootViewController`
+(in your `AppDelegate`)..
+
+------
 
 The Dummy
 ---------
@@ -500,30 +1355,28 @@ If you get an error that looks like this:
     precompiled. Make sure you properly link with the framework or library that
     defines this message.
 
-You need to add your method to dummy.rb.  This is a compiler issue, nothing we
-can do about it except build up a huge dummy.rb file that has just about every
-method that you would want to style.
+You probably need to add your method to [dummy.rb][].  This is a compiler issue,
+nothing we can do about it except build up a huge dummy.rb file that has just
+about every method that you would want to style.
 
-Example
-=======
+# Teacup is a Community Project!
 
-The error above was from trying to style the
-`UIActivityIndicatorView#hidesWhenStopped` property.  Make a new `Dummy` class,
-subclass the class *where the method is defined* (not a subclass, please) and
-add that method to a `dummy` method.  You should assign it `nil` so that the
-method signature looks right.  And you should mark it private, too.
+Teacup was born out of the #rubymotion irc chatroom in the early days of
+RubyMotion.  Its design, direction, and priorities are all up for discussion!
 
-```ruby
-class DummyActivityIndicatorView < UIActivityIndicatorView
-private
-  def dummy
-    setHidesWhenStopped(nil)
-  end
-end
-```
+I'm [Colin T.A. Gray][colinta], the maintainer of the Teacup project.  I hope this
+tool helps you build great apps!
 
-Bugs
-----
+[advanced]: https://github.com/rubymotion/teacup/#advanced-teacup-tricks
+[calculations]: https://github.com/rubymotion/teacup/#frame-calculations
+[dummy.rb]: https://github.com/rubymotion/teacup/tree/master/lib/dummy.rb
+[other-handlers]: https://github.com/rubymotion/teacup/tree/master/lib/teacup/z_core_extensions/z_handlers.rb
 
-Please report any bugs you find with our source at the
-[Issues](https://github.com/rubymotion/teacup/issues) page.
+[Pixate]: http://www.pixate.com
+[NUI]: https://github.com/tombenner/nui
+[geomotion]: https://github.com/clayallsopp/geomotion
+[UIAppearance]: http://developer.apple.com/library/ios/#documentation/uikit/reference/UIAppearance_Protocol/Reference/Reference.html#//apple_ref/occ/intf/UIAppearance
+[motion-layout]: https://github.com/qrush/motion-layout
+[sweettea]: https://github.com/colinta/sweettea
+[qrush]: https://github.com/qrush
+[colinta]: https://github.com/colinta