totalspaces 0.1 → 0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -6,6 +6,10 @@ This gem enables you to get information from and to control {TotalSpaces}[link:h
6
6
 
7
7
  It is the officially supported way of using the API library libtotalspacesapi, and the required dylib
8
8
  comes bundled with this gem. This gem uses {Ruby-FFI}[link:https://github.com/ffi/ffi] to call the functions in the dylib.
9
+ You'll need a sane ruby and compilation environment to install ruby-ffi - it probably won't install immediately with the
10
+ ruby that comes with Mountain Lion because none of the compilation tools are present. We use {homebrew}[link:http://mxcl.github.com/homebrew/]
11
+ and {rbenv}[link:https://github.com/sstephenson/rbenv/] to manage our ruby scripting environment.
12
+ {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.
9
13
 
10
14
  You may use this gem in various ways. For instance, you could:
11
15
 
@@ -13,6 +13,8 @@
13
13
 
14
14
  #import <Foundation/Foundation.h>
15
15
 
16
+ #define TSAPI_MAX_SPACES 16
17
+
16
18
  /*
17
19
  * In case of comm error, all the functions apart from tsapi_libTotalSpacesVersion() will
18
20
  * return an empty string, zero, false or a pointer to a struct containing zero spaces (in
@@ -23,14 +25,14 @@
23
25
  */
24
26
 
25
27
  /*
26
- * The version of the API present in TotalSpaces.app
28
+ * The version of the API present in TotalSpaces.app.
27
29
  *
28
30
  * You must call tsapi_freeString when you have finished with the returned string.
29
31
  */
30
32
  const char *tsapi_apiVersion();
31
33
 
32
34
  /*
33
- * The version number of TotalSpaces itself
35
+ * The version number of TotalSpaces itself.
34
36
  *
35
37
  * You must call tsapi_freeString when you have finished with the returned string.
36
38
  */
@@ -38,90 +40,110 @@ const char *tsapi_totalSpacesVersion();
38
40
 
39
41
  /*
40
42
  * The version of the API dylib. This should match the string returned
41
- * by tsapi_apiVersion()
43
+ * by tsapi_apiVersion().
42
44
  *
43
45
  * You must call tsapi_freeString when you have finished with the returned string.
44
46
  */
45
47
  const char *tsapi_libTotalSpacesVersion();
46
48
 
47
49
  /*
48
- * The number of the current space
50
+ * The number of the current space.
49
51
  *
50
52
  * If the current space is the dashboard, 0 is returned.
51
53
  */
52
54
  unsigned int tsapi_currentSpaceNumber();
53
55
 
54
56
  /*
55
- * The name for the given space number
57
+ * The name for the given space number.
56
58
  *
57
59
  * You must call tsapi_freeString when you have finished with the returned string.
58
60
  */
59
61
  const char *tsapi_spaceNameForSpaceNumber(unsigned int spaceNumber);
60
62
 
61
63
  /*
62
- * The total number of spaces
64
+ * The total number of spaces.
63
65
  * This includes the dashboard if you have it set as a space, and any
64
- * fullscreen apps
66
+ * fullscreen apps.
65
67
  */
66
68
  unsigned int tsapi_numberOfSpaces();
67
69
 
68
70
  /*
69
- * The number of fullscreen apps
71
+ * The number of fullscreen apps.
70
72
  */
71
73
  unsigned int tsapi_numberOfFullScreens();
72
74
 
73
75
  /*
74
- * The number of desktops / normal spaces
76
+ * The number of desktops / normal spaces.
75
77
  */
76
78
  unsigned int tsapi_numberOfDesktops();
77
79
 
78
80
  /*
79
81
  * The number of fullscreen apps that are allowed to be present
80
- * in the grid, defined in advanced preferences
82
+ * in the grid, defined in advanced preferences.
81
83
  */
82
84
  unsigned int tsapi_numberOfFullScreensInGrid();
83
85
 
84
86
  /*
85
- * Is the dashboard set to be a space in Mission Control preferences
87
+ * Is the dashboard set to be a space in Mission Control preferences.
86
88
  */
87
89
  bool tsapi_dashboardIsASpace();
88
90
 
89
91
  /*
90
- * The number of rows defined in TotalSpaces layout preferences
92
+ * The number of rows defined in TotalSpaces layout preferences.
91
93
  */
92
94
  unsigned int tsapi_definedRows();
93
95
 
94
96
  /*
95
- * The number of columns defined in TotalSpaces layout preferences
97
+ * The number of columns defined in TotalSpaces layout preferences.
96
98
  */
97
99
  unsigned int tsapi_definedColumns();
98
100
 
99
101
  /*
100
- * Call this to free strings returned by the TotalSpaces API
102
+ * Sets the number of rows in the TotalSpaces grid.
103
+ * Returns true on success, false if the new grid would exceed TSAPI_MAX_SPACES
104
+ * or if rows is zero.
105
+ * Note that the actual number of desktops present in the system is unchanged,
106
+ * you should call tsapi_addDesktops or tsapi_removeDesktops after calling this
107
+ * function.
108
+ */
109
+ bool tsapi_setDefinedRows(unsigned int rows);
110
+
111
+ /*
112
+ * Sets the number of columns in the TotalSpaces grid.
113
+ * Returns true on success, false if the new grid would exceed TSAPI_MAX_SPACES
114
+ * or if columns is zero.
115
+ * Note that the actual number of desktops present in the system is unchanged,
116
+ * you should call tsapi_addDesktops or tsapi_removeDesktops after calling this
117
+ * function.
118
+ */
119
+ bool tsapi_setDefinedColumns(unsigned int columns);
120
+
121
+ /*
122
+ * Call this to free strings returned by the TotalSpaces API.
101
123
  */
102
124
  void tsapi_freeString(char *str);
103
125
 
104
126
  /*
105
- * Switch the display to the given space
106
- * Returns false if the space number is invalid
127
+ * Switch the display to the given space.
128
+ * Returns false if the space number is invalid.
107
129
  */
108
130
  bool tsapi_moveToSpace(unsigned int spaceNumber);
109
131
 
110
132
  /*
111
- * Set the name of a space
112
- * The maximum length is 255 bytes. The name should be in UTF-8
113
- * Returns true on success, false if the name was too long or the space number was invalid
133
+ * Set the name of a space.
134
+ * The maximum length is 255 bytes. The name should be in UTF-8.
135
+ * Returns true on success, false if the name was too long or the space number was invalid.
114
136
  */
115
137
  bool tsapi_setNameForSpace(unsigned int spaceNumber, char *name);
116
138
 
117
139
  /*
118
- * Type for space change callback
140
+ * Type for space change callback.
119
141
  */
120
142
  typedef void (*space_change_callback_t)(unsigned int fromSpaceNumber, unsigned int toSpaceNumber);
121
143
 
122
144
  /*
123
- * Set the function that will be called when the visible space changes
124
- * There is only one callback per process, registering a new callback will supercede any previous one
145
+ * Set the function that will be called when the visible space changes.
146
+ * There is only one callback per process, registering a new callback will supercede any previous one.
125
147
  */
126
148
  void tsapi_setSpaceWillChangeCallback(space_change_callback_t callback);
127
149
 
@@ -136,21 +158,21 @@ void tsapi_unsetSpaceWillChangeCallback();
136
158
  typedef void (*space_layout_changed_callback_t)(void);
137
159
 
138
160
  /*
139
- * Set the function that will be called when the layout changes
161
+ * Set the function that will be called when the layout changes.
140
162
  * This could be any change - for instance adding or removing a fullscreen, changing the name of a space,
141
163
  * or a change of rows or columns.
142
- * It indicates that you should re-request any information you are holding on the spaces
143
- * There is only one callback per process, registering a new callback will supercede any previous one
164
+ * It indicates that you should re-request any information you are holding on the spaces.
165
+ * There is only one callback per process, registering a new callback will supercede any previous one.
144
166
  */
145
167
  void tsapi_setLayoutChangedCallback(space_layout_changed_callback_t callback);
146
168
 
147
169
  /*
148
- * Cancel layout change callbacks
170
+ * Cancel layout change callbacks.
149
171
  */
150
172
  void tsapi_unsetLayoutChangedCallback();
151
173
 
152
174
  /*
153
- * Struct containing information about a window
175
+ * Struct containing information about a window.
154
176
  */
155
177
  struct tsapi_window {
156
178
  char *appName;
@@ -161,8 +183,8 @@ struct tsapi_window {
161
183
  };
162
184
 
163
185
  /*
164
- * Struct containing information about a space
165
- * Contains a pointer to an array of tsapi_window structs
186
+ * Struct containing information about a space.
187
+ * Contains a pointer to an array of tsapi_window structs.
166
188
  */
167
189
  struct tsapi_space {
168
190
  unsigned int spaceNumber;
@@ -172,7 +194,7 @@ struct tsapi_space {
172
194
 
173
195
  /*
174
196
  * Struct containing the count of spaces and a pointer to an
175
- * array of tsapi_space structs
197
+ * array of tsapi_space structs.
176
198
  */
177
199
  struct tsapi_spaces {
178
200
  unsigned int spacesCount;
@@ -181,11 +203,11 @@ struct tsapi_spaces {
181
203
 
182
204
  /*
183
205
  * Return a pointer to a tsapi_spaces struct containing information about all the windows
184
- * in all spaces
206
+ * in all spaces.
185
207
  *
186
- * The windows are listed front to back, so the first widow in the array is the frontmost
208
+ * The windows are listed front to back, so the first widow in the array is the frontmost.
187
209
  *
188
- * You must call tsapi_freeWindowList when you have finished with this
210
+ * You must call tsapi_freeWindowList when you have finished with this.
189
211
  */
190
212
  struct tsapi_spaces *tsapi_windowList();
191
213
 
@@ -202,5 +224,40 @@ void tsapi_freeWindowList(struct tsapi_spaces *windowList);
202
224
  */
203
225
  bool tsapi_moveWindowToSpace(unsigned int windowId, unsigned int spaceNumber);
204
226
 
227
+ /*
228
+ * Move a space to another position
229
+ * You cannot move a space to position 1, and you cannot move the first
230
+ * space anywhere else - it is fixed.
231
+ * You cannot move full screen apps around with this method, only normal desktops.
232
+ *
233
+ * Returns true on success, false if the spaceNumber or positionNumber was
234
+ * invalid
235
+ */
236
+ bool tsapi_moveSpaceToPosition(unsigned int spaceNumber, unsigned int positionNumber);
237
+
238
+ /*
239
+ * Add desktops
240
+ * There can be at most 16 desktops
241
+ *
242
+ * Returns true on success, false if numberToAdd was zero, or would result in more than
243
+ * 16 desktops
244
+ */
245
+ bool tsapi_addDesktops(unsigned int numberToAdd);
246
+
247
+ /*
248
+ * Remove desktops
249
+ * Removes numberToRemove desktops. The highest numbered desktops are removed.
250
+ *
251
+ * Removing a desktop you are currently on will result in TotalSpaces switching to
252
+ * another dektop.
253
+ *
254
+ * Any windows present on a desktop being removed will be moved to one of the
255
+ * remaining desktops.
256
+ *
257
+ * Returns true on success, false if numberToRemove was zero or would result in less
258
+ * than 1 desktop remaining.
259
+ */
260
+ bool tsapi_removeDesktops(unsigned int numberToRemove);
261
+
205
262
  #endif
206
263
 
Binary file
@@ -36,9 +36,13 @@ module TSApi #:nodoc:
36
36
  attach_function :tsapi_numberOfFullScreensInGrid, [], :uint
37
37
  attach_function :tsapi_numberOfDesktops, [], :uint
38
38
  attach_function :tsapi_dashboardIsASpace, [], :bool
39
+
39
40
  attach_function :tsapi_definedRows, [], :uint
40
41
  attach_function :tsapi_definedColumns, [], :uint
41
42
 
43
+ attach_function :tsapi_setDefinedRows, [:uint], :bool
44
+ attach_function :tsapi_setDefinedColumns, [:uint], :bool
45
+
42
46
  attach_function :tsapi_moveToSpace, [:uint], :bool
43
47
  attach_function :tsapi_setNameForSpace, [:uint, :string], :bool
44
48
 
@@ -54,10 +58,18 @@ module TSApi #:nodoc:
54
58
  attach_function :tsapi_freeWindowList, [:pointer], :void
55
59
 
56
60
  attach_function :tsapi_moveWindowToSpace, [:uint, :uint], :bool
61
+
62
+ attach_function :tsapi_moveSpaceToPosition, [:uint, :uint], :bool
63
+
64
+ attach_function :tsapi_addDesktops, [:uint], :bool
65
+ attach_function :tsapi_removeDesktops, [:uint], :bool
57
66
  end
58
67
 
59
68
  module TotalSpaces
60
69
 
70
+ MAX_DESKTOPS = 16
71
+ UNUSED_SPACE_NUMBER_OFFSET = 100
72
+
61
73
  #--
62
74
  # See tslib.h for the structures returned by the C API
63
75
  #++
@@ -96,6 +108,12 @@ module TotalSpaces
96
108
  #
97
109
  # puts "libTotalSpaces version: #{TotalSpaces.lib_total_spaces_version}"
98
110
  #
111
+ # if TotalSpaces.lib_total_spaces_version != TotalSpaces.api_version
112
+ # puts "Comms error!"
113
+ # exit(1)
114
+ # end
115
+ #
116
+ #
99
117
  def lib_total_spaces_version
100
118
  string_and_free(TSApi.tsapi_libTotalSpacesVersion)
101
119
  end
@@ -105,6 +123,11 @@ module TotalSpaces
105
123
  #
106
124
  # puts "TotalSpaces API version: #{TotalSpaces.api_version}"
107
125
  #
126
+ # if TotalSpaces.lib_total_spaces_version != TotalSpaces.api_version
127
+ # puts "Comms error!"
128
+ # exit(1)
129
+ # end
130
+ #
108
131
  def api_version
109
132
  string_and_free(TSApi.tsapi_apiVersion)
110
133
  end
@@ -197,10 +220,34 @@ module TotalSpaces
197
220
  def grid_columns
198
221
  TSApi.tsapi_definedColumns
199
222
  end
223
+
224
+ # Sets the number of rows defined in TotalSpaces.
225
+ #
226
+ # This does not change the actual number of desktops present, you should
227
+ # call add_desktops or remove_desktops as appropriate after changing the number
228
+ # of rows.
229
+ #
230
+ # TotalSpaces.set_grid_rows(3)
231
+ #
232
+ def set_grid_rows(rows)
233
+ TSApi.tsapi_setDefinedRows(rows)
234
+ end
200
235
 
201
- # Command TotalSpaces to switch to the given space number
202
- # Returns false if the space number was invalid
203
- # The on_space_change notification will be sent
236
+ # Sets the number of columns defined in TotalSpaces.
237
+ #
238
+ # This does not change the actual number of desktops present, you should
239
+ # call add_desktops or remove_desktops as appropriate after changing the number
240
+ # of columns.
241
+ #
242
+ # TotalSpaces.set_grid_columns(3)
243
+ #
244
+ def set_grid_columns(columns)
245
+ TSApi.tsapi_setDefinedColumns(columns)
246
+ end
247
+
248
+ # Command TotalSpaces to switch to the given space number.
249
+ # Returns false if the space number was invalid.
250
+ # The on_space_change notification will be sent.
204
251
  #
205
252
  # TotalSpaces.move_to_space(1)
206
253
  #
@@ -208,10 +255,10 @@ module TotalSpaces
208
255
  TSApi.tsapi_moveToSpace(space_number)
209
256
  end
210
257
 
211
- # Set the name for a space
212
- # Note that using this command will cause a layout notification to be sent
213
- # if the new name was different from that previously set
214
- # The maximum length for a name is 255 bytes
258
+ # Set the name for a space.
259
+ # Note that using this command will cause a layout notification to be sent.
260
+ # if the new name was different from that previously set.
261
+ # The maximum length for a name is 255 bytes.
215
262
  #
216
263
  # TotalSpaces.set_name_for_space(1, "Home")
217
264
  #
@@ -219,9 +266,9 @@ module TotalSpaces
219
266
  TSApi.tsapi_setNameForSpace(space_number, name)
220
267
  end
221
268
 
222
- # Register for notifications on space change
269
+ # Register for notifications on space change.
223
270
  # The given block will be called whenever you move from one space to another. The arguments are
224
- # the space number you moved from, and the one you are moving to
271
+ # the space number you moved from, and the one you are moving to.
225
272
  #
226
273
  # TotalSpaces.on_space_change {|from, to| puts "Moving from space #{from} to space #{to}";}
227
274
  #
@@ -233,14 +280,14 @@ module TotalSpaces
233
280
  TSApi.tsapi_setSpaceWillChangeCallback(block)
234
281
  end
235
282
 
236
- # Cancel the on_space_change notification
283
+ # Cancel the on_space_change notification.
237
284
  #
238
285
  def cancel_on_space_change
239
286
  $tsapi_on_space_change_block = nil
240
287
  TSApi.tsapi_unsetSpaceWillChangeCallback
241
288
  end
242
289
 
243
- # Register for notifications on layout change
290
+ # Register for notifications on layout change.
244
291
  # The given block will be called whenever the layout changes - this could be due to making an app
245
292
  # fullscreen, changing a space name, or changing the layout of the TotalSpaces grid. There are no
246
293
  # arguments passed to the block.
@@ -280,7 +327,6 @@ module TotalSpaces
280
327
  # TotalSpaces.move_window_to_space(front_window[:window_id], TotalSpaces.current_space + 1)
281
328
  # end
282
329
  #
283
- end
284
330
  def window_list
285
331
  result = []
286
332
  list = TSApi.tsapi_windowList
@@ -314,5 +360,45 @@ module TotalSpaces
314
360
  def move_window_to_space(window_id, space_number)
315
361
  TSApi.tsapi_moveWindowToSpace(window_id, space_number)
316
362
  end
363
+
364
+ # Move space to a new position
365
+ # You cannot move a space to position 1, and you cannot move the first
366
+ # space anywhere else - it is fixed.
367
+ # You cannot move full screen apps around with this method, only normal desktops
368
+ # Returns false if the space_number or position_number is not valid.
369
+ #
370
+ # TotalSpaces.move_space_to_position(4, 2)
371
+ #
372
+ def move_space_to_position(space_number, position_number)
373
+ TSApi.tsapi_moveSpaceToPosition(space_number, position_number)
374
+ end
375
+
376
+ # Add desktops
377
+ # There can be at most 16 desktops
378
+ # Returns true on success, false if number_to_add was zero, or would result
379
+ # in more than 16 desktops.
380
+ # The on_layout_change notification will be sent if a changed was made.
381
+ #
382
+ # TotalSpaces.add_desktops(1)
383
+ #
384
+ def add_desktops(number_to_add)
385
+ TSApi.tsapi_addDesktops(number_to_add)
386
+ end
387
+
388
+ # Remove desktops
389
+ # The highest numbered desktops are removed.
390
+ # Removing a desktop you are currently on will result in TotalSpaces switching to
391
+ # another dektop.
392
+ # Any windows present on a desktop being removed will be moved to one of the
393
+ # remaining desktops.
394
+ # Returns true on success, false if number_to_remove was zero or would result in less
395
+ # than 1 desktop remaining.
396
+ # The on_layout_change notification will be sent if a change was made.
397
+ #
398
+ # TotalSpaces.remove_desktops(1)
399
+ #
400
+ def remove_desktops(number_to_remove)
401
+ TSApi.tsapi_removeDesktops(number_to_remove)
402
+ end
317
403
  end
318
404
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: totalspaces
3
3
  version: !ruby/object:Gem::Version
4
- version: '0.1'
4
+ version: '0.2'
5
5
  prerelease:
6
6
  platform: ruby
7
7
  authors: