Metadata-Version: 2.4
Name: textual-transitions
Version: 0.0.2
Summary: Transition effects for Textual TUI apps
Author-email: Christopher Trudeau <ctrudeau+pypi@arsensa.com>
License: MIT License
        
        Copyright (c) 2025 Christopher Trudeau
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: repository, https://github.com/cltrudeau/textual-effects
Project-URL: documentation, https://textual-effects.readthedocs.io/en/latest/index.html
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: textual>=5.3
Provides-Extra: build
Requires-Dist: build~=1.3; extra == "build"
Requires-Dist: twine~=6.2; extra == "build"
Provides-Extra: dev
Requires-Dist: pyflakes==3.4.0; extra == "dev"
Requires-Dist: Sphinx==8.2.3; extra == "dev"
Requires-Dist: sphinx-rtd-theme==3.0.2; extra == "dev"
Requires-Dist: textual-dev==1.7.0; extra == "dev"
Requires-Dist: waelstow~=0.12; extra == "dev"
Dynamic: license-file

Textual Effects
===============

Textual Effects is a transition effects library for textual TUI applications.
It provides a series of wipe-like transitions as overlays for content similar
to how PowerPoint or Keynote do slide transitions.

The current effects are:

* Blinds: mimics vertical blinds closing
* Curtain: a wipe that starts from the top and descends, then re-ascends
* Drapes: two wipes starting from the left and right
* Fire: simulates setting fire to the screen
* Iris: a centred rectangular block that grows in side until it fills the
  screen
* Matrix: Matrix-movie like green character lines
* Scanline: a right-to left line that transitions from top to bottom
* Water: a dripping water effect until the screen fills

.. image:: capture.gif

Each effect has an optional call-back mechanism that gets triggered in the
middle of the effect. This is typically used to replace the content that you
have overlayed so that when the transition is complete new content is present.

.. _installation:

Installation
============

.. code-block:: bash

    $ pip install textual-effects

.. _quickstart:

Quick Start
===========

The effects are installed as an overlay of an existing widget (typically a
Container) using the ``layers`` CSS directive. Consider the following
structure that you want to overlay:

.. code-block:: python

    def compose(self) -> ComposeResult:
        with Container(id="my_content"):
            yield Static("Stuff in my content")
            # and more widgets


To create an overlay, put your existing widget into a wrapping Container which
will also contains a sibling Container for the effect. The above code would be
replaced with:

.. code-block:: python

    def compose(self) -> ComposeResult:

        with Container(id="effect_holder") as self.effect_holder:
            self.overlay = Container(id="overlay")
            yeild self.overlay

            # Original contents
            with Container(id="my_content"):
                yield Static("Stuff in my content")
                # and more widgets

The original and effects Containers need to be on different layers, and the
overlay must be set to ``hidden``:

.. code-block:: CSS

    #effect_holder {
        layers: below above;
    }

    #overlay {
        layer: above;
        visibility: hidden;
    }

    #my_content {
        layer: below;
    }

To activate the effect, you instantiate a new effect class, mount it within
the overlay, then create a worker with the effect's ``.run()`` method:

.. code-block:: python

    from textual_effect import Curtain

    async def on_key(self, event):
        if event.key == 'c':
            curtain = Curtain(self.effect_holder)
            self.overlay.mount(curtain)
            self.run_worker(curtain.run(), exclusive=True)

All effects support call-back mechanisms, one or more ways of adjusting the
transition speed, and padding controls. Some effects also allow you to
determine the color of the wipe. For full information on each effect, see the
documentation.


Supports
========

This code is still pretty much alpha and doesn't have automated tests. Manual
testing was done in Python 3.13. There are no match/case blocks or walrus
operators, so it should work with earlier versions.

Docs & Source
=============

Docs: http://textual_effects.readthedocs.io/en/latest/

Source: https://github.com/cltrudeau/textual-effects
