teacup 0.0.1.pre

data/.gitignore

@@ -0,0 +1,3 @@
+.DS_Store
+.rspec
+.sass-cache/

data/Dofile

@@ -0,0 +1,6 @@
+require 'do_it'
+
+tasks = DoIt.new do
+  todo 'Make a "nicer looking" sample app (or improve existing app).'
+  todo 'Extend wiki on Github.'
+end

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,26 @@
+PATH
+  remote: .
+  specs:
+    teacup (0.0.1)
+      rake
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.3)
+    rake (0.9.2.2)
+    rspec (2.10.0)
+      rspec-core (~> 2.10.0)
+      rspec-expectations (~> 2.10.0)
+      rspec-mocks (~> 2.10.0)
+    rspec-core (2.10.1)
+    rspec-expectations (2.10.0)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.10.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rspec
+  teacup!

data/README.md

@@ -0,0 +1,151 @@
+Teacup
+======
+
+A community-driven DSL for creating user interfaces on the iphone.
+
+By including the `Teacup` module, you can easily create layouts that adhere to
+the [iOS user interface guidelines][iOS HIG], and it's an easy way to assign labels,
+delegators, and datasources.
+
+The goal is not to simply rename CocoaTouch method names, but to offer a
+rubyesque (well, actually a rubymotion-esque) way to create an interface.
+
+Using stylesheets and layouts, it makes coding an iOS app like designing a website with HTML and CSS.
+
+**Check out a working sample app [here](https://github.com/rubymotion/teacup/tree/master/samples/Hai)!**
+
+#### Installation
+
+```bash
+$ git submodule add https://github.com:rubymotion/teacup vendor/teacup
+```
+
+Then add the teacup library to your Rakefile:
+```
+  # Add libraries *before* your app so that you can access constants they define safely
+  #
+  dirs = ['vendor/teacup/lib', 'app']
+
+  # require all the directories in order.
+  app.files = dirs.map{|d| Dir.glob(File.join(app.project_dir, "#{d}/**/*.rb")) }.flatten
+```
+
+
+#### Showdown
+
+Regular
+
+```ruby
+class SomeController < UIViewController
+ def viewDidLoad
+
+  @field = UITextField.new
+  @field.height = 50
+  @field.width  = 200
+  view.addSubview(@field)
+  
+  @search = UITextField.new
+  @search.height = 50
+  @search.width  = 200
+  @search.placeholder = 'Find something...'
+  view.addSubview(@search)
+  
+  true
+ end
+end
+```
+
+Teacup
+
+```ruby
+# Stylesheet
+
+Teacup::StyleSheet.new(:IPhone) do
+ 
+ style :field,
+  height: 50,
+  width:  200
+  
+ style :search, extends: :field,
+  placeholder: 'Foo...'
+ 
+end
+
+# Controller
+
+class SomeController < UIViewController
+ 
+ def viewDidLoad
+  view.addSubview(Teacup.style(:field, UITextField.new))
+  view.addSubview(Teacup.style(:search))
+  true
+ end
+ 
+end
+```
+
+Development
+-----------
+
+*Current version*: v0.0.0 (or see `lib/teacup/version.rb`)
+
+*Last milestone*: Pick a name
+
+*Next milestone*: Pick a DSL
+
+teacup, being a community project, moves in "spurts" of decision making and
+coding.  Only the name — both the least and most important part :-) — is
+decided.
+
+We would love suggestions of any sort, and we're always free over at the `#teacuprb` channel on `irc.freenode.org`.
+
+
+Ideas that proposals should keep in mind
+----------------------------------------
+
+1. output will conform, unless explicitly *disabled* to the [iOS HIG][]
+2. should provide a few useful layouts (see [readme for layout proposals](teacup/tree/master/proposals/layout)):
+     * basic: vertically arranged "things", or
+     * form: label/input combinations arranged in a table
+     * navbar: with ability to customize the buttons that get placed at the top
+     * tabbar: similar, but with the tabs at the bottom instead of nav at the top
+     * splitview: A splitview controller (for iPad Apps) with sane navigation defaults, nice loading webviews and JSON to populate the items in the popover menu
+
+3. layouts should have ways of placing things relative to edges, so placing a
+   label or nav at the "bottom" that spans the entire width should be *easy*.
+   (This means we'll need to check for ipad or iphone.)
+4. actions are either blocks, defined inline, or target/action combos (e.g.
+   `target: self, action: :my_method`)
+5. there should be a consistent "styling" language, preferably in a separate
+   file, something that could be handed to a designer.  this is the BIG item!
+6. teacup should take a little `config` block for easy configuration
+7. Ideally, there should be some way to "inherit" styles in this language. So you can define a basic layout for all platforms and then tweak (see [readme for style proposals](teacup/tree/master/proposals/styles))
+
+[iOS HIG]: http://developer.apple.com/library/ios/#DOCUMENTATION/UserExperience/Conceptual/MobileHIG/Introduction/Introduction.html
+
+Bugs
+----
+
+Please, do *not* hesitate to report any bugs you find with our source at the [Issues](https://github.com/rubymotion/teacup/issues) page.
+
+Actual proposals
+----------------
+
+1. [stylesheet][Commune], by [ConradIrwin][]
+2. [teacup][teacup_colinta], by [colinta][]
+3. [style][style_by_beakr], by [Beakr][]
+3. [layout][layout_by_beakr], by [Beakr][]
+4. [layout][layout_by_farcaller], by [farcaller][]
+5. [hybrid][], by [colinta][]
+
+[Commune]: https://github.com/colinta/teacup/blob/master/proposals/styles/stylesheet_by_conradirwin.rb
+[teacup_colinta]: https://github.com/colinta/teacup/blob/master/proposals/styles/teacup_by_colinta.rb
+[style_by_beakr]: https://github.com/colinta/teacup/blob/master/proposals/layout/beakr_improved.rb
+[layout_by_beakr]: https://github.com/colinta/teacup/blob/master/proposals/styles/beakr_improved.rb
+[layout_by_farcaller]: https://github.com/colinta/teacup/blob/master/proposals/styles/layout_by_farcaller.rb
+[hybrid]: https://github.com/colinta/teacup/blob/master/proposals/layout/hybrid_style_and_layout_by_colinta.rb
+
+[ConradIrwin]: https://github.com/ConradIrwin
+[colinta]: https://github.com/colinta
+[farcaller]: https://github.com/farcaller
+[Beakr]: https://github.com/Beakr

data/Rakefile

@@ -0,0 +1,39 @@
+#!/usr/bin/env rake
+
+# Bundler gem tasks ftw
+require 'bundler/gem_tasks'
+
+require 'rspec/core/rake_task'
+require File.expand_path '../lib/teacup/version.rb', __FILE__
+
+# Default task
+task :default => :spec # Run spec
+task :v       => :version # Alt
+
+# - - - - - - - - - - - - - - - - - - -
+# Tasks
+# - - - - - - - - - - - - - - - - - - -
+
+desc 'display Teacup\'s current version'
+task(:version) { version }
+
+desc 'diesplay list of contributors'
+task(:contrib)  { contrib }
+
+desc 'run RSpec tests'
+RSpec::Core::RakeTask.new
+
+desc 'build and install the gem'
+task(:prep) { system('rake build; rake install') }
+
+# - - - - - - - - - - - - - - - - - - -
+# Helpers
+# - - - - - - - - - - - - - - - - - - -
+
+def version
+  puts "Teacup #{Teacup::VERSION}"
+end
+
+def contrib
+  puts Teacup::CONTRIBUTORS
+end

data/lib/teacup.rb

@@ -0,0 +1,41 @@
+unless defined?(Motion::Project::Config)
+  raise "This file must be required within a RubyMotion project Rakefile."
+end
+
+# In order that we can prepend our files to the load path after the user has
+# configured their app.files, we need to run code *after* the user has set up
+# their app.
+#
+# Unfortunately, the canonical place to require rubygems is at the top of the
+# file (while we could just add to the instructions "please `require 'teacup'`
+# at the bottom, that would be odd, and no-one would read the instructions).
+#
+# To this end, we tweak the App setup function so that whenever setup is called,
+# we configure teacup after that.
+#
+# This is not great though, as other gems may (following the instructions at
+# http://reality.hk/posts/2012/05/22/create-gems-for-rubymotion/) also call
+# setup...
+#
+# For sanity reasons, we therefore delete teacup requires from the load order
+# and re-add them to the front every single time {setup} is called.
+#
+# TODO: We should send a patch to rubymotion that adds first-class support for
+# app.gems. These could then be required *after* the user has finished running
+# the setup block, so that they can just run setup properly.
+#
+class << Motion::Project::App
+
+  def setup_with_teacup
+    setup_without_teacup do |app|
+      yield app
+
+      dirs = %w(teacup teacup/core_extensions)
+      files = dirs.map{ |dir| Dir.glob("#{File.dirname(__FILE__)}/#{dir}/*.rb") }.flatten
+      app.files = files + (app.files - files)
+    end
+  end
+
+  alias setup_without_teacup setup
+  alias setup setup_with_teacup
+end

data/lib/teacup/contributors.rb

@@ -0,0 +1,7 @@
+module Teacup
+
+  # If you've made a contribution, add your name here in :' ... ' as a constant symbol.
+  # Please place names in aphabetical order.
+  CONTRIBUTORS = ['Chris Clarke', 'Colin Thomas-Arnold', 'Conrad Irwin', 'Roland Oth', 'Vladimir Pouzanov']
+
+end

data/lib/teacup/core_extensions/ui_view.rb

@@ -0,0 +1,4 @@
+class UIView
+  include Teacup::Layout
+  include Teacup::View
+end

data/lib/teacup/core_extensions/ui_view_controller.rb

@@ -0,0 +1,62 @@
+class UIViewController
+  include Teacup::Layout
+
+  class << self
+    # 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 his 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, xjad: "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, properties={}, &block)
+      @layout_definition = [stylename, properties, block]
+    end
+
+    # Retreive the layout defined by {layout}
+    def layout_definition
+      @layout_definition
+    end
+  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 self.class.layout_definition
+      name, properties, block = self.class.layout_definition
+      layout(view, name, properties, &block)
+    end
+
+    layoutDidLoad
+  end
+
+  def layoutDidLoad; true; end
+end

data/lib/teacup/layout.rb

@@ -0,0 +1,207 @@
+module Teacup
+  # Teacup::Layout defines a layout function that can be used to configure the
+  # layout of views in your application.
+  #
+  # It is included into UIView and UIViewController directly so these functions
+  # should be available when 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.
+  #
+  # @example
+  #   class MyViewController < UIViewController
+  #     interface(:my_view) do
+  #       layout UIImage, :logo
+  #     end
+  #  
+  #     def stylesheet
+  #       Teacup::Stylesheet::Logo
+  #     end
+  #   end
+  #
+  module Layout
+
+    # Alter the layout of a view
+    #
+    # @param instance           The first parameter is the view that you want to
+    #                           layout.
+    #
+    # @param 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.
+    #
+    # @param properties         The third parameter is optional, and is a Hash
+    #                           of properties to apply to the view directly.
+    #
+    # @param &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.
+    #
+    # For example, to alter the width and height of a carousel:
+    #
+    # @example
+    #   layout(carousel, width: 500, height: 100)
+    #
+    # Or to layout the carousel in the default style:
+    #
+    # @example
+    #   layout(carousel, :default_carousel)
+    #
+    # You can also use this method with {subview}, for example to add a new
+    # image to a carousel:
+    #
+    # @example
+    #   layout(carousel) {
+    #     subview(UIImage, backgroundColor: UIColor.colorWithImagePattern(image)
+    #   }
+    #
+    def layout(instance, name_or_properties, properties_or_nil=nil, &block)
+      if properties_or_nil
+        name = name_or_properties.to_sym
+        properties = properties_or_nil
+      elsif Hash === name_or_properties
+        name = nil
+        properties = name_or_properties
+      else
+        name = name_or_properties.to_sym
+        properties = nil
+      end
+
+      instance.stylesheet = stylesheet
+      instance.style(properties) if properties
+      instance.stylename = name if name
+
+      begin
+        superview_chain << instance
+        instance_exec(instance, &block) if block_given?
+      ensure
+        superview_chain.pop
+      end
+
+      instance
+    end
+
+    # 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.
+    #
+    # @param 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}.
+    #
+    # @param *args              Arguments to pass to {layout} to instruct teacup how to
+    #                           lay out the newly added subview.
+    #
+    # @param &block             A block to execute with the current view context set to
+    #                           your new element, see {layout} for more details.
+    #
+    # @return instance          The instance that was added to the view heirarchy.
+    #
+    # For example, to specify that a controller should contain some labels:
+    #
+    # @example
+    #   MyViewController < UIViewController
+    #     heirarchy(:my_view) do
+    #       subview(UILabel, text: 'Test')
+    #       subview(UILabel, :styled_label)
+    #     end
+    #   end
+    #
+    # If you need to add a new image at runtime, you can also do that:
+    #
+    # @example
+    #   layout(carousel) {
+    #     subview(UIImage, backgroundColor: UIColor.colorWithImagePattern(image)
+    #   }
+    #
+    def subview(class_or_instance, *args, &block)
+      instance = Class === class_or_instance ? class_or_instance.new : class_or_instance
+
+      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
+
+    # Returns a stylesheet to use to style the contents of this controller's
+    # view.
+    #
+    # 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
+      nil
+    end
+
+    # Instruct teacup to reapply styles to your subviews
+    #
+    # You should call this whenever the return value of your stylesheet meethod
+    # would change,
+    #
+    # @example
+    #   def willRotateToInterfaceOrientation(io, duration: duration)
+    #     restyle!
+    #   end
+    def restyle!
+      top_level_view.stylesheet = stylesheet
+    end
+
+    protected
+
+    # Get's the top-level UIView for this object.
+    #
+    # This can either be 'self' if the current object is in fact a UIView,
+    # or 'view' if it's a controller.
+    #
+    # @return UIView
+    def top_level_view
+      case self
+      when UIViewController
+        view
+      when UIView
+        self
+      end
+    end
+
+    # Get's the current stack of views in nested calls to layout.
+    #
+    # The view at the end of the stack is the one into which subviews
+    # are currently being attached.
+    def superview_chain
+      @superview_chain ||= []
+    end
+  end
+end