{#
SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
SPDX-FileCopyrightText: 2026 Arjen Hiemstra <ahiemstra@heimr.nl>

This is the template that is used to generate element reference documentation.

REUSE-IgnoreStart
#}
/*
    SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
    SPDX-FileCopyrightText: 2026 Arjen Hiemstra <ahiemstra@heimr.nl>
*/
{# REUSE-IgnoreEnd #}

{% macro print_attribute(attribute) %}
    \li \b {{ attribute.name }}
    \li {{ attribute.description }} \br
        Possible values:
        \list
        {% for key, value in attribute.values.items() %}
            \li \b {{ key }} {{ value }}
        {% endfor %}
        \endlist
{% endmacro %}

{% macro print_element(element, level = 2) %}
\section{{ level }} {{ element.name }}

{{ element.description }}

{% if element.has_details() %}
\table
{% if element.type %}
\row
    \li \b{Type}
    \li{2, 1} {{ element.type }}
{% endif %}

{% if element.states %}
\row
    \li{1, {{ element.states | length }}} \b{States}
    \li{2, 1} {{ element.states[0] }}
{% for state in element.states[1:] %}
\row
    \li{2, 1} {{ state }}
{% endfor %}
{% endif %}

{% if element.hints %}
\row
    \li{1, {{ element.hints | length }}} \b{Hints}
    \li \b {{ element.hints[0].name }}
    \li {{ element.hints[0].description }}
{% for hint in element.hints[1:] %}
\row
    \li \b {{ hint.name }}
    \li {{ hint.description }}
{% endfor %}
{% endif %}

{% if element.attributes %}
\row
    \li{1, {{ element.attributes | length }}} \b{Attributes}
    {{ print_attribute(element.attributes[0]) }}
{% for attribute in element.attributes[1:] %}
\row
    {{ print_attribute(attribute) }}
{% endfor %}
{% endif %}

\endtable
{% endif %}

{% if element.subelements %}
\section3 Sub-Elements

{% for element in element.subelements %}
{{ print_element(element, 4) }}
{% endfor %}
{% endif %}
{% endmacro %}

/*
This file is automatically generated from elements.qdoc.j2.
To regenerate, run `tools/elementdocgenerator/generate_doc.py`.
*/

/*!

\page elements.html
\title Element Reference

This document describes the various elements that Union knows about and their
properties. Note that this page is based upon what the QtQuick output provides,
as that is at time of writing the most complete output.

\section1 Element Overview

Things that can be styled by Union are generally referred to as \i{elements}.
Each element consists of a number of properties that allow style rules to target
elements matching those properties. The matching style rules result in a set of
properties that should be applied to the matching elements.

An element can have children and each child can have its own children. Indirect
children are referred to as \i{descendants}. Certain elements have specific
children that are considered part of the element, even though they have their
own properties. These are referred to as sub-elements.

Each element can have the following properties:

\section2 Type

A string indicating the type of element.

\section2 ID

A string used as a unique identifier for a single element.

\section2 States

States represent different states the element can be in. Many of these are
related to input. The following states are currently supported:

\section3 Hovered
Set whenever the element is hovered by a mouse or similar input device.

\section3 ActiveFocus
Set whenever the element will receive keyboard input when input.

\section3 VisualFocus
Set if \c{ActiveFocus} is set and the element should visualize that focus.

\section3 Pressed
Set whenever the element is being tapped or clicked.

\section3 Checked
Set whenever the element is considered to be "on".

\section3 Highlighted
Set whenever the element should receive extra visual highlighting.

\section2 Hints

Hints are used as extra boolean flags that indicate something is different about
the element.

\section2 Attributes

Attributes are key-value pairs that indicate something is different about the
element, which is more complex than a simple binary state.

{% for type in types %}
{% if loop.changed(type.group) %}
\section1 {{ type.group }}
{% endif %}

{{ print_element(type) }}
{% endfor %}

*/
