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

Rename CSS units as CSS types.

Browse Source
This commit is contained in:
Rodrigo Girão Serrão
2022-12-21 17:32:44 +00:00
parent 52b30c8d3b
commit 74c525e56d
8 changed files with 12 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
docs/css_types/color.md Normal file
View File

@@ -0,0 +1,61 @@
# Color unit
Color units are used with rules that need to set the color of a part of a widget.
For example, the `background` rule sets the color of the background of a widget.
!!! warning
Not to be confused with the [`color`](../color.md) CSS rule to set text color.
## Syntax
--8<-- "docs/styles/snippets/color_css_syntax.md"
## Examples
```css
Widget {
background: red; /* color name */
background: #A8F; /* 3-digit hex RGB */
background: #FF00FFDD; /* 6-digit hex RGB + transparency */
background: rgb(15,200,73); /* RGB description */
background: hsl(300,20%,70%); /* HSL description */
background: $accent; /* Textual variable */
}
```
```py
# Mimicking the CSS syntax
widget.styles.background = "red"
widget.styles.background = "#A8F"
widget.styles.background = "#FF00FFDD"
widget.styles.background = "rgb(15,200,73)"
widget.styles.background = "hsl(300,20%,70%)"
widget.styles.background = "$accent"
# Using a Color object directly...
widget.styles.background = Color(16, 200, 45)
# ... which can also parse the CSS syntax
widget.styles.background = Color.parse("#A8F")
```
## Used by
- [`background`](../background.md)
- [`border`](../border.md)
- [`color`](../color.md)
- Links:
- [`link-color`](../links/link_color.md)
- [`link-background`](../links/link_background.md)
- [`link-hover-color`](../links/link_hover_color.md)
- [`link-hover-background`](../links/link_hover_background.md)
- [`outline`](../outline.md)
- Scrollbars:
- [`scrollbar-color`](../scrollbar_colors/scrollbar_color.md)
- [`scrollbar-color-hover`](../scrollbar_colors/scrollbar_color_hover.md)
- [`scrollbar-color-active`](../scrollbar_colors/scrollbar_color_active.md)
- [`scrollbar-background`](../scrollbar_colors/scrollbar_background.md)
- [`scrollbar-background-hover`](../scrollbar_colors/scrollbar_background_hover.md)
- [`scrollbar-background-active`](../scrollbar_colors/scrollbar_background_active.md)
- [`scrollbar-corner-color`](../scrollbar_colors/scrollbar_corner_color.md)
- [`tint`](../tint.md)

28
docs/css_types/fractional.md Normal file
View File

@@ -0,0 +1,28 @@
# Fractional
## Syntax
--8<-- "docs/styles/snippets/fractional_syntax.md"
!!! warning
Not to be confused with the [percentage](./percentage.md) unit nor with the [scalar](./scalar.md) unit.
## Examples
```css
Widget {
text-opacity: 0.45;
text-opacity: 45%;
}
```
```py
widget.styles.text_opacity = 0.45
widget.styles.text_opacity = "45%"
```
## Used by
- [`opacity`](../opacity.md)
- [`text-opacity`](../text_opacity.md)

12
docs/css_types/index.md Normal file
View File

@@ -0,0 +1,12 @@
# CSS Types
CSS types define the values that Textual CSS rules accept.
CSS types will be linked from within the [styles reference](../styles/index.md) in the "Formal Syntax" section of each rule.
The CSS types will be denoted by a keyword enclosed by angle brackets `<` and `>`.
For example, the style [`align-horizontal`](../styles/align.md) references the CSS type [<horizontal>](./horizontal.md):
--8<-- "docs/snippets/syntax_block_start.md"
align-horizontal: <a href="./horizontal.md">&lt;horizontal&gt;</a>
--8<-- "docs/snippets/syntax_block_end.md"

30
docs/css_types/integer.md Normal file
View File

@@ -0,0 +1,30 @@
# Integer
An integer unit.
## Syntax
Any legal integer, like `-10` or `42`.
Integer units can be negative, althought that may not make sense in some rules.
## Examples
```css
Widget {
margin: -5 10;
}
```
```py
widget.styles.offset = (-5, 10)
```
## Used by
- Grids:
- [`grid-size`](../grid/grid_size.md)
- [`grid-rows`](../grid/grid_rows.md)
- [`grid-columns`](../grid/grid_columns.md)
- [`margin`](../margin.md)
- [`padding`](../padding.md)
- [`scrollbar-size`](../scrollbar_size.md)

27
docs/css_types/percentage.md Normal file
View File

@@ -0,0 +1,27 @@
# Percentage
## Syntax
--8<-- "docs/styles/snippets/percentage_syntax.md"
!!! warning
Not to be confused with the [fractional](./fractional.md) unit nor with the [scalar](./scalar.md) unit.
## Examples
```css
Widget {
background: red 70%;
}
```
```py
widget.styles.background = "red 70%"
```
## Used by
- [`background`](../background.md)
- [`color`](../color.md)
- [`tint`](../tint.md)

123
docs/css_types/scalar.md Normal file
View File

