src/controls/Heading.qml

0001 /*
0002  *  SPDX-FileCopyrightText: 2012 by Sebastian Kügler <sebas@kde.org>
0003  *
0004  *  SPDX-License-Identifier: LGPL-2.0-or-later
0005  */
0006
0007 import QtQuick
0008 import QtQuick.Controls as QQC2
0009 import org.kde.kirigami as Kirigami
0010
0011 /**
0012  * @brief A heading label used for subsections of texts.
0013  *
0014  * The characteristics of the text will be automatically set according to the
0015  * Kirigami.Theme. Use this components for section titles or headings in your UI,
0016  * for example page or section titles.
0017  *
0018  * Example usage:
0019  * @code
0020  * import org.kde.kirigami 2.4 as Kirigami
0021  * [...]
0022  * Column {
0023  *     Kirigami.Heading {
0024  *         text: "Apples in the sunlight"
0025  *         level: 2
0026  *     }
0027  *   [...]
0028  * }
0029  * @endcode
0030  *
0031  * The most important property is "text", which applies to the text property of
0032  * Label. See the Label component from QtQuick.Controls 2 and primitive QML Text
0033  * element API for additional properties, methods and signals.
0034  *
0035  * @inherit QtQuick.Controls.Label
0036  */
0037 QQC2.Label {
0038     id: heading
0039
0040     /**
0041      * @brief This property holds the level of the heading, which determines its size.
0042      *
0043      * This property holds the level, which determines how large the header is.
0044      *
0045      * Acceptable values range from 1 (big) to 5 (small).
0046      *
0047      * default: ``1``
0048      */
0049     property int level: 1
0050
0051     /**
0052      * @brief This enumeration defines heading types.
0053      *
0054      * This enum helps with heading visibility (making it less or more important).
0055      */
0056     enum Type {
0057         Normal,
0058         Primary,
0059         Secondary
0060     }
0061
0062     /**
0063      * @brief This property holds the heading type.
0064      *
0065      * The type of the heading. This can be:
0066      * * ``Kirigami.Heading.Type.Normal``: Create a normal heading (default)
0067      * * ``Kirigami.Heading.Type.Primary``: Makes the heading more prominent. Useful
0068      *   when making the heading bigger is not enough.
0069      * * ``Kirigami.Heading.Type.Secondary``: Makes the heading less prominent.
0070      *   Useful when an heading is for a less important section in an application.
0071      *
0072      * @property Heading::Type type
0073      * @since 5.82
0074      */
0075     property int type: Heading.Type.Normal
0076
0077     font.pointSize: {
0078         let factor = 1;
0079         switch (heading.level) {
0080             case 1:
0081                 factor = 1.35;
0082                 break;
0083             case 2:
0084                 factor = 1.20;
0085                 break;
0086             case 3:
0087                 factor = 1.15;
0088                 break;
0089             case 4:
0090                 factor = 1.10;
0091                 break;
0092             default:
0093                 break;
0094         }
0095         return Kirigami.Theme.defaultFont.pointSize * factor;
0096     }
0097     font.weight: type === Heading.Type.Primary ? Font.DemiBold : Font.Normal
0098
0099     opacity: type === Heading.Type.Secondary ? 0.7 : 1
0100
0101     Accessible.role: Accessible.Heading
0102 }