January Update

[Ottatop]

Hello Gros Michels and Cavendishes,

What's that? The last update was over half a year ago? And Silksong still isn't out? How tragic 😞.
In other news, good coding practices died today when I merged 30,000 lines of changes into main

As a result, enjoy this also way-too-big update detailing most of the changes that have occurred.

Note that there may still be changes because of my lack of planning.

General changes

• metaconfig.toml has been renamed to pinnacle.toml. Additionally, command = [...] is now run = [...]. Don't ask me why I'm doing random name changes.
• You no longer set a quit and reload keybind in the toml file.

Lua

• The API no longer gives you a Pinnacle table with all the config tables. Instead, you can require them yourself:

  -- Old
  require("pinnacle").setup(function(Pinnacle)
      local Input = Pinnacle.Input
  end)
  
  -- New
  local Input = require("pinnacle.input")
  require("pinnacle").setup(function() end)

Rust

• The API no longer uses an attribute macro to set up a config. Instead, use pinnacle_api::main!(config_fn):

  // Old
  #[pinnacle_api::config]
  async fn main() { ... }
  
  // New
  async fn config() { ... }
  pinnacle_api::main!(config);

  This has the benefit of rust-analyzer still working when syntax isn't fully formed.

• API functions are now accessible through free functions instead of unit-struct methods:

  // Old
  let modules = ApiModules::new();
  modules.input.keybind(...);
  
  // New
  pinnacle_api::input::keybind(...);

Input

General

• Bind modifiers now allow you to ignore a set of modifiers. Previously, if you set a keybind with modifiers Super and Shift, the compositor would require that Super and Shift be pressed while Ctrl and Alt not be pressed for the bind to trigger. Now, you can opt out of strict modifier checking per modifier:

  • Rust:

    input::keybind(Mod::SUPER | Mod::IGNORE_SHIFT | Mod::IGNORE_CTRL | Mod::IGNORE_ALT, ...);

  • Lua:

    input.keybind({ "super", "ignore_shift", "ignore_ctrl", "ignore_alt" }, ...);

• Support for the iso_level3_shift and iso_level5_shift modifiers has been implemented.

• Bind modes have been implemented. These allow you to switch between sets of key and mousebinds. Also I called them "layers" because internally they're in a stack.

  • Rust:

    let spawn_layer = BindLayer::get("spawn");
    spawn_layer.keybind(Mod::empty(), 'f')
        .on_press(|| Command::new("firefox").spawn());
    spawn_layer.keybind(Mod::empty(), 't')
        .on_press(|| Command::new("alacritty").spawn());
    spawn_layer.keybind(Mod::empty(), Keysym::Escape)
        .on_press(|| BindLayer::DEFAULT.enter());
    
    input::keybind(Mod::SUPER, 's')
        .on_press(move || spawn_layer.enter());

  • Lua:

    Input.keybind({
        mods = {},
        key = "f",
        bind_layer = "spawn",
        on_press = function()
            Process.spawn("firefox")
        end,
    })
    Input.keybind({
        mods = {},
        key = "t",
        bind_layer = "spawn",
        on_press = function()
            Process.spawn("alacritty")
        end,
    })
    Input.keybind({
        mods = {},
        key = key.Escape,
        bind_layer = "spawn",
        on_press = function()
            Input.enter_bind_layer(nil) -- `nil` is the default layer
        end,
    })
    
    Input.keybind({
        mods = { "super" },
        key = "s",
        bind_layer = "spawn",
        on_press = function()
            Input.enter_bind_layer("spawn")
        end
    })

• Release binds have been implemented. These allow you to execute an action on the release of a key or mouse button instead of on press. Additionally, if the bind has no on_press action, the key or mouse button used will still be passed through to any focused clients.

  • Rust:

    input::keybind(...)
        .on_release(|| println!("hey this happened on release"));

  • Lua:

    Input.keybind({
        mods = ...,
        key = ...,
        on_release = function()
            print("hey this happened on release")
        end
    })

• There is now a recommended way to set "quit" and "reload config" binds. Because configs are programs, they can hang or deadlock, preventing important keybinds like quitting from executing. Previously, you had to declare a hardcoded quit and reload config keybind within the metaconfig.toml file. Now, you define it within your config. Just make sure that your config doesn't somehow deadlock before setting these important binds.

  • Rust:

    input::keybind(Mod::SUPER | Mod::SHIFT, 'q')
        .set_as_quit();
    input::keybind(Mod::SUPER | Mod::CTRL, 'r')
        .set_as_reload_config();

  • Lua:

    Input.keybind({
        mods = { "super", "shift" },
        key = "q",
        quit = true,
    })
    Input.keybind({
        mods = { "super", "ctrl" },
        key = "r",
        reload_config = true,
    })

• The API for setting input device options has changed. Now, you provide a closure that will act on current and newly connected input devices. This means you can now target specific devices like touchpads for settings.

  • Lua:

    require("pinnacle.input.libinput").for_each_device(function(device)
        if device:device_type() == "touchpad" then
            device:set_natural_scroll(true)
        end
      
        if device:name() == "Razer Basilisk Whatever the name of this thing is I forgot" then
            device:set_accel_profile("flat")
        end
    end)

  • Rust:

    input::libinput::for_each_device(|device| {
        if device.device_type() == DeviceType::Touchpad {
            device.set_natural_scroll(true);
        }
      
        if device.name() == "Razer Basilisk Whatever the name of this thing is I forgot" {
            device.set_accel_profile(AccelProfile::Flat);
        }
    });

