How to set up scratchpads

[bakkeby]

This quick guide goes through the basics of setting up scratchpads.

General idea

The general idea of scratchpads is to have a window that you can quickly open to make some quick notes and then hide again, much like a physical scratchpad or notebook.

When it comes to window managers the term scratchpads have become synonymous with windows that pop in and out of existence on demand using keybindings.

In practice any window can be used as a scratchpad, for example a web browser or even a combination of multiple windows.

How it works

There are some basic principles with regards to how it works that may help you understand why scratchpads are configured the way they are.

These principles are the same whether you are using dusk or if you are using dwm with one of the many scratchpad patches.

Let's say that we want a keybinding MOD+w to open the program kwrite as a scratchpad.

Having configured the scratchpad correctly we have the expected scenario of:

• the user hits the MOD+w keybinding (1)
• the window manager will search for a client (window) that is associated with the given scratchpad
• if such a client is found then it will be revealed (or toggled away if already visible)
• but if such a client does not exist then it will spawn the program instead (2)
  • the spawned process may (should) open a window and
  • that window will ask to be shown (i.e. to be mapped) and
  • the window will be managed by the window manager and
  • we need a client rule (3) to associate the window with the given scratchpad so that the window manager may find it the next time the user hits that keybinding

In terms of configuration we need three separate things for this to work:

• (1) - a keybinding
• (2) - a command to spawn if we do not have a client associated with the scratchpad
• (3) - a client rule to associate the new window with the given scratchpad

The method of associating a client with a scratchpad and searching for a client associated with a scratchpad will depend on the patch used.

Configuration

Here we continue with the example of using kwrite as a scratchpad toggled using MOD+w.

The configuration will vary depending on what scratchpad patch is used.

For completeness this guide outlines configuration options for a series of scratchpad solutions.
Refer to the patch implementation of choice.

dwm + scratchpad

The old scratchpad patch supports a single scratchpad and works by adding a hidden tag that is viewed in tandem with other tags.

static const char scratchpadname[] = "scratchpad";

^ (3) this represents the window title and it is not matched via client rules; instead it has hardcoded logic in the manage function that associates the client with the scratchpad based on the window title.

static const char *scratchpadcmd[] = { "kwrite", "--title", scratchpadname, NULL };

^ (2) the command to execute if the scratchpad window does not exist.

    /* modifier                     key        function        argument */
    { MODKEY,                       XK_w,      togglescratch,  {.v = scratchpadcmd } },

^ (1) the keybinding to toggle/spawn the scratchpad.

dwm + scratchpads

The scratchpads patch supports multiple scratchpads and works by adding hidden tags that are viewed in tandem with other tags.

const char *spcmd_w[] = {"kwrite", "--title", "scratchpad_w", NULL };
const char *spcmd_e[] = {"kwrite", "--title", "scratchpad_e", NULL };

^ (2) the command(s) to execute if the scratchpad window does not exist.

static Sp scratchpads[] = {
    /* name          cmd  */
    {"scratchpad_w", spcmd_w},
    {"scratchpad_e", spcmd_e},
};

^ this is merely associating the scratchpad commands with an index in the scratchpads array, the name here is not actually used.

    /* modifier                     key        function        argument */
    { MODKEY,                       XK_w,      togglescratch,  {.ui = 0 } },
    { MODKEY,                       XK_e,      togglescratch,  {.ui = 1 } },

^ (1) the keybinding(s) that toggles the scratchpad based on the index in the scratchpads array.

    /* class      instance  title            tags mask       isfloating   monitor */
    { NULL,       NULL,     "scratchpad_w",  SPTAG(0),       1,           -1 },
    { NULL,       NULL,     "scratchpad_e",  SPTAG(1),       1,           -1 },

^ (3) the client rule(s) that associate clients with the given scratchpad index / tag.

dwm + namedscratchpads

The namedscratchpads patch supports multiple scratchpads and works by using a scratch "key" that is set for a client. Note that scratchpads are unique on a per monitor basis.

