teacup 0.0.1.pre → 0.3.1

data/lib/teacup/stylesheet.rb

@@ -0,0 +1,242 @@
+module Teacup
+  # Stylesheets in Teacup act as a central configuration mechanism,
+  # they have two aims:
+  #
+  # 1. Allow you to store "Details" away from the main body of your code.
+  #    (controllers shouldn't have to be filled with style rules)
+  # 2. Allow you to easily re-use configuration in many places.
+  #
+  # The API really provides only two methods, {Stylesheet#style} to store properties
+  # on the Stylesheet; and {Stylesheet#query} to get them out again:
+  #
+  # @example
+  #   stylesheet = Teacup::Stylesheet.new
+  #   stylesheet.style :buttons, :corners => :rounded
+  #   # => nil
+  #   stylesheet.query :buttons
+  #   # => {:corners => :rounded}
+  #
+  # In addition to this, two separate mechanisms are provided for sharing
+  # configuration within stylesheets.
+  #
+  # Firstly, if you set the ':extends' property for a given stylename, then on lookup
+  # the Stylesheet will merge the properties for the ':extends' stylename into the return
+  # value. Conflicts are resolved so that properties with the original stylename
+  # are resolved in its favour.
+  #
+  # @example
+  #   Teacup::Stylesheet.new(:ipad) do
+  #     style :button,
+  #       backgroundImage: UIImage.imageNamed("big_red_shiny_button"),
+  #       top: 100
+  #
+  #     style :ok_button, extends: :button,
+  #       title: "OK!",
+  #       top: 200
+  #
+  #   end
+  #   Teacup::Stylesheet[:ipad].query(:ok_button)
+  #   # => {backgroundImage: UIImage.imageNamed("big_red_shiny_button"), top: 200, title: "OK!"}
+  #
+  # Secondly, you can import Stylesheets into each other, in exactly the same way as you
+  # can include Modules into each other in Ruby. This allows you to share rules between
+  # Stylesheets.
+  #
+  # As you'd expect, conflicts are resolved so that the Stylesheet on which you
+  # call query has the highest precedence.
+  #
+  # @example
+  #   Teacup::Stylesheet.new(:ipad) do
+  #     style :ok_button,
+  #       title: "OK!"
+  #   end
+  #
+  #   Teacup::Stylesheet.new(:ipadvertical) do
+  #     import :ipad
+  #     style :ok_button,
+  #       width: 80
+  #   end
+  #   Teacup::Stylesheet[:ipadvertical].query(:ok_button)
+  #   # => {title: "OK!", width: 80}
+  #
+  # The two merging mechanisms are considered independently, so you can override
+  # a property both in a ':extends' rule, and also in an imported Stylesheet. In such a
+  # a case the Stylesheet inclusion conflicts are resolved independently; and then in
+  # a second phase, the ':extends' chain is flattened.
+  #
+  class Stylesheet
+    attr_reader :name
+
+    class << self
+      def stylesheets
+        @stylesheets ||= {}
+      end
+
+      def [] name
+        stylesheets[name]
+      end
+
+      def []= name, stylesheet
+        stylesheets[name] = stylesheet
+      end
+    end
+
+    # Create a new Stylesheet.
+    #
+    # If a name is provided then a new constant will be created using that name.
+    #
+    # @param name, The (optional) name to give.
+    # @param &block, The body of the Stylesheet instance_eval'd.
+    #
+    # @example
+    #   Teacup::Stylesheet.new(:ipadvertical) do
+    #     import :ipadbase
+    #     style :continue_button,
+    #        top: 50
+    #   end
+    #
+    #   Teacup::Stylesheet[:ipadvertical].query(:continue_button)
+    #   # => {top: 50}
+    #
+    def initialize(name=nil, &block)
+      if name
+        @name = name.to_sym
+        Teacup::Stylesheet[@name] = self
+      end
+
+      # we just store the block for now, because some classes are not "ready"
+      # for instance, calling `UIFont.systemFontOfSize()` will cause the
+      # application to crash.  We will lazily-load this block in `query`, and
+      # then set it to nil.
+      @block = block
+    end
+
+    # Include another Stylesheet into this one, the rules defined
+    # within it will have lower precedence than those defined here
+    # in the case that they share the same keys.
+    #
+    # @param Symbol|Teacup::Stylesheet  the name of the stylesheet,
+    #                                   or the stylesheet to include.
+    #
+    # When defining a stylesheet declaratively, it is better to use the symbol
+    # that represents a stylesheet, as the constant may not be defined yet:
+    #
+    # @example
+    #   Teacup::Stylesheet.new(:ipadvertical) do
+    #     import :ipadbase
+    #     import :verticaltweaks
+    #   end
+    #
+    #
+    # If you are using anonymous stylesheets however, then it will be necessary
+    # to pass an actual stylesheet object.
+    #
+    # @example
+    #   @stylesheet.import(base_stylesheet)
+    #
+    def import(name_or_stylesheet)
+      imported << name_or_stylesheet
+    end
+
+    # Get the properties defined for the given stylename, in this Stylesheet and
+    # all those that have been imported.
+    #
+    # The Style class handles precedence rules, and extending via `:extends` and
+    # `import`.  If needs the orientation in order to merge and remove the
+    # appropriate orientation styles.
+    #
+    # @param Symbol stylename, the stylename to look up.
+    # @return Hash[Symbol, *] the resulting properties.
+    # @example
+    #   Teacup::Stylesheet[:ipadbase].query(:continue_button)
+    #   # => {backgroundImage: UIImage.imageNamed("big_red_shiny_button"), title: "Continue!", top: 50}
+    def query(stylename, target=nil, orientation=nil, seen={})
+      return {} if seen[self]
+
+      # the block handed to Stylesheet#new is not run immediately - it is run
+      # the first time the stylesheet is queried.  This fixes bugs related to
+      # some resources (fonts) not available when the application is first
+      # started.  The downside is that @instance variables and variables that
+      # should be closed over are not.
+      if @block
+        instance_eval &@block
+        @block = nil
+      end
+      seen[self] = true
+
+      styles[stylename].build(target, orientation, seen)
+    end
+
+    # Add a set of properties for a given stylename or multiple stylenames.
+    #
+    # @param Symbol, *stylename
+    # @param Hash[Symbol, Object], properties
+    #
+    # @example
+    #   Teacup::Stylesheet.new(:ipadbase) do
+    #     style :pretty_button,
+    #       backgroundImage: UIImage.imageNamed("big_red_shiny_button")
+    #
+    #     style :continue_button, extends: :pretty_button,
+    #       title: "Continue!",
+    #       top: 50
+    #   end
+    def style(*queries)
+      if queries[-1].is_a? Hash
+        properties = queries.pop
+      else
+        # empty style declarations are allowed
+        return
+      end
+
+      queries.each do |stylename|
+        # merge into styles[stylename], new properties "win"
+        Teacup::merge_defaults(properties, styles[stylename], styles[stylename])
+      end
+    end
+
+    # A unique and hopefully meaningful description of this Object.
+    #
+    # @return String
+    def inspect
+      "Teacup::Stylesheet[#{name.inspect}] = #{styles.inspect}"
+    end
+
+    # The array of Stylesheets that have been imported into this one.
+    #
+    # @return Array[Stylesheet]
+    def imported_stylesheets
+      imported.map do |name_or_stylesheet|
+        if name_or_stylesheet.is_a? Teacup::Stylesheet
+          name_or_stylesheet
+        elsif Teacup::Stylesheet.stylesheets.has_key? name_or_stylesheet
+          Teacup::Stylesheet.stylesheets[name_or_stylesheet]
+        else
+          raise "Teacup tried to import Stylesheet #{name_or_stylesheet.inspect} into Stylesheet[#{self.name.inspect}], but it didn't exist"
+        end
+      end
+    end
+
+    protected
+
+    # The list of Stylesheets or names that have been imported into this one.
+    #
+    # @return Array[Symbol|Stylesheet]
+    def imported
+      @imported ||= []
+    end
+
+    # The actual contents of this stylesheet as a Hash from stylename to properties.
+    #
+    # @return Hash[Symbol, Hash]
+    def styles
+      @styles ||= Hash.new{ |_styles, stylename|
+        @styles[stylename] = Style.new
+        @styles[stylename].stylename = stylename
+        @styles[stylename].stylesheet = self
+        @styles[stylename]
+      }
+    end
+
+  end
+end

