Skip to content

Sway Modules

Jump to bottom
Almarhoon Ibraheem edited this page Jun 25, 2024 · 2 revisions

The swayipc modules offer a range of functions to extend and modify Sway’s behavior. The primary goal of swayipc is to provide an interface for easily controlling Sway, with modules serving as configurable features that are simple to set up and use. This project aims to include as many Sway modules as necessary, allowing users to customize and integrate them into their configurations effortlessly.

Auto Reload

The auto-reload module is designed to automatically reload Sway configuration when changes are detected in specified directories. This module leverages the Sway IPC protocol for reloading and uses inotify for monitoring file system events. The key functions are:

  • auto-reload-configure: Configures the directories to watch for changes.
  • auto-reload-init: Initiates the monitoring of the specified directories and reloads the Sway configuration upon detecting changes.

Here’s an example of how to use this module:

;; NOTE: use the full path for your home, don't use tilde (~)
;; you may use env variable HOME and string append to get reference to your home.
(auto-reload-configure #:directories '("/home/ebeem/.config/sway/"))
(auto-reload-init)

General

The general module is designed to simplify and manage the definition of keybindings and submaps within the Sway window manager. It offers a structured approach to configure and dynamically handle keybindings and submaps.

  • Keybinding Management:
    • general-define-key: Assigns specific key chords to commands or submaps.
    • general-define-keys: Assigns multiple key chords and commands to a submap, with optional prefixes.
  • Configuration:
    • general-configure: Configures the keybinding translator function.
    • general-init: Initializes the module, sets up event hooks for handling Sway binding events and received commands.
(general-configure)
(general-init)

(general-define-keys
 ;; #:prefix "s-spc" #:wk "Leader"			;; can be done when module kbd is enabled
 #:prefix "mod4+Space" #:wk "Leader"
 `("o" (exec "rofi -show drun"))
 `("g" (sway-mode "default") #:wk "abort")

 ;; rofi keymap
 `(general-define-keys
   #:prefix "r" #:wk "Rofi"
   ("p" (exec "~/.config/rofi/bin/password-manager"))
   ("m" (exec "rofi-mount"))
   ("u" (exec "rofi-unmount"))
   ("w" (exec ".config/rofi/bin/wifi"))
   ("b" (exec "~/.config/rofi/bin/bluetooth"))
   ("f" (exec "~/.config/rofi/bin/finder"))
   ("k" (exec "~/.config/rofi/bin/keyboard-layout"))
   ("P" (exec "~/.config/rofi/bin/powermenu"))
   ("s" (exec "~/.config/rofi/bin/sound-input"))
   ("S" (exec "~/.config/rofi/bin/sound-output")))

 ;; window management
 `(general-define-keys
   #:prefix "w" #:wk "Window"
   ("v" (sway-layout SWAY-LAYOUT-SPLITV))
   ("h" (sway-layout SWAY-LAYOUT-SPLITH))
   ("f" (sway-fullscreen SWAY-FULLSCREEN-TOGGLE))
   ("d" (sway-layout SWAY-LAYOUT-DEFAULT))
   ("t" (sway-layout SWAY-LAYOUT-TABBED))))

KBD

The kbd module is a layer that translates emacs like keybindings into compatible sway keybindings. It allows users to add their own translations to a hashtable accessible from the kbd module. This module works very well with general since it accepts a translation procedure which is offered by kbd.

  • Translations Management:
    • kbd-define-modsym: Defines a modifier key translation from emacs like keybindings to sway compatible ones.
    • kbd-define-keysym: Defines a key translation from emacs like keybindings to sway compatible ones.
  • Configuration:
    • kbd-init: Initializes the module, sets up initial modifier and key translations.
;; init kbd
(kbd-init)

;; pass kbd-translate to general to enable translations
;; this allows adding keybindings like "s-SPC f"
;; which will be translated into "mod4+space f"
(general-configure #:keybinding-translator kbd-translate)
(general-init)

Which Key

The which-key module is an emacs like package that helps users discover available keybindings and commands interactively. When you start a key sequence, which-key will display a popup with all possible completions, making it easier to learn and remember keybindings without having to refer to documentation frequently.

Note: This works better with general as it uses the #:wk parameter in keybindings which describes the which key function.

  • Configuration:
    • which-key-configure: configures the idle delay before showing which key.
    • which-key-init: Initializes the module, sets up a hook for changing submap modes.
  • Hooks:
    • which-key-display-keybindings-hook: a hook that’s called when which-key should be displayed.
    • which-key-hide-keybindings-hook: a hook that’s called when which-key should be hidden.
;; show rofi message which-key
(define (show-rofi-message msg)
  (hide-rofi-message)
  (display (format #f "rofi -e \"~a\"" msg))
  (system (format #f "rofi -e \"~a\"" msg)))

;; hide rofi message which-key
(define (hide-rofi-message)
  (system "pkill -f '.*rofi -e.*'"))

;; hide which-ui function (will be hooked to which-key-display-keybindings-hook)
;; this simple show will display which key on guile display (e.g. repl/terminal)
;; and also call show-rofi-message to show which key using rofi (if it's installed)
(define (show-which-key submap bindings)
  (format #t "Displaying Submap ~a Bindings:\n" submap)
  (let ((message ""))
    (for-each
     (lambda (ls)
       (let ((nmsg (format #f "    - ~a -> ~a\n" (list-ref ls 1) (list-ref ls 3))))
        (display nmsg)
        (set! message (string-append message nmsg))))
     bindings)
    (show-rofi-message message)))

;; hide which-ui function (will be hooked to which-key-hide-keybindings-hook)
(define (hide-which-key submap)
  ;; hide your which-key viewer (rofi, eww, etc.)
  (format #t "Hiding Submap Bindings:\n")
  (hide-rofi-message))

;; adding hooks to display and hide which-key ui
(add-hook! which-key-display-keybindings-hook show-which-key)
(add-hook! which-key-hide-keybindings-hook hide-which-key)

Workspace Grid

The workspace-gird module provides a way to organize your workspaces in a grid layout, making it easier to manage multiple workspaces efficiently.

Note: Names of workspaces count should be equal to rows x columns Note: You have to assign keybindings to the exposed functions of this module to make good use of it.

  • Configuration:
    • workspace-gird-configure: configures the number of rows and columns and the names of workspaces.
    • workspace-gird-init: Initializes the module, validates the configuration.
  • Exposed Function:
    • workspace-grid-switch-workspace-up: switches workspace to the workspace in the direction up.
    • workspace-grid-switch-workspace-right: switches workspace to the workspace in the direction right.
    • workspace-grid-switch-workspace-down: switches workspace to the workspace in the direction down.
    • workspace-grid-switch-workspace-left: switches workspace to the workspace in the direction left.
    • workspace-grid-move-container-to-workspace-up: moves current window to the workspace in the direction up.
    • workspace-grid-move-container-to-workspace-right: moves current window workspace to the workspace in the direction right.
    • workspace-grid-move-container-to-workspace-down: moves current window workspace to the workspace in the direction down.
    • workspace-grid-move-container-to-workspace-left: moves current window workspace to the workspace in the direction left.
(workspace-grid-configure #:rows 2 #:columns 2 #:workspaces
                          '(("ws-o1-1" "ws-o1-2" "ws-o1-3" "ws-o1-4")  	;; output-1 workspaces
                            ("ws-o2-1" "ws-o2-2" "ws-o2-3" "ws-o2-4")))	;; output-2 workspaces
(workspace-grid-init)

Workspace Groups

The workspace-group module organizes workspaces in groups/activities/tasks such that switching to a workspace will automatically switch to the other workspaces configured. For example, communication group has workspace whatsapp on output#1 and irc on output#2. Having workspace-grid configured to sync these workspaces will automatically switch to workspace whatsapp when irc is focused and vise versa.

  • Configuration:
    • workspace-group-configure: configures the outputs and their synced workspaces.
    • workspace-group-init: Initializes the module, sets up hook on workspace changed.
(workspace-groups-configure
  #:outputs '("DP-1" "DP-2")
  #:groups '(("dp-1-browsing" "dp-2-browsing")
             ("dp-1-programming" "dp-2-programming")))
(workspace-groups-init)
Clone this wiki locally