[−][src]Module cursive::theme
Handle colors and themes in the UI.
Colors
Characters can be printed in the terminal with a specific color.
The Color
enum represents the ways this can be set.
Palette
To achieve a customizable, yet unified look, Cursive uses a configurable palette of colors to be used through the entire application.
The PaletteColor
enum defines possible entries in this palette.
These entries are:
Background
: used to color the application background (around views). Defaults to blue.Shadow
: used to color shadow around views. Defaults to black.View
: used to color the background for views. Defaults to white.Primary
: used to print primary text. Defaults to black.Secondary
: used to print secondary text. Defaults to blue.Tertiary
: used to print tertiary text. Defaults to white.TitlePrimary
: used to print primary titles. Defaults to red.TitleSecondary
: used to print secondary titles. Defaults to yellow.Highlight
: used to highlight selected items. Defaults to red.HighlightInactive
: used to highlight selected but inactive items. Defaults to blue.HighlightText
: used to print primary text when highlighted Defaults to white.
A Palette
then maps each of these to an actual Color
.
Color Types
When drawing views, color can be picked in two way:
- An exact
Color
can be given directly - A
PaletteColor
entry can be given, which will fetch whatever color is currently defined for this.
The ColorType
enum abstract over these two choices.
Color Styles
To actually print anything, two colors must be picked: one for the foreground, and one for the background.
As such, a ColorStyle
is made of a pair of ColorType
.
Since some pairs are frequently used, ColorStyle
defines some methods to
create these usual values:
ColorStyle::background()
: style used to print the application background.- Its background color is
Background
. - Its foreground color is unimportant as no characters are ever printed in the background.
- Its background color is
ColorStyle::shadow()
: style used to print shadows behind views.- Its background color is
Shadow
. - Here again, the foreground color is unimportant.
- Its background color is
ColorStyle::primary()
: style used to print primary text.- Its background color is
View
. - Its foreground color is
Primary
.
- Its background color is
ColorStyle::secondary()
: style used to print secondary text.- Its background color is
View
. - Its foreground color is
Secondary
.
- Its background color is
ColorStyle::tertiary()
: style used to print tertiary text.- Its background color is
View
. - Its foreground color is
Tertiary
.
- Its background color is
ColorStyle::title_primary()
: style used to print titles.- Its background color is
View
. - Its foreground color is
TitlePrimary
.
- Its background color is
ColorStyle::title_secondary()
: style used to print secondary titles.- Its background color is
View
. - Its foreground color is
TitleSecondary
.
- Its background color is
ColorStyle::highlight()
: style used to print selected items.- Its background color is
Highlight
. - Its foreground color is
HighlightText
.
- Its background color is
ColorStyle::highlight_inactive()
: style used to print selected, but inactive items.- Its background color is
HighlightInactive
. - Its foreground color is
HighlightText
.
- Its background color is
Using one of these pairs when styling your application helps give it a coherent look.
Effects
On top of a color style, some effects can be applied on cells: Reverse
,
for instance, swaps the foreground and background colors of a cell.
Style
Finally, a style combine a ColorType
and a set of Effect
s, to
represent any way text should be printed on screen.
Themes
A Theme
object defines the color palette an application will use, as
well as various options to style views.
There are several ways to set a theme for the application:
- Construct a
Theme
object by setting every field individually. - Get the current theme with
Cursive::current_theme
method and changing the required fields (for example see theme_manual example). - Using a toml file as a theme configuration (for example see theme example).
Configuring theme with toml
This requires the toml
feature to be enabled.
[dependencies]
cursive = { version = "*", features = ["toml"] }
To use the theme in your application, load it with Cursive::load_toml
method (or use theme::load_theme_file
to aquire the theme object).
let mut siv = Cursive::new(); // Embed the theme with the binary. siv.load_toml(include_str!("<path_to_theme_file>.toml")).unwrap();
Here are the possible entries (all fields are optional):
# Every field in a theme file is optional.
# First come some various options
shadow = false # Don't draw shadows around stacked views
borders = "simple" # Alternatives are "none" and "outset"
# Here we define the color palette.
[colors]
background = "black"
# If the value is an array, the first valid color will be used.
# If the terminal doesn't support custom color,
# non-base colors will be skipped.
shadow = ["#000000", "black"]
view = "#d3d7cf"
# Array and simple values have the same effect.
primary = ["#111111"]
secondary = "#EEEEEE"
tertiary = "#444444"
# Hex values can use lower or uppercase.
# (base color MUST be lowercase)
title_primary = "#ff5555"
title_secondary = "#ffff55"
# Lower precision values can use only 3 digits.
highlight = "#F00"
highlight_inactive = "#5555FF"
Structs
ColorPair | Combines a front and back color. |
ColorStyle | Possible color style for a cell. |
Palette | Color configuration for the application. |
Style | Combine a color and an effect. |
Theme | Represents the style a Cursive application will use. |
Enums
BaseColor | One of the 8 base colors. |
BorderStyle | Specifies how some borders should be drawn. |
Color | Represents a color used by the theme. |
ColorType | Either a color from the palette, or a direct color. |
Effect | Text effect |
Error | Possible error returned when loading a theme. |
PaletteColor | Color entry in a palette. |
Functions
load_default | Loads the default theme, and returns its representation. |
load_theme_file | Loads a theme from file. |
load_toml | Loads a theme string and sets it as active. |