From 0fe4b970f097a3796c858667c5a3fa5b9946ccce Mon Sep 17 00:00:00 2001 From: Will McGugan Date: Sun, 31 Jul 2022 08:47:34 +0100 Subject: [PATCH] more docs --- docs/examples/styles/border.py | 3 +- docs/examples/styles/box_sizing.py | 32 +++++++++++++++++ docs/examples/styles/outline.py | 31 ++++++++++++++++ docs/styles/border.md | 55 ++++++++++++++++++++++++++++ docs/styles/box_sizing.md | 42 ++++++++++++++++++++++ docs/styles/color.md | 6 ++-- docs/styles/height.md | 2 +- docs/styles/margin.md | 8 +++-- docs/styles/outline.md | 57 ++++++++++++++++++++++++++++++ docs/styles/padding.md | 8 +++-- mkdocs.yml | 3 ++ 11 files changed, 235 insertions(+), 12 deletions(-) create mode 100644 docs/examples/styles/box_sizing.py create mode 100644 docs/examples/styles/outline.py create mode 100644 docs/styles/border.md create mode 100644 docs/styles/box_sizing.md create mode 100644 docs/styles/outline.md diff --git a/docs/examples/styles/border.py b/docs/examples/styles/border.py index 9c36c6d45..311dab510 100644 --- a/docs/examples/styles/border.py +++ b/docs/examples/styles/border.py @@ -8,7 +8,7 @@ class BorderApp(App): background: white; } Screen > Static { - height:5; + height: 5; content-align: center middle; color: white; margin: 1; @@ -23,7 +23,6 @@ class BorderApp(App): background: green 20%; color: green; border: dashed green; - } #static3 { background: blue 20%; diff --git a/docs/examples/styles/box_sizing.py b/docs/examples/styles/box_sizing.py new file mode 100644 index 000000000..3b97601b5 --- /dev/null +++ b/docs/examples/styles/box_sizing.py @@ -0,0 +1,32 @@ +from textual.app import App +from textual.widgets import Static + + +class BoxSizingApp(App): + CSS = """ + Screen { + background: white; + color: black; + } + Static { + background: blue 20%; + height: 5; + margin: 2; + padding: 1; + border: wide black; + } + #static1 { + box-sizing: border-box; + } + #static2 { + box-sizing: content-box; + } + + """ + + def compose(self): + yield Static("Hello, World!", id="static1") + yield Static("Hello, World!", id="static2") + + +app = BoxSizingApp() diff --git a/docs/examples/styles/outline.py b/docs/examples/styles/outline.py new file mode 100644 index 000000000..0fc1a476c --- /dev/null +++ b/docs/examples/styles/outline.py @@ -0,0 +1,31 @@ +from textual.app import App +from textual.widgets import Static + + +TEXT = """I must not fear. +Fear is the mind-killer. +Fear is the little-death that brings total obliteration. +I will face my fear. +I will permit it to pass over me and through me. +And when it has gone past, I will turn the inner eye to see its path. +Where the fear has gone there will be nothing. Only I will remain.""" + + +class OutlineApp(App): + CSS = """ + Screen { + background: white; + color: black; + } + Static { + margin: 4 8; + background: green 20%; + outline: wide green; + } + """ + + def compose(self): + yield Static(TEXT) + + +app = OutlineApp() diff --git a/docs/styles/border.md b/docs/styles/border.md new file mode 100644 index 000000000..9ca540c5f --- /dev/null +++ b/docs/styles/border.md @@ -0,0 +1,55 @@ +# Border + +The `border` rule enables the drawing of a box around a widget. A border is set with a border style (see below) followed by a color. + +- `"ascii"` +- `"round"` +- `"solid"` +- `"double"` +- `"dashed"` +- `"heavy"` +- `"inner"` +- `"outer"` +- `"hkey"` +- `"vkey"` +- `"tall"` +- `"wide"` + +For examples `heavy white` would display a heavy white line around a widget. + +Borders may also be set individually with the `border-top`, `border-right`, `border-bottom` and `border-left` rules. + +## Example + +This examples shows three widgets with different border styles. + +=== "border.py" + + ```python + --8<-- "docs/examples/styles/border.py" + ``` + +=== "Output" + + ```{.textual path="docs/examples/styles/border.py"} + ``` + +## CSS + +```sass +/* Set a heavy white border */ +border: heavy white; + +/* set a red border on the left */ +border-left: outer red; +``` + +## Python + +```python +# Set a heavy white border +widget.border = ("heavy", "white) + +# Set a red border on the left +widget.border_left = ("outer", "red) +``` diff --git a/docs/styles/box_sizing.md b/docs/styles/box_sizing.md new file mode 100644 index 000000000..d0d5fdce2 --- /dev/null +++ b/docs/styles/box_sizing.md @@ -0,0 +1,42 @@ +# Box-sizing + +The `box-sizing` rule impacts how `width` and `height` rules are translated in to screen dimensions, when combined with `padding` and `border`. + +The default value is `border-box` which means that padding and border are included in in the width and height. This setting means that if you add padding and/or border the widget will not change in size, but you will have less space for content. + +You can set `box-sizing` to `content-box` which tells Textual that padding and border should increase the size of the widget, leaving the content area unaffected. + +## Example + +Both widgets in this example have the same height (5). The top widget has `box-sizing: border-box` which means that padding and border reduces the space for content. The bottom widget has `box-sizing: content-box` which increases the size of the widget to compensate for padding and border. + +=== "box_sizing.py" + + ```python + --8<-- "docs/examples/styles/box_sizing.py" + ``` + +=== "Output" + + ```{.textual path="docs/examples/styles/box_sizing.py"} + ``` + +## CSS + +```sass +/* Set box sizing to border-box (default) */ +box-sizing: border-box; + +/* Set box sizing to content-box */ +box-sizing: content-box; +``` + +## Python + +```python +# Set box sizing to border-box (default) +widget.box_sizing = "border-box" + +# Set box sizing to content-box +widget.box_sizing = "content-box" +``` diff --git a/docs/styles/color.md b/docs/styles/color.md index 51806d857..053dcd53e 100644 --- a/docs/styles/color.md +++ b/docs/styles/color.md @@ -16,10 +16,10 @@ The `color` rule sets the text color of a Widget. ## CSS ```sass -/* Blue background */ +/* Blue text */ color: blue; -/* 20% red backround */ +/* 20% red text */ color: red 20%; /* RGB color */ @@ -31,7 +31,7 @@ color: rgb(100,120,200); You can use the same syntax as CSS, or explicitly set a Color object. ```python -# Set blue background +# Set blue text widget.styles.color = "blue" from textual.color import Color diff --git a/docs/styles/height.md b/docs/styles/height.md index 12aefac09..b7c6b664d 100644 --- a/docs/styles/height.md +++ b/docs/styles/height.md @@ -1,6 +1,6 @@ # Height -The `height` style sets a widget's height. By default, it sets the width of the content area, but if `box-sizing` is set to `border-box` it sets the width of the border area. +The `height` style sets a widget's height. By default, it sets the height of the content area, but if `box-sizing` is set to `border-box` it sets the height of the border area. ## Example diff --git a/docs/styles/margin.md b/docs/styles/margin.md index a0cc4d443..2bd01ba68 100644 --- a/docs/styles/margin.md +++ b/docs/styles/margin.md @@ -2,9 +2,11 @@ The `margin` rule adds space around the entire widget. -- `1` Sets a margin of 1 around all 4 edges -- `1 2` Sets a margin of 1 on the top and bottom edges, and a margin of 2 on the left and right edges -- `1 2 3 4` Sets a margin of one on the top edge, 2 on the right, 3 on the bottom, and 4 on the left. +- `margin: 1;` Sets a margin of 1 around all 4 edges +- `margin: 1 2;` Sets a margin of 1 on the top and bottom edges, and a margin of 2 on the left and right edges +- `margin: 1 2 3 4;` Sets a margin of one on the top edge, 2 on the right, 3 on the bottom, and 4 on the left. + +Margin may also be set individually, following the same pattern as above, by setting `margin-top`, `margin-right`, `margin-bottom`, or `margin-left`. ## Example diff --git a/docs/styles/outline.md b/docs/styles/outline.md new file mode 100644 index 000000000..d475b9519 --- /dev/null +++ b/docs/styles/outline.md @@ -0,0 +1,57 @@ +# Outline + +The `outline` rule enables the drawing of a box around a widget. Similar to `border`, but unlike border, outline will draw over the content area. This rule can be useful for emphasis if you want to display a outline for a brief time to draw the user's attention to it. + +An outline is set with a border style (see below) followed by a color. + +- `"ascii"` +- `"round"` +- `"solid"` +- `"double"` +- `"dashed"` +- `"heavy"` +- `"inner"` +- `"outer"` +- `"hkey"` +- `"vkey"` +- `"tall"` +- `"wide"` + +For examples `heavy white` would display a heavy white line around a widget. + +Outlines may also be set individually with the `outline-top`, `outline-right`, `outline-bottom` and `outline-left` rules. + +## Example + +This examples shows a widget with an outline. Note how the outline occludes the text area. + +=== "outline.py" + + ```python + --8<-- "docs/examples/styles/outline.py" + ``` + +=== "Output" + + ```{.textual path="docs/examples/styles/outline.py"} + ``` + +## CSS + +```sass +/* Set a heavy white outline */ +outline: heavy white; + +/* set a red outline on the left */ +outline-left: outer red; +``` + +## Python + +```python +# Set a heavy white outline +widget.outline = ("heavy", "white) + +# Set a red outline on the left +widget.outline_left = ("outer", "red) +``` diff --git a/docs/styles/padding.md b/docs/styles/padding.md index 0c8272fbc..75207b62a 100644 --- a/docs/styles/padding.md +++ b/docs/styles/padding.md @@ -2,9 +2,11 @@ The padding rule adds space around the content of a widget. You can specify padding with 1, 2 or 4 numbers. -- `1` Sets a padding of 1 around all 4 edges -- `1 2` Sets a padding of 1 on the top and bottom edges, and a padding of two on the left and right edges -- `1 2 3 4` Sets a padding of one on the top edge, 2 on the right, 3 on the bottom, and 4 on the left. +- `padding: 1;` Sets a padding of 1 around all 4 edges +- `padding: 1 2;` Sets a padding of 1 on the top and bottom edges, and a padding of two on the left and right edges +- `padding: 1 2 3 4;` Sets a padding of one on the top edge, 2 on the right, 3 on the bottom, and 4 on the left. + +Padding may also be set individually, following the same pattern as above, by setting `padding-top`, `padding-right`, `padding-bottom`, or `padding-left`. ## Example diff --git a/mkdocs.yml b/mkdocs.yml index 20713abbf..e737b699c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -12,6 +12,8 @@ nav: - "events/resize.md" - Styles: - "styles/background.md" + - "styles/border.md" + - "styles/box_sizing.md" - "styles/color.md" - "styles/display.md" - "styles/min_height.md" @@ -20,6 +22,7 @@ nav: - "styles/max_width.md" - "styles/height.md" - "styles/margin.md" + - "styles/outline.md" - "styles/overflow.md" - "styles/padding.md" - "styles/text_style.md"