rm-extensions 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2ba4ba13ce05f6391b658a6d6968fd368d6eb66e
-  data.tar.gz: 9140c139f8dc4c75d01183e46019df8ebac3a7c2
+  metadata.gz: 5d64ca280c2914d4e0e8ebda0af7b8900c4a71d0
+  data.tar.gz: 422760a452010841d394d296a59090c5967b43cd
 SHA512:
-  metadata.gz: 4ba45a55bbee4a13e6d0d72326208e4c704377ad24b28c6e04569e857cfeb74e869e9d846e9744367432e34068f8808dd502326f79b9cf242dfcebdb541b7c6c
-  data.tar.gz: 03222f43b0510a630fd09b33f30bc59815c06ad6d54e41384f76880d0f645bb449ff297ee689d01988235ff66d4a8be31df1385d60b174b6c7222be4c18d7c4e
+  metadata.gz: 613afb58ed64e974e51cdfc117e8627ecc381084c2d1cf6e571b2d0df6a95ba071fab76efeda59cf9eb0e6a203a3d9cce1908a5e3cdf05be8b9179e8c947c4dd
+  data.tar.gz: 41375da6369ebe8921c5f47d2576ea774cc353b8701774e092ffaf7df6948e6b65b87bf203f10c2a055603e324c93b8ee4689205f76f5597ee267ee38a45f86d

data/Gemfile

@@ -1,4 +1,7 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in rm-extensions.gemspec
+group :test, :development do
+  gem 'rake'
+end
+
 gemspec

data/README.md

@@ -1,7 +1,204 @@
 RMExtensions
 -----------------
 
