teacup 0.0.1.pre → 0.3.1

data/.gitignore

@@ -1,3 +1,5 @@
-.DS_Store
-.rspec
-.sass-cache/
+.repl_history
+build
+resources/*.nib
+resources/*.momd
+resources/*.storyboardc

data/CHANGES.md

@@ -0,0 +1,26 @@
+v0.2.0
+------
+
+- Stylesheets are no longer constants. Instead, they can be fetched by name: `Teacup::Stylesheet[:iphone]`
+- Stylesheets can be assigned by calling the `stylesheet :stylesheet_name` inside a view controller.
+- Ability to style based on view class.
+- Support for orientation-based styles.
+
+
+v0.1.0
+------
+
+Working code!  Uses finalized proposal, but changes are still happenin'.
+
+v0.0.0
+------
+
+Proposals.  They have been merged into a finalized proposal, based mostly on
+ConradIrwin's stylesheets and a declaritive layout DSL that emerged from
+discussions
+
+embryo
+------
+
+It will be known as "teacup".
+

data/Gemfile

@@ -1,3 +1,5 @@
 source :rubygems
 
+gem 'teacup', :path => '.'
+
 gemspec

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    teacup (0.0.1)
+    teacup (0.3.0)
       rake
 
 GEM

data/LICENSE

@@ -0,0 +1,26 @@
+Copyright (c) 2012, rubymotion community
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+The views and conclusions contained in the software and documentation are those
+of the authors and should not be interpreted as representing official policies,
+either expressed or implied, of the Teacup Project.

data/README.md

@@ -3,55 +3,81 @@ 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.
+Using teacup, you can easily create and style layouts while keeping your code
+dry.  The goal is to offer a rubyesque (well, actually a rubymotion-esque) way
+to create interfaces programmatically.
 
-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.
+**Check out a working sample app [here][Hai]!**
 
-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)!**
+[Hai]: https://github.com/rubymotion/teacup/tree/master/samples/Hai
 
 #### Installation
 
+First get the teacup library into your local project using git submodules:
+
 ```bash
-$ git submodule add https://github.com:rubymotion/teacup vendor/teacup
+$ 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
+```
+  Motion::Project::App.setup do |app|
+    # ...
+    app.files.unshift(*Dir['vendor/teacup/lib/**/*.rb'])
+  end
 ```
 
+You can run the test suite or compile the test app:
+
+```bash
+$ cd vendor/teacup
+$ rake spec  # or just rake, to run the app.
+```
 
 #### Showdown
 
-Regular
+Cocoa
 
 ```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
+
+  def viewDidLoad
+
+    @field = UITextField.new
+    @field.frame = [[10, 10], [200, 50]]
+    @search.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)
+
+    true
+  end
+
+  # code to enable orientation changes
+  def shouldAutorotateToInterfaceOrientation(orientation)
+    if orientation == UIDeviceOrientationPortraitUpsideDown
+      return false
+    end
+    true
+  end
+
+  # perform the frame changes depending on orientation
+  def willAnimateRotationToInterfaceOrientation(orientation, duration:duration)
+    case orientation
+    when UIDeviceOrientationLandscapeLeft, UIDeviceOrientationLandscapeRight
+      @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
 ```
 
@@ -60,92 +86,354 @@ Teacup
 ```ruby
 # Stylesheet
 
-Teacup::StyleSheet.new(:IPhone) do
- 
- style :field,
-  height: 50,
-  width:  200
-  
- style :search, extends: :field,
-  placeholder: 'Foo...'
- 
+Teacup::Stylesheet.new(:some_view) do
+
+  style :root,
+    landscape: true  # enable landscape rotation (otherwise only portrait is enabled)
+                     # 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
 
 # Controller
 
 class SomeController < UIViewController
