diff --git a/CHANGELOG.md b/CHANGELOG.md index 05165a611..23e3071e7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,6 +24,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/). the return value of `DOMQuery.remove`, which uses to return `self`. https://github.com/Textualize/textual/issues/1094 - Added Pilot.wait_for_animation +- Added widget `Placeholder` ### Changed diff --git a/docs/api/placeholder.md b/docs/api/placeholder.md new file mode 100644 index 000000000..4ec987d9b --- /dev/null +++ b/docs/api/placeholder.md @@ -0,0 +1 @@ +::: textual.widgets.Placeholder diff --git a/docs/examples/widgets/placeholder.css b/docs/examples/widgets/placeholder.css new file mode 100644 index 000000000..0fe651cd5 --- /dev/null +++ b/docs/examples/widgets/placeholder.css @@ -0,0 +1,50 @@ +Placeholder { + height: 100%; +} + +#top { + height: 50%; + width: 100%; + layout: grid; + grid-size: 2 2; +} + +#left { + row-span: 2; +} + +#bot { + height: 50%; + width: 100%; + layout: grid; + grid-size: 8 8; +} + +#c1 { + row-span: 4; + column-span: 8; +} + +#col1, #col2, #col3 { + width: 1fr; +} + +#p1 { + row-span: 4; + column-span: 4; +} + +#p2 { + row-span: 2; + column-span: 4; +} + +#p3 { + row-span: 2; + column-span: 2; +} + +#p4 { + row-span: 1; + column-span: 2; +} diff --git a/docs/examples/widgets/placeholder.py b/docs/examples/widgets/placeholder.py new file mode 100644 index 000000000..d47cadeca --- /dev/null +++ b/docs/examples/widgets/placeholder.py @@ -0,0 +1,39 @@ +from textual.app import App, ComposeResult +from textual.containers import Container, Horizontal, Vertical +from textual.widgets import Placeholder + + +class PlaceholderApp(App): + + CSS_PATH = "placeholder.css" + + def compose(self) -> ComposeResult: + yield Vertical( + Container( + Placeholder(label="This is a custom label for p1.", id="p1"), + Placeholder(label="Placeholder p2 here!", id="p2"), + Placeholder(id="p3"), + Placeholder(id="p4"), + Placeholder(id="p5"), + Placeholder(), + Horizontal( + Placeholder("size", id="col1"), + Placeholder("text", id="col2"), + Placeholder("size", id="col3"), + id="c1", + ), + id="bot" + ), + Container( + Placeholder("text", id="left"), + Placeholder("size", id="topright"), + Placeholder("text", id="botright"), + id="top", + ), + id="content", + ) + + +if __name__ == "__main__": + app = PlaceholderApp() + app.run() diff --git a/docs/widgets/placeholder.md b/docs/widgets/placeholder.md new file mode 100644 index 000000000..be935d4a3 --- /dev/null +++ b/docs/widgets/placeholder.md @@ -0,0 +1,47 @@ +# Placeholder + + +A widget that is meant to have no complex functionality. +Use the placeholder widget when studying the layout of your app before having to develop your custom widgets. + +The placeholder widget has variants that display different bits of useful information. +Clicking a placeholder will cycle through its variants. + +- [ ] Focusable +- [ ] Container + +## Example + +The example below shows each placeholder variant. + +=== "Output" + + ```{.textual path="docs/examples/widgets/placeholder.py"} + ``` + +=== "placeholder.py" + + ```python + --8<-- "docs/examples/widgets/placeholder.py" + ``` + +=== "placeholder.css" + + ```css + --8<-- "docs/examples/widgets/placeholder.css" + ``` + +## Reactive Attributes + +| Name | Type | Default | Description | +| ---------- | ------ | ----------- | -------------------------------------------------- | +| `variant` | `str` | `"default"` | Styling variant. One of `default`, `size`, `text`. | + + +## Messages + +This widget sends no messages. + +## See Also + +* [Placeholder](../api/placeholder.md) code reference diff --git a/mkdocs.yml b/mkdocs.yml index e7b4e5f9e..5019e4444 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -96,6 +96,7 @@ nav: - "widgets/footer.md" - "widgets/header.md" - "widgets/input.md" + - "widgets/placeholder.md" - "widgets/static.md" - "widgets/tree_control.md" - API: