diff --git a/README.md b/README.md index 04d3c90..d228e0c 100644 --- a/README.md +++ b/README.md @@ -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_ +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 + +### 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. @@ -743,13 +846,13 @@ I far from wrote this entire project myself. Below are people who made this proj - kleinbottle4 - Luigi Foscari - Luke Smith -- Marius Iacob +- Marius Iacob - Markus Teich - Mihir Lad - MLquest8 - Ondřej Grover - ornx -- Patrick Steinhardt +- Patrick Steinhardt - phi - prx - Rob King diff --git a/docs/doc-10 b/docs/doc-10 index 06e53c0..765274b 100644 --- a/docs/doc-10 +++ b/docs/doc-10 @@ -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_ +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 + +### 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. diff --git a/docs/doc-11 b/docs/doc-11 new file mode 100644 index 0000000..92397ed --- /dev/null +++ b/docs/doc-11 @@ -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. diff --git a/scripts/speedwm-help b/scripts/speedwm-help index 272f163..48d4c8e 100755 --- a/scripts/speedwm-help +++ b/scripts/speedwm-help @@ -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 diff --git a/speedwm.1 b/speedwm.1 index 030fa15..adaa0ae 100644 --- a/speedwm.1 +++ b/speedwm.1 @@ -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