- 
- def viewDidLoad
-  view.addSubview(Teacup.style(:field, UITextField.new))
-  view.addSubview(Teacup.style(:search))
-  true
- end
- 
+
+  # the stylesheet determines the placement and design of your views.  You can
+  # also implement a stylesheet method, or assign the stylesheet name to the
+  # UIViewController later.
+  stylesheet :some_view
+
+  # think of this as a nib file that you are declaring in your UIViewController.
+  # it is styled according to the :root styles, and can add and style subviews
+  layout :root do
+    subview(UITextField, :field)
+    @search = subview(UITextField, :search)
+  end
+
+  # you have to enable the auto-rotation stuff by implementing a
+  # shouldAutorotateToInterfaceOrientation method
+  def shouldAutorotateToInterfaceOrientation(orientation)
+    # but don't worry, we made that painless, too!
+    autorotateToOrientation(orientation)
+  end
+
+end
+```
+
+The orientation styling is really neat.  I think you'll find that you will be
+more inspired to enable multiple orientations because the code is so much more
+painless.
+
+Stylesheets
+-----------
+
+The basic format for a `style` is a name and a dictionary of "styles".  These
+are usually just methods that get called on the target (a `UIView` or `CALayer`,
+most likely), but they can also perform introspection, using "handlers".
+
+Basics
+======
+
+Create a stylesheet in any code file, usually `styles.rb` or `styles/main.rb`,
+if you have a ton of 'em.  The `Teacup::Stylesheet` constructor accepts a
+stylesheet name and a block, which will contain your style declarations.
+
+```ruby
+Teacup::Stylesheet.new :main_menu do
+  style :ready_to_play_button,
+    backgroundColor: UIColor.blackColor,
+    frame: [[20, 300], [50, 20]]  # [[x, y], [w, h]]
 end
 ```
 
+Any method that accepts a single value can be assigned here.  Please don't abuse
+this by hiding application logic in your stylesheets - these are meant for
+*design*, not behavior.  That said, if you're coding by yourself - go for it! ;)
+
+Orientations
+============
+
+Teacup stylesheets can be given orientation hashes.  The supported orientations
+are:
+
+- `portrait` - upright or upside down
+- `upside_up`
+- `upside_down`
+- `landscape` - on either side
+- `landscape_left` - "left" refers to the home button, e.g. the button is on the left.
+- `landscape_right` - home button is on the right
+
+An example should suffice:
+
+```ruby
+style :ready_to_play_button,
+  portrait: {
+    frame: [[20, 300], [50, 20]]
+  },
+  landscape: {
+    frame: [[60, 300], [50, 20]]  # button moves over 40 pixels because of the wider screen
+  }
+```
+
+That code is repetive, though, let's shorten it up by using precedence and some
+aliases for setting the `frame`:
+
+```ruby
+style :ready_to_play_button,
+  top: 300,
+  width: 50,
+  height: 20,
+  portrait: {
+    left: 20
+  },
+  landscape: {
+    left: 60
+  }
+```
+
+Styles declared in an orientation hash will override the "generic" styles
+declared directly above it, so the above could also be written as:
+
+```ruby
+style :ready_to_play_button,
+  top: 300,
+  width: 50,
+  height: 20,
+  left: 20
+  landscape: {
+    left: 60  #  overrides left: 20
+  }
+```
+
+Handlers
+========
+
+Above, we saw that we can assign `view.frame.x` by using the `left` property.
+There *is* no `UIView#left` method, so this must be handled somewhere special...
+
+Not **that** special, it turns out.  This used to be an internal translation,
+but the list of "translations" was getting out of hand, and we realized that we
+could break this out into a new feature.  **Handlers**.  Here is the `handler`
+for the `left` property:
+
+```ruby
+Teacup.handler UIView, :left { |view, x|
+  f = view.frame
+  f.origin.x = x
+  view.frame = f
+}
+```
+
+How about setting the title of a `UIButton`?
+
+```ruby
+Teacup.handler UIButton, :title { |view, title|
+  target.setTitle(title, forState: UIControlStateNormal)
+}
+```
+
+You can also make aliases for long method names, or to shorten a style you use a
+lot.  You can alias two ways - give multiple names in a `Teacup.handler` method,
+or use `Teacup.alias`.
+
+```ruby
+# the actual `left` handler offers an alias `x`
+Teacup, handler UIView, :left, :x { |view, x|
+  f = view.frame
+  f.origin.x = x
+  view.frame = f
+}
+
+# but I speak japanese, and I want it to be called "hidari" instead, and I want
+# top to be "ue".
+Teacup.alias UIView, :hidari => :left, :ue => :top
+```
+
+extends:
+=======
+
+You might have a view where all the buttons or text fields have similar colors
+or font.  You can have them extend a common style declaration.
+
+```ruby
+style :button,
+  font: UIFont.systemFontOfSize(20)
+
+style :ok_button, extends: :button,
+  title: "OK"
+
+style :cancel_button, extends: :button,
+  title: "Cancel"
+```
+
+Precedence is important.  We said that "orientation" overrides "generic", but
+that is only at the local `style` declaration level.  If you declare a property
+in `style` that is set in an orientation hash in an extended style, *your*
+property will win.
+
+```ruby
+style :button,
+  portrait: {
+    width: 40
+  },
+  landscape: {
+    width: 45
+  }
+
+style :ok_button, extends: :button,
+  title: "OK",
+  width: 40  # width will always be 40, even in landscape
+
+style :cancel_button, extends: :button,
+  title: "Cancel"
+  # width will be 40 or 45, depending on orientation
+```
+
+import
+======
+
+Each `UIView` or `UIViewController` can have only one stylesheet attached to it.
+If you want to break up a stylesheet into multiple sheets, you will use `import`
+to do it.
+
+```ruby
+Teacup::Stylesheet.new :base do
+  style :button,
+    font: UIFont.systemFontOfSize(20)
+end
+
+Teacup::Stylesheet.new :main do
+  import :base
+
+  style :ok_button, extends: :button,
+    top: 10
+end
+
+Teacup::Stylesheet.new :register do
+  import :base
+
+  style :submit_button, extends: :button,
+    top: 50
+end
+```
+
+UIView classes
+==============
+
+You can style entire classes of `UIView`s!  These get merged in last (lowest
+precedence), but they are a great way to get site-wide styles.  Put these in a
+base stylesheet, and import that stylesheet everywhere.  The Apple
+`UIAppearance` protocol/classes do this same thing, but in much more code ;-)
+
+```ruby
+Teacup::Stylesheet.new :base do
+  style UIButton,
+    font: UIFont.systemFontOfSize(20)
+end
+
+Teacup::Stylesheet.new :main do
+  style :ok_button,  # no need to use extends
+    top: 10
+end
+
+Teacup::Stylesheet.new :register do
+  style :submit_button,  # no need to use extends
+    top: 50
+end
+```
+
+Precedence, and Style
+==========
+
+1. Within a `style` declaration, orientation-specific properties override generic properties
+2. Imported properties will be merged in, but no values from (1) will be overridden
+3. Extended styles will be merged in, but no values from (1) or (2) will be overridden
+4. Styles applied to an ancestor will be merged in, but no values from (1) or (2) or (3) will be overridden
+
+These rules are maintained in the `Style` class.  It starts by creating a Hash
+based on the `style` declaration, then merges the orientation styles, if
+applicable (orientation styles override).  Next it merges imports, then
+extends, and finally the class ancestors.  At each "merge" except orientation
+merges, it is a recursive-soft-merge, meaning that Hashes will be merged, but
+existing keys will be left alone.
+
+Unless you are going to be hacking on teacup, you do not need to understand the
+nitty-gritty - just remember the precedence rules.
+
 Development
 -----------
 
