totalspaces 0.1 → 0.2

data/README.rdoc

@@ -6,6 +6,10 @@ This gem enables you to get information from and to control {TotalSpaces}[link:h
 
 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'll need a sane ruby and compilation environment to install ruby-ffi - it probably won't install immediately with the
+ruby that comes with Mountain Lion 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.
+{This simple guide}[link:http://jacobswanner.com/2012/07/13/ruby-1-9-3-without-gcc.html] may help if you are new to this.
 
 You may use this gem in various ways. For instance, you could:
 

data/lib/TSLib.h

@@ -13,6 +13,8 @@
 
 #import <Foundation/Foundation.h>
 
+#define TSAPI_MAX_SPACES 16
+
 /*
  * 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 
@@ -23,14 +25,14 @@
  */
 
 /*
- * The version of the API present in TotalSpaces.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
+ * The version number of TotalSpaces itself.
  *
  * You must call tsapi_freeString when you have finished with the returned string.
  */
@@ -38,90 +40,110 @@ const char *tsapi_totalSpacesVersion();
 
 /*
  * The version of the API dylib. This should match the string returned
- * by tsapi_apiVersion()
+ * 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
+ * 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
+ * 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
+ * The total number of spaces.
  * This includes the dashboard if you have it set as a space, and any
- * fullscreen apps
+ * fullscreen apps.
  */
 unsigned int tsapi_numberOfSpaces();
 
 /*
- * The number of fullscreen apps
+ * The number of fullscreen apps.
  */
 unsigned int tsapi_numberOfFullScreens();
 
 /*
- * The number of desktops / normal spaces
+ * 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
+ * in the grid, defined in advanced preferences.
  */
 unsigned int tsapi_numberOfFullScreensInGrid();
 
 /*
- * Is the dashboard set to be a space in Mission Control preferences
+ * Is the dashboard set to be a space in Mission Control preferences.
  */
 bool tsapi_dashboardIsASpace();
 
 /*
- * The number of rows defined in TotalSpaces layout preferences
+ * The number of rows defined in TotalSpaces layout preferences.
  */
 unsigned int tsapi_definedRows();
 
 /*
- * The number of columns defined in TotalSpaces layout preferences
+ * The number of columns defined in TotalSpaces layout preferences.
  */
 unsigned int tsapi_definedColumns();
 
 /*
- * Call this to free strings returned by the TotalSpaces API
+ * Sets the number of rows in the TotalSpaces grid.
+ * Returns true on success, false if the new grid would exceed TSAPI_MAX_SPACES
+ * or if rows 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_setDefinedRows(unsigned int rows);
+
+/*
+ * 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_setDefinedColumns(unsigned int columns);
+
+/*
+ * 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
+ * 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
+ * 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
+ * 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
+ * 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);
 
@@ -136,21 +158,21 @@ void tsapi_unsetSpaceWillChangeCallback();
 typedef void (*space_layout_changed_callback_t)(void);
 
 /*
- * Set the function that will be called when the layout changes
+ * 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
+ * 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
+ * Cancel layout change callbacks.
  */
 void tsapi_unsetLayoutChangedCallback();
 
 /*
- * Struct containing information about a window
+ * Struct containing information about a window.
  */
 struct tsapi_window {
   char *appName;
@@ -161,8 +183,8 @@ struct tsapi_window {
 };
 
 /*
- * Struct containing information about a space
- * Contains a pointer to an array of tsapi_window structs
+ * Struct containing information about a space.
+ * Contains a pointer to an array of tsapi_window structs.
  */
 struct tsapi_space {
   unsigned int spaceNumber;
@@ -172,7 +194,7 @@ struct tsapi_space {
 
 /*
  * Struct containing the count of spaces and a pointer to an
- * array of tsapi_space structs
+ * array of tsapi_space structs.
  */
 struct tsapi_spaces {
   unsigned int spacesCount;
@@ -181,11 +203,11 @@ struct tsapi_spaces {
 
 /*
  * Return a pointer to a tsapi_spaces struct containing information about all the windows
- * in all spaces
+ * in all spaces.
  *
- * The windows are listed front to back, so the first widow in the array is the frontmost
+ * 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
+ * You must call tsapi_freeWindowList when you have finished with this.
  */
 struct tsapi_spaces *tsapi_windowList();
 
@@ -202,5 +224,40 @@ void tsapi_freeWindowList(struct tsapi_spaces *windowList);
  */
 bool tsapi_moveWindowToSpace(unsigned int windowId, unsigned int spaceNumber);
 
+/*
+ * Move a space to another position
+ * You cannot move a space to position 1, and you cannot move the first
+ * space anywhere else - it is fixed.
+ * You cannot move full screen apps around with this method, only normal desktops.
+ *
+ * Returns true on success, false if the spaceNumber or positionNumber was
+ * invalid
+ */
+bool tsapi_moveSpaceToPosition(unsigned int spaceNumber, unsigned int positionNumber);
+
+/*
+ * Add desktops
+ * There can be at most 16 desktops
+ *
+ * Returns true on success, false if numberToAdd was zero, or would result in more than
+ * 16 desktops
+ */
+bool tsapi_addDesktops(unsigned int numberToAdd);
+
+/*
+ * 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_removeDesktops(unsigned int numberToRemove);
+
 #endif
 

data/lib/totalspaces.rb

@@ -36,9 +36,13 @@ module TSApi  #:nodoc:
   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_setDefinedRows, [:uint], :bool
+  attach_function :tsapi_setDefinedColumns, [:uint], :bool
+  
   attach_function :tsapi_moveToSpace, [:uint], :bool
   attach_function :tsapi_setNameForSpace, [:uint, :string], :bool
   
@@ -54,10 +58,18 @@ module TSApi  #:nodoc:
   attach_function :tsapi_freeWindowList, [:pointer], :void
   
   attach_function :tsapi_moveWindowToSpace, [:uint, :uint], :bool
+  
+  attach_function :tsapi_moveSpaceToPosition, [:uint, :uint], :bool
+  
+  attach_function :tsapi_addDesktops, [:uint], :bool
+  attach_function :tsapi_removeDesktops, [:uint], :bool
 end
 
 module TotalSpaces
 
+  MAX_DESKTOPS = 16
+  UNUSED_SPACE_NUMBER_OFFSET = 100
+
   #--
   # See tslib.h for the structures returned by the C API
   #++
@@ -96,6 +108,12 @@ module TotalSpaces
     #
     #   puts "libTotalSpaces version: #{TotalSpaces.lib_total_spaces_version}"
     #
+    #   if TotalSpaces.lib_total_spaces_version != TotalSpaces.api_version
+    #     puts "Comms error!"
+    #     exit(1)
+    #   end
+    #
+    #
     def lib_total_spaces_version
       string_and_free(TSApi.tsapi_libTotalSpacesVersion)
     end
@@ -105,6 +123,11 @@ module TotalSpaces
     #
     #   puts "TotalSpaces API version: #{TotalSpaces.api_version}"
     #
+    #   if TotalSpaces.lib_total_spaces_version != TotalSpaces.api_version
+    #     puts "Comms error!"
+    #     exit(1)
+    #   end
+    #
     def api_version
       string_and_free(TSApi.tsapi_apiVersion)
     end
@@ -197,10 +220,34 @@ module TotalSpaces
     def grid_columns
       TSApi.tsapi_definedColumns
     end
+
+    # Sets the number of rows defined in TotalSpaces.
+    #
+    # 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 rows.
+    #
+    #   TotalSpaces.set_grid_rows(3)
+    #
+    def set_grid_rows(rows)
+      TSApi.tsapi_setDefinedRows(rows)
+    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
+    # Sets the number of columns defined in TotalSpaces.
+    #
+    # 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.
+    #
+    #   TotalSpaces.set_grid_columns(3)
+    #
+    def set_grid_columns(columns)
+      TSApi.tsapi_setDefinedColumns(columns)
+    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)
     #
@@ -208,10 +255,10 @@ module TotalSpaces
       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
+    # 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")
     #
@@ -219,9 +266,9 @@ module TotalSpaces
       TSApi.tsapi_setNameForSpace(space_number, name)
     end
     
-    # Register for notifications on space change
+    # 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
+    # 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}";}
     #
@@ -233,14 +280,14 @@ module TotalSpaces
       TSApi.tsapi_setSpaceWillChangeCallback(block)
     end
     
-    # Cancel the on_space_change notification
+    # 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
+    # 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.
@@ -280,7 +327,6 @@ module TotalSpaces
     #     TotalSpaces.move_window_to_space(front_window[:window_id], TotalSpaces.current_space + 1)
     #   end
     #
-    end
     def window_list
       result = []
       list = TSApi.tsapi_windowList
@@ -314,5 +360,45 @@ module TotalSpaces
     def move_window_to_space(window_id, space_number)
       TSApi.tsapi_moveWindowToSpace(window_id, space_number)
     end
+    
+    # Move space to a new position
+    # You cannot move a space to position 1, and you cannot move the first
+    # space anywhere else - it is fixed.
+    # You cannot move full screen apps around with this method, only normal desktops
+    # Returns false if the space_number or position_number is not valid.
+    #
+    #   TotalSpaces.move_space_to_position(4, 2)
+    #
+    def move_space_to_position(space_number, position_number)
+      TSApi.tsapi_moveSpaceToPosition(space_number, position_number)
+    end
+    
+    # Add desktops
+    # There can be at most 16 desktops
+    # 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.
+    #
+    #   TotalSpaces.add_desktops(1)
+    #
+    def add_desktops(number_to_add)
+      TSApi.tsapi_addDesktops(number_to_add)
+    end
+    
+    # Remove 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 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.
+    #
+    # TotalSpaces.remove_desktops(1)
+    #
+    def remove_desktops(number_to_remove)
+      TSApi.tsapi_removeDesktops(number_to_remove)
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: totalspaces
 version: !ruby/object:Gem::Version
-  version: '0.1'
+  version: '0.2'
   prerelease: 
 platform: ruby
 authors: