From 73bdd7ed43f44f54311ff803f4ade8dff1aac767 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rodrigo=20Gir=C3=A3o=20Serr=C3=A3o?= <5621605+rodrigogiraoserrao@users.noreply.github.com> Date: Mon, 19 Dec 2022 16:11:42 +0000 Subject: [PATCH] Complete reference for scalar unit. --- docs/styles/css_units/scalar.md | 122 ++++++++++++++++++++++++++ docs/styles/snippets/scalar_syntax.md | 8 ++ 2 files changed, 130 insertions(+) create mode 100644 docs/styles/snippets/scalar_syntax.md diff --git a/docs/styles/css_units/scalar.md b/docs/styles/css_units/scalar.md index 7b3723c22..3a50d8397 100644 --- a/docs/styles/css_units/scalar.md +++ b/docs/styles/css_units/scalar.md @@ -1 +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) diff --git a/docs/styles/snippets/scalar_syntax.md b/docs/styles/snippets/scalar_syntax.md new file mode 100644 index 000000000..9581e271b --- /dev/null +++ b/docs/styles/snippets/scalar_syntax.md @@ -0,0 +1,8 @@ +A scalar can be any of the following: + + - a fixed number of cells (e.g., `10`); + - a fractional proportion relative to the sizes of the other widgets (e.g., `1fr`); + - a percentage relative to the container widget (e.g., `50%`); + - a percentage relative to the container width/height (e.g., `25w`/`75h`); + - a percentage relative to the viewport width/height (e.g., `25vw`/`75vh`); or + - the special value `auto` to compute the optimal size to fit without scrolling.