-#### Extensions and helpers for dealing with various areas of rubymotion.
+#### Extensions and helpers for dealing with various areas of rubymotion and iOS.
+
+## Equation-style AutoLayout Constraints 
+
+AutoLayout is a great way to lay out views, but writing constraints manually is
+confusing and verbose.
+
+Using Apple's "Visual Format Language" ASCII-inspired
+strings can improve things, but it has drawbacks:  **1)** It returns an array
+of constraints.  This means if you plan on altering one of them later, or removing
+one in particular, you would have to loop through all of the constraints, testing
+each one to see if its the one you want.  **2)** The `options` argument adds additional
+constraints.  For example, if you specify NSLayoutAttributeCenterY to a horizontal string,
+an additional constraint will be added for each view to set their centerY's equal to each
+other.  This compounds problem #1.  The chances you will get an error that the layout system
+cannot satisfy your constraints is probably because of these "extra" constraints. **3)**
+It can't handle complex constraints, so you end up needing to supplement it with
+verbose low-level constraint creation anyway.
+
+Apple makes note of how constraints can be thought of like a linear equation:
+
+http://developer.apple.com/library/ios/documentation/AppKit/Reference/NSLayoutConstraint_Class/NSLayoutConstraint/NSLayoutConstraint.html
+
+**Remember the formula:**
+
+```ruby
+view1.attr1 == view2.attr2 * multiplier + constant @ priority
+```
+
+**We can actually use this super-simple formula to write ALL of our constraints, simple OR complex!**
+
+Once you get the hang of the formula and visualization of how the geometry works, it becomes easy to create complex layouts with little
+effort.  And, in my opinion, its only slightly more verbose than the visual format language, but much clearer, and you only end up
+with the exact constraints you want.
+
+Available values for `attr1` and `attr2` are:
+
+- left
+- right
+- top
+- bottom
+- leading
+- trailing
+- width
+- height
+- centerX
+- centerY
+- baseline
+
+Available `relation` values are:
+
+- ==
+- <=
+- >=
+
+Available `priority` values are:
+
+- required (1000 is the default)
+- high (750)
+- low (250)
+- fit (50)
+- or, you can use your own value between 1-1000
+
+
+### Examples
+
+Here is a real example.  The Layout instance is created just like the motion-layout gem.  `layout.view` sets the view
+that will act as the 'superview' to the views set in `layout.subviews`.  Thats where the similarities end with
+motion-layout.  With RMExtensions::Layout, there are two methods: `eq` and `eqs`, short for equation and equations.
+
+- `layout.eq` takes one string, and returns *one constraint*
+- `layout.eqs` takes one string, assumes multiple constraints are separated by newlines, and returns an *array of constraints*
+
+```ruby
+RMExtensions::Layout.new do |layout|
+  layout.view view
+  layout.subviews({
+    "calendar" => calendarView,
+    "table" => tableView,
+    "shadow" => line
+  })
+
+  layout.eqs %Q{
+    calendar.left == 0
+    calendar.right == 0
+    table.left == 7
+    table.right == -7
+    shadow.left == 0
+    shadow.right == 0
+
+    calendar.top == 0
+    table.top == calendar.bottom
+    table.bottom == 0
+    shadow.top == table.top
+  }
+
+  @calendar_height_constraint = layout.eq "calendar.height == 0"
+end
+```
+
+Above, **calendar.left == 0** is short for **calendar.left == view.left * 1.0 + 0 @ 1000**.  If no view2 is given, the superview ('view') is assumed.
+If no multiplier is given, 1.0 is assumed.  If no constant is given, 0 is assumed.  If no priority is given, "required" (1000) is assumed.
+The last constraint is created separately and stored in @calendar_height_constraint, because I want to be able to change the calendar's height
+any time I want.
+
+Here is another example:
+
+```ruby
+RMExtensions::Layout.new do |layout|
+  layout.view self
+  layout.subviews({
+    "timeLabel" => @timeLabel,
+    "titleLabel" => @titleLabel,
+    "trackingImage" => @trackingImage,
+    "inOutStatusInImage" => @inOutStatusInImage,
+    "inOutStatusOutImage" => @inOutStatusOutImage,
+    "plannerImage" => @plannerImage,
+    "shareButton" => @shareButton,
+    "cancelledLabel" => @cancelledLabel,
+    "unreadImage" => @unreadImage
+  })
+  
+  layout.eqs %Q{
+    unreadImage.left == 6
+    unreadImage.top == 6
+    plannerImage.left == 14
+    plannerImage.centerY == 0
+    plannerImage.width == 30
+    plannerImage.height == 30
+    trackingImage.left == timeLabel.right + 5
+    inOutStatusOutImage.left == trackingImage.right + 5
+    inOutStatusInImage.left == inOutStatusOutImage.right + 5
+    timeLabel.left == plannerImage.right + 5
+    timeLabel.baseline == plannerImage.bottom + 1
+    trackingImage.centerY == timeLabel.centerY
+    inOutStatusOutImage.centerY == timeLabel.centerY
+    inOutStatusInImage.centerY == timeLabel.centerY
+    titleLabel.left == cancelledLabel.right
+    cancelledLabel.left == plannerImage.right + 5
+    titleLabel.top == plannerImage.top - 4
+    cancelledLabel.centerY == titleLabel.centerY
+    shareButton.right == -10
+    shareButton.centerY == 0
+    titleLabel.resistH == low
+    shareButton.left >= titleLabel.right + 5
+    timeLabel.resistH == low
+    shareButton.left >= inOutStatusInImage.right + 5
+  }
+
+end
+```
+
+Keep in mind none of these lines are using the multiplier, and thats OK.  I've only needed it on one constraint in my entire app so far,
+so don't think its odd if you can't find a use for it.
+
+There are two special cases at the moment.  **titleLabel.resistH == low** is not a "real" constraint.  Its a shortcut to
+`setContentCompressionResistancePriority`, and since its common when dealing with autolayout, its nice to include it
+in our layout code.  The same is done for `setContentHuggingPriority`.  The full list of "special cases" at the moment:
+
+- view1.resistH == priority
+- view1.resistV == priority
+- view1.hugH == priority
+- view1.hugV == priority
+
+"priority" can be one of the values listed earlier, or your own number between 1-1000.
+
+### Debugging constraints
+
+- You can include a **?** on any line, and debug output will be printed when that constraint is built:
+
+```ruby
+layout.eqs %Q{
+  label.left == photo.right + 5 ?
+}
+```
+
+- Since layout.eqs allows you to write many constraints in one string, and sometimes its nice to
+keep comments next to constraints, **comments are allowed**:
+
+```ruby
+layout.eqs %Q{
+  commentsCount.width == likesCount.width @ low # the widths of the labels prefer to be the same
+}
+```
+
+### Things to remember
+
+- Remember you usually want negative constants for right and bottom.  For example: label.right == -10 means "label's right should be 10 away from the right side of the superview".  But if you accidentally said label.right == 10, you would have created "label's right should be 10 PAST the right side of the superview".  It may require you to adjust your thinking.
+
+- The formula is just shorthand for `constraintWithItem:attribute:relatedBy:toItem:attribute:multiplier:constant:`.  You should **really** read up on constraints and
+understand this method, to fully understand the power and simplicity the shorthand formula gives you.
+
+
+
+
+
+
+
 
 ## Observation/KVO, Events
 

