/****************************************************************************
**
** Copyright (C) 2021 The Qt Company Ltd.
** Copyright (C) 2019 Luxoft Sweden AB
** Copyright (C) 2018 Pelagicore AG
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\page filter-reference.html
\title Filter Reference
\previouspage Use the Generator
\nextpage Qmake Integration

In addition to the built-in Jinja filters listed \l
{http://jinja.pocoo.org/docs/2.9/templates/#list-of-builtin-filters} {here}, the following
additional features are implemented in the ivigenerator.

\section1 Filters

\target return_type(symbol)
\target return_type()
\section2 return_type(symbol)

Returns the C++ type for the passed symbol.

E.g. QString for a symbol of type "string".

\target parameter_type(symbol)
\section2 parameter_type(symbol)

Return the C++ type for the passed symbol. This returns the same type as return_type(), but already
prepared to be used as a parameter for methods.

E.g. "const QString &<name>" for a symbol of type "string"

\target getter_name(symbol)
\section2 getter_name(symbol)

Returns the getter name of the property, if defined by the \c @getter_name annotation. Otherwise
retuns the passed symbol.

\target setter_name(symbol)
\section2 setter_name(symbol)

Returns the setter name of the property, if defined by the \c @setter_name annotation. Otherwise
retuns the passed symbol.

\target default_type_value(symbol)
\section2 default_type_value(symbol)

Returns the default value for the passed symbol. Models are initialized as \c nullptr

\target default_value(symbol, zone="=")
\section2 default_value(symbol, zone="=")

\note This filter is deprecated and will be removed in future Qt versions.

Returns the default value for the passed symbol set by the \c @default annotation. If not set uses
\c default_type_value instead.

The zone parameter is used to identify different default values per zone.

\target model_type(symbol)
\section2 model_type(symbol)

\note This filter is deprecated and will be removed in future Qt versions.

Returns the C++ class name for this model.

\target flag_type(symbol)
\section2 flag_type(symbol)

Returns the name defined by the \c @type annotation for the passed flag. If this is not set, tries to
pluralize the passed name by adding an 's' at the end.

\target parse_doc(string)
\section2 parse_doc(string)

Parses the passed comment string and adds every javadoc command into its own group. Sentences
without tag are put into the 'description' group.

\badcode
{% with doc = comments|parse_doc -%}
{% if doc.brief %}    \brief {{doc.brief}}
{% endif %}

{% if doc.description %}
    {{doc.description}}
{% endif %}
{% endwith %}
\endcode

\target lowerfirst(string)
\section2 lowerfirst(string)

Only lowers the first character of the given string.

\target range_low(property)
\section2 range_low(property)

\note This filter is deprecated and will be removed in future Qt versions.

Returns the minimum value for the passed property using the \c @range or \c @minimum annotations.

\target range_high(property)
\section2 range_high(property)

\note This filter is deprecated and will be removed in future Qt versions.

Returns the maximum value for the passed property using the \c @range or \c @maximum annotations.

\target strip_QT(string)
\section2 strip_QT(string)

Removes the 'QT' at the beginning, if the string starts with it.

\target domain_values(symbol)
\section2 domain_values(symbol)

\note This filter is deprecated and will be removed in future Qt versions.

Returns the domain values for the passed property using the \c @domain annotation.

\target enum_value(value, module_name)
\section2 enum_value(value, module_name)

Returns the fully qualified C++ name of the given value. The passed module_name is used as C++ class
name containing the enum.

Also supports passing '|' connected values.

\target tag_by_path(symbol, path, default_value=False)
\section2 tag_by_path(symbol, path, default_value=False)

\note This filter is deprecated and will be removed in future Qt versions.

Find the tag given by its full path in the object hierarchy, like
\c property.config_sim.zones.right. If some parts of the path are missing, return \c None.

\target conf_sim_tag(symbol, path, default_value=False)
\section2 conf_sim_tag(symbol, path, default_value=False)

\note This filter is deprecated and will be removed in future Qt versions.

Find the tag, given by its path, located under the "config_simulator" sub-object. Returns \c None,
if parts of the path are missing.

\target jsonify(obj)
\section2 jsonify(obj)

Returns a JSON representation of the given obj.

\target has_domains(properties)
\section2 has_domains(properties)

\note This filter is deprecated and will be removed in future Qt versions.

Returns \c true if any of the given properties has \c @range or \c @domain annotations.

\target json_domain(properties)
\section2 json_domain(properties)

\note This filter is deprecated and will be removed in future Qt versions.

Returns the property domains for the given properties formated in JSON.

\target qml_type(interface)
\section2 qml_type(interface)

Returns the name of the interface/module for use in QML. This name is defined by the \c @qml_type
annotation. This annotation is optional: if not provided, the interface name is used, for modules
module_name is used.

\target qml_control(symbol, backend_obj)
\section2 qml_control(symbol, backend_obj)

\note This filter is deprecated and will be removed in future Qt versions.

Returns the QML code for the control (or group of controls) to represent the editing UI for the
passed symbol.

\target qml_binding_property(symbol)
\section2 qml_binding_property(symbol)

\note This filter is deprecated and will be removed in future Qt versions.

Returns the name of the property of the QML control to be bound with.

E.g. "value" for a Slider and "checked" for a CheckBox.

\target qml_control_signal_parameters(symbol)
\section2 qml_control_signal_parameters(symbol)

\note This filter is deprecated and will be removed in future Qt versions

Returns the parameters for calling the signal using the values from the UI controls.

\target struct_includes(symbol)
\section2 struct_includes(symbol)

Returns the includes for the structs that the interface or a struct depends on. The returned
strings are complete and in format #include "struct.h".

\target comment_text(comment)
\section2 comment_text(comment)

Returns the text of the passed comment without the leading/trailing comment tokens ('/**', '*').

\target qml_info_type(symbol)
\section2 qml_info_type(symbol)

Returns the correct type for the symbol, to be used inside the qmltype templates.

\section1 Global Functions

\target error(msg)
\section2 error(msg)
Throws an error with the given msg

\target warning(msg)
\section2 warning(msg)
Reports a warning with the given msg

*/