summaryrefslogtreecommitdiffstats
path: root/docs/pages/advanced_topics/styling.rst
blob: 11695470cb19df24ec5ec40bf164f8875256361c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
.. _styling:

More about styling
==================

This page will attempt to explain in more detail how to use styling in
prompt_toolkit.

To some extent, it is very similar to how `Pygments <http://pygments.org/>`_
styling works.


Style strings
-------------

Many user interface controls, like :class:`~prompt_toolkit.layout.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:ansired"``  (ANSI color palette)
- ``"fg:ansiblue"`` (ANSI color palette)
- ``"fg:#ffaa33"``  (hexadecimal notation)
- ``"fg:darkred"``  (named color)

Or a background color:

- ``"bg:ansired"``  (ANSI color palette)
- ``"bg:#ffaa33"``  (hexadecimal notation)

Or we can add one of the following flags:

- ``"bold"``
- ``"italic"``
- ``"underline"``
- ``"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 as well:

- ``"fg:ansiyellow bg:black bold underline"``

The style string can be given to any user control directly, or to a
:class:`~prompt_toolkit.layout.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"``.

.. note::

    These styles are actually compatible with
    `Pygments <http://pygments.org/>`_ styles, with additional support for
    `reverse` and `blink`. Further, we ignore flags like `roman`, `sans`,
    `mono` and `border`.

The following ANSI colors are available (both for foreground and background):

.. code::

    # 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, it is
possible to call :meth:`~Application.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
:class:`~prompt_toolkit.styles.Style` can be passed as an argument to the
:class:`~prompt_toolkit.application.Application`.

.. code:: python

    from prompt_toolkit.layout import VSplit, Window
    from prompt_toolkit.styles 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:ansired'),
         ('top', 'fg:#00aaaa'),
         ('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.

.. code:: python

   Window(BufferControl(...), style='class:left,bottom'),
   Window(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.

.. code:: python

    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 <http://pygments.org/>`_ 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).

.. code:: python

    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``):

.. code:: python

    style = Style([
         ('a.b.c', 'underline'),
     ])

It is possible to combine this:

.. code:: python

    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 underline``

- Then 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.

.. code:: python

    from prompt_toolkit.styles import Style

    style = Style.from_dict({
         'header body left.text': 'underline',
    })


Loading a style from Pygments
-----------------------------

`Pygments <http://pygments.org/>`_ 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:

.. code:: python

    from prompt_toolkit.styles.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 :class:`~prompt_toolkit.styles.Style` objects can be merged together as
follows:

.. code:: python

    from prompt_toolkit.styles 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 | ``ColorDepth.DEPTH_1_BIT``  | ``ColorDepth.MONOCHROME``       |
+--------+-----------------+-----------------------------+---------------------------------+
| 4 bit  | ANSI colors     | ``ColorDepth.DEPTH_4_BIT``  | ``ColorDepth.ANSI_COLORS_ONLY`` |
+--------+-----------------+-----------------------------+---------------------------------+
| 8 bit  | 256 colors      | ``ColorDepth.DEPTH_8_BIT``  | ``ColorDepth.DEFAULT``          |
+--------+-----------------+-----------------------------+---------------------------------+
| 24 bit | True colors     | ``ColorDepth.DEPTH_24_BIT`` | ``ColorDepth.TRUE_COLOR``       |
+--------+-----------------+-----------------------------+---------------------------------+

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 prompt_toolkit application can be done
by setting the ``PROMPT_TOOLKIT_COLOR_DEPTH`` environment variable. You could
for instance copy the following into your `.bashrc` file.

.. code:: shell

    # export PROMPT_TOOLKIT_COLOR_DEPTH=DEPTH_1_BIT
    export PROMPT_TOOLKIT_COLOR_DEPTH=DEPTH_4_BIT
    # export PROMPT_TOOLKIT_COLOR_DEPTH=DEPTH_8_BIT
    # export PROMPT_TOOLKIT_COLOR_DEPTH=DEPTH_24_BIT

An application can also decide to set the color depth manually by passing a
:class:`~prompt_toolkit.output.ColorDepth` value to the
:class:`~prompt_toolkit.application.Application` object:

.. code:: python

    from prompt_toolkit.output.color_depth import ColorDepth

    app = Application(
        color_depth=ColorDepth.ANSI_COLORS_ONLY,
        # ...
    )


Style transformations
---------------------

Prompt_toolkit 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
:class:`~prompt_toolkit.styles.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.

.. code:: python

    from prompt_toolkit.styles import AdjustBrightnessStyleTransformation

    app = Application(
        style_transformation=AdjustBrightnessStyleTransformation(
            min_brightness=0.5,  # Increase the minimum brightness.
            max_brightness=1.0,
        )
        # ...
    )