data/Rakefile

@@ -1 +1,16 @@
 require "bundler/gem_tasks"
+$:.unshift('/Library/RubyMotion/lib')
+if ENV.fetch('platform', 'ios') == 'ios'
+  require 'motion/project/template/ios'
+elsif ENV['platform'] == 'osx'
+  require 'motion/project/template/osx'
+else
+  raise "Unsupported platform #{ENV['platform']}"
+end
+require 'bundler'
+Bundler.require
+
+Motion::Project::App.setup do |app|
+  # Use `rake config' to see complete project settings.
+  app.name = 'rm-extensions'
+end

data/app/app_delegate.rb

@@ -0,0 +1,5 @@
+class AppDelegate
+  def application(application, didFinishLaunchingWithOptions:launchOptions)
+    true
+  end
+end

data/lib/rm-extensions/version.rb

@@ -1,3 +1,3 @@
 module RMExtensions
-  VERSION = "0.1.5"
+  VERSION = "0.1.6"
 end

data/spec/main_spec.rb

@@ -0,0 +1,240 @@
+describe "Equation-style AutoLayout Constraints" do
+
+  def self.test_constraint_equation(c1_str, optional_desc=nil, &block)
+    it "#{optional_desc || c1_str}" do
+      c1 = @layout.eq c1_str
+      c2 = block.call
+      c1.priority.should == c2.priority
+      c1.firstItem.should == c2.firstItem
+      c1.firstAttribute.should == c2.firstAttribute
+      c1.relation.should == c2.relation
+      c1.secondItem.should == c2.secondItem
+      c1.secondAttribute.should == c2.secondAttribute
+      c1.multiplier.should == c2.multiplier
+      c1.constant.should == c2.constant
+    end
+  end
+
+  before do
+    @view = UIView.new
+    @label1 = UILabel.new
+    @label2 = UILabel.new
+    @layout = RMExtensions::Layout.new
+    @layout.view @view
+    @layout.subviews({
+      "label1" => @label1,
+      "label2" => @label2
+    })
+  end
+
+  test_constraint_equation("label1.left == 0") do
+    NSLayoutConstraint.constraintWithItem(@label1,
+     attribute:NSLayoutAttributeLeft,
+     relatedBy:NSLayoutRelationEqual,
+        toItem:@view,
+     attribute:NSLayoutAttributeLeft,
+    multiplier:1.0,
+      constant:0)
+  end
+
+  test_constraint_equation("label1.left == 8") do
+    NSLayoutConstraint.constraintWithItem(@label1,
+     attribute:NSLayoutAttributeLeft,
+     relatedBy:NSLayoutRelationEqual,
+        toItem:@view,
+     attribute:NSLayoutAttributeLeft,
+    multiplier:1.0,
+      constant:8)
+  end
+
+  test_constraint_equation("label1.right == -20") do
+    NSLayoutConstraint.constraintWithItem(@label1,
+     attribute:NSLayoutAttributeRight,
+     relatedBy:NSLayoutRelationEqual,
+        toItem:@view,
+     attribute:NSLayoutAttributeRight,
+    multiplier:1.0,
+      constant:-20)
+  end
+
+  test_constraint_equation("label1.top == 0") do
+    NSLayoutConstraint.constraintWithItem(@label1,
+     attribute:NSLayoutAttributeTop,
+     relatedBy:NSLayoutRelationEqual,
+        toItem:@view,
+     attribute:NSLayoutAttributeTop,
+    multiplier:1.0,
+      constant:0)
+  end
+
+  test_constraint_equation("label1.bottom == -36") do
+    NSLayoutConstraint.constraintWithItem(@label1,
+     attribute:NSLayoutAttributeBottom,
+     relatedBy:NSLayoutRelationEqual,
+        toItem:@view,
+     attribute:NSLayoutAttributeBottom,
+    multiplier:1.0,
+      constant:-36)
+  end
+
+  test_constraint_equation("label1.height == 1") do
+    NSLayoutConstraint.constraintWithItem(@label1,
+     attribute:NSLayoutAttributeHeight,
+     relatedBy:NSLayoutRelationEqual,
+        toItem:nil,
+     attribute:NSLayoutAttributeNotAnAttribute,
+    multiplier:1.0,
+      constant:1)
+  end
+
+  test_constraint_equation("label1.centerX == 0") do
+    NSLayoutConstraint.constraintWithItem(@label1,
+     attribute:NSLayoutAttributeCenterX,
+     relatedBy:NSLayoutRelationEqual,
+        toItem:@view,
+     attribute:NSLayoutAttributeCenterX,
+    multiplier:1.0,
+      constant:0)
+  end
+
+  test_constraint_equation("label1.width == 1.5") do
+    NSLayoutConstraint.constraintWithItem(@label1,
+     attribute:NSLayoutAttributeWidth,
+     relatedBy:NSLayoutRelationEqual,
+        toItem:nil,
+     attribute:NSLayoutAttributeNotAnAttribute,
+    multiplier:1.0,
+      constant:1.5)
+  end
+
+  test_constraint_equation("label1.left >= 6") do
+    NSLayoutConstraint.constraintWithItem(@label1,
+     attribute:NSLayoutAttributeLeft,
+     relatedBy:NSLayoutRelationGreaterThanOrEqual,
+        toItem:@view,
+     attribute:NSLayoutAttributeLeft,
+    multiplier:1.0,
+      constant:6)
+  end
+
+  test_constraint_equation("label1.width == 0 @ low # prefer box hugs content") do
+    NSLayoutConstraint.constraintWithItem(@label1,
+     attribute:NSLayoutAttributeWidth,
+     relatedBy:NSLayoutRelationEqual,
+        toItem:nil,
+     attribute:NSLayoutAttributeNotAnAttribute,
+    multiplier:1.0,
+      constant:0).tap { |x| x.priority = UILayoutPriorityDefaultLow }
+  end
+
+  test_constraint_equation("label1.left == 24 @ low # this button prefers to hug the left") do
+    NSLayoutConstraint.constraintWithItem(@label1,
+     attribute:NSLayoutAttributeLeft,
+     relatedBy:NSLayoutRelationEqual,
+        toItem:@view,
+     attribute:NSLayoutAttributeLeft,
+    multiplier:1.0,
+      constant:24).tap { |x| x.priority = UILayoutPriorityDefaultLow }
+  end
+
+  test_constraint_equation("label1.top == view.top + 8") do
+    NSLayoutConstraint.constraintWithItem(@label1,
+     attribute:NSLayoutAttributeTop,
+     relatedBy:NSLayoutRelationEqual,
+        toItem:@view,
+     attribute:NSLayoutAttributeTop,
+    multiplier:1.0,
+      constant:8)
+  end
+
+  test_constraint_equation("label1.left == label2.left * 0.5 - 5") do
+    NSLayoutConstraint.constraintWithItem(@label1,
+     attribute:NSLayoutAttributeLeft,
+     relatedBy:NSLayoutRelationEqual,
+        toItem:@label2,
+     attribute:NSLayoutAttributeLeft,
+    multiplier:0.5,
+      constant:-5)
+  end
+
+  test_constraint_equation("label1.top == label2.top + 5") do
+    NSLayoutConstraint.constraintWithItem(@label1,
+     attribute:NSLayoutAttributeTop,
+     relatedBy:NSLayoutRelationEqual,
+        toItem:@label2,
+     attribute:NSLayoutAttributeTop,
+    multiplier:1.0,
+      constant:5)
+  end
+
+  test_constraint_equation("label1.top == label2.bottom") do
+    NSLayoutConstraint.constraintWithItem(@label1,
+     attribute:NSLayoutAttributeTop,
+     relatedBy:NSLayoutRelationEqual,
+        toItem:@label2,
+     attribute:NSLayoutAttributeBottom,
+    multiplier:1.0,
+      constant:0)
+  end
+
+  test_constraint_equation("label1.width == label2.width @ low # the widths of the labels prefer to be the same") do
+    NSLayoutConstraint.constraintWithItem(@label1,
+     attribute:NSLayoutAttributeWidth,
+     relatedBy:NSLayoutRelationEqual,
+        toItem:@label2,
+     attribute:NSLayoutAttributeWidth,
+    multiplier:1.0,
+      constant:0).tap { |x| x.priority = UILayoutPriorityDefaultLow }
+  end
+
+  test_constraint_equation("label1.left == label2.right + 20") do
+    NSLayoutConstraint.constraintWithItem(@label1,
+     attribute:NSLayoutAttributeLeft,
+     relatedBy:NSLayoutRelationEqual,
+        toItem:@label2,
+     attribute:NSLayoutAttributeRight,
+    multiplier:1.0,
+      constant:20)
+  end
+
+  test_constraint_equation("label1.centerY == label2.centerY") do
+    NSLayoutConstraint.constraintWithItem(@label1,
+     attribute:NSLayoutAttributeCenterY,
+     relatedBy:NSLayoutRelationEqual,
+        toItem:@label2,
+     attribute:NSLayoutAttributeCenterY,
+    multiplier:1.0,
+      constant:0)
+  end
+
+  test_constraint_equation("label1.left >= label2.right + 6") do
+    NSLayoutConstraint.constraintWithItem(@label1,
+     attribute:NSLayoutAttributeLeft,
+     relatedBy:NSLayoutRelationGreaterThanOrEqual,
+        toItem:@label2,
+     attribute:NSLayoutAttributeRight,
+    multiplier:1.0,
+      constant:6)
+  end
+
+  test_constraint_equation("label1.right <= view.right - 8") do
+    NSLayoutConstraint.constraintWithItem(@label1,
+     attribute:NSLayoutAttributeRight,
+     relatedBy:NSLayoutRelationLessThanOrEqual,
+        toItem:@view,
+     attribute:NSLayoutAttributeRight,
+    multiplier:1.0,
+      constant:-8)
+  end
+
+  test_constraint_equation("label1.right <= label2.left - 10") do
+    NSLayoutConstraint.constraintWithItem(@label1,
+     attribute:NSLayoutAttributeRight,
+     relatedBy:NSLayoutRelationLessThanOrEqual,
+        toItem:@label2,
+     attribute:NSLayoutAttributeLeft,
+    multiplier:1.0,
+      constant:-10)
+  end
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rm-extensions
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - Joe Noon
@@ -22,6 +22,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- app/app_delegate.rb
 - lib/motion/accessors.rb
 - lib/motion/layout.rb
 - lib/motion/observation.rb
@@ -29,7 +30,9 @@ files:
 - lib/motion/util.rb
 - lib/rm-extensions.rb
 - lib/rm-extensions/version.rb
+- resources/Default-568h@2x.png
 - rm-extensions.gemspec
+- spec/main_spec.rb
 homepage: https://github.com/joenoon/rm-extensions
 licenses: []
 metadata: {}
@@ -53,4 +56,5 @@ rubygems_version: 2.0.3
 signing_key: 
 specification_version: 4
 summary: Extensions and helpers for dealing with various areas of rubymotion
-test_files: []
+test_files:
+- spec/main_spec.rb