data/lib/teacup/stylesheet_extensions/rotation.rb

@@ -0,0 +1,38 @@
+
+module Teacup
+
+  class Stylesheet
+    def identity
+      [1,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,1]
+    end
+
+    def pi
+      3.1415926
+    end
+
+    # rotates the "up & down" direction.  The bottom of the view will rotate
+    # towards the user as angle increases.
+    def flip matrix, angle
+      CATransform3DRotate(matrix, angle, 1, 0, 0)
+    end
+
+    # rotates the "left & right" direction.  The right side of the view will
+    # rotate towards the user as angle increases.
+    def twist matrix, angle
+      CATransform3DRotate(matrix, angle, 0, 1, 0)
+    end
+
+    # spins, along the z axis.  This is probably the one you want, for
+    # "spinning" a view like you might a drink coaster or paper napkin.
+    def spin matrix, angle
+      CATransform3DRotate(matrix, angle, 0, 0, 1)
+    end
+
+    # rotates the layer arbitrarily
+    def rotate matrix, angle, x, y, z
+      CATransform3DRotate(matrix, angle, x, y, z)
+    end
+
+  end
+
+end

data/lib/teacup/version.rb

@@ -1,5 +1,5 @@
 module Teacup
 
-  VERSION = '0.0.1'
+  VERSION = '0.3.1'
 
 end

