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
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cliapp-docs.R
\name{themes}
\alias{themes}
\title{About cli themes}
\description{
CLI elements can be styled via a CSS-like language of selectors and
properties. Only a small subset of CSS3 is supported, and
a lot visual properties cannot be implemented on a terminal, so these
will be ignored as well.
}
\section{Adding themes}{
The style of an element is calculated from themes from four sources.
These form a stack, and the themes on the top of the stack take
precedence, over themes in the bottom.
\enumerate{
\item The cli package has a built-in theme. This is always active.
See \code{\link[=builtin_theme]{builtin_theme()}}.
\item When an app object is created via \code{\link[=start_app]{start_app()}}, the caller can
specify a theme, that is added to theme stack. If no theme is
specified for \code{\link[=start_app]{start_app()}}, the content of the \code{cli.theme} option
is used. Removed when the corresponding app stops.
\item The user may specify a theme in the \code{cli.user_theme} option. This
is added to the stack \emph{after} the app's theme (step 2.), so it can
override its settings. Removed when the app that added it stops.
\item Themes specified explicitly in \code{\link[=cli_div]{cli_div()}} elements. These are
removed from the theme stack, when the corresponding \code{\link[=cli_div]{cli_div()}}
elements are closed.
}
}
\section{Writing themes}{
A theme is a named list of lists. The name of each entry is a CSS
selector. Only a subset of CSS is supported:
\itemize{
\item Type selectors, e.g. \code{input} selects all \verb{<input>} elements.
\item Class selectors, e.g. \code{.index} selects any element that has a class
of "index".
\item ID selector. \verb{#toc} will match the element that has the ID "toc".
\item The descendant combinator, i.e. the space, that selects nodes
that are descendants of the first element. E.g. \verb{div span} will match
all \verb{<span>} elements that are inside a \verb{<div>} element.
}
The content of a theme list entry is another named list, where the
names are CSS properties, e.g. \code{color}, or \code{font-weight} or
\code{margin-left}, and the list entries themselves define the values of
the properties. See \code{\link[=builtin_theme]{builtin_theme()}} and \code{\link[=simple_theme]{simple_theme()}} for examples.
}
\section{Formatter callbacks}{
For flexibility, themes may also define formatter functions, with
property name \code{fmt}. These will be called once the other styles are
applied to an element. They are only called on elements that produce
output, i.e. \emph{not} on container elements.
}
\section{Supported properties}{
Right now only a limited set of properties are supported. These include
left, right, top and bottom margins, background and foreground colors,
bold and italic fonts, underlined text. The \code{before} and \code{after}
properties are supported to insert text before and after the
content of the element.
The current list of properties:
\itemize{
\item \code{after}: A string literal to insert after the element. It can also be
a function that returns a string literal. Supported by all inline
elements, list items, alerts and rules.
\item \code{background-color}: An R color name, or HTML hexadecimal color.
It can be applied to most elements (inline elements, rules, text,
etc.), but the background of containers is not colored properly
currently.
\item \code{before}: A string literal to insert before the element. It can also be
a function that returns a string literal. Supported by all inline
elements, list items, alerts and rules.
\item \code{class-map}: Its value can be a named list, and it specifies how
R (S3) class names are mapped to cli class names. E.g.
\code{list(fs_path = "file")} specifies that \code{fs_path} objects (from the fs
package) should always print as \code{.file} objects in cli.
\item \code{color}: Text color, an R color name or a HTML hexadecimal color. It
can be applied to most elements that are printed.
\item \code{collapse}: Specifies how to collapse a vector, before applying
styling. If a character string, then that is used as the separator.
If a function, then it is called, with the vector as the only
argument.
\item \code{digits}: Number of digits after the decimal point for numeric inline
element of class \code{.val}.
\item \code{fmt}: Generic formatter function that takes an input text and returns
formatted text. Can be applied to most elements. If colors are in use,
the input text provided to \code{fmt} already includes ANSI sequences.
\item \code{font-style}: If \code{"italic"} then the text is printed as cursive.
\item \code{font-weight}: If \code{"bold"}, then the text is printed in boldface.
\item \code{line-type}: Line type for \code{\link[=cli_rule]{cli_rule()}}.
\item \code{list-style-type}: String literal or functions that returns a string
literal, to be used as a list item marker in un-ordered lists.
\item \code{margin-bottom}, \code{margin-left}, \code{margin-right}, \code{margin-top}: Margins.
\item \code{padding-left}, \code{padding-right}: This is currently used the same way
as the margins, but this might change later.
\item \code{start}: Integer number, the first element in an ordered list.
\item \code{string-quote}: Quoting character for inline elements of class \code{.val}.
\item \code{text-decoration}: If \code{"underline"}, then underlined text is created.
\item \code{text-exdent}: Amount of indentation from the second line of wrapped
text.
\item \code{transform}: A function to call on glue substitutions, before
collapsing them. Note that \code{transform} is applied prior to
implementing color via ANSI sequences.
\item \code{vec-last}: The last separator when collapsing vectors.
\item \code{vec-sep}: The separator to use when collapsing vectors.
\item \code{vec-sep2}: The separator to use for two elements when collapsing
vectors. If not set, then \code{vec-sep} is used for these as well.
\item \code{vec-trunc}: Vectors longer than this will be truncated. Defaults to
100.
\item \code{vec-trunc-style}: Select between two ways of collapsing vectors:
\itemize{
\item \code{"both-ends"} is the current default and it shows the beginning and
the end of the vector.
\item \code{"head"} only shows the beginning of the vector.
}
}
More properties might be added later. If you think that a property is
not applied properly to an element, please open an issue about it in
the cli issue tracker.
}
\section{Examples}{
Color of headings, that are only active in paragraphs with an
'output' class:
\if{html}{\out{<div class="sourceCode">}}\preformatted{list(
"par.output h1" = list("background-color" = "red", color = "#e0e0e0"),
"par.output h2" = list("background-color" = "orange", color = "#e0e0e0"),
"par.output h3" = list("background-color" = "blue", color = "#e0e0e0")
)
}\if{html}{\out{</div>}}
Create a custom alert type:
\if{html}{\out{<div class="sourceCode">}}\preformatted{list(
".alert-start" = list(before = symbol$play),
".alert-stop" = list(before = symbol$stop)
)
}\if{html}{\out{</div>}}
}
|
