launchpad 0.1.0 → 0.1.1

data/.document

@@ -1,5 +1,3 @@
 README.rdoc
 lib/**/*.rb
-bin/*
-features/**/*.feature
 LICENSE

data/README.rdoc

@@ -2,7 +2,7 @@
 
 This gem provides an interface to access novation's launchpad programmatically. LEDs can be lighted and button presses can be responded to. Internally, launchpad's MIDI input/output is used to accomplish this.
 
-The interfaces should be rather stable now, so experiment with them and comment on their usability. This still is work in progress. If you need anything or think the interfaces could be improved in any way, please contact me.
+The interfaces should be rather stable now (sorry, I changed quite a bit since the last release), so experiment with them and comment on their usability. This still is work in progress. If you need anything or think the interfaces could be improved in any way, please contact me.
 
 Sometimes, the launchpad won't react to anything or react to/light up the wrong LEDs. Don't despair, just dis- and reconnect the thing. It seems that some (unexpected) MIDI signals make it hickup.
 
@@ -53,6 +53,9 @@ This is an interaction example lighting all grid buttons in red when pressed and
   interaction.response_to(:grid, :down) do |interaction, action|
     interaction.device.change(:grid, action.merge(:red => :high))
   end
+  interaction.response_to(:mixer, :down) do |interaction, action|
+    interaction.stop
+  end
   
   interaction.start
 
@@ -62,12 +65,24 @@ For more details, see the examples. examples/color_picker.rb is the most complex
 
 == Near future plans
 
-* close devices properly as soon as halfbyte's pulled my changes to portmidi
 * interaction responses for presses on single grid buttons/button areas
 * double buffering
 * bitmap rendering
 
 
+== Changelog
+
+=== v0.1.1
+
+* ability to close device/interaction to free portmidi resources
+* ability to initialize devices using device ids as well as device names
+* complete documentation for http://rdoc.info/projects/thomasjachmann/launchpad
+
+=== v0.1.0
+
+* first feature complete version with kinda stable API
+
+
 == Copyright
 
 Copyright (c) 2009 Thomas Jachmann. See LICENSE for details.

data/Rakefile

@@ -13,6 +13,7 @@ begin
     gem.homepage = 'http://github.com/thomasjachmann/launchpad'
     gem.version = Launchpad::VERSION
     gem.authors = ['Thomas Jachmann']
+    gem.has_rdoc = true
     gem.add_dependency('portmidi')
     gem.add_development_dependency('thoughtbot-shoulda', '>= 0')
     gem.add_development_dependency('mocha')