data/lib/teacup/z_core_extensions/ca_layer.rb

@@ -0,0 +1,6 @@
+# adds the `debug` property to CALayer
+class CALayer
+
+  attr_accessor :debug
+
+end

data/lib/teacup/z_core_extensions/ui_view.rb

@@ -0,0 +1,119 @@
+# Teacup's UIView extensions defines some utility functions for UIView that
+# enable a lot of the magic for Teacup::Layout.
+
+# Users of teacup should be able to ignore the contents of this file for
+# the most part.
+class UIView
+  include Teacup::Layout
+
+  # The current stylename that is used to look up properties in the stylesheet.
+  attr_reader :stylename
+
+  # Enable debug messages for this object
+  attr_accessor :debug
+
+  # The current stylesheet will be looked at when properties are needed.  It
+  # is loaded lazily, so that assignment can occur before the Stylesheet has
+  # been created.
+  def stylesheet
+    if Symbol === @stylesheet
+      @stylesheet = Teacup::Stylesheet[@stylesheet]
+    end
+
+    @stylesheet
+  end
+
+  # Alter the stylename of this view.
+  #
+  # This will cause new styles to be applied from the stylesheet.
+  #
+  # @param Symbol  stylename
+  def stylename=(new_stylename)
+    @stylename = new_stylename
+    restyle!
+  end
+
+  # Alter the stylesheet of this view.
+  #
+  # This will cause new styles to be applied using the current stylename,
+  # and will recurse into subviews.
+  #
+  # If you would prefer that a given UIView object does not inherit the
+  # stylesheet from its parents, override the 'stylesheet' method to
+  # return the correct value at all times.
+  #
+  # @param Teacup::Stylesheet  stylesheet.
+  def stylesheet=(new_stylesheet)
+    @stylesheet = new_stylesheet
+    restyle!
+    subviews.each{ |subview| subview.stylesheet = new_stylesheet }
+  end
+
+  def restyle!(orientation=nil)
+    style(stylesheet.query(stylename, self, orientation)) if stylesheet
+    subviews.each{ |subview| subview.restyle!(orientation) }
+  end
+
+  # Animate a change to a new stylename.
+  #
+  # This is equivalent to wrapping a call to .stylename= inside
+  # UIView.beginAnimations.
+  #
+  # @param Symbol  the new stylename
+  # @param Options  the options for the animation (may include the
+  #                 duration and the curve)
+  #
+  def animate_to_stylename(stylename, options={})
+    return if self.stylename == stylename
+
+    UIView.beginAnimations(nil, context: nil)
+    # TODO: This should be in a style-sheet!
+    UIView.setAnimationDuration(options[:duration]) if options[:duration]
+    UIView.setAnimationCurve(options[:curve]) if options[:curve]
+    self.stylename = stylename
+    UIView.commitAnimations
+  end
+
+  # Animate a change to new styles
+  #
+  # This is equivalent to wrapping a call to .style() inside
+  # UIView.beginAnimations.
+  #
+  # @param Hash   the new styles and options for the animation
+  #
+  def animate_to_style(style)
+    UIView.beginAnimations(nil, context: nil)
+    UIView.setAnimationDuration(style[:duration]) if style[:duration]
+    UIView.setAnimationCurve(style[:curve]) if style[:curve]
+    style(style)
+    UIView.commitAnimations
+  end
+
+  # Apply style properties to this element.
+  #
+  # Takes a hash of properties such as may have been read from a stylesheet
+  # or passed as parameters to {Teacup::Layout#layout}, and applies them to
+  # the element.
+  #
+  # Does a little bit of magic (that may be split out as 'sugarcube') to
+  # make properties work as you'd expect.
+  #
+  # If you try and assign something in properties that is not supported,
+  # a warning message will be emitted.
+  #
+  # @param Hash  the properties to set.
+  def style(properties, orientation=nil)
+    Teacup.apply_hash self, properties
+    properties.each do |key, value|
+      Teacup.apply self, key, value
+    end
+
+    self.setNeedsDisplay
+    self.setNeedsLayout
+  end
+
+  def top_level_view
+    return self
+  end
+
+end

