ruby_motion_query 0.1.1 → 0.2.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    YTE0YTM0NWIzY2ZmNDIwMTgxNDgzMDMwZDM0MzAxNzJhZmJiN2EyMg==
+    ZjFmZTc0N2Y5NDViYjkyNGI3MjQ0MmFhZmQxNmQ3NzRiMzY3YzRkNQ==
   data.tar.gz: !binary |-
-    NjM1Zjg4OGRjM2U0YTgyNDFkMWQ2NzZlNjg0MWFjMmQxZTIxYTliZQ==
+    ZjU1NWJhMmE3MmZkNGRjNDIyYzJjNjE0YTdmOGNlYzcxNDE3MTMzMQ==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    YjI4MTM1NTUzZGJkMTg4MGY0NWE0YzgwMDFmMjI5ZGM5YTBhNWFhNDNjYzI4
-    ZGY5NzNiNTFhYTgyMzM1MThmYTgwNDA3NDE4NmM4Y2Y1YzhmMmFhNGMxNGQz
-    OWI3N2NlZWNlYTlmYzk5NmY1OTYzODQwZjMwYmMzMWE3M2QyMmE=
+    ZDA4NThmZjhhYjhlM2ViZjBiYzI4NzFlYjg0NzdlYTllMGQyNzE3Y2ZiZGQ1
+    YjE3M2JmNzc0ZmRhMzVhYWIxYzg5ZjdhMGEyYzFiYTg2ZmQyM2E5YzlhNDNl
+    MGYxNDUyOTE5NDJkODljYjc3MmMwYTI1ZDZjNzgwNGI2NDhiMmI=
   data.tar.gz: !binary |-
-    YmU4MTYyMjdiNGJkZjdmZDY2OTVjNDlhMGExOGIyMjljYWJhNGJjYmRjNDBh
-    YjUzMGIxZmIyMjdlODY4Yzg4N2JjN2MyNDQ1NDAzYWQxMTNkZTVjMmY5Njll
-    NzQwZGZlNDBiODJkMTVjN2UwMmY4ZWE4Zjg3NjMwMmRmM2FmNjQ=
+    YWNkY2Q3YjgyYTJhM2EzZmYxNTcyMzI5MTM2NzU5OGFjNGVlY2U5NDg1YzM2
+    MmI5ZDc4Y2ZkNGE1YTUwNDA1MzA5OTdkODFhZjVkZGNlZmYzZWM2ZjU1OGQ1
+    NmJmZWQ2OTFiZjllMDA4YjA0YmQ4ZTUzNDI0NGE0ODU3ZjU3MWY=

data/README.md

