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

Merge pull request #713 from Textualize/docs-values

Browse Source 
Values sections for CSS properties, some rewordings
This commit is contained in:
Will McGugan
2022-08-30 12:59:31 +01:00
committed by GitHub
parent 9fff9dbcb9 79ccbae06e
commit 1907b3fd88
13 changed files with 122 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/styles/background.md
View File

@@ -5,7 +5,7 @@ The `background` rule sets the background color of the widget.
## Syntax ## Syntax
``` ```
background: COLOR [PERCENTAGE] background: <COLOR> [<PERCENTAGE>];
``` ```
## Example ## Example

32
docs/styles/border.md
View File

@@ -2,8 +2,22 @@
The `border` rule enables the drawing of a box around a widget. A border is set with a border value (see below) followed by a color. The `border` rule enables the drawing of a box around a widget. A border is set with a border value (see below) followed by a color.
| Border value | Explanation | 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.
| ------------ |---------------------------------------------------------|
## Syntax
```
border: [<COLOR>] [<BORDER VALUE>];
border-top: [<COLOR>] [<BORDER VALUE>];
border-right: [<COLOR>] [<BORDER VALUE>];
border-bottom: [<COLOR>] [<BORDER VALUE>];
border-left: [<COLOR>] [<BORDER VALUE>];
```
### Values
| Border value | Description |
|--------------|---------------------------------------------------------|
| `"ascii"` | A border with plus, hyphen, and vertical bar | | `"ascii"` | A border with plus, hyphen, and vertical bar |
| `"blank"` | A blank border (reserves space for a border) | | `"blank"` | A blank border (reserves space for a border) |
| `"dashed"` | Dashed line border | | `"dashed"` | Dashed line border |
@@ -20,19 +34,7 @@ The `border` rule enables the drawing of a box around a widget. A border is set
| `"vkey"` | Vertical key-line border | | `"vkey"` | Vertical key-line border |
| `"wide"` | Solid border with additional space left and right | | `"wide"` | Solid border with additional space left and right |
For example `heavy white` would display a heavy white line around a widget. For example, `heavy white` would display a heavy white line around a widget.
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.
## Syntax
```
border: [<COLOR>] [<BORDER VALUE>];
border-top: [<COLOR>] [<BORDER VALUE>];
border-right: [<COLOR>] [<BORDER VALUE>];
border-bottom: [<COLOR>] [<BORDER VALUE>];
border-left: [<COLOR>] [<BORDER VALUE>];
```
## Border command ## Border command

17
docs/styles/box_sizing.md
View File

@@ -1,10 +1,6 @@
# Box-sizing # 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 `box-sizing` property determines how the width and height of a widget are calculated.
The default value is `border-box` which means that padding and border are included 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.
## Syntax ## Syntax
@@ -12,9 +8,18 @@ You can set `box-sizing` to `content-box` which tells Textual that padding and b
box-sizing: [border-box|content-box]; box-sizing: [border-box|content-box];
``` ```
### Values
| Values | Description |
|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `border-box` (default) | Padding and border are included in the width and height. If you add padding and/or border the widget will not change in size, but you will have less space for content. |
| `content-box` | Padding and border will increase the size of the widget, leaving the content area unaffected. |
## Example ## 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. 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" === "box_sizing.py"

9
docs/styles/display.md
View File

@@ -1,6 +1,6 @@
# Display # Display
The `display` property defines if a Widget is displayed or not. The default value is `"block"` which will display the widget as normal. Setting the property to `"none"` will effectively make it invisible. The `display` property defines whether a widget is displayed or not.
## Syntax ## Syntax
@@ -8,6 +8,13 @@ The `display` property defines if a Widget is displayed or not. The default valu
display: [none|block]; display: [none|block];
``` ```
### Values
| Value | Description |
|-------------------|---------------------------------------------------------------------------|
| `block` (default) | Display the widget as normal |
| `none` | The widget not be displayed, and space will no longer be reserved for it. |
## Example ## Example
Note that the second widget is hidden by adding the "hidden" class which sets the display style to None. Note that the second widget is hidden by adding the "hidden" class which sets the display style to None.

4
docs/styles/margin.md
View File

@@ -2,8 +2,8 @@
The `margin` rule adds space around the entire widget. Margin may be specified with 1, 2 or 4 values. The `margin` rule adds space around the entire widget. Margin may be specified with 1, 2 or 4 values.
| example | | | Example | Description |
| ------------------ | ------------------------------------------------------------------- | |--------------------|---------------------------------------------------------------------|
| `margin: 1;` | A single value sets a margin of 1 around all 4 edges | | `margin: 1;` | A single value sets a margin of 1 around all 4 edges |
| `margin: 1 2;` | Two values sets the margin for the top/bottom and left/right edges | | `margin: 1 2;` | Two values sets the margin for the top/bottom and left/right edges |
| `margin: 1 2 3 4;` | Four values sets top, right, bottom, and left margins independently | | `margin: 1 2 3 4;` | Four values sets top, right, bottom, and left margins independently |

39
docs/styles/outline.md
View File

@@ -1,11 +1,28 @@
# Outline # 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. 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 an outline for a brief time to
draw the user's attention to it.
An outline is set with a border value (see below) followed by a color. An outline is set with a border value (see table below) followed by a color.
| Border value | Explanation | Outlines may also be set individually with the `outline-top`, `outline-right`, `outline-bottom` and `outline-left`
| ------------ | ------------------------------------------------------- | rules.
## Syntax
```
outline: [<COLOR>] [<BORDER VALUE>];
outline-top: [<COLOR>] [<BORDER VALUE>];
outline-right: [<COLOR>] [<BORDER VALUE>];
outline-bottom: [<COLOR>] [<BORDER VALUE>];
outline-left: [<COLOR>] [<BORDER VALUE>];
```
### Values
| Border value | Description |
|--------------|---------------------------------------------------------|
| `"ascii"` | A border with plus, hyphen, and vertical bar | | `"ascii"` | A border with plus, hyphen, and vertical bar |
| `"blank"` | A blank border (reserves space for a border) | | `"blank"` | A blank border (reserves space for a border) |
| `"dashed"` | Dashed line border | | `"dashed"` | Dashed line border |
@@ -22,19 +39,7 @@ An outline is set with a border value (see below) followed by a color.
| `"vkey"` | Vertical key-line border | | `"vkey"` | Vertical key-line border |
| `"wide"` | Solid border with additional space left and right | | `"wide"` | Solid border with additional space left and right |
For example `heavy white` would display a heavy white line around a widget. For example, `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.
## Syntax
```
outline: [<COLOR>] [<BORDER VALUE>];
outline-top: [<COLOR>] [<BORDER VALUE>];
outline-right: [<COLOR>] [<BORDER VALUE>];
outline-bottom: [<COLOR>] [<BORDER VALUE>];
outline-left: [<COLOR>] [<BORDER VALUE>];
```
## Example ## Example

20
docs/styles/overflow.md
View File

@@ -1,12 +1,7 @@
# Overflow # Overflow
The `overflow` rule specifies if and when scrollbars should be displayed on the `x` and `y` axis. The rule takes two overflow values; one for the horizontal bar (x axis), followed by the vertical bar (y-axis). The `overflow` rule specifies if and when scrollbars should be displayed on the `x` and `y` axis.
The rule takes two overflow values; one for the horizontal bar (x-axis), followed by the vertical bar (y-axis).
| Overflow value | Effect |
| -------------- | ------------------------------------------------------------------------- |
| `"auto"` | Automatically show the scrollbar if the content doesn't fit (the default) |
| `"hidden"` | Never show the scrollbar |
| `"scroll"` | Always show the scrollbar |
The default value for overflow is `"auto auto"` which will show scrollbars automatically for both scrollbars if content doesn't fit within container. The default value for overflow is `"auto auto"` which will show scrollbars automatically for both scrollbars if content doesn't fit within container.
@@ -20,11 +15,20 @@ overflow-x: [auto|hidden|scroll];
overflow-y: [auto|hidden|scroll]; overflow-y: [auto|hidden|scroll];
``` ```
### Values
| Value | Description |
|------------------|---------------------------------------------------------|
| `auto` (default) | Automatically show the scrollbar if content doesn't fit |
| `hidden` | Never show the scrollbar |
| `scroll` | Always show the scrollbar |
## Example ## Example
Here we split the screen in to left and right sections, each with three vertically scrolling widgets that do not fit in to the height of the terminal. Here we split the screen in to left and right sections, each with three vertically scrolling widgets that do not fit in to the height of the terminal.
The left side has `overflow-y: auto` (the default) and will automatically show a scrollbar. The right side has `overflow-y: hidden` which will prevent a scrollbar from being shown. The left side has `overflow-y: auto` (the default) and will automatically show a scrollbar.
The right side has `overflow-y: hidden` which will prevent a scrollbar from being shown.
=== "overflow.py" === "overflow.py"

5
docs/styles/scrollbar.md
View File

@@ -1,9 +1,10 @@
# Scrollbar colors # Scrollbar colors
There are a number of rules 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. There are a number of rules 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 | Color | | Rule | Color |
| ----------------------------- | ------------------------------------------------------- | |-------------------------------|---------------------------------------------------------|
| `scrollbar-color` | Scrollbar "thumb" (movable part) | | `scrollbar-color` | Scrollbar "thumb" (movable part) |
| `scrollbar-color-hover` | Scrollbar thumb when the mouse is hovering over it | | `scrollbar-color-hover` | Scrollbar thumb when the mouse is hovering over it |
| `scrollbar-color-active` | Scrollbar thumb when it is active (being dragged) | | `scrollbar-color-active` | Scrollbar thumb when it is active (being dragged) |

25
docs/styles/text_style.md
View File

@@ -1,23 +1,26 @@
# Text-style # Text-style
The `text-style` rule enables a number of different ways of displaying text. The value may be set to any of the following: The `text-style` rule enables a number of different ways of displaying text.
| Style | Effect | Text styles may be set in combination.
| ------------- | -------------------------------------------------------------- | For example `bold underline` or `reverse underline strike`.
| `"bold"` | **bold text** |
| `"italic"` | _italic text_ |
| `"reverse"` | reverse video text (foreground and background colors reversed) |
| `"underline"` | <u>underline text</u> |
| `"strike"` | <s>strikethrough text</s> |
Text styles may be set in combination. For example "bold underline" or "reverse underline strike".
## Syntax ## Syntax
``` ```
text-style: <TEXT STYLE> ... text-style: <TEXT STYLE> ...;
``` ```
### Values
| Value | Description |
|-------------|----------------------------------------------------------------|
| `bold` | **bold text** |
| `italic` | _italic text_ |
| `reverse` | reverse video text (foreground and background colors reversed) |
| `underline` | <u>underline text</u> |
| `strike` | <s>strikethrough text</s> |
## Example ## Example
Each of the three text panels has a different text style. Each of the three text panels has a different text style.

11
docs/styles/visibility.md
View File

@@ -1,13 +1,20 @@
# Visibility # Visibility
The `visibility` rule may be used to make a widget invisible while still reserving spacing for it. The default value is `"visible"` which will cause the Widget to be displayed as normal. Setting the value to `"hidden"` will cause the Widget to become invisible. The `visibility` rule may be used to make a widget invisible while still reserving spacing for it.
## Syntax ## Syntax
``` ```
visibility: [hidden|visible]; visibility: [visible|hidden];
``` ```
### Values
| Value | Description |
|---------------------|----------------------------------------|
| `visible` (default) | The widget will be displayed as normal |
| `hidden` | The widget will be invisible |
## Example ## Example
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.

25
sandbox/darren/just_a_box.css
View File

@@ -2,23 +2,14 @@ Screen {
background: lightcoral; background: lightcoral;
} }
#left_pane { .box1 {
background: red; background: orangered;
width: 20
overflow: scroll scroll;
}
#middle_pane {
background: green;
width: 140;
}
#right_pane {
background: blue;
width: 30;
}
.box {
height: 12; height: 12;
width: 30; width: 30;
} }
.box2 {
background: blueviolet;
height: 6;
width: 12;
}

21
sandbox/darren/just_a_box.py
View File

@@ -1,7 +1,5 @@
from __future__ import annotations from __future__ import annotations
import asyncio
from rich.console import RenderableType from rich.console import RenderableType
from textual import events from textual import events
@@ -23,17 +21,20 @@ class Box(Widget, can_focus=True):
class JustABox(App): class JustABox(App):
def compose(self) -> ComposeResult: def compose(self) -> ComposeResult:
self.box = Box() self.box = Box(classes="box1")
yield self.box yield self.box
yield Box(classes="box2")
def key_a(self): def key_a(self):
self.animator.animate( self.box.styles.display = "none"
self.box.styles, # self.box.styles.visibility = "hidden"
"opacity", # self.animator.animate(
value=0.0, # self.box.styles,
duration=2.0, # "opacity",
on_complete=self.box.remove, # value=0.0,
) # duration=2.0,
# on_complete=self.box.remove,
# )
async def on_key(self, event: events.Key) -> None: async def on_key(self, event: events.Key) -> None:
await self.dispatch_key(event) await self.dispatch_key(event)

4
src/textual/css/tokenizer.py
View File

@@ -45,10 +45,6 @@ class TokenError(Exception):
def _get_snippet(self) -> Panel: def _get_snippet(self) -> Panel:
"""Get a short snippet of code around a given line number. """Get a short snippet of code around a given line number.
Args:
code (str): The code.
line_no (int): Line number.
Returns: Returns:
Panel: A renderable. Panel: A renderable.
""" """