static const char *spcmd_w[] = {"w", "kwrite", "--title", "scratchpad_w", NULL};

^ (2) the command to execute if the scratchpad window does not exist.

Note the leading "w" in the command - this is the single letter scratch key that is associated with this scratchpad. You can use any character you want, but it is good practice to use the same character as the keyboard shortcut that you will use to toggle this scratchpad. "w" is chosen here because we want to use MOD+w as the keyboard shortcut.

    /* modifier                     key        function        argument */
    { MODKEY,                       XK_w,      togglescratch,  {.v = spcmd_w } },

^ (1) the keybinding to spawn the scratchpad, note how the command itself is passed to the
togglescratch function.

    /* class      instance  title            tags mask       isfloating   monitor   scratchkey */
    { NULL,       NULL,     "scratchpad_w",  0,              1,           -1,       'w' },

^ (3) the client rule that associates the client with the given scratch key.

dwm + renamedscratchpads

The renamedscratchpads patch is a variant of the namedscratchpads patch and as such the setup for this is the same. Refer to the instructions above.

The only notable difference is the extra keybindings to set or remove scratch keys.

    /* modifier                     key        function        argument */
    { MODKEY,                       XK_w,      togglescratch,  {.v = spcmd_w } },
    { MODKEY|ShiftMask,             XK_w,      removescratch,  {.v = spcmd_w } },
    { MODKEY|ControlMask,           XK_w,      setscratch,     {.v = spcmd_w } },

dwm + multimonitorscratchpads

The multimonitorscratchpads patch for dwm support multiple scratchpads.

The patch is similar to the namedscratchpads patch, but it does not use scratch keys. Instead it will check the class hints of every client each time togglescratch is triggered.

static const scratchpad spcmd_w = {.class = "kwrite", .v = (char *[]){"kwrite", NULL}};

^ (2) the command(s) to execute if the scratchpad window does not exist, along with the expected class.

    /* modifier                     key        function        argument */
    { MODKEY,                       XK_w,      togglescratch,  {.v = &spcmd_w } },

^ (1) the keybinding to spawn the scratchpad.

    /* class    instance  title   tags mask  isfloating   x, y, w, h        monitor */
    { "kwrite", NULL,     NULL,   0,         1,           .35,35,.3,.5,     -1},

^ (3) a client rule to make it floating and to give it a designated position and size. Note that this rule has nothing to do with associating the client with the scratchpad.

dwm + dynamicscratchpads

The dynamicscratchpads patch for dwm supports a single scratchpad that can hold multiple windows by the use of a special tag.

It mimics the behaviour of the scratchpad feature in i3wm where hidden scratchpad windows are stacked and are revealed one-by-one as they are popped from the stack.

It has neither client rules nor commands that are automatically executed, but instead expects the user to manually associate windows with the scratchpad during runtime.

That said one can still make a window start in the scratchpad by adding a client rule that assigns the special tag.

    /* class      instance  title           tags mask           isfloating   monitor */
    { NULL,       NULL,     "scratchpad_w", SCRATCHPAD_MASK,    0,           -1 },

Also see the original dwm-scratchpad patch.

dwm + multipledynamicscratchpads

The multipledynamicscratchpads patch for dwm supports three scratchpads and works by adding hidden tags that are viewed in tandem with other tags.

It has neither client rules nor commands that are automatically executed, but instead expects the user to manually associate windows with scratchpads during runtime.

The patch expands on the dynamicscratchpads patch.

One can still make a window start in the designated scratchpad by adding a client rule that assigns the special tag.

    /* class      instance  title           tags mask           isfloating   monitor */
    { NULL,       NULL,     "scratchpad_w", SCRATCHPAD_MASK_1,  0,           -1 },
    { NULL,       NULL,     "scratchpad_e", SCRATCHPAD_MASK_2,  0,           -1 },
    { NULL,       NULL,     "scratchpad_r", SCRATCHPAD_MASK_3,  0,           -1 },

dusk (renamedscratchpads)

