Styling 🎨¶
This page will attempt to explain in more detail how to use styling in quo.
Style strings¶
Many user interface controls, like Window
accept a style argument which can be used to pass the formatting as a
string. For instance, we can select a foreground color:
"fg:red""fg:blue""fg:#ffaa33"(hexadecimal notation)"fg:darkred"(named color)
Or a background color:
"bg:green""bg:#ffaa33"(hexadecimal notation)
Or we can add one of the following flags:
"bold""italic""underline"or"ul""blink""reverse"(reverse foreground and background on the terminal.)"hidden"
Or their negative variants:
"nobold""noitalic""nounderline""noblink""noreverse""nohidden"
All of these formatting options can be combined like so:
"fg:yellow bg:black bold underline"
The style string can be given to any user control directly, or to a
Container object from where it will propagate
to all its children. A style defined by a parent user control can be overridden
by any of its children. The parent can for instance say style="bold
underline" where a child overrides this style partly by specifying
style="nobold bg:ansired".
The following ANSI colors are available (both for foreground and background) when using Style
# Low intensity, dark. (One or two components 0x80, the other 0x00.)
ansiblack, ansired, ansigreen, ansiyellow, ansiblue
ansimagenta, 'ansicyan, ansigray
# High intensity, bright.
ansibrightblack, ansibrightred, ansibrightgreen, ansibrightyellow
ansibrightblue, ansibrightmagenta, ansibrightcyan, ansiwhite
In order to know which styles are actually used in an application using Console class, it is
possible to call get_used_style_strings(), when the
application is done.
Class names¶
Like we do for web design, it is not a good habit to specify all styling
inline. Instead, we can attach class names to UI controls and have a style
sheet that refers to these class names. The
Style can be passed as an argument to the Console.
from quo.layout import VSplit
from quo.layout import HSplit
from quo.layout import Window
from quo.layout import BufferControl
from quo.style import Style
layout = VSplit([
Window(BufferControl(...), style='class:left'),
HSplit([
Window(BufferControl(...), style='class:top'),
Window(BufferControl(...), style='class:bottom'),
], style='class:right')
])
style = Style([
('left', 'bg:red'),
('top', 'fg:green'),
('bottom', 'underline bold'),
])
It is possible to add multiple class names to an element. That way we’ll
combine the styling for these class names. Multiple classes can be passed by
using a comma separated list, or by using the class: prefix twice.
quo.layout.Window(quo.layout.BufferControl(...), style='class:left,bottom'),
quo.layout.Window(quo.layout.BufferControl(...), style='class:left class:bottom'),
It is possible to combine class names and inline styling. The order in which the class names and inline styling is specified determines the order of priority. In the following example for instance, we’ll take first the style of the “header” class, and then override that with a red background color.
Window(BufferControl(...), style='class:header bg:red'),
Dot notation in class names¶
The dot operator has a special meaning in a class name. If we write:
style="class:a.b.c", then this will actually expand to the following:
style="class:a class:a.b class:a.b.c".
This is mainly added for Pygments lexers, which specify “Tokens” like this, but it’s useful in other situations as well.
Multiple classes in a style sheet¶
A style sheet can be more complex as well. We can for instance specify two class names. The following will underline the left part within the header, or whatever has both the class “left” and the class “header” (the order doesn’t matter).
style = Style([
('header left', 'underline'),
])
If you have a dotted class, then it’s required to specify the whole path in the
style sheet (just typing c or b.c doesn’t work if the class is
a.b.c):
style = Style([
('a.b.c', 'underline'),
])
It is possible to combine this:
style = Style([
('header body left.text', 'underline'),
])
Evaluation order of rules in a style sheet¶
The style is determined as follows:
First, we concatenate all the style strings from the root control through all the parents to the child in one big string. (Things at the right take precedence anyway.)
E.g:
class:body bg:#aaaaaa #000000 class:header.focused class:left.text.highlighted underlineThen we go through this style from left to right, starting from the default style. Inline styling is applied directly.
If we come across a class name, then we generate all combinations of the class names that we collected so far (this one and all class names to the left), and for each combination which includes the new class name, we look for matching rules in our style sheet. All these rules are then applied (later rules have higher priority).
If we find a dotted class name, this will be expanded in the individual names (like
class:left class:left.text class:left.text.highlighted), and all these are applied like any class names.Then this final style is applied to this user interface element.
Using a dictionary as a style sheet¶
The order of the rules in a style sheet is meaningful, so typically, we use a
list of tuples to specify the style. But is also possible to use a dictionary
as a style sheet. This makes sense for Python 3.6, where dictionaries remember
their ordering. An OrderedDict works as well.
from quo.style import Style
style = Style.add({
'header body left.text': 'underline',
})
Loading a style from Pygments¶
Pygments has a slightly different notation for specifying styles, because it maps styling to Pygments “Tokens”. A Pygments style can however be loaded and used as follows:
from quo.style.pygments import style_from_pygments_cls
from pygments.styles import get_style_by_name
style = style_from_pygments_cls(get_style_by_name('monokai'))
Merging styles together¶
Multiple Style objects can be merged together as
follows:
from quo.style import merge_styles
style = merge_styles([
style1,
style2,
style3
])
Color depths¶
There are four different levels of color depths available:
1 bit |
Black and white |
|
|
4 bit |
ANSI colors |
|
|
8 bit |
256 colors |
|
|
24 bit |
True colors |
|
|
By default, 256 colors are used, because this is what most terminals support
these days. If the TERM enviroment variable is set to linux or
eterm-color, then only ANSI colors are used, because of these terminals. The 24
bit true color output needs to be enabled explicitely. When 4 bit color output
is chosen, all colors will be mapped to the closest ANSI color.
Setting the default color depth for any application can be done
by setting the QUO_COLOR_DEPTH environment variable. You could
for instance copy the following into your .bashrc or .zshrc file.
# export QUO_COLOR_DEPTH=one_bit
export QUO_COLOR_DEPTH=four_bit
# export QUO_COLOR_DEPTH=eight_bit
# export QUO_COLOR_DEPTH=twenty_four_bit
An application can also decide to set the color depth manually by passing a
ColorDepth value to the
Console object:
from quo.console import Console
from quo.color import ColorDepth
app = Console(color_depth=ColorDepth.ANSI_COLORS_ONLY,
# ...
)
Style transformations¶
Quo supports a way to apply certain transformations to the styles near the end of the rendering pipeline. This can be used for instance to change certain colors to improve the rendering in some terminals.
One useful example is the
AdjustBrightnessStyleTransformation class,
which takes min_brightness and max_brightness as arguments which by default
have 0.0 and 1.0 as values. In the following code snippet, we increase the
minimum brightness to improve rendering on terminals with a dark background.
from quo.console import Console
from quo.style import AdjustBrightnessStyleTransformation
app = Console(
style_transformation=AdjustBrightnessStyleTransformation(
min_brightness=0.5, # Increase the minimum brightness.
max_brightness=1.0,
)
# ...
)