Lua

• There is now an alternative way to specify key and mousebinds. This way must be used if you want to assign the bind to a layer, set an action on release, or set a dedicated quit or reload config binding.

  -- Regular way (unchanged)
  Input.keybind({ mod_key, "shift" }, "c", function()
      local focused = Window.get_focused()
      if focused then
          focused:close()
      end
  end, {
      group = "Window",
      description = "Close the focused window",
  })
  
  -- New way
  Input.keybind({
      mods = ...,
      key = ...,
      bind_layer = ...,
      on_release = function() end,
      on_press = function() end,
  })
  

Rust

• Key and mousebinds have been reworked to use the builder pattern:

  // Old
  input.keybind(
      [mod_key, Mod::Shift],
      'c',
      || {
          if let Some(window) = window.get_focused() {
              window.close();
          }
      },
      KeybindInfo {
          group: Some("Window".into()),
          description: Some("Close the focused window".into()),
      },
  );
  
  // New
  input::keybind(mod_key | Mod::SHIFT, 'c')
      .on_press(|| {
          if let Some(window) = window::get_focused() {
              window.close();
          }
      })
      .group("Window")
      .description("Close the focused window");

• Modifiers have been changed to a bitflag instead of a list of modifiers:

  // Old
  input.mousebind([mod_key, Mod::Shift], ...);
  
  // New
  input::mousebind(mod_key | Mod::SHIFT, ...);

Process

General

• You can now spawn processes only once throughout the entire lifespan of the compositor. What was previously spawn_once was more like "spawn it if another instance isn't already running". This was a little awkward when reloading a config and having things that you wanted to close reopen. Now, that functionality has been moved to spawn_unique, and spawn_once now actually does what it says.
  • Rust:

    Command::new("alacritty").once().spawn();
    Command::new("alacritty").unique().spawn();

  • Lua:

    Process.spawn_once("alacritty");
    Process.spawn_unique("alacritty");

Lua

• The API for process spawning has been changed to be a bit more like Rust's std::process::Command. Instead of providing callbacks, spawning a process now yields a Child if successful. You can attach callbacks to the child and wait on it to retrieve exit information. There are helper functions that give you some of the older API's functionality.

  let child = assert(Process.command({
      cmd = "alacritty",
      envs = {
          SOME_ENV_VAR = "some_env_val",
      },
      once = true,
  }):spawn())
  
  child:on_line_stdout(function(line)
      print(line)
  end)
  
  local exit_info = child:wait()
  
  -- Helpers
  Process.spawn("program")
  Process.spawn_once("program")
  Process.spawn_unique("program")

Rust

• The process spawning API has been overhauled to be more like std::process's. Now, you create a Command that you can then spawn. If successful, you'll get the standard IO of the spawned process to do whatever you'd like with. You can also wait for the child to exit.

  use pinnacle_api::process::Command;
  
  let mut child = Command::new("cat").arg("/home/you/some_file").spawn()?;
  if let Some(stdout) = child.stdout.take() {
      let mut lines = pinnacle_api::tokio::io::BufReader::new(stdout).lines();
      tokio::spawn(async move {
          while let Ok(Some(line)) = lines.next_line().await {
              println!("cat said {line}");
          }
      })
  }
  
  let exit_info = child.wait()?;
  println!("cat exited with code {:?} and msg {:?}", exit_info.exit_code, exit_info.exit_msg);

Output

• connect_for_all is now for_each_output.

• The setup and setup_loc APIs have been removed until I think of something better. For now, consider using something like kanshi or build something on for_each_output.

Window

• Declarative window rules have been removed. I didn't really want a split between the rest of the API and the declarative system. Now, to add a window rule, you provide a closure that acts on newly spawned windows using the same API as everywhere else.
  • Lua:

    require("pinnacle.window").add_window_rule(function(window)
        window.set_decoration_mode("client_side")
    
        if window:app_id() == "alacritty" then
            window:set_floating(true)
        end
    end)

  • Rust:

    window::add_window_rule(|window| {
        window.set_decoration_mode(DecorationMode::ClientSide);
    
        if window.app_id() == "alacritty" {
            window.set_floating(true);
        }
    });

Layout

• The layout backend has been overhauled. Instead of the compositor requesting a list of geometries from clients, it now requests a tree of layout nodes that gets converted and fed to taffy to compute the layout. Cue me diving into a rabbit hole of tree-diffing academic papers for two weeks. This gives us actually accurate layouts instead of the napkin math that I gave y'all in the old system. It should also make it possible to support tile resizing. Soon ™️.
• Layout managers have been removed because, as it was pointed out in Are Layout Managers Necessary? #272, they didn't actually offer anything over another layout generator that does the cycling for you.
• Docs for the new system soon I swear, this post is getting really long

---

Aight I'm probably forgetting a bunch more stuff but the above is most of the big things that have changed.

Is 0.1 gonna release before Silksong? Is the cake a lie? Who knows! Let's hope I don't go silent for another half a year haha
Also I keep discarding and John Balatro isn't giving me the last card I need for a flush, rigged

...

^{What? You want to know if all this stuff actually works? Well there aren't any tests for the new stuff. What you're getting is like a few minutes of me ad hoc running everything just to make sure it works 👍}

[Abdillah]

Now, this is a cool way to break my build 🤣

[Ottatop]

Yeaaaa it's either this or carry all the less-than-ideal design decisions into 0.1 trying to keep backward-compatibility with older configs. Didn't want bloat from the latter (at least not until an actual version is out) so one big ol' change it is