dusk uses the renamedscratchpads patch and the general setup is the same as the namedscratchpads patch just that a macro is used to set up the keybindings and client rules are handled slightly differently.

static const char *spcmd_w[] = {"w", "kwrite", "--title", "scratchpad_w", NULL};
static const char *spcmd_e[] = {"e", "kwrite", "--title", "scratchpad_e", NULL};
static const char *spcmd_r[] = {"r", "kwrite", "--title", "scratchpad_r", NULL};

^ (2) the command to execute if the scratchpad window does not exist.

Note the leading "w" in the first command - this is the single letter scratch key that is associated with this scratchpad. You can use any character you want, but it is good practice to use the same character as the keyboard shortcut that you will use to toggle this scratchpad. "w" is chosen here because we want to use MOD+w as the keyboard shortcut.

  SCRATCHKEYS(MODKEY, XK_w, spcmd_w)
  SCRATCHKEYS(MODKEY, XK_e, spcmd_e)
  SCRATCHKEYS(MODKEY, XK_r, spcmd_r)

^ (1) the keybinding(s) to toggle/spawn the commands. Note how the commands themselves are passed as arguments.

The SCRATCHKEYS macro will set up keybindings for togglescratch, removescratch and setscratch.

  { .title = "scratchpad_w", .scratchkey = 'w', .flags = Floating },
  { .title = "scratchpad_e", .scratchkey = 'e', .flags = Floating },
  { .title = "scratchpad_r", .scratchkey = 'r', .flags = Floating },

^ (3) client rule(s) to associate windows with the given scratch key.

Also see the scratchpads page for more details.

General recommendations

As demonstrated in the various examples above adding a prefix or suffix indicating which scratchpad a given command is associated with makes the configuration a bit more manageable.

For example seeing the command of spcmd_x in the config file lets you draw the conclusion that it is in relation to the scratchpad with the MOD+x keybinding.

The same goes with finding a client rule that refers to "scratchpad_x" or "scratchpad (x)".

Doing this consistently makes it easier to spot what commands, keybindings and client rules are associated with each other should you need to make changes.

Troubleshooting

Here are a few issues that are fairly regular.

Scratchpad command won't spawn

Problem: I have set up scratchpads but when I hit the keybinding nothing happens.

1) Check that you have set up a keybinding to spawn the command

2) Check that the command and arguments are correctly spaced with commas and separate strings for each argument.

E.g. this will not work:

static const char *spcmd_w[] = {"w", "st -n 'spterm (w)' -g 120x34", NULL };

but this should:

static const char *spcmd_w[] = {"w", "st", "-n", "spterm (w)", "-g", "120x34", NULL };

Double check that the command works on the command line.

Note that if you are executing a shell script then that shell script may not be in the PATH environment variable that is visible to your window manager. This may be different from what you may have set in bash or some other shell.

If that is the case then try checking if using an absolute path to the script works. If that solves the issue then you may want to consider updating the path in your ~/.profile file.

Scratchpads keep opening

Problem: I have set up scratchpads, but every time I hit the keybinding a new window spawns instead of hiding the existing window.

1) Most likely your client rule does not match the window and thus the client is not associated with the given scratchpad.

Double check the client rules and note that:

• other rules may be interfering and
• some windows come through with no title, no class and no instance (e.g. spotify) and
• some windows may change title, class and instance after having been mapped (e.g. LibreOffice applications)

My scratchpad window interferes with the normal window

Problem: I use a particular application as a normal client, but I also want a second instance to work as a scratchpad. When I launch the normal client it becomes the scratchpad which I do not want.

1) Double check the client rules that identify the window as a scratchpad

Generally you will want to be able to uniquely identify the scratchpad window using the class, instance and/or window title (or other filters, if available). Some, but not all, windows will allow for some of these properties to be overridden using command line arguments.

If such command line arguments are available then you should definitely use them.

In cases where the application does not allow new instances to be spawned with a unique class, instance or window title then it may be that the only real solution is to assign scratchpads on demand during runtime (provided that the patch supports that).