data/lib/teacup/z_core_extensions/ui_view_controller.rb

@@ -0,0 +1,179 @@
+# Adds methods to the UIViewController class to make defining a layout and
+# stylesheet very easy.  Also provides rotation methods that analyze
+class UIViewController
+  include Teacup::Layout
+
+  class << self
+    attr_reader :layout_definition
+
+    # Define the layout of a controller's view.
+    #
+    # This function is analogous to Teacup::Layout#layout, though it is
+    # designed so you can create an entire layout in a declarative manner in
+    # your controller.
+    #
+    # The hope is that this declarativeness will allow us to automatically
+    # deal with common iOS programming tasks (like releasing views when
+    # low-memory conditions occur) for you. This is still not implemented
+    # though.
+    #
+    # @param name  The stylename for your controller's view.
+    #
+    # @param properties  Any extra styles that you want to apply.
+    #
+    # @param &block  The block in which you should define your layout.
+    #                It will be instance_exec'd in the context of a
+    #                controller instance.
+    #
+    # @example
+    #   MyViewController < UIViewController
+    #     layout :my_view do
+    #       subview UILabel, title: "Test"
+    #       subview UITextField, {
+    #         frame: [[200, 200], [100, 100]]
+    #         delegate: self
+    #       }
+    #       subview UIView, :shiny_thing) {
+    #         subview UIView, :centre_of_shiny_thing
+    #       }
+    #     end
+    #   end
+    #
+    def layout(stylename=nil, properties={}, &block)
+      @layout_definition = [stylename, properties, block]
+    end
+
+    def stylesheet(new_stylesheet=nil)
+      if new_stylesheet.nil?
+        return @stylesheet
+      end
+
+      @stylesheet = new_stylesheet
+    end
+
+  end # class << self
+
+  # Returns a stylesheet to use to style the contents of this controller's
+  # view.  You can also assign a stylesheet to {stylesheet=}, which will in
+  # turn call {restyle!}.
+  #
+  # This method will be queried each time {restyle!} is called, and also
+  # implicitly whenever Teacup needs to draw your layout (currently only at
+  # view load time).
+  #
+  # @return Teacup::Stylesheet
+  #
+  # @example
+  #
+  #  def stylesheet
+  #    if [UIDeviceOrientationLandscapeLeft,
+  #        UIDeviceOrientationLandscapeRight].include?(UIDevice.currentDevice.orientation)
+  #      Teacup::Stylesheet[:ipad]
+  #    else
+  #      Teacup::Stylesheet[:ipadvertical]
+  #    end
+  #  end
+  def stylesheet
+    @stylesheet
+  end
+
+  # Assigning a new stylesheet triggers {restyle!}, so do this during a
+  # rotation to get your different layouts applied.
+  #
+  # Assigning a stylesheet is an *alternative* to returning a Stylesheet in
+  # the {stylesheet} method. Note that {restyle!} calls {stylesheet}, so while
+  # assigning a stylesheet will trigger {restyle!}, your stylesheet will not
+  # be picked up if you don't return it in a custom stylesheet method.
+  #
+  # @return Teacup::Stylesheet
+  #
+  # @example
+  #
+  #   stylesheet = Teacup::Stylesheet[:ipadhorizontal]
+  #   stylesheet = :ipadhorizontal
+  def stylesheet=(new_stylesheet)
+    @stylesheet = new_stylesheet
+    if view
+      view.stylesheet = new_stylesheet
+      view.restyle!
+    end
+  end
+
+  def top_level_view
+    return self.view
+  end
+
+
+  # Instantiate the layout from the class, and then call layoutDidLoad.
+  #
+  # If you want to use Teacup in your controller, please hook into layoutDidLoad,
+  # not viewDidLoad.
+  def viewDidLoad
+
+    if not self.stylesheet
+      self.stylesheet = self.class.stylesheet
+    end
+
+    if self.class.layout_definition
+      stylename, properties, block = self.class.layout_definition
+      layout(view, stylename, properties, &block)
+    end
+
+    layoutDidLoad
+  end
+
+  def viewWillAppear(animated)
+    self.view.restyle!
+  end
+
+  def layoutDidLoad
+    true
+  end
+
+  # The compiling mechanisms combined with how UIKit works of rubymotion do
+  # not allow the `shouldAutorotateToInterfaceOrientation` method to be
+  # overridden in modules/extensions.  So instead, HERE is the code for what
+  # `shouldAutorotateToInterfaceOrientation` should look like if you want
+  # to use the teacup rotation stuff.  Call this method from your own
+  # `shouldAutorotateToInterfaceOrientation` method.
+  #
+  # the teacup developers apologize for any inconvenience. :-)
+  def autorotateToOrientation(orientation)
+    if view.stylesheet and view.stylename
+      properties = view.stylesheet.query(view.stylename, self, orientation)
+
+      # check for orientation-specific properties
+      case orientation
+      when UIInterfaceOrientationPortrait
+        # portrait is "on" by default, must be turned off explicitly
+        if properties.supports?(:portrait) == nil and properties.supports?(:upside_up) == nil
+          return true
+        end
+
+        return (properties.supports?(:portrait) or properties.supports?(:upside_up))
+      when UIInterfaceOrientationPortraitUpsideDown
+        if UIDevice.currentDevice.userInterfaceIdiom == UIUserInterfaceIdiomPhone
+          # iphone must have an explicit upside-down style, otherwise this returns
+          # false
+          return properties.supports?(:upside_down)
+        else
+          # ipad can just have a portrait style
+          return (properties.supports?(:portrait) or properties.supports?(:upside_down))
+        end
+      when UIInterfaceOrientationLandscapeLeft
+        return (properties.supports?(:landscape) or properties.supports?(:landscape_left))
+      when UIInterfaceOrientationLandscapeRight
+        return (properties.supports?(:landscape) or properties.supports?(:landscape_right))
+      end
+
+      return false
+    end
+
+    return orientation == UIInterfaceOrientationPortrait
+  end
+
+  def willAnimateRotationToInterfaceOrientation(orientation, duration:duration)
+    view.restyle!(orientation)
+  end
+
+end

data/lib/teacup/z_core_extensions/ui_view_getters.rb

@@ -0,0 +1,34 @@
+# Methods to retrieve a subview using the stylename as a key
+# Kinda similar to jQuery-style $().find('stylename')
+class UIView
+
+  # get one stylesheet by stylename
+  # my_view[:button] :button => #<UIButton..>
+  def viewWithStylename name
+    subviews.each do |view|
+      if view.stylename == name
+        return view
+      end
+    end
+    subviews.each do |view|
+      if v = view.viewWithStylename(name)
+        return v
+      end
+    end
+    nil  # couldn't find it
+  end
+
+  # get stylesheets by stylename
+  # my_view.all :button => [#<UIButton..>, #<UIButton...>]
+  def viewsWithStylename name
+    r = []
+    subviews.each do |view|
+      if view.stylename == name
+        r.push name
+      end
+      r += view.viewsWithStylename name
+    end
+    r
+  end
+
+end

data/lib/teacup/z_core_extensions/z_handlers.rb

@@ -0,0 +1,57 @@
+##|
+##|  UIView.frame
+##|
+Teacup.handler UIView, :left, :x { |view, x|
+  f = view.frame
+  f.origin.x = x
+  view.frame = f
+}
+
+Teacup.handler UIView, :right { |view, r|
+  f = view.frame
+  f.origin.x = r - f.size.width
+  view.frame = f
+}
+
+Teacup.handler UIView, :top, :y { |view, y|
+  f = view.frame
+  f.origin.y = y
+  view.frame = f
+}
+
+Teacup.handler UIView, :bottom { |view, b|
+  f = view.frame
+  f.origin.y = b - f.size.height
+  view.frame = f
+}
+
+Teacup.handler UIView, :width { |view, w|
+  f = view.frame
+  f.size.width = w
+  view.frame = f
+}
+
+Teacup.handler UIView, :height { |view, h|
+  f = view.frame
+  f.size.height = h
+  view.frame = f
+}
+
+Teacup.handler UIView, :origin { |view, origin|
+  f = view.frame
+  f.origin = origin
+  view.frame = f
+}
+
+Teacup.handler UIView, :size { |view, size|
+  f = view.frame
+  f.size = size
+  view.frame = f
+}
+
+##|
+##|  UIButton
+##|
+Teacup.handler UIButton, :title { |view, title|
+  view.setTitle(title, forState: UIControlStateNormal)
+}