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

lots more docs

Browse Source
This commit is contained in:
Will McGugan
2022-08-14 15:43:00 +01:00
parent a1c0b173bd
commit 538e5d4701
45 changed files with 653 additions and 199 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/examples/guide/dom3.py
View File

@@ -1,6 +1,8 @@
from textual.app import App, ComposeResult
from textual.layout import Container
from textual.widgets import Header, Footer, Static
from textual.layout import Container, Horizontal
from textual.widgets import Header, Footer, Static, Button
QUESTION = "Do you want to learn about Textual CSS?"
class ExampleApp(App):
@@ -8,9 +10,13 @@ class ExampleApp(App):
yield Header()
yield Footer()
yield Container(
Static(id="widget1"),
Static(id="widget2"),
Static(id="widget3"),
Static(QUESTION, classes="question"),
Horizontal(
Button("Yes", variant="success"),
Button("No", variant="error"),
classes="buttons",
),
id="dialog",
)

29
docs/examples/guide/dom4.css
View File

@@ -0,0 +1,29 @@
/* The top level dialog (a Container) */
#dialog {
margin: 4 8;
background: darkblue 20%;
color: darkblue;
border: tall darkblue;
padding: 1 2;
}
/* The button class */
Button {
width: 1fr;
}
/* Matches the question text */
.question {
text-style: bold;
height: 100%;
content-align: center middle;
}
.buttons {
width: 100%;
height: auto;
dock: bottom;
}

19
docs/examples/guide/dom4.py
View File

@@ -1,7 +1,8 @@
from textual.app import App, ComposeResult
from textual.layout import Container
from textual.widget import Widget
from textual.widgets import Header, Footer
from textual.layout import Container, Horizontal
from textual.widgets import Header, Footer, Static, Button
QUESTION = "Do you want to learn about Textual CSS?"
class ExampleApp(App):
@@ -9,10 +10,14 @@ class ExampleApp(App):
yield Header()
yield Footer()
yield Container(
Widget(id="widget1"),
Widget(id="widget2"),
Widget(id="widget3"),
Static(QUESTION, classes="question"),
Horizontal(
Button("Yes", variant="success"),
Button("No", variant="error"),
classes="buttons",
),
id="dialog",
)
app = ExampleApp()
app = ExampleApp(css_path="dom4.css")

9
docs/examples/styles/outline.css Normal file
View File

@@ -0,0 +1,9 @@
Screen {
background: white;
color: black;
}
Static {
margin: 4 8;
background: green 20%;
outline: wide green;
}

14
docs/examples/styles/outline.py
View File

@@ -12,20 +12,8 @@ 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()
app = OutlineApp(css_path="outline.css")

19
docs/examples/styles/overflow.css Normal file
View File

@@ -0,0 +1,19 @@
Screen {
background: $background;
color: black;
}
Vertical {
width: 1fr;
}
Static {
margin: 1 2;
background: blue 20%;
border: blue wide;
height: auto;
}
#right {
overflow-y: hidden;
}

24
docs/examples/styles/overflow.py
View File

@@ -12,28 +12,6 @@ Where the fear has gone there will be nothing. Only I will remain."""
class OverflowApp(App):
CSS = """
Screen {
background: $background;
color: black;
}
Vertical {
width: 1fr;
}
Static {
margin: 1 2;
background: blue 20%;
border: blue wide;
height: auto;
}
#right {
overflow-y: hidden;
}
"""
def compose(self):
yield Horizontal(
Vertical(Static(TEXT), Static(TEXT), Static(TEXT), id="left"),
@@ -41,4 +19,4 @@ class OverflowApp(App):
)
app = OverflowApp()
app = OverflowApp(css_path="overflow.css")

9
docs/examples/styles/padding.css Normal file
View File

@@ -0,0 +1,9 @@
Screen {
background: white;
color: blue;
}
Static {
padding: 4 8;
background: blue 20%;
}

16
docs/examples/styles/padding.py
View File

@@ -11,22 +11,8 @@ Where the fear has gone there will be nothing. Only I will remain."""
class PaddingApp(App):
CSS = """
Screen {
background: white;
color: blue;
}
Static {
padding: 4 8;
background: blue 20%;
}
"""
def compose(self):
yield Static(TEXT)
app = PaddingApp()
app = PaddingApp(css_path="padding.css")

