From 1d5b87c3bad83efc7f683676a218790e5bc02311 Mon Sep 17 00:00:00 2001 From: speedie Date: Fri, 3 Feb 2023 16:40:18 +0100 Subject: [PATCH] add more pages --- icons/w2-icon.png | Bin 1744 -> 0 bytes index.php | 2 +- pages/Client rules.md | 66 +++++++++---- pages/Configuring the bar.md | 178 +++++++++++++++++++++++++++++++++++ pages/Keybinds.md | 167 ++++++++++++++++++++++++++++++++ pages/_sidebar.md | 11 ++- 6 files changed, 405 insertions(+), 19 deletions(-) delete mode 100755 icons/w2-icon.png create mode 100644 pages/Configuring the bar.md create mode 100644 pages/Keybinds.md diff --git a/icons/w2-icon.png b/icons/w2-icon.png deleted file mode 100755 index 9df16f66023bb0297701e1bb2ba8a55a50529a2e..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1744 zcmaJ?c~BEq9L@+-4Yyovn876!MJ3rJB!Q%W97#B8s0J`8f+fdB0wf!fMFNVAqPC!@ zK-8i*fYc&#RSTtv7iB1lAlE1(cogLn5yi#yV2z{ge^eAVJVU#R6!Vj2`qwu5V>$0#Dj#A)TA4b zHwwkeA_RzlyMZZ&w+EUawIK#R(7sh@fpUg%5tR;VK@GNqq2p8kfXX z210SN;4~E!o)#7%PD>CoB>45dfVYN;3dkWu2x#Pq3N=&XgP+r7qI<(JhzI5%NP-Xk zeNY1KMj#MYK>&?NB8W+J5P;n) zGI=b{2Vbb=gO5WHB@+ZwQc{R19zA&b*cgpY6uFo%e(>$Qj1kG zB_e|rfI(3xf|C&+JR0fy6y(YUS%vyTnb3lP8le&-6G?`Y=7C)9|3l^S1+*IBK_BD& zPhoXLsuBWukQz=_iP6SMT@0?2%s>?+L||0}3@6T4abp~e!0I?y2?U1I0IpChQyAcqi4?3O3p;Ad?GK&*HCUaPUEDkM@9Z2`5c+GQJ zusB%`DUf-tcmfb`?6-SFeoKqPK+=!t#&M^tDAbWH*RET1{zL%bVfhe ztn^AW=~C1cKE3|((mwVk+YNgwnoW!BEVeh?xBo(vHv_aMv8{c7r@f$`zcE3HAI^HP zCZ>05bxY9n&`vvNYKxu8z-qq|hW6Hoi?@?yx;&Fd_z7P){zB7+JMyFb5eNQsSJ~-5 zPn;`1QGV9Fn?Kvi_vKqMWB6V1yGI-f6DDTX256Gx!(n5Lq7HtSuaiqlkVcm?rt))+ z550oRZSCt$ip%8Hh;WfWo+npz`9%-n@{GS`kZXl75|X&d`tA1{rch7 zw%(}tFH6h4mOeE{hNBKwVXMZf^LXk=Rpe@|;?z6k&=&W+b-Sh2M{##LW{+JL$>iG6 z?G2UWZ;nPYX42eUk{U<29@I( zBzw4#WJ9=nJKpYo_KM7?CW>{IgX!~4)VtTF?^!2ZnL3d1bp@$iQK}eBeda8|{uOFt zRm?37kBG3EefJ0(lPY*?C2g2;(l4!7C7R+k*SwkidzZ<|;2d2a_N3*-7Qb|C=)H@^ z`f8`(oQq}$p2aRJyijR|owg~ubi%DW?wD-#)SBbk5pA%(tp0Si)V<96F>*3N6eh3T zx0zRQsWW#^=_K9pwq$f->uWn}1T@\n"; print " \n"; print " \n"; - print " \n"; + print " \n"; print " \n"; print " \n"; print " ".PAGE_TITLE."$title\n"; diff --git a/pages/Client rules.md b/pages/Client rules.md index 5aa4622..c5c08fd 100644 --- a/pages/Client rules.md +++ b/pages/Client rules.md @@ -5,71 +5,103 @@ The `Rule` array allows you to specify rules for X11 clients based on factors su To get this information, you can use the X11 utility `xprop` to get information about a client. If you want to see in detail how the rule system works, refer to function `applyrules` and the `Rule` struct in `speedwm.c`. -### Rule structure +### Rule structure (user-friendly) 1. Class -Internally: `const char *class` +Type: `const char *` 2. Instance -Internally: `const char *instance` +Type: `const char *` 3. Title -Internally: `const char *title` +Type: `const char *` 4. Tags -Internally: `unsigned int tags` +Type: `unsigned int` 5. isfloating -Internally: `int isfloating` +Type: `int` 6. ispermanent -Internally: `int ispermanent` +Type: `int` 7. isterminal -Internally: `int isterminal` +Type: `int` 8. noswallow -Internally: `int noswallow` +Type: `int` 9. Monitor -Internally: `int monitor` +Type: `int` 10. unmanaged -Internally: `int unmanaged` +Type: `int` 11. ignoretransient -Internally: `int ignoretransient` +Type: `int` 12. floatx -Internally: `int floatx` +Type: `int` 13. floaty -Internally: `int floaty` +Type: `int` 14. floatw -Internally: `int floatw` +Type: `int` 15. floath -Internally: `int floath` +Type: `int` 16. scratchkey -Internally: `const char scratchkey` +Type: `const char` + +### Rule structure (internally) + +`typedef struct {` + +`const char *class;` + +`const char *instance;` + +`const char *title;` + +`unsigned int tags;` + +`int isfloating;` + +`int ispermanent;` + +`int isterminal;` + +`int noswallow;` + +`int monitor;` + +`int unmanaged;` + +`int ignoretransient;` + +`int floatx, floaty, floatw, floath;` + +`const char scratchkey;` + +`} Rule;` ### Class diff --git a/pages/Configuring the bar.md b/pages/Configuring the bar.md new file mode 100644 index 0000000..b24d21b --- /dev/null +++ b/pages/Configuring the bar.md @@ -0,0 +1,178 @@ +Configuring the bar +=================== + +As of 1.8, speedwm has a module system. It is based on the [barmodules](https://github.com/bakkeby/patches/blob/master/dwm/dwm-barmodules-6.2.diff) 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 (user-friendly) + +1. Monitor + +Type: `int` + +2. Bar + +Type: `int` + +3. Alignment + +Type: `int` + +4. Width function + +Type: `int (*widthfunc)` + +5. Draw function + +Type: `int (*drawfunc)` + +6. Click function + +Type: `int (*clickfunc)` + +7. Value + +Type: `int` + +8. Name + +Type: `char *` + +### BarRule structure (internally) + +`typedef struct {` + +`int monitor;` + +`int bar;` + +`int alignment;` + +`int (*widthfunc)(Bar *bar, BarWidthArg *a);` + +`int (*drawfunc)(Bar *bar, BarDrawArg *a);` + +`int (*clickfunc)(Bar *bar, Arg *arg, BarClickArg *a);` + +`int val;` + +`char *name;` + +`int x, w;` + +`} BarRule;` + +### 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. + +- ltsymbol: Standard, basic layout icon. +- tags: Basic tags, without powerlines. +- tags_pwl: Tags with powerlines. +- systray: Basic X11 system tray. +- status_basic: Basic status bar. +- status_basic_es: Basic status bar. +- status: Clickable status bar with color support through status2d. +- status_es: Clickable status bar with color support through status2d (Extra status). +- status_pwl: Non-clickable status bar with powerlines. It supports colors by cycling through colorschemes. +- status_pwl_es: Non-clickable status bar with powerlines. It supports colors by cycling through colorschemes (Extra status). +- title: Title, shows all windows, including hidden windows. +- title_basic: Basic title, shows focused window. + +### Monitor + +The monitor value allows you to specify which monitor the module should be placed on. In addition to this, you can also choose to only draw the module on the focused monitor. + +-1: Show the module on all monitors. +0: Show on the main monitor (monitor 0). +1: Show on monitor #1 (This can be any monitor you want). + +### Bar + +This value allows you to specify which bar the module is placed on. speedwm supports two (0 and 1) bars. 0 is the main bar, which is by default placed at the top. 1 is the second bar which is only visible if modules actively use it. If the main bar is placed on the top, the second bar is placed on the bottom and vice versa. + +0: Place the module on the main bar +1: Place the module on the extra bar + +### Alignment + +This value allows you to specify an alignment for the module in question. As previously mentioned, the first module takes priority if multiple modules have the same alignment. +The 'center split' refers to the middle of the bar, and that's where any free space/remainder of the screen ends up for other modules to use if desired. + +- bar_align_left: Force the module to be placed on the left side of the bar if possible. +- bar_align_right: Force the module to be placed on the right side of the bar if possible. +- bar_align_center: Force the module to be placed in the center of the bar if possible. +- bar_align_left_left: Force the module to be placed on the left side of the bar next to the center split. +- bar_align_left_right: Force the module to be placed on the right side of the bar next to the center split. +- bar_align_left_center: Force the module to be placed on the center in the middle of the remaining space left of the center split on the left.. +- bar_align_right_left: Force the module to be placed on the left side of the bar next to the center split. +- bar_align_right_right: Force the module to be placed on the right side of the bar next to the center split. +- bar_align_right_center: Force the module to be placed on the center in the middle of the remaining space left of the center split on the right. +- bar_align_none: No specific alignment. This will give the module the remaining space. + +### Width + +'Width' refers to the function to call which returns the width of a module. The syntax below applies to all default modules. + +Syntax: width_ +Example: width_tags_pwl + +### Draw + +'Draw' refers to the function to call which draws the module on the bar. The syntax below applies to all default modules. + +Syntax: draw_ +Example: draw_tags_pwl + +### Click + +'Click' refers to the function to call which checks if you clicked on said module. The syntax below applies to all default modules. + +Syntax: click_ +Example: click_tags_pwl + +### Value + +**NOTE: Support for this was added in version 1.9 of speedwm, and speedwm 1.8 does not have it. Any modules using it will be incompatible with speedwm 1.8. I highly recommend upgrading to 1.9 for this (and many more) reason.** + +'Value' here is simply an integer (a number) which the different functions can access and read to (possibly) determine different functionality. Most modules don't use it, in fact speedwm 1.9 doesn't even come with any modules that use this, however in an effort to make writing modules easy, it is included in the base build. + +It should be noted that passing `0` here does not *disable* it, but sets it to `0`. For most modules, it doesn't matter what you pass but it is recommended that you simply pass `0`. + +Syntax: +Example: 12 + +### Module name + +The module name really doesn't mean anything at all, it is just useful for debugging. + +### Example module + +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. `0,` +8. `"my cool powerline tags" },` + +Combined into one line: `{ 'A', 0, bar_align_left, width-tags_pwl, draw_tags_pwl, click_tags_pwl, 0, "my cool powerline tags" },` + +Let's break down the above. + +1. 'A' here refers to the focused monitor, indicating that we want to place it on the focused monitor. +2. 0 here means we want to place it on the primary bar. +3. bar_align_left indicates we want to align it to the left part of the bar, you know, where tags usually are. +4. width_tags_pwl is the function we call to get the width. +5. draw_tags_pwl is the function we call to draw the bar. +6. click_tags_pwl is the function we call to check if we clicked on that module. +7. 0 here is the value we allow the function to access. The value doesn't matter for most modules but 0 is used here. +8. 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. diff --git a/pages/Keybinds.md b/pages/Keybinds.md new file mode 100644 index 0000000..9ac39c2 --- /dev/null +++ b/pages/Keybinds.md @@ -0,0 +1,167 @@ +Keybinds +======== + +Like the `BarRules` array mentioned, 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 (user-friendly) + +1. Event + +Type: `int` + +2. Modifier + +Type: `unsigned int` + +3. Chain key + +Type: `KeySym` + +4. Key + +Type: `KeySym` + +5. Function + +Type: `void (*func)` + +6. Function arguments + +Type: `const Arg` + +### Key structure (internally) + +`typedef struct {` + +`int type;` + +`unsigned int mod;` + +`KeySym chain;` + +`KeySym keysym;` + +`void (*func)(const Arg *);` + +`const Arg arg;` + +`} Key;` + +### 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/pages/_sidebar.md b/pages/_sidebar.md index cb263b0..402ee93 100755 --- a/pages/_sidebar.md +++ b/pages/_sidebar.md @@ -1,3 +1,12 @@ +Basics +====== + - [[Home]] +- [[Where do I go?]] +- [[Getting Started]] + +### Deeper + - [[Client rules]] -- [[Getting Started]] \ No newline at end of file +- [[Keybinds]] +- [[Configuring the bar]]