mouse 0.0.1 → 0.1.0

data/History.markdown

@@ -1,10 +1,24 @@
+# 0.1.0 - The basic API
+
+  * Fixed animation timing (sleep(3) type coercion issue)
+
+  * Added `Mouse#click_down`
+  * Added `Mouse#click_up`
+  * Added `Mouse#click`
+  * Added `Mouse#secondary_click`
+  * Added `Mouse#arbitrary_click`
+  * Added `Mouse#middle_click`
+  * Added `Mouse#multi_click`
+  * Added `Mouse#double_click`
+  * Added `Mouse#triple_click`
+
 # 0.0.1 - Initial Release
 
   * CRuby and MacRuby compatible
 
-  * Added Mouse.current_position
-  * Added Mouse.move_to
-  * Added Mouse.drag_to
-  * Added Mouse.scroll
-  * Added CGPoint on CRuby to mimic CGPoint in MacRuby
-  * Added Array#to_point to mimic MacRuby allowing Arrays for structs
+  * Added `Mouse.current_position`
+  * Added `Mouse.move_to`
+  * Added `Mouse.drag_to`
+  * Added `Mouse.scroll`
+  * Added `CGPoint` on CRuby to mimic `CGPoint` in MacRuby
+  * Added `Array#to_point` to mimic MacRuby allowing Arrays for structs

data/README.markdown

@@ -4,7 +4,9 @@ A port of mouse.rb from [AXElements](http://github.com/Marketcircle/AXElements),
 but cleaned up and rewritten in C to be more portable across languages and
 runtimes.
 
-Not much to see right now.
+## Examples
+
+TODO :P
 
 ## Copyright
 
@@ -34,5 +36,3 @@ INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
 IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-

data/ext/mouse/mouse.c

@@ -41,8 +41,8 @@ rb_mouse_unwrap_point(VALUE point)
 #endif
 }
 
-/***
- * Returns the current co-ordinates of the Mouse
+/*
+ * Returns the current co-ordinates of the mouse cursor
  *
  * @return [CGPoint]
  */
@@ -53,8 +53,8 @@ rb_mouse_current_position(VALUE self)
   return CURRENT_POSITION;
 }
 
-/***
- * Move the cursor to the given co-ordinates
+/*
+ * Move the mouse cursor to the given co-ordinates
  *
  * @param point [CGPoint,Array(Number,Number),#to_point]
  * @return [CGPoint]
@@ -67,8 +67,8 @@ rb_mouse_move_to(VALUE self, VALUE point)
   return CURRENT_POSITION;
 }
 
-/***
- * Drag the cursor to the given co-ordinates
+/*
+ * Drag the mouse cursor to the given co-ordinates
  *
  * @param point [CGPoint,Array(Number,Number),#to_point]
  * @return [CGPoint]
@@ -81,11 +81,13 @@ rb_mouse_drag_to(VALUE self, VALUE point)
   return CURRENT_POSITION;
 }
 
-/***
+/*
  * Generate `amount` scroll events at the current cursor position
  *
+ * Returns number of lines scrolled.
+ *
  * @param amount [Number]
- * @return [CGPoint]
+ * @return [Number]
  */
 static
 VALUE
