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

Refactor units to types.

Browse Source
This commit is contained in:
Rodrigo Girão Serrão
2022-12-21 19:41:39 +00:00
parent cf6cd06a33
commit 175f6b65cb
5 changed files with 125 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
docs/css_types/color.md
View File

@@ -1,40 +1,43 @@
# Color unit
# <color>
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.
The `<color>` CSS type represents a color.
!!! warning
Not to be confused with the [`color`](../color.md) CSS rule to set text color.
Not to be confused with the [`color`](../styles/color.md) CSS rule to set text color.
## Syntax
--8<-- "docs/snippets/color_css_syntax.md"
--8<-- "docs/snippets/type_syntax/color.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 */
### CSS
```sass
* {
rule: red; /* color name */
rule: #A8F; /* 3-digit hex RGB */
rule: #FF00FFDD; /* 6-digit hex RGB + transparency */
rule: rgb(15,200,73); /* RGB description */
rule: hsl(300,20%,70%); /* HSL description */
rule: $accent; /* Textual variable */
}
```
### Python
```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"
color = "red"
color = "#A8F"
color = "#FF00FFDD"
color = "rgb(15,200,73)"
color = "hsl(300,20%,70%)"
color = "$accent"
# Using a Color object directly...
widget.styles.background = Color(16, 200, 45)
color = Color(16, 200, 45)
# ... which can also parse the CSS syntax
widget.styles.background = Color.parse("#A8F")
color = Color.parse("#A8F")
```

25
docs/css_types/integer.md
View File

@@ -1,20 +1,31 @@
# Integer
# &lt;integer&gt;
An integer unit.
The `<integer>` CSS type represents an integer number and can be positive or negative.
!!! note
Some CSS rules may expect an `<integer>` within certain bounds. If that is the case, it will be noted in that rule.
## 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;
### CSS
```sass
* {
rule: -5;
rule: 10;
}
```
### Python
In Python, a rule that expects a CSS type `<integer>` will expect a value of the type `int`:
```py
widget.styles.offset = (-5, 10)
integer = -5
integer = 10
```

26
docs/css_types/percentage.md
View File

@@ -1,21 +1,29 @@
# Percentage
# &lt;percentage&gt;
## Syntax
--8<-- "docs/snippets/percentage_syntax.md"
The `<percentage>` CSS type represents a percentage value.
It is often used to represent values that are relative to the parent's values.
!!! warning
Not to be confused with the [fractional](./fractional.md) unit nor with the [scalar](./scalar.md) unit.
Not to be confused with the [`<scalar>`](./scalar.md) type.
## Syntax
--8<-- "docs/snippets/type_syntax/percentage.md"
## Examples
```css
Widget {
background: red 70%;
### CSS
```sass
* {
rule: 70%; /* Integer followed by % */
rule: -3.5%; /* The number can be negative/decimal */
}
```
### Python
```py
widget.styles.background = "red 70%"
percentage = "70%"
```

67
docs/css_types/scalar.md
View File

@@ -1,16 +1,19 @@
# Scalar
# &lt;scalar&gt;
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`.
The `<scalar>` CSS type represents a length.
It can be a [`<number>`](./number.md) and a unit, or the special value `auto`.
It is used to represent lengths, for example in the [`width`](../styles/width.md) and [`height`](../styles/height.md) rules.
Scalars also accept the special value `auto`.
!!! warning
Not to be confused with the [`<number>`](./number.md) or [`<percentage>`](./percentage.md) types.
## Syntax
--8<-- "docs/snippets/scalar_syntax.md"
--8<-- "docs/snippets/type_syntax/scalar.md"
A complete reference table and detailed explanations follow.
You can [skip to the examples](#Examples).
You can [skip to the examples](#examples).
| Unit symbol | Unit | Example | Description |
|-------------|-----------------|---------|-------------------------------------------------------------|
@@ -36,13 +39,13 @@ For example, in `height: 10`, this sets the height of a widget to be equal to 10
### Fraction
The fraction scalar is used to represent proportional sizes.
The unit fraction 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.
The percent unit matches a [`<percentage>`](./percentage.md) and 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.
@@ -52,27 +55,27 @@ For example, `height: 50%` sets the height of a widget to 50% of the height of i
### Width
The width scalar is similar to the percent scalar, except it sets the percentage to be relative to the width of the container.
The width unit is similar to the percent unit, 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.
The height unit is similar to the percent unit, 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.
This is the same as the [width unit](#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.
This is the same as the [height unit](#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.
@@ -84,26 +87,30 @@ For example, if its container is big enough, a label with `width: auto` will be
## Examples
```css
Widget {
width: 16;
width: 1fr;
width: 50%;
width: 25w;
width: 75h;
width: 25vw;
width: 75vh;
width: auto;
### CSS
```sass
* {
rule: 16; /* 16 cells */
rule: 1fr; /* proportional size of 1 */
rule: 50%; /* 50% of the same dimension of the parent */
rule: 25w; /* 25% of the width of the parent */
rule: 75h; /* 75% of the height of the parent */
rule: 25vw; /* 25% of the viewport width */
rule: 75vh; /* 75% of the viewport height */
rule: auto; /* special value */
}
```
### Python
```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"
scalar = 16 # Cell unit can be specified with an int/float
scalar = "1fr" # proportional size of 1
scalar = "50%" # 50% of the same dimension of the parent
scalar = "25w" # 25% of the width of the parent
scalar = "75h" # 75% of the height of the parent
scalar = "25vw" # 25% of the viewport width
scalar = "75vh" # 75% of the viewport height
scalar = "auto" # special value
```

55
docs/css_types/text_style.md
View File

@@ -1,6 +1,6 @@
# Text style
# &lt;text-style&gt;
The text style unit is a combination of any of the legal text style values in a space-separated list.
The `<text-style>` CSS type represents styles that can be applied to text.
!!! warning
@@ -8,37 +8,40 @@ The text style unit is a combination of any of the legal text style values in a
## Syntax
--8<-- "docs/snippets/text_style_syntax.md"
--8<-- "docs/snippets/type_syntax/text_style.md"
## Examples
!!! note
### CSS
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.
```sass
* {
/* You can specify any value by itself. */
rule: bold;
rule: italic;
rule: none;
rule: reverse;
rule: strike;
rule: underline;
```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;
/* You can also combine multiple values. */
rule: strike bold italic reverse;
rule: 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"
### Python
# Multiple values can be specified
widget.styles.text_style = "strike bold italic reverse"
widget.styles.text_style = "bold underline italic"
```py
# You can specify any value by itself
text_style = "bold"
text_style = "italic"
text_style = "none"
text_style = "reverse"
text_style = "strike"
text_style = "underline"
# You can also combine multiple values
text_style = "strike bold italic reverse"
text_style = "bold underline italic"
```