Teacup
A community-driven DSL for creating user interfaces on iOS and OS X.
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.
A note about Teacup and MotionKit
Read a letter from Colin T.A. Gray regarding the future of Teacup and introducing MotionKit, its successor.
Check out some sample apps!
- iOS
- OS X
- Tweets - ported from RubyMotionSamples
- simple
Quick Install
“sh
gem install teacup
“nd in your Rakefile
“by require ‘teacup’
“
10 second primer, iOS
-
Create a
UIViewController
subclass:“by class MyController < UIViewController
“
-
Assign a stylesheet name:
“by class MyController < UIViewController stylesheet :main_screen
“
-
Create a layout:
“by class MyController < UIViewController stylesheet :main_screen
def teacup_layout subview(UIButton, :hi_button) end end
“
-
Create the stylesheet (in
app/styles/
or somewhere near the controller)“by Teacup::Stylesheet.new :main_screen do style :hi_button, origin: [10, 10], title: ‘Hi!’ end
“
10 second primer, OS X
Pretty much the same! Note that on OS X, view coordinates are based on having the origin in the bottom-left corner, not the upper-left like it is on every other GUI system ever. :-|
You should use the TeacupWindowController
parent class instead of NSWindowController
-
Create a
TeacupWindowController
subclass.“by class MyController < TeacupWindowController
“
-
Assign a stylesheet name:
“by class MyController < TeacupWindowController stylesheet :main_window
“
-
Create a layout:
“by class MyController < TeacupWindowController stylesheet :main_window
def teacup_layout subview(NSButton, :hi_button) end end
“
-
Create the stylesheet (in
app/styles/
or somewhere near the controller)“by Teacup::Stylesheet.new :main_window do style :hi_button, origin: [10, 10], title: ‘Hi!’ end
“
Teacup
Teacup’s goal is to facilitate the creation and styling of your view hierarchy. Say “Goodbye!” to Xcode & XIB files!
Teacup is composed of two systems:
-
Layouts A DSL to create Views 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!
Changes in 3.0
There is one significant change in version 3.0. In every version of Teacup prior (from 0.2.0 to 2.3.0) the controller layout was usually created by calling a class method called layout
. It was discovered, embarrassingly late, that this system is causing memory leaks. To fix it we had to remove this feature altogether. So if you are looking at old Teacup examples, you will see this block syntax that is no longer offered. It is easy to update to 3.0, though:
“by
<= 2.3.0
class MyController < UIViewController layout(:root_stylename) do # <= this block is what caused the memory leak! # teacup code goes here end end
3.0
class MyController < UIViewController def teacup_layout # in 3.0 we just changed it to be a method # introduced in 3.0, this is how you assign a stylename to the root view root(:root_stylename, { background: UIColor.blueColor }) # teacup code goes here - no other code changes necessary end # actually, this method still works as long as you don’t pass a block. It’s # the same as calling root(stylename, {})
layout(:root_stylename, {}) end
“
Table of Contents
- Layouts — define your views
- Stylesheets — style your views
- UITableViews - This is important if you are using styles and constraints in a
UITableViewDelegate
. - More Teacup features
- Showdown — Cocoa vs Teacup
- The Nitty Gritty — some implementation details and gotchas
- Advanced Teacup Tricks
- Misc notes
- The Dummy — fixes “uncompiled selector” errors
Layouts
The Teacup::Layout
module is mixed into UIViewController
and UIView
on iOS, and NSWindowController
, NSViewController
, and NSView
on OS X. These classes can take advantage of the view-hierarchy DSL.
You saw an example in the primer, using the UIViewController
/NSWindowController
class method layout
and the teacup_layout
method. You could just as easily use Teacup’s DSL to create your views from a loadView
method, for instance you might want to use a custom view subclass as your root view. An example might look like this:
“by
controller example
class MyController < UIViewController
def loadView # we will create the controller’s view, assigning it the stylename :root self.view = layout(FancyView, :root) do # these subviews will be added to self.view
subview(UIToolbar, :toolbar) subview(UIButton, :hi_button) end end
end
“
You can use very similar code in your view subclasses.
“by
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
“
The layout
and subview
methods are the work horses of the Teacup view DSL.
layout(view|ViewClass, stylename, style_classes, additional_styles, &block)
view|ViewClass
- You can layout an existing class or you can have Teacup create it for you (it just callsnew
on the class, nothing special). This argument is required.stylename
(Symbol
) - This is the name of a style in your stylesheet. It is optionalstyle_classes
([Symbol,...]
) - Other stylenames, they have lower priority than thestylename
.additional_styles
(Hash
) - You can pass other styles in here as well, either to override or augment the settings from theStylesheet
. It is common to use this feature to assign thedelegate
ordataSource
.&block
- See discussion below- Returns the
view
that was created or passed tolayout
. - only the
view
arg is required. You can pass any combination of stylename, style_classes, and additional_styles (some, none, or all).
subview(view|UIViewClass, stylename, style_classes, additional_styles, &block)
- Identical to
layout
, but adds the view to the current target
- Identical to
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.
“by subview(UIView, :container) do # create a UIView instance and give it the stylename :container subview(UIView, :inputs) do # create another container # these views will be added to the :inputs view @email_input = subview(UITextField, :email_input) @password_input = subview(UITextField, :password_input) end # this view will be added to :container subview(UIButton.buttonWithType(UIButtonTypeRoundedRect), :submit_button) end
“
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?).
“by
the methods you add here will be available in UIView/NSView,
UIViewController/NSViewController/NSWindowController, and any of your own
classes that include Teacup::Layout
module Teacup::Layout
# creates a button and assigns a default stylename def button(args, &block) # apply a default stylename args = [:button] if args.empty?
# instantiate a button and give it a style class
subview(UIButton.(UIButtonTypeCustom), *args, &block)
end
# 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
= UIButton.(UIButtonTypeCustom)
.addSubview(image_view)
.addSubview(label)
# code could go here to position the icon and label, or at could be handled
# by the stylesheet
subview()
end
end
“
example use of the helper methods
“by class MyController < UIViewController
def teacup_layout @button1 = button() @button2 = button(:blue_button) @button3 = button_with_icon(UIImage.imageNamed(‘email_icon’), ‘Email’) end
end
“
The Controller#teacup_layout
method is going to be the first or second thing you add to a controller when you are building an app with Teacup. Inside you will add subviews using subview
or you can create a view using the layout
method (subview
delegates most of its work to layout
)
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 can do it in this method.
Stylesheets
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.
“by
classic Cocoa/UIKit
def viewDidLoad self.view.backgroundColor = UIColor.grayColor # ^………….^ end
in Teacup
def viewDidLoad self.stylesheet = :main self.view.stylename = :root end
Teacup::Stylesheet.new :main do style :root, backgroundColor: UIColor.grayColor
^………….^
end
“
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.
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.
“by Teacup::Stylesheet.new :main_menu do style :ready_to_play_button, backgroundColor: UIColor.blackColor, frame: [[20, 300], [50, 20]] 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.
Limelight syntax
If you want to use a shorter syntax, you can use the “Limelight” inspired syntax:
“by Teacup::Stylesheet.new :main_menu do ready_to_play_button do backgroundColor UIColor.blackColor frame [[20, 300], [50, 20]] end end
“
This creates the same style hashes as style :ready_to_play_button
, so you have access to all the features that are available in the “traditional” syntax.
Using and re-using styles in a Stylesheet
- 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.
“by class MainController < UIViewController
stylesheet :main # <= assigns the stylesheet named :main to this controller
def teacup_layout 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
“
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)
.
But we didn’t assign any text!
We can tackle this a couple ways. You can apply “last-minute” styles in the layout
and subview
methods:
“by def teacup_layout subview(UILabel, :h1, # the subview
and layout
methods can apply styles text: “Omg, it’s full of stars” ) end
“
In this case though we just have static text, so you can assign the text using the stylesheet:
“by 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
“
Extending Styles
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:
“by def teacup_layout 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 variables to store settings you want to re-use.
“by Teacup::Stylesheet.new :main do h1_font = UIFont.systemFontOfSize(20)
style :h1, font: h1_font style :main_header, extends: :h1, text: “Omg, it’s full of stars” end
“
And you’re not limited to one class that you can extend, it accepts an array
“by Teacup::Stylesheet.new :main do h1_font = UIFont.systemFontOfSize(20)
style :h1, font: h1_font
style :label, textColor: UIColor.black
style :main_header, extends: [:h1, :label], text: “Omg, it’s full of stars” end
“
Style via View Class
If you need to apply styles to all instances of a UIView
/NSView
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!).
“by Teacup::Stylesheet.new :app do
style UILabel, font: UIFont.systemFontOfSize(20)
style UITableView, backgroundColor: UIColor.blackColor
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.
“by 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
end
Teacup::Stylesheet.new :main do import :app
style :subheader, extends: :header # <= the :header style is imported from the :app stylesheet
style :button, titleColor: @header_color # <= @header_color is imported, too end
“
Style via UIAppearance
iOS only
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.
But, it does come in handy sometimes… so here it is!
“by Teacup::Appearance.new do
# UINavigationBar.appearance.setBarTintColor(UIColor.blackColor) style UINavigationBar, barTintColor: UIColor.blackColor, titleTextAttributes: { UITextAttributeFont => UIFont.fontWithName(‘Trebuchet MS’, size:24), UITextAttributeTextShadowColor => UIColor.colorWithWhite(0.0, alpha:0.4), UITextAttributeTextColor => UIColor.whiteColor }
# UINavigationBar.appearanceWhenContainedIn(UINavigationBar, nil).setColor(UIColor.blackColor) style UIBarButtonItem, when_contained_in: UINavigationBar, tintColor: UIColor.blackColor
# UINavigationBar.appearanceWhenContainedIn(UIToolbar, UIPopoverController, nil).setColor(UIColor.blackColor) style UIBarButtonItem, when_contained_in: [UIToolbar, UIPopoverController], tintColor: UIColor.blackColor
end
“
In your AppDelegate you need to call Teacup::Appearance.apply
. It will get called automatically using the UIApplicationDidFinishLaunchingNotification
, but that notification is triggered after the method AppDelegate#didFinishLaunching(withOptions:)
is called.
app_delegate.rb
“by class AppDelegate def didFinishLaunching(application, withOptions:options) Teacup::Appearance.apply
@window = UIWindow.alloc.initWithFrame(UIScreen.mainScreen.bounds)
ctlr = MainController.new
@window.rootViewController = UINavigationController.alloc.initWithRootController(ctlr)
@window.makeKeyAndVisible
true
end
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.
You should also be sure to read the Misc notes section at the bottom. These aren’t very well organized, but the information is important. You can learn about features any time, but learning about the “gotcha”s sooner rather than later could save you a lot of time!
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
and NSView
have 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.
“by
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’)
“
UITableViews
Teacup is designed to be used in coordination with the controller life cycle, but there are other life cycles that need to be considered as well. UITableViews maintain a “queue” of cells that can be reused, and they need to be restyled when the cell is created and re-used.
The solution is to apply the styles and layout constraints inside the tableView:willDisplayCell:forRowAtIndexPath:
delegate method. In your delegate, if you include the Teacup::TableViewDelegate
module, you’ll get this behavior for free, and if you override this method, you can call super
to have the Teacup method run.
“by class TableViewController < UITableViewController include Teacup::TableViewDelegate
stylesheet :table
def tableView(table_view, cellForRowAtIndexPath:index_path) cell = table_view.dequeueReusableCellWithIdentifier(‘cell id’)
layout(cell.contentView, :root) do
cell.title_label = subview(UILabel, :title_label, :text => "title #{index_path.row}")
cell.details_label = subview(UILabel, :details_label, :text => "details #{index_path.row}")
cell.other_label = subview(UILabel, :other_label, :text => "other #{index_path.row}")
end
return cell
end
# This method is implemented by the Teacup::TableViewDelegate. If you need # to implement it, be sure to call super. # def tableView(tableView, willDisplayCell:cell, forRowAtIndexPath:indexPath) # super # end end
“
Constraints and styles get applied before the view appears, even if the cell is reused later.
More Teacup features
There are a few (OK, a bunch) more features that Teacup provides that deserve discussion:
- Styling View Properties
- Orientation Styles
- View Class Additions
- Style Handlers
- Frame Calculations
- Auto-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!
“by
UITableViewCells have a contentView, a backgroundView, imageView, textLabel,
detailTextLabel, and a layer! whew!
style :tablecell, layer: { # style the layer! shadowRadius: 3 }, backgroundView: { # style the background! backgroundColor: UIColor.blackColor }, imageView: { # style the imageView! contentMode: UIViewContentModeScaleAspectFill }
“
Orientation Styles
iOS only
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.
“by 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
“
Combine these styles with Frame Calculations to have you view frame recalculated automatically.
Animation additions
We’ve already seen the Teacup related properties:
stylename
, the primary style namestyle_classes
, secondary style namesstyle
, 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)
On OS X you have to use the view.animator
property to perform animations. This is supported, but it’s kind of “hacky”.
Style Handlers
This feature is used extensively by sweettea to make a more intuitive stylesheet DSL
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.
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.
“by
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 )
“
Other built-in 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.
“by style :container, frame: :full # => [[0, 0], superview.frame.size]
“
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
“by 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%]]
end
“
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.
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.
“by margin = 8
style :button, left: margin, top: margin, width: “100% - #* 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% - #/ 2]] style :bottom_half, frame: [[0, “50% + #/ 2”], [100%, 50% - #/ 2]]
“
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
.
“by 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
“
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 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)
“by 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, heres 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.
If you need to reset the list of constraints managed by Teacup, you can call reset_constraints
before you add the new styles to a UIView. This can be useful when you need to define a new set of layout constraints for a dynamic set of views.
This works on OS X and iOS, and you don’t have to go changing the idea of “top” and “bottom” even though OS X uses reversed frames.
Motion-Layout
If you are using Nick Quaranto‘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.
“by def teacup_layout 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
“
Stylesheet extensions
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.
“by
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
e.g. fixed_top_left, fixed_middle, fixed_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.
# incidentally:
float_horizontal | float_vertical == fixed_middle
Device detection
iOS only
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:
“by Teacup::Stylesheet.new do if device_is? iPhone margin = 8 elsif device_is? iPad margin = 20 end
style :container, frame: [[margin, margin], [100% - #* 2, 100% * #* 2]] end
“
Multiple calls to style
will add those styles, not replace. So this code works just fine:
“by 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
iOS only
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.
“by 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
.
“by 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.
“by #
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
def teacup_layout root(:root) 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.
end
“
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).
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.
“by def teacup_layout subview(UITableView, delegate: self) end
“
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.
“by def teacup_layout table_view = subview(UITableView, :tableview, delegate: self, font: UIFont.boldSystemFontOfSize(10) # the stylesheet could override this during rotation ) end
def layoutDidLoad table_view.apply_stylename(:tableview_init) # this will only get applied once end
“
The idea here is that the closer the style setting is to where the view is instantiated, the higher the precedence.
More examples!
“by class MyController < UIViewController stylesheet :my_sheet def teacup_layout 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
“
Advanced Teacup Tricks
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.
Trust your parent view - by using springs and struts
…not autolayout
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.
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.
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
.
Including Teacup::Layout
on arbitrary classes
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.
If you are using your controller as your table view dataSource, the subview
and layout
methods continue to work as you expect them to. This is for the case when you are using a helper class as the dataSource and/or delegate.
“by class TableHelper include Teacup::TableViewDelegate 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
“
Calculating values using lambda
All styles can accept a proc, and before the style is applied the proc is called and you can calculate a value at runtime. There are times when this is simply convenient, and there are times when it is necessary.
Convenient: when a value is based on some other view’s value
“by
calculate ‘backgroundColor’ based on another view
style :some_view, backgroundColor: ->(view) { view.backgroundColor = view.superview.someOtherColor }
“
Required: when you need to instantiate an object, like a view
“by
calculate ‘backgroundColor’ based on another view
style :some_view, # there’s no “only run once” idiom in teacup, so we need to make sure not to # create this view every time :some_view is restyled. leftView: ->(view) { view.leftView || UILabel.alloc.initWithFrame(…) }
“
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.
“by 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.
“by
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 (it is a per orientation cache).
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
If you get an error that looks like this:
Objective-C stub for message `setHidesWhenStopped:' type `[email protected]:c' not
precompiled. Make sure you properly link with the framework or library that
defines this message.
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. There is a [dummy.rb file for iOS][], and one for OS X.
If you need to add this method to your project, please give back to the community by forking teacup and adding this method to the dummy.rb file. It’s easy! Create a subclass, define a method called dummy
, and call the “not precompiled” message inside it. That will trigger the compiler to include this method signature.
For instance, lets say you are styling a UIPickerView
and you get the error:
Objective-C stub for message `setShowsSelectionIndicator:' type ...
You would open up dummy.rb and add the following code:
“by class DummyPickerView < UIPickerView private def dummy setShowsSelectionIndicator(nil) end end
“
Recompile your project, and you should be good to go!
Teacup is a Community Project!
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!
I’m Colin T.A. Gray, the maintainer of the Teacup project. I hope this tool helps you build great apps!