teacup 2.0.0 → 2.0.2

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    teacup (2.0.0)
+    teacup (2.0.2)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,7 +1,7 @@
 Teacup
 ======
 
-A community-driven DSL for creating user interfaces on iOS.
+A community-driven DSL for creating user interfaces on iOS and OS X.
 
 [![Build Status](https://travis-ci.org/rubymotion/teacup.png)](https://travis-ci.org/rubymotion/teacup)
 
@@ -11,13 +11,20 @@ interfaces programmatically.
 
 **Check out some sample apps!**
 
-* “[Hai][Hai]”
-* “[AutoLayout][AutoLayout]”
-* “[OnePage][OnePage]”
+* iOS
+  * “[Hai][Hai]”
+  * “[AutoLayout][AutoLayout]”
+  * “[OnePage][OnePage]”
+* OS X
+  * “[Tweets][Tweets]” - ported from [RubyMotionSamples][]
+  * “[teacup-osx][teacup-osx]”
 
 [Hai]: https://github.com/rubymotion/teacup/tree/master/samples/Hai
 [AutoLayout]: https://github.com/rubymotion/teacup/tree/master/samples/AutoLayout
 [OnePage]: https://github.com/rubymotion/teacup/tree/master/samples/OnePage
+[Tweets]: https://github.com/rubymotion/teacup/tree/master/samples/Tweets
+[teacup-osx]: https://github.com/rubymotion/teacup/tree/master/samples/teacup-osx
+[RubyMotionSamples]: https://github.com/HipByte/RubyMotionSamples/tree/master/osx/Tweets
 
 **Quick Install**
 
@@ -29,7 +36,7 @@ and in your Rakefile
 require 'teacup'
 ```
 
-#### 10 second primer
+#### 10 second primer, iOS
 
 1.  Create a `UIViewController` subclass:
 
@@ -63,17 +70,54 @@ require 'teacup'
     end
     ```
 
+#### 10 second primer, OS X
+
+Pretty much the same!
+
+**You should use the `TeacupWindowController` parent class instead of `NSWindowController`**
+
+1.  Create a `TeacupWindowController` subclass.
+
+    ```ruby
+    class MyController < TeacupWindowController
+    ```
+2.  Assign a stylesheet name:
+
+    ```ruby
+    class MyController < TeacupWindowController
+      stylesheet :main_window
+    ```
+3.  Create a layout:
+
+    ```ruby
+    class MyController < TeacupWindowController
+      stylesheet :main_window
+
+      layout do
+        subview(NSButton, :hi_button)
+      end
+    end
+    ```
+4.  Create the stylesheet (in `app/styles/` or somewhere near the controller)
+
+    ```ruby
+    Teacup::Stylesheet.new :main_window do
+      style :hi_button,
+        origin: [10, 10],
+        title: 'Hi!'
+    end
+    ```
 
 Teacup
 ------
 
-Teacup's goal is to facilitate the creation and styling of your `UIViews`
-hierarchy. Say "Goodbye!" to Xcode & XIB files!
+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 `UIViews` and to organize them in a hierarchy.  You assign the
+  A DSL to create Views and to organize them in a hierarchy.  You assign the
   style name and style classes from these methods.
 
 - Stylesheets
@@ -94,19 +138,19 @@ constraints.  Teacup can also integrate with the [motion-layout][] gem!
   * [Extending Styles](#extending-styles)
   * [Style via UIView Class](#style-via-uiview-class)
   * [Importing stylesheets](#importing-stylesheets)
-  * [Style via UIAppearance](#style-via-uiappearance)
+  * [Style via UIAppearance](#style-via-uiappearance) (iOS only)
 * [More Teacup features](#more-teacup-features)
   * [Styling View Properties](#styling-view-properties)
-  * [Orientation Styles](#orientation-styles)
-  * [UIView animation additions](#uiview-animation-additions)
+  * [Orientation Styles](#orientation-styles) (iOS only)
+  * [Animation additions](#animation-additions)
   * [Style Handlers](#style-handlers)
   * [Frame Calculations](#frame-calculations)
   * [Auto-Layout](#auto-layout)
   * [Motion-Layout](#motion-layout)
   * [Stylesheet extensions](#stylesheet-extensions)
     * [Autoresizing Masks](#autoresizing-masks)
-    * [Device detection](#device-detection)
-    * [Rotation helpers](#rotation-helpers)
+    * [Device detection](#device-detection) (iOS only)
+    * [Rotation helpers](#rotation-helpers) (iOS only)
 * [Showdown](#showdown)
 * [The Nitty Gritty](#the-nitty-gritty)
 * [Advanced Teacup Tricks](#advanced-teacup-tricks)
@@ -118,12 +162,14 @@ constraints.  Teacup can also integrate with the [motion-layout][] gem!
 Layouts
 -------
 
-The `Teacup::Layout` module is mixed into `UIViewController` and `UIView` so
-that these two classes can take advantage of the view-hierarchy DSL.
+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` class method
-`layout`.  This is a helper function that stores the layout code.  A more direct
-example might look like this:
+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:
 
 ```ruby
 # controller example
@@ -141,12 +187,12 @@ class MyController < UIViewController
 end
 ```
 
-You can use very similar code in your `UIView` subclasses.
+You can use very similar code in your view subclasses.
 
 ```ruby
 # view example
 #
-# if you use teacup in all your projects, you can bundle your custom views with
+# if you use Teacup in all your projects, you can bundle your custom views with
 # their own stylesheets
 def MyView < UIView
 
@@ -162,10 +208,10 @@ end
 
 The `layout` and `subview` methods are the work horses of the Teacup view DSL.
 
-* `layout(uiview|UIViewClass, stylename, style_classes, additional_styles, &block)`
-  - `uiview|UIViewClass` - You can layout an existing class or you can have
-    teacup create it for you (it just calls `new` on the class, nothing
-    special).  This argument is required.
+* `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 calls `new` on the class, nothing special).  This
+    argument is required.
   - `stylename` (`Symbol`) - This is the name of a style in your stylesheet. It
     is optional
   - `style_classes` (`[Symbol,...]`) - Other stylenames, they have lower
@@ -174,10 +220,10 @@ The `layout` and `subview` methods are the work horses of the Teacup view DSL.
     either to override or augment the settings from the `Stylesheet`.  It is
     common to use this feature to assign the `delegate` or `dataSource`.
   - `&block` - See discussion below
-  - Returns the `uiview` that was created or passed to `layout`.
-  - only the `uiview` arg is required.  You can pass any combination of
+  - Returns the `view` that was created or passed to `layout`.
+  - only the `view` arg is required.  You can pass any combination of
     stylename, style_classes, and additional_styles (some, none, or all).
-* `subview(uiview|UIViewClass, stylename, style_classes, additional_styles, &block)`
+* `subview(view|UIViewClass, stylename, style_classes, additional_styles, &block)`
   - Identical to `layout`, but adds the view to the current target
 
 The reason it is so easy to define view hierarchies in Teacup is because the
@@ -198,8 +244,9 @@ 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?).
 
 ```ruby
-# the methods you add here will be available in UIView, UIViewController, and
-# any of your own classes that `include Teacup::Layout`
+# 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
@@ -246,12 +293,15 @@ class MyController < UIViewController
 end
 ```
 
-The `UIViewController##layout` method that has been used so far is going to be
+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
 
 ```ruby
+# 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)
 ```
 
 * `stylename` is the stylename you want applied to your controller's `self.view`
@@ -422,12 +472,12 @@ Teacup::Stylesheet.new :main do
 end
 ```
 
-### Style via UIView Class
+### Style via View Class
 
-If you need to apply styles to *all* instances of a `UIView` 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!).
+If 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!).
 
 ```ruby
 Teacup::Stylesheet.new :app do
@@ -477,6 +527,8 @@ end
 
 ### Style via UIAppearance
 
+*iOS 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
@@ -526,9 +578,9 @@ 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` has 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.
+`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.
 
 ```ruby
 # Custom Navigation Title created and styled by Teacup
@@ -566,7 +618,7 @@ discussion:
 
 - Styling View Properties
 - Orientation Styles
-- UIView Additions
+- View Class Additions
 - Style Handlers
 - Frame Calculations
 - Auto-Layout & [Motion-Layout][motion-layout]
@@ -595,6 +647,8 @@ style :tablecell,
 
 ### Orientation Styles
 
+*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.
@@ -617,7 +671,7 @@ end
 Combine these styles with [Frame Calculations][calculations] to have you view
 frame recalculated automatically.
 
-### UIView animation additions
+### Animation additions
 
 We've already seen the Teacup related properties:
 
@@ -632,6 +686,9 @@ animations.
 - `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".
+
 ### Style Handlers
 
 *This feature is used extensively by [sweettea][] to make a more intuitive
@@ -671,6 +728,8 @@ style :container,
   frame: :full  # => [[0, 0], superview.frame.size]
 ```
 
+[other-handlers]: https://github.com/rubymotion/teacup/tree/master/lib/teacup/z_core_extensions/z_handlers.rb
+
 ### Frame Calculations
 
 *These are super cool, just don't forget your autoresizingMasks*
@@ -811,11 +870,14 @@ 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.
 
-### Motion-Layout[motion-layout]
+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.
+
+### Motion-Layout
 
-If you are using [Nick Quaranto][qrush]'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
+If you are using [Nick Quaranto][qrush]'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.
 
 ```ruby
@@ -887,13 +949,18 @@ The `fixed` methods pin the view to one of nine locations:
     ------------+---------------+-------------
     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
 
 #### Device detection
 
+*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.
@@ -931,6 +998,8 @@ end
 
 #### Rotation helpers
 
+*iOS 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.
@@ -1370,7 +1439,6 @@ tool helps you build great apps!
 [advanced]: https://github.com/rubymotion/teacup/#advanced-teacup-tricks
 [calculations]: https://github.com/rubymotion/teacup/#frame-calculations
 [dummy.rb]: https://github.com/rubymotion/teacup/tree/master/lib/dummy.rb
-[other-handlers]: https://github.com/rubymotion/teacup/tree/master/lib/teacup/z_core_extensions/z_handlers.rb
 
 [Pixate]: http://www.pixate.com
 [NUI]: https://github.com/tombenner/nui

data/lib/teacup/version.rb

@@ -1,5 +1,5 @@
 module Teacup
 
-  VERSION = '2.0.0'
+  VERSION = '2.0.2'
 
 end

data/lib/teacup-osx/core_extensions/z_core_extensions.rb

@@ -0,0 +1,131 @@
+##|
+##|  NSView.frame
+##|
+Teacup.handler NSView, :left, :x do |target, x|
+  f = target.frame
+  f.origin.x = Teacup::calculate(target, :width, x)
+  target.frame = f
+end
+
+Teacup.handler NSView, :right do |target, r|
+  f = target.frame
+  f.origin.x = Teacup::calculate(target, :width, r) - f.size.width
+  target.frame = f
+end
+
+Teacup.handler NSView, :center_x, :middle_x do |target, x|
+  c = target.center
+  c.x = Teacup::calculate(target, :width, x)
+  target.center = c
+end
+
+Teacup.handler NSView, :top, :y do |target, y|
+  f = target.frame
+  f.origin.y = Teacup::calculate(target, :height, y)
+  target.frame = f
+end
+
+Teacup.handler NSView, :bottom do |target, b|
+  f = target.frame
+  f.origin.y = Teacup::calculate(target, :height, b) - f.size.height
+  target.frame = f
+end
+
+Teacup.handler NSView, :center_y, :middle_y do |target, y|
+  c = target.center
+  c.y = Teacup::calculate(target, :height, y)
+  target.center = c
+end
+
+Teacup.handler NSView, :width do |target, w|
+  f = target.frame
+  f.size.width = Teacup::calculate(target, :width, w)
+  target.frame = f
+end
+
+Teacup.handler NSView, :height do |target, h|
+  f = target.frame
+  f.size.height = Teacup::calculate(target, :height, h)
+  target.frame = f
+end
+
+Teacup.handler NSView, :size do |target, size|
+  f = target.frame
+  size_x = Teacup::calculate(target, :width, size[0])
+  size_y = Teacup::calculate(target, :height, size[1])
+  f.size = [size_x, size_y]
+  target.frame = f
+end
+
+Teacup.handler NSView, :origin do |target, origin|
+  f = target.frame
+  origin_x = Teacup::calculate(target, :width, origin[0])
+  origin_y = Teacup::calculate(target, :height, origin[1])
+  f.origin = [origin_x, origin_y]
+  target.frame = f
+end
+
+Teacup.handler NSView, :center do |target, center|
+  center_x = Teacup::calculate(target, :width, center[0])
+  center_y = Teacup::calculate(target, :height, center[1])
+  target.center = [center_x, center_y]
+end
+
+Teacup.handler NSView, :size do |target, size|
+  # odd... if I changed these to .is_a?, weird errors happen.  Use ===
+  if Symbol === size && size == :full
+    if target.superview
+      size = target.superview.bounds.size
+    else
+      size = target.frame.size
+    end
+  elsif Array === size
+    size = [Teacup::calculate(target, :width, size[0]), Teacup::calculate(target, :height, size[1])]
+  end
+  f = target.frame
+  f.size = size
+  target.frame = f
+end
+
+Teacup.handler NSView, :frame do |target, frame|
+  # odd... if I changed these to .is_a?, weird errors happen.  Use ===
+  if Symbol === frame && frame == :full
+    if target.superview
+      frame = target.superview.bounds
+    else
+      frame = target.frame
+    end
+  elsif Array === frame && frame.length == 4
+    frame = [
+        [Teacup::calculate(target, :width, frame[0]), Teacup::calculate(target, :height, frame[1])],
+        [Teacup::calculate(target, :width, frame[2]), Teacup::calculate(target, :height, frame[3])]
+      ]
+  elsif (Array === frame && frame.length == 2) || CGRect === frame
+    frame = [
+        [Teacup::calculate(target, :width, frame[0][0]), Teacup::calculate(target, :height, frame[0][1])],
+        [Teacup::calculate(target, :width, frame[1][0]), Teacup::calculate(target, :height, frame[1][1])]
+      ]
+  end
+  target.frame = frame
+end
+
+Teacup.handler NSView, :gradient do |target, gradient|
+  gradient_layer = target.instance_variable_get(:@teacup_gradient_layer) || begin
+    gradient_layer = CAGradientLayer.layer
+    gradient_layer.frame = target.bounds
+    target.layer.insertSublayer(gradient_layer, atIndex:0)
+    gradient_layer
+  end
+
+  gradient.each do |key, value|
+    case key.to_s
+    when 'colors'
+      colors = [value].flatten.collect { |color| color.is_a?(UIColor) ? color.CGColor : color }
+      gradient_layer.colors = colors
+    else
+      gradient_layer.send("#{key}=", value)
+    end
+  end
+
+  target.instance_variable_set(:@teacup_gradient_layer, gradient_layer)
+end

data/lib/teacup-osx/style.rb

@@ -1,43 +1,22 @@
 module Teacup
   # The Style class is where the precedence rules are applied.  A Style can
   # query the Stylesheet that created it to look up other styles (for
-  # `extends:`) and to import other Stylesheets.  If it is handed a target (e.g.
-  # a `UIView` instance) and orientation, it will merge those in appropriately
-  # as well.
+  # `extends:`) and to import other Stylesheets.
   class Style < Hash
     attr_accessor :stylename
     attr_accessor :stylesheet
 
-    # A hash of orientation => true/false.  true means the orientation is
-    # supported.
-    def supports
-      @supports ||= {}
-    end
-
-    # returns the value - `nil` has special meaning when querying :portrait or :upside_up
-    def supports? orientation_key
-      false
-    end
-
+    # orientation is completely ignored on OS X, but the Teacup code was written
+    # to support them, and it was easier to ignore the orientation system than
+    # refactor it out of the shared code base.
     def build(target=nil, rotation_orientation=nil, seen={})
       properties = Style.new
       properties.stylename = self.stylename
       properties.stylesheet = self.stylesheet
 
-      # if we have an orientation, only apply those styles.  otherwise apply the
-      # entire style, including the current orientation.
-      if rotation_orientation
-        # in order to preserve the "local-first" override, we need to *delete*
-        # the keys in imported_stylesheets and extended_properties that are
-        # present in this style - even though we don't ultimately *apply* the
-        # styles
-        delete_keys = self.keys
-        orientation = rotation_orientation
-      else
-        delete_keys = []
-        properties.update(self)
-        orientation = nil
-      end
+      delete_keys = []
+      properties.update(self)
+      orientation = nil
 
       # now we can merge extends, and imported_stylesheets.  before merging,
       # these will go through the same process that we just finished on the

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: teacup
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-09 00:00:00.000000000 Z
+date: 2013-05-13 00:00:00.000000000 Z
 dependencies: []
 description: ! 'Teacup is a community-driven DSL for making CSS-like styling, and
   layouts for
@@ -62,6 +62,7 @@ files:
 - lib/teacup-osx/core_extensions/ns_window.rb
 - lib/teacup-osx/core_extensions/ns_window_controller.rb
 - lib/teacup-osx/core_extensions/teacup_handlers.rb
+- lib/teacup-osx/core_extensions/z_core_extensions.rb
 - lib/teacup-osx/dummy.rb
 - lib/teacup-osx/handler.rb
 - lib/teacup-osx/style.rb