Quickstart
==========

This page gets a minimal Tessella window on screen. See
:doc:`installation` first if you haven't set up your environment yet.

The game loop
-------------

Tessella doesn't manage the ``pygame`` window or event loop for you: it's a
widget layer that sits *inside* a regular pygame application. Every Tessella
app follows the same four steps, once per frame:

1. ``calculate_layout``: (re)computes the widget tree's sizing and
   positioning against the available screen area. Called once up front, and
   again whenever the window is resized.
2. ``process_event``: forwards pygame events (clicks, key presses, ...) to
   the widget tree so interactive widgets can react to them.
3. ``update``: advances any time-based state (e.g. animations) using the
   frame's delta time.
4. ``render``: draws the widget tree onto a target surface.

Hello, Tessella
----------------

Here's the smallest useful example: a window that centers a piece of text.

.. code-block:: python

   import pygame
   from tessella import *

   pygame.init()

   display = pygame.display.set_mode((400, 300), pygame.RESIZABLE)
   clock = pygame.time.Clock()

   gui: Widget = Center(
       Text(
           "Hello, Tessella!",
           style=TextStyle(font_size=32, font_color="#eeeeee")
       )
   )
   gui.calculate_layout(display.get_rect())

   running = True
   while running:
       delta_time = clock.tick(60)

       for event in pygame.event.get():
           if event.type == pygame.QUIT:
               running = False
           elif event.type == pygame.WINDOWRESIZED:
               gui.calculate_layout(display.get_rect())

           # consumed is True if the UI acted on this event (e.g. a button
           # click). Not used here since this example has no game logic of
           # its own, but you'd check it to decide whether an unconsumed
           # event should also be handled as gameplay input, e.g. a click
           # the UI ignored being treated as aiming or firing a weapon.
           consumed = gui.process_event(event)

       gui.update(delta_time)

       display.fill(Palette.BACKGROUND)
       gui.render(display)
       pygame.display.update()

   pygame.quit()

Running this script opens a resizable ``400x300`` window with the text
"Hello, Tessella!" centered on it:

.. container:: tessella-swatch

   .. image:: /_static/images/quickstart/hello.png
      :alt: A 400x300 window with light text reading "Hello, Tessella!" centered on a dark background.

A quick tour of what's happening
---------------------------------

- ``from tessella import *`` pulls in the whole public widget API: widgets
  (``Center``, ``Text``, ...), style classes (``TextStyle``, ...) and helpers
  like ``ValueNotifier``.
- :class:`~tessella.widgets.center.Center` positions its single child in the
  middle of the space available to it.
- :class:`~tessella.widgets.text.Text` renders a string using a ``TextStyle``,
  which controls font size, color, font file and anti-aliasing.
- ``gui.calculate_layout(display.get_rect())`` must be called before the
  first render (and again on ``WINDOWRESIZED``) so every widget in the tree
  knows its size and position.

Next steps
----------

Head over to :doc:`tutorial` to build something interactive: buttons,
state, and reactive updates. Or browse the :doc:`API reference
</api/modules>` for the full list of available widgets and styles.