ruby_motion_query 0.1.1 → 0.2.0

data/motion/ruby_motion_query/selectors.rb

@@ -1,15 +1,24 @@
 module RubyMotionQuery
   class RMQ
 
+    # Do not use
     def selectors=(value)
       @selected_dirty = true
       normalize_selectors(value)
       @_selectors = value
     end
+
+    # @return [Array] The selectors, which is what you used for the query
+    # @example
+    #  (main)> rmq(UILabel, UIImageView).selectors
+    #  => [UILabel, UIImageView] 
     def selectors
       @_selectors
     end
 
+
+    protected 
+
     def match_context(new_selectors)
       match(context_or_context_view, new_selectors)
     end

data/motion/ruby_motion_query/stylesheet.rb

@@ -1,5 +1,7 @@
 module RubyMotionQuery
   class RMQ
+
+    # @return [RMQ]
     def stylesheet=(value)
       controller = view_controller
       unless value.is_a?(RubyMotionQuery::Stylesheet)
@@ -8,12 +10,15 @@ module RubyMotionQuery
       controller.rmq_data.stylesheet = value
       self
     end
+
+    # @return [String]
     def stylesheet
       @_stylesheet ||= begin
         self.view_controller.rmq_data.stylesheet if self.view_controller
       end
     end
 
+    # @return [RMQ]
     def apply_style(style_name)
       selected.each do |selected_view|
         apply_style_to_view selected_view, style_name
@@ -21,6 +26,7 @@ module RubyMotionQuery
       self
     end
 
+    # @return [RMQ]
     def style()
       selected.each do |view|
         yield(styler_for(view))
@@ -28,12 +34,14 @@ module RubyMotionQuery
       self
     end
 
+    # @return [RMQ]
     def reapply_styles
       selected.each do |selected_view|
         if style_name = selected_view.rmq_data.style_name
         apply_style_to_view selected_view, style_name
         end
       end
+      self
     end
 
     def styler_for(view)
@@ -41,7 +49,6 @@ module RubyMotionQuery
       # memoize this, however if you do that, make sure the dev doesn't retain them in a var
       custom_stylers(view) || begin
         case view
-        # TODO, rename all the stylers to Styler::UILabel, etc
         when UILabel              then Stylers::UILabelStyler.new(view)
         when UIButton             then Stylers::UIButtonStyler.new(view)
         when UIImageView          then Stylers::UIImageViewStyler.new(view)

data/motion/ruby_motion_query/subviews.rb

@@ -2,13 +2,16 @@
 module RubyMotionQuery
   class RMQ
 
+    # @return [RMQ]
     def remove
       selected.each { |view| view.removeFromSuperview }
       self
     end
 
-    def append(view_or_constant, style = nil)
+    # @return [RMQ]
+    def add_subview(view_or_constant, opts={})
       subviews_added = []
+      style = opts[:style]
       selected.each do |selected_view|
         if view_or_constant.is_a?(UIView)
           new_view = view_or_constant
@@ -17,7 +20,13 @@ module RubyMotionQuery
         end
 
         subviews_added << new_view
-        selected_view.addSubview(new_view)
+        if at_index = opts[:at_index]
+          selected_view.insertSubview(new_view, atIndex: at_index)
+        elsif below_view = opts[:below_view]
+          selected_view.insertSubview(new_view, belowSubview: below_view)
+        else
+          selected_view.addSubview(new_view)
+        end
 
         if self.stylesheet
           apply_style_to_view(new_view, style) if style
@@ -26,10 +35,16 @@ module RubyMotionQuery
 
       RMQ.create_with_array_and_selectors(subviews_added, selectors, @context)
     end
-    alias :add_subview :append
+    alias :insert :add_subview
+
+    # @return [RMQ]
+    def append(view_or_constant, style=nil)
+      add_subview(view_or_constant, style: style)
+    end
 
-    def insert(view, at_index, style = nil)
-       # TODO
+    # @return [RMQ]
+    def unshift(view_or_constant, style = nil)
+      add_subview view_or_constant, style: style, at_index: 0
     end
 
     protected

data/motion/ruby_motion_query/tags.rb

