Write documentation for how to add and modify bar modules

This commit is contained in:
speedie 2023-01-24 22:07:39 +01:00
parent 4288f142ce
commit e397d0ca81
5 changed files with 429 additions and 49 deletions

103
README.md
View file

@ -717,6 +717,109 @@ If you wish to add autostart entries without recompiling, consider using $HOME/.
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.
## 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`.
`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.
### 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: Clickable status bar with color support through status2d.
- status_pwl: Non-clickable status bar with powerlines. It supports colors by cycling through colorschemes.
- 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_<module>
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_<module>
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_<module>
Example: click_tags_pwl
### 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. "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. 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.
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.
## 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.

View file

@ -1,47 +1,103 @@
## Credits
## Configuring the bar
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.
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`.
- Adam Yuan
- Alex Cole
- Anukul Adhikari
- Ayoub Khater
- bakkeby
- bit6tream
- cd
- Chris Down
- Chris Noxz
- Daniel Bylinka
- Dhaval Patel
- Eon S. Jeon
- explosion-mental
- Fabian Blatz
- Finn Rayment
- Georgios Oxinos
- Ivan J.
- Jan Christoph Ebersbach
- Jared
- kleinbottle4
- Luigi Foscari
- Luke Smith
- Marius Iacob
- Markus Teich
- Mihir Lad
- MLquest8
- Ondřej Grover
- ornx
- Patrick Steinhardt
- phi
- prx
- Rob King
- Ryan Roden-Corrent
- sipi
- Sönke Lambert
- speedie
- Stefan Mark
- Stefan Matz
- suckless.org
- Timmy Keller
- Viliam Kováč
`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.
### 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: Clickable status bar with color support through status2d.
- status_pwl: Non-clickable status bar with powerlines. It supports colors by cycling through colorschemes.
- 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_<module>
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_<module>
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_<module>
Example: click_tags_pwl
### 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. "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. 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.
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.
See Codeberg contributions for more information.

47
docs/doc-11 Normal file
View file

@ -0,0 +1,47 @@
## 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.
- Adam Yuan
- Alex Cole
- Anukul Adhikari
- Ayoub Khater
- bakkeby
- bit6tream
- cd
- Chris Down
- Chris Noxz
- Daniel Bylinka
- Dhaval Patel
- Eon S. Jeon
- explosion-mental
- Fabian Blatz
- Finn Rayment
- Georgios Oxinos
- Ivan J.
- Jan Christoph Ebersbach
- Jared
- kleinbottle4
- Luigi Foscari
- Luke Smith
- Marius Iacob
- Markus Teich
- Mihir Lad
- MLquest8
- Ondřej Grover
- ornx
- Patrick Steinhardt
- phi
- prx
- Rob King
- Ryan Roden-Corrent
- sipi
- Sönke Lambert
- speedie
- Stefan Mark
- Stefan Matz
- suckless.org
- Timmy Keller
- Viliam Kováč
See Codeberg contributions for more information.

View file

@ -30,7 +30,8 @@ HELP() {
printf "%s-8 Layouts\n"
printf "%s-9 Important details.\n"
printf "%s-10 Additional note on autostart.\n"
printf "%s-11 Credits.\n"
printf "%s-11 Configuring the bar.\n"
printf "%s-12 Credits.\n"
printf "%sNo arguments View this list of arguments.\n"
printf "\n"
printf "%s--generate-markdown Write documentation (Markdown)\n"
@ -99,7 +100,8 @@ cat "${DOCDIR}/${PREFIX}doc-01" \
"${DOCDIR}/${PREFIX}example.signal" \
"${DOCDIR}/${PREFIX}doc-08" \
"${DOCDIR}/${PREFIX}doc-09" \
"${DOCDIR}/${PREFIX}doc-10" | \
"${DOCDIR}/${PREFIX}doc-10" \
"${DOCDIR}/${PREFIX}doc-11" | \
grep -v "!!" > "/tmp/${PREFIX}doc"
# check arguments and perform actions based on it
@ -122,6 +124,7 @@ case "$1" in
"-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}doc-11" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;;
"-a") cat "/tmp/${PREFIX}doc" > /tmp/stdout ; $VIEWER /tmp/stdout ; exit 0 ;;
esac

173
speedwm.1
View file

@ -1421,7 +1421,178 @@ 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.
## Credits
## 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.
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
options here, but more importantly it contains a \f[V]barrules\f[R]
array.
This array similar to the \f[V]rules\f[R] 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?
.PP
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 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.
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.
.IP \[bu] 2
ltsymbol: Standard, basic layout icon.
.IP \[bu] 2
tags: Basic tags, without powerlines.
.IP \[bu] 2
tags_pwl: Tags with powerlines.
.IP \[bu] 2
systray: Basic X11 system tray.
.IP \[bu] 2
status_basic: Basic status bar.
.IP \[bu] 2
status: Clickable status bar with color support through status2d.
.IP \[bu] 2
status_pwl: Non-clickable status bar with powerlines.
It supports colors by cycling through colorschemes.
.IP \[bu] 2
title: Title, shows all windows, including hidden windows.
.IP \[bu] 2
title_basic: Basic title, shows focused window.
.SS Monitor
.PP
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.
.PP
-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).
.SS Bar
.PP
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.
.PP
0: Place the module on the main bar 1: Place the module on the extra bar
.SS Alignment
.PP
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\[cq]s where
any free space/remainder of the screen ends up for other modules to use
if desired.
.IP \[bu] 2
bar_align_left: Force the module to be placed on the left side of the
bar if possible.
.IP \[bu] 2
bar_align_right: Force the module to be placed on the right side of the
bar if possible.
.IP \[bu] 2
bar_align_center: Force the module to be placed in the center of the bar
if possible.
.IP \[bu] 2
bar_align_left_left: Force the module to be placed on the left side of
the bar next to the center split.
.IP \[bu] 2
bar_align_left_right: Force the module to be placed on the right side of
the bar next to the center split.
.IP \[bu] 2
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..
.IP \[bu] 2
bar_align_right_left: Force the module to be placed on the left side of
the bar next to the center split.
.IP \[bu] 2
bar_align_right_right: Force the module to be placed on the right side
of the bar next to the center split.
.IP \[bu] 2
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.
.IP \[bu] 2
bar_align_none: No specific alignment.
This will give the module the remaining space.
.SS Width
.PP
`Width' refers to the function to call which returns the width of a
module.
The syntax below applies to all default modules.
.PP
Syntax: width_ Example: width_tags_pwl
.SS Draw
.PP
`Draw' refers to the function to call which draws the module on the bar.
The syntax below applies to all default modules.
.PP
Syntax: draw_ Example: draw_tags_pwl
.SS Click
.PP
`Click' refers to the function to call which checks if you clicked on
said module.
The syntax below applies to all default modules.
.PP
Syntax: click_ Example: click_tags_pwl
.SS Module name
.PP
The module name really doesn\[cq]t mean anything at all, it is just
useful for debugging.
.SS Example module
.PP
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',
.IP "2." 3
0,
.IP "3." 3
bar_align_left,
.IP "4." 3
width_tags_pwl,
.IP "5." 3
draw_tags_pwl,
.IP "6." 3
click_tags_pwl,
.IP "7." 3
\[lq]my cool powerline tags\[rq] },\[ga]
.PP
Let\[cq]s break down the above.
.IP "1." 3
`A' here refers to the focused monitor, indicating that we want to place
it on the focused monitor.
.IP "2." 3
0 here means we want to place it on the primary bar.
.IP "3." 3
bar_align_left indicates we want to align it to the left part of the
bar, you know, where tags usually are.
.IP "4." 3
width_tags_pwl is the function we call to get the width.
.IP "5." 3
draw_tags_pwl is the function we call to draw the bar.
.IP "6." 3
click_tags_pwl is the function we call to check if we clicked on that
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.
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 Credits
.PP
I far from wrote this entire project myself.
Below are people who made this project what it is through submitting