totalspaces 0.1

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,49 @@
+= TotalSpaces - Ruby API bindings for TotalSpaces from BinaryAge
+
+== 2013-02 At present this is pre-release, there is no public version of TotalSpaces containing the API.
+
+This gem enables you to get information from and to control {TotalSpaces}[link:http://totalspaces.binaryage.com]
+
+It is the officially supported way of using the API library libtotalspacesapi, 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 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 TotalSpaces v1.1.4. The API is a premium feature,
+and will only work with registered versions of TotalSpaces.
+
+== Download and installation
+
+The latest version of the TotalSpaces gem can be installed with RubyGems:
+
+  % [sudo] gem install totalspaces
+
+Source code can be downloaded on GitHub
+
+* https://github.com/binaryage/totalspaces-api
+
+
+== Documentation
+
+* In progress
+
+== 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://support.binaryage.com

data/lib/TSLib.h

@@ -0,0 +1,206 @@
+//
+//  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>
+
+/*
+ * 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_numberOfSpaces() returns a number greater than zero when you initialize
+ * your app.
+ */
+
+/*
+ * 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();
+
+/*
+ * The number of the current space
+ *
+ * If the current space is the dashboard, 0 is returned.
+ */
+unsigned int tsapi_currentSpaceNumber();
+
+/*
+ * The name for the given space number
+ *
+ * You must call tsapi_freeString when you have finished with the returned string.
+ */
+const char *tsapi_spaceNameForSpaceNumber(unsigned int spaceNumber);
+
+/*
+ * The total number of spaces
+ * This includes the dashboard if you have it set as a space, and any
+ * fullscreen apps
+ */
+unsigned int tsapi_numberOfSpaces();
+
+/*
+ * The number of fullscreen apps
+ */
+unsigned int tsapi_numberOfFullScreens();
+
+/*
+ * The number of desktops / normal spaces
+ */
+unsigned int tsapi_numberOfDesktops();
+
+/*
+ * The number of fullscreen apps that are allowed to be present
+ * in the grid, defined in advanced preferences
+ */
+unsigned int tsapi_numberOfFullScreensInGrid();
+
+/*
+ * Is the dashboard set to be a space in Mission Control preferences
+ */
+bool tsapi_dashboardIsASpace();
+
+/*
+ * The number of rows defined in TotalSpaces layout preferences
+ */
+unsigned int tsapi_definedRows();
+
+/*
+ * The number of columns defined in TotalSpaces layout preferences
+ */
+unsigned int tsapi_definedColumns();
+
+/*
+ * 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_moveToSpace(unsigned int spaceNumber);
+
+/*
+ * 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_setNameForSpace(unsigned int spaceNumber, char *name);
+
+/*
+ * Type for space change callback
+ */
+typedef void (*space_change_callback_t)(unsigned int fromSpaceNumber, unsigned int toSpaceNumber);
+
+/*
+ * 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;
+};
+
+/*
+ * Struct containing information about a space
+ * Contains a pointer to an array of tsapi_window structs
+ */
+struct tsapi_space {
+  unsigned int spaceNumber;
+  unsigned int windowCount;
+  struct tsapi_window *windows;
+};
+
+/*
+ * Struct containing the count of spaces and a pointer to an
+ * array of tsapi_space structs
+ */
+struct tsapi_spaces {
+  unsigned int spacesCount;
+  struct tsapi_space *spaces;
+};
+
+/*
+ * Return a pointer to a tsapi_spaces struct containing information about all the windows
+ * in all spaces
+ *
+ * The windows are listed front to back, so the first widow in the array is the frontmost
+ *
+ * You must call tsapi_freeWindowList when you have finished with this
+ */
+struct tsapi_spaces *tsapi_windowList();
+
+/*
+ * Free a previously returned spaceWindowsArray struct
+ */
+void tsapi_freeWindowList(struct tsapi_spaces *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_moveWindowToSpace(unsigned int windowId, unsigned int spaceNumber);
+
+#endif
+

data/lib/totalspaces.rb

@@ -0,0 +1,318 @@
+# TotalSpaces - control TotalSpaces from Ruby
+# This gem provides a number of ways to control TotalSpaces. It is intended to be used
+# to add functionality to TotalSpaces, or to use your spaces and desktops in
+# creative ways.
+#
+# === Examples
+#   require 'totalspaces'
+#   
+#   TotalSpaces.on_space_change {|from, to| puts "Moving from space #{from} to space #{to}";}
+#
+#   TotalSpaces.move_to_space(1)
+#
+#   current_space = TotalSpaces.current_space
+#   puts "Current space number: #{current_space}"
+#   puts "Current space is called: #{TotalSpaces.name_for_space(current_space)}"
+#
+#   TotalSpaces.set_name_for_space(1, "Home")
+#
+
+require 'ffi'
+
+module TSApi  #:nodoc:
+  extend FFI::Library
+  ffi_lib File.join(File.dirname(__FILE__), "libtotalspacesapi.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_currentSpaceNumber, [], :uint
+  attach_function :tsapi_spaceNameForSpaceNumber, [:uint], :pointer
+  attach_function :tsapi_numberOfSpaces, [], :uint
+  attach_function :tsapi_numberOfFullScreens, [], :uint
+  attach_function :tsapi_numberOfFullScreensInGrid, [], :uint
+  attach_function :tsapi_numberOfDesktops, [], :uint
+  attach_function :tsapi_dashboardIsASpace, [], :bool
+  attach_function :tsapi_definedRows, [], :uint
+  attach_function :tsapi_definedColumns, [], :uint
+  
+  attach_function :tsapi_moveToSpace, [:uint], :bool
+  attach_function :tsapi_setNameForSpace, [:uint, :string], :bool
+  
+  callback :space_change_function, [: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_moveWindowToSpace, [:uint, :uint], :bool
+end
+
+module TotalSpaces
+
+  #--
+  # See tslib.h for the structures returned by the C API
+  #++
+
+  class Spaces < FFI::Struct  #:nodoc:
+    layout :count, :uint,
+           :windows_arrays, :pointer
+  end
+  
+  class Space < FFI::Struct  #:nodoc:
+    layout :space_number, :uint,
+           :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
+  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 version as that returned by the api_version call
+    #
+    #   puts "libTotalSpaces version: #{TotalSpaces.lib_total_spaces_version}"
+    #
+    def lib_total_spaces_version
+      string_and_free(TSApi.tsapi_libTotalSpacesVersion)
+    end
+
+    # Returns the version of the api present in TotalSpaces, a string such as "1.0"
+    # You should be using the same dylib version as that returned by the this call
+    #
+    #   puts "TotalSpaces API version: #{TotalSpaces.api_version}"
+    #
+    def api_version
+      string_and_free(TSApi.tsapi_apiVersion)
+    end
+
+    # Returns the version of TotalSpaces running on the system, a string such as "1.1.4"
+    #
+    #   puts "TotalSpaces version: #{TotalSpaces.total_spaces_version}"
+    #
+    def total_spaces_version
+      string_and_free(TSApi.tsapi_totalSpacesVersion)
+    end
+    
+    # Returns the number of the current space. Numbering starts at 1, except if you have
+    # the Dashboard enabled as a space, in which case the Dashboard counts as space 0
+    #
+    #   puts "Current space number: #{TotalSpaces.current_space}"
+    #
+    def current_space
+      TSApi.tsapi_currentSpaceNumber
+    end
+    
+    # Returns the name for a space. The returned string will be empty if the space number is
+    # not valid
+    #
+    #   current_space = TotalSpaces.current_space
+    #   puts "Current space is called: #{TotalSpaces.name_for_space(current_space)}"
+    #
+    def name_for_space(space_number)
+      name = string_and_free(TSApi.tsapi_spaceNameForSpaceNumber(space_number))
+      name.force_encoding("UTF-8")
+    end
+    
+    # Returns the total number of spaces including fullscreens, dashboard (if it's a space), 
+    # and spaces that are unused in the grid
+    #
+    #   puts "Total number of spaces: #{TotalSpaces.number_of_spaces}"
+    #
+    def number_of_spaces
+      TSApi.tsapi_numberOfSpaces
+    end
+    
+    # Returns the number of fullscreen apps present
+    #
+    #   puts "Number of fullscreens: #{TotalSpaces.number_of_fullscreens}"
+    #
+    def number_of_fullscreens
+      TSApi.tsapi_numberOfFullScreens
+    end
+
+    # Returns the number of fullscreen apps tht are defined in the grid - this can be defined
+    # in Advanced preferences in TotalSpaces.
+    # The return value does not depend on how many fullscreens actually exist in the grid - the
+    # value is the definition only, there could be fewer than this actually present.
+    #
+    #   puts "Number of fullscreens in the grid: #{TotalSpaces.number_of_fullscreens_in_grid}"
+    #
+    def number_of_fullscreens_in_grid
+      TSApi.tsapi_numberOfFullScreensInGrid
+    end
+    
+    # Returns the number of desktops that are present in the system. This may be a bigger number
+    # that the rows x columns in the grid if more desktops have been created in Mission Control.
+    #
+    #   puts "Number of desktops: #{TotalSpaces.number_of_desktops}"
+    #
+    def number_of_desktops
+      TSApi.tsapi_numberOfDesktops
+    end
+    
+    # Returns true if the dashboard is configured to appear as a space in Mission Control preferences.
+    #
+    #   puts "Dashboard is a space: #{TotalSpaces.dashboard_is_a_space?}"
+    #
+    def dashboard_is_a_space?
+      TSApi.tsapi_dashboardIsASpace
+    end
+    
+    # Returns the number of rows defined in TotalSpaces
+    #
+    #   puts "Number of rows: #{TotalSpaces.grid_rows}"
+    #
+    def grid_rows
+      TSApi.tsapi_definedRows
+    end
+    
+    # Returns the number of columns defined in TotalSpaces
+    #
+    #   puts "Number of columns: #{TotalSpaces.grid_columns}"
+    #
+    def grid_columns
+      TSApi.tsapi_definedColumns
+    end
+    
+    # Command TotalSpaces to switch to the given space number
+    # Returns false if the space number was invalid
+    # The on_space_change notification will be sent
+    #
+    #   TotalSpaces.move_to_space(1)
+    #
+    def move_to_space(space_number)
+      TSApi.tsapi_moveToSpace(space_number)
+    end
+    
+    # Set the name for a space
+    # Note that using this command will cause a layout notification to be sent
+    # if the new name was different from that previously set
+    # The maximum length for a name is 255 bytes
+    #
+    #   TotalSpaces.set_name_for_space(1, "Home")
+    #
+    def set_name_for_space(space_number, name)
+      TSApi.tsapi_setNameForSpace(space_number, name)
+    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
+    #
+    #   TotalSpaces.on_space_change {|from, to| puts "Moving from space #{from} to space #{to}";}
+    #
+    # There can only be one block registered at any time, the most recently registered one will
+    # be called.
+    #
+    def on_space_change(&block)
+      $tsapi_on_space_change_block = block  # prevent CG
+      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 TotalSpaces grid. There are no
+    # arguments passed to the block.
+    #
+    #   TotalSpaces.on_layout_change {puts "Spaces changed"}
+    #
+    # 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 CG
+      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 space.
+    # The hash contains the space number (key :space_number) and an array of hashes, one
+    # for each window (key :windows). The windows are in front to back order.
+    # Each window hash 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 = TotalSpaces.window_list
+    #   if !windows.empty?
+    #     current_space_windows = windows[TotalSpaces.current_space - 1]
+    #     front_window = current_space_windows[:windows][0]
+    #     TotalSpaces.move_window_to_space(front_window[:window_id], TotalSpaces.current_space + 1)
+    #   end
+    #
+    end
+    def window_list
+      result = []
+      list = TSApi.tsapi_windowList
+      main_array = Spaces.new(list)
+
+      (0...main_array[:count]).each do |n|
+        result[n] = {}
+        windows_array = Space.new(main_array[:windows_arrays] + n * Space.size)
+        result[n][:space_number] = windows_array[:space_number]
+        result[n][:windows] = []
+        (0...windows_array[:count]).each do |m|
+          window_hash = result[n][:windows][m] = {}
+          window = Window.new(windows_array[:windows_array] + m * Window.size)
+          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")
+        end
+      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_moveWindowToSpace(window_id, space_number)
+    end
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: totalspaces
+version: !ruby/object:Gem::Version
+  version: '0.1'
+  prerelease: 
+platform: ruby
+authors:
+- Stephen Sykes
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-02-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.11
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.11
+description: This allows you to control the TotalSpaces desktop manager for mac from
+  ruby.
+email: stephen@binaryage.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.rdoc
+- MIT_LICENCE
+- lib/totalspaces.rb
+- lib/libtotalspacesapi.dylib
+- lib/TSLib.h
+homepage: http://github.com/binaryage/totalspaces-api
+licenses: []
+post_install_message: 
+rdoc_options:
+- --charset=UTF-8
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: TotalSpaces control from ruby
+test_files: []