data/launchpad.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{launchpad}
-  s.version = "0.1.0"
+  s.version = "0.1.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Thomas Jachmann"]
-  s.date = %q{2009-11-13}
+  s.date = %q{2009-11-18}
   s.description = %q{This gem provides an interface to access novation's launchpad programmatically. LEDs can be lighted and button presses can be evaluated using launchpad's MIDI input/output.}
   s.email = %q{tom.j@gmx.net}
   s.extra_rdoc_files = [

data/lib/launchpad.rb

@@ -1,2 +1,34 @@
 require 'launchpad/device'
 require 'launchpad/interaction'
+
+# All the fun of launchpad in one module!
+# 
+# See Launchpad::Device for basic access to launchpad input/ouput
+# and Launchpad::Interaction for advanced interaction features.
+# 
+# The following parameters will be used throughout the library, so here are the ranges:
+# 
+# [+type+]              type of the button, one of
+#                       <tt>
+#                       :grid,
+#                       :up, :down, :left, :right, :session, :user1, :user2, :mixer,
+#                       :scene1 - :scene8
+#                       </tt>
+# [<tt>x/y</tt>]        x/y coordinate (used when type is set to :grid),
+#                       <tt>0-7</tt> (from left to right/top to bottom),
+#                       mandatory when +type+ is set to <tt>:grid</tt>
+# [<tt>red/green</tt>]  brightness of the red/green LED,
+#                       can be set to one of four levels:
+#                       * off (<tt>:off, 0</tt>)
+#                       * low brightness (<tt>:low, :lo, 1</tt>)
+#                       * medium brightness (<tt>:medium, :med, 2</tt>)
+#                       * full brightness (<tt>:high, :hi, 3</tt>)
+#                       optional, defaults to <tt>:off</tt>
+# [+mode+]              button mode,
+#                       one of
+#                       * <tt>:normal</tt>
+#                       * <tt>:flashing</tt> (LED is marked as flashing, see Launchpad::Device.flashing_on, Launchpad::Device.flashing_off and Launchpad::Device.flashing_auto)
+#                       * <tt>:buffering</tt> (LED is written to buffer, see Launchpad::Device.start_buffering, Launchpad::Device.flush_buffer)
+#                       optional, defaults to <tt>:normal</tt>
+# [+state+]             whether the button is pressed or released, <tt>:down/:up</tt>
+module Launchpad; end

data/lib/launchpad/device.rb

@@ -6,54 +6,98 @@ require 'launchpad/version'
 
 module Launchpad
   
+  # This class is used to exchange data with the launchpad.
+  # It provides methods to light LEDs and to get information about button presses/releases.
+  # 
+  # Example:
+  # 
+  #   require 'rubygems'
+  #   require 'launchpad/device'
+  #   
+  #   device = Launchpad::Device.new
+  #   device.test_leds
+  #   sleep 1
+  #   device.reset
+  #   sleep 1
+  #   device.change :grid, :x => 4, :y => 4, :red => :high, :green => :low
   class Device
     
     include MidiCodes
     
-    # Initializes the launchpad
-    # {
-    #   :device_name  => Name of the MIDI device to use, optional, defaults to Launchpad
-    #   :input        => true/false, whether to use MIDI input for user interaction, optional, defaults to true
-    #   :output       => true/false, whether to use MIDI output for data display, optional, defaults to true
-    # }
+    # Initializes the launchpad device. When output capabilities are requested,
+    # the launchpad will be reset.
+    # 
+    # Optional options hash:
+    # 
+    # [<tt>:input</tt>]             whether to use MIDI input for user interaction,
+    #                               <tt>true/false</tt>, optional, defaults to +true+
+    # [<tt>:output</tt>]            whether to use MIDI output for data display,
+    #                               <tt>true/false</tt>, optional, defaults to +true+
+    # [<tt>:input_device_id</tt>]   ID of the MIDI input device to use,
+    #                               optional, <tt>:device_name</tt> will be used if omitted
+    # [<tt>:output_device_id</tt>]  ID of the MIDI output device to use,
+    #                               optional, <tt>:device_name</tt> will be used if omitted
+    # [<tt>:device_name</tt>]       Name of the MIDI device to use,
+    #                               optional, defaults to "Launchpad"
+    # 
+    # Errors raised:
+    # 
+    # [Launchpad::NoSuchDeviceError] when device with ID or name specified does not exist
+    # [Launchpad::DeviceBusyError] when device with ID or name specified is busy
     def initialize(opts = nil)
       opts = {
-        :device_name  => 'Launchpad',
         :input        => true,
         :output       => true
       }.merge(opts || {})
       
       Portmidi.start
       
-      if opts[:input]
-        input_device = Portmidi.input_devices.select {|device| device.name == opts[:device_name]}.first
-        raise NoSuchDeviceError.new("MIDI input device #{opts[:device_name]} doesn't exist") if input_device.nil?
-        begin
-          @input = Portmidi::Input.new(input_device.device_id)
-        rescue RuntimeError => e
-          raise DeviceBusyError.new(e)
-        end
-      end
-      
-      if opts[:output]
-        output_device = Portmidi.output_devices.select {|device| device.name == opts[:device_name]}.first
-        raise NoSuchDeviceError.new("MIDI output device #{opts[:device_name]} doesn't exist") if output_device.nil?
-        begin
-          @output = Portmidi::Output.new(output_device.device_id)
-        rescue RuntimeError => e
-          raise DeviceBusyError.new(e)
-        end
-        reset
-      end
+      @input = device(Portmidi.input_devices, Portmidi::Input, :id => opts[:input_device_id], :name => opts[:device_name]) if opts[:input]
+      @output = device(Portmidi.output_devices, Portmidi::Output, :id => opts[:output_device_id], :name => opts[:device_name]) if opts[:output]
+      reset if output_enabled?
+    end
+    
+    # Closes the device - nothing can be done with the device afterwards.
+    def close
+      @input.close unless @input.nil?
+      @input = nil
+      @output.close unless @output.nil?
+      @output = nil
     end
     
-    # Resets the launchpad - all settings are reset and all LEDs are switched off
+    # Determines whether this device has been closed.
+    def closed?
+      !(input_enabled? || output_enabled?)
+    end
+    
+    # Determines whether this device can be used to read input.
+    def input_enabled?
+      !@input.nil?
+    end
+    
+    # Determines whether this device can be used to output data.
+    def output_enabled?
+      !@output.nil?
+    end
+    
+    # Resets the launchpad - all settings are reset and all LEDs are switched off.
+    # 
+    # Errors raised:
+    # 
+    # [Launchpad::NoOutputAllowedError] when output is not enabled
     def reset
       output(Status::CC, Status::NIL, Status::NIL)
     end
     
-    # Lights all LEDs (for testing purposes)
-    # takes an optional parameter brightness (:off/:low/:medium/:high, defaults to :high)
+    # Lights all LEDs (for testing purposes).
+    # 
+    # Parameters (see Launchpad for values):
+    # 
+    # [+brightness+] brightness of both LEDs for all buttons
+    # 
+    # Errors raised:
+    # 
+    # [Launchpad::NoOutputAllowedError] when output is not enabled
     def test_leds(brightness = :high)
       brightness = brightness(brightness)
       if brightness == 0
@@ -63,27 +107,52 @@ module Launchpad
       end
     end
     
-    # Changes a single LED
-    # type   => one of :grid, :up, :down, :left, :right, :session, :user1, :user2, :mixer, :scene1 - :scene8
-    # opts => {
-    #   :x      => x coordinate (0 based from top left, mandatory if type is :grid)
-    #   :y      => y coordinate (0 based from top left, mandatory if type is :grid)
-    #   :red    => brightness of red LED (0-3, optional, defaults to 0)
-    #   :green  => brightness of red LED (0-3, optional, defaults to 0)
-    #   :mode   => button behaviour (:normal, :flashing, :buffering, optional, defaults to :normal)
-    # }
+    # Changes a single LED.
+    # 
+    # Parameters (see Launchpad for values):
+    # 
+    # [+type+] type of the button to change
+    # 
+    # Optional options hash (see Launchpad for values):
+    # 
+    # [<tt>:x</tt>]     x coordinate
+    # [<tt>:y</tt>]     y coordinate
+    # [<tt>:red</tt>]   brightness of red LED
+    # [<tt>:green</tt>] brightness of green LED
+    # [<tt>:mode</tt>]  button mode
+    # 
+    # Errors raised:
+    # 
+    # [Launchpad::NoValidGridCoordinatesError] when coordinates aren't within the valid range
+    # [Launchpad::NoValidBrightnessError] when brightness values aren't within the valid range
+    # [Launchpad::NoOutputAllowedError] when output is not enabled
     def change(type, opts = nil)
       opts ||= {}
       status = %w(up down left right session user1 user2 mixer).include?(type.to_s) ? Status::CC : Status::ON
       output(status, note(type, opts), velocity(opts))
     end
     
-    # Changes all LEDs at once
-    # velocities is an array of arrays, each containing a
-    # color value calculated using the formula
-    # color = 16 * green + red
-    # with green and red each ranging from 0-3
-    # first the grid, then the scene buttons (top to bottom), then the top control buttons (left to right), maximum 80 values
+    # Changes all LEDs in batch mode.
+    # 
+    # Parameters (see Launchpad for values):
+    # 
+    # [+colors] an array of colors, each either being an integer or a Hash
+    #           * integer: calculated using the formula
+    #             <tt>color = 16 * green + red</tt>
+    #           * Hash:
+    #             [<tt>:red</tt>]   brightness of red LED
+    #             [<tt>:green</tt>] brightness of green LED
+    #             [<tt>:mode</tt>]  button mode
+    #           the array consists of 64 colors for the grid buttons,
+    #           8 colors for the scene buttons (top to bottom)
+    #           and 8 colors for the top control buttons (left to right),
+    #           maximum 80 values - excessive values will be ignored,
+    #           missing values will be filled with 0
+    # 
+    # Errors raised:
+    # 
+    # [Launchpad::NoValidBrightnessError] when brightness values aren't within the valid range
+    # [Launchpad::NoOutputAllowedError] when output is not enabled
     def change_all(*colors)
       # ensure that colors is at least and most 80 elements long
       colors = colors.flatten[0..79]
@@ -96,17 +165,30 @@ module Launchpad
       end
     end
     
-    # Switches LEDs marked as flashing on (when using custom timer for flashing)
+    # Switches LEDs marked as flashing on when using custom timer for flashing.
+    # 
+    # Errors raised:
+    # 
+    # [Launchpad::NoOutputAllowedError] when output is not enabled
     def flashing_on
       output(Status::CC, Status::NIL, Velocity::FLASHING_ON)
     end
     
-    # Switches LEDs marked as flashing off (when using custom timer for flashing)
+    # Switches LEDs marked as flashing off when using custom timer for flashing.
+    # 
+    # Errors raised:
+    # 
+    # [Launchpad::NoOutputAllowedError] when output is not enabled
     def flashing_off
       output(Status::CC, Status::NIL, Velocity::FLASHING_OFF)
     end
     
-    # Starts flashing LEDs marked as flashing automatically (stop by calling #flashing_on or #flashing_off)
+    # Starts flashing LEDs marked as flashing automatically.
+    # Stop flashing by calling flashing_on or flashing_off.
+    # 
+    # Errors raised:
+    # 
+    # [Launchpad::NoOutputAllowedError] when output is not enabled
     def flashing_auto
       output(Status::CC, Status::NIL, Velocity::FLASHING_AUTO)
     end
@@ -124,16 +206,21 @@ module Launchpad
     #     end
     #   end
     
-    # Reads user actions (button presses/releases) that aren't handled yet
-    # [
-    #   {
-    #     :timestamp  => integer indicating the time when the action occured
-    #     :state      => :down/:up, whether the button has been pressed or released
-    #     :type       => which button has been pressed, one of :grid, :up, :down, :left, :right, :session, :user1, :user2, :mixer, :scene1 - :scene8
-    #     :x          => x coordinate (0-7), only set when :type is :grid
-    #     :y          => y coordinate (0-7), only set when :type is :grid
-    #   }, ...
-    # ]
+    # Reads user actions (button presses/releases) that haven't been handled yet.
+    # 
+    # Returns:
+    # 
+    # an array of hashes with (see Launchpad for values):
+    # 
+    # [<tt>:timestamp</tt>] integer indicating the time when the action occured
+    # [<tt>:state</tt>]     state of the button after action
+    # [<tt>:type</tt>]      type of the button
+    # [<tt>:x</tt>]         x coordinate
+    # [<tt>:y</tt>]         y coordinate
+    # 
+    # Errors raised:
+    # 
+    # [Launchpad::NoInputAllowedError] when input is not enabled
     def read_pending_actions
       Array(input).collect do |midi_message|
         (code, note, velocity) = midi_message[:message]
@@ -175,17 +262,97 @@ module Launchpad
     
     private
     
+    # Creates input/output devices.
+    # 
+    # Parameters:
+    # 
+    # [+devices+]     array of portmidi devices
+    # [+device_type]  class to instantiate (<tt>Portmidi::Input/Portmidi::Output</tt>)
+    # 
+    # Options hash:
+    # 
+    # [<tt>:id</tt>]    id of the MIDI device to use
+    # [<tt>:name</tt>]  name of the MIDI device to use,
+    #                   only used when <tt>:id</tt> is not specified,
+    #                   defaults to "Launchpad"
+    # 
+    # Returns:
+    # 
+    # newly created device
+    # 
+    # Errors raised:
+    # 
+    # [Launchpad::NoSuchDeviceError] when device with ID or name specified does not exist
+    # [Launchpad::DeviceBusyError] when device with ID or name specified is busy
+    def device(devices, device_type, opts)
+      id = opts[:id]
+      if id.nil?
+        name = opts[:name] || 'Launchpad'
+        device = devices.select {|device| device.name == name}.first
+        id = device.device_id unless device.nil?
+      end
+      raise NoSuchDeviceError.new("MIDI device #{opts[:id] || opts[:name]} doesn't exist") if id.nil?
+      device_type.new(id)
+    rescue RuntimeError => e
+      raise DeviceBusyError.new(e)
+    end
+    
+    # Reads input from the MIDI device.
+    # 
+    # Returns:
+    # 
+    # an array of hashes with:
+    # 
+    # [<tt>:message</tt>]   an array of
+    #                       MIDI status code,
+    #                       MIDI data 1 (note),
+    #                       MIDI data 2 (velocity)
+    #                       and a fourth value
+    # [<tt>:timestamp</tt>] integer indicating the time when the MIDI message was created
+    # 
+    # Errors raised:
+    # 
+    # [Launchpad::NoInputAllowedError] when output is not enabled
     def input
       raise NoInputAllowedError if @input.nil?
       @input.read(16)
     end
     
-    def output(*args)
+    # Writes data to the MIDI device.
+    # 
+    # Parameters:
+    # 
+    # [+status+]  MIDI status code
+    # [+data1+]   MIDI data 1 (note)
+    # [+data2+]   MIDI data 2 (velocity)
+    # 
+    # Errors raised:
+    # 
+    # [Launchpad::NoOutputAllowedError] when output is not enabled
+    def output(status, data1, data2)
       raise NoOutputAllowedError if @output.nil?
-      @output.write([{:message => args, :timestamp => 0}])
+      @output.write([{:message => [status, data1, data2], :timestamp => 0}])
       nil
     end
     
+    # Calculates the MIDI data 1 value (note) for a button.
+    # 
+    # Parameters (see Launchpad for values):
+    # 
+    # [+type+] type of the button
+    # 
+    # Options hash:
+    # 
+    # [<tt>:x</tt>]     x coordinate
+    # [<tt>:y</tt>]     y coordinate
+    # 
+    # Returns:
+    # 
+    # integer to be used for MIDI data 1
+    # 
+    # Errors raised:
+    # 
+    # [Launchpad::NoValidGridCoordinatesError] when coordinates aren't within the valid range
     def note(type, opts)
       case type
       when :up      then ControlButton::UP
@@ -212,6 +379,21 @@ module Launchpad
       end
     end
     
+    # Calculates the MIDI data 2 value (velocity) for given brightness and mode values.
+    # 
+    # Options hash:
+    # 
+    # [<tt>:red</tt>]   brightness of red LED
+    # [<tt>:green</tt>] brightness of green LED
+    # [<tt>:mode</tt>]  button mode
+    # 
+    # Returns:
+    # 
+    # integer to be used for MIDI data 2
+    # 
+    # Errors raised:
+    # 
+    # [Launchpad::NoValidBrightnessError] when brightness values aren't within the valid range
     def velocity(opts)
       color = if opts.is_a?(Hash)
         red = brightness(opts[:red] || 0)
@@ -228,6 +410,15 @@ module Launchpad
       color + flags
     end
     
+    # Calculates the integer brightness for given brightness values.
+    # 
+    # Parameters (see Launchpad for values):
+    # 
+    # [+brightness+] brightness
+    # 
+    # Errors raised:
+    # 
+    # [Launchpad::NoValidBrightnessError] when brightness values aren't within the valid range
     def brightness(brightness)
       case brightness
       when 0, :off            then 0

data/lib/launchpad/errors.rb

@@ -1,31 +1,31 @@
 module Launchpad
   
-  # Generic launchpad error
+  # Generic launchpad error.
   class LaunchpadError < StandardError; end
   
-  # Error raised when the MIDI device specified doesn't exist
+  # Error raised when the MIDI device specified doesn't exist.
   class NoSuchDeviceError < LaunchpadError; end
   
-  # Error raised when the MIDI device specified is busy
+  # Error raised when the MIDI device specified is busy.
   class DeviceBusyError < LaunchpadError; end
   
   # Error raised when an input has been requested, although
-  # launchpad has been initialized without input
+  # launchpad has been initialized without input.
   class NoInputAllowedError < LaunchpadError; end
   
   # Error raised when an output has been requested, although
-  # launchpad has been initialized without output
+  # launchpad has been initialized without output.
   class NoOutputAllowedError < LaunchpadError; end
   
-  # Error raised when x/y coordinates outside of the grid
-  # or none at all were specified
+  # Error raised when <tt>x/y</tt> coordinates outside of the grid
+  # or none were specified.
   class NoValidGridCoordinatesError < LaunchpadError; end
   
-  # Error raised when wrong brightness was specified
+  # Error raised when wrong brightness was specified.
   class NoValidBrightnessError < LaunchpadError; end
   
   # Error raised when anything fails while communicating
-  # with the launchpad
+  # with the launchpad.
   class CommunicationError < LaunchpadError
     attr_accessor :source
     def initialize(e)

data/lib/launchpad/interaction.rb

@@ -2,16 +2,49 @@ require 'launchpad/device'
 
 module Launchpad
   
+  # This class provides advanced interaction features.
+  # 
+  # Example:
+  # 
+  #   require 'rubygems'
+  #   require 'launchpad'
+  #   
+  #   interaction = Launchpad::Interaction.new
+  #   interaction.response_to(:grid, :down) do |interaction, action|
+  #     interaction.device.change(:grid, action.merge(:red => :high))
+  #   end
+  #   interaction.response_to(:mixer, :down) do |interaction, action|
+  #     interaction.stop
+  #   end
+  #   
+  #   interaction.start
   class Interaction
     
-    attr_reader :device, :active
+    # Returns the Launchpad::Device the Launchpad::Interaction acts on.
+    attr_reader :device
     
-    # Initializes the launchpad interaction
-    # {
-    #   :device       => Launchpad::Device instance, optional
-    #   :device_name  => Name of the MIDI device to use, optional, defaults to Launchpad, ignored when :device is specified
-    #   :latency      => delay (in s, fractions allowed) between MIDI pulls, optional, defaults to 0.001
-    # }
+    # Returns whether the Launchpad::Interaction is active or not.
+    attr_reader :active
+    
+    # Initializes the interaction.
+    # 
+    # Optional options hash:
+    # 
+    # [<tt>:device</tt>]            Launchpad::Device to act on,
+    #                               optional, <tt>:input_device_id/:output_device_id</tt> will be used if omitted
+    # [<tt>:input_device_id</tt>]   ID of the MIDI input device to use,
+    #                               optional, <tt>:device_name</tt> will be used if omitted
+    # [<tt>:output_device_id</tt>]  ID of the MIDI output device to use,
+    #                               optional, <tt>:device_name</tt> will be used if omitted
+    # [<tt>:device_name</tt>]       Name of the MIDI device to use,
+    #                               optional, defaults to "Launchpad"
+    # [<tt>:latency</tt>]           delay (in s, fractions allowed) between MIDI pulls,
+    #                               optional, defaults to 0.001 (1ms)
+    # 
+    # Errors raised:
+    # 
+    # [Launchpad::NoSuchDeviceError] when device with ID or name specified does not exist
+    # [Launchpad::DeviceBusyError] when device with ID or name specified is busy
     def initialize(opts = nil)
       opts ||= {}
       @device = opts[:device] || Device.new(opts.merge(:input => true, :output => true))
@@ -19,7 +52,23 @@ module Launchpad
       @active = false
     end
     
-    # Starts interacting with the launchpad, blocking
+    # Closes the interaction's device - nothing can be done with the interaction/device afterwards.
+    def close
+      @device.close
+    end
+    
+    # Determines whether this interaction's device has been closed.
+    def closed?
+      @device.closed?
+    end
+    
+    # Starts interacting with the launchpad, blocking. Resets the device when
+    # the interaction was properly stopped via stop.
+    # 
+    # Errors raised:
+    # 
+    # [Launchpad::NoInputAllowedError] when input is not enabled on the interaction's device
+    # [Launchpad::CommunicationError] when anything unexpected happens while communicating with the launchpad
     def start
       @active = true
       while @active do
@@ -31,17 +80,32 @@ module Launchpad
       raise CommunicationError.new(e)
     end
     
-    # Stops interacting with the launchpad
+    # Stops interacting with the launchpad and resets it.
     def stop
       @active = false
     end
     
-    # Registers a response to one or more actions
-    # types => the type of action to respond to, one or more of :all, :grid, :up, :down, :left, :right, :session, :user1, :user2, :mixer, :scene1 - :scene8, optional, defaults to :all
-    # state => which state transition to respond to, one of :down, :up, :both, optional, defaults to :both
-    # opts => {
-    #   :exclusive => whether all other responses to the given types shall be deregistered first
-    # }
+    # Registers a response to one or more actions.
+    # 
+    # Parameters (see Launchpad for values):
+    # 
+    # [+types+] one or an array of button types to respond to,
+    #           additional value <tt>:all</tt> for all buttons
+    # [+state+] button state to respond to,
+    #           additional value <tt>:both</tt>
+    # 
+    # Optional options hash:
+    # 
+    # [<tt>:exclusive</tt>] <tt>true/false</tt>,
+    #                       whether to deregister all other responses to the specified actions,
+    #                       optional, defaults to +false+
+    # 
+    # Takes a block which will be called when an action matching the parameters occurs.
+    # 
+    # Block parameters:
+    # 
+    # [+interaction+] the interaction object that received the action
+    # [+action+]      the action received from Launchpad::Device.read_pending_actions
     def response_to(types = :all, state = :both, opts = nil, &block)
       types = Array(types)
       opts ||= {}
@@ -49,39 +113,61 @@ module Launchpad
       Array(state == :both ? %w(down up) : state).each do |state|
         types.each {|type| responses[type.to_sym][state.to_sym] << block}
       end
+      nil
     end
     
-    # Deregisters all responses to one or more actions
-    # type  => the type of response to clear, one or more of :all (not meaning "all responses" but "responses registered for type :all"), :grid, :up, :down, :left, :right, :session, :user1, :user2, :mixer, :scene1 - :scene8, optional, defaults to nil (meaning "all responses")
-    # state => which state transition to not respond to, one of :down, :up, :both, optional, defaults to :both
+    # Deregisters all responses to one or more actions.
+    # 
+    # Parameters (see Launchpad for values):
+    # 
+    # [+types+] one or an array of button types to respond to,
+    #           additional value <tt>:all</tt> for actions on all buttons
+    #           (but not meaning "all responses"),
+    #           optional, defaults to +nil+, meaning "all responses"
+    # [+state+] button state to respond to,
+    #           additional value <tt>:both</tt>
     def no_response_to(types = nil, state = :both)
       types = Array(types)
       Array(state == :both ? %w(down up) : state).each do |state|
         types.each {|type| responses[type.to_sym][state.to_sym].clear}
       end
+      nil
     end
     
-    # Responds to an action by executing all matching responses
-    # type => the type of action to respond to, one of :grid, :up, :down, :left, :right, :session, :user1, :user2, :mixer, :scene1 - :scene8
-    # state => which state transition to respond to, one of :down, :up
-    # opts => {
-    #   :x => x coordinate (0 based from top left)
-    #   :y => y coordinate (0 based from top left)
-    # }, unused unless type is :grid
+    # Responds to an action by executing all matching responses, effectively simulating
+    # a button press/release.
+    # 
+    # Parameters (see Launchpad for values):
+    # 
+    # [+type+]  type of the button to trigger
+    # [+state+] state of the button
+    # 
+    # Optional options hash (see Launchpad for values):
+    # 
+    # [<tt>:x</tt>]     x coordinate
+    # [<tt>:y</tt>]     y coordinate
     def respond_to(type, state, opts = nil)
       respond_to_action((opts || {}).merge(:type => type, :state => state))
     end
     
     private
     
+    # Returns the hash storing all responses. Keys are button types, values are
+    # hashes themselves, keys are <tt>:down/:up</tt>, values are arrays of responses.
     def responses
       @responses ||= Hash.new {|hash, key| hash[key] = {:down => [], :up => []}}
     end
     
+    # Reponds to an action by executing all matching responses.
+    # 
+    # Parameters:
+    # 
+    # [+action+]  hash containing an action from Launchpad::Device.read_pending_actions
     def respond_to_action(action)
       type = action[:type].to_sym
       state = action[:state].to_sym
       (responses[type][state] + responses[:all][state]).each {|block| block.call(self, action)}
+      nil
     end
     
   end

data/lib/launchpad/midi_codes.rb

@@ -1,7 +1,9 @@
 module Launchpad
   
+  # Module defining constants for MIDI codes.
   module MidiCodes
     
+    # Module defining MIDI status codes.
     module Status
       NIL           = 0x00
       OFF           = 0x80
@@ -10,13 +12,7 @@ module Launchpad
       CC            = 0xB0
     end
     
-    module Velocity
-      FLASHING_ON   = 0x20
-      FLASHING_OFF  = 0x21
-      FLASHING_AUTO = 0x28
-      TEST_LEDS     = 0x7C
-    end
-    
+    # Module defininig MIDI data 1 (note) codes for control buttons.
     module ControlButton
       UP            = 0x68
       DOWN          = 0x69
@@ -28,6 +24,7 @@ module Launchpad
       MIXER         = 0x6F
     end
     
+    # Module defininig MIDI data 1 (note) codes for scene buttons.
     module SceneButton
       SCENE1        = 0x08
       SCENE2        = 0x18
@@ -39,6 +36,14 @@ module Launchpad
       SCENE8        = 0x78
     end
     
+    # Module defining MIDI data 2 (velocity) codes.
+    module Velocity
+      FLASHING_ON   = 0x20
+      FLASHING_OFF  = 0x21
+      FLASHING_AUTO = 0x28
+      TEST_LEDS     = 0x7C
+    end
+    
   end
   
 end

data/lib/launchpad/version.rb

@@ -1,3 +1,3 @@
 module Launchpad
-  VERSION = '0.1.0'
+  VERSION = '0.1.1'
 end

data/test/helper.rb

@@ -19,13 +19,13 @@ end
 # mock Portmidi for tests
 module Portmidi
   
-  class DeviceError < StandardError; end
-  
   class Input
     attr_accessor :device_id
     def initialize(device_id)
       self.device_id = device_id
     end
+    def read(*args); nil; end
+    def close; nil; end
   end
   
   class Output
@@ -33,6 +33,8 @@ module Portmidi
     def initialize(device_id)
       self.device_id = device_id
     end
+    def write(*args); nil; end
+    def close; nil; end
   end
   
   def self.input_devices; mock_devices; end

data/test/test_device.rb

@@ -73,7 +73,7 @@ class TestDevice < Test::Unit::TestCase
       assert_nil d.instance_variable_get('@output')
     end
     
-    should 'initialize the correct input output devices' do
+    should 'initialize the correct input output devices when specified by name' do
       Portmidi.stubs(:input_devices).returns(mock_devices(:id => 4, :name => 'Launchpad Name'))
       Portmidi.stubs(:output_devices).returns(mock_devices(:id => 5, :name => 'Launchpad Name'))
       d = Launchpad::Device.new(:device_name => 'Launchpad Name')
@@ -83,6 +83,16 @@ class TestDevice < Test::Unit::TestCase
       assert_equal 5, output.device_id
     end
     
+    should 'initialize the correct input output devices when specified by id' do
+      Portmidi.stubs(:input_devices).returns(mock_devices(:id => 4))
+      Portmidi.stubs(:output_devices).returns(mock_devices(:id => 5))
+      d = Launchpad::Device.new(:input_device_id => 4, :output_device_id => 5, :device_name => 'nonexistant')
+      assert_equal Portmidi::Input, (input = d.instance_variable_get('@input')).class
+      assert_equal 4, input.device_id
+      assert_equal Portmidi::Output, (output = d.instance_variable_get('@output')).class
+      assert_equal 5, output.device_id
+    end
+    
     should 'raise NoSuchDeviceError when requested input device does not exist' do
       assert_raise Launchpad::NoSuchDeviceError do
         Portmidi.stubs(:input_devices).returns(mock_devices(:name => 'Launchpad Input'))
@@ -113,6 +123,59 @@ class TestDevice < Test::Unit::TestCase
     
   end
   
+  context 'close' do
+    
+    should 'not fail when neither input nor output are there' do
+      Launchpad::Device.new(:input => false, :output => false).close
+    end
+    
+    context 'with input and output devices' do
+      
+      setup do
+        Portmidi::Input.stubs(:new).returns(@input = mock('input'))
+        Portmidi::Output.stubs(:new).returns(@output = mock('output', :write => nil))
+        @device = Launchpad::Device.new
+      end
+      
+      should 'close input/output and raise NoInputAllowedError/NoOutputAllowedError on subsequent read/write accesses' do
+        @input.expects(:close)
+        @output.expects(:close)
+        @device.close
+        assert_raise Launchpad::NoInputAllowedError do
+          @device.read_pending_actions
+        end
+        assert_raise Launchpad::NoOutputAllowedError do
+          @device.change(:session)
+        end
+      end
+      
+    end
+    
+  end
+  
+  context 'closed?' do
+    
+    should 'return true when neither input nor output are there' do
+      assert Launchpad::Device.new(:input => false, :output => false).closed?
+    end
+    
+    should 'return false when initialized with input' do
+      assert !Launchpad::Device.new(:input => true, :output => false).closed?
+    end
+    
+    should 'return false when initialized with output' do
+      assert !Launchpad::Device.new(:input => false, :output => true).closed?
+    end
+    
+    should 'return false when initialized with both but true after calling close' do
+      d = Launchpad::Device.new
+      assert !d.closed?
+      d.close
+      assert d.closed?
+    end
+    
+  end
+  
   {
     :reset          => [0xB0, 0x00, 0x00],
     :flashing_on    => [0xB0, 0x00, 0x20],

data/test/test_interaction.rb

@@ -26,6 +26,35 @@ class TestInteraction < Test::Unit::TestCase
     
   end
   
+  context 'close' do
+    
+    should 'close device' do
+      interaction = Launchpad::Interaction.new(:device => device = Launchpad::Device.new)
+      device.expects(:close)
+      interaction.close
+    end
+    
+    should 'craise NoInputAllowedError on subsequent accesses' do
+      interaction = Launchpad::Interaction.new(:device => device = Launchpad::Device.new)
+      interaction.close
+      assert_raise Launchpad::NoInputAllowedError do
+        interaction.start
+      end
+    end
+    
+  end
+  
+  context 'closed?' do
+    
+    should 'return false on a newly created interaction, but true after closing' do
+      interaction = Launchpad::Interaction.new
+      assert !interaction.closed?
+      interaction.close
+      assert interaction.closed?
+    end
+    
+  end
+  
   context 'start' do
     
     # this is kinda greybox tested, since I couldn't come up with another way to test a loop [thomas, 2009-11-11]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: launchpad
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors: 
 - Thomas Jachmann
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-13 00:00:00 +01:00
+date: 2009-11-18 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency