From b8498348870221f5ff76c4c0e8fb3323f4565faf Mon Sep 17 00:00:00 2001 From: speedie Date: Wed, 25 Jan 2023 16:29:53 +0100 Subject: [PATCH] new documentation, rename lots of docs to add .md prefix --- .gitignore | 1 + Makefile | 4 +- README.md | 226 ++++++++++++-- bar.h | 2 +- docs/{credits => credits.md} | 0 docs/{dependencies => dependencies.md} | 2 +- docs/{doc-01 => doc-01.md} | 17 + docs/{doc-02 => doc-02.md} | 0 docs/{doc-03 => doc-03.md} | 0 docs/{doc-04 => doc-04.md} | 2 +- docs/{doc-05 => doc-05.md} | 2 +- docs/{doc-06 => doc-06.md} | 2 +- docs/{doc-07 => doc-07.md} | 2 +- docs/{doc-08 => doc-08.md} | 2 +- docs/{doc-09 => doc-09.md} | 2 +- docs/{doc-10 => doc-10.md} | 47 ++- docs/doc-11.md | 147 +++++++++ docs/keybinds | 1 - keybinds.h | 3 +- scripts/speedwm-help | 53 ++-- speedwm.1 | 416 +++++++++++++++++++++---- 21 files changed, 803 insertions(+), 128 deletions(-) rename docs/{credits => credits.md} (100%) rename docs/{dependencies => dependencies.md} (99%) rename docs/{doc-01 => doc-01.md} (70%) rename docs/{doc-02 => doc-02.md} (100%) rename docs/{doc-03 => doc-03.md} (100%) rename docs/{doc-04 => doc-04.md} (83%) rename docs/{doc-05 => doc-05.md} (99%) rename docs/{doc-06 => doc-06.md} (97%) rename docs/{doc-07 => doc-07.md} (98%) rename docs/{doc-08 => doc-08.md} (98%) rename docs/{doc-09 => doc-09.md} (91%) rename docs/{doc-10 => doc-10.md} (81%) create mode 100644 docs/doc-11.md diff --git a/.gitignore b/.gitignore index 669b1da..3e81742 100644 --- a/.gitignore +++ b/.gitignore @@ -13,3 +13,4 @@ core speedwm speedwm-ipc .custom_history +*.out diff --git a/Makefile b/Makefile index 801b8cc..34d29ce 100644 --- a/Makefile +++ b/Makefile @@ -86,7 +86,7 @@ install_only_misc: mkdir -p ${DESTDIR}${PREFIX}/bin mkdir -p ${DESTDIR}${PREFIX}/share/speedwm cp -f docs/keybinds ${DESTDIR}${PREFIX}/share/speedwm/keybinds - cp -f docs/dependencies ${DESTDIR}${PREFIX}/share/speedwm/dependencies + cp -f docs/dependencies.md ${DESTDIR}${PREFIX}/share/speedwm/dependencies.md cp -f docs/doc-* ${DESTDIR}${PREFIX}/share/speedwm/ cp -f docs/example.* ${DESTDIR}${PREFIX}/share/speedwm/ cp -f scripts/speedwm* ${DESTDIR}${PREFIX}/bin ; chmod +x ${DESTDIR}${PREFIX}/bin/speedwm* @@ -112,7 +112,7 @@ install: all [ -f speedwm.1 ] && mkdir -p ${DESTDIR}${MANPREFIX}/man1 || : [ -f speedwm.1 ] && cp speedwm.1 ${DESTDIR}${MANPREFIX}/man1/speedwm.1 || : cp -f docs/keybinds ${DESTDIR}${PREFIX}/share/speedwm/keybinds - cp -f docs/dependencies ${DESTDIR}${PREFIX}/share/speedwm/dependencies + cp -f docs/dependencies.md ${DESTDIR}${PREFIX}/share/speedwm/dependencies.md cp -f docs/doc-* ${DESTDIR}${PREFIX}/share/speedwm/ cp -f docs/example.* ${DESTDIR}${PREFIX}/share/speedwm/ cp -f scripts/speedwm* ${DESTDIR}${PREFIX}/bin ; chmod +x ${DESTDIR}${PREFIX}/bin/speedwm* diff --git a/README.md b/README.md index 4ea3423..b96d052 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,23 @@ # speedwm ![image](/docs/preview.png) +## Table of contents + +0. Table of contents +1. What is speedwm? +2. Installation +3. Layouts +4. Default keybinds +5. Dependencies +6. Important +7. Configuration and .Xresources +8. Signals +9. Status bar +10. Additional note on autostart +11. Configuring the bar +12. Keybinds +13. Credits + ## 1. What is speedwm? speedwm is a window manager forked from dwm or dynamic window manager. It manages the user's open windows and tiles them according to a set layout (dynamic). @@ -51,7 +68,7 @@ speedwm comes with the following layouts: They can be switched between using a little menu (See Keybinds for more information) or by right clicking the Layout indicator. The more commonly used layouts can be switched between using a quick keybind. -## 4. Keybinds +## 4. Default keybinds This is a full list of keybinds. Please let me know if any keybinds are missing as these have been manually added. @@ -70,7 +87,6 @@ Please let me know if any keybinds are missing as these have been manually added - Super+Shift+m - Opens the defined music player - Super+Shift+x - Opens the defined system process viewer in your terminal - Super+Shift+c - Opens the defined chat client -- Super+Shift+d - Opens iron in the terminal if it is installed - Super+Shift+u - Opens the defined RSS reader - Super+Shift+r - Opens the defined email client @@ -253,7 +269,7 @@ Please let me know if any keybinds are missing as these have been manually added - Dragging (SuperControl+Right click) - Increase/decrease cfact - Root window (Right click) - List .desktop entries and open them (requires j4-dmenu-desktop) -## Dependencies +## 5. Dependencies ### Required @@ -310,7 +326,7 @@ You can add, change and remove keybinds by editing `keybinds.h` and `mouse.h` an And everything under `Features`. -## 5. Important +## 6. Important If you're used to dwm, speedwm might be a little unfamiliar to you at first. This is because speedwm doesn't use config.h (or config.def.h). Instead, config.h is split into different parts to make it easier to edit. Instead of editing config.h you'll want to edit: @@ -339,7 +355,7 @@ You can also configure it by editing '~/.config/speedwm/statusrc'. If you want to change status bar, edit options.h and set 'static char status' to your status bar binary (must be in $PATH). Alternatively, you can also set it in .Xresources (See .Xresources and Pywal). -## 6. Configuration and .Xresources +## 7. Configuration and .Xresources speedwm has .Xresources support thanks to the .Xresources patch. It also has pywal support (tool which grabs colors based on your wallpaper). @@ -557,7 +573,7 @@ Below is a list of all .Xresources values you can define. - speedwm.status.rightpadding: - speedwm.status.separator: -## 7. Signals +## 8. Signals Thanks to the 'fsignal' patch available on suckless.org's website, we can easily write shell scripts to interact with dwm and therefore speedwm. I made some changes to this patch, because it has some.. questionable behaviour in my opinion. @@ -691,7 +707,7 @@ Below is a list of all signums and what they do. - 120 - Toggle border for the focused window - 121 - Reset bar padding and gaps -## 8. Status bar +## 9. Status bar speedwm has a status bar. It's the (by default) right part of the bar. It supports: @@ -713,24 +729,47 @@ By default the status bar runs modules that are also bundled with speedwm (see m The bundled status bar is autostarted by speedwm if it is installed. If you want to use your own status bar, comment out 'USESTATUS' in toggle.mk and remove /usr/bin/status if speedwm has been installed previously. Then simply start the status bar through autostart.h, ~/.config/speedwm/autostart.sh, .xinitrc or some other means of running a program. -## 9. Additional note on autostart +## 10. Additional note on autostart If you wish to add autostart entries without recompiling, consider using $HOME/.config/speedwm/autostart.sh. This is a path added to autostart.h and you can fill it with anything you want. Make sure your user has permission to execute the script. Note that this script or any other commands in autostart.h will **not** run when speedwm is restarted, only when speedwm is first started. -## 10. Configuring the bar +## 11. Configuring the bar -As of 1.8, speedwm has a module system. It is based on the barmodules patch for dwm and allows extensive control over the way the speedwm bar functions. This control has its own header, `bar.h`. +As of 1.8, speedwm has a module system. It is based on the `barmodules` patch for dwm and allows extensive control over the way the speedwm bar functions. This control has its own header, `bar.h`. `bar.h` contains a somewhat detailed list of all possible options here, but more importantly it contains a `barrules` array. This array similar to the `rules` array allows extensive control over where each bar module is placed and how it functions. In theory, this means you could put 22 instances of the same, boring tags on one bar, although why would one do that? Each module can be aligned to any part of the bar (See 'Alignment' for possible values). If, let's say multiple modules both align to the right next to the center split (middle), the first module takes priority. +### BarRule structure + +1. Monitor +Internally: `int monitor` + +2. Bar +Internally: `int bar` + +3. Alignment +Internally: `int alignment` + +4. Width function +Internally: `int (*widthfunc)(Bar *bar, BarWidthArg *a)` + +5. Draw function +Internally: `int (*drawfunc)(Bar *bar, BarDrawArg *a)` + +6. Click function +Intenrally: `int (*clickfunc)(Bar *bar, BarClickArg *a)` + +7. Name +Internally: `char *name` + ### Module list -Below is a list of all modules bundled with speedwm. The source code for these modules are all in bar/ and declared in bar/items.c and bar/items.h. If you want to add more, you can just declare them in the same way and add them to the barrules array if you want to use them. +Below is a list of all modules bundled with speedwm. The source code for these modules are all in `bar/` and declared in `bar/items.c` and `bar/items.h`. If you want to add more, you can just declare them in the same way and add them to the `barrules` array if you want to use them. - ltsymbol: Standard, basic layout icon. - tags: Basic tags, without powerlines. @@ -802,13 +841,15 @@ The module name really doesn't mean anything at all, it is just useful for debug With all that said, you should now be able to add a module. In case you weren't able to follow along, here is an example of how you can add powerline tags on the focused monitor. -1. `{ 'A', -2. 0, -3. bar_align_left, -4. width_tags_pwl, -5. draw_tags_pwl, -6. click_tags_pwl, -7. "my cool powerline tags" },` +1. `{ 'A',` +2. `0,` +3. `bar_align_left,` +4. `width_tags_pwl,` +5. `draw_tags_pwl,` +6. `click_tags_pwl,` +7. `"my cool powerline tags" },` + +Combined into one line: `{ 'A', 0, bar_align_left, width-tags_pwl, draw_tags_pwl, click_tags_pwl, "my cool powerline tags" },` Let's break down the above. @@ -820,9 +861,156 @@ Let's break down the above. 6. click_tags_pwl is the function we call to check if we clicked on that module. 7. A label for our module, it's only useful for debugging. -Feel free to copy the above to bar.h if you want to experiment with it. +Feel free to copy the above to `bar.h` if you want to experiment with it. Remember that you can have put any module wherever you want. Nothing is stopping you from having your tags on the right. This is what makes bar rules so powerful. +## 12. Keybinds + +Like the bar array mentioned previously, there is a `Key keys` array in `keybinds.h` which contains all keybinds speedwm will recognize. While this isn't the only way to add keybinds in speedwm, it does not require any additional software to be installed. + +### Key structure + +1. Event +Internally: `int type` + +2. Modifier +Internally: `unsigned int mod` + +3. Chain key +Internally: `KeySym chain` + +4. Key +Internally: `KeySym keysym` + +5. Function +Internally: `void (*func)(const Arg *)` + +6. Function arguments +Internally: `const Arg arg` + +### Event + +The event value allow you to specify when a keybind is executed. Internally this is known as `int type` and it specifies when the function is executed. + +- KeyPress: Activate immediately on key press. +- KeyRelease: Activate immediately on key release. + +### Modifier + +There are a lot of different modifiers, this list is only going to list the ones declared in speedwm. You can, of course declare more if necessary although it should be noted that doing so is out of the scope of this documentation. We will be focusing on the defined modifiers which are defined in `speedwm.c` like this: + +` +/* Modifiers */ +#define CONTROL ControlMask +#define SHIFT ShiftMask +#define ALT Mod1Mask +#define ALTR Mod3Mask +#define SUPER Mod4Mask +#define SUPERR Mod5Mask +` + +Below is a list of defined modifiers: + +- CONTROL Left Control (Ctrl) key. +- SHIFT Left Shift key. +- ALT Left Alt key. +- SUPER Left Super (Windows) key. +- SUPERR Right Super (Windows) key. + +In keybinds.h, MODIFIER1 and MODIFIER2 are also defined. MODIFIER1 is defined in order to make modifying keybinds easier. MODIFIER1 is by default defined as SUPER or Mod4Mask. For instance, if you want to use MODIFIER1 as your modifier, `MODIFIER1` would be the right value here. + +Do note that you can may use multiple modifiers. Do this by adding two or more modifiers separated by a pipe (MODIFIER1|SHIFT) + +### Chain key + +This value *is* mandatory, but it does not have to be used. speedwm has supported chained keybinds since 0.4. Chained keybinds allow more keybinds as like the name implies, the user has to press multiple keys to activate it. You can think of it as in Vim where there's different modes. + +The first key that needs to be pressed to activate a chain needs to be the key specified here. In order to see a list of possible keys, see `/usr/include/X11/keysymdef.h`. If, let's say we want to use simply the letter `a` as the key to start a chain, the value here would be `XK_a`. + +If we want a normal key, one that is **not** chained, we can accomplish that by simply setting the Chain key to `-1`. You can see this in the `keypress()` function in `speedwm.c`. This line of code is responsible for this behavior. + +`if (keysym == keys[i].keysym && keys[i].chain == -1` + +### Key + +The next value, similar to the Chain key also needs to be a keysym. If the key is a chained key, this is the second key that needs to be pressed. If it isn't a chained key, this is the key that needs to be pressed while the Modifier is pressed. + +In order to see a list of possible keys, see `/usr/include/X11/keysymdef.h`. Note that this path may differ depending on your operating system. + +There are a lot more keys technically defined, see `/usr/include/X11/XF86keysym.h` for a list of media keys. + +### Function + +Many functions expect `const Arg *arg` to be passed to them. However this value does require any function argument to be specified because it simply passes the next value to the function and calls it. + +There is no list of functions, but `speedwm.c` has a lot of declared functions which you may use in keybinds provided the function expects `const Arg *arg`. + +### Function arguments + +This is the actual argument passed to the function we're calling when the keybind is activated. Explaining this well would be fairly simple, but instead of doing so I recommend you read the `typedef union Arg` in `speedwm.c`. It looks like this: + +` +typedef union { + long i; + unsigned long ui; + float f; + const void *v; +} Arg; +` + +In short, Arg is a list of different types, which may be used to set different things in the argument. +Passing a float (such as mfact) through would mean I should override `.f`, passing an integer (such as barposition) through would mean I should override `.i`. There's also `.v` for `void` and `.ui` for tags. This is not used unless you want to mess with tag keybinds. + +When you don't care about the value given to the function, you may simply enter a `0`. + +### Example keybind + +With all that said, you probably get the idea of how it works. But you still don't know how to put all this knowledge together. + +1. `{ KeyPress,` +2. `MODIFIER1|SHIFT,` +3. `-1,` +4. `XK_w,` +5. `spawn,` +6. `cmd( "firefox" ) },` + +Combined into one line: `{ KeyPress, MODIFIER1|SHIFT, -1, XK_w, spawn, cmd( "firefox" ) },` + +Let's break down the above. + +1. This is our type. If it's `KeyPress`, it will be activated when the keybind is pressed. If it is `KeyRelease` it will be activated when the keybind is released. +2. This is our modifier. `MODIFIER1` is defined in `keybinds.h`. We're adding SHIFT to it, (defined in `speedwm.c`) which means we have to press BOTH `MODIFIER1` and `SHIFT` at the same time to activate this keybind. +3. This is our **chain** key. `-1` here indicates that we do not want it to be chained. We want a regular keybind. See the example below for an example *with* a chained keybind instead. +4. This is our regular key. `XK_w` is defined in `/usr/include/X11/keysymdef.h` on most operating systems and it means we have to press `w` on our keyboard along with the modifier to activate this keybind. +5. This is our function. We call this, passing the next value (`const Arg *arg`) to it. +6. This is our function argument. Do note that in this case `cmd()` is a macro and it is defined in `speedwm.c`. This macro will pass the contents of the macro to a shell it will spawn. + +Feel free to copy the above to `keybinds.h` if you want to experiment with it. + +### Example chained keybind + +1. `{ KeyPress,` +2. `MODIFIER1|SHIFT,` +3. `XK_a,` +4. `XK_w,` +5. `togglebar,` +6. `{0} },` + +Combined into one line: `{ KeyPress, MODIFIER1|SHIFT, XK_a, XK_w, togglebar, {0} },` + +Let's break down the above. + +1. This is our type. If it's `KeyPress`, it will be activated when the keybind is pressed. If it is `KeyRelease` it will be activated when the keybind is released. +2. This is our modifier. `MODIFIER1` is defined in `keybinds.h`. We're adding SHIFT to it, (defined in `speedwm.c`) which means we have to press BOTH `MODIFIER1` and `SHIFT` at the same time to activate this keybind. +3. This is our **chain** key. `XK_a` here is the key we have to press along with our modifier to activate this keybind. `XK_a` is defined in `/usr/include/X11/keysymdef.h` on most operating systems. +4. This is our regular key. `XK_w` is defined in `/usr/include/X11/keysymdef.h` on most operating systems and it means we have to press `w` on our keyboard to activate this keybind. Note that we do **not** need to press the modifier here, because it is a chained keybind. +5. This is our function. We call this, passing the next value (`const Arg *arg`) to it. +6. This is our function argument. We simply pass `0` here because we don't need to pass anything to the function, because the function does not care. + +Feel free to copy the above to `keybinds.h` if you want to experiment with it. + +This should give you a brief idea of how keybinds work in speedwm. Most of this carries over to `dwm` as well, although it does not have some of this stuff. It should be noted that as I mentioned previously, you don't HAVE to use this system. You can use external programs to handle keybinds, and `libspeedwm` to perform actions in speedwm. sxkbd is one popular program for this purpose and window managers like `bspwm` use it. However such a solution is out of the scope of this documentation! + ## Credits I far from wrote this entire project myself. Below are people who made this project what it is through submitting patches to suckless or otherwise contributing code in some way in alphabetical order. diff --git a/bar.h b/bar.h index 4c574dd..be828a9 100644 --- a/bar.h +++ b/bar.h @@ -64,6 +64,6 @@ static const BarRule barrules[] = { { -1, 0, bar_align_left, width_ltsymbol, draw_ltsymbol, click_ltsymbol, "layout" }, { -1, 0, bar_align_left, width_tags_pwl, draw_tags_pwl, click_tags_pwl, "powerline tags" }, { 'A', 0, bar_align_right, width_systray, draw_systray, click_systray, "systray" }, - { -1, 0, bar_align_right, width_status_pwl, draw_status_pwl, click_status_pwl, "powerline status" }, + { -1, 1, bar_align_right, width_status_pwl, draw_status_pwl, click_status_pwl, "powerline status" }, { -1, 0, bar_align_none, width_title, draw_title, click_title, "title" }, }; diff --git a/docs/credits b/docs/credits.md similarity index 100% rename from docs/credits rename to docs/credits.md diff --git a/docs/dependencies b/docs/dependencies.md similarity index 99% rename from docs/dependencies rename to docs/dependencies.md index 3c6052d..1ca0ec0 100644 --- a/docs/dependencies +++ b/docs/dependencies.md @@ -1,4 +1,4 @@ -## Dependencies +## 5. Dependencies ### Required diff --git a/docs/doc-01 b/docs/doc-01.md similarity index 70% rename from docs/doc-01 rename to docs/doc-01.md index 0a8f5f9..8a7713c 100644 --- a/docs/doc-01 +++ b/docs/doc-01.md @@ -1,6 +1,23 @@ # speedwm ![image](/docs/preview.png) +## Table of contents + +0. Table of contents +1. What is speedwm? +2. Installation +3. Layouts +4. Default keybinds +5. Dependencies +6. Important +7. Configuration and .Xresources +8. Signals +9. Status bar +10. Additional note on autostart +11. Configuring the bar +12. Keybinds +13. Credits + ## 1. What is speedwm? speedwm is a window manager forked from dwm or dynamic window manager. It manages the user's open windows and tiles them according to a set layout (dynamic). diff --git a/docs/doc-02 b/docs/doc-02.md similarity index 100% rename from docs/doc-02 rename to docs/doc-02.md diff --git a/docs/doc-03 b/docs/doc-03.md similarity index 100% rename from docs/doc-03 rename to docs/doc-03.md diff --git a/docs/doc-04 b/docs/doc-04.md similarity index 83% rename from docs/doc-04 rename to docs/doc-04.md index 00ae675..77d948a 100644 --- a/docs/doc-04 +++ b/docs/doc-04.md @@ -1,4 +1,4 @@ -## 4. Keybinds +## 4. Default keybinds This is a full list of keybinds. Please let me know if any keybinds are missing as these have been manually added. diff --git a/docs/doc-05 b/docs/doc-05.md similarity index 99% rename from docs/doc-05 rename to docs/doc-05.md index 12e6379..278856e 100644 --- a/docs/doc-05 +++ b/docs/doc-05.md @@ -1,4 +1,4 @@ -## 5. Important +## 6. Important If you're used to dwm, speedwm might be a little unfamiliar to you at first. This is because speedwm doesn't use config.h (or config.def.h). Instead, config.h is split into different parts to make it easier to edit. Instead of editing config.h you'll want to edit: diff --git a/docs/doc-06 b/docs/doc-06.md similarity index 97% rename from docs/doc-06 rename to docs/doc-06.md index 7f549a8..9c37acb 100644 --- a/docs/doc-06 +++ b/docs/doc-06.md @@ -1,4 +1,4 @@ -## 6. Configuration and .Xresources +## 7. Configuration and .Xresources speedwm has .Xresources support thanks to the .Xresources patch. It also has pywal support (tool which grabs colors based on your wallpaper). diff --git a/docs/doc-07 b/docs/doc-07.md similarity index 98% rename from docs/doc-07 rename to docs/doc-07.md index 64cbdc9..4724834 100644 --- a/docs/doc-07 +++ b/docs/doc-07.md @@ -1,5 +1,5 @@ -## 7. Signals +## 8. Signals Thanks to the 'fsignal' patch available on suckless.org's website, we can easily write shell scripts to interact with dwm and therefore speedwm. I made some changes to this patch, because it has some.. questionable behaviour in my opinion. diff --git a/docs/doc-08 b/docs/doc-08.md similarity index 98% rename from docs/doc-08 rename to docs/doc-08.md index 81e0f11..de8af6a 100644 --- a/docs/doc-08 +++ b/docs/doc-08.md @@ -1,4 +1,4 @@ -## 8. Status bar +## 9. Status bar speedwm has a status bar. It's the (by default) right part of the bar. It supports: diff --git a/docs/doc-09 b/docs/doc-09.md similarity index 91% rename from docs/doc-09 rename to docs/doc-09.md index 5de3ba8..803d8d1 100644 --- a/docs/doc-09 +++ b/docs/doc-09.md @@ -1,4 +1,4 @@ -## 9. Additional note on autostart +## 10. Additional note on autostart If you wish to add autostart entries without recompiling, consider using $HOME/.config/speedwm/autostart.sh. This is a path added to autostart.h and you can fill it with anything you want. Make sure your user has permission to execute the script. diff --git a/docs/doc-10 b/docs/doc-10.md similarity index 81% rename from docs/doc-10 rename to docs/doc-10.md index 0d9d13b..89a920c 100644 --- a/docs/doc-10 +++ b/docs/doc-10.md @@ -1,14 +1,37 @@ -## 10. Configuring the bar +## 11. Configuring the bar -As of 1.8, speedwm has a module system. It is based on the barmodules patch for dwm and allows extensive control over the way the speedwm bar functions. This control has its own header, `bar.h`. +As of 1.8, speedwm has a module system. It is based on the `barmodules` patch for dwm and allows extensive control over the way the speedwm bar functions. This control has its own header, `bar.h`. `bar.h` contains a somewhat detailed list of all possible options here, but more importantly it contains a `barrules` array. This array similar to the `rules` array allows extensive control over where each bar module is placed and how it functions. In theory, this means you could put 22 instances of the same, boring tags on one bar, although why would one do that? Each module can be aligned to any part of the bar (See 'Alignment' for possible values). If, let's say multiple modules both align to the right next to the center split (middle), the first module takes priority. +### BarRule structure + +1. Monitor +Internally: `int monitor` + +2. Bar +Internally: `int bar` + +3. Alignment +Internally: `int alignment` + +4. Width function +Internally: `int (*widthfunc)(Bar *bar, BarWidthArg *a)` + +5. Draw function +Internally: `int (*drawfunc)(Bar *bar, BarDrawArg *a)` + +6. Click function +Intenrally: `int (*clickfunc)(Bar *bar, BarClickArg *a)` + +7. Name +Internally: `char *name` + ### Module list -Below is a list of all modules bundled with speedwm. The source code for these modules are all in bar/ and declared in bar/items.c and bar/items.h. If you want to add more, you can just declare them in the same way and add them to the barrules array if you want to use them. +Below is a list of all modules bundled with speedwm. The source code for these modules are all in `bar/` and declared in `bar/items.c` and `bar/items.h`. If you want to add more, you can just declare them in the same way and add them to the `barrules` array if you want to use them. - ltsymbol: Standard, basic layout icon. - tags: Basic tags, without powerlines. @@ -80,13 +103,15 @@ The module name really doesn't mean anything at all, it is just useful for debug With all that said, you should now be able to add a module. In case you weren't able to follow along, here is an example of how you can add powerline tags on the focused monitor. -1. `{ 'A', -2. 0, -3. bar_align_left, -4. width_tags_pwl, -5. draw_tags_pwl, -6. click_tags_pwl, -7. "my cool powerline tags" },` +1. `{ 'A',` +2. `0,` +3. `bar_align_left,` +4. `width_tags_pwl,` +5. `draw_tags_pwl,` +6. `click_tags_pwl,` +7. `"my cool powerline tags" },` + +Combined into one line: `{ 'A', 0, bar_align_left, width-tags_pwl, draw_tags_pwl, click_tags_pwl, "my cool powerline tags" },` Let's break down the above. @@ -98,6 +123,6 @@ Let's break down the above. 6. click_tags_pwl is the function we call to check if we clicked on that module. 7. A label for our module, it's only useful for debugging. -Feel free to copy the above to bar.h if you want to experiment with it. +Feel free to copy the above to `bar.h` if you want to experiment with it. Remember that you can have put any module wherever you want. Nothing is stopping you from having your tags on the right. This is what makes bar rules so powerful. diff --git a/docs/doc-11.md b/docs/doc-11.md new file mode 100644 index 0000000..26240f4 --- /dev/null +++ b/docs/doc-11.md @@ -0,0 +1,147 @@ +## 12. Keybinds + +Like the bar array mentioned previously, there is a `Key keys` array in `keybinds.h` which contains all keybinds speedwm will recognize. While this isn't the only way to add keybinds in speedwm, it does not require any additional software to be installed. + +### Key structure + +1. Event +Internally: `int type` + +2. Modifier +Internally: `unsigned int mod` + +3. Chain key +Internally: `KeySym chain` + +4. Key +Internally: `KeySym keysym` + +5. Function +Internally: `void (*func)(const Arg *)` + +6. Function arguments +Internally: `const Arg arg` + +### Event + +The event value allow you to specify when a keybind is executed. Internally this is known as `int type` and it specifies when the function is executed. + +- KeyPress: Activate immediately on key press. +- KeyRelease: Activate immediately on key release. + +### Modifier + +There are a lot of different modifiers, this list is only going to list the ones declared in speedwm. You can, of course declare more if necessary although it should be noted that doing so is out of the scope of this documentation. We will be focusing on the defined modifiers which are defined in `speedwm.c` like this: + +` +/* Modifiers */ +#define CONTROL ControlMask +#define SHIFT ShiftMask +#define ALT Mod1Mask +#define ALTR Mod3Mask +#define SUPER Mod4Mask +#define SUPERR Mod5Mask +` + +Below is a list of defined modifiers: + +- CONTROL Left Control (Ctrl) key. +- SHIFT Left Shift key. +- ALT Left Alt key. +- SUPER Left Super (Windows) key. +- SUPERR Right Super (Windows) key. + +In keybinds.h, MODIFIER1 and MODIFIER2 are also defined. MODIFIER1 is defined in order to make modifying keybinds easier. MODIFIER1 is by default defined as SUPER or Mod4Mask. For instance, if you want to use MODIFIER1 as your modifier, `MODIFIER1` would be the right value here. + +Do note that you can may use multiple modifiers. Do this by adding two or more modifiers separated by a pipe (MODIFIER1|SHIFT) + +### Chain key + +This value *is* mandatory, but it does not have to be used. speedwm has supported chained keybinds since 0.4. Chained keybinds allow more keybinds as like the name implies, the user has to press multiple keys to activate it. You can think of it as in Vim where there's different modes. + +The first key that needs to be pressed to activate a chain needs to be the key specified here. In order to see a list of possible keys, see `/usr/include/X11/keysymdef.h`. If, let's say we want to use simply the letter `a` as the key to start a chain, the value here would be `XK_a`. + +If we want a normal key, one that is **not** chained, we can accomplish that by simply setting the Chain key to `-1`. You can see this in the `keypress()` function in `speedwm.c`. This line of code is responsible for this behavior. + +`if (keysym == keys[i].keysym && keys[i].chain == -1` + +### Key + +The next value, similar to the Chain key also needs to be a keysym. If the key is a chained key, this is the second key that needs to be pressed. If it isn't a chained key, this is the key that needs to be pressed while the Modifier is pressed. + +In order to see a list of possible keys, see `/usr/include/X11/keysymdef.h`. Note that this path may differ depending on your operating system. + +There are a lot more keys technically defined, see `/usr/include/X11/XF86keysym.h` for a list of media keys. + +### Function + +Many functions expect `const Arg *arg` to be passed to them. However this value does require any function argument to be specified because it simply passes the next value to the function and calls it. + +There is no list of functions, but `speedwm.c` has a lot of declared functions which you may use in keybinds provided the function expects `const Arg *arg`. + +### Function arguments + +This is the actual argument passed to the function we're calling when the keybind is activated. Explaining this well would be fairly simple, but instead of doing so I recommend you read the `typedef union Arg` in `speedwm.c`. It looks like this: + +` +typedef union { + long i; + unsigned long ui; + float f; + const void *v; +} Arg; +` + +In short, Arg is a list of different types, which may be used to set different things in the argument. +Passing a float (such as mfact) through would mean I should override `.f`, passing an integer (such as barposition) through would mean I should override `.i`. There's also `.v` for `void` and `.ui` for tags. This is not used unless you want to mess with tag keybinds. + +When you don't care about the value given to the function, you may simply enter a `0`. + +### Example keybind + +With all that said, you probably get the idea of how it works. But you still don't know how to put all this knowledge together. + +1. `{ KeyPress,` +2. `MODIFIER1|SHIFT,` +3. `-1,` +4. `XK_w,` +5. `spawn,` +6. `cmd( "firefox" ) },` + +Combined into one line: `{ KeyPress, MODIFIER1|SHIFT, -1, XK_w, spawn, cmd( "firefox" ) },` + +Let's break down the above. + +1. This is our type. If it's `KeyPress`, it will be activated when the keybind is pressed. If it is `KeyRelease` it will be activated when the keybind is released. +2. This is our modifier. `MODIFIER1` is defined in `keybinds.h`. We're adding SHIFT to it, (defined in `speedwm.c`) which means we have to press BOTH `MODIFIER1` and `SHIFT` at the same time to activate this keybind. +3. This is our **chain** key. `-1` here indicates that we do not want it to be chained. We want a regular keybind. See the example below for an example *with* a chained keybind instead. +4. This is our regular key. `XK_w` is defined in `/usr/include/X11/keysymdef.h` on most operating systems and it means we have to press `w` on our keyboard along with the modifier to activate this keybind. +5. This is our function. We call this, passing the next value (`const Arg *arg`) to it. +6. This is our function argument. Do note that in this case `cmd()` is a macro and it is defined in `speedwm.c`. This macro will pass the contents of the macro to a shell it will spawn. + +Feel free to copy the above to `keybinds.h` if you want to experiment with it. + +### Example chained keybind + +1. `{ KeyPress,` +2. `MODIFIER1|SHIFT,` +3. `XK_a,` +4. `XK_w,` +5. `togglebar,` +6. `{0} },` + +Combined into one line: `{ KeyPress, MODIFIER1|SHIFT, XK_a, XK_w, togglebar, {0} },` + +Let's break down the above. + +1. This is our type. If it's `KeyPress`, it will be activated when the keybind is pressed. If it is `KeyRelease` it will be activated when the keybind is released. +2. This is our modifier. `MODIFIER1` is defined in `keybinds.h`. We're adding SHIFT to it, (defined in `speedwm.c`) which means we have to press BOTH `MODIFIER1` and `SHIFT` at the same time to activate this keybind. +3. This is our **chain** key. `XK_a` here is the key we have to press along with our modifier to activate this keybind. `XK_a` is defined in `/usr/include/X11/keysymdef.h` on most operating systems. +4. This is our regular key. `XK_w` is defined in `/usr/include/X11/keysymdef.h` on most operating systems and it means we have to press `w` on our keyboard to activate this keybind. Note that we do **not** need to press the modifier here, because it is a chained keybind. +5. This is our function. We call this, passing the next value (`const Arg *arg`) to it. +6. This is our function argument. We simply pass `0` here because we don't need to pass anything to the function, because the function does not care. + +Feel free to copy the above to `keybinds.h` if you want to experiment with it. + +This should give you a brief idea of how keybinds work in speedwm. Most of this carries over to `dwm` as well, although it does not have some of this stuff. It should be noted that as I mentioned previously, you don't HAVE to use this system. You can use external programs to handle keybinds, and `libspeedwm` to perform actions in speedwm. sxkbd is one popular program for this purpose and window managers like `bspwm` use it. However such a solution is out of the scope of this documentation! + diff --git a/docs/keybinds b/docs/keybinds index cd172b7..b1ccce7 100644 --- a/docs/keybinds +++ b/docs/keybinds @@ -12,7 +12,6 @@ - Super+Shift+m - Opens the defined music player - Super+Shift+x - Opens the defined system process viewer in your terminal - Super+Shift+c - Opens the defined chat client -- Super+Shift+d - Opens iron in the terminal if it is installed - Super+Shift+u - Opens the defined RSS reader - Super+Shift+r - Opens the defined email client diff --git a/keybinds.h b/keybinds.h index e712eea..152d3e5 100644 --- a/keybinds.h +++ b/keybinds.h @@ -1,6 +1,6 @@ /* These are all your keybinds. * - * Types + * Event * * KeyPress - Activate when a key is pressed. * KeyRelease - Activate when a key is released. @@ -58,7 +58,6 @@ static Key keys[] = { { KeyPress, MODIFIER1|SHIFT, -1, XK_f, spawn, cmd( TERMINAL "lfrun || lf" ) }, { KeyPress, MODIFIER1|SHIFT, -1, XK_w, spawn, cmd( "chromium || chromium-bin" ) }, { KeyPress, MODIFIER1|SHIFT, -1, XK_o, spawn, cmd( "speedwm-dfmpeg" ) }, - { KeyPress, MODIFIER1|SHIFT, -1, XK_d, spawn, cmd( TERMINAL "iron" ) }, { KeyPress, MODIFIER1|SHIFT, -1, XK_t, spawn, cmd( TERMINAL "nvim" ) }, { KeyPress, MODIFIER1|SHIFT, -1, XK_a, spawn, cmd( TERMINAL "speedwm-audioctrl -runmixer" ) }, { KeyPress, MODIFIER1|SHIFT, -1, XK_m, spawn, cmd( TERMINAL "tmux new-session -A -D -s cmus $(which --skip-alias cmus)" ) }, diff --git a/scripts/speedwm-help b/scripts/speedwm-help index 67f7e5f..7564a28 100755 --- a/scripts/speedwm-help +++ b/scripts/speedwm-help @@ -31,7 +31,8 @@ HELP() { printf "%s-9 Important details.\n" printf "%s-10 Additional note on autostart.\n" printf "%s-11 Configuring the bar.\n" - printf "%s-12 Credits.\n" + printf "%s-12 Keybinds.\n" + printf "%s-13 Credits.\n" printf "%sNo arguments View this list of arguments.\n" printf "\n" printf "%s--generate-markdown Write documentation (Markdown)\n" @@ -87,21 +88,22 @@ FORMATMD() { } # write docs -cat "${DOCDIR}/${PREFIX}doc-01" \ -"${DOCDIR}/${PREFIX}doc-02" \ -"${DOCDIR}/${PREFIX}doc-03" \ -"${DOCDIR}/${PREFIX}doc-04" \ +cat "${DOCDIR}/${PREFIX}doc-01.md" \ +"${DOCDIR}/${PREFIX}doc-02.md" \ +"${DOCDIR}/${PREFIX}doc-03.md" \ +"${DOCDIR}/${PREFIX}doc-04.md" \ "${DOCDIR}/${PREFIX}keybinds" \ -"${DOCDIR}/${PREFIX}dependencies" \ -"${DOCDIR}/${PREFIX}doc-05" \ -"${DOCDIR}/${PREFIX}doc-06" \ +"${DOCDIR}/${PREFIX}dependencies.md" \ +"${DOCDIR}/${PREFIX}doc-05.md" \ +"${DOCDIR}/${PREFIX}doc-06.md" \ "/tmp/example.Xresources" \ -"${DOCDIR}/${PREFIX}doc-07" \ +"${DOCDIR}/${PREFIX}doc-07.md" \ "${DOCDIR}/${PREFIX}example.signal" \ -"${DOCDIR}/${PREFIX}doc-08" \ -"${DOCDIR}/${PREFIX}doc-09" \ -"${DOCDIR}/${PREFIX}doc-10" \ -"${DOCDIR}/${PREFIX}credits" | \ +"${DOCDIR}/${PREFIX}doc-08.md" \ +"${DOCDIR}/${PREFIX}doc-09.md" \ +"${DOCDIR}/${PREFIX}doc-10.md" \ +"${DOCDIR}/${PREFIX}doc-11.md" \ +"${DOCDIR}/${PREFIX}credits.md" | \ grep -v "!!" > "/tmp/${PREFIX}doc" # check arguments and perform actions based on it @@ -113,18 +115,19 @@ case "$1" in "") $0 -h && exit 0 ;; "-h") HELP && exit 0 ;; "--help") HELP && exit 0 ;; -"-1") tail -n +4 "${DOCDIR}/${PREFIX}doc-01" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;; -"-2") cat "${DOCDIR}/${PREFIX}doc-04" "${DOCDIR}/${PREFIX}keybinds" > "/tmp/stdout" ; $VIEWER "/tmp/stdout" ; exit 0 ;; -"-3") cat "${DOCDIR}/${PREFIX}dependencies" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;; -"-4") cat "${DOCDIR}/${PREFIX}doc-06" "/tmp/example.Xresources" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;; -"-5") cat "${DOCDIR}/${PREFIX}doc-07" "${DOCDIR}/${PREFIX}example.signal" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;; -"-6") cat "${DOCDIR}/${PREFIX}doc-08" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;; -"-7") cat "${DOCDIR}/${PREFIX}doc-02" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;; -"-8") cat "${DOCDIR}/${PREFIX}doc-03" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;; -"-9") cat "${DOCDIR}/${PREFIX}doc-05" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;; -"-10") cat "${DOCDIR}/${PREFIX}doc-09" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;; -"-11") cat "${DOCDIR}/${PREFIX}doc-10" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;; -"-12") cat "${DOCDIR}/${PREFIX}credits" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;; +"-1") tail -n +4 "${DOCDIR}/${PREFIX}doc-01.md" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;; +"-2") cat "${DOCDIR}/${PREFIX}doc-04.md" "${DOCDIR}/${PREFIX}keybinds" > "/tmp/stdout" ; $VIEWER "/tmp/stdout" ; exit 0 ;; +"-3") cat "${DOCDIR}/${PREFIX}dependencies.md" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;; +"-4") cat "${DOCDIR}/${PREFIX}doc-06.md" "/tmp/example.Xresources" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;; +"-5") cat "${DOCDIR}/${PREFIX}doc-07.md" "${DOCDIR}/${PREFIX}example.signal" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;; +"-6") cat "${DOCDIR}/${PREFIX}doc-08.md" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;; +"-7") cat "${DOCDIR}/${PREFIX}doc-02.md" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;; +"-8") cat "${DOCDIR}/${PREFIX}doc-03.md" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;; +"-9") cat "${DOCDIR}/${PREFIX}doc-05.md" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;; +"-10") cat "${DOCDIR}/${PREFIX}doc-09.md" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;; +"-11") cat "${DOCDIR}/${PREFIX}doc-10.md" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;; +"-12") cat "${DOCDIR}/${PREFIX}doc-11.md" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;; +"-13") cat "${DOCDIR}/${PREFIX}credits.md" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;; "-a") cat "/tmp/${PREFIX}doc" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;; esac diff --git a/speedwm.1 b/speedwm.1 index b06847c..f93d44d 100644 --- a/speedwm.1 +++ b/speedwm.1 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pandoc 3.0 +.\" Automatically generated by Pandoc 2.19.2 .\" .\" Define V font for inline verbatim, using C font in formats .\" that render this, and otherwise B font. @@ -17,6 +17,35 @@ .TH "speedwm" "1" "" "1.9" "speedie\[cq]s window manager." .hy .SH speedwm +.SS Table of contents +.IP " 0." 4 +Table of contents +.IP " 1." 4 +What is speedwm? +.IP " 2." 4 +Installation +.IP " 3." 4 +Layouts +.IP " 4." 4 +Default keybinds +.IP " 5." 4 +Dependencies +.IP " 6." 4 +Important +.IP " 7." 4 +Configuration and .Xresources +.IP " 8." 4 +Signals +.IP " 9." 4 +Status bar +.IP "10." 4 +Additional note on autostart +.IP "11." 4 +Configuring the bar +.IP "12." 4 +Keybinds +.IP "13." 4 +Credits .SS 1. What is speedwm? .PP speedwm is a window manager forked from dwm or dynamic window manager. @@ -112,7 +141,7 @@ They can be switched between using a little menu (See Keybinds for more information) or by right clicking the Layout indicator. The more commonly used layouts can be switched between using a quick keybind. -.SS 4. Keybinds +.SS 4. Default keybinds .PP This is a full list of keybinds. Please let me know if any keybinds are missing as these have been @@ -146,8 +175,6 @@ Super+Shift+x - Opens the defined system process viewer in your terminal .IP \[bu] 2 Super+Shift+c - Opens the defined chat client .IP \[bu] 2 -Super+Shift+d - Opens iron in the terminal if it is installed -.IP \[bu] 2 Super+Shift+u - Opens the defined RSS reader .IP \[bu] 2 Super+Shift+r - Opens the defined email client @@ -507,7 +534,7 @@ Dragging (SuperControl+Right click) - Increase/decrease cfact .IP \[bu] 2 Root window (Right click) - List .desktop entries and open them (requires j4-dmenu-desktop) -.SS Dependencies +.SS 5. Dependencies .SS Required .PP These are absolutely necessary, speedwm will NOT compile without them - @@ -600,7 +627,7 @@ tmux - Used for the music player and IRC client j4-dmenu-desktop - Listing .desktop entries .PP And everything under \f[V]Features\f[R]. -.SS 5. Important +.SS 6. Important .PP If you\[cq]re used to dwm, speedwm might be a little unfamiliar to you at first. @@ -654,7 +681,7 @@ If you want to change status bar, edit options.h and set `static char status' to your status bar binary (must be in $PATH). Alternatively, you can also set it in .Xresources (See .Xresources and Pywal). -.SS 6. Configuration and .Xresources +.SS 7. Configuration and .Xresources .PP speedwm has .Xresources support thanks to the .Xresources patch. It also has pywal support (tool which grabs colors based on your @@ -904,71 +931,71 @@ speedwm.col.windowbordersel: #eeeeee .IP \[bu] 2 speedwm.col.windowborderurg: #f0e68c .IP \[bu] 2 -speedwm.text.tag1.empty:  +speedwm.text.tag1.empty: \[uF8A5] .IP \[bu] 2 -speedwm.text.tag2.empty:  +speedwm.text.tag2.empty: \[uF8A8] .IP \[bu] 2 -speedwm.text.tag3.empty:  +speedwm.text.tag3.empty: \[uF8AB] .IP \[bu] 2 -speedwm.text.tag4.empty:  +speedwm.text.tag4.empty: \[uF8AE] .IP \[bu] 2 -speedwm.text.tag5.empty:  +speedwm.text.tag5.empty: \[uF8B1] .IP \[bu] 2 -speedwm.text.tag6.empty:  +speedwm.text.tag6.empty: \[uF8B4] .IP \[bu] 2 -speedwm.text.tag7.empty:  +speedwm.text.tag7.empty: \[uF8B7] .IP \[bu] 2 -speedwm.text.tag8.empty:  +speedwm.text.tag8.empty: \[uF8BA] .IP \[bu] 2 -speedwm.text.tag9.empty:  +speedwm.text.tag9.empty: \[uF8BD] .IP \[bu] 2 -speedwm.text.tag1.used:  +speedwm.text.tag1.used: \[uF8A3] .IP \[bu] 2 -speedwm.text.tag2.used:  +speedwm.text.tag2.used: \[uF8A6] .IP \[bu] 2 -speedwm.text.tag3.used:  +speedwm.text.tag3.used: \[uF8A9] .IP \[bu] 2 -speedwm.text.tag4.used:  +speedwm.text.tag4.used: \[uF8AC] .IP \[bu] 2 -speedwm.text.tag5.used:  +speedwm.text.tag5.used: \[uF8AF] .IP \[bu] 2 -speedwm.text.tag6.used:  +speedwm.text.tag6.used: \[uF8B2] .IP \[bu] 2 -speedwm.text.tag7.used:  +speedwm.text.tag7.used: \[uF8B5] .IP \[bu] 2 -speedwm.text.tag8.used:  +speedwm.text.tag8.used: \[uF8B8] .IP \[bu] 2 -speedwm.text.tag9.used:  +speedwm.text.tag9.used: \[uF8BB] .IP \[bu] 2 -speedwm.text.layout1:  +speedwm.text.layout1: \[uF330] .IP \[bu] 2 -speedwm.text.layout2:  +speedwm.text.layout2: \[uF331] .IP \[bu] 2 -speedwm.text.layout3:  +speedwm.text.layout3: \[uF332] .IP \[bu] 2 -speedwm.text.layout4:  +speedwm.text.layout4: \[uF333] .IP \[bu] 2 -speedwm.text.layout5:  +speedwm.text.layout5: \[uF334] .IP \[bu] 2 -speedwm.text.layout6:  +speedwm.text.layout6: \[uF335] .IP \[bu] 2 -speedwm.text.layout7:  +speedwm.text.layout7: \[uF336] .IP \[bu] 2 -speedwm.text.layout8:  +speedwm.text.layout8: \[uF337] .IP \[bu] 2 -speedwm.text.layout9:  +speedwm.text.layout9: \[uF338] .IP \[bu] 2 -speedwm.text.layout10:  +speedwm.text.layout10: \[uF339] .IP \[bu] 2 -speedwm.text.layout11:  +speedwm.text.layout11: \[uF33A] .IP \[bu] 2 -speedwm.text.layout12:  +speedwm.text.layout12: \[uF33B] .IP \[bu] 2 -speedwm.text.layout13:  +speedwm.text.layout13: \[uF33C] .IP \[bu] 2 -speedwm.text.layout14:  +speedwm.text.layout14: \[uF33D] .IP \[bu] 2 -speedwm.text.layout15:  +speedwm.text.layout15: \[uF33E] .IP \[bu] 2 speedwm.color.hiddentitle: 1 .IP \[bu] 2 @@ -1093,7 +1120,7 @@ speedwm.status.leftpadding: speedwm.status.rightpadding: .IP \[bu] 2 speedwm.status.separator: -.SS 7. Signals +.SS 8. Signals .PP Thanks to the `fsignal' patch available on suckless.org\[cq]s website, we can easily write shell scripts to interact with dwm and therefore @@ -1356,7 +1383,7 @@ Below is a list of all signums and what they do. 120 - Toggle border for the focused window .IP \[bu] 2 121 - Reset bar padding and gaps -.SS 8. Status bar +.SS 9. Status bar .PP speedwm has a status bar. It\[cq]s the (by default) right part of the bar. @@ -1405,7 +1432,7 @@ previously. Then simply start the status bar through autostart.h, \[ti]/.config/speedwm/autostart.sh, .xinitrc or some other means of running a program. -.SS 9. Additional note on autostart +.SS 10. Additional note on autostart .PP If you wish to add autostart entries without recompiling, consider using $HOME/.config/speedwm/autostart.sh. @@ -1416,11 +1443,11 @@ Make sure your user has permission to execute the script. Note that this script or any other commands in autostart.h will \f[B]not\f[R] run when speedwm is restarted, only when speedwm is first started. -.SS 10. Configuring the bar +.SS 11. Configuring the bar .PP As of 1.8, speedwm has a module system. -It is based on the barmodules patch for dwm and allows extensive control -over the way the speedwm bar functions. +It is based on the \f[V]barmodules\f[R] patch for dwm and allows +extensive control over the way the speedwm bar functions. This control has its own header, \f[V]bar.h\f[R]. .PP \f[V]bar.h\f[R] contains a somewhat detailed list of all possible @@ -1435,13 +1462,31 @@ Each module can be aligned to any part of the bar (See `Alignment' for possible values). If, let\[cq]s say multiple modules both align to the right next to the center split (middle), the first module takes priority. +.SS BarRule structure +.IP "1." 3 +Monitor Internally: \f[V]int monitor\f[R] +.IP "2." 3 +Bar Internally: \f[V]int bar\f[R] +.IP "3." 3 +Alignment Internally: \f[V]int alignment\f[R] +.IP "4." 3 +Width function Internally: +\f[V]int (*widthfunc)(Bar *bar, BarWidthArg *a)\f[R] +.IP "5." 3 +Draw function Internally: +\f[V]int (*drawfunc)(Bar *bar, BarDrawArg *a)\f[R] +.IP "6." 3 +Click function Intenrally: +\f[V]int (*clickfunc)(Bar *bar, BarClickArg *a)\f[R] +.IP "7." 3 +Name Internally: \f[V]char *name\f[R] .SS Module list .PP Below is a list of all modules bundled with speedwm. -The source code for these modules are all in bar/ and declared in -bar/items.c and bar/items.h. +The source code for these modules are all in \f[V]bar/\f[R] and declared +in \f[V]bar/items.c\f[R] and \f[V]bar/items.h\f[R]. If you want to add more, you can just declare them in the same way and -add them to the barrules array if you want to use them. +add them to the \f[V]barrules\f[R] array if you want to use them. .IP \[bu] 2 ltsymbol: Standard, basic layout icon. .IP \[bu] 2 @@ -1550,19 +1595,22 @@ With all that said, you should now be able to add a module. In case you weren\[cq]t able to follow along, here is an example of how you can add powerline tags on the focused monitor. .IP "1." 3 -\[ga]{ `A', +\f[V]{ \[aq]A\[aq],\f[R] .IP "2." 3 -0, +\f[V]0,\f[R] .IP "3." 3 -bar_align_left, +\f[V]bar_align_left,\f[R] .IP "4." 3 -width_tags_pwl, +\f[V]width_tags_pwl,\f[R] .IP "5." 3 -draw_tags_pwl, +\f[V]draw_tags_pwl,\f[R] .IP "6." 3 -click_tags_pwl, +\f[V]click_tags_pwl,\f[R] .IP "7." 3 -\[lq]my cool powerline tags\[rq] },\[ga] +\f[V]\[dq]my cool powerline tags\[dq] },\f[R] +.PP +Combined into one line: +\f[V]{ \[aq]A\[aq], 0, bar_align_left, width-tags_pwl, draw_tags_pwl, click_tags_pwl, \[dq]my cool powerline tags\[dq] },\f[R] .PP Let\[cq]s break down the above. .IP "1." 3 @@ -1583,10 +1631,258 @@ module. .IP "7." 3 A label for our module, it\[cq]s only useful for debugging. .PP -Feel free to copy the above to bar.h if you want to experiment with it. +Feel free to copy the above to \f[V]bar.h\f[R] if you want to experiment +with it. Remember that you can have put any module wherever you want. Nothing is stopping you from having your tags on the right. This is what makes bar rules so powerful. +.SS 12. Keybinds +.PP +Like the bar array mentioned previously, there is a \f[V]Key keys\f[R] +array in \f[V]keybinds.h\f[R] which contains all keybinds speedwm will +recognize. +While this isn\[cq]t the only way to add keybinds in speedwm, it does +not require any additional software to be installed. +.SS Key structure +.IP "1." 3 +Event Internally: \f[V]int type\f[R] +.IP "2." 3 +Modifier Internally: \f[V]unsigned int mod\f[R] +.IP "3." 3 +Chain key Internally: \f[V]KeySym chain\f[R] +.IP "4." 3 +Key Internally: \f[V]KeySym keysym\f[R] +.IP "5." 3 +Function Internally: \f[V]void (*func)(const Arg *)\f[R] +.IP "6." 3 +Function arguments Internally: \f[V]const Arg arg\f[R] +.SS Event +.PP +The event value allow you to specify when a keybind is executed. +Internally this is known as \f[V]int type\f[R] and it specifies when the +function is executed. +.IP \[bu] 2 +KeyPress: Activate immediately on key press. +.IP \[bu] 2 +KeyRelease: Activate immediately on key release. +.SS Modifier +.PP +There are a lot of different modifiers, this list is only going to list +the ones declared in speedwm. +You can, of course declare more if necessary although it should be noted +that doing so is out of the scope of this documentation. +We will be focusing on the defined modifiers which are defined in +\f[V]speedwm.c\f[R] like this: +.PP +\f[V]/* Modifiers */ #define CONTROL ControlMask #define SHIFT ShiftMask #define ALT Mod1Mask #define ALTR Mod3Mask #define SUPER Mod4Mask #define SUPERR Mod5Mask\f[R] +.PP +Below is a list of defined modifiers: +.IP \[bu] 2 +CONTROL Left Control (Ctrl) key. +.IP \[bu] 2 +SHIFT Left Shift key. +.IP \[bu] 2 +ALT Left Alt key. +.IP \[bu] 2 +SUPER Left Super (Windows) key. +.IP \[bu] 2 +SUPERR Right Super (Windows) key. +.PP +In keybinds.h, MODIFIER1 and MODIFIER2 are also defined. +MODIFIER1 is defined in order to make modifying keybinds easier. +MODIFIER1 is by default defined as SUPER or Mod4Mask. +For instance, if you want to use MODIFIER1 as your modifier, +\f[V]MODIFIER1\f[R] would be the right value here. +.PP +Do note that you can may use multiple modifiers. +Do this by adding two or more modifiers separated by a pipe +(MODIFIER1|SHIFT) +.SS Chain key +.PP +This value \f[I]is\f[R] mandatory, but it does not have to be used. +speedwm has supported chained keybinds since 0.4. +Chained keybinds allow more keybinds as like the name implies, the user +has to press multiple keys to activate it. +You can think of it as in Vim where there\[cq]s different modes. +.PP +The first key that needs to be pressed to activate a chain needs to be +the key specified here. +In order to see a list of possible keys, see +\f[V]/usr/include/X11/keysymdef.h\f[R]. +If, let\[cq]s say we want to use simply the letter \f[V]a\f[R] as the +key to start a chain, the value here would be \f[V]XK_a\f[R]. +.PP +If we want a normal key, one that is \f[B]not\f[R] chained, we can +accomplish that by simply setting the Chain key to \f[V]-1\f[R]. +You can see this in the \f[V]keypress()\f[R] function in +\f[V]speedwm.c\f[R]. +This line of code is responsible for this behavior. +.PP +\f[V]if (keysym == keys[i].keysym && keys[i].chain == -1\f[R] +.SS Key +.PP +The next value, similar to the Chain key also needs to be a keysym. +If the key is a chained key, this is the second key that needs to be +pressed. +If it isn\[cq]t a chained key, this is the key that needs to be pressed +while the Modifier is pressed. +.PP +In order to see a list of possible keys, see +\f[V]/usr/include/X11/keysymdef.h\f[R]. +Note that this path may differ depending on your operating system. +.PP +There are a lot more keys technically defined, see +\f[V]/usr/include/X11/XF86keysym.h\f[R] for a list of media keys. +.SS Function +.PP +Many functions expect \f[V]const Arg *arg\f[R] to be passed to them. +However this value does require any function argument to be specified +because it simply passes the next value to the function and calls it. +.PP +There is no list of functions, but \f[V]speedwm.c\f[R] has a lot of +declared functions which you may use in keybinds provided the function +expects \f[V]const Arg *arg\f[R]. +.SS Function arguments +.PP +This is the actual argument passed to the function we\[cq]re calling +when the keybind is activated. +Explaining this well would be fairly simple, but instead of doing so I +recommend you read the \f[V]typedef union Arg\f[R] in +\f[V]speedwm.c\f[R]. +It looks like this: +.PP +\f[V]typedef union { long i; unsigned long ui; float f; const void *v; } Arg;\f[R] +.PP +In short, Arg is a list of different types, which may be used to set +different things in the argument. +Passing a float (such as mfact) through would mean I should override +\f[V].f\f[R], passing an integer (such as barposition) through would +mean I should override \f[V].i\f[R]. +There\[cq]s also \f[V].v\f[R] for \f[V]void\f[R] and \f[V].ui\f[R] for +tags. +This is not used unless you want to mess with tag keybinds. +.PP +When you don\[cq]t care about the value given to the function, you may +simply enter a \f[V]0\f[R]. +.SS Example keybind +.PP +With all that said, you probably get the idea of how it works. +But you still don\[cq]t know how to put all this knowledge together. +.IP "1." 3 +\f[V]{ KeyPress,\f[R] +.IP "2." 3 +\f[V]MODIFIER1|SHIFT,\f[R] +.IP "3." 3 +\f[V]-1,\f[R] +.IP "4." 3 +\f[V]XK_w,\f[R] +.IP "5." 3 +\f[V]spawn,\f[R] +.IP "6." 3 +\f[V]cmd( \[dq]firefox\[dq] ) },\f[R] +.PP +Combined into one line: +\f[V]{ KeyPress, MODIFIER1|SHIFT, -1, XK_w, spawn, cmd( \[dq]firefox\[dq] ) },\f[R] +.PP +Let\[cq]s break down the above. +.IP "1." 3 +This is our type. +If it\[cq]s \f[V]KeyPress\f[R], it will be activated when the keybind is +pressed. +If it is \f[V]KeyRelease\f[R] it will be activated when the keybind is +released. +.IP "2." 3 +This is our modifier. +\f[V]MODIFIER1\f[R] is defined in \f[V]keybinds.h\f[R]. +We\[cq]re adding SHIFT to it, (defined in \f[V]speedwm.c\f[R]) which +means we have to press BOTH \f[V]MODIFIER1\f[R] and \f[V]SHIFT\f[R] at +the same time to activate this keybind. +.IP "3." 3 +This is our \f[B]chain\f[R] key. +\f[V]-1\f[R] here indicates that we do not want it to be chained. +We want a regular keybind. +See the example below for an example \f[I]with\f[R] a chained keybind +instead. +.IP "4." 3 +This is our regular key. +\f[V]XK_w\f[R] is defined in \f[V]/usr/include/X11/keysymdef.h\f[R] on +most operating systems and it means we have to press \f[V]w\f[R] on our +keyboard along with the modifier to activate this keybind. +.IP "5." 3 +This is our function. +We call this, passing the next value (\f[V]const Arg *arg\f[R]) to it. +.IP "6." 3 +This is our function argument. +Do note that in this case \f[V]cmd()\f[R] is a macro and it is defined +in \f[V]speedwm.c\f[R]. +This macro will pass the contents of the macro to a shell it will spawn. +.PP +Feel free to copy the above to \f[V]keybinds.h\f[R] if you want to +experiment with it. +.SS Example chained keybind +.IP "1." 3 +\f[V]{ KeyPress,\f[R] +.IP "2." 3 +\f[V]MODIFIER1|SHIFT,\f[R] +.IP "3." 3 +\f[V]XK_a,\f[R] +.IP "4." 3 +\f[V]XK_w,\f[R] +.IP "5." 3 +\f[V]togglebar,\f[R] +.IP "6." 3 +\f[V]{0} },\f[R] +.PP +Combined into one line: +\f[V]{ KeyPress, MODIFIER1|SHIFT, XK_a, XK_w, togglebar, {0} },\f[R] +.PP +Let\[cq]s break down the above. +.IP "1." 3 +This is our type. +If it\[cq]s \f[V]KeyPress\f[R], it will be activated when the keybind is +pressed. +If it is \f[V]KeyRelease\f[R] it will be activated when the keybind is +released. +.IP "2." 3 +This is our modifier. +\f[V]MODIFIER1\f[R] is defined in \f[V]keybinds.h\f[R]. +We\[cq]re adding SHIFT to it, (defined in \f[V]speedwm.c\f[R]) which +means we have to press BOTH \f[V]MODIFIER1\f[R] and \f[V]SHIFT\f[R] at +the same time to activate this keybind. +.IP "3." 3 +This is our \f[B]chain\f[R] key. +\f[V]XK_a\f[R] here is the key we have to press along with our modifier +to activate this keybind. +\f[V]XK_a\f[R] is defined in \f[V]/usr/include/X11/keysymdef.h\f[R] on +most operating systems. +.IP "4." 3 +This is our regular key. +\f[V]XK_w\f[R] is defined in \f[V]/usr/include/X11/keysymdef.h\f[R] on +most operating systems and it means we have to press \f[V]w\f[R] on our +keyboard to activate this keybind. +Note that we do \f[B]not\f[R] need to press the modifier here, because +it is a chained keybind. +.IP "5." 3 +This is our function. +We call this, passing the next value (\f[V]const Arg *arg\f[R]) to it. +.IP "6." 3 +This is our function argument. +We simply pass \f[V]0\f[R] here because we don\[cq]t need to pass +anything to the function, because the function does not care. +.PP +Feel free to copy the above to \f[V]keybinds.h\f[R] if you want to +experiment with it. +.PP +This should give you a brief idea of how keybinds work in speedwm. +Most of this carries over to \f[V]dwm\f[R] as well, although it does not +have some of this stuff. +It should be noted that as I mentioned previously, you don\[cq]t HAVE to +use this system. +You can use external programs to handle keybinds, and +\f[V]libspeedwm\f[R] to perform actions in speedwm. +sxkbd is one popular program for this purpose and window managers like +\f[V]bspwm\f[R] use it. +However such a solution is out of the scope of this documentation! .SS Credits .PP I far from wrote this entire project myself. @@ -1647,7 +1943,7 @@ Mihir Lad .IP \[bu] 2 MLquest8 .IP \[bu] 2 -Ondřej Grover +Ond\[u0159]ej Grover .IP \[bu] 2 ornx .IP \[bu] 2 @@ -1663,7 +1959,7 @@ Ryan Roden-Corrent .IP \[bu] 2 sipi .IP \[bu] 2 -Sönke Lambert +S\[:o]nke Lambert .IP \[bu] 2 speedie .IP \[bu] 2 @@ -1675,6 +1971,6 @@ suckless.org .IP \[bu] 2 Timmy Keller .IP \[bu] 2 -Viliam Kováč +Viliam Kov\['a]\[u010D] .PP See Codeberg contributions for more information.