15
docs/examples/styles/scrollbar_size.css Normal file
View File

@@ -0,0 +1,15 @@
Screen {
background: white;
color: blue 80%;
layout: horizontal;
}
Static {
padding: 1 2;
width: 200;
}
.panel {
scrollbar-size: 10 4;
padding: 1 2;
}

20
docs/examples/styles/scrollbar_size.py
View File

@@ -13,26 +13,8 @@ Where the fear has gone there will be nothing. Only I will remain.
class ScrollbarApp(App):
CSS = """
Screen {
background: white;
color: blue 80%;
layout: horizontal;
}
Static {
padding: 1 2;
width: 200;
}
.panel {
scrollbar-size: 10 4;
padding: 1 2;
}
"""
def compose(self):
yield layout.Vertical(Static(TEXT * 5), classes="panel")
app = ScrollbarApp()
app = ScrollbarApp(css_path="scrollbar_size.css")

23
docs/examples/styles/scrollbars.css Normal file
View File

@@ -0,0 +1,23 @@
Screen {
background: #212121;
color: white 80%;
layout: horizontal;
}
Static {
padding: 1 2;
}
.panel1 {
width: 1fr;
scrollbar-color: green;
scrollbar-background: #bbb;
padding: 1 2;
}
.panel2 {
width: 1fr;
scrollbar-color: yellow;
scrollbar-background: purple;
padding: 1 2;
}

30
docs/examples/styles/scrollbars.py
View File

@@ -13,37 +13,9 @@ Where the fear has gone there will be nothing. Only I will remain.
class ScrollbarApp(App):
CSS = """
Screen {
background: #212121;
color: white 80%;
layout: horizontal;
}
Static {
padding: 1 2;
}
.panel1 {
width: 1fr;
scrollbar-color: green;
scrollbar-background: #bbb;
padding: 1 2;
}
.panel2 {
width: 1fr;
scrollbar-color: yellow;
scrollbar-background: purple;
padding: 1 2;
}
"""
def compose(self):
yield layout.Vertical(Static(TEXT * 5), classes="panel1")
yield layout.Vertical(Static(TEXT * 5), classes="panel2")
app = ScrollbarApp()
app = ScrollbarApp(css_path="scrollbars.css")

18
docs/examples/styles/text_style.css Normal file
View File

@@ -0,0 +1,18 @@
Screen {
layout: horizontal;
}
Static {
width:1fr;
}
#static1 {
background: red 30%;
text-style: bold;
}
#static2 {
background: green 30%;
text-style: italic;
}
#static3 {
background: blue 30%;
text-style: reverse;
}

23
docs/examples/styles/text_style.py
View File