@@ -0,0 +1,123 @@
# Scalar
A scalar unit is a numeric value with a unit, e.g., `50vh`.
Scalars are used with styles that specify lengths, like `width` and `height`.
Scalars also accept the special value `auto`.
## Syntax
--8<-- "docs/styles/snippets/scalar_syntax.md"
A complete reference table and detailed explanations follow.
You can [skip to the examples](#Examples).
| Unit symbol | Unit | Example | Description |
|-------------|-----------------|---------|-------------------------------------------------------------|
| `""` | Cell | `10` | Number of cells (rows or columns). |
| `"fr"` | Fraction | `1fr` | Specifies the proportion of space the widget should occupy. |
| `"%"` | Percent | `75%` | Length relative to the container widget. |
| `"w"` | Width | `25w` | Percentage relative to the width of the container widget. |
| `"h"` | Height | `75h` | Percentage relative to the height of the container widget. |
| `"vw"` | Viewport width | `25vw` | Percentage relative to the viewport width. |
| `"vh"` | Viewport height | `75vh` | Percentage relative to the viewport height. |
| - | Auto | `auto` | Tries to compute the optimal size to fit without scrolling. |
### Cell
The number of cells is the only unit for a scalar that is _absolute_.
This can be an integer or a float but floats are truncated to integers.
If used to specify a horizontal length, it corresponds to the number of columns.
For example, in `width: 15`, this sets the width of a widget to be equal to 15 cells, which translates to 15 columns.
If used to specify a vertical length, it corresponds to the number of lines.
For example, in `height: 10`, this sets the height of a widget to be equal to 10 cells, which translates to 10 lines.
### Fraction
The fraction scalar is used to represent proportional sizes.
For example, if two widgets are side by side and one has `width: 1fr` and the other has `width: 3fr`, the second one will be three times as wide as the first one.
### Percent
The percent scalar is used to specify a total length relative to the space made available by the container widget.
If used to specify a horizontal length, it will be relative to the width of the container.
For example, `width: 50%` sets the width of a widget to 50% of the width of its container.
If used to specify a vertical length, it will be relative to the height of the container.
For example, `height: 50%` sets the height of a widget to 50% of the height of its container.
### Width
The width scalar is similar to the percent scalar, except it sets the percentage to be relative to the width of the container.
For example, `width: 25w` sets the width of a widget to 25% of the width of its container and `height: 25w` sets the height of a widget to 25% of the width of its container.
So, if the container has a width of 100 cells, the width and the height of the child widget will be of 25 cells.
### Height
The height scalar is similar to the percent scalar, except it sets the percentage to be relative to the height of the container.
For example, `height: 75h` sets the height of a widget to 75% of the height of its container and `width: 75h` sets the width of a widget to 75% of the height of its container.
So, if the container has a height of 100 cells, the width and the height of the child widget will be of 75 cells.
### Viewport width
This is the same as the [width scalar](#Width), except that it is relative to the width of the viewport instead of the width of the immediate container.
For example, `width: 25vw` will try to set the width of a widget to be 25% of the viewport width, regardless of the widths of its containers.
### Viewport height
This is the same as the [height scalar](#Height), except that it is relative to the height of the viewport instead of the height of the immediate container.
For example, `height: 75vh` will try to set the height of a widget to be 75% of the viewport height, regardless of the height of its containers.
### Auto
This special value will try to calculate the optimal size to fit the contents of the widget without scrolling.
For example, if its container is big enough, a label with `width: auto` will be just as wide as its text.
## Examples
```css
Widget {
width: 16;
width: 1fr;
width: 50%;
width: 25w;
width: 75h;
width: 25vw;
width: 75vh;
width: auto;
}
```
```py
widget.styles.width = 16 # Cell scalar can be an int or a float
widget.styles.width = "1fr"
widget.styles.width = "50%"
widget.styles.width = "25w"
widget.styles.width = "75h"
widget.styles.width = "25vw"
widget.styles.width = "75vh"
widget.styles.width = "auto"
```
## Used by
- Grids:
- [`grid-rows`](../grid/grid_rows.md)
- [`grid-columns`](../grid/grid_columns.md)
- [`grid-gutter`](../grid/grid_gutter.md)
- [`height`](../height.md)
- [`max-height`](../max_height.md)
- [`max-width`](../max_width.md)
- [`min-height`](../min_height.md)
- [`min-width`](../min_width.md)
- [`offset`](../offset.md)
- [`width`](../width.md)

51
docs/css_types/text_style.md Normal file
View File

@@ -0,0 +1,51 @@
# Text style
The text style unit is a combination of any of the legal text style values in a space-separated list.
!!! warning
Not to be confused with the [`text-style`](../text_style.md) CSS rule that sets the style of text in a widget.
## Syntax
--8<-- "docs/styles/snippets/text_style_syntax.md"
## Examples
!!! note
The `text-style` CSS rule and the text style unit are closely related but they are not the same thing.
Here, we show examples of the text style unit, which are relevant for [all CSS rules](#used-by) that use the text style unit.
```css
Widget {
text-style: bold;
text-style: italic;
text-style: reverse;
text-style: underline;
text-style: strike;
/* When the unit expected is a style, you can specify multiple values */
text-style: strike bold italic reverse;
text-style: bold underline italic;
}
```
```py
widget.styles.text_style = "bold"
widget.styles.text_style = "italic"
widget.styles.text_style = "reverse"
widget.styles.text_style = "underline"
widget.styles.text_style = "strike"
# Multiple values can be specified
widget.styles.text_style = "strike bold italic reverse"
widget.styles.text_style = "bold underline italic"
```
## Used by
- Links:
- [`link-style`](../links/link_style.md)
- [`link-hover-style`](../links/link_hover_style.md)
- [`text-style`](../text_style.md)