Window Border Decorations

Warning

This feature is experimental.

The decorations may behave unexpectedly, have missing features and will probably crash at some point!

Feedback on any issues would be appreciated.

ConditionalBorder

class qtile_extras.layout.decorations.borders.ConditionalBorder(**config)

A decoration that allows finer control as to which border is applied to which window.

To configure the decoration, you need to provide two parameters:

• matches: a list of tuples of (Match rules, border style)

• fallback: border style to apply if no matches

Example:

from qtile_extras.layout.decorations import ConditionalBorder, GradientBorder

layouts = [
    layout.MonadTall(
        border_focus=ConditionalBorder(
            matches=[
                (Match(wm_class="vlc"), GradientBorder(colours=["e85e00", "e80000", "e85e00"])),
                (Match(wm_class="firefox"), "f0f")
            ],
            fallback="00f"),
        border_width=4
    ),
]

The above code will draw an orange/red gradient border when VLC is focused, a solid purple border when firefox is focused and a solid blue border when any other window is focused.

Matches can be provided as single rule or a list of rules. The advanced combination of rules (using &, |, ~) is also supported here.

key	default	description
fallback	'fff'	Border to be applied if no matches
matches	[]	List of tuples of match rules and applicable

CustomBorder

class qtile_extras.layout.decorations.borders.CustomBorder(**config)

Decoration to allow users to create custom borders.

To use this border, you need to define a function that takes four arguments:

• ctx: A cairocffi.Context object for the drawing operations

• border_width: the width of the border to be drawn

• width: the width of the area to be drawn

• height: the height of the area to be drawn

width and height are defined that the top left corner of the border is at (0, 0) in the context. The bottom right corner is (width, height).

For example:

from qtile_extras.layout.decorations import CustomBorder


def stripey_red_border(ctx, bw, w, h):
    ctx.set_source_rgb(1,0,0)
    for x in range(0, h, 10):
        ctx.new_path()
        ctx.move_to(0, x)
        ctx.line_to(w, x)
        ctx.set_line_width(4)
        ctx.stroke()


layouts = [
    layout.Max(
        margin=5,
        border_width=10,
        border_focus=CustomBorder(func=stripey_red_border)
    ),
]

Note

The decoration will not clip the drawing to the area within the specified border width. Therefore, if you draw outside this area and have defined multiple borders, this drawing may overlap those borders.

Red stripey border

Diagonal green border

key	default	description
func	None	Custom function to render border. See docstring for more.

GradientBorder

class qtile_extras.layout.decorations.borders.GradientBorder(**config)

Renders borders with a gradient.

colours defines the list of colours in the gradient.

The angle/direction of the gradient is set by the points parameter. This is a list of a two (x, y) tuples. The x and y values are relative to the window. A value of (0, 0) is the top left corner while (1, 1) represents the bottom right corner.

offsets is used to adjust the position of the colours within the gradient. Leaving this as None will space the colours evenly. The values need to be in ascending order and in the range of 0.0 (the very start of the gradient) and 1.0 (the end of the gradient). These represent positions on the imagninary line between the two points defined above.

When radial=True the points parameter has no impact. The gradient will be drawn from the center of the window to the corner of the window. offsets can still be used to adjust the spacing of the colours.

border_focus=GradientBorder(colours=[“00f”, “0ff”])

border_focus=GradientBorder(colours=[“f0f”, “00f”, “0ff”], points=[(0, 1), (1, 0)])

key	default	description
colours	['00ffff', '0000ff']	List of colours in the gradient
offsets	None	Offset locations (in range of 0.0-1.0) for gradient stops. None to use regular spacing.
points	[(0, 0), (0, 1)]	Points to size/angle the gradient. See docs for more.
radial	False	Use radial gradient

GradientFrame

class qtile_extras.layout.decorations.borders.GradientFrame(**config)

Renders a frame with a gradient. Each edge’s gradient is from the outside towards the centre.

border_focus=GradientFrame(colours=[“00f”, “0ff”])

key	default	description
colours	['00ffff', '0000ff']	List of colours in the gradient

RoundedCorners

class qtile_extras.layout.decorations.borders.RoundedCorners(**config)

A simple decoration to draw rounded corners.

Note

This border will not render well on x11 backends as it does not implement transparency. As a result, the border will display with black artefacts in the corners.

Rounded corners

key	default	description
colour	'00f'	Border colour

ScreenGradientBorder

class qtile_extras.layout.decorations.borders.ScreenGradientBorder(**config)

Renders a border with a gradient which is scaled to the screen, rather than the window. This means that a window’s border will change depending on where it is in the screen.

colours defines the list of colours in the gradient.

The angle/direction of the gradient is set by the points parameter. This is a list of a two (x, y) tuples. The x and y values are relative to the screen. A value of (0, 0) is the top left corner while (1, 1) represents the bottom right corner.

offsets is used to adjust the position of the colours within the gradient. Leaving this as None will space the colours evenly. The values need to be in ascending order and in the range of 0.0 (the very start of the gradient) and 1.0 (the end of the gradient). These represent positions on the imagninary line between the two points defined above.

When radial=True the points parameter has no impact. The gradient will be drawn from the center of the screen to the corner of the screen. offsets can still be used to adjust the spacing of the colours.

ScreenGradientBorder(colours=[“f00”, “0f0”, “00f”], points=[(0,0), (1,1)])

Gradient is applied to screen…

…no matter how many windows are open.

key	default	description
colours	['00ffff', '0000ff']	List of colours in the gradient
offsets	None	Offset locations (in range of 0.0-1.0) for gradient stops. None to use regular spacing.
points	[(0, 0), (0, 1)]	Points to size/angle the gradient. See docs for more.
radial	False	Use radial gradient

SolidEdge

class qtile_extras.layout.decorations.borders.SolidEdge(**config)

A decoration that renders a solid border. Colours can be specified for each edge.

SolidEdge(colours=[“00f”, “0ff”, “00f”, “0ff”])

key	default	description
colours	['00f', '00f', '00f', '00f']	List of colours for each edge of the window [N, E, S, W].

TestDecoration

class qtile_extras.layout.decorations.borders.TestDecoration(**config)

Changing border widths

ConditionalBorderWidth

class qtile_extras.layout.decorations.borders.ConditionalBorderWidth(**config)

A class that allows finer control as to which border width is applied to which window.

To configure the border width, you need to provide two parameters:

• matches: a list of tuples of (Match rules, border width)

• default: border width to apply if no matches

Matches are applied in order and will return a border width as soon as a rule matches.

It can be used in place of the integer border width layout when defining layouts in your config. For example:

from qtile_extras.layout.decorations import ConditionalBorderWidth

layouts = [
    layout.Columns(
        border_focus_stack=["#d75f5f", "#8f3d3d"],
        border_width=ConditionalBorderWidth(
            default=2,
            matches=[(Match(wm_class="vlc"), 0)])
    ),
    ...
]

The above code will default to a border width of 2 but will apply a border width of zero for VLC windows.

key	default	description
default	0	Default border width value if no rule is matched
matches	[]	List of rules to apply border widths. See docs for more details.