totalspaces2 2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a133c5d3f23844aa9ca70332146796499c6e3b9e
+  data.tar.gz: 342ceaf3ec96f133b4e6b0a06e8f1a7400c24a4c
+SHA512:
+  metadata.gz: 4455a450a3c33fa50fce7162d9ebca2285fcb10d1828132cdbbf99d9aa2c36f02f6e01d354a0efd6f58f89bb749429e35b400e7ad48ec1dedb79d8cac14d7ac6
+  data.tar.gz: 2f025c0a21fc74d0f166ed95d7cb0bab5c0d1ec955a7ce743a0e5893267353f7e0d01a31446d36c3f232bd73fec51bd785dc48f0aefe66ee073759f479d70408

data/MIT_LICENCE

@@ -0,0 +1,20 @@
+Copyright (c) 2013 Stephen Sykes
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,65 @@
+= TotalSpaces2 - Ruby API bindings for TotalSpaces2 from BinaryAge
+
+== PRERELEASE: You will be able to use the API with versions 2.1 and above of totalspaces.
+
+This gem enables you to get information from and to control {TotalSpaces2}[link:http://totalspaces.binaryage.com]
+
+It is the officially supported way of using the API library libtotalspaces2api, and the required dylib 
+comes bundled with this gem. This gem uses {Ruby-FFI}[link:https://github.com/ffi/ffi] to call the functions in the dylib.
+You'll need a sane ruby and compilation environment to install ruby-ffi - it probably won't install immediately with the
+ruby that comes with Mavericks because none of the compilation tools are present. We use {homebrew}[link:http://mxcl.github.com/homebrew/]
+and {rbenv}[link:https://github.com/sstephenson/rbenv/] to manage our ruby scripting environment.
+
+You may use this gem in various ways. For instance, you could:
+
+* Display a message or alert when a particular space is moved to
+
+* Automatically change the name of spaces depending on what apps are in them
+
+* Record which spaces certain windows are on, and restoring those windows to those spaces when the owning app restarts
+
+* Trigger moving certain windows between spaces
+
+API support, and support for this gem starts with TotalSpaces2 v2.0.12 The API is a premium feature,
+and will only work with registered versions of TotalSpaces2.
+
+== Download and installation
+
+The latest version of the TotalSpaces2 gem can be installed with RubyGems:
+
+  % [sudo] gem install totalspaces2
+
+Source code can be downloaded on GitHub
+
+* https://github.com/binaryage/totalspaces2-api
+
+
+== Documentation
+
+{module TotalSpaces2}[link:http://binaryage.github.io/totalspaces2-api/ruby/rdoc/TotalSpaces2.html]
+
+== Examples
+   require 'totalspaces2'
+   
+   TotalSpaces2.on_space_change {|from, to, display_id| puts "Moving from space #{from} to space #{to}";}
+
+   TotalSpaces2.move_to_space(1)
+
+   current_space = TotalSpaces2.current_space
+   puts "Current space number: #{current_space}"
+   puts "Current space is called: #{TotalSpaces2.name_for_space(current_space)}"
+
+   TotalSpaces2.set_name_for_space(1, "Home")
+
+== License
+
+The TotalSpaces2 gem is released under the MIT license:
+
+* http://www.opensource.org/licenses/MIT
+
+The source code of the dylib is not available at this time.
+
+
+== Support and feature requests
+
+* http://discuss.binaryage.com

data/lib/TSLib.h

@@ -0,0 +1,256 @@
+//
+//  TSLib.h
+//  totalspacesapi
+//
+//  Created by Stephen Sykes on 27/1/13.
+//  Copyright (c) 2013 Stephen Sykes. All rights reserved.
+//
+//  The API is a premium feature, and will only work with registered versions of TotalSpaces.
+//
+
+#ifndef totalspacesapi_tslib
+#define totalspacesapi_tslib_h
+
+#import <Foundation/Foundation.h>
+
+#define TSAPI_MAX_SPACES 32
+
+/*
+ * In case of comm error, all the functions apart from tsapi_libTotalSpacesVersion() will 
+ * return an empty string, zero, false or a pointer to a struct containing zero spaces (in 
+ * the case of tsapi_windowList).
+ * It is recommended to check that comms to TotalSpaces are working by, for instance,
+ * checking that tsapi_apiVersion() matches tsapi_libTotalSpacesVersion() when you initialize
+ * your app.
+ *
+ * Some actions such as renaming a space will cause the overview grid to be exited if it
+ * is showing at the time.
+ */
+
+/*
+ * The version of the API present in TotalSpaces.app.
+ *
+ * You must call tsapi_freeString when you have finished with the returned string.
+ */
+const char *tsapi_apiVersion();
+
+/*
+ * The version number of TotalSpaces itself.
+ *
+ * You must call tsapi_freeString when you have finished with the returned string.
+ */
+const char *tsapi_totalSpacesVersion();
+
+/*
+ * The version of the API dylib. This should match the string returned
+ * by tsapi_apiVersion().
+ *
+ * You must call tsapi_freeString when you have finished with the returned string.
+ */
+const char *tsapi_libTotalSpacesVersion();
+
+/*
+ * Struct containing info about a display.
+ */
+struct tsapi_display {
+  CGDirectDisplayID displayId;
+  char *displayName;
+  size_t width;
+  size_t height;
+};
+
+/*
+ * Struct containing the count of spaces and a pointer to an
+ * array of CGDirectDisplayIDs.
+ */
+struct tsapi_displays {
+  unsigned int displaysCount;
+  struct tsapi_display *displays;
+};
+
+/*
+ * Return a pointer to a tsapi_displays struct containing information about all the displays.
+ *
+ * The first display in the list will be the main display. The main display is the display 
+ * with its screen location at (0,0) in the global display coordinate space. In a system
+ * without display mirroring, the display with the menu bar is typically the main display.
+ *
+ * You must call tsapi_freeDisplayList when you have finished with this.
+ */
+struct tsapi_displays *tsapi_displayList();
+
+/*
+ * Free a previously returned tsapi_displays struct
+ */
+void tsapi_freeDisplayList(struct tsapi_displays *displayList);
+
+/*
+ * The number of the current space.
+ *
+ * If the current space is the dashboard, 0 is returned.
+ */
+unsigned int tsapi_currentSpaceNumberOnDisplay(CGDirectDisplayID displayID);
+
+/*
+ * The name for the given space number.
+ *
+ * You must call tsapi_freeString when you have finished with the returned string.
+ */
+const char *tsapi_spaceNameForSpaceNumberOnDisplay(unsigned int spaceNumber, CGDirectDisplayID displayID);
+
+/*
+ * The total number of spaces.
+ * This includes the dashboard if you have it set as a space, and any
+ * fullscreen apps.
+ */
+unsigned int tsapi_numberOfSpacesOnDisplay(CGDirectDisplayID displayID);
+
+/*
+ * The number of columns defined in TotalSpaces layout preferences.
+ */
+unsigned int tsapi_definedColumnsOnDisplay(CGDirectDisplayID displayID);
+
+/*
+ * Sets the number of columns in the TotalSpaces grid.
+ * Returns true on success, false if the new grid would exceed TSAPI_MAX_SPACES
+ * or if columns is zero.
+ * Note that the actual number of desktops present in the system is unchanged,
+ * you should call tsapi_addDesktops or tsapi_removeDesktops after calling this
+ * function.
+ */
+bool tsapi_setDefinedColumnsOnDisplay(unsigned int columns, CGDirectDisplayID displayID);
+
+/*
+ * Call this to free strings returned by the TotalSpaces API.
+ */
+void tsapi_freeString(char *str);
+
+/*
+ * Switch the display to the given space.
+ * Returns false if the space number is invalid.
+ */
+bool tsapi_moveToSpaceOnDisplay(unsigned int spaceNumber, CGDirectDisplayID displayID);
+
+/*
+ * Set the name of a space.
+ * The maximum length is 255 bytes. The name should be in UTF-8.
+ * Returns true on success, false if the name was too long or the space number was invalid.
+ */
+bool tsapi_setNameForSpaceOnDisplay(unsigned int spaceNumber, char *name, CGDirectDisplayID displayID);
+
+/*
+ * Type for space change callback.
+ */
+typedef void (*space_change_callback_t)(unsigned int fromSpaceNumber, unsigned int toSpaceNumber, CGDirectDisplayID displayID);
+
+/*
+ * Set the function that will be called when the visible space changes.
+ * There is only one callback per process, registering a new callback will supercede any previous one.
+ */
+void tsapi_setSpaceWillChangeCallback(space_change_callback_t callback);
+
+/*
+ * Cancel space change callbacks
+ */
+void tsapi_unsetSpaceWillChangeCallback();
+
+/*
+ * Type for layout change callback
+ */
+typedef void (*space_layout_changed_callback_t)(void);
+
+/*
+ * Set the function that will be called when the layout changes.
+ * This could be any change - for instance adding or removing a fullscreen, changing the name of a space,
+ * or a change of rows or columns.
+ * It indicates that you should re-request any information you are holding on the spaces.
+ * There is only one callback per process, registering a new callback will supercede any previous one.
+ */
+void tsapi_setLayoutChangedCallback(space_layout_changed_callback_t callback);
+
+/*
+ * Cancel layout change callbacks.
+ */
+void tsapi_unsetLayoutChangedCallback();
+
+/*
+ * Struct containing information about a window.
+ */
+struct tsapi_window {
+  char *appName;
+  unsigned int windowId;
+  bool isOnAllSpaces;
+  char *title;
+  char *frame;
+  CGDirectDisplayID displayID;
+  unsigned int spaceNumber;
+};
+
+/*
+ * Struct containing information about windows.
+ * Contains a pointer to an array of tsapi_window structs.
+ */
+struct tsapi_windows {
+  unsigned int windowCount;
+  struct tsapi_window *windows;
+};
+
+/*
+ * Return a pointer to a tsapi_windows struct containing information about all the windows
+ * in all spaces.
+ *
+ * The windows are listed in space order for each display, and within each space
+ * the windows are listed front to back, so earlier windows in the array are frontmost.
+ *
+ * You must call tsapi_freeWindowList when you have finished with this.
+ */
+struct tsapi_windows *tsapi_windowList();
+
+/*
+ * Free a previously returned tsapi_spaces struct
+ */
+void tsapi_freeWindowList(struct tsapi_windows *windowList);
+
+/*
+ * Move a window to a different space
+ * The windowId must be one that has been returned in a tsapi_window struct
+ *
+ * Returns true on success, false if the windowID or spaceNumber was invalid
+ */
+bool tsapi_moveWindowToSpaceOnDisplay(unsigned int windowID, unsigned int spaceNumber, CGDirectDisplayID displayID);
+
+/*
+ * Move a space to another position
+ * You cannot move space 1 when displays have separate spaces is turned off.
+ *
+ * Returns true on success, false if the spaceNumber or positionNumber was
+ * invalid
+ */
+bool tsapi_moveSpaceToPositionOnDisplay(unsigned int spaceNumber, unsigned int positionNumber, CGDirectDisplayID displayID);
+
+/*
+ * Add desktops
+ * There can usually be at most 16 desktops, unless desktops have migrated
+ * from another monitor.
+ *
+ * Returns the number of desktops actually added.
+ */
+unsigned int tsapi_addDesktopsOnDisplay(unsigned int numberToAdd, CGDirectDisplayID displayID);
+
+/*
+ * Remove desktops
+ * Removes numberToRemove desktops. The highest numbered desktops are removed.
+ *
+ * Removing a desktop you are currently on will result in TotalSpaces switching to
+ * another dektop.
+ *
+ * Any windows present on a desktop being removed will be moved to one of the
+ * remaining desktops.
+ *
+ * Returns true on success, false if numberToRemove was zero or would result in less
+ * than 1 desktop remaining.
+ */
+bool tsapi_removeDesktopsOnDisplay(unsigned int numberToRemove, CGDirectDisplayID displayID);
+
+#endif
+

data/lib/totalspaces2.rb

@@ -0,0 +1,575 @@
+# = TotalSpaces2 - Ruby API bindings for TotalSpaces2 from BinaryAge
+#
+# This gem enables you to get information from and to control {TotalSpaces2}[link:http://totalspaces.binaryage.com]
+#
+# It is the officially supported way of using the API library libtotalspaces2api, and the required dylib 
+# comes bundled with this gem. This gem uses {Ruby-FFI}[link:https://github.com/ffi/ffi] to call the functions in the dylib.
+# You'll need a sane ruby and compilation environment to install ruby-ffi - it probably won't install immediately with the
+# ruby that comes with OSX because none of the compilation tools are present. We use {homebrew}[link:http://mxcl.github.com/homebrew/]
+# and {rbenv}[link:https://github.com/sstephenson/rbenv/] to manage our ruby scripting environment.
+#
+# You may use this gem in various ways. For instance, you could:
+#
+# * Display a message or alert when a particular space is moved to
+#
+# * Automatically change the name of spaces depending on what apps are in them
+#
+# * Record which spaces certain windows are on, and restoring those windows to those spaces when the owning app restarts
+#
+# * Trigger moving certain windows between spaces
+#
+# API support, and support for this gem starts with TotalSpaces2 v2.1.0. The API is a premium feature,
+# and will only work with registered versions of TotalSpaces2.
+#
+# == Download and installation
+#
+# The latest version of the TotalSpaces2 gem can be installed with RubyGems:
+#
+#  % [sudo] gem install totalspaces2
+#
+# Source code can be downloaded on GitHub
+#
+# * https://github.com/binaryage/totalspaces2-api
+#
+#
+# == Documentation
+#
+# * http://binaryage.github.io/totalspaces2-api/ruby/rdoc/TotalSpaces2.html
+#
+# == License
+#
+# The TotalSpaces gem is released under the MIT license:
+#
+# * http://www.opensource.org/licenses/MIT
+#
+# The source code of the dylib is not available at this time.
+#
+#
+# == Support and feature requests
+#
+# * http://discuss.binaryage.com
+#
+#
+# == Examples
+#   require 'totalspaces2'
+#   
+#   TotalSpaces2.on_space_change {|from, to, display_id| puts "Moving from space #{from} to space #{to}";}
+#
+#   TotalSpaces2.move_to_space(1)
+#
+#   current_space = TotalSpaces2.current_space
+#   puts "Current space number: #{current_space}"
+#   puts "Current space is called: #{TotalSpaces2.name_for_space(current_space)}"
+#
+#   TotalSpaces2.set_name_for_space(1, "Home")
+#
+
+require 'ffi'
+
+module TSApi  #:nodoc:
+  extend FFI::Library
+  ffi_lib File.join(File.dirname(__FILE__), "libtotalspaces2api.dylib")
+
+  attach_function :tsapi_freeString, [:pointer], :void
+  
+  attach_function :tsapi_libTotalSpacesVersion, [], :pointer
+  attach_function :tsapi_apiVersion, [], :pointer
+  attach_function :tsapi_totalSpacesVersion, [], :pointer
+  
+  attach_function :tsapi_displayList, [], :pointer
+  attach_function :tsapi_freeDisplayList, [:pointer], :void
+  
+  attach_function :tsapi_currentSpaceNumberOnDisplay, [:uint], :uint
+  attach_function :tsapi_spaceNameForSpaceNumberOnDisplay, [:uint, :uint], :pointer
+  attach_function :tsapi_numberOfSpacesOnDisplay, [:uint], :uint
+  
+  attach_function :tsapi_definedColumnsOnDisplay, [:uint], :uint
+  
+  attach_function :tsapi_setDefinedColumnsOnDisplay, [:uint, :uint], :bool
+  
+  attach_function :tsapi_moveToSpaceOnDisplay, [:uint, :uint], :bool
+  attach_function :tsapi_setNameForSpaceOnDisplay, [:uint, :string, :uint], :bool
+  
+  callback :space_change_function, [:uint, :uint, :uint], :void
+  attach_function :tsapi_setSpaceWillChangeCallback, [:space_change_function], :void
+  attach_function :tsapi_unsetSpaceWillChangeCallback, [], :void
+  
+  callback :layout_changed_function, [], :void
+  attach_function :tsapi_setLayoutChangedCallback, [:layout_changed_function], :void
+  attach_function :tsapi_unsetLayoutChangedCallback, [], :void
+
+  attach_function :tsapi_windowList, [], :pointer
+  attach_function :tsapi_freeWindowList, [:pointer], :void
+  
+  attach_function :tsapi_moveWindowToSpaceOnDisplay, [:uint, :uint, :uint], :bool
+  
+  attach_function :tsapi_moveSpaceToPositionOnDisplay, [:uint, :uint, :uint], :bool
+  
+  attach_function :tsapi_addDesktopsOnDisplay, [:uint, :uint], :uint
+  attach_function :tsapi_removeDesktopsOnDisplay, [:uint, :uint], :bool
+end
+
+module TotalSpaces2
+
+  MAX_DESKTOPS = 16
+
+  #--
+  # See TSLib.h for the structures returned by the C API
+  #++
+
+  class Display < FFI::Struct  #:nodoc:
+    layout :displayID, :uint32,
+           :display_name, :string,
+           :width, :size_t,
+           :height, :size_t
+  end
+
+  class Displays < FFI::Struct  #:nodoc:
+    layout :count, :uint,
+           :displays_array, :pointer
+    
+    def display_info
+      displays = []
+      displays_array = self[:displays_array]
+      (0...self[:count]).each do |n|
+        display = Display.new(displays_array + n * Display.size)
+        info = {
+          display_id: display[:displayID],
+          display_name: display[:display_name],
+          width: display[:width],
+          height: display[:height]
+        }
+        displays << info
+      end
+      
+      displays
+    end
+  end
+
+  class Windows < FFI::Struct  #:nodoc:
+    layout :count, :uint,
+           :windows_array, :pointer
+  end
+    
+  class Window < FFI::Struct  #:nodoc:
+    layout :app_name, :string,
+           :window_id, :uint,
+           :is_on_all_spaces, :bool,
+           :title, :string,
+           :frame, :string,
+           :display_id, :uint,
+           :space_number, :uint
+  end
+  
+  class << self
+    private
+    def string_and_free(cstr_pointer)  #:nodoc:
+      str = cstr_pointer.get_string(0)
+      TSApi.tsapi_freeString(cstr_pointer)
+      str
+    end
+    
+    public
+    
+    # Returns the version of the dylib, a string such as "1.0"
+    # You should be using the same dylib major version number as that returned by the api_version call
+    #
+    #   puts "libTotalSpaces2 version: #{TotalSpaces2.lib_total_spaces_version}"
+    #
+    #   if TotalSpaces2.lib_total_spaces_version.split('.')[0] != TotalSpaces2.api_version.split('.')[0]
+    #     puts "Comms error!"
+    #     exit(1)
+    #   end
+    #
+    #
+    def lib_total_spaces_version
+      string_and_free(TSApi.tsapi_libTotalSpacesVersion)
+    end
+
+    # Returns the version of the api present in TotalSpaces2, a string such as "1.0"
+    # You should be using the same dylib version as that returned by the this call
+    #
+    #   puts "TotalSpaces2 API version: #{TotalSpaces2.api_version}"
+    #
+    #    if TotalSpaces2.lib_total_spaces_version.split('.')[0] != TotalSpaces2.api_version.split('.')[0]
+    #     puts "Comms error!"
+    #     exit(1)
+    #   end
+    #
+    def api_version
+      string_and_free(TSApi.tsapi_apiVersion)
+    end
+
+    # Returns the version of TotalSpaces2 running on the system, a string such as "2.0.12"
+    #
+    #   puts "TotalSpaces2 version: #{TotalSpaces2.total_spaces_version}"
+    #
+    def total_spaces_version
+      string_and_free(TSApi.tsapi_totalSpacesVersion)
+    end
+
+    # Returns an array of hashes with information about attached displays. The ids returned
+    # from this call can be used where a display id is required in the other calls in this library.
+    #
+    #   puts "Attached displays: #{TotalSpaces2.display_list}"
+    #
+    #   [{:display_id=>69679040, :display_name=>"Color LCD", :width=>1440, :height=>900}, 
+    #   {:display_id=>69514913, :display_name=>"LED Cinema Display", :width=>2560, :height=>1440}]
+    #
+    def display_list
+      list = TSApi.tsapi_displayList
+      displays = Displays.new(list)
+      result = displays.null? ? [] : displays.display_info
+      TSApi.tsapi_freeDisplayList(list)
+      result
+    end
+
+    # Returns information about the main display.
+    # Methods that do not take a display id always operate on this display.
+    #
+    #   puts "Main display id: #{TotalSpaces2.main_display_id}"
+    #
+    #   {:display_id=>69679040, :display_name=>"Color LCD", :width=>1440, :height=>900}
+    #
+    def main_display
+      self.display_list[0]
+    end
+    
+    # Returns the number of the current space on the main display. Numbering starts at 1.
+    #
+    #   puts "Current space number: #{TotalSpaces2.current_space}"
+    #
+    def current_space
+      TSApi.tsapi_currentSpaceNumberOnDisplay(0)
+    end
+
+    # Returns the number of the current space on the given display. 
+    # Space numbering starts at 1
+    #
+    #   display_id = TotalSpaces2.displays[0]
+    #   puts "Current space number: #{TotalSpaces2.current_space_on_display(display_id)}"
+    #
+    def current_space_on_display(display_id)
+      TSApi.tsapi_currentSpaceNumberOnDisplay(display_id)
+    end
+    
+    # Returns the name for a space on the main display. The returned string will be empty 
+    # if the space number is not valid
+    #
+    #   current_space = TotalSpaces2.current_space
+    #   puts "Current space is called: #{TotalSpaces2.name_for_space(current_space)}"
+    #
+    def name_for_space(space_number)
+      name = string_and_free(TSApi.tsapi_spaceNameForSpaceNumberOnDisplay(space_number, 0))
+      name.force_encoding("UTF-8")
+    end
+
+    # Returns the name for a space. The returned string will be empty if the space number is
+    # not valid
+    #
+    #   current_space = TotalSpaces2.current_space
+    #   display_id = TotalSpaces2.main_display[:display_id]
+    #   puts "Current space is called: #{TotalSpaces2.name_for_space_on_display(current_space, display_id)}"
+    #
+    def name_for_space_on_display(space_number, display_id)
+      name = string_and_free(TSApi.tsapi_spaceNameForSpaceNumberOnDisplay(space_number, display_id))
+      name.force_encoding("UTF-8")
+    end
+    
+    # Returns the total number of spaces including fullscreens, dashboard (if it's a space).
+    #
+    #   puts "Total number of spaces: #{TotalSpaces2.number_of_spaces}"
+    #
+    def number_of_spaces
+      TSApi.tsapi_numberOfSpacesOnDisplay(0)
+    end
+    
+    # Returns the total number of spaces including fullscreens, dashboard (if it's a space).
+    #
+    #   display_id = TotalSpaces2.main_display[:display_id]
+    #   puts "Total number of spaces: #{TotalSpaces2.number_of_spaces_on_display(display_id)}"
+    #
+    def number_of_spaces_on_display(display_id)
+      TSApi.tsapi_numberOfSpacesOnDisplay(display_id)
+    end
+    
+    # Returns the number of columns defined in TotalSpaces2 for the main display
+    #
+    #   puts "Number of columns: #{TotalSpaces2.grid_columns}"
+    #
+    def grid_columns
+      TSApi.tsapi_definedColumnsOnDisplay(0)
+    end
+    
+    # Returns the number of columns defined in TotalSpaces2
+    #
+    #   display_id = TotalSpaces2.main_display[:display_id]
+    #   puts "Number of columns: #{TotalSpaces2.grid_columns_on_display(display_id)}"
+    #
+    def grid_columns_on_display(display_id)
+      TSApi.tsapi_definedColumnsOnDisplay(display_id)
+    end
+    
+    # Sets the number of columns defined in TotalSpaces2 for the main display.
+    #
+    # This does not change the actual number of desktops present, you should 
+    # call add_desktops or remove_desktops as appropriate after changing the number
+    # of columns.
+    #
+    #   TotalSpaces2.set_grid_columns(3)
+    #
+    def set_grid_columns(columns)
+      TSApi.tsapi_setDefinedColumnsOnDisplay(columns, 0)
+    end
+    
+    # Sets the number of columns defined in TotalSpaces2.
+    #
+    # This does not change the actual number of desktops present, you should 
+    # call add_desktops_on_display or remove_desktops_on_display as appropriate 
+    # after changing the number of columns.
+    #
+    #   display_id = TotalSpaces2.main_display[:display_id]
+    #   TotalSpaces2.set_grid_columns_on_display(3, display_id)
+    #
+    def set_grid_columns_on_display(columns, display_id)
+      TSApi.tsapi_setDefinedColumnsOnDisplay(columns, display_id)
+    end
+    
+    # Command TotalSpaces2 to switch to the given space number on the main display.
+    # Returns false if the space number was invalid.
+    # The on_space_change notification will be sent.
+    #
+    #   TotalSpaces2.move_to_space(1)
+    #
+    def move_to_space(space_number)
+      TSApi.tsapi_moveToSpaceOnDisplay(space_number, 0)
+    end
+    
+    # Command TotalSpaces2 to switch to the given space number.
+    # Returns false if the space number was invalid.
+    # The on_space_change notification will be sent.
+    #
+    #   display_id = TotalSpaces2.main_display[:display_id]
+    #   TotalSpaces2.move_to_space_on_Display(1, display_id)
+    #
+    def move_to_space_on_display(space_number, display_id)
+      TSApi.tsapi_moveToSpaceOnDisplay(space_number, display_id)
+    end
+    
+    # Set the name for a space on the main display.
+    # Note that using this command will cause a layout change notification to be sent
+    # if the new name was different from that previously set.
+    # The maximum length for a name is 255 bytes.
+    #
+    #   TotalSpaces2.set_name_for_space(1, "Home")
+    #
+    def set_name_for_space(space_number, name)
+      TSApi.tsapi_setNameForSpaceOnDisplay(space_number, name, 0)
+    end
+
+    # Set the name for a space.
+    # Note that using this command will cause a layout change notification to be sent
+    # if the new name was different from that previously set.
+    # The maximum length for a name is 255 bytes.
+    #
+    #   display_id = TotalSpaces2.main_display[:display_id]
+    #   TotalSpaces2.set_name_for_space_on_display(1, "Home", display_id)
+    #
+    def set_name_for_space_on_display(space_number, name, display_id)
+      TSApi.tsapi_setNameForSpaceOnDisplay(space_number, name, display_id)
+    end
+    
+    # Register for notifications on space change.
+    # The given block will be called whenever you move from one space to another. The arguments are
+    # the space number you moved from, and the one you are moving to.
+    #
+    #   TotalSpaces2.on_space_change {|from, to, displayID| puts "Moving from space #{from} to space #{to}"}
+    #   
+    #   sleep
+    #
+    # There can only be one block registered at any time, the most recently registered one will
+    # be called.
+    # This callback is called just before the space actually changes - current_space will still 
+    # report the from space.
+    #
+    def on_space_change(&block)
+      $tsapi_on_space_change_block = block  # prevent GC
+      TSApi.tsapi_setSpaceWillChangeCallback(block)
+    end
+    
+    # Cancel the on_space_change notification.
+    #
+    def cancel_on_space_change
+      $tsapi_on_space_change_block = nil
+      TSApi.tsapi_unsetSpaceWillChangeCallback
+    end
+
+    # Register for notifications on layout change.
+    # The given block will be called whenever the layout changes - this could be due to making an app
+    # fullscreen, changing a space name, or changing the layout of the TotalSpaces2 grid. There are no
+    # arguments passed to the block.
+    #
+    #   
+    #   TotalSpaces.on_layout_change {puts "Spaces changed"}
+    #   
+    #   sleep
+    #
+    # When you get a notification from this method, you should re-fetch any information about the spaces
+    # that you may be storing.
+    #
+    # There can only be one block registered at any time, the most recently registered one will
+    # be called.
+    #
+    def on_layout_change(&block)
+      $tsapi_on_layout_change_block = block  # prevent GC
+      TSApi.tsapi_setLayoutChangedCallback(block)
+    end
+    
+    # Cancel the layout change notification
+    #
+    def cancel_on_layout_change
+      $tsapi_on_layout_change_block = nil
+      TSApi.tsapi_unsetLayoutChangedCallback
+    end
+    
+    # Get a list of all the windows on your mac
+    # It returns an array containing a hash for each window.
+    # The hash contains the display id (key :display_id) and space number (key :space_number) 
+    # and details for each window.
+    # The windows are in front to back order within each space.
+    # Each window hash also contains a window_id, title, frame, app_name and is_on_all_spaces flag
+    #
+    # The below example would move the frontmost window to the next space to the right.
+    # 
+    #   windows = TotalSpaces2.window_list
+    #   current_space = TotalSpaces2.current_space
+    #   main_display_id = TotalSpaces2.main_display[:display_id]
+    #   if !windows.empty?
+    #     current_space_windows = windows.select {|window| window[:display_id] == main_display_id 
+    #                                                      && window[:space_number] == current_space}
+    #     front_window = current_space_windows[0]
+    #     TotalSpaces2.move_window_to_space(front_window[:window_id], TotalSpaces.current_space + 1)
+    #   end
+    #
+    def window_list
+      result = []
+      list = TSApi.tsapi_windowList
+      main_array = Windows.new(list)
+
+      (0...main_array[:count]).each do |n|
+        window = Window.new(main_array[:windows_array] + n * Window.size)
+        window_hash = {}
+        window_hash[:window_id] = window[:window_id]
+        window_hash[:title] = window[:title].dup.force_encoding("UTF-8")
+        window_hash[:frame] = window[:frame].dup.force_encoding("UTF-8")
+        window_hash[:is_on_all_spaces] = window[:is_on_all_spaces]
+        window_hash[:app_name] = window[:app_name].dup.force_encoding("UTF-8")
+        window_hash[:display_id] = window[:display_id]
+        window_hash[:space_number] = window[:space_number]
+        result << window_hash
+      end
+      
+      TSApi.tsapi_freeWindowList(list)
+
+      result
+    end
+    
+    # Move a window to a given space
+    # The window_id parameter must be fetched using window_list.
+    # Returns false if the space_number or window_id is invalid.
+    #
+    def move_window_to_space(window_id, space_number)
+      TSApi.tsapi_moveWindowToSpaceOnDisplay(window_id, space_number, 0)
+    end
+    
+    # Move a window to a given space on the main display
+    # The window_id parameter must be fetched using window_list.
+    # Returns false if the space_number or window_id is invalid.
+    #
+    def move_window_to_space_on_display(window_id, space_number, display_id)
+      TSApi.tsapi_moveWindowToSpaceOnDisplay(window_id, space_number, display_id)
+    end
+    
+    # Move space to a new position in the grid on the main display.
+    #
+    # Returns false if the space_number or position_number is not valid.
+    #
+    #   TotalSpaces2.move_space_to_position(4, 2)
+    #
+    def move_space_to_position(space_number, position_number)
+      TSApi.tsapi_moveSpaceToPositionOnDisplay(space_number, position_number)
+    end
+
+    # Move space to a new position in the grid. Spaces can only be moved 
+    # within their own display.
+    #
+    # Returns false if the space_number or position_number is not valid.
+    #
+    #   display_id = TotalSpaces2.main_display[:display_id]
+    #   TotalSpaces2.move_space_to_position_on_display(4, 2, display_id)
+    #
+    def move_space_to_position_on_display(space_number, position_number, display_id)
+      TSApi.tsapi_moveSpaceToPositionOnDisplay(space_number, position_number, display_id)
+    end
+    
+    # Add desktops
+    # There can be at most 16 desktops unless the display has collected some when
+    # a secondary display has been unplugged.
+    # Returns true on success, false if number_to_add was zero, or would result 
+    # in more than 16 desktops.
+    # The on_layout_change notification will be sent if a changed was made.
+    #
+    #   TotalSpaces2.add_desktops(1)
+    #
+    def add_desktops(number_to_add)
+      TSApi.tsapi_addDesktopsOnDisplay(number_to_add, 0)
+    end
+
+    # Add desktops
+    # There can be at most 16 desktops unless the display has collected some when
+    # a secondary display has been unplugged.
+    # Returns true on success, false if number_to_add was zero, or would result 
+    # in more than 16 desktops.
+    # The on_layout_change notification will be sent if a changed was made.
+    #
+    #   display_id = TotalSpaces2.main_display[:display_id]
+    #   TotalSpaces2.add_desktops_on_display(1, display_id)
+    #
+    def add_desktops_on_display(number_to_add, display_id)
+      TSApi.tsapi_addDesktopsOnDisplay(number_to_add, display_id)
+    end
+    
+    # Remove desktops
+    # The highest numbered desktops are removed.
+    # Removing a desktop you are currently on will result in TotalSpaces2 switching to
+    # another dektop.
+    # Any windows present on a desktop being removed will be moved to one of the
+    # remaining desktops.
+    # Returns true on success, false if number_to_remove was zero or would result in less
+    # than 1 desktop remaining.
+    # The on_layout_change notification will be sent if a change was made.
+    #
+    #   TotalSpaces2.remove_desktops(1)
+    #
+    def remove_desktops(number_to_remove)
+      TSApi.tsapi_removeDesktopsOnDisplay(number_to_remove, 0)
+    end
+
+    # Remove desktops
+    # The highest numbered desktops are removed.
+    # Removing a desktop you are currently on will result in TotalSpaces2 switching to
+    # another dektop.
+    # Any windows present on a desktop being removed will be moved to one of the
+    # remaining desktops.
+    # Returns true on success, false if number_to_remove was zero or would result in less
+    # than 1 desktop remaining.
+    # The on_layout_change notification will be sent if a change was made.
+    #
+    #   display_id = TotalSpaces2.main_display[:display_id]
+    #   TotalSpaces2.remove_desktops_on_display(1, display_id)
+    #
+    def remove_desktops_on_display(number_to_remove, display_id)
+      TSApi.tsapi_removeDesktopsOnDisplay(number_to_remove, display_id)
+    end
+  end
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: totalspaces2
+version: !ruby/object:Gem::Version
+  version: '2.0'
+platform: ruby
+authors:
+- Stephen Sykes
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-02-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.11
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.11
+description: This allows you to control the TotalSpaces2 desktop manager for mac from
+  ruby.
+email: stephen@binaryage.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.rdoc
+- MIT_LICENCE
+- lib/totalspaces2.rb
+- lib/libtotalspaces2api.dylib
+- lib/TSLib.h
+homepage: https://github.com/binaryage/totalspaces2-api/tree/master/ruby
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options:
+- --charset=UTF-8
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: TotalSpaces2 control from ruby
+test_files: []