diff --git a/README.md b/README.md index 63321d7..023ecd0 100644 --- a/README.md +++ b/README.md @@ -15,22 +15,20 @@ spaces on MacOS. 1. If you do not have [**Homebrew**](https://brew.sh) yet, install it and install [Hammerspoon](https://www.hammerspoon.org) for Mac automation: -``` -brew install --cask hammerspoon -``` + ``` + brew install --cask hammerspoon + ``` -2. Install the [spaces module](https://github.com/asmagill/hs._asm.spaces) - for Hammerspoon: + already including the [spaces module](https://github.com/asmagill/hs._asm.spaces) + in its latest version. -- Download `spaces-v0.x-universal.tar.gz` -- Extract it in your `.hammerspoon` folder: + > ⚠️ **Note:** As of macOS 14.5, some `spaces` functions [do not work correctly](https://github.com/Hammerspoon/hammerspoon/pull/3638). As a temporary solution, the Hammerspoon + > [build by user `gartnera`](https://github.com/gartnera/hammerspoon/releases/tag/0.10.0) + > can be used instead ((_vide_ **Known Issues**)). -``` -cd ~/.hammerspoon -tar -xzf ~/Downloads/spaces-v0.x.tar.gz -``` +
-3. Run `install.sh` to copy the `init.lua` file and the `restore_spaces` folder +2. Run `install.sh` to copy the `init.lua` file and the `restore_spaces` folder and into your `.hammerspoon` directory: ``` @@ -41,27 +39,33 @@ tar -xzf ~/Downloads/spaces-v0.x.tar.gz in your own `.hammerspoon/init.lua` file to avoid conflicts with other modules. -4. Set your preferred configurations and hotkey combinations, for example: +
-``` -local hs = {} -hs.hotkey = require "hs.hotkey" -hs.restore_spaces = require 'hs.restore.spaces.restore_spaces' - --- Configure 'restore_spaces' -hs.restore_spaces.verbose = false -hs.restore_spaces.space_pause = 0.3 -hs.restore_spaces.screen_pause = 0.4 - --- Bind hotkeys for 'restore_spaces' -hs.hotkey.bind({"cmd", "alt", "ctrl"}, "S", hs.restore_spaces.saveState) -hs.hotkey.bind({"cmd", "alt", "ctrl"}, "A", hs.restore_spaces.applyState) -``` +3. Set your preferred configurations and hotkey combinations, for example: + + ``` + local hs = {} + hs.hotkey = require "hs.hotkey" + hs.restore_spaces = require 'hs.restore.spaces.restore_spaces' + + -- Configure 'restore_spaces' + hs.restore_spaces.verbose = false + hs.restore_spaces.space_pause = 0.3 + hs.restore_spaces.screen_pause = 0.4 + + -- Bind hotkeys for 'restore_spaces' + hs.hotkey.bind({"cmd", "alt", "ctrl"}, "S", hs.restore_spaces.saveState) + hs.hotkey.bind({"cmd", "alt", "ctrl"}, "A", hs.restore_spaces.applyState) + ``` + +
-5. Open the Hammerspoon app, enable it in Accessibility, restart it and select +4. Open the Hammerspoon app, enable it in Accessibility, restart it and select `Reload Config`. -6. Run the commands a few times to check whether the `space_pause` and +
+ +5. Run the commands a few times to check whether the `space_pause` and `screen_pause` settings comply with your mac. They might need to be increased if the console prints: ``` @@ -95,13 +99,16 @@ Following features have already been implemented: - Check functionalities if/when space IDs change with space deletion/creation. - Add a workaround to deal with the phantom dashboard space (_vide_ **Known Issues**). +- Fix restore for windows that have empty title. +- Fix restore for a list of spaces that has their order changed, by using a + `space_map` variable to store the order of space IDs. +- Fix restore for windows that changed their ID after app restart (_vide_ + **Known Issues**). Current features under development; any help is appreciated: - Add a `notifyUser` call if `gotoSpace` fails due too short pause setting. -- Fix restore for windows that have empty title. -- Fix restore for windows that changed their ID after app restart (_vide_ - **Known Issues**). +- Add better logging to produce debugging reports. - Fix restore for two windows in Fullscreen, Tile left and Tile right, which current does not work (afaik, cannot be implemented). - Ensure save/apply do not consider hidden windows. @@ -115,12 +122,23 @@ Current features under development; any help is appreciated: - Add tests with mocking, due to the dependence on mac features. - ... +To use a development version of the `spaces` module, install it from its +[repo](https://github.com/asmagill/hs._asm.spaces) package: + +- Download `spaces-v0.x-universal.tar.gz` +- Extract it in your `.hammerspoon` folder: + +``` +cd ~/.hammerspoon +tar -xzf ~/Downloads/spaces-v0.x.tar.gz +``` + ## Known issues -1. The "Dashboard" feature may create a hidden space that cannot be accessed, - and thus breaks the `hs.spaces.gotoSpace()` method, even in MacOS versions - that do not feature Dashboard anymore. This can be see in the spaces plist - file, for example: +1. The **"Dashboard"** feature may create a hidden space that cannot be + accessed, and thus breaks the `hs.spaces.gotoSpace()` method, even in MacOS + versions that do not feature Dashboard anymore. This can be see in the + spaces plist file, for example: ``` defaults read com.apple.spaces.plist @@ -145,16 +163,31 @@ Current features under development; any help is appreciated: killall Dock ``` - Instead, the `plist` file is read and used to validate the list of spaces + Instead, that `plist` file is read and used to validate the list of spaces used to save the environment state. -1. There are no official APIs for putting two windows in split-view fullscreen - mode, so the current approach is to place all windows that had a fullscreen +1. There are no official APIs for putting two windows in **split-view** + fullscreen mode, so the current approach is to place all windows that had a fullscreen state (split-view or not) into single fullscreen. Split-view has to be set manually by the user (with the mouse) after calling `applyEnvironmentState`. -1. Window IDs change when you close/open an app. The current implementation - needs to be changed to take into account this. +1. **Window IDs change when you close/open an app.** The current implementation is + able to restore a window to a desired space during `apply` if that window + title is the same as it was during the `save` call. If the title changes for + any reason, that window will not be recognized. + In the particular case of apps in which windows can have multiple tabs, the + title tends to coincide with the title of the tab currently selected. This + is taken into account by the module with the `multitab_apps` settings, which + specifies for which apps the `save` and `apply` functions may cycle through + all tabs of each window to gather a list of titles. This is done using a + custom function developed in `applescript`. Windows are then restored during + `apply` by determiing whether they have a counterpart in the saved states, + by comparing the current list of tabs with the saved one. Thresholds for + what is considered a "counterpart" are defined by the `multitab_comparison` + setting, by establishing a fraction of the list of tabs that must coincide + (regardless of the order). Two fractions are defined, for comparing "short" + and "long" tab lists, with the number of tabs that switches between them + defined in `critical_tab_count`. 1. The function `spaces.moveWindowtoSpace` function [stopped working in MacOS 14.5](https://github.com/Hammerspoon/hammerspoon/pull/3638). The current @@ -164,5 +197,5 @@ Current features under development; any help is appreciated: which slightly increases the delay time of processing each Space. To avoid this increase in unnecessary cases, a switch for this is implemented as the `spaces_fixed_after_macOS14_5` global variable. It might become obsolete - after the `spaces` extension is updated in Hammerspoon to work with Sonoma - 14.5. + after the `spaces` extension is updated to work with **Sonoma 14.5** in the + Hammerspoon repo itself. diff --git a/restore_spaces/restore_spaces.lua b/restore_spaces/restore_spaces.lua index 959def2..235f0d2 100644 --- a/restore_spaces/restore_spaces.lua +++ b/restore_spaces/restore_spaces.lua @@ -28,11 +28,11 @@ rs.screen_pause = 0.4 -- in seconds (<0.4 breaks the spaces module) rs.multitab_pause = 0.01 -- in seconds (=0 breaks tab lists comparison) rs.multitab_comparison = { critical_tab_count = 10, -- decides which threshold to use - small_similarity_threshold = 0.8, -- small number of tabs - large_similarity_threshold = 0.6 -- large number of tabs + small_similarity_threshold = 0.8, -- 80%, for a small number of tabs + large_similarity_threshold = 0.6 -- 60%, for a large number of tabs } -rs.config_path = "scp/scp_config" rs.multitab_apps = {"Google Chrome", "Firefox", "Safari"} +rs.config_path = "scp/scp_config" rs.spaces_fixed_after_macOS14_5 = true --TODO: mod.max_spaces = 0 (maximum number of spaces saved per screen)