@@ -1,6 +1,7 @@
 module RubyMotionQuery
   class RMQ
 
+    # @return [RMQ]
     def tag(*tag_or_tags)
       selected.each do |view|
         view.rmq_data.tag(tag_or_tags)

data/motion/ruby_motion_query/traverse.rb

@@ -1,7 +1,15 @@
 module RubyMotionQuery 
   class RMQ
 
-    # Most everthing uses filter to do its work
+    # Most everything uses filter to do its work. This is mostly used internally
+    # but you can use it too. Just pass a block that returns views, it will be
+    # called for every view that is *selected*
+    #
+    # @param return_array returns array not rmq: return_array: true 
+    # @param uniq removes duplicate views: uniq: true 
+    # @param limit limits the number of views *per selected view*: limit: true 
+    #
+    # @return [RMQ]
     def filter(opts = {}, &block)
       out = []
       limit = opts[:limit]
@@ -25,10 +33,20 @@ module RubyMotionQuery
       end
     end
 
+    # @return [RMQ] All selected views
+    #
+    # @example
+    #   rmq.all.log
     def all
       self.view_controller.rmq.find
     end
 
+    # @return [RMQ] A new rmq instance reducing selected views to those that match selectors provided
+    #
+    # @param selectors your selector
+    #
+    # @example
+    #   rmq(UIImage).and(:some_tag).attr(image: nil)
     def and(*working_selectors)
       return self unless working_selectors
       normalize_selectors(working_selectors)
@@ -38,6 +56,13 @@ module RubyMotionQuery
       end
     end
 
+    # @return [RMQ] A new rmq instance removing selected views that match selectors provided
+    #
+    # @param selectors
+    #
+    # @example
+    #   # Entire family of labels from siblings on down
+    #   rmq(my_label).parent.find(UILabel).not(my_label).move(left: 10)
     def not(*working_selectors)
       return self unless working_selectors
       normalize_selectors(working_selectors)
@@ -47,10 +72,10 @@ module RubyMotionQuery
       end
     end
 
-    # Return any selected that has a child that matches the selectors
-    #def has
-    #end
-
+    # @return [RMQ] A new rmq instance adding the context to the selected views
+    #
+    # @example
+    #   rmq(my_view).children.and_self
     def and_self
       if @parent_rmq
         out = @parent_rmq.selected.dup
@@ -63,15 +88,30 @@ module RubyMotionQuery
     end
     alias :add_self :and_self
     
+    # @return [RMQ] The parent rmq instance 
+    #
+    # @example
+    #   rmq(test_view).find(UIImageView).tag(:foo).end.find(UILabel).tag(:bar)
     def end
       @parent_rmq || self
     end
 
+    # @return [RMQ] rmq instance selecting the parent of the selected view(s)
+    #
+    # @example
+    #   rmq(my_view).parent.find(:delete_button).toggle_enabled
     def parent
       closest(UIView)
     end
     alias :superview :parent
 
+    # @return [RMQ] Instance selecting the parents, grandparents, etc, all the way up the tree 
+    # of the selected view(s)
+    #
+    # @param selectors
+    #
+    # @example
+    #   rmq(my_view).parents.log
     def parents(*working_selectors)
       normalize_selectors(working_selectors)
 
@@ -90,6 +130,14 @@ module RubyMotionQuery
     end
     alias :superviews :parents
 
+    # Get the descendants of each view in the current set of selected views, filtered by a selector(s)
+    #
+    # @return [RMQ] Instance selecting the children, grandchildren, etc of the selected view(s)
+    #
+    # @param selectors
+    #
+    # @example
+    #   rmq(my_view).find(UIButton).show
     def find(*working_selectors)
       normalize_selectors(working_selectors)
 
@@ -107,6 +155,12 @@ module RubyMotionQuery
       end
     end
 
+    # @return [RMQ] Instance selecting the children of the selected view(s)
+    #
+    # @param selectors
+    #
+    # @example
+    #   rmq(my_view).children.show
     def children(*working_selectors)
       normalize_selectors(working_selectors)
 
@@ -125,19 +179,65 @@ module RubyMotionQuery
     end
     alias :subviews :children
 
+
+    # @return [RMQ] Siblings of the selected view(s)
+    #
+    # @param selectors
+    #
+    # @example
+    #   rmq(my_view).siblings.send(:poke)
     def siblings(*working_selectors)
       normalize_selectors(working_selectors)
 
       self.parent.children.not(selected)
     end
 
-    # TODO
-    #def next(*working_selectors)
-    #end
-    #def prev(*working_selectors)
-    #end
+
+    # @return [RMQ] Sibling above to the selected view(s)
     #
+    # @param selectors
+    #
+    # @example
+    #   rmq(my_view).next(UITextField).focus
+    def next(*working_selectors)
+      normalize_selectors(working_selectors)
+
+      filter do |view|
+        subs = view.superview.subviews
+        location = subs.index(view)
+        if location < subs.length - 1
+          subs[location + 1]
+        end
+      end
+    end
+
+    # @return [RMQ] Sibling below to the selected view(s)
+    #
+    # @param selectors
+    #
+    # @example
+    #   rmq(my_view).prev(UITextField).focus
+    def prev(*working_selectors)
+      normalize_selectors(working_selectors)
 
+      filter do |view|
+        subs = view.superview.subviews
+        location = subs.index(view)
+        if location > 0
+          subs[location - 1]
+        end
+      end
+    end
+
+    # For each selected view, get the first view that matches the selector(s) by testing the view's parent and 
+    # traversing up through its ancestors in the tree
+    #
+    # @return [RMQ] Instance selecting the first parent or grandparent or ancestor up the tree of the selected view(s)
+    #
+    # @param selectors
+    #
+    # @example
+    #   rmq.closest(UIScrollView).get.setContentOffset([0,0])
     def closest(*working_selectors)
       normalize_selectors(working_selectors)
 
@@ -146,6 +246,10 @@ module RubyMotionQuery
       end
     end
 
+    # @return [UIViewController] Controller of this rmq instance
+    #
+    # @example
+    #   rmq.view_controller
     def view_controller
       @_view_controller ||= begin
         if @context.is_a?(UIViewController)
@@ -156,6 +260,10 @@ module RubyMotionQuery
       end
     end
 
+    # @return [UIView] Root view of this rmq instance's controller
+    #
+    # @example
+    #   rmq.root_view
     def root_view
       vc = self.view_controller
       if RMQ.is_blank?(vc)

data/motion/ruby_motion_query/utils.rb

@@ -2,6 +2,7 @@ module RubyMotionQuery
   class RMQ
 
     class << self
+      # @return [Boolean]
       def is_class?(o)
         # This line fails in spec, causes exit without message. It works fine in production
         #(o.class == Class) && (defined?(o) == 'constant')
@@ -12,6 +13,8 @@ module RubyMotionQuery
 
       # This is purposely not blank? as to not conflict with many libraries that
       # add .blank? to Object
+      #
+      # @return [Boolean]
       def is_blank?(o)
         if o.is_a?(RubyMotionQuery::RMQ)
           RubyMotionQuery::RMQ.is_blank?(o.to_a)
@@ -20,9 +23,8 @@ module RubyMotionQuery
         end
       end
 
- 
-      # Given a UIView, returns the UIViewController it is sitting in, or nil if it's not
-      # sitting anywhere in particular 
+      # @param view
+      # @return [UIViewController] The controller the view it is sitting in, or nil if it's not sitting anywhere in particular 
       def controller_for_view(view)
         # Non-recursive for speed
         while view
@@ -38,6 +40,8 @@ module RubyMotionQuery
       end
 
       # Mainly used for console and logging
+      #
+      # @return [String]
       def view_to_s(view)
         out = "\n"
         out << "  VIEW  class:o #{view.class.name}  object_id: #{view.object_id}\n"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_motion_query
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Todd Werth
@@ -9,8 +9,36 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-30 00:00:00.000000000 Z
-dependencies: []
+date: 2013-08-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bacon
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: RubyMotionQuery - RMQ - A light, nonpolluting, jQuery-like library for
   RubyMotion
 email: todd@infinitered.com
@@ -87,3 +115,4 @@ signing_key:
 specification_version: 4
 summary: RubyMotionQuery - RMQ
 test_files: []
+has_rdoc: