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.
Check out some sample apps!
- iOS
- “Hai”
- “AutoLayout”
- “Sweettea Example”
- OS X
- “Tweets” - ported from RubyMotionSamples
- “simple”
Quick Install
> gem install teacupand in your Rakefile
require 'teacup'-
Create a
UIViewControllersubclass:class MyController < UIViewController
-
Assign a stylesheet name:
class MyController < UIViewController stylesheet :main_screen
-
Create a layout:
class MyController < UIViewController stylesheet :main_screen layout do subview(UIButton, :hi_button) end end
-
Create the stylesheet (in
app/styles/or somewhere near the controller)Teacup::Stylesheet.new :main_screen do style :hi_button, origin: [10, 10], title: 'Hi!' end
Pretty much the same!
You should use the TeacupWindowController parent class instead of NSWindowController
-
Create a
TeacupWindowControllersubclass.class MyController < TeacupWindowController
-
Assign a stylesheet name:
class MyController < TeacupWindowController stylesheet :main_window
-
Create a layout:
class MyController < TeacupWindowController stylesheet :main_window layout do subview(NSButton, :hi_button) end end
-
Create the stylesheet (in
app/styles/or somewhere near the controller)Teacup::Stylesheet.new :main_window do style :hi_button, origin: [10, 10], title: 'Hi!' end
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!
- Layouts
- Stylesheets
- UITableViews - This is important if you are using styles and
constraints in a
UITableViewDelegate. - More Teacup features
- Showdown
- The Nitty Gritty
- Advanced Teacup Tricks
- Misc notes
- The Dummy
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. This is a helper
function that stores the layout code. A more direct example might look like
this:
# 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
endYou can use very similar code in your view subclasses.
# 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
endThe 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 callsnewon 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 thedelegateordataSource.&block- See discussion below- Returns the
viewthat was created or passed tolayout. - only the
viewarg 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.
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)
endThese 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?).
# 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.buttonWithType(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
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
endclass MyController < UIViewController
layout do
@button1 = button()
@button2 = button(:blue_button)
@button3 = button_with_icon(UIImage.imageNamed('email_icon'), 'Email')
end
end
The Controller##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
# defined in teacup/teacup_controller.rb as Teacup::Controller module
UIViewController.layout(stylename=nil, styles={}, &block)
NSViewController.layout(stylename=nil, styles={}, &block)
NSWindowController.layout(stylename=nil, styles={}, &block)stylenameis the stylename you want applied to your controller'sself.viewobject.stylesare rarely applied here, but one common use case is when you assign a custom view inloadView, and you want to apply settings to it. I find it cleaner to move this code into the body of thelayoutblock, though.&blockis the most important - it is the layout code that will be called duringviewDidLoad.
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.
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.
# 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
# ^.............^
endNice! 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.
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 stylesheetAny 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.
- 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.
This is the most common way to apply a style.
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
endWhen 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:
layout do
subview(UILabel, :h1,
# the `subview` and `layout` methods can apply styles
text: "Omg, it's full of stars"
)
endIn this case though we just have static text, so you can assign the text using the stylesheet:
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)
endNot 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:
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"
endA common style when writing stylesheets is to use instance variables to store settings you want to tweak.
Teacup::Stylesheet.new :main do
@hi_font = UIFont.systemFontOfSize(20)
style :h1,
font: @hi_font
style :main_header, extends: :h1,
text: "Omg, it's full of stars"
endIf 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!).
Teacup::Stylesheet.new :app do
style UILabel,
font: UIFont.systemFontOfSize(20)
style UITableView,
backgroundColor: UIColor.blackColor
endWe'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 styles and you gain
access to its instance variables. This way you can define colors and margins and
such in a "parent" stylesheet.
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
endiOS 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!
Teacup::Appearance.new do
# UINavigationBar.appearance.setTintColor(UIColor.blackColor)
style UINavigationBar,
tintColor: UIColor.blackColor
# 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
endIn 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.
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
endThat 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.
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.
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.
# 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')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.
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
endConstraints and styles get applied before the view appears, even if the cell is reused later.
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 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!
# 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
}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.
Teacup::Stylesheet.new :main do
# this label hides when the orientation is landscape (left or right)
style :label,
landscape: {
hidden: true
},
portrait: {
hidden: false
}
endCombine these styles with Frame Calculations to have you view frame recalculated automatically.
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".
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.
# 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.
style :container,
frame: :full # => [[0, 0], superview.frame.size]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
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%']]
endWhen 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.
margin = 8
style :button,
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}"]]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.
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.
endThis 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)
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),
]
endWriting 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.
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.
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.
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
endAuto-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.
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.
# 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.fillThe 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
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:
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}"]]
endMultiple calls to style will add those styles, not replace. So this code
works just fine:
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
endiOS 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.
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.
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)
}As a recap, here is a translation of traditional Cocoa code done using Teacup.
No cool tricks here, just some plain ol' Cocoa.
#
# 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.
endYou 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.
layout do
subview(UITableView, delegate: self)
endStyles 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.
layout do
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
endThe idea here is that the closer the style setting is to where the view is instantiated, the higher the precedence.
More examples!
class MyController < UIViewController
stylesheet :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
endThere 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.
...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.
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.
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
endSugarCube + 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.
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: :slateblueSweettea 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.
# 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_inputMultiple 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)..
If you get an error that looks like this:
Objective-C stub for message `setHidesWhenStopped:' type `v@: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.
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!