@@ -1,14 +1,17 @@
 ![RQM logo](http://ir_wp.s3.amazonaws.com/wp-content/uploads/sites/9/2013/07/rmq_logo.png)
 
-RubyMotionQuery - RMQ - A small, light, muggle, nonpolluting, jQuery-like library for [RubyMotion](http://rubymotion.com).
+# RubyMotionQuery - RMQ
+A light, muggle, nonpolluting, jQuery-like library for [RubyMotion](http://rubymotion.com).
 
-#### The [RMQ Introductory Guide and other info][1] is a great place to start.
+**The [RMQ Introductory Guide and other info][1] is a great place to start.**
 
+[![Dependency Status](https://gemnasium.com/infinitered/rmq.png)](https://gemnasium.com/infinitered/rmq)
+[![Build Status](https://travis-ci.org/infinitered/rmq.png?branch=master)](https://travis-ci.org/infinitered/rmq)
 
-----------
 
+## General
 
-#### Some of the very cool features:
+### Some of the very cool features:
  - **selecting** (*querying*) views
  - **traversal** through view hierarchy (moving around the tree)
  - tagging
@@ -21,30 +24,21 @@ RubyMotionQuery - RMQ - A small, light, muggle, nonpolluting, jQuery-like librar
  - app
  - device
 
-#### Other wrapper libraries
-There are a lot of great wrappers out there such as Teacup and Sugarcube. I've used these and I enjoy them. However, many of the wrappers heavily pollute the standard classes, which is great if you like that sort of thing. RMQ is designed to have minimal pollution, to be very simple and high performance (it will be when it's done). RMQ shouldn't conflict with anything.
-
-RMQ **doesn't require any** other wrapper or gem. 
-
-> If you preferred jQuery over Prototype, you'll love RMQ.
-
-Some of the code in RMQ came from BubbleWrap and Sugarcube. Not too much but some did. I thank you BubbleWrap and Sugarcube teams for your work.
-
 ----------
 
-### * Alpha * Warning *
+**Tested only on iOS only, not OS X (nor is there any OS X specific code)**
 
-This is in the **alpha** stage right now, it works well and we've used some of RMQ in production apps, but it **needs** more **testing**, **performance** optimizations, **documentation**, and the **TODOs** to be finished. 
+----------
 
-RDocs are not done. I'd appreciate help on these. This readme isn't up to the quality I'd like either. I figure it's better to get it out to the community sooner rather than wait for it to be more finished. My ideal is jQuery quality docs in addition to basic RDoc reference.
+### Other wrapper libraries
+There are a lot of great wrappers out there such as Teacup and Sugarcube. I've used these and I enjoy them. However, many of the wrappers heavily pollute the standard classes, which is great if you like that sort of thing. RMQ is designed to have minimal pollution, to be very simple and high performance (it will be when it's done). RMQ shouldn't conflict with anything.
 
-Nothing is optimized for speed yet. Well, that isn't true, somethings are.
+RMQ **doesn't require any** other wrapper or gem. 
 
-Memory leaks may exist. 
+> If you preferred jQuery over Prototype, you'll love RMQ.
 
-Tested only on iOS, not OS X (nor is there any OS X specific code)
+Some of the code in RMQ came from BubbleWrap and Sugarcube. Not too much but some did. I thank you BubbleWrap and Sugarcube teams for your work.
 
-----------
 
 ## Installation
 
@@ -58,7 +52,6 @@ or add it to your `Gemfile`:
 - `gem 'ruby_motion_query'`
 
 
-
 ## Usage
 
 ### Example App
@@ -159,6 +152,8 @@ rmq(UILabel).get
  - find
  - children
  - siblings
+ - next
+ - prev
  - closest
  - parent
  - parents
@@ -303,6 +298,7 @@ rmq(my_view).hide
 rmq(my_view).show
 rmq(my_view).toggle
 rmq(my_view).toggle_enabled
+rmq(my_text_field).focus # or .become_first_responder
 ```
 
 ### Subviews
@@ -311,10 +307,19 @@ rmq(my_view).toggle_enabled
 rmq.append(UILabel) # Creates a UILabel in the current controller
 rmq.append(UILabel, :my_label_style)
 rmq.append(UILabel.alloc.initWithFrame([[0,0],[10,10]]), :my_label_style)
-rmq(my_view).append(UIButton) # A custom button
+
+rmq(my_view).append(UIButton)
 rmq(my_view).remove
 rmq(my_vuew).children.remove
-rmq(UIView).append(UIButton, :delete_me)
+
+rmq(UIView).append(UIButton, :delete_me) # A custom button for all views
+
+rmq.unshift(UILabel) # Adds to index 0 of the subviews
+rmq.unshift(UILabel, :my_style)
+rmq.insert(UILabel, at_index: 2)
+rmq.insert(UILabel, at_index: 2, style: :my_style)
+rmq.insert(UILabel, below_view: some_view_of_mine)
+rmq.insert(UILabel, below_view: some_view_of_mine, style: :my_style)
 
 rmq(my_view).parent  # .superview works too
 rmq(my_view).parents # all parents up the tree, up to the root

data/motion/ruby_motion_query/actions.rb

@@ -1,5 +1,7 @@
 module RubyMotionQuery
   class RMQ
+
+    # @return [RMQ]
     def attr(new_settings)
       selected.each do |view|
         new_settings.each do |k,v|
@@ -9,6 +11,7 @@ module RubyMotionQuery
       self
     end
 
+    # @return [RMQ]
     def send(method, args = nil)
       selected.each do |view|
         if args
@@ -20,21 +23,39 @@ module RubyMotionQuery
       self
     end
 
+    # Sets the last selected view as the first responder
+    #
+    # @return [RMQ]
+    #
+    # @example
+    #   rmq(my_view).next(UITextField).focus
+    def focus
+      unless RMQ.is_blank?(selected)
+        selected.last.becomeFirstResponder
+      end
+      self
+    end
+    alias :become_first_responder :focus
+
+    # @return [RMQ]
     def hide
       selected.each { |view| view.hidden = true }
       self
     end
 
+    # @return [RMQ]
     def show
       selected.each { |view| view.hidden = false }
       self
     end
 
+    # @return [RMQ]
     def toggle
       selected.each { |view| view.hidden = !view.hidden? }
       self
     end
 
+    # @return [RMQ]
     def toggle_enabled
       selected.each { |view| view.enabled = !view.enabled? }
       self

data/motion/ruby_motion_query/animations.rb

@@ -1,5 +1,7 @@
 module RubyMotionQuery
   class RMQ
+
+    # @return [RMQ]
     def animate(opts = {})
       working_selected = self.selected
       @_rmq = self # @ for rm bug
@@ -35,6 +37,7 @@ module RubyMotionQuery
       self
     end
 
+    # @return [Animations]
     def animations
       @_animations ||= Animations.new(self)
     end
@@ -45,6 +48,7 @@ module RubyMotionQuery
       @rmq = rmq
     end
 
+    # @return [RMQ]
     def fade_in(opts = {})
       @rmq.each do |view|
         view.layer.opacity = 0.0
@@ -58,6 +62,7 @@ module RubyMotionQuery
       @rmq.animate(opts)
     end
 
+    # @return [RMQ]
     def fade_out(opts = {})
       opts[:animations] = lambda do |rmq|
         rmq.get.layer.opacity = 0.0
@@ -77,6 +82,7 @@ module RubyMotionQuery
       @rmq.animate(opts)
     end
 
+    # @return [RMQ]
     def throb
       @rmq.animate(
         duration: 0.1,
@@ -94,22 +100,27 @@ module RubyMotionQuery
       )
     end
 
+    # @return [RMQ]
     def blink
       self.fade_out(duration: 0.2, after: lambda {|did_finish, rmq| rmq.animations.fade_in(duration: 0.2)})
     end
 
+    # @return [RMQ]
     def start_spinner(style = UIActivityIndicatorViewStyleGray)
       spinner = Animations.window_spinner(style)
       spinner.startAnimating
       @rmq.create_rmq_in_context(spinner)
     end
 
+    # @return [RMQ]
     def stop_spinner
       spinner = Animations.window_spinner
       spinner.stopAnimating
       @rmq.create_rmq_in_context(spinner)
     end
 
+    protected 
+
     def self.window_spinner(style = UIActivityIndicatorViewStyleGray)
       @_window_spinner ||= begin
         window = RMQ.app.window

data/motion/ruby_motion_query/app.rb

@@ -1,68 +1,71 @@
 module RubyMotionQuery
   class RMQ
+    # @return [App]
     def app
       App
     end
 
+    # @return [App]
     def self.app
       App
     end
-
-    # TODO This is a bit wierd and may not work, need to think on this
-    # It's also confusing use of rmq which assumes a controller and subviews
-    #def window_rmq
-      #RMQ.create_with_selectors([App.window], self.context)
-    #end
-
-    #def self.window_rmq
-      #RMQ.create_with_selectors([App.window], App.window)
-    #end
   end
 
   class App
     class << self
 
+      # @return [UIWindow]
       def window
         UIApplication.sharedApplication.keyWindow || UIApplication.sharedApplication.windows[0]
       end
 
+      # @return [UIApplicationDelegate]
       def delegate 
         UIApplication.sharedApplication.delegate
       end
 
+      # @return [Symbol] Environment the app is running it
       def environment
         RUBYMOTION_ENV.to_sym
       end
 
+      # @return [Boolean] true if the app is running in the :release environment
       def release?
         environment == :release
       end
       alias :production? :release?
 
+      # @return [Boolean] true if the app is running in the :test environment
       def test?
         environment == :test
       end
 
+      # @return [Boolean] true if the app is running in the :development environment
       def development?
         environment == :development
       end
 
+      # @return [String] Version
       def version
         NSBundle.mainBundle.infoDictionary['CFBundleVersion']
       end
 
+      # @return [String] Name of app
       def name
         NSBundle.mainBundle.objectForInfoDictionaryKey 'CFBundleDisplayName'
       end
 
+      # @return [String] Identifier of app
       def identifier
         NSBundle.mainBundle.bundleIdentifier
       end
 
+      # @return [String] Full path of the resources folder
       def resource_path
         NSBundle.mainBundle.resourcePath
       end
 
+      # @return [String] Full path of the document folder
       def document_path
         NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, true)[0]
       end

data/motion/ruby_motion_query/base.rb

@@ -1,4 +1,20 @@
 module RubyMotionQuery
+
+  # The main class for RubyMotionQuery
+  #
+  # What's an rmq instance?
+  # - an rmq instance is an array-like object containing UIViews
+  # - rmq() never returns nil. If nothing is selected, it's an empty [ ] array-like
+  #   object   
+  # - an rmq object always (almost always) returns either itself or a new
+  #   rmq object. This is  how chaining works. You do not need to worry if
+  #   an rmq is blank or not, everything  always works without throwing a
+  #   nil exception
+  # - jQuery uses the DOM, what is rmq using for the "DOM"? It uses the
+  #   controller it was  called in. The "DOM" is the controller's subview
+  #   tree. If you call rmq inside a view, it will  attach to the
+  #   controller that the view is currently in or to the current screen's
+  #   controller
   class RMQ
     attr_accessor :context, :parent_rmq
 
@@ -6,10 +22,17 @@ module RubyMotionQuery
       @selected_dirty = true
     end
 
+    # Do not use
     def selected=(value)
       @_selected = value
       @selected_dirty = false
     end
+
+    # The UIViews currently selected
+    #
+    # Use {#get} instead to get the actual UIView objects
+    #
+    # @return [Array]
     def selected
       if @selected_dirty
         @_selected = []
@@ -39,6 +62,8 @@ module RubyMotionQuery
     end
 
     # The view(s) this rmq was derived from
+    #
+    # @return [Array]
     def origin_views
       if @parent_rmq
         @parent_rmq.selected
@@ -51,7 +76,15 @@ module RubyMotionQuery
     # Normally used to get the only view in selected.
     #
     # @example
-    # rmq(foo).parent.get.some_method_on_parent
+    #   # returns my_view
+    #   rmq(my_view).get
+    #
+    #   # returns an array
+    #   rmq(UILabel).get
+    #
+    #   rmq(foo).parent.get.some_method_on_parent
+    #
+    # @return [UIView or Array]
     def get
       sel = self.selected
       if sel.length == 1
@@ -61,10 +94,21 @@ module RubyMotionQuery
       end
     end
 
+    # Is this rmq a root instance? 
+    #
+    # Which means it only has 1 selected view, and that view
+    # is the view you called rmq in. Which is a tad confusing, but if you call *just* rmq inside a 
+    # view, then only that view will be *selected* and this rmq will be *root*. If you call rmq
+    # inside a controller, only controller.view will be selected and the rma instance will be a root.
     def root?
       (selected.length == 1) && (selected.first == @context)
     end
 
+    # The context is where rmq was created (not the selectors). 
+    #
+    # Normally you are inside a controller or a UIView when you execute the rmq method. 
+    #
+    # @return [UIView] the controller's view or the view you are in when calling rmq
     def context_or_context_view
       if @context.is_a?(UIViewController)
         @context.view
@@ -73,45 +117,50 @@ module RubyMotionQuery
       end
     end
 
-    def extract_views_from_selectors(view_container, working_selectors)
-      unless RMQ.is_blank?(working_selectors)
-        working_selectors.each do |selector|
-          if selector.is_a?(UIView)
-            view_container << working_selectors.delete(selector)
-          end
-        end
-      end
-      [view_container, working_selectors]
-    end
-
-    def all_subviews_for(view)
-      # TODO maybe cache this, and invalidate cache properly
-      out = []
-      if view.subviews
-        view.subviews.each do |subview|
-          out << subview
-          out << all_subviews_for(subview)
-        end
-        out.flatten!
-      end
-
-      out
-    end
-
-    def all_superviews_for(view, out = [])
-      if (nr = view.nextResponder) && nr.is_a?(UIView)
-        out << nr
-        all_superviews_for(nr, out)
-      end     
-      out
-    end
-
+    # Changed inspect to be useful
+    #
+    # @return [String]
+    #
+    # @example
+    #   (main)> rmq.all
+    #   => RMQ 172658240. 26 selected. selectors: []. .log for more info
     def inspect
       out = "RMQ #{self.object_id}. #{self.count} selected. selectors: #{self.selectors.to_s}. .log for more info"
       out << "\n[#{selected.first}]" if self.count == 1
       out
     end
 
+    # Super useful in the console. log outputs to the console a table of the selected views
+    #
+    # @param :wide outputs wide format (really wide, but awesome: rmq.all.log :wide)
+    #
+    # @return [String]
+    #
+    # @example
+    #    (main)> rmq(UIImageView).log
+    #
+    #    object_id   | class                 | style_name              | frame                           |
+    #    sv id       | superview             | subviews count          | tags                            |
+    #    - - - - - - | - - - - - - - - - - - | - - - - - - - - - - - - | - - - - - - - - - - - - - - - - |
+    #    168150976   | UIImageView           | logo                    | {l: 60, t: 10, w: 200, h: 95.5} |
+    #    168128784   | UIView                | 0                       |                                 |
+    #    - - - - - - | - - - - - - - - - - - | - - - - - - - - - - - - | - - - - - - - - - - - - - - - - |
+    #    168180640   | UIImageView           |                         | {l: 1, t: 1, w: 148, h: 19}     |
+    #    168173616   | UIRoundedRectButton   | 0                       |                                 |
+    #    - - - - - - | - - - - - - - - - - - | - - - - - - - - - - - - | - - - - - - - - - - - - - - - - |
+    #    168204336   | UIImageView           |                         | {l: 1, t: 0, w: 77, h: 27}      |
+    #    168201952   | _UISwitchInternalView | 0                       |                                 |
+    #    - - - - - - | - - - - - - - - - - - | - - - - - - - - - - - - | - - - - - - - - - - - - - - - - |
+    #    172600352   | UIImageView           |                         | {l: -2, t: 0, w: 79, h: 27}     |
+    #    168204512   | UIView                | 0                       |                                 |
+    #    - - - - - - | - - - - - - - - - - - | - - - - - - - - - - - - | - - - - - - - - - - - - - - - - |
+    #    168205504   | UIImageView           |                         | {l: -2, t: 0, w: 131, h: 27}    |
+    #    168204512   | UIView                | 0                       |                                 |
+    #    - - - - - - | - - - - - - - - - - - | - - - - - - - - - - - - | - - - - - - - - - - - - - - - - |
+    #    168205600   | UIImageView           |                         | {l: 49, t: 0, w: 29, h: 27}     |
+    #    168204512   | UIView                | 0                       |                                 |
+    #    - - - - - - | - - - - - - - - - - - | - - - - - - - - - - - - | - - - - - - - - - - - - - - - - |
+    #    RMQ 278442176. 6 selected. selectors: [UIImageView]#
     def log(opt = nil)
       wide = (opt == :wide)
       out =  "\n object_id   | class                 | style_name              | frame                           |"
@@ -157,5 +206,40 @@ module RubyMotionQuery
       attr_accessor :cache_controller_rmqs
       @cache_controller_rmqs = true
     end
+
+    protected 
+    def extract_views_from_selectors(view_container, working_selectors)
+      unless RMQ.is_blank?(working_selectors)
+        working_selectors.each do |selector|
+          if selector.is_a?(UIView)
+            view_container << working_selectors.delete(selector)
+          end
+        end
+      end
+      [view_container, working_selectors]
+    end
+
+    def all_subviews_for(view)
+      # TODO maybe cache this, and invalidate cache properly
+      out = []
+      if view.subviews
+        view.subviews.each do |subview|
+          out << subview
+          out << all_subviews_for(subview)
+        end
+        out.flatten!
+      end
+
+      out
+    end
+
+    def all_superviews_for(view, out = [])
+      if (nr = view.nextResponder) && nr.is_a?(UIView)
+        out << nr
+        all_superviews_for(nr, out)
+      end     
+      out
+    end
+
   end
 end