From 9e883d3e4595e163d912fec4b0f382ef8ef95e3a Mon Sep 17 00:00:00 2001 From: darrenburns Date: Thu, 15 Sep 2022 16:32:23 +0100 Subject: [PATCH] Document styles (#785) * Add docs for CSS variables * Add ref docs for various styles, fix some typos in places --- docs/guide/layout.md | 2 ++ docs/styles/color.md | 5 +++- docs/styles/dock.md | 45 +++++++++++++++++++++++++++++++++++ docs/styles/grid.md | 27 +++++++++++++++++++++ docs/styles/layer.md | 50 +++++++++++++++++++++++++++++++++++++++ docs/styles/layers.md | 50 +++++++++++++++++++++++++++++++++++++++ docs/styles/max_height.md | 6 ++--- docs/styles/max_width.md | 3 +-- docs/styles/min_width.md | 7 +++--- mkdocs.yml | 4 ++++ 10 files changed, 189 insertions(+), 10 deletions(-) create mode 100644 docs/styles/dock.md create mode 100644 docs/styles/grid.md create mode 100644 docs/styles/layer.md create mode 100644 docs/styles/layers.md diff --git a/docs/guide/layout.md b/docs/guide/layout.md index 534355643..8275b9e65 100644 --- a/docs/guide/layout.md +++ b/docs/guide/layout.md @@ -518,6 +518,8 @@ However, in this case, both `#box1` and `#box2` are assigned to layers. From the `layers: below above;` declaration inside `layers.css`, we can see that the layer named `above` is on top of the `below` layer. Since `#box1` is on the higher layer, it is drawn on top of `#box2`. +[//]: # (NOTE: the example below also appears in the layers and layer style reference) + === "Output" ```{.textual path="docs/examples/guide/layout/layers.py"} diff --git a/docs/styles/color.md b/docs/styles/color.md index 24b80143c..0fae0a0b0 100644 --- a/docs/styles/color.md +++ b/docs/styles/color.md @@ -5,7 +5,7 @@ The `color` rule sets the text color of a Widget. ## Syntax ``` -color: []; +color: | auto []; ``` ## Example @@ -40,6 +40,9 @@ color: red 20%; /* RGB color */ color: rgb(100,120,200); + +/* Automatically choose color with suitable contrast for readability */ +color: auto; ``` ## Python diff --git a/docs/styles/dock.md b/docs/styles/dock.md new file mode 100644 index 000000000..875358614 --- /dev/null +++ b/docs/styles/dock.md @@ -0,0 +1,45 @@ +# Dock + +The `dock` property is used to fix a widget to the edge of a container (which may be the entire terminal window). + +## Syntax + +``` +dock: top|right|bottom|left; +``` + +## Example + +The example below shows a `left` docked sidebar. +Notice that even though the content is scrolled, the sidebar remains fixed. + +=== "Output" + + ```{.textual path="docs/examples/guide/layout/dock_layout1_sidebar.py" press="pagedown,down,down,_,_,_,_,_"} + ``` + +=== "dock_layout1_sidebar.py" + + ```python + --8<-- "docs/examples/guide/layout/dock_layout1_sidebar.py" + ``` + +=== "dock_layout1_sidebar.css" + + ```sass hl_lines="2" + --8<-- "docs/examples/guide/layout/dock_layout1_sidebar.css" + ``` + +## CSS + +```sass +/* Dock the widget on the left edge of its parent container */ +dock: left; +``` + +## Python + +```python +# Dock the widget on the left edge of its parent container +widget.styles.dock = "left" +``` diff --git a/docs/styles/grid.md b/docs/styles/grid.md new file mode 100644 index 000000000..40089e6cb --- /dev/null +++ b/docs/styles/grid.md @@ -0,0 +1,27 @@ +# Grid properties + +There are a number of properties relating to the Textual `grid` layout. + +For an in-depth look at the grid layout, visit the grid [guide](../guide/layout.md#grid). + +| Property | Description | +|----------------|------------------------------------------------| +| `grid-size` | Number of columns and rows in the grid layout. | +| `grid-rows` | Height of grid rows. | +| `grid-columns` | Width of grid columns. | +| `grid-gutter` | Spacing between grid cells. | +| `row-span` | Number of rows a cell spans. | +| `column-span` | Number of columns a cell spans. | + +## Syntax + +```sass +grid-size: []; /* columns first, then rows */ +grid-rows: ...; +grid-columns: ...; +grid-gutter: ; +row-span: ; +column-span: ; +``` + +## Example diff --git a/docs/styles/layer.md b/docs/styles/layer.md new file mode 100644 index 000000000..383e745b2 --- /dev/null +++ b/docs/styles/layer.md @@ -0,0 +1,50 @@ +# Layer + +The `layer` property is used to assign widgets to a layer. +The value of the `layer` property must be the name of a layer defined using a `layers` declaration. +Layers control the order in which widgets are painted on screen. +More information on layers can be found in the [guide](../guide/layout.md#layers). + +## Syntax + +``` +layer: ; +``` + +## Example + +In the example below, `#box1` is yielded before `#box2`. +However, since `#box1` is on the higher layer, it is drawn on top of `#box2`. + +[//]: # (NOTE: the example below also appears in the guide and 'layers.md'.) + +=== "Output" + + ```{.textual path="docs/examples/guide/layout/layers.py"} + ``` + +=== "layers.py" + + ```python + --8<-- "docs/examples/guide/layout/layers.py" + ``` + +=== "layers.css" + + ```sass hl_lines="3 15 19" + --8<-- "docs/examples/guide/layout/layers.css" + ``` + +## CSS + +```sass +/* Draw the widget on the layer called 'below' */ +layer: below; +``` + +## Python + +```python +# Draw the widget on the layer called 'below' +widget.layer = "below" +``` diff --git a/docs/styles/layers.md b/docs/styles/layers.md new file mode 100644 index 000000000..9eed3156d --- /dev/null +++ b/docs/styles/layers.md @@ -0,0 +1,50 @@ +# Layers + +The `layers` property allows you to define an ordered set of layers. +These `layers` can later be referenced using the `layer` property. +Layers control the order in which widgets are painted on screen. +More information on layers can be found in the [guide](../guide/layout.md#layers). + +## Syntax + +``` +layers: ...; +``` + +## Example + +In the example below, `#box1` is yielded before `#box2`. +However, since `#box1` is on the higher layer, it is drawn on top of `#box2`. + +[//]: # (NOTE: the example below also appears in the guide and 'layer.md'.) + +=== "Output" + + ```{.textual path="docs/examples/guide/layout/layers.py"} + ``` + +=== "layers.py" + + ```python + --8<-- "docs/examples/guide/layout/layers.py" + ``` + +=== "layers.css" + + ```sass hl_lines="3 15 19" + --8<-- "docs/examples/guide/layout/layers.css" + ``` + +## CSS + +```sass +/* Bottom layer is called 'below', layer above it is called 'above' */ +layers: below above; +``` + +## Python + +```python +# Bottom layer is called 'below', layer above it is called 'above' +widget.layers = ("below", "above") +``` diff --git a/docs/styles/max_height.md b/docs/styles/max_height.md index faecdffd9..e80d996fe 100644 --- a/docs/styles/max_height.md +++ b/docs/styles/max_height.md @@ -22,10 +22,10 @@ max-height: 25vh; ## Python ```python -# Set the maximum width to 10 rows +# Set the maximum height to 10 rows widget.styles.max_height = 10 -# Set the maximum width to 25% of the screen width -widget.styles.max_height = "25vw" +# Set the maximum height to 25% of the screen height +widget.styles.max_height = "25vh" ``` diff --git a/docs/styles/max_width.md b/docs/styles/max_width.md index 9a4ae931d..c6ce4ef67 100644 --- a/docs/styles/max_width.md +++ b/docs/styles/max_width.md @@ -16,7 +16,7 @@ max-width: ; max-width: 10; /* Set a maximum width of 25% of the screen width */ -max-width: 25vh; +max-width: 25vw; ``` ## Python @@ -27,5 +27,4 @@ widget.styles.max_width = 10 # Set the maximum width to 25% of the screen width widget.styles.max_width = "25vw" - ``` diff --git a/docs/styles/min_width.md b/docs/styles/min_width.md index 01cf2a49d..81331469a 100644 --- a/docs/styles/min_width.md +++ b/docs/styles/min_width.md @@ -16,7 +16,7 @@ min-width: ; min-width: 10; /* Set a minimum width of 25% of the screen width */ -min-width: 25vh; +min-width: 25vw; ``` ## Python @@ -25,7 +25,6 @@ min-width: 25vh; # Set the minimum width to 10 cells widget.styles.min_width = 10 -# Set the minimum width to 25% of the screen height -widget.styles.min_width = "25vh" - +# Set the minimum width to 25% of the screen width +widget.styles.min_width = "25vw" ``` diff --git a/mkdocs.yml b/mkdocs.yml index a2c957d2f..ee8bb75cc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -57,7 +57,11 @@ nav: - "styles/color.md" - "styles/content_align.md" - "styles/display.md" + - "styles/dock.md" + - "styles/grid.md" - "styles/height.md" + - "styles/layer.md" + - "styles/layers.md" - "styles/layout.md" - "styles/margin.md" - "styles/max_height.md"