layout
======

.. py:module:: layout

.. autoapi-nested-parse::

   Dashboard layout: draws readings as a grid of tiles below a header bar.

   Knows nothing about where readings come from (see `datasource`); tiles
   say which reading keys to show and how. Draws onto any framebuf-like
   object (see `text`).



Attributes
----------

.. autoapisummary::

   layout.WIDTH
   layout.HEIGHT
   layout.COLUMNS
   layout.MARGIN
   layout.NO_VALUE
   layout.TREND_ICONS
   layout.LINK_CAPTION
   layout.QR_MODULE_PX
   layout.NOTICE_ICON
   layout.ALERT_ICON
   layout.ALERT_TITLE_LINES


Functions
---------

.. autoapisummary::

   layout.format_value
   layout.pick_value_font
   layout.icon_for
   layout.draw_tile
   layout.draw_value
   layout.link_tile_index
   layout.draw_link_tile
   layout.draw_notice_tile
   layout.draw_alerts
   layout.render


Module Contents
---------------

.. py:data:: WIDTH
   :value: 400


.. py:data:: HEIGHT
   :value: 300


.. py:data:: COLUMNS
   :value: 2


.. py:data:: MARGIN
   :value: 10


.. py:data:: NO_VALUE
   :value: '?'


.. py:function:: format_value(value, decimals=None, states=None)

   Display text for a reading value (German decimal comma).


.. py:function:: pick_value_font(value, unit, space)

   Large font if value and unit fit into `space` pixels, else medium.


.. py:function:: icon_for(value, icons)

   Name of the icon for a string value, or None to show text.


.. py:data:: TREND_ICONS

.. py:function:: draw_tile(fb, tile, reading, x, y, w, h)

   One tile: label on top, value with unit below, trend arrow top right.


.. py:function:: draw_value(fb, value, unit, left, space, baseline)

   Value in the large (or, if too wide, medium) font with its unit.


.. py:data:: LINK_CAPTION
   :value: ('Kacheln', 'einstellen')


.. py:data:: QR_MODULE_PX
   :value: 3


.. py:function:: link_tile_index(tile_count)

   The bottom-left tile, which shows the web interface's QR code.


.. py:function:: draw_link_tile(fb, url, x, y, w, h)

   QR code for `url` with a short caption right of it.


.. py:data:: NOTICE_ICON
   :value: 'battery-warning'


.. py:function:: draw_notice_tile(fb, lines, x, y, w, h)

   Warning symbol with up to two lines of text, e.g. to charge the board.


.. py:data:: ALERT_ICON
   :value: 'warning-circle'


.. py:data:: ALERT_TITLE_LINES
   :value: 3


.. py:function:: draw_alerts(fb, active, top)

   Draw the warning screen below `top`.

   Shows the first (most severe) alert with icon, title, as much text as
   fits and a facts line; further alerts are counted.


.. py:function:: render(fb, readings, tiles, header, link=None, notice=None, active_alerts=None)

   Draw the whole screen.

   `readings` is what a data source's read() returns, `tiles` a list of
   {"key", "label"[, "decimals", "unit", "states", "icons"]} dicts in
   display order, `header` a header dict (see `header`).
   Tiles whose key is missing from `readings` show no value. "icons" maps
   string values to icon names in icons_large; values without an icon
   are shown as text. With `link` (a URL), the bottom-left tile shows it
   as QR code instead of its reading; otherwise `notice` (a list of up to
   two text lines) shows a warning there. `active_alerts` (see `alerts`,
   most severe first) replace all tiles with a warning screen.