Goal: Show the Herbstclient Tag.

Focusing in "herbstclient tag_status". 

HerbstluftWM: Tag Status

This tutorial cover Lemonbar, and in order to use Dzen2, any reader could use the source code in github.


Before you jump off to scripting, you might desire to read this overview.

All The Source Code:

Impatient coder like me, like to open many tab on browser.

HerbstluftWM Tag Status in Many Languages

This article is one part of a collection. All integrated, on related to another. So we can compare each other quickly.

Tutorial/ Guidance/ Article: [ Tag Status Overview ] [ BASH ] [ Perl ] [ Python ] [ Ruby ] [ PHP ] [ Lua ] [ Haskell ]

Dzen2 Source Code Directory: [ BASH ] [ Perl ] [ Python ] [ Ruby ] [ PHP ] [ Lua ] [ Haskell ]

Lemonbar Source Code Directory: [ BASH ] [ Perl ] [ Python ] [ Ruby ] [ PHP ] [ Lua ] [ Haskell ]


Since window manager is out of topic in this tutorial, I present only panel HerbstluftWM screenshot.


Statusbar: Dzen2 Screenshot


Statusbar: Lemonbar Screenshot

Directory Structure

Directory Structure has been explained in preface. For both Dzen2 and Lemonbar, the structure are the same. This figure will explain how it looks in PHP script directory.

Statusbar: Directory Structure

Special customization can be done in output script, without changing the whole stuff.

Get Geometry

Let’s have a look at helper.php in github.

View Source File:

Similar Code (Dzen2): [ BASH Helper ] [ Perl Helper ] [ Python Helper ] [ Ruby Helper ] [ PHP Helper ] [ Lua Helper ] [ Haskell Helper ]

Similar Code (Lemonbar): [ BASH Helper ] [ Perl Helper ] [ Python Helper ] [ Ruby Helper ] [ PHP Helper ] [ Lua Helper ] [ Haskell Helper ]

Get Script Argument

The original herbstluftwm panel example, contain statusbar for each monitor. The default is using monitor 0, although you can use other monitor as well.

$ ./panel.php 0

I do not implement statusbar in multi monitor since I only have my notebook. But I’ll pass the argument anyway for learning purpose. Here it is our code in PHP.


function get_monitor($arguments)
    // ternary operator
    return count($arguments) > 0 ? (int)$arguments[0] : 0;

And in main code we can call


$monitor = get_monitor($argv);
echo $monitor;

This will display 0 or else such as 1, depend on the script argument given.


Get Monitor Geometry

HerbstluftWM give this little tools to manage monitor geometry by getting monitor rectangle.

$ herbstclient monitor_rect

This will show something similar to this.

0 0 1280 800

HerbstluftWM: Monitor Rectangle

Consider wrap the code into function. And get an array as function return.


function get_geometry($monitor)
    $raw = shell_exec('herbstclient monitor_rect '.$monitor);

    if (empty($raw)) {
        print('Invalid monitor '.$monitors);
    return explode(' ', trim($raw));

Consider call this function from script later. To print array in PHP, we just have to wrap it in implode(' ', $geometry).

$monitor  = get_monitor($argv);
$geometry = get_geometry($monitor);
echo implode(' ', $geometry)."\n";

This will produce

0 0 1280 800

Get Panel Geometry

The Panel geometry is completely depend on the user flavor and taste. You can put it, on top, or bottom, or hanging somewhere. You can create gap on both left and right.

Consider this example: helper.php

function get_bottom_panel_geometry($height, $geometry)
    // geometry has the format X Y W H
    return array(
        $geometry[0] + 24, ($geometry[3] - $height), 
        $geometry[2] - 48, $height);

We are going to use this X Y W H, to get lemonbar parameter.

$panel_height = 24;
$monitor  = get_monitor($argv);
$geometry = get_geometry($monitor);
list($xpos, $ypos, $width, $height) = get_bottom_panel_geometry(
    $panel_height, $geometry);

echo "Lemonbar geometry: ${width}x${height}+${xpos}+${ypos}\n"

This will show something similar to this result, depend on your monitor size.

Lemonbar geometry: 1280x24+24+776

Get Lemonbar Parameters

We almost done. This is the last step. We wrap it all inside this function below.


function get_lemon_parameters($monitor, $panel_height)
    # calculate geometry
    $geometry = get_geometry($monitor);
    list($xpos, $ypos, $width, $height) = get_top_panel_geometry(
        $panel_height, $geometry);

    # geometry: -g widthxheight+x+y
    $geom_res = "${width}x${height}+${xpos}+${ypos}";
    # color, with transparency    
    $bgcolor = "'#aa000000'";
    $fgcolor = "'#ffffff'";

    # XFT: require lemonbar_xft_git 
    $font_takaop  = "takaopgothic-9";
    $font_bottom  = "monospace-9";
    $font_symbol  = "PowerlineSymbols-11";
    $font_awesome = "FontAwesome-9";

    # finally  
    $parameters  =  "  -g $geom_res -u 2"
                 . " -B $bgcolor -F $fgcolor"
                 . " -f $font_takaop -f $font_awesome -f $font_symbol"; 

    return $parameters;

Testing The Parameters

Consider this code 01-testparams.php. The script call the above function to get lemon parameters.

<?php # using PHP7


# initialize
$panel_height = 24;
$monitor = get_monitor($argv);

$lemon_parameters = get_lemon_parameters($monitor, $panel_height);
echo $lemon_parameters."\n";

This will produce output something similar to this result

-g 1280x24+0+0 -u 2 -B '#aa000000' -F '#ffffff' 
-f takaopgothic-9 -f FontAwesome-9 -f PowerlineSymbols-11

Or in Dzen2 version:

-x 0 -y 0 -w 1280 -h 24 -ta l 
-bg '#000000' -fg '#ffffff' -title-name dzentop 
-fn '-*-takaopgothic-medium-*-*-*-12-*-*-*-*-*-*-*'

View Source File:

Adjusting the Desktop

Since we want to use panel, we have to adjust the desktop gap, giving space at the top and bottom.

$ herbstclient pad 0 24 0 24 0

For more information, do $ man herbsluftclient, and type \pad to search what it means.

In script, it looks like this below.

system("herbstclient pad $monitor $panel_height 0 $panel_height 0");

Color Schemes

Using a simple data structure key-value pairs, we have access to google material color for use with dzen2 or lemonbar. Having a nice pallete to work with, makes our panel more fun.


$color = array(
    'white' => '#ffffff',
    'black' => '#000000',

    'grey50'  => '#fafafa',
    'grey100' => '#f5f5f5',

View Source File:

Similar Code (Dzen2): [ BASH Color ] [ Perl Color ] [ Python Color ] [ Ruby Color ] [ PHP Color ] [ Lua Color ] [ Haskell Color ]

Similar Code (Lemon): [ BASH Color ] [ Perl Color ] [ Python Color ] [ Ruby Color ] [ PHP Color ] [ Lua Color ] [ Haskell Color ]

Preparing Output

Let’s have a look at output.php in github.

View Source File:

Similar Code (Dzen2): [ BASH Output ] [ Perl Output ] [ Python Output ] [ Ruby Output ] [ PHP Output ] [ Lua Output ] [ Haskell Output ]

Similar Code (Lemonbar): [ BASH Output ] [ Perl Output ] [ Python Output ] [ Ruby Output ] [ PHP Output ] [ Lua Output ] [ Haskell Output ]

Global Variable and Constant

Constant in PHP begin with the word const.

Mutable State: Segment Variable

The different between interval based and event based is that, with interval based all panel segment are recalculated, while with event based only recalculate the trigerred segment.

In this case, we only have two segment in panel.

  • Tag

  • Title

output.php In script, we initialize the variable as below

$segment_windowtitle = ''; # empty string
$tags_status = [];         # empty array

Each segment buffered. And will be called while rendering the panel.

Global Constant: Tag Name

Assuming that herbstclient tag status only consist of nine number element.

$ herbstclient tag_status
	#1	:2	:3	:4	:5	.6	.7	.8	.9	

We can manage custom tag names, consist of nine string element. We can also freely using unicode string instead of plain one.


const TAG_SHOWS = ['一 ichi', '二 ni', '三 san', '四 shi', 
  '五 go', '六 roku', '七 shichi', '八 hachi', '九 kyū', '十 jū'];

Global Constant: Decoration

output.php Decoration consist lemonbar formatting tag.


// decoration
const SEPARATOR = "%{B-}%{F".COLOR['yellow500']."}|%{B-}%{F-}";

// Powerline Symbol
const RIGHT_HARD_ARROW = "";
const RIGHT_SOFT_ARROW = "";
const LEFT_HARD_ARROW  = "";
const LEFT_SOFT_ARROW  = "";

// theme
const PRE_ICON    = "%{F".COLOR['yellow500']."}";
const POST_ICON   = "%{F-}";

Segment Variable

As response to herbstclient event idle, these two function set the state of segment variable.


function set_tag_value($monitor)
    global $tags_status;

    $raw = shell_exec("herbstclient tag_status $monitor");
    $tags_status = explode("\t", trim($raw));

This function above turn the tag status string into array of tags for later use.


function set_windowtitle($windowtitle)
    global $segment_windowtitle;

    $icon = PRE_ICON."".POST_ICON;
    $windowtitle = trim($windowtitle);
    $segment_windowtitle = " ${icon} %{B-}"
        . "%{F".COLOR['grey700']."} ${windowtitle}";

We will call these two functions later.

Decorating: Window Title

This is self explanatory. I put separator, just in case you want to add other segment. And then returning string as result.


function output_by_title()
    global $segment_windowtitle;    
    $text  = "$segment_windowtitle ".SEPARATOR."  ";
    return $text;

Decorating: Tag Status

This transform each plain tag such as .2, to decorated tag names such as 二 ni. Note that it only process one tag. We process all tags in a loop in other function.

This has some parts:

  • Pre Text: Color setting for Main Text (Background, Foreground, Underline). Arrow before the text, only for active tag.

  • Main Text: Tag Name by number, each with their tag state #, +, ., |, !, and each tag has clickable area setting.

  • Post Text: Arrow after the text, only for active tag.

  • Color Reset: %{B-}, %{F-}, %{-u} (Background, Foreground, Underline).


function output_by_tag($monitor, $tag_status)
    $tag_index  = substr($tag_status, 1, 1);
    $tag_mark   = substr($tag_status, 0, 1);
    $tag_name   = TAG_SHOWS[(int)$tag_index - 1]; # zero based

    # ----- pre tag

    switch ($tag_mark) {
    case "#":
        $text_pre = "%{B".COLOR['blue500']."}%{F".COLOR['black']."}"
                  . "%{U".COLOR['white']."}%{+u}".RIGHT_HARD_ARROW
                  . "%{B".COLOR['blue500']."}%{F".COLOR['white']."}"
                  . "%{U".COLOR['white']."}%{+u}";
    case "+":
        $text_pre = "%{B".COLOR['yellow500']."}%{F".COLOR['grey400']."}";
    case ":":
        $text_pre = $text_pre = "%{B-}%{F".COLOR['white']."}"
                  . "%{U".COLOR['red500']."}%{+u}";
    case "!":
        $text_pre = "%{B".COLOR['red500']."}%{F".COLOR['white']."}"
                  . "%{U".COLOR['white']."}%{+u}";
        $text_pre = "%{B-}%{F".COLOR['grey600']."}%{-u}";

    # ----- tag by number
    // clickable tags
    $text_name = "%{A:herbstclient focus_monitor \"${monitor}\" && " 
               . "herbstclient use \"${tag_index}\":} ${tag_name} %{A}";
    # non clickable tags
    #$text_name = " $tag_name ";

    # ----- post tag

    if ($tag_mark == '#')
        $text_post = "%{B-}%{F".COLOR['blue500']."}"
                   . "%{U".COLOR['red500']."}%{+u}"
                   . RIGHT_HARD_ARROW;
        $text_post = "";

    $text_clear = '%{B-}%{F-}%{-u}';
    return $text_pre . $text_name . $text_post . $text_clear;

Combine The Segments

Now it is time to combine all segments to compose one panel. Lemonbar using %{l} to align left segment, and %{r} to align right segment. All tags processed in a loop.


function get_statusbar_text($monitor)
    global $tags_status;
    $text = '';
    // draw tags
    $text .= '%{l}';
    foreach ($tags_status as $tag_status) {
        $text .= output_by_tag($monitor, $tag_status);
    // draw window title
    $text .= '%{r}';
    $text .= output_by_title();

    return $text;

Testing The Output

Consider this code 02-testoutput.php. The script is using pipe as feed to lemonbar.

We append -p parameter to make the panel persistent.

<?php # using PHP7


# process handler
function test_lemon($monitor, $parameters) 
    $command_out  = "lemonbar $parameters -p";
    $pipe_out = popen($command_out, 'w');

    // initialize statusbar
    $text = get_statusbar_text($monitor);
    fwrite($pipe_out, $text."\n");


# initialize
$panel_height = 24;
$monitor = get_monitor($argv);
$lemon_parameters = get_lemon_parameters($monitor, $panel_height);

# test
system("herbstclient pad $monitor $panel_height 0 $panel_height 0");
test_lemon($monitor, $lemon_parameters);

This will produce a panel on top.

Statusbar: Lemonbar Screenshot

The panel only contain the initialized version of the text. It does not really interact with the HerbstluftWM event.

You can also click the clickable area to see it’s result. It only show text, not executed yet.

herbstclient focus_monitor "0" && herbstclient use "2"
herbstclient focus_monitor "0" && herbstclient use "3"

View Source File:

Coming up Next

It is already a long tutorial. It is time to take a break for a while.

We are going to continue on next tutorial to cover interaction between the script process and HerbstluftWM idle event.

Enjoy the statusbar !