status2d - bakkeby/dusk GitHub Wiki

Status2d is a form of markup language that allows for text colours to be specified as well as simple rectangle drawing.

As the name suggests this is primarily intended for status text, but can be used for other things as well such as the indicators, layout symbols and workspace icons.

Annotations Description
^rx,y,w,h^ Draw a rectangle of width w and height h, with its top left corner at (x,y) relative to the X drawing cursor. Note special values below.
^c#FF0000^ Set foreground colour
^b#55CDFC^ Set background colour, only applies to text
^f<px>^ Move the X drawing cursor forward by <px> pixels. Note that you have to move the cursor forward enough to display your drawing (by the width of your drawing) as otherwise it may be overwritten by text.
^fp^ Move the X drawing cursor forward by left padding (lpad) amount of pixels
^i<filepath>^ Draw an image in the bar by specifying the path to a file (will be cached)
^I<filepath>^ Draw an image in the bar by specifying the path to a file (cache buster)
^d^ Reset colours back to default
^C<num>^ Set foreground colour to terminal colour 0-15
^B<num>^ Set background colour to terminal colour 0-15
^S<num>^ Set a specific colour scheme via index
^w^ Swaps the current foreground/background colours. Useful when drawing multiple rectangles on top of one another.
^v^ Saves the current colour scheme so it can be restored later with the ^t^ tag. This way a script can modify colours in the middle of the bar agnostic to what colour was set previously.
^t^ Restores the last colour scheme saved by the ^v^ tag
^.^ Toggles whether or not to fill the background with colour when drawing text

Drawing rectangles

When drawing rectangles the characters of "w" and "h" can be used in place of numbers to indicate upper boundaries. This can be useful for when the size is not known up front.

  • if the x value is "w" then it means start drawing at the far right of the available space
  • similarly if the y value is "h" then start drawing at the bottom of the available space
  • if the w value is "w" then the width is the maximum available space and
  • if the h value is "h" then the height is the maximum available space

When drawing rectangles negative values can be used to start drawing from the opposite side or to specify a value less than the maximum.

  • if the x value is -3 then the drawing will start at 3 pixels left of the right hand side of the available space
  • if the y value is -3 then the drawing will start at 3 pixels above the bottom of the available space
  • if the w value is -6 then the width will be 6 pixels less than the available space and
  • if the h value is -6 then the height will be 6 pixels less than the available space

Examples

Example for drawing a battery icon:

  • draw the nose: "^r00,07,02,04^"
  • draw the battery: "^r02,04,22,10^"
  • fill it so that the border stays: "^c#000000^^r03,05,20,08^"
  • fill it with the remaining capacity: "^c#FFFFFF^^r10,05,13,08^"
  • reset the colour scheme: "^d^"
  • forward the cursor: "^f24^"

Put it all together:

  • "^r0,7,2,4^^r2,4,22,10^^c#000000^^r3,5,20,8^^c#FFFFFF^^r10,5,13,8^^d^^f24^"

This can then be set to status number 7.

$ duskc run_command setstatus 7 "^r0,7,2,4^^r2,4,22,10^^c#000000^^r3,5,20,8^^c#FFFFFF^^r10,5,13,8^^d^^f24^"

Here is a basic example setting different colours:

$ duskc run_command setstatus 9 "[status2d] ^c#FF0000^red text with blue rectangle^c#55CDFC^^r3,3,14,14^^f20^^c#FFFFFF^^b#F7A8B8^ and white text on pink background"

Including images in the status

Images can be included in the status (and other places where status2d markup is supported) by using the i markup followed by the file path to an image.

For example:

  • "^i~/Pictures/sm.png^"
  • "^I/home/username/Pictures/cat.png^"

For status updates ~/ will expand to the HOME environment variable, but in other places where status2d markup is used the full path to image files should be used.

Example where images are included in a status: status2d_img.png

The main restrictions that applies are:

  • file paths should not exceed 255 characters

Images that are loaded are scaled and cached for performance reasons.

The capital I markup can be used as a cache buster in that it will force the image to be read from file again rather than retrieving the image from cache.

Technically what is happening internally when this option is used is that:

  • the previous image will still be looked up from the cache based on the file path
  • if found then the previous image will be freed
  • the (new) image will be read from file
  • that image will be cached
  • the I markup in the status string will be changed to a normal i to avoid repeatedly reading the image from file every time the bar is drawn (e.g. on focus change)

This can be used for status images that dynamically change over time. The use of a ramdisk in this situation can help avoid wear and tear on SSDs or hard drives if you are considering having a status with dynamically generated images.

Unfortunately due to a limitation in Imlib the image file path has to lead to an actual file - it can not be a pipe.

Tip: you can use farbfeld images for status updates (it doesn't have to be a .png file).

With the farbfeld utilities most programs read an image from standard in and writes the output to standard out, which means that different tools can be chained together using pipes to produce the desired output. If you need graphics that are dynamically generated then farbfeld may be something to consider.

Refer to custom 2d indicators configuration and the Bar Indicators page for more practical examples.

Back to Functions > Bar > Status Module.

Concepts | Configuration | Features | Flags | Functionality | Functions

⚠️ **GitHub.com Fallback** ⚠️