sugarcube 0.11.3 → 0.12

data/.gitignore

@@ -1,3 +1,4 @@
 pkg/
 *.gem
 .DS_Store
+/build/

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown - LICENSE

data/README.md

@@ -1,4 +1,4 @@
-sugarcube
+SugarCube
 =========
 
 Some sugar for your cocoa, or your [tea][sweettea].
@@ -8,14 +8,14 @@ About
 
 CocoaTouch/iOS is a *verbose* framework.  These extensions hope to make
 development in rubymotion more enjoyable by tacking "UI" methods onto the base
-classes (String, Fixnum, Numeric).  With sugarcube, you can create a color from an
+classes (String, Fixnum, Numeric).  With SugarCube, you can create a color from an
 integer or symbol, or create a UIFont or UIImage from a string.
 
 Some UI classes are opened up as well, like adding the '<<' operator to a UIView
 instance, instead of view.addSubview(subview), you can use the more idiomatic:
 view << subview.
 
-The basic idea of sugarcube is to turn some operations on their head.  Insead of
+The basic idea of SugarCube is to turn some operations on their head.  Insead of
 
     UIApplication.sharedApplication.openURL(NSURL.URLWithString(url))
 
@@ -25,7 +25,7 @@ How about:
 
 **DISCLAIMER**
 
-It is possible that you *will not like sugarcube*.  That is perfectly fine!
+It is possible that you *will not like SugarCube*.  That is perfectly fine!
 Some people take milk in their coffee, some take sugar.  Some crazy maniacs
 don't even *drink* coffee, if you can imagine that... All I'm saying is: to each
 their own.  You should checkout [BubbleWrap][] for another take on
@@ -45,11 +45,14 @@ Installation
 
     gem install sugarcube
 
+    # in Rakefile
+    require 'sugarcube'
+
     # or in Gemfile
     gem 'sugarcube'
 
-    # in Rakefile
-    require 'sugarcube'
+    # in terminal
+    $ bundle install
 
 Examples
 ========
@@ -114,7 +117,8 @@ Shorthands and hash-like access to the coder/decoder objects.
 coder['key'] = self.value
 self.value = decoder['key']
 
-# but if you want to store booleans and such in the MOST compact way:
+# but if you want to store booleans and such (in their C form,
+# which will take up less space I suppose):
 coder.set('sugarcube_is_neat', toBool:self.is_sugarcube_neat?)
 self.sugarcube_is_neat = decoder.bool('sugarcube_is_neat')
 
@@ -160,6 +164,11 @@ recurring events)
    ignoring the time components.  `start_of_day` and `end_of_day` methods help
    you here.  They are akin to `floor` and `ceil`, if you consider the time to
    be the "floating" component, and the date to be the nearest "integer".
+4. Formatting is made easier with `NSDate#string_with_style(NSDateStyleConstant or Symbol)`
+   and `NSDate#string_with_format(format_string)`.  See
+   <http://www.unicode.org/reports/tr35/tr35-25.html#Date_Format_Patterns> for
+   the formatters, they take getting used to, coming from `strftime`, but they
+   are much more powerful and locale-aware.
 
 ```
 (main)> now = NSDate.new  # Time.new is the same thing
@@ -358,6 +367,11 @@ This is the "big daddy".  Lots of sugar here...
 :change.uicontrolevent  # => UIControlEventValueChanged
 :all.uicontrolevent  # => UIControlEventAllEvents
 :blue.uicolor  # UIColor.blueColor
+
+# these are really handy for custom buttons - touch_start means the finger is inside the button, touch_stop is outside the button or canceled
+:touch_start  # => UIControlEventTouchDown | UIControlEventTouchDragEnter
+:touch_stop   # => UIControlEventTouchUpInside | UIControlEventTouchCancel | UIControlEventTouchDragExit
+
 # all CSS colors are supported, and alpha
 # (no "grey"s, only "gray"s, consistent with UIKit, which only provides "grayColor")
 :firebrick.uicolor(0.25)  # => 0xb22222.uicolor(0.25)
@@ -385,16 +399,28 @@ image = "my_image".uiimage
 image.uicolor # => UIColor.colorWithPatternImage(image)
 ```
 
-###### Image Manipulation
+###### Image Manipulation - VERY handy!
 
 ```ruby
 image.scale_to [37, 37]
 image.rounded  # default: 5 pt radius
 image.rounded(10)
 
-# these both use UIEdgeInsetsZero (for now)
+image.in_rect([[10, 10], [100, 100]])  # get part of an image
+
+image.darken  # => good for "pressed" buttons
+image.darken(brightness: -0.5, saturation: -0.2)  # these are the defaults
+
+image.rotate(:left)
+image.rotate(:right)
+image.rotate(:flip)  # 180° - if you have a better name, let me know!
+image.rotate(45.degrees)
+
+# default insets are UIEdgeInsetsZero
 image.tileable
+image.tileable(insets)
 image.stretchable
+image.stretchable(insets)
 ```
 
  UIAlertView
@@ -530,7 +556,7 @@ UIActivityIndicatorView.gray
 -----------
 
 Inspired by [BubbleWrap's][BubbleWrap] `when` method, but I prefer jQuery-style
-verbs and sugarcube symbols.
+verbs and SugarCube symbols.
 
 ```ruby
 button = UIButton.alloc.initWithFrame([0, 0, 10, 10])
@@ -715,13 +741,13 @@ date2.same_day? date1
 :key.get_default  # => NSUserDefaults.standardUserDefaults.objectForKey(:key)
 ```
 
-This is strange, and backwards, which is just sugarcube's style.  But there is
+This is strange, and backwards, which is just SugarCube's style.  But there is
 one advantage to doing it this way.  Compare these two snippets:
 
 ```ruby
 # BubbleWrap
 App::Persistance[:test] = { my: 'test' }
-# sugarcube
+# SugarCube
 :test.set_default { my: 'test' }
 # k, BubbleWrap looks better
 
@@ -743,19 +769,26 @@ test[:my] = 'new'
  CoreGraphics
 --------------
 
-###### Is it `CGMakeRect` or `CGRectMake`?
+###### Is it `CGMakeRect` or `CGRectMake`?  What arguments does `CGRect.new` take?
 
-Instead, just use `Rect`, `Size` and `Point`.  They will happily convert most
-sensible arguments into a `Rect/Size/Point`, which can be treated as a `CGRect`
-object OR as an `Array` (woah).
+Instead, just use the coercion methods `Rect()`, `Size()` and `Point()`.  They
+will happily convert most sensible (and some non-sensible) arguments into a
+`CGRect/CGSize/CGPoint` struct.  For more CoreGraphics additions, you should use
+[geomotion][] by [Clay Allsopp][].  It adds methods to `CGRect`, `CGPoint`, and
+`CGSize` to make these structures more rubyesque (these methods used to be part
+of SugarCube, but were removed in an attempt to decrease the amount of
+duplicated code).
 
-These are namespaced in `SugarCube::CoreGraphics` module, but I recommend you
-`include SugarCube::CoreGraphics` in app_delegate.rb.
+[geomotion]: https://github.com/clayallsopp
+[Clay Allsopp]: https://github.com/clayallsopp/geomotion
+
+These are namespaced in the `SugarCube::CoreGraphics` module, but I recommend
+you `include SugarCube::CoreGraphics` in app_delegate.rb.
 
 ```ruby
-f = Rect(view.frame)  # converts a CGRect into a Rect
-o = Point(view.frame.origin)  # converts a CGPoint into a Point
-s = Size(view.frame.size)  # converts a CGSize into a Size
+f = Rect(view.frame)  # the identity function - returns a copy of the CGRect
+o = Point(view.frame.origin)  # returns a copy of CGPoint
+s = Size(view.frame.size)  # returns a copy of CGSize
 
 # lots of other conversions are possible.
 # a UIView or CALayer => view.frame
@@ -763,103 +796,19 @@ f = Rect(view)
 # 4 numbers
 f = Rect(x, y, w, h)
 # or two arrays
+f = Rect([x, y], [w, h])
+# one array
+f = Rect([[x, y], [w, h]])
+f = Rect([x, y, w, h])
+# a CGPoint and CGSize
 p = Point(x, y)  # or just [x, y] works, too
 s = Size(w, h)  # again, [w, h] is fine
 f = Rect(p, s)
-# like I said, a straight-up array of nested arrays is fine, too.
-f = Rect([[x, y], [w, h]])
-```
-
-###### CG{Rect,Point,Size} is a *real boy*!
-
-These methods get defined in a module (`SugarCube::CG{Rect,Size,Point}Extensions`),
-and included in `CGRect` *and* `Rect`.  The idea is that you do not have to
-distinguish between the two objects.
-
-These methods all use the methods as described in [CGGeometry Reference][], e.g.
-`CGRectContainsPoint`, `CGRectIntersectsRect`, etc.
-
-```ruby
-# intersection / contains
-Point(0, 0).intersects?(Rect(-1, -1, 2, 2))  # => true
-# if a Point intersects a Rect, the Rect intersects the Point, right?
-Rect(-1, -1, 2, 2).intersects? Point(0, 0)  # => true
-
-# CGRect and the gang are real Ruby objects.  Let's treat 'em that way!
-view.frame.contains? Point(10, 10)  # in this case, contains? and intersects? are synonyms
-view.frame.intersects? Rect(0, 0, 10, 10)  #  <= but this one
-view.frame.contains? Rect(0, 0, 10, 10)    #  <= and this one are different.
-
-# CGRect has factory methods for CGRectEmpty, CGRectNull, and - KINDA - CGRectInfinite
-# BUT, there is a bug (?) right now where CGRectIsInfinite(CGRectInfinite) returns false.
-# so instead, I've built my own infinite? method that checks for the special "Infinite" value
-> CGRect.infinite
-=> [[0, 0], [Infinity, Infinity]]
-> CGRect.infinite.infinite?
-=> true
-> CGRect.null
-=> [[Infinity, Infinity], [0.0, 0.0]]
-> CGRect.null.null?
-=> true
-> CGRect.empty
-=> [[0.0, 0.0], [0.0, 0.0]]
-> CGRect.empty.empty?
-=> true
-```
-
-A lot of the methods in CGGeometry Reference are available as instance methods
-
-```ruby
-view.frame.left    # => CGRectGetMinX(view.frame)
-view.frame.right   # => CGRectGetMaxX(view.frame)
-view.frame.top     # => CGRectGetMinY(view.frame)
-view.frame.bottom  # => CGRectGetMaxY(view.frame)
-view.frame.width   # => CGRectGetWidth(view.frame)
-view.frame.height  # => CGRectGetHeight(view.frame)
-view.frame.center  # => Point(CGRectGetMidX(view.frame), CGRectGetMidY(view.frame))
-
-view.frame.intersection(another_rect)  # => CGRectIntersection(view.frame, another_rect)
-view.frame + another_rect  # => CGRectUnion(view.frame, another_rect)
-view.frame + a_point  # => CGRectOffset(view.frame, a_point.x, a_point.y)
-view.frame + a_offset  # => CGRectOffset(view.frame, a_offset.horizontal, a_offset.vertical)
-view.frame + edgeinsets  # => UIEdgeInsetsInsetRect(view.frame, edgeinsets)
-view.frame + a_size  # => CGRectInset(view.frame, -a_size.width, -a_size.height)
-# Adding a size to a view keeps the view's CENTER in the same place, but
-# increases its size by `size.width,size.height`. it's the same as using
-# UIEdgeInsets with top == bottom, and left == right
-> Rect(0, 0, 10, 10).center
-=> Point(5.0, 5.0)  # note the center
-> Rect(0, 0, 10, 10) + Size(10, 10)
-=> Rect([-10.0, -10.0],{30.0 × 30.0})  # origin and size changed, but...
-> (Rect(0, 0, 10, 10) + Size(10, 10)).center
-=> Point(5.0, 5.0)
-# See?  It's bigger, but the center hasn't moved.
+# any combination of the two
+f = Rect(p, [w, h])
+f = Rect([x, y], s)
 ```
 
-`to_hash/from_hash`, and notice here that I used `inspect`, to show that it is a
-little more readable.
-
-**NOTE** As of today, Aug. 25, 2012, rubymotion v1.22, the `inspect` method in SugarCube is not
-being called.  I think this is a bug... this worked before!
-
-```ruby
-> Rect(0, 0, 10, 10).to_hash
-=> {"Width"=>10.0, "Height"=>10.0, "Y"=>0.0, "X"=>0.0}
-> puts CGRect.from_hash(Rect(0, 0, 1, 1).to_hash).inspect
-CGRect([0.0, 0.0],{1.0 × 1.0})
-```
-
-`to_s/from_s`, which rely on `NSStringFromCGRect/CGRectFromString` (et. al.)
-
-```ruby
-> Rect(0, 0, 10, 10).to_s
-=> "{{0, 0}, {10, 10}}"
-> puts CGRect.from_s Rect(0, 0, 10, 10).to_s
-{{0, 0}, {10, 10}}
-```
-
-[CGGeometry Reference]: https://developer.apple.com/library/mac/documentation/graphicsimaging/reference/CGGeometry/Reference/reference.html
-
  CoreLocation
 --------------
 
@@ -1126,3 +1075,45 @@ true.blank?     # => false
 ['a'].blank?    # => false
 {a: 'a'}.blank? # => false
 ```
+
+Gestures
+--------
+
+Sugarcube's gesture support is very similar to BubbleWrap's, and it's entirely
+possible that the two will be merged into one thing.  But SugarCube is all about
+extending base classes, whereas BubbleWrap tends to add *new* classes to do the
+heavy lifting.  Plus the options you pass to SugarCube are very different, and
+the prefix is "on" instead of "when" (e.g. "on_pan" instead of "when_panned")
+
+Gestures are an "opt-in" extension.  In your Rakefile, add
+`require 'sugarcube-gestures'`.
+
+```ruby
+require 'sugarcube-gestures'
+
+view.on_pan { |gesture|
+  location = gesture.view.locationInView(view)
+}
+
+# other gesture methods, with common options:
+view.on_tap   # use system defaults
+view.on_tap(1)  # number of taps
+view.on_tap(taps: 1, fingers: 1)  # number of taps and number of fingers
+
+view.on_pinch   # no options
+view.on_rotate  # no options
+
+view.on_swipe   # use system defaults
+view.on_swipe :left
+view.on_swipe(direction: :left, fingers: 1)
+view.on_swipe(direction: UISwipeGestureRecognizerDirectionLeft, fingers: 1)
+
+view.on_pan   # use system defaults
+view.on_pan(2)  # minimum and maximum fingers required
+view.on_pan(fingers: 2)
+view.on_pan(min_fingers: 2, max_fingers: 3)
+
+view.on_press   # use system defaults
+view.on_press(1.5)  # duration
+view.on_press(duration: 1.5, taps: 1, fingers: 1)
+```

data/Rakefile

@@ -1 +1,3 @@
-require 'bundler/gem_tasks'
+$:.unshift('/Library/RubyMotion/lib')
+require 'motion/project'
+require './lib/sugarcube'

data/app/app_delegate.rb

@@ -0,0 +1,4 @@
+include SugarCube::CoreGraphics
+
+class AppDelegate
+end

data/lib/sugarcube-gestures.rb

@@ -0,0 +1,23 @@
+unless defined?(Motion::Project::Config)
+  raise "The sugarcube gem must be required within a RubyMotion project Rakefile."
+end
+
+
+Motion::Project::App.setup do |app|
+  # scans app.files until it finds app/ (the default)
+  # if found, it inserts just before those files, otherwise it will insert to
+  # the end of the list
+  insert_point = 0
+  app.files.each_index do |index|
+    file = app.files[index]
+    if file =~ /^(?:\.\/)?app\//
+      # found app/, so stop looking
+      break
+    end
+    insert_point = index + 1
+  end
+
+  Dir.glob(File.join(File.dirname(__FILE__), 'sugarcube-gestures/**/*.rb')).reverse.each do |file|
+    app.files.insert(insert_point, file)
+  end
+end

data/lib/sugarcube-gestures/gestures.rb

@@ -0,0 +1,134 @@
+# BubbleWrap has these same methods, but the logic and options are a little
+# different. In the spirit of open source, I am blatantly copying their code,
+# changing it to suit my needs, and offering it here
+class UIView
+
+  # a generic gesture adder, but using sugarcube_add_gesture, which handles the block
+  def on_gesture(klass, options={}, &proc)
+    recognizer = klass.alloc.initWithTarget(self, action:'sugarcube_handle_gesture:')
+    options.each do |method, value|
+      recognizer.send(method, value)
+    end
+    sugarcube_add_gesture(proc, recognizer)
+  end
+
+  def on_tap(taps_or_options=nil, &proc)
+    taps = nil
+    fingers = nil
+
+    if taps_or_options
+      if taps_or_options.is_a? Hash
+        taps = taps_or_options[:taps] || taps
+        fingers = taps_or_options[:fingers] || fingers
+      else
+        taps = taps_or_options
+      end
+    end
+
+    recognizer = UITapGestureRecognizer.alloc.initWithTarget(self, action:'sugarcube_handle_gesture:')
+    recognizer.numberOfTapsRequired = taps if taps
+    recognizer.numberOfTouchesRequired = fingers if fingers
+    sugarcube_add_gesture(proc, recognizer)
+  end
+
+  def on_pinch(&proc)
+    recognizer = UIPinchGestureRecognizer.alloc.initWithTarget(self, action:'sugarcube_handle_gesture:')
+    sugarcube_add_gesture(proc, recognizer)
+  end
+
+  def on_rotate(&proc)
+    recognizer = UIRotationGestureRecognizer.alloc.initWithTarget(self, action:'sugarcube_handle_gesture:')
+    sugarcube_add_gesture(proc, recognizer)
+  end
+
+  def on_swipe(direction_or_options=nil, &proc)
+    direction = UISwipeGestureRecognizerDirectionRight
+    fingers = nil
+
+    if direction_or_options
+      if direction_or_options.is_a? Hash
+        direction = direction_or_options[:direction] || direction
+        fingers = direction_or_options[:fingers] || fingers
+      else
+        direction = direction_or_options
+      end
+    end
+
+    case direction
+    when :left
+      direction = UISwipeGestureRecognizerDirectionLeft
+    when :right
+      direction = UISwipeGestureRecognizerDirectionRight
+    when :up
+      direction = UISwipeGestureRecognizerDirectionUp
+    when :down
+      direction = UISwipeGestureRecognizerDirectionDown
+    end
+
+    recognizer = UISwipeGestureRecognizer.alloc.initWithTarget(self, action:'sugarcube_handle_gesture:')
+    recognizer.direction = direction if direction
+    recognizer.numberOfTouchesRequired = fingers if fingers
+    sugarcube_add_gesture(proc, recognizer)
+  end
+
+  def on_pan(fingers_or_options=nil, &proc)
+    fingers = nil
+    min_fingers = nil
+    max_fingers = nil
+
+    if fingers_or_options
+      if fingers_or_options.is_a? Hash
+        fingers = fingers_or_options[:fingers] || fingers
+        min_fingers = fingers_or_options[:min_fingers] || min_fingers
+        max_fingers = fingers_or_options[:max_fingers] || max_fingers      else
+        fingers = fingers_or_options
+      end
+    end
+
+    recognizer = UIPanGestureRecognizer.alloc.initWithTarget(self, action:'sugarcube_handle_gesture:')
+    sugarcube_add_gesture(proc, recognizer)
+  end
+
+  def on_press(duration_or_options=nil, &proc)
+    duration = nil
+    taps = nil
+    fingers = nil
+
+    if duration_or_options
+      if duration_or_options.is_a? Hash
+        duration = duration_or_options[:duration] || duration
+        taps = duration_or_options[:taps] || taps
+        fingers = duration_or_options[:fingers] || fingers
+      else
+        duration = duration_or_options
+      end
+    end
+
+    recognizer = UILongPressGestureRecognizer.alloc.initWithTarget(self, action:'sugarcube_handle_gesture:')
+    recognizer.minimumPressDuration = duration if duration
+    recognizer.numberOfTapsRequired = taps if taps
+    recognizer.numberOfTouchesRequired = fingers if fingers
+    sugarcube_add_gesture(proc, recognizer)
+  end
+
+private
+  def sugarcube_handle_gesture(recognizer)
+    handler = @sugarcube_recognizers[recognizer]
+    if handler.arity == 0
+      handler.call
+    else
+      handler.call(recognizer)
+    end
+  end
+
+  # Adds the recognizer and keeps a strong reference to the Proc object.
+  def sugarcube_add_gesture(proc, recognizer)
+    self.addGestureRecognizer(recognizer)
+
+    @sugarcube_recognizers = {} unless @sugarcube_recognizers
+    @sugarcube_recognizers[recognizer] = proc
+
+    recognizer
+  end
+
+end