motion-wiretap 1.1.5 → 1.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8a0ba74d89d7665f5da90026f2547c5a6b76ca5f
-  data.tar.gz: aad024532ba78acde032d7b77f9beabdd37e1212
+  metadata.gz: 7d28f1e832294f594579798c62718339c9822a31
+  data.tar.gz: aeeec36e2613e003f5d90788ffad2b9a06c4e56c
 SHA512:
-  metadata.gz: d534884d01c3d1f90ebcb09550007cdfb1fab5351162c2e6e5d43d2aa1ede4e87f533a8ac822f74cef120ea2f6fea0ef612e439a818cb70e1cd664c73a6d04f5
-  data.tar.gz: aef50be40d464e1642d8da25eebfc3fa1046180e870b5a750ed67d8db1ddb90efb77fae5281df137d1cac0ac03149e00ee920d628fe0c382195d21c5d87691aa
+  metadata.gz: 19c5b44d1a0b39827bf145baa0664f099ea239e487936a24246609aac88422a56cd2f8809c31043281618153c3fdf78748044a4a6808dc6e22721c004e534ee2
+  data.tar.gz: 6043ff1c69787e815f115d616399d19ad1296dc9fc9b08b3b2a67ce50f0febf8d9fc9795bbb566a577c51a20f4cf8a68cb55a6c6d7fdd67f0829c8aecc4944c2

data/README.md

@@ -50,7 +50,9 @@ like this style, but the default is to have a non-polluting system.
 
 Wiretaps can be composed all sorts of ways: you can filter them, map them,
 combine multiple wiretaps into a single value, use them to respond to
-notifications or control events.
+notifications or control events.  When you compose them in this way you only
+need to retain the "bottom most" wiretap.  Examples follow.
+
 
 ### Let's start with something practical!
 
@@ -60,17 +62,17 @@ In these examples I will use all three ways of creating a Wiretap
 ```ruby
 # assign the label to the text view; changes to the text view will be reflected
 # on the label.
-MW(@label, :text).bind_to(MW(@text_view, :text))
+@wiretap = MW(@label, :text).bind_to(MW(@text_view, :text))
 
 # assign the attributedText of the label to the text view, doing some
 # highlighting in-between.
-@label.wiretap(:attributedText).bind_to(@text_view.wiretap(:text).map do |text|
+@wiretap = @label.wiretap(:attributedText).bind_to(@text_view.wiretap(:text).map do |text|
   NSAttributedString.alloc.initWithString(text, attributes: { NSForegroundColorAttributeName => UIColor.blueColor })
 end)
 
 # This code will set the 'enabled' property depending on whether the username
 # and password are not empty.
-Motion.wiretap(@login_button, :enabled).bind_to(
+@wiretap = Motion.wiretap(@login_button, :enabled).bind_to(
   Motion.wiretap([
     Motion.wiretap(@username_field, :text),
     Motion.wiretap(@password_field, :text),
@@ -81,6 +83,10 @@ Motion.wiretap(@login_button, :enabled).bind_to(
   )
 ```
 
+See how in the example above I only retain the "final" signal (the return value
+from `#combine` is what gets retained by `@wiretap`). That's what I mean by the
+"bottom most" wiretap.  Don't worry, the intermediate wiretaps get retained.
+
 ### Types of wiretaps
 
 - Key-Value Observation / KVO
@@ -102,35 +108,35 @@ end
 person = Person.new
 # you need to store the wiretap object in memory; when the object is
 # deallocated, it will no longer receive updates.
-wiretap = Motion.wiretap(person, :name)
+@wiretap = Motion.wiretap(person, :name)
 # react to change events
-wiretap.listen do |name|
+@wiretap.listen do |name|
   puts "name is now #{name}"
 end
 person.name = 'Joe'
 # puts => "name is now Joe"
 
 # Since listening is very common, you can easily shorthand this to:
-wiretap = Motion.wiretap(person, :name) do |name|
+@wiretap = Motion.wiretap(person, :name) do |name|
   puts "name is now #{name}"
 end
 
 # bind the property of one object to the value of another
 person_1 = Person.new
 person_2 = Person.new
