Module: Teacup::Layout

Included in:
UIView
Defined in:
lib/teacup/layout.rb

Overview

Teacup::Layout defines a layout and subview function that can be used to declare and configure the layout of views and the view hierarchy in your application.

This module is included into UIView and UIViewController directly so these functions are available in the places you need them.

In order to use layout() in a UIViewController most effectively you will want to define a stylesheet method that returns a stylesheet.

Examples:

class MyViewController < UIViewController
  layout(:my_view) do
    layout UIImage, :logo
  end

  def stylesheet
    Teacup::Stylesheet[:logo]
  end
end

Instance Method Summary (collapse)

Instance Method Details

- (Object) layout(view, name_or_properties = nil, properties_or_nil = nil, &block)

Alter the layout of a view

For example, to alter the width and height of a carousel:

Or to layout the carousel in the default style:

You can also use this method with subview, for example to add a new image to a carousel:

Examples:

layout(carousel, width: 500, height: 100)
layout(carousel, :default_carousel)
layout(carousel) {
  subview(UIImage, backgroundColor: UIColor.colorWithImagePattern(image)
}

Parameters:

  • instance —

    The first parameter is the view that you want to layout.

  • name —

    The second parameter is optional, and is the stylename to apply to the element. When using stylesheets any properties defined in the current stylesheet (see stylesheet) for this element will be immediately applied.

  • properties —

    The third parameter is optional, and is a Hash of properties to apply to the view directly.

  • &block —

    If a block is passed, it is evaluated such that any calls to subview that occur within that block cause created subviews to be added to this view instead of to the top-level view.



62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/teacup/layout.rb', line 62

def layout(view, name_or_properties=nil, properties_or_nil=nil, &block)
  name = nil
  properties = properties_or_nil

  if Hash === name_or_properties
    name = nil
    properties = name_or_properties
  elsif name_or_properties
    name = name_or_properties.to_sym
  end

  view.stylesheet = stylesheet
  view.stylename = name
  view.style(properties) if properties

  begin
    superview_chain << view
    instance_exec(view, &block) if block_given?
  ensure
    superview_chain.pop
  end

  view
end

- (Object) subview(class_or_instance, *args, &block)

Add a new subview to the view heirarchy.

By default the subview will be added at the top level of the view heirarchy, though if this function is executed within a block passed to layout or subview, then this view will be added as a subview of the instance being layed out by the block.

This is particularly useful when coupled with the UIViewController.heirarchy function that allows you to declare your view heirarchy.

For example, to specify that a controller should contain some labels:

If you need to add a new image at runtime, you can also do that:

Examples:

MyViewController < UIViewController
  heirarchy(:my_view) do
    subview(UILabel, text: 'Test')
    subview(UILabel, :styled_label)
  end
end
layout(carousel) {
  subview(UIImage, backgroundColor: UIColor.colorWithImagePattern(image)
}

Parameters:

  • class_or_instance —

    The UIView subclass (or instance thereof) that you want to add. If you pass a class, an instance will be created by calling new.

  • *args —

    Arguments to pass to layout to instruct teacup how to lay out the newly added subview.

  • &block —

    A block to execute with the current view context set to your new element, see layout for more details.

Returns:

  • instance The instance that was added to the view heirarchy.



125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
 
# File 'lib/teacup/layout.rb', line 125

def subview(class_or_instance, *args, &block)
  if Class === class_or_instance
    unless class_or_instance <= UIView
      raise "Expected subclass of UIView, got: #{class_or_instance.inspect}"
    end
    instance = class_or_instance.new
  elsif UIView === class_or_instance
    instance = class_or_instance
  else
    raise "Expected a UIView, got: #{class_or_instance.inspect}"
  end

  (superview_chain.last || top_level_view).addSubview(instance)

  layout(instance, *args, &block)

  instance
end