-*Current version*: v0.0.0 (or see `lib/teacup/version.rb`)
+*Current version*: v0.2.0 (or see `lib/teacup/version.rb`)
+
+*Last milestone*: Release layout and stylesheet DSL to the world.
+
+*Next milestone*: Provide default styles, that mimic Interface Builder's object library
 
-*Last milestone*: Pick a name
+**Changelog v0.2.0:**
+
+- Stylesheets are no longer constants. Instead, they can be fetched by name: `Teacup::Stylesheet[:iphone]`
+- Stylesheets can be assigned by calling the `stylesheet :stylesheet_name` inside a view controller.
+- Ability to style based on view class.
+- Support for orientation-based styles.
 
-*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.
+coding.  We will announce when we are in "proposal mode".  That's a good time to
+jump into the project and offer suggestions for its future.
+
+And we're usually hanging out over at the `#teacuprb` channel on `irc.freenode.org`.
+
+The Dummy
+---------
 
-We would love suggestions of any sort, and we're always free over at the `#teacuprb` channel on `irc.freenode.org`.
+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.
 
-Ideas that proposals should keep in mind
-----------------------------------------
+You 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.
 
-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
+Example
+=======
 
-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))
+The error above was from trying to style the
+`UIActivityIndicatorView#hidesWhenStopped` property.  Make a new `Dummy` class,
+subclass the class *where the method is defined* (not a subclass, please) and
+add that method to a `dummy` method.  You should assign it `nil` so that the
+method signature looks right.  And you should mark it private, too.
 
-[iOS HIG]: http://developer.apple.com/library/ios/#DOCUMENTATION/UserExperience/Conceptual/MobileHIG/Introduction/Introduction.html
+```ruby
+class DummyActivityIndicatorView < UIActivityIndicatorView
+private
+  def dummy
+    setHidesWhenStopped(nil)
+  end
+end
+```
 
 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
+Please report any bugs you find with our source at the
+[Issues](https://github.com/rubymotion/teacup/issues) page.

data/Rakefile

@@ -1,39 +1,11 @@
-#!/usr/bin/env rake
+$:.unshift('/Library/RubyMotion/lib')
+require 'motion/project'
+require 'bundler'
+Bundler.require
 
-# 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
+Motion::Project::App.setup do |app|
+  # Use `rake config' to see complete project settings.
+  app.name = 'teacup'
+  app.identifier = 'com.rubymotion.teacup'
 end

data/app/app_delegate.rb

@@ -0,0 +1,14 @@
+class AppDelegate
+
+  def application(application, didFinishLaunchingWithOptions:launchOptions)
+    application.setStatusBarStyle(UIStatusBarStyleBlackTranslucent)
+
+    @window = UIWindow.alloc.initWithFrame(UIScreen.mainScreen.bounds)
+    @window.rootViewController = FirstController.new
+    @window.rootViewController.wantsFullScreenLayout = true
+    @window.makeKeyAndVisible
+
+    true
+  end
+
+end