@@ -11,31 +11,10 @@ Where the fear has gone there will be nothing. Only I will remain."""
class TextStyleApp(App):
CSS = """
Screen {
layout: horizontal;
}
Static {
width:1fr;
}
#static1 {
background: red 30%;
text-style: bold;
}
#static2 {
background: green 30%;
text-style: italic;
}
#static3 {
background: blue 30%;
text-style: reverse;
}
"""
def compose(self):
yield Static(TEXT, id="static1")
yield Static(TEXT, id="static2")
yield Static(TEXT, id="static3")
app = TextStyleApp()
app = TextStyleApp(css_path="text_style.css")

7
docs/examples/styles/tint.css Normal file
View File

@@ -0,0 +1,7 @@
Static {
height: 3;
text-style: bold;
background: white;
color: black;
content-align: center middle;
}

12
docs/examples/styles/tint.py
View File

@@ -4,16 +4,6 @@ from textual.widgets import Static
class TintApp(App):
CSS = """
Static {
height: 3;
text-style: bold;
background: white;
color: black;
content-align: center middle;
}
"""
def compose(self):
color = Color.parse("green")
for tint_alpha in range(0, 101, 10):
@@ -22,4 +12,4 @@ class TintApp(App):
yield widget
app = TintApp()
app = TintApp(css_path="tint.css")

12
docs/examples/styles/visibility.css Normal file
View File

@@ -0,0 +1,12 @@
Screen {
background: green;
}
Static {
height: 5;
background: white;
color: blue;
border: heavy blue;
}
Static.invisible {
visibility: hidden;
}

17
docs/examples/styles/visibility.py
View File

@@ -3,25 +3,10 @@ from textual.widgets import Static
class VisibilityApp(App):
CSS = """
Screen {
background: green;
}
Static {
height: 5;
background: white;
color: blue;
border: heavy blue;
}
Static.invisible {
visibility: hidden;
}
"""
def compose(self):
yield Static("Widget 1")
yield Static("Widget 2", classes="invisible")
yield Static("Widget 3")
app = VisibilityApp()
app = VisibilityApp(css_path="visibility.css")

5
docs/examples/styles/width.css Normal file
View File

@@ -0,0 +1,5 @@
Screen > Widget {
background: green;
width: 50%;
color: white;
}

10
docs/examples/styles/width.py
View File

@@ -3,16 +3,8 @@ from textual.widget import Widget
class WidthApp(App):
CSS = """
Screen > Widget {
background: green;
width: 50%;
color: white;
}
"""
def compose(self):
yield Widget()
app = WidthApp()
app = WidthApp(css_path="width.css")

328
docs/guide/CSS.md
View File

@@ -1,12 +1,64 @@
# Textual CSS
Textual uses CSS to apply style to widgets. If you have any exposure to web development you will have encountered CSS, bit don't worry if you haven't: this section will get you up to speed.
Textual uses CSS to apply style to widgets. If you have any exposure to web development you will have encountered CSS, but don't worry if you haven't: this section will get you up to speed.
CSS stands for _Cascading Stylesheets_. A stylesheet is a list of styles and the parts of a webpage to apply them to. In the case of Textual, the stylesheets apply styles to widgets.
## Stylesheets
CSS stands for _Cascading Stylesheets_. A stylesheet is a list of styles and rules about what parts of a webpage to apply them to. In the case of Textual, the stylesheets apply styles to widgets but otherwise it is the same idea.
!!! note
Depending on what you want to build with Textual, you may not need to learn Textual CSS at all. Widgets are packaged with CSS styles so apps with exclusively pre-built widgets may not need any additional CSS.
Textual CSS defines a set of rules which apply visual _styles_ to your application and widgets. These style can customize a large variety of visual settings, such as color, border, size, alignment; and more dynamic features such as animation and hover effects. As powerful as it is, CSS in Textual is quite straightforward.
CSS is typically stored in an external file with the extension `.css` alongside your Python code.
Let's look at some Textual CSS.
```css
Header {
dock: top;
height: 3;
content-align: center middle;
background: blue;
color: white;
}
```
This is an example of a CSS _rule set_. There may be many such sections in any given CSS file.
The first line is a _selector_, which tells Textual which Widget(s) to modify. In the above example, the styles will be applied to a widget defined in the Python class `Header`.
```css hl_lines="1"
Header {
dock: top;
height: 3;
content-align: center middle;
background: blue;
color: white;
}
```
The lines inside the curly braces contains CSS _rules_, which consist of a rule name and rule value separated by a colon and ending in a semi-colon. Such rules are typically written one per line, but you could add additional rules as long as they are separated by semi-colons.
```css hl_lines="2 3 4 5 6"
Header {
dock: top;
height: 3;
content-align: center middle;
background: blue;
color: white;
}
```
The first rule in the above example reads `"dock: top;"`. The rule name is `dock` which tells Textual to place the widget on a edge of the screen. The text after the colon is `top` which tells Textual to dock to the _top_ of the screen. Other valid values for dock are "right", "bottom", or "left"; but `top` is naturally appropriate for a header.
You may be able to guess what some of the the other rules do. We will cover those later.
## The DOM
The DOM, or _Document Object Model_, is a term borrowed from the web world. Textual doesn't use documents, but the term has stuck. The DOM is essentially an arrangement of widgets in to a tree.
The DOM, or _Document Object Model_, is a term borrowed from the web world. Textual doesn't use documents but the term has stuck. The DOM is an arrangement of widgets which form a tree. Some widgets may contain other widgets. For instance a list control widget will likely have item widgets, or a dialog widget may contain button widgets. These _child_ widgets form the branches of the tree.
Let's look at a super trivial Textual app.
@@ -21,7 +73,7 @@ Let's look at a super trivial Textual app.
```{.textual path="docs/examples/guide/dom1.py"}
```
When you run this app, you will have an instance of an app (ExampleAPP) in memory. The app class will also create a Screen object. In DOM terms, the Screen is a _child_ of the app.
When you run this code you will have an instance of an app (ExampleApp) in memory. This app class will also create a Screen object. In DOM terms, the Screen is a _child_ of the app.
With the above example, the DOM will look like the following:
@@ -29,7 +81,7 @@ With the above example, the DOM will look like the following:
--8<-- "docs/images/dom1.excalidraw.svg"
</div>
The above doesn't look much like a tree. Adding more widgets will create more _branches_ in the tree:
This doesn't look much like a tree yet. Let's add a header and a footer to this application, which will create more _branches_ of the tree:
=== "dom2.py"
@@ -42,7 +94,7 @@ The above doesn't look much like a tree. Adding more widgets will create more _b
```{.textual path="docs/examples/guide/dom2.py"}
```
This examples adds a header and a footer widget, which makes our DOM look the following:
With a header and a footer widget the DOM look the this:
<div class="excalidraw">
--8<-- "docs/images/dom2.excalidraw.svg"
@@ -52,22 +104,22 @@ This examples adds a header and a footer widget, which makes our DOM look the fo
We've simplified the above example somewhat. Both the Header and Footer widgets contain children of their own. When building an app with pre-built widgets you rarely need to know how they are constructed unless you plan on changing the styles for the individual components.
Both Header and Footer are children of the Screen objects. If you were to print `app.screen.children` you would see something like `[Header(), Footer()]`.
Both Header and Footer are children of the Screen object.
To further explore the DOM, lets add a few more levels. We are going to add a `textual.layout.Container` widget which (as the name suggests) is a container for other widgets. To that container we are going to add three `textual.widget.Widget` widgets. The `Widget` class is the base class for all widgets. Normally you would extend the `Widget` class to build a functional widget, but for our experiment that the base class will do.
To further explore the DOM, we're going to build a simple dialog with a question and two buttons. To do this we're going import and use a few more builtin widgets:
- `texual.layout.Container` For our top-level dialog.
- `textual.layout.Horizontal` To arrange widgets left to right.
- `textual.widgets.Static` For simple content.
- `textual.widgets.Button` For a clickable button.
=== "dom3.py"
```python
```python hl_lines="12 13 14 15 16 17 18 19 20"
--8<-- "docs/examples/guide/dom3.py"
```
=== "Output"
```{.textual path="docs/examples/guide/dom3.py"}
```
You may notice that there is a scrollbar in the output now, and we see the text "Widget#widget1". We will explain why that is later.
We've added a Container to our DOM which (as the name suggests) is a container for other widgets. The container has a number of other widgets passed as positional arguments which will be added as the children of the container. Not all widgets accept child widgets in this way; for instance the Button widget doesn't need any children.
Here's the DOM created by the above code:
@@ -75,8 +127,248 @@ Here's the DOM created by the above code:
--8<-- "docs/images/dom3.excalidraw.svg"
</div>
You'll notice that we defined the children of our container differently. The `Container` class, and most other widgets, will accept their children as positional arguments. These children are added to the DOM at the same time as their parents.
Here's the output from this example:
```{.textual path="docs/examples/guide/dom3.py"}
```python hl_lines="10 11 12 13 14"
--8<-- "docs/examples/guide/dom3.py"
```
You may recognize some of the elements, but it doesn't look quite right. This is because we haven't added a stylesheet.
## CSS files
To add a stylesheet we need to pass the path to a CSS file via the app classes' `css_path` argument:
```python hl_lines="23"
--8<-- "docs/examples/guide/dom4.py"
```
You may have noticed that some of the constructors have additional keywords argument: `id` and `classes`. These are used by the CSS to identify parts of the DOM. We will cover these in the next section.
Here's the CSS file we are applying:
```python
--8<-- "docs/examples/guide/dom4.css"
```
The CSS contains a number of rules sets with a selector and a list of rules. You can also add comments with text between `/*` and `*/` which will be ignored by Textual. Add comments to leave yourself reminders or to temporarily disable selectors.
With the CSS in place, the output looks very different:
```{.textual path="docs/examples/guide/dom4.py"}
```
### Why CSS?
It is reasonable to ask why use CSS at all? Python is a powerful and expressive language. Wouldn't it be easier to do everything in your `.py` files?
One advantage of CSS is that it separates how your app _looks_ from how it _works_. Setting styles in Python can generate a lot of code which can make it hard to see the more important logic in your application.
Another advantage of CSS is that you can _live edit_ the styles. If you run your application with the following command, any changes you make to the CSS file will be instantly updated:
```bash
textual run my_app.py --dev
```
Being able to iterate on the design without restarting the Python code can make it much easier to design beautiful interfaces.
## Selectors
A selector is the text which precedes the curly braces in a set of rules. It tells textual which widgets it should apply rules to
Selectors can target a kind of widget or a specific widget. For example you may want to style a particular button green only if it is within a dialog. Or you may want to draw a red box around a widget when it is underneath the mouse cursor. CSS selector allows you to do such things simply, without writing (Python) code.
Let's look at the selectors supported by Textual CSS.
### Type selector
The _type_ selector matches the name of the (Python) class, which is literally the name of the class in your Python code. For example, the following widget can be matched with a `Button` selector:
```python
from textual.widgets import Widget
class Button(Static):
pass
```
To apply a border to this widget, we could have a rule such as the following:
```css
Button {
border: solid blue;
}
```
The type selector will also match a widget's base classes. For instance, the `Button` Python class will will also match the `Static` selector because Widget extends Static in the Python code. Similarly, it will also match `Widget` which is the base class for all widgets.
So the following selector will also match our `Button`:
```css
Static {
background: blue;
border: rounded white;
}
```
You may have noticed that the `border` rule exists in both Static and Button. When this happens, Textual will use the most recently defined sub-class within a list of bases. So Button wins over Static, and Static wins over Widget.
### ID selector
Every Widget can have a single `id` attribute, which is set via the constructor. The ID should be unique to it's container.
Here's an example of a widget with an ID:
```python
yield Button(id="next")
```
You can match an ID with a selector starting with a hash (`#`). Here is how you might draw a red outline around the above button:
```css
#next {
outline: red;
}
```
### Class-name selector
Every widget can have a number of class names applied. The term "class" here is borrowed from web CSS, and has a different meaning to a Python class. You can think of a CSS class as a tag of sorts. Widgets with the same tag may share a particular style.
CSS classes are set via the widgets `classses` parameter in the constructor. Here's an example:
```python
yield Button(classes="success")
```
This button will have a single class called `"success"` which we could target via CSS to make the button green.
You may also set multiple classes separated by spaces. For instance, here is a button with both an `error` class and a `disabled` class:
```python
Button(classes="error disabled")
```
To match a Widget with a given class in CSS you can precede the class name with a dot (`.`). Here's a rule with a class selector to match the `"success"` class:
```css
.success {
background: green;
color: white;
}
```
!!! note
You can apply a class name to any class, which means that widgets of different types could share classes.
Class name selectors may be _chained_ together by appending another full stop and class name. The selector will match a widget that has _all_ of the class names set. For instance, the following sets a red background on widgets that have both `error` _and_ `disables` class names.
```css
.error.disabled {
background: darkred;
}
```
### Universal selectors
The _universal_ selectors is specified by an asterisk and will match _all_ widgets.
For example, the following will draw a red outline around all widgets:
```css
* {
outline: solid red;
}
```
### Pseudo classes
Pseudo classes can be used to match widgets a given state. For instance, you might want a button to have a green background when the mouse cursor moves over it. We can do this with the `:hover` pseudo selector.
```css
Button:hover {
background: green;
}
```
Here are some other such pseudo classes:
- `:focus` Matches widgets which have input focus.
- `:focus-within` Matches widgets with a focused a child widget.
## Combinators
More sophisticated selectors can be created by combining simple selectors. The rule that combines selectors is know as a _combinator_.
### Descendant combinator
If you separate two selectors with a space it will match widgets with the second selector that have a parent that matches the first selector.
Here's a section of DOM to illustrate this combinator:
<div class="excalidraw">
--8<-- "docs/images/descendant_combinator.excalidraw.svg"
</div>
Let's say we want to make the text of the buttons in the dialog bold, but we _don't_ want to change the Button in the sidebar. We can do this with the following rule:
```css hl_lines="1"
#dialog Button {
text-style: bold;
}
```
The `#dialog Button` selector matches all buttons that are below the widget with an id of "dialog". No other buttons will be matched.
As with all selectors you can combine as many as you wish. The following will match a `Button` that is under a `Horizontal` widget _and_ under a widget with an id of `"dialog"`:
```css
#dialog Horizontal Button {
text-style: bold;
}
```
### Child combinator
The child combinator is similar to the descendant combinator but will only match an immediate child. To create a child combinator, separate two selectors with a greater than symbol (`>`). Any whitespace around the `>` will be ignored.
Let's use this to match the Button in the sidebar given the following DOM:
<div class="excalidraw">
--8<-- "docs/images/child_combinator.excalidraw.svg"
</div>
We can use the following CSS to style all buttons which have a parent with an ID of `sidebar`:
```css
#sidebar > Button {
text-style: underline;
}
```
## Specificity
It is possible that several selectors match a given widget. If the same rule is applied by more than one selector, then Textual needs a way to decide which rule _wins_. It does this by following these rules:
- The selector with the most IDs wins. For instance `"#next"` beats `".button"` and `#dialog #next` beats `#next`. If the selectors have the same number of IDs move to the next rule.
- The selector with the most class names wins. For instance `".button.success"` beats `".success"`. For the purposes of specificity, pseudo classes are treated the same as regular class names, so ".button:hover" counts as _2_ class names. If the selectors have the same number of class names then move to the next rule.
- The selector with the most types wins. For instance `Container Button` beats `Button`.
### Important rules
The specificity rules are usually enough to fix any conflicts in your stylesheets. There is one last way of resolving conflicting selectors which applies to individual rules. If you add the text `!important` to the end of a rule then it will "win" regardless of the specificity.
!!! warning
Use `!important` sparingly (if at all) as it can make it difficult to modify your CSS in the future.
Here's an example that makes buttons blue when hovered over with the mouse, regardless of any other selectors that match Buttons:
```css hl_lines="2"
Button:hover {
background: blue !important;
}
```

16
docs/images/child_combinator.excalidraw.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 21 KiB

16
docs/images/descendant_combinator.excalidraw.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 24 KiB

6
docs/images/dom3.excalidraw.svg
View File

File diff suppressed because one or more lines are too long
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 25 KiB

After

Width:  |  Height:  |  Size: 30 KiB

4
docs/styles/background.md
View File

@@ -2,6 +2,10 @@
The `background` rule sets the background color of the widget.
## Example
This example creates three widgets and applies a different background to each.
=== "background.py"
```python

6
docs/styles/border.md
View File

@@ -42,6 +42,12 @@ This examples shows three widgets with different border styles.
--8<-- "docs/examples/styles/border.py"
```
=== "border.css"
```css
--8<-- "docs/examples/styles/border.css"
```
=== "Output"
```{.textual path="docs/examples/styles/border.py"}

6
docs/styles/box_sizing.md
View File

@@ -16,6 +16,12 @@ Both widgets in this example have the same height (5). The top widget has `box-s
--8<-- "docs/examples/styles/box_sizing.py"
```
=== "box_sizing.css"
```css
--8<-- "docs/examples/styles/box_sizing.css"
```
=== "Output"
```{.textual path="docs/examples/styles/box_sizing.py"}

10
docs/styles/color.md
View File

@@ -2,12 +2,22 @@
The `color` rule sets the text color of a Widget.
## Example
This example sets a different text color to three different widgets.
=== "color.py"
```python
--8<-- "docs/examples/styles/color.py"
```
=== "color.css"
```css
--8<-- "docs/examples/styles/color.css"
```
=== "Output"
```{.textual path="docs/examples/styles/color.py"}

6
docs/styles/display.md
View File

@@ -12,6 +12,12 @@ Note that the second widget is hidden by adding the "hidden" class which sets th
--8<-- "docs/examples/styles/display.py"
```
=== "display.css"
```css
--8<-- "docs/examples/styles/display.css"
```
=== "Output"
```{.textual path="docs/examples/styles/display.py"}

8
docs/styles/height.md
View File

@@ -4,12 +4,20 @@ The `height` rule sets a widget's height. By default, it sets the height of the
## Example
This examples applies a widget with a height of 50% of the screen.
=== "height.py"
```python
--8<-- "docs/examples/styles/height.py"
```
=== "height.css"
```python
--8<-- "docs/examples/styles/height.css"
```
=== "Output"
```{.textual path="docs/examples/styles/height.py"}

8
docs/styles/margin.md
View File

@@ -12,12 +12,20 @@ Margin may also be set individually by setting `margin-top`, `margin-right`, `ma
## Example
In this example we add a large margin to a some static text.
=== "margin.py"
```python
--8<-- "docs/examples/styles/margin.py"
```
=== "margin.css"
```css
--8<-- "docs/examples/styles/margin.css"
```
=== "Output"
```{.textual path="docs/examples/styles/margin.py"}

8
docs/styles/offset.md
View File

@@ -4,12 +4,20 @@ The `offset` rule adds an offset to the widget's position.
## Example
In this example, we have 3 widgets with differing offsets.
=== "offset.py"
```python
--8<-- "docs/examples/styles/offset.py"
```
=== "offset.css"
```css
--8<-- "docs/examples/styles/offset.css"
```
=== "Output"
```{.textual path="docs/examples/styles/offset.py"}

6
docs/styles/outline.md
View File

@@ -36,6 +36,12 @@ This examples shows a widget with an outline. Note how the outline occludes the
--8<-- "docs/examples/styles/outline.py"
```
=== "outline.css"
```css
--8<-- "docs/examples/styles/outline.css"
```
=== "Output"
```{.textual path="docs/examples/styles/outline.py"}

8
docs/styles/overflow.md
View File

@@ -18,12 +18,18 @@ Here we split the screen in to left and right sections, each with three vertical
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 show.
=== "width.py"
=== "overflow.py"
```python
--8<-- "docs/examples/styles/overflow.py"
```
=== "overflow.css"
```css
--8<-- "docs/examples/styles/overflow.css"
```
=== "Output"
```{.textual path="docs/examples/styles/overflow.py"}

6
docs/styles/padding.md
View File

@@ -20,6 +20,12 @@ This example adds padding around static text.
--8<-- "docs/examples/styles/padding.py"
```
=== "padding.css"
```css
--8<-- "docs/examples/styles/padding.css"
```
=== "Output"
```{.textual path="docs/examples/styles/padding.py"}

6
docs/styles/scrollbar.md
View File

@@ -21,6 +21,12 @@ In this example we have two panels with different scrollbar colors set for each.
--8<-- "docs/examples/styles/scrollbars.py"
```
=== "scrollbars.css"
```css
--8<-- "docs/examples/styles/scrollbars.css"
```
=== "Output"
```{.textual path="docs/examples/styles/scrollbars.py"}

6
docs/styles/scrollbar_size.md
View File

@@ -14,6 +14,12 @@ In this example we modify the size of the widgets scrollbar to be _much_ larger
--8<-- "docs/examples/styles/scrollbar_size.py"
```
=== "scrollbar_size.css"
```css
--8<-- "docs/examples/styles/scrollbar_size.css"
```
=== "Output"
```{.textual path="docs/examples/styles/scrollbar_size.py"}

6
docs/styles/text_style.md
View File

@@ -22,6 +22,12 @@ Each of the three text panels has a different text style.
--8<-- "docs/examples/styles/text_style.py"
```
=== "text_style.css"
```css
--8<-- "docs/examples/styles/text_style.css"
```
=== "Output"
```{.textual path="docs/examples/styles/text_style.py"}

6
docs/styles/tint.md
View File

@@ -12,6 +12,12 @@ This examples shows a green tint with gradually increasing alpha.
--8<-- "docs/examples/styles/tint.py"
```
=== "tint.css"
```css
--8<-- "docs/examples/styles/tint.css"
```
=== "Output"
```{.textual path="docs/examples/styles/tint.py"}

6
docs/styles/visibility.md
View File

@@ -12,6 +12,12 @@ Note that the second widget is hidden, while leaving a space where it would have
--8<-- "docs/examples/styles/visibility.py"
```
=== "visibility.css"
```css
--8<-- "docs/examples/styles/visibility.css"
```
=== "Output"
```{.textual path="docs/examples/styles/visibility.py"}

8
docs/styles/width.md
View File

@@ -4,12 +4,20 @@ The `width` rule sets a widget's width. By default, it sets the width of the con
## Example
This example adds a widget with 50% width of the screen.
=== "width.py"
```python
--8<-- "docs/examples/styles/width.py"
```
=== "width.css"
```css
--8<-- "docs/examples/styles/width.css"
```
=== "Output"
```{.textual path="docs/examples/styles/width.py"}

1
sandbox/will/basic.css
View File

@@ -109,6 +109,7 @@ Tweet {
/* scrollbar-gutter: stable; */
align-horizontal: center;
box-sizing: border-box;
}

19
src/textual/box_model.py
View File

@@ -43,15 +43,18 @@ def get_box_model(
gutter = styles.gutter
margin = styles.margin
is_auto_width = styles.width and styles.width.is_auto
is_auto_height = styles.height and styles.height.is_auto
styles_width = styles.width
styles_height = styles.height
is_auto_width = styles_width and styles_width.is_auto
is_auto_height = styles_height and styles_height.is_auto
# Container minus padding and border
content_container = container - gutter.totals
# The container including the content
sizing_container = content_container if is_border_box else container
if styles.width is None:
if styles_width is None:
# No width specified, fill available space
content_width = Fraction(content_container.width - margin.width)
elif is_auto_width:
@@ -61,10 +64,10 @@ def get_box_model(
)
else:
# An explicit width
content_width = styles.width.resolve_dimension(
content_width = styles_width.resolve_dimension(
sizing_container - styles.margin.totals, viewport, fraction_unit
)
if is_border_box:
if is_border_box and not styles_width.is_percent:
content_width -= gutter.width
if styles.min_width is not None:
@@ -83,7 +86,7 @@ def get_box_model(
content_width = max(Fraction(0), content_width)
if styles.height is None:
if styles_height is None:
# No height specified, fill the available space
content_height = Fraction(content_container.height - margin.height)
elif is_auto_height:
@@ -93,10 +96,10 @@ def get_box_model(
)
else:
# Explicit height set
content_height = styles.height.resolve_dimension(
content_height = styles_height.resolve_dimension(
sizing_container - styles.margin.totals, viewport, fraction_unit
)
if is_border_box:
if is_border_box and not styles_height.is_percent:
content_height -= gutter.height
if styles.min_height is not None:

5
src/textual/css/scalar.py
View File

@@ -189,6 +189,11 @@ class Scalar(NamedTuple):
return "auto"
return f"{int(value) if value.is_integer() else value}{self.symbol}"
@property
def is_cells(self) -> bool:
"""Check if the Scalar is explicit cells."""
return self.unit == Unit.CELLS
@property
def is_percent(self) -> bool:
"""Check if the Scalar is a percentage unit."""