alihan/textual
1
0
Fork 0
mirror of https://github.com/Textualize/textual.git synced 2025-10-17 02:38:12 +03:00
Code Issues Packages Projects Releases Wiki Activity

Add more consistent phrasing.

Browse Source 
Related issues: #2107
This commit is contained in:
Rodrigo Girão Serrão
2023-03-23 11:04:17 +00:00
parent a935a632fa
commit 559f976f78
57 changed files with 141 additions and 161 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
docs/snippets/border_vs_outline_example.md Normal file
View File

@@ -0,0 +1,21 @@
The next example makes the difference between [`border`](/styles/border) and [`outline`](/styles/outline) clearer by having three labels side-by-side.
They contain the same text, have the same width and height, and are styled exactly the same up to their [`border`](/styles/border) and [`outline`](/styles/outline) styles.
This example also shows that a widget cannot contain both a `border` and an `outline`:
=== "Output"
```{.textual path="docs/examples/styles/outline_vs_border.py"}
```
=== "outline_vs_border.py"
```python
--8<-- "docs/examples/styles/outline_vs_border.py"
```
=== "outline_vs_border.css"
```sass hl_lines="5-7 9-11"
--8<-- "docs/examples/styles/outline_vs_border.css"
```

46
docs/styles/_template.md
View File

@@ -1,20 +1,20 @@
<!-- This is the template file for a CSS rule reference page. -->
<!-- This is the template file for a CSS style reference page. -->
# Rule-name
# Style-name
<!-- Short description of what the rule does, without syntax details or anything.
<!-- Short description of what the style does, without syntax details or anything.
One or two sentences is typically enough. -->
## Syntax
--8<-- "docs/snippets/syntax_block_start.md"
<!--
Formal syntax description of the rule
rule-name: <a href="../../css_types/type_one">&lt;type-one&gt;</a>;
Formal syntax description of the style
style-name: <a href="../../css_types/type_one">&lt;type-one&gt;</a>;
-->
--8<-- "docs/snippets/syntax_block_end.md"
<!-- Description of what the rule uses the types/values for. -->
<!-- Description of what the style uses the types/values for. -->
### Values
@@ -35,19 +35,19 @@ Short description of the first example.
=== "Output"
```{.textual path="docs/examples/styles/rule.py"}
```{.textual path="docs/examples/styles/style.py"}
```
=== "rule.py"
=== "style.py"
```py
--8<-- "docs/examples/styles/rule.py"
--8<-- "docs/examples/styles/style.py"
```
=== "rule.css"
=== "style.css"
```sass
--8<-- "docs/examples/styles/rule.css"
--8<-- "docs/examples/styles/style.css"
```
-->
@@ -57,19 +57,19 @@ Short description of the second example.
=== "Output"
```{.textual path="docs/examples/styles/rule.py"}
```{.textual path="docs/examples/styles/style.py"}
```
=== "rule.py"
=== "style.py"
```py
--8<-- "docs/examples/styles/rule.py"
--8<-- "docs/examples/styles/style.py"
```
=== "rule.css"
=== "style.css"
```sass
--8<-- "docs/examples/styles/rule.css"
--8<-- "docs/examples/styles/style.css"
```
-->
@@ -98,18 +98,18 @@ rule-name-variant: value4
## Python
<!--
The Python syntax for the rule definitions.
The Python syntax for the style definitions.
Copy the same examples as the ones shown in the CSS above.
If the programmatic way of setting the rule differs significantly from the CSS way, make note of that here.
If the programmatic way of setting the property differs significantly from the CSS way, make note of that here.
```py
widget.styles.rule_name = value1
widget.styles.rule_name = value2
widget.styles.rule_name = (different_syntax_value, shown_here)
widget.styles.property_name = value1
widget.styles.property_name = value2
widget.styles.property_name = (different_syntax_value, shown_here)
widget.styles.rule_name_variant = value3
widget.styles.rule_name_variant = value4
widget.styles.property_name_variant = value3
widget.styles.property_name_variant = value4
```
-->

2
docs/styles/align.md
View File

@@ -11,7 +11,7 @@ align-horizontal: <a href="../../css_types/horizontal">&lt;horizontal&gt;</a>;
align-vertical: <a href="../../css_types/vertical">&lt;vertical&gt;</a>;
--8<-- "docs/snippets/syntax_block_end.md"
The style `align` takes a [`<horizontal>`](../../css_types/horizontal) followed by a [`<vertical>`](../../css_types/vertical).
The `align` style takes a [`<horizontal>`](../../css_types/horizontal) followed by a [`<vertical>`](../../css_types/vertical).
You can specify the alignment of children on both the horizontal and vertical axes at the same time,
or on each of the axis separately.

6
docs/styles/background.md
View File

@@ -1,6 +1,6 @@
# Background
The `background` rule sets the background color of a widget.
The `background` style sets the background color of a widget.
## Syntax
@@ -8,7 +8,7 @@ The `background` rule sets the background color of a widget.
background: <a href="../../css_types/color">&lt;color&gt;</a> [<a href="../../css_types/percentage">&lt;percentage&gt;</a>];
--8<-- "docs/snippets/syntax_block_end.md"
The style `background` needs a [`<color>`](../../css_types/color) followed by an optional [`<percentage>`](../../css_types/percentage) to specify the color transparency (clamped between `0%` and `100%`).
The `background` style needs a [`<color>`](../../css_types/color) followed by an optional [`<percentage>`](../../css_types/percentage) to specify the color transparency (clamped between `0%` and `100%`).
## Examples
@@ -35,7 +35,7 @@ This example creates three widgets and applies a different background to each.
### Different transparency settings
The next example creates ten widgets layed out side by side to show the effect of setting different percentages for the transparency of the background color.
The next example creates ten widgets laid out side by side to show the effect of setting different percentages for the transparency of the background color.
=== "Output"

28
docs/styles/border.md
View File

@@ -1,6 +1,6 @@
# Border
The `border` rule enables the drawing of a box around a widget.
The `border` style enables the drawing of a box around a widget.
!!! note
@@ -17,13 +17,13 @@ border-bottom: [<a href="../../css_types/border">&lt;border&gt;</a>] [<a href=".
border-left: [<a href="../../css_types/border">&lt;border&gt;</a>] [<a href="../../css_types/color">&lt;color&gt;</a> [<a href="../../css_types/percentage">&lt;percentage&gt;</a>]];
--8<-- "docs/snippets/syntax_block_end.md"
The style `border` accepts an optional [`<border>`](../../css_types/border) that sets the visual style of the widget border, an optional [`<color>`](../../css_types/color) to set the color of the border, and an optional [`<percentage>`](../../css_types/percentage) to specify the color transparency.
The `border` style accepts an optional [`<border>`](../../css_types/border) that sets the visual style of the widget border, an optional [`<color>`](../../css_types/color) to set the color of the border, and an optional [`<percentage>`](../../css_types/percentage) to specify the color transparency.
Borders may also be set individually for the four edges of a widget with the `border-top`, `border-right`, `border-bottom` and `border-left` rules.
### Multiple edge rules
If multiple border rules target the same edge, the last rule that targets a specific edge is the one that is applied to that edge.
If multiple border styles target the same edge, the last style that targets a specific edge is the one that is applied to that edge.
For example, consider the CSS below:
```sass
@@ -99,27 +99,7 @@ The next example shows a grid with all the available border types.
### Borders and outlines
The next example makes the difference between [`border`](./border.md) and [`outline`](./outline.md) clearer by having three labels side-by-side.
They contain the same text, have the same width and height, and are styled exactly the same up to their `outline` and [`border`](./border.md) rules.
This example also shows that a widget cannot contain both a `border` and an `outline`:
=== "Output"
```{.textual path="docs/examples/styles/outline_vs_border.py"}
```
=== "outline_vs_border.py"
```python
--8<-- "docs/examples/styles/outline_vs_border.py"
```
=== "outline_vs_border.css"
```sass hl_lines="5-7 9-11"
--8<-- "docs/examples/styles/outline_vs_border.css"
```
--8<-- "docs/snippets/border_vs_outline_example.md"
## CSS

4
docs/styles/border_subtitle_align.md
View File

@@ -1,6 +1,6 @@
# Border-subtitle-align
The `border-subtitle-align` rule sets the horizontal alignment for the border subtitle.
The `border-subtitle-align` style sets the horizontal alignment for the border subtitle.
## Syntax
@@ -8,7 +8,7 @@ The `border-subtitle-align` rule sets the horizontal alignment for the border su
border-subtitle-align: <a href="../../css_types/horizontal">&lt;horizontal&gt;</a>;
--8<-- "docs/snippets/syntax_block_end.md"
The style `border-subtitle-align` takes a [`<horizontal>`](../../css_types/horizontal) that determines where the border subtitle is aligned along the top edge of the border.
The `border-subtitle-align` style takes a [`<horizontal>`](../../css_types/horizontal) that determines where the border subtitle is aligned along the top edge of the border.
This means that the border corners are always visible.
### Default

4
docs/styles/border_title_align.md
View File

@@ -1,6 +1,6 @@
# Border-title-align
The `border-title-align` rule sets the horizontal alignment for the border title.
The `border-title-align` style sets the horizontal alignment for the border title.
## Syntax
@@ -8,7 +8,7 @@ The `border-title-align` rule sets the horizontal alignment for the border title
border-title-align: <a href="../../css_types/horizontal">&lt;horizontal&gt;</a>;
--8<-- "docs/snippets/syntax_block_end.md"
The style `border-title-align` takes a [`<horizontal>`](../../css_types/horizontal) that determines where the border title is aligned along the top edge of the border.
The `border-title-align` style takes a [`<horizontal>`](../../css_types/horizontal) that determines where the border title is aligned along the top edge of the border.
This means that the border corners are always visible.
### Default

2
docs/styles/box_sizing.md
View File

@@ -1,6 +1,6 @@
# Box-sizing
The `box-sizing` property determines how the width and height of a widget are calculated.
The `box-sizing` style determines how the width and height of a widget are calculated.
## Syntax

4
docs/styles/color.md
View File

@@ -1,6 +1,6 @@
# Color
The `color` rule sets the text color of a widget.
The `color` style sets the text color of a widget.
## Syntax
@@ -8,7 +8,7 @@ The `color` rule sets the text color of a widget.
color: (<a href="../../css_types/color">&lt;color&gt;</a> | auto) [<a href="../../css_types/percentage">&lt;percentage&gt;</a>];
--8<-- "docs/snippets/syntax_block_end.md"
The style `color` needs a [`<color>`](../../css_types/color) followed by an optional [`<percentage>`](../../css_types/percentage) to specify the color transparency.
The `color` style needs a [`<color>`](../../css_types/color) followed by an optional [`<percentage>`](../../css_types/percentage) to specify the color transparency.
Instead of a [`<color>`](../../css_types/color), one can use the special value `"auto"` to choose automatically the color with the best contrast for readability purposes.

2
docs/styles/content_align.md
View File

@@ -11,7 +11,7 @@ content-align-horizontal: <a href="../../css_types/horizontal">&lt;horizontal&gt
content-align-vertical: <a href="../../css_types/vertical">&lt;vertical&gt;</a>;
--8<-- "docs/snippets/syntax_block_end.md"
The style `content-align` takes a [`<horizontal>`](../../css_types/horizontal) followed by a [`<vertical>`](../../css_types/vertical).
The `content-align` style takes a [`<horizontal>`](../../css_types/horizontal) followed by a [`<vertical>`](../../css_types/vertical).
You can specify the alignment of content on both the horizontal and vertical axes at the same time,
or on each of the axis separately.

2
docs/styles/display.md
View File

@@ -1,6 +1,6 @@
# Display
The `display` property defines whether a widget is displayed or not.
The `display` style defines whether a widget is displayed or not.
## Syntax

2
docs/styles/dock.md
View File

@@ -1,6 +1,6 @@
# Dock
The `dock` property is used to fix a widget to the edge of a container (which may be the entire terminal window).
The `dock` style is used to fix a widget to the edge of a container (which may be the entire terminal window).
## Syntax

2
docs/styles/grid/column_span.md
View File

@@ -12,7 +12,7 @@ The `column-span` style specifies how many columns a widget will span in a grid
column-span: <a href="../../css_types/integer">&lt;integer&gt;</a>;
--8<-- "docs/snippets/syntax_block_end.md"
The style `column-span` accepts a single non-negative [`<integer>`](../../../css_types/integer) that quantifies how many columns the given widget spans.
The `column-span` style accepts a single non-negative [`<integer>`](../../../css_types/integer) that quantifies how many columns the given widget spans.
## Example

4
docs/styles/grid/grid_columns.md
View File

@@ -12,7 +12,7 @@ The `grid-columns` style allows to define the width of the columns of the grid.
grid-columns: <a href="../../css_types/scalar">&lt;scalar&gt;</a>+;
--8<-- "docs/snippets/syntax_block_end.md"
The style `grid-columns` takes one or more [`<scalar>`](../../../css_types/scalar) that specify the length of the columns of the grid.
The `grid-columns` style takes one or more [`<scalar>`](../../../css_types/scalar) that specify the length of the columns of the grid.
If there are more columns in the grid than scalars specified in `grid-columns`, they are reused cyclically.
If the number of [`<scalar>`](../../../css_types/scalar) is in excess, the excess is ignored.
@@ -22,7 +22,7 @@ If the number of [`<scalar>`](../../../css_types/scalar) is in excess, the exces
The example below shows a grid with 10 labels laid out in a grid with 2 rows and 5 columns.
We set `grid-columns: 1fr 16 2fr`.
Because there are more rows than scalars in the style rule, the scalars will be reused:
Because there are more rows than scalars in the style definition, the scalars will be reused:
- columns 1 and 4 have width `1fr`;
- columns 2 and 5 have width `16`; and

4
docs/styles/grid/grid_gutter.md
View File

@@ -4,7 +4,7 @@ The `grid-gutter` style sets the size of the gutter in the grid layout.
That is, it sets the space between adjacent cells in the grid.
Gutter is only applied _between_ the edges of cells.
No spacing is added between the edges of cells and the edges of the container.
No spacing is added between the edges of the cells and the edges of the container.
!!! note
@@ -16,7 +16,7 @@ No spacing is added between the edges of cells and the edges of the container.
grid-gutter: <a href="../../css_types/scalar">&lt;scalar&gt;</a> [<a href="../../css_types/scalar">&lt;scalar&gt;</a>];
--8<-- "docs/snippets/syntax_block_end.md"
The style `grid-gutter` takes one or two [`<scalar>`](../../../css_types/scalar) that set the length of the gutter along the vertical and horizontal axes.
The `grid-gutter` style takes one or two [`<scalar>`](../../../css_types/scalar) that set the length of the gutter along the vertical and horizontal axes.
If only one [`<scalar>`](../../../css_types/scalar) is supplied, it sets the vertical and horizontal gutters.
If two are supplied, they set the vertical and horizontal gutters, respectively.

4
docs/styles/grid/grid_rows.md
View File

@@ -12,7 +12,7 @@ The `grid-rows` style allows to define the height of the rows of the grid.
grid-rows: <a href="../../css_types/scalar">&lt;scalar&gt;</a>+;
--8<-- "docs/snippets/syntax_block_end.md"
The style `grid-rows` takes one or more [`<scalar>`](../../../css_types/scalar) that specify the length of the rows of the grid.
The `grid-rows` style takes one or more [`<scalar>`](../../../css_types/scalar) that specify the length of the rows of the grid.
If there are more rows in the grid than scalars specified in `grid-rows`, they are reused cyclically.
If the number of [`<scalar>`](../../../css_types/scalar) is in excess, the excess is ignored.
@@ -22,7 +22,7 @@ If the number of [`<scalar>`](../../../css_types/scalar) is in excess, the exces
The example below shows a grid with 10 labels laid out in a grid with 5 rows and 2 columns.
We set `grid-rows: 1fr 6 25%`.
Because there are more rows than scalars in the style rule, the scalars will be reused:
Because there are more rows than scalars in the style definition, the scalars will be reused:
- rows 1 and 4 have height `1fr`;
- rows 2 and 5 have height `6`; and

4
docs/styles/grid/grid_size.md
View File

@@ -14,7 +14,7 @@ The number of rows can be left unspecified and it will be computed automatically
grid-size: <a href="../../css_types/integer">&lt;integer&gt;</a> [<a href="../../css_types/integer">&lt;integer&gt;</a>];
--8<-- "docs/snippets/syntax_block_end.md"
The style `grid-size` takes one or two non-negative [`<integer>`](../../../css_types/integer).
The `grid-size` style takes one or two non-negative [`<integer>`](../../../css_types/integer).
The first defines how many columns there are in the grid.
If present, the second one sets the number of rows – regardless of the number of children of the grid –, otherwise the number of rows is computed automatically.
@@ -22,7 +22,7 @@ If present, the second one sets the number of rows – regardless of the number
### Columns and rows
In the first example, we create a grid with 2 columns and 5 rows, regardless of the fact that we do not have enough labels to fill in the whole grid:
In the first example, we create a grid with 2 columns and 5 rows, although we do not have enough labels to fill in the whole grid:
=== "Output"

8
docs/styles/grid/index.md
View File

@@ -1,6 +1,6 @@
# Grid
There are a number of properties relating to the Textual `grid` layout.
There are a number of styles relating to the Textual `grid` layout.
For an in-depth look at the grid layout, visit the grid [guide](../../guide/layout.md#grid).
@@ -33,10 +33,10 @@ Visit each style's reference page to learn more about how the values are used.
## Example
The example below shows all the properties above in action.
The example below shows all the styles above in action.
The `grid-size: 3 4;` declaration sets the grid to 3 columns and 4 rows.
The first cell of the grid, tinted magenta, shows a cell spanning multiple rows and columns.
The spacing between grid cells is because of the `grid-gutter` declaration.
The spacing between grid cells is defined by the `grid-gutter` style.
=== "Output"
@@ -57,7 +57,7 @@ The spacing between grid cells is because of the `grid-gutter` declaration.
!!! warning
The properties listed on this page will only work when the layout is `grid`.
The styles listed on this page will only work when the layout is `grid`.
## See also

2
docs/styles/grid/row_span.md
View File

@@ -12,7 +12,7 @@ The `row-span` style specifies how many rows a widget will span in a grid layout
row-span: <a href="../../css_types/integer">&lt;integer&gt;</a>;
--8<-- "docs/snippets/syntax_block_end.md"
The style `row-span` accepts a single non-negative [`<integer>`](../../../css_types/integer) that quantifies how many rows the given widget spans.
The `row-span` style accepts a single non-negative [`<integer>`](../../../css_types/integer) that quantifies how many rows the given widget spans.
## Example

4
docs/styles/height.md
View File

@@ -1,6 +1,6 @@
# Height
The `height` rule sets a widget's height.
The `height` style sets a widget's height.
## Syntax
@@ -8,7 +8,7 @@ The `height` rule sets a widget's height.
height: <a href="../../css_types/scalar">&lt;scalar&gt;</a>;
--8<-- "docs/snippets/syntax_block_end.md"
The style `height` needs a [`<scalar>`](../../css_types/scalar) to determine the vertical length of the widget.
The `height` style needs a [`<scalar>`](../../css_types/scalar) to determine the vertical length of the widget.
By default, it sets the height of the content area, but if [`box-sizing`](./box_sizing) is set to `border-box` it sets the height of the border area.
## Examples

6
docs/styles/layer.md
View File

@@ -1,6 +1,6 @@
# Layer
The `layer` property defines the layer a widget belongs to.
The `layer` style defines the layer a widget belongs to.
## Syntax
@@ -8,8 +8,8 @@ The `layer` property defines the layer a widget belongs to.
layer: <a href="../../css_types/name">&lt;name&gt;</a>;
--8<-- "docs/snippets/syntax_block_end.md"
The `layer` rule accepts a [`<name>`](../../css_types/name) that defines the layer this widget belongs to.
This [`<name>`](../../css_types/name) must correspond to a [`<name>`](../../css_types/name) that has been defined in a [`layers`](./layers) rule by an ancestor of this widget.
The `layer` style accepts a [`<name>`](../../css_types/name) that defines the layer this widget belongs to.
This [`<name>`](../../css_types/name) must correspond to a [`<name>`](../../css_types/name) that has been defined in a [`layers`](./layers) style by an ancestor of this widget.
More information on layers can be found in the [guide](../guide/layout.md#layers).

4
docs/styles/layers.md
View File

@@ -1,6 +1,6 @@
# Layers
The `layers` property allows you to define an ordered set of layers.
The `layers` style allows you to define an ordered set of layers.
## Syntax
@@ -8,7 +8,7 @@ The `layers` property allows you to define an ordered set of layers.
layers: <a href="../../css_types/name">&lt;name&gt;</a>+;
--8<-- "docs/snippets/syntax_block_end.md"
The `layers` rule accepts one or more [`<name>`](../../css_types/name) that define the layers that the widget is aware of, and the order in which they will be painted on the screen.
The `layers` style accepts one or more [`<name>`](../../css_types/name) that define the layers that the widget is aware of, and the order in which they will be painted on the screen.
The values used here can later be referenced using the [`layer`](../layer) property.
The layers defined first in the list are drawn under the layers that are defined later in the list.

4
docs/styles/layout.md
View File

@@ -1,6 +1,6 @@
# Layout
The `layout` property defines how a widget arranges its children.
The `layout` style defines how a widget arranges its children.
## Syntax
@@ -22,7 +22,7 @@ See the [layout](../guide/layout.md) guide for more information.
## Example
Note how the `layout` property affects the arrangement of widgets in the example below.
Note how the `layout` style affects the arrangement of widgets in the example below.
To learn more about the grid layout, you can see the [layout guide](../guide/layout.md) or the [grid reference](../grid).
=== "Output"

2
docs/styles/links/index.md
View File

@@ -5,7 +5,7 @@ There are a number of styles which influence the appearance of these links withi
!!! note
These CSS rules only target Textual action links. Internet hyperlinks are not affected by these CSS rules.
These CSS rules only target Textual action links. Internet hyperlinks are not affected by these styles.
| Property | Description |
|-------------------------------------------------------|-------------------------------------------------------------------|

2
docs/styles/links/link_background.md
View File

@@ -1,6 +1,6 @@
# Link-background
The `link-background` sets the background color of the link.
The `link-background` style sets the background color of the link.
!!! note

2
docs/styles/links/link_color.md
View File

@@ -1,6 +1,6 @@
# Link-color
The `link-color` sets the color of the link text.
The `link-color` style sets the color of the link text.
!!! note

2
docs/styles/links/link_hover_background.md
View File

@@ -1,6 +1,6 @@
# Link-hover-background
The `link-hover-background` sets the background color of the link when the mouse cursor is over the link.
The `link-hover-background` style sets the background color of the link when the mouse cursor is over the link.
!!! note

2
docs/styles/links/link_hover_color.md
View File

@@ -1,6 +1,6 @@
# Link-hover-color
The `link-hover-color` sets the color of the link text when the mouse cursor is over the link.
The `link-hover-color` style sets the color of the link text when the mouse cursor is over the link.
!!! note

2
docs/styles/links/link_hover_style.md
View File

@@ -1,6 +1,6 @@
# Link-hover-style
The `link-hover-style` sets the text style for the link text when the mouse cursor is over the link.
The `link-hover-style` style sets the text style for the link text when the mouse cursor is over the link.
!!! note

2
docs/styles/links/link_style.md
View File

@@ -1,6 +1,6 @@
# Link-style
The `link-style` sets the text style for the link text.
The `link-style` style sets the text style for the link text.
!!! note

9
docs/styles/margin.md
View File

@@ -1,6 +1,6 @@
# Margin
The `margin` rule specifies spacing around a widget.
The `margin` style specifies spacing around a widget.
## Syntax
@@ -30,7 +30,7 @@ The number of values given defines what edges get what margin:
To remember the order of the edges affected by the rule `margin` when it has 4 values, think of a clock.
Its hand starts at the top and the goes clockwise: top, right, bottom, left.
Alternatively, margin can be set for each edge individually through the rules `margin-top`, `margin-right`, `margin-bottom`, and `margin-left`, respectively.
Alternatively, margin can be set for each edge individually through the styles `margin-top`, `margin-right`, `margin-bottom`, and `margin-left`, respectively.
## Examples
@@ -96,9 +96,8 @@ margin-left: 4;
## Python
In Python, you cannot set any of the individual `margin` rules `margin-top`, `margin-right`, `margin-bottom`, and `margin-left`.
However, you _can_ set margin to a single integer, a tuple of 2 integers, or a tuple of 4 integers:
Python does not provide the properties `margin-top`, `margin-right`, `margin-bottom`, and `margin-left`.
However, you _can_ set the margin to a single integer, a tuple of 2 integers, or a tuple of 4 integers:
```python
# Set margin of 1 around all edges

4
docs/styles/max_height.md
View File

@@ -1,6 +1,6 @@
# Max-height
The `max-height` rule sets a maximum height for a widget.
The `max-height` style sets a maximum height for a widget.
## Syntax
@@ -8,7 +8,7 @@ The `max-height` rule sets a maximum height for a widget.
max-height: <a href="../../css_types/scalar">&lt;scalar&gt;</a>;
--8<-- "docs/snippets/syntax_block_end.md"
The `max-height` rule accepts a [`<scalar>`](../../css_types/scalar) that defines an upper bound for the [`height`](./height) of a widget.
The `max-height` style accepts a [`<scalar>`](../../css_types/scalar) that defines an upper bound for the [`height`](./height) of a widget.
That is, the height of a widget is never allowed to exceed `max-height`.
## Example

6
docs/styles/max_width.md
View File

@@ -1,6 +1,6 @@
# Max-width
The `max-width` rule sets a maximum width for a widget.
The `max-width` style sets a maximum width for a widget.
## Syntax
@@ -8,12 +8,12 @@ The `max-width` rule sets a maximum width for a widget.
max-width: <a href="../../css_types/scalar">&lt;scalar&gt;</a>;
--8<-- "docs/snippets/syntax_block_end.md"
The `max-width` rule accepts a [`<scalar>`](../../css_types/scalar) that defines an upper bound for the [`width`](./width) of a widget.
The `max-width` style accepts a [`<scalar>`](../../css_types/scalar) that defines an upper bound for the [`width`](./width) of a widget.
That is, the width of a widget is never allowed to exceed `max-width`.
## Example
The example below shows some placeholders that were defined to span horizontally from the top edge of the terminal to the bottom edge.
The example below shows some placeholders that were defined to span horizontally from the left edge of the terminal to the right edge.
Then, we set `max-width` individually on each placeholder.
=== "Output"

4
docs/styles/min_height.md
View File

@@ -1,6 +1,6 @@
# Min-height
The `min-height` rule sets a minimum height for a widget.
The `min-height` style sets a minimum height for a widget.
## Syntax
@@ -8,7 +8,7 @@ The `min-height` rule sets a minimum height for a widget.
min-height: <a href="../../css_types/scalar">&lt;scalar&gt;</a>;
--8<-- "docs/snippets/syntax_block_end.md"
The `min-height` rule accepts a [`<scalar>`](../../css_types/scalar) that defines a lower bound for the [`height`](./height) of a widget.
The `min-height` style accepts a [`<scalar>`](../../css_types/scalar) that defines a lower bound for the [`height`](./height) of a widget.
That is, the height of a widget is never allowed to be under `min-height`.
## Example

4
docs/styles/min_width.md
View File

@@ -1,6 +1,6 @@
# Min-width
The `min-width` rule sets a minimum width for a widget.
The `min-width` style sets a minimum width for a widget.
## Syntax
@@ -8,7 +8,7 @@ The `min-width` rule sets a minimum width for a widget.
min-width: <a href="../../css_types/scalar">&lt;scalar&gt;</a>;
--8<-- "docs/snippets/syntax_block_end.md"
The `min-width` rule accepts a [`<scalar>`](../../css_types/scalar) that defines a lower bound for the [`width`](./width) of a widget.
The `min-width` style accepts a [`<scalar>`](../../css_types/scalar) that defines a lower bound for the [`width`](./width) of a widget.
That is, the width of a widget is never allowed to be under `min-width`.
## Example

2
docs/styles/offset.md
View File

@@ -1,6 +1,6 @@
# Offset
The `offset` rule defines an offset for the position of the widget.
The `offset` style defines an offset for the position of the widget.
## Syntax

4
docs/styles/opacity.md
View File

@@ -1,6 +1,6 @@
# Opacity
The `opacity` property sets the opacity/transparency of a widget.
The `opacity` style sets the opacity/transparency of a widget.
## Syntax
@@ -8,7 +8,7 @@ The `opacity` property sets the opacity/transparency of a widget.
opacity: <a href="../../css_types/number">&lt;number&gt;</a> | <a href="../../css_types/percentage">&lt;percentage&gt;</a>;
--8<-- "docs/snippets/syntax_block_end.md"
The opacity of a widget can be set as a [`<number>`](../css_types/number.md) or a [`<percentage>`](../css_types/percentage.md).
The opacity of a widget can be set as a [`<number>`](../css_types/number.md) or a [`<percentage>`](../css_types/percentage.md).
`0`/`0%` means no opacity, which is equivalent to full transparency.
Conversely, `1`/`100%` means full opacity, which is equivalent to no transparency.
Values outside of these ranges will be clamped.

26
docs/styles/outline.md
View File

@@ -1,6 +1,6 @@
# Outline
The `outline` rule enables the drawing of a box around the content of a widget, which means the outline is drawn _over_ the content area.
The `outline` style enables the drawing of a box around the content of a widget, which means the outline is drawn _over_ the content area.
!!! note
@@ -20,7 +20,7 @@ outline-left: [<a href="../../css_types/border">&lt;border&gt;</a>] [<a href="..
The style `outline` accepts an optional [`<border>`](../../css_types/border) that sets the visual style of the widget outline and an optional [`<color>`](../../css_types/color) to set the color of the outline.
Unlike the style [`border`](./border.md), the frame of the outline is drawn over the content area of the widget.
This rule can be useful for temporary emphasis of the content of a widget, if you want to draw the user's attention to it.
This rule can be useful to add temporary emphasis on the content of a widget, if you want to draw the user's attention to it.
## Border command
@@ -77,27 +77,7 @@ The next example shows a grid with all the available outline types.
### Borders and outlines
The next example makes the difference between [`border`](./border.md) and [`outline`](./outline.md) clearer by having three labels side-by-side.
They contain the same text, have the same width and height, and are styled exactly the same up to their `outline` and [`border`](./border.md) rules.
This example also shows that a widget cannot contain both a `border` and an `outline`:
=== "Output"
```{.textual path="docs/examples/styles/outline_vs_border.py"}
```
=== "outline_vs_border.py"
```python
--8<-- "docs/examples/styles/outline_vs_border.py"
```
=== "outline_vs_border.css"
```sass hl_lines="5-7 9-11"
--8<-- "docs/examples/styles/outline_vs_border.css"
```
--8<-- "docs/snippets/border_vs_outline_example.md"
## CSS

2
docs/styles/overflow.md
View File

@@ -1,6 +1,6 @@
# Overflow
The `overflow` rule specifies if and when scrollbars should be displayed.
The `overflow` style specifies if and when scrollbars should be displayed.
## Syntax

6
docs/styles/padding.md
View File

@@ -1,6 +1,6 @@
# Padding
The `padding` rule specifies spacing around the content of a widget.
The `padding` style specifies spacing around the content of a widget.
## Syntax
@@ -27,7 +27,7 @@ The values of the [`<integer>`](../../css_types/integer) determine how much spac
!!! tip
To remember the order of the edges affected by the rule `padding` when it has 4 values, think of a clock.
Its hand starts at the top and the goes clockwise: top, right, bottom, left.
Its hand starts at the top and then goes clockwise: top, right, bottom, left.
Alternatively, padding can be set for each edge individually through the rules `padding-top`, `padding-right`, `padding-bottom`, and `padding-left`, respectively.
@@ -96,7 +96,7 @@ padding-left: 4;
## Python
In Python, you cannot set any of the individual `padding` rules `padding-top`, `padding-right`, `padding-bottom`, and `padding-left`.
In Python, you cannot set any of the individual `padding` styles `padding-top`, `padding-right`, `padding-bottom`, and `padding-left`.
However, you _can_ set padding to a single integer, a tuple of 2 integers, or a tuple of 4 integers:

6
docs/styles/scrollbar_colors/index.md
View File

@@ -1,9 +1,9 @@
# Scrollbar colors
There are a number of rules to set the colors used in Textual scrollbars.
There are a number of styles to set the colors used in Textual scrollbars.
You won't typically need to do this, as the default themes have carefully chosen colors, but you can if you want to.
| Rule | Applies to |
| Style | Applies to |
|-------------------------------------------------------------------|----------------------------------------------------------|
| [`scrollbar-background`](./scrollbar_background.md) | Scrollbar background. |
| [`scrollbar-background-active`](./scrollbar_background_active.md) | Scrollbar background when the thumb is being dragged. |
@@ -35,7 +35,7 @@ Visit each style's reference page to learn more about how the values are used.
## Example
This example shows two planels that contain oversized text.
This example shows two panels that contain oversized text.
The right panel sets `scrollbar-background`, `scrollbar-color`, and `scrollbar-corner-color`, and the left panel shows the default colors for comparison.
=== "Output"

2
docs/styles/scrollbar_colors/scrollbar_background.md
View File

@@ -1,6 +1,6 @@
# Scrollbar-background
The `scrollbar-background` sets the background color of the scrollbar.
The `scrollbar-background` style sets the background color of the scrollbar.
## Syntax
--8<-- "docs/snippets/syntax_block_start.md"

2
docs/styles/scrollbar_colors/scrollbar_background_active.md
View File

@@ -1,6 +1,6 @@
# Scrollbar-background-active
The `scrollbar-background-active` sets the background color of the scrollbar when the thumb is being dragged.
The `scrollbar-background-active` style sets the background color of the scrollbar when the thumb is being dragged.
## Syntax

2
docs/styles/scrollbar_colors/scrollbar_background_hover.md
View File

@@ -1,6 +1,6 @@
# Scrollbar-background-hover
The `scrollbar-background-hover` sets the background color of the scrollbar when the cursor is over it.
The `scrollbar-background-hover` style sets the background color of the scrollbar when the cursor is over it.
## Syntax

2
docs/styles/scrollbar_colors/scrollbar_color.md
View File

@@ -1,6 +1,6 @@
# Scrollbar-color
The `scrollbar-color` sets the color of the scrollbar.
The `scrollbar-color` style sets the color of the scrollbar.
## Syntax

2
docs/styles/scrollbar_colors/scrollbar_color_active.md
View File

@@ -1,6 +1,6 @@
# Scrollbar-color-active
The `scrollbar-color-active` sets the color of the scrollbar when the thumb is being dragged.
The `scrollbar-color-active` style sets the color of the scrollbar when the thumb is being dragged.
## Syntax

2
docs/styles/scrollbar_colors/scrollbar_color_hover.md
View File

@@ -1,6 +1,6 @@
# Scrollbar-color-hover
The `scrollbar-color-hover` sets the color of the scrollbar when the cursor is over it.
The `scrollbar-color-hover` style sets the color of the scrollbar when the cursor is over it.
## Syntax

2
docs/styles/scrollbar_colors/scrollbar_corner_color.md
View File

@@ -1,6 +1,6 @@
# Scrollbar-corner-color
The `scrollbar-corner-color` sets the color of the gap between the horizontal and vertical scrollbars.
The `scrollbar-corner-color` style sets the color of the gap between the horizontal and vertical scrollbars.
## Syntax

2
docs/styles/scrollbar_gutter.md
View File

@@ -1,6 +1,6 @@
# Scrollbar-gutter
The `scrollbar-gutter` rule allows reserving space for a vertical scrollbar.
The `scrollbar-gutter` style allows reserving space for a vertical scrollbar.
## Syntax

6
docs/styles/scrollbar_size.md
View File

@@ -1,6 +1,6 @@
# Scrollbar-size
The `scrollbar-size` rule defines the width of the scrollbars.
The `scrollbar-size` style defines the width of the scrollbars.
## Syntax
@@ -12,7 +12,7 @@ scrollbar-size-horizontal: <a href="../../css_types/integer">&lt;integer&gt;</a>
scrollbar-size-vertical: <a href="../../css_types/integer">&lt;integer&gt;</a>;
--8<-- "docs/snippets/syntax_block_end.md"
The `scrollbar-size` rule takes two [`<integer>`](../css_types/integer.md) to set the horizontal and vertical scrollbar sizes, respectively.
The `scrollbar-size` style takes two [`<integer>`](../css_types/integer.md) to set the horizontal and vertical scrollbar sizes, respectively.
This customisable size is the width of the scrollbar, given that its length will always be 100% of the container.
The scrollbar widths may also be set individually with `scrollbar-size-horizontal` and `scrollbar-size-vertical`.
@@ -76,7 +76,7 @@ scrollbar-size-vertical: 4;
## Python
The rule `scrollbar-size` has no Python equivalent.
The style `scrollbar-size` has no Python equivalent.
The scrollbar sizes must be set independently:
```py

4
docs/styles/text_align.md
View File

@@ -1,6 +1,6 @@
# Text-align
The `text-align` rule sets the text alignment in a widget.
The `text-align` style sets the text alignment in a widget.
## Syntax
@@ -8,7 +8,7 @@ The `text-align` rule sets the text alignment in a widget.
text-align: <a href="../../css_types/text_align">&lt;text-align&gt;</a>;
--8<-- "docs/snippets/syntax_block_end.md"
The `text-align` rule accepts a value of the type [`<text-align>`](../css_types/text_align.md) that defines how text is aligned inside the widget.
The `text-align` style accepts a value of the type [`<text-align>`](../css_types/text_align.md) that defines how text is aligned inside the widget.
### Defaults

2
docs/styles/text_opacity.md
View File

@@ -1,6 +1,6 @@
# Text-opacity
The `text-opacity` blends the color of the content of a widget with the color of the background.
The `text-opacity` style blends the color of the content of a widget with the color of the background.
## Syntax

2
docs/styles/text_style.md
View File

@@ -35,7 +35,7 @@ Each of the three text panels has a different text style, respectively `bold`, `
### All text styles
The next example shows all different styles on their own, as well as some combinations of styles in a single widget.
The next example shows all different text styles on their own, as well as some combinations of styles in a single widget.
=== "Output"

4
docs/styles/tint.md
View File

@@ -1,6 +1,6 @@
# Tint
The `tint` rule blends a color with the whole widget.
The `tint` style blends a color with the whole widget.
## Syntax
@@ -8,7 +8,7 @@ The `tint` rule blends a color with the whole widget.
tint: <a href="../../css_types/color">&lt;color&gt;</a> [<a href="../../css_types/percentage">&lt;percentage&gt;</a>];
--8<-- "docs/snippets/syntax_block_end.md"
The tint rule blends a [`<color>`](../css_types/color.md) with the widget. The color should likely have an _alpha_ component (specified directly in the color used or by the optional [`<percentage>`](../css_types/percentage.md)), otherwise the end result will obscure the widget content.
The tint style blends a [`<color>`](../css_types/color.md) with the widget. The color should likely have an _alpha_ component (specified directly in the color used or by the optional [`<percentage>`](../css_types/percentage.md)), otherwise the end result will obscure the widget content.
## Example

6
docs/styles/visibility.md
View File

@@ -1,6 +1,6 @@
# Visibility
The `visibility` rule determines whether a widget is visible or not.
The `visibility` style determines whether a widget is visible or not.
## Syntax
@@ -32,7 +32,7 @@ This is shown in the second example below.
### Basic usage
Note that the second widget is hidden, while leaving a space where it would have been rendered.
Note that the second widget is hidden while leaving a space where it would have been rendered.
=== "Output"
@@ -53,7 +53,7 @@ Note that the second widget is hidden, while leaving a space where it would have
### Overriding container visibility
The next example shows the interaction of the `visibility` rule with invisible containers that have visible children.
The next example shows the interaction of the `visibility` style with invisible containers that have visible children.
The app below has three rows with a `Horizontal` container per row and three placeholders per row.
The containers all have a white background, and then:

2
docs/styles/width.md
View File

@@ -1,6 +1,6 @@
# Width
The `width` rule sets a widget's width.
The `width` style sets a widget's width.
## Syntax