@@ -93,24 +95,198 @@ rb_mouse_scroll(VALUE self, VALUE amount)
 {
   amount = rb_funcall(amount, sel_to_i, 0);
   mouse_scroll(NUM2SIZET(amount));
+  return amount;
+}
+
+/*
+ * Generate the down click part of a click event at the current position
+ *
+ * This might be useful in concert with {Mouse.click_up} if you want
+ * to inject some behaviour between the down and up click events.
+ *
+ * @return [CGPoint]
+ */
+static
+VALUE
+rb_mouse_click_down(VALUE self)
+{
+  mouse_click_down();
+  return CURRENT_POSITION;
+}
+
+/*
+ * Generate the up click part of a click event at the current position
+ *
+ * This might be useful in concert with {Mouse.click_down} if you want
+ * to inject some behaviour between the down and up click events.
+ *
+ * @return [CGPoint]
+ */
+static
+VALUE
+rb_mouse_click_up(VALUE self)
+{
+  mouse_click_up();
+  return CURRENT_POSITION;
+}
+
+/*
+ * Generate a regular click event at the current mouse position
+ *
+ * @return [CGPoint]
+ */
+static
+VALUE
+rb_mouse_click(VALUE self)
+{
+  mouse_click();
+  return CURRENT_POSITION;
+}
+
+/*
+ * Generate a secondary click at the current mouse position
+ *
+ * Secondary click is often referred to as "right click".
+ *
+ * @return [CGPoint]
+ */
+static
+VALUE
+rb_mouse_secondary_click(VALUE self)
+{
+  mouse_secondary_click();
+  return CURRENT_POSITION;
+}
+
+/*
+ * Generate a click using an arbitrary mouse button at the current position
+ *
+ * Numbers are used to map the mouse buttons. At the time of writing,
+ * the documented values are:
+ *
+ *  - `kCGMouseButtonLeft   = 0`
+ *  - `kCGMouseButtonRight  = 1`
+ *  - `kCGMouseButtonCenter = 2`
+ *
+ * And the rest are not documented! Though they should be easy enough
+ * to figure out. See the `CGMouseButton` enum in the reference
+ * documentation for the most up to date list.
+ *
+ * @param button [Number,#to_i]
+ * @return [CGPoint]
+ */
+static
+VALUE
+rb_mouse_arbitrary_click(VALUE self, VALUE button)
+{
+  button = rb_funcall(button, sel_to_i, 0);
+  mouse_arbitrary_click(NUM2UINT(button));
+  return CURRENT_POSITION;
+}
+
+/*
+ * Generate a click event for the middle mouse button at the current position
+ *
+ * It doesn't matter if you don't have a middle mouse button.
+ *
+ * @return [CGPoint]
+ */
+static
+VALUE
+rb_mouse_middle_click(VALUE self)
+{
+  mouse_middle_click();
+  return CURRENT_POSITION;
+}
+
+/*
+ * Generate a multi-click event at the current mouse position
+ *
+ * Unlike {Mouse.double_click} and {Mouse.triple_click} this will generate
+ * a single event with the given number of clicks.
+ *
+ * @param num_clicks [Number,#to_i]
+ * @return [CGPoint]
+ */
+static
+VALUE
+rb_mouse_multi_click(VALUE self, VALUE num_clicks)
+{
+  // TODO: there has got to be a more idiomatic way to do this coercion
+  num_clicks = rb_funcall(num_clicks, sel_to_i, 0);
+  mouse_multi_click(NUM2SIZET(num_clicks));
+  return CURRENT_POSITION;
+}
+
+/*
+ * Perform a double click at the given mouse position
+ *
+ * Implemented by first generating a single click, and then a double click.,
+ * Apps seem to respond more consistently to this behaviour since that is
+ * how a human would have to generate a double click event.
+ *
+ * @return [CGPoint]
+ */
+static
+VALUE
+rb_mouse_double_click(VALUE self)
+{
+  mouse_double_click();
+  return CURRENT_POSITION;
+}
+
+/*
+ * Perform a triple click at the given mouse position
+ *
+ * Implemented by first generating a single click, then a double click,
+ * and finally a triple click. Apps seem to respond more consistently to
+ * this behaviour since that is how a human would have to generate a
+ * triple click event.
+ *
+ * @return [CGPoint]
+ */
+static
+VALUE
+rb_mouse_triple_click(VALUE self)
+{
+  mouse_triple_click();
   return CURRENT_POSITION;
 }
 
 void
 Init_mouse()
 {
+  // on either supported Ruby, this should be defined by now
   rb_cCGPoint = rb_const_get(rb_cObject, rb_intern("CGPoint"));
-  sel_x = rb_intern("x");
-  sel_y = rb_intern("y");
+
+  sel_x        = rb_intern("x");
+  sel_y        = rb_intern("y");
   sel_to_point = rb_intern("to_point");
   sel_to_i     = rb_intern("to_i");
-  sel_new = rb_intern("new");
+  sel_new      = rb_intern("new");
 
+  /*
+   * Document-module: Mouse
+   *
+   * Herp Derp TODO
+   *
+   * [Reference](http://developer.apple.com/library/mac/#documentation/Carbon/Reference/QuartzEventServicesRef/Reference/reference.html)
+   */
   rb_mMouse = rb_define_module("Mouse");
+
   rb_funcall(rb_mMouse, rb_intern("extend"), 1, rb_mMouse);
 
   rb_define_method(rb_mMouse, "current_position", rb_mouse_current_position, 0);
   rb_define_method(rb_mMouse, "move_to",          rb_mouse_move_to,          1);
   rb_define_method(rb_mMouse, "drag_to",          rb_mouse_drag_to,          1);
   rb_define_method(rb_mMouse, "scroll",           rb_mouse_scroll,           1);
+  rb_define_method(rb_mMouse, "click_down",       rb_mouse_click_down,       0);
+  rb_define_method(rb_mMouse, "click_up",         rb_mouse_click_up,         0);
+  rb_define_method(rb_mMouse, "click",            rb_mouse_click,            0);
+  rb_define_method(rb_mMouse, "secondary_click",  rb_mouse_secondary_click,  0);
+  rb_define_method(rb_mMouse, "arbitrary_click",  rb_mouse_arbitrary_click,  1);
+  rb_define_method(rb_mMouse, "middle_click",     rb_mouse_middle_click,     0);
+  rb_define_method(rb_mMouse, "multi_click",      rb_mouse_multi_click,      1);
+  rb_define_method(rb_mMouse, "double_click",     rb_mouse_double_click,     0);
+  rb_define_method(rb_mMouse, "triple_click",     rb_mouse_triple_click,     0);
 }

data/ext/mouse/mouser.c

@@ -9,8 +9,8 @@
 #include <ApplicationServices/ApplicationServices.h>
 #include "mouser.h"
 
-static const double FPS              = 120.0;
-static const double QUANTUM          = 1 / 120; // Should be (1 / FPS), but gcc sucks
+static const uint_t FPS              = 120;
+static const uint_t QUANTUM          = 1000000 / 120; // should be FPS, but GCC sucks
 static const double DEFAULT_DURATION = 0.2; // seconds
 
 #define NEW_EVENT(type,point,button) CGEventCreateMouseEvent(nil,type,point,button)
@@ -35,9 +35,9 @@ static const double DEFAULT_DURATION = 0.2; // seconds
 
 static
 void
-mouse_sleep(size_t quanta)
+mouse_sleep(uint_t quanta)
 {
-  sleep(quanta * QUANTUM);
+  usleep(quanta * QUANTUM);
 }
 
 CGPoint
@@ -175,7 +175,7 @@ mouse_scroll(size_t amount)
 
 
 void
-mouse_click_down3(CGPoint point, size_t sleep_quanta)
+mouse_click_down3(CGPoint point, uint_t sleep_quanta)
 {
   POSTRELEASE(NEW_EVENT(kCGEventLeftMouseDown, point, kCGMouseButtonLeft));
   mouse_sleep(sleep_quanta);
@@ -223,7 +223,7 @@ mouse_click()
 
 
 void
-mouse_secondary_click3(CGPoint point, size_t sleep_quanta)
+mouse_secondary_click3(CGPoint point, uint_t sleep_quanta)
 {
   CGEventRef base_event = NEW_EVENT(
 				    kCGEventRightMouseDown,
@@ -252,7 +252,7 @@ mouse_secondary_click()
 
 
 void
-mouse_arbitrary_click3(CGEventMouseSubtype button, CGPoint point, size_t sleep_quanta)
+mouse_arbitrary_click3(CGEventMouseSubtype button, CGPoint point, uint_t sleep_quanta)
 {
   CGEventRef base_event = NEW_EVENT(
 				    kCGEventOtherMouseDown,

data/ext/mouse/mouser.h

@@ -8,6 +8,8 @@
 
 #include <ApplicationServices/ApplicationServices.h>
 
+typedef unsigned int uint_t;
+
 enum MouseMovementUnit {
   kMouseScrollByLine  = kCGScrollEventUnitLine,
   // TODO: might not be real pixels, might be Cocoa co-ords, need to investigate
@@ -29,7 +31,7 @@ void mouse_scroll3(size_t amount, enum MouseMovementUnit units, double duration)
 
 void mouse_click_down();
 void mouse_click_down2(CGPoint point);
-void mouse_click_down3(CGPoint point, size_t sleep_quanta);
+void mouse_click_down3(CGPoint point, uint_t sleep_quanta);
 
 void mouse_click_up();
 void mouse_click_up2(CGPoint point);
@@ -39,11 +41,11 @@ void mouse_click2(CGPoint point);
 
 void mouse_secondary_click();
 void mouse_secondary_click2(CGPoint point);
-void mouse_secondary_click3(CGPoint point, size_t sleep_quanta);
+void mouse_secondary_click3(CGPoint point, uint_t sleep_quanta);
 
 void mouse_arbitrary_click(CGEventMouseSubtype button);
 void mouse_arbitrary_click2(CGEventMouseSubtype button, CGPoint point);
-void mouse_arbitrary_click3(CGEventMouseSubtype button, CGPoint point, size_t sleep_quanta);
+void mouse_arbitrary_click3(CGEventMouseSubtype button, CGPoint point, uint_t sleep_quanta);
 
 void mouse_middle_click();
 void mouse_middle_click2(CGPoint point);

data/lib/mouse.rb

@@ -1,12 +1,22 @@
 if RUBY_ENGINE == 'macruby'
 
+  # A workaround that guarantees that `CGPoint` is defined
   framework '/System/Library/Frameworks/CoreGraphics.framework'
 
 else
 
   ##
-  #
+  # A structure that contains a point in a two-dimensional coordinate system
   class CGPoint < Struct.new(:x, :y)
+
+    # @!attribute [rw] x
+    #   The `x` co-ordinate of the screen point
+    #   @return [Number]
+
+    # @!attribute [rw] y
+    #   The `y` co-ordinate of the screen point
+    #   @return [Number]
+
     ##
     # Return a nice string representation of the point
     #
@@ -16,13 +26,11 @@ else
     def inspect
       "#<CGPoint x=#{self[:x]} y=#{self[:y]}>"
     end
+
   end
 
 end
 
-
-##
-# Mouse extensions to `CGPoint`
 class CGPoint
   ##
   # Returns the receiver, since the receiver is already a {CGPoint}

data/lib/mouse/version.rb

@@ -1,4 +1,4 @@
 module Mouse
-  VERSION = '0.0.1'
+  VERSION = '0.1.0'
 end
 

metadata

@@ -1,19 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: mouse
 version: !ruby/object:Gem::Version
+  version: 0.1.0
   prerelease: 
-  version: 0.0.1
 platform: ruby
 authors:
 - Mark Rada
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-02 00:00:00 Z
+date: 2012-12-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
-  prerelease: false
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
@@ -21,6 +20,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 0.8.3
   type: :development
+  prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
@@ -29,7 +29,6 @@ dependencies:
         version: 0.8.3
 - !ruby/object:Gem::Dependency
   name: kramdown
-  prerelease: false
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
@@ -37,6 +36,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 0.14.1
   type: :development
+  prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
@@ -45,7 +45,6 @@ dependencies:
         version: 0.14.1
 - !ruby/object:Gem::Dependency
   name: rake-compiler
-  prerelease: false
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
@@ -53,13 +52,15 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 0.8.1
   type: :development
+  prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
         version: 0.8.1
-description: 'mouse is a rich, high level wrapper around OS X CGEvent APIs that allow
+description: ! 'mouse is a rich, high level wrapper around OS X CGEvent APIs that
+  allow
 
   programmatic manipulation of the mouse cursor.
 
@@ -94,15 +95,21 @@ require_paths:
 required_ruby_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - '>='
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: "0"
+      version: '0'
+      segments:
+      - 0
+      hash: 1024147063034037924
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - '>='
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: "0"
+      version: '0'
+      segments:
+      - 0
+      hash: 1024147063034037924
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24