-wiretap = Motion.wiretap(person_1, :name)
-wiretap.bind_to(person_2, :name)  # creates a new Wiretap object for person_2; changes to person_2.name will affect person_1
+@wiretap = Motion.wiretap(person_1, :name)
+@wiretap.bind_to(person_2, :name)  # creates a new Wiretap object for person_2; changes to person_2.name will affect person_1
 person_2.name = 'Bob'
 person_1.name # => "Bob"
 
 # cancel a wiretap
-wiretap.cancel!
+@wiretap.cancel!
 person_2.name = 'Jane'
 person_1.name
 # => "BOB"
 
 # bind the property of one object to the value of another, but change it using `map`
-wiretap = Motion.wiretap(person_1, :name).bind_to(Motion.wiretap(person_2, :name).map { |value| value.upcase })
+@wiretap = Motion.wiretap(person_1, :name).bind_to(Motion.wiretap(person_2, :name).map { |value| value.upcase })
 person_2.name = 'Bob'
 person_1.name # => "BOB"
 ```
@@ -138,70 +144,82 @@ person_1.name # => "BOB"
 ### Working with arrays
 
 ```ruby
-# combine the values `name` and `email`
+# combine the values `name` and `email`, which means they'll be sent together
+# when either one changes
 person = Person.new
-taps = Motion.wiretap([
+@info = nil
+@taps = Motion.wiretap([
   Motion.wiretap(person, :name),
   Motion.wiretap(person, :email),
 ]).combine do |name, email|
-  puts "#{name} <#{email}>"
+  @info = "#{name} <#{email}>"
 end
 
 person.name = 'Kazuo'
-# puts => "Kazuo <>"
+# @info => "Kazuo <>"
 person.email = 'kaz@example.com'
-# puts => "Kazuo <kaz@example.com>"
+# @info => "Kazuo <kaz@example.com>"
 
-# reduce/inject
+# With reduce you get a memo and a value, and you should return a new value. Be
+# careful about mutable structures: the initial memo is retained, not copied.
 person_1 = Person.new
 person_2 = Person.new
-taps = Motion.wiretap([
+@names = []
+@taps = Motion.wiretap([
   Motion.wiretap(person_1, :name),
   Motion.wiretap(person_2, :name),
-]).reduce do |memo, name|
-  memo ||= []
+]).reduce([]) do |memo, name|
   memo + [name]
-end
-wiretap.listen do |names|
-  puts names.inspect
+end.listen do |names|
+  @names = names.inspect
 end
 person_1.name = 'Mr. White'
-person_1.name = 'Mr. Blue'
-# => ["Mr. White", "Mr. Blue"]
-
-# you can provide an initial 'memo' (default: nil)
-Motion.wiretap([
-  Motion.wiretap(person_1, :name),
-  Motion.wiretap(person_2, :name),
-]).reduce([]) do |memo, name|
-  memo + [name]  # you should not change memo in place, the same one will be used on every change event
-end
+# @names => ["Mr. White", nil]
+person_2.name = 'Mr. Blue'
+# @names => ["Mr. White", "Mr. Blue"]
 ```
 
 ### Monitoring jobs
 
+There is a "short form" and "long form" to these wiretaps.  The "short form" is
+something like `Motion.wiretap(proc) do (block) end`.  The `proc` will be
+executed, and when it's done, the `block` will execute.
+
+The "long form" is different only in that the block is passed to the `and_then`
+method, not the initializer: `Motion.wiretap(proc).and_then do ... end`.  In
+this form, you must call `start` on the wiretap:
+
 ```ruby
-# Monitor for background job completion:
-Motion.wiretap(-> do
+# Monitor for background job completion, short form:
+@wiretap = Motion.wiretap(-> do
+  this_will_take_forever!
+end) do
+  puts "done!"
+end
+
+# Monitor for background job completion, long form:
+@wiretap = Motion.wiretap(-> do
   this_will_take_forever!
 end).and_then do
   puts "done!"
-end.start
+end.start  # you must call 'start' explicitly
 
-# Same, but specifying the thread to run on. The completion block will be called
-# on this thread, too. The queue conveniently accepts a completion handler
-# (delegates to the `Wiretap#and_then` method).
-Motion.wiretap(-> do
+# Same again, but specifying the thread to run on. The completion block will be
+# called on this thread, too. The queue conveniently accepts a completion
+# handler (delegates to the `Wiretap#and_then` method).
+@wiretap = Motion.wiretap(-> do
   this_will_take_forever!
 end).queue(Dispatch::Queue.concurrent).and_then do
   puts "done!"
-end.start
+end
+@wiretap.start
 
 # Send a stream of values from a block. A lambda is passed in that will forward
 # change events to the `listen` block
-Motion.wiretap(-> (on_change) do
+@wiretap = Motion.wiretap(-> (on_change) do
   5.times do |count|
     on_change.call count
+    sleep(1)
   end
 end).listen do |index|
   puts "...#{index}"
@@ -211,17 +229,50 @@ end.start
 # => puts "...0", "...1", "...2", "...3", "...4", "done!"
 ```
 
-### Notifications
+### Gestures
+
+Possible gestures:
+
+    :tap, :pinch, :rotate, :swipe, :pan, :press
+
+Options:
+
+    :taps (:tap, :press)
+    :fingers (:tap, :swipe, :pan, :press)
+    :direction (:direction)
+    :min_fingers (:pan)
+    :max_fingers (:pan)
+    :duration (:press)
 
 ```ruby
-notification = Motion.wiretap('NotificationName') do
-  puts 'notification received!'
+@wiretap = Motion.wiretap(view).on(:tap) do |gesture|
+  point = gesture.locationInView(view)
+  puts "you tapped #{point.x}, #{point.y}"
 end
-# the notification observer will be removed when the Wiretap is dealloc'd
 ```
 
-### Gestures
+### Control events
+
+Possible events:
+
+    :touch, :touch_up, :touch_down, :touch_start, :touch_stop, :change, :begin,
+    :end, :touch_down_repeat, :touch_drag_inside, :touch_drag_outside,
+    :touch_drag_enter, :touch_drag_exit, :touch_up_inside, :touch_up_outside,
+    :touch_cancel, :value_changed, :editing_did_begin, :editing_changed,
+    :editing_did_change, :editing_did_end, :editing_did_end_on_exit
+    :all_touch, :all_editing, :application, :system, :all
 
 ```ruby
+@wiretap = Motion.wiretap(control).on(:touch) do |event|
+end
+```
 
-```
+### Notifications
+
+```ruby
+@wiretap = Motion.wiretap('NotificationName') do |object, user_info|
+  puts 'notification received!'
+end
+
+NSNotificationCenter.defaultCenter.postNotificationName('NotificationName', object: nil, userInfo: info)
+```

data/lib/motion-wiretap/ios/wiretap_gestures.rb

@@ -23,7 +23,7 @@ module MotionWiretap
         end
       end
 
-      recognizer = UITapGestureRecognizer.alloc.initWithTarget(target, action: :handle_gesture)
+      recognizer = UITapGestureRecognizer.alloc.initWithTarget(target, action: 'handle_gesture:')
       recognizer.numberOfTapsRequired = taps if taps
       recognizer.numberOfTouchesRequired = fingers if fingers
       return recognizer
@@ -31,13 +31,13 @@ module MotionWiretap
 
     # @yield [recognizer] Handles the gesture event, and passes the recognizer instance to the block.
     def pinch(target)
-      recognizer = UIPinchGestureRecognizer.alloc.initWithTarget(target, action: :handle_gesture)
+      recognizer = UIPinchGestureRecognizer.alloc.initWithTarget(target, action: 'handle_gesture:')
       return recognizer
     end
 
     # @yield [recognizer] Handles the gesture event, and passes the recognizer instance to the block.
     def rotate(target)
-      recognizer = UIRotationGestureRecognizer.alloc.initWithTarget(target, action: :handle_gesture)
+      recognizer = UIRotationGestureRecognizer.alloc.initWithTarget(target, action: 'handle_gesture:')
       return recognizer
     end
 
@@ -71,7 +71,7 @@ module MotionWiretap
         direction = UISwipeGestureRecognizerDirectionDown
       end
 
-      recognizer = UISwipeGestureRecognizer.alloc.initWithTarget(target, action: :handle_gesture)
+      recognizer = UISwipeGestureRecognizer.alloc.initWithTarget(target, action: 'handle_gesture:')
       recognizer.direction = direction if direction
       recognizer.numberOfTouchesRequired = fingers if fingers
       return recognizer
@@ -103,7 +103,7 @@ module MotionWiretap
       min_fingers ||= fingers
       max_fingers ||= fingers
 
-      recognizer = UIPanGestureRecognizer.alloc.initWithTarget(target, action: :handle_gesture)
+      recognizer = UIPanGestureRecognizer.alloc.initWithTarget(target, action: 'handle_gesture:')
       recognizer.maximumNumberOfTouches = min_fingers if min_fingers
       recognizer.minimumNumberOfTouches = max_fingers if max_fingers
       return recognizer
@@ -131,7 +131,7 @@ module MotionWiretap
         end
       end
 
-      recognizer = UILongPressGestureRecognizer.alloc.initWithTarget(target, action: :handle_gesture)
+      recognizer = UILongPressGestureRecognizer.alloc.initWithTarget(target, action: 'handle_gesture:')
       recognizer.minimumPressDuration = duration if duration
       recognizer.numberOfTapsRequired = taps if taps
       recognizer.numberOfTouchesRequired = fingers if fingers

data/lib/motion-wiretap/ios/wiretap_ios.rb

@@ -4,6 +4,11 @@ module MotionWiretap
 
   class WiretapView < WiretapTarget
 
+    def initialize(target, &block)
+      super
+      @gesture_recognizers = []
+    end
+
     def on(recognizer, options=nil, &block)
       if recognizer
         case recognizer
@@ -24,6 +29,7 @@ module MotionWiretap
         end
 
         self.target.addGestureRecognizer(recognizer)
+        @gesture_recognizers << recognizer
       end
 
       listen(&block)
@@ -31,14 +37,27 @@ module MotionWiretap
       return self
     end
 
-    def handle_gesture
-      trigger_changed
+    def handle_gesture(gesture)
+      trigger_changed(gesture)
+    end
+
+    def teardown
+      remove_gesture = (-> (recognizer) {
+        self.target.removeGestureRecognizer(recognizer)
+      }).weak!
+      @gesture_recognizers.each(&remove_gesture)
+      super
     end
 
   end
 
   class WiretapControl < WiretapView
 
+    def initialize(target, &block)
+      super
+      @control_events = []
+    end
+
     # control_event can be any UIControlEventConstant, or any symbol found in
     # wiretap_control_events.rb, or an array of UIControlEventConstants or
     # symbols.  Since UIView implements `on` to accept a gesture, this method
@@ -46,7 +65,8 @@ module MotionWiretap
     def on(control_event, options={}, &block)
       begin
         control_event = ControlEvents.convert(control_event)
-        self.target.addTarget(self, action: :handle_event, forControlEvents: control_event)
+        self.target.addTarget(self, action: 'handle_event:', forControlEvents: control_event)
+        @control_events << control_event
       rescue ControlEventNotFound
         super(control_event, options, &block)
       else
@@ -56,8 +76,16 @@ module MotionWiretap
       return self
     end
 
-    def handle_event
-      trigger_changed
+    def handle_event(event)
+      trigger_changed(event)
+    end
+
+    def teardown
+      remove_event = (-> (event) {
+        self.target.removeTarget(self, action: 'handle_event:', forControlEvents: event)
+      }).weak!
+      @control_events.each(&remove_event)
+      super
     end
 
   end

data/lib/motion-wiretap/version.rb

@@ -1,3 +1,3 @@
 module MotionWiretap
-  VERSION = '1.1.5'
+  VERSION = '1.1.6'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: motion-wiretap
 version: !ruby/object:Gem::Version
-  version: 1.1.5
+  version: 1.1.6
 platform: ruby
 authors:
 - Colin T.A. Gray