1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2014 Thomas Lübking <thomas.luebking@gmail.com>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KSTYLEEXTENSIONS_H
9#define KSTYLEEXTENSIONS_H
10
11#include <QStyle>
12#include <kwidgetsaddons_export.h>
13
14/*!
15 * \namespace KStyleExtensions
16 * \inmodule KWidgetsAddons
17 *
18 * \brief Runtime style extensions.
19 *
20 * You can use this to have a supporting QStyle implementation paint your widget
21 * This is just convenience and does /not/ require the using widgets style to inherit KStyle (i.e.
22 * calling this while using cleanlooks won't segfault but just return "0")
23 *
24 * For simplicity, only StyleHints, ControlElements and their SubElements are supported
25 * If you don't need extended SubElement functionality, just skip its usage
26 *
27 * The element string has to be of the form: "appname.(2-char-element-type)_element"
28 * The 2-char-element-type is the corresponding {SH, CE, SE}
29 * Widgets in KWidgetsAddons don't have to pass the appname
30 *
31 * Examples: "CE_CapacityBar", "amarok.CE_Analyzer"
32 *
33 * Important notes:
34 *
35 * 1) If your string lacks the matching "SH_", "CE_" or "SE_" token the element request will be ignored (return is 0)
36 *
37 * 2) Try to avoid custom elements and use default ones (if possible) to get better style support and keep UI coherency
38 *
39 * 3) If you cache this value (good idea, this requires a map lookup) do not forget to catch style changes in QWidget::changeEvent()!
40 */
41namespace KStyleExtensions
42{
43/*!
44 * Resolve a dynamic QStyle::ControlElement for eg. QStyle::drawControl()
45 *
46 * Returns a unique QStyle::ControlElement or 0 in case the style doesn't support this element
47 *
48 * \a element a valid element string appname.CE_element, eg. "amarok.CE_Analyzer"
49 *
50 * \a widget the widget to paint this element for. This parameter is mandatory, nullptr will return 0!
51 *
52 * \since 5.3
53 */
54KWIDGETSADDONS_EXPORT QStyle::ControlElement customControlElement(const QString &element, const QWidget *widget);
55/*!
56 * Resolve a dynamic QStyle::StyleHint to query QStyle::styleHint()
57 *
58 * Returns a unique QStyle::StyleHint or 0 in case the style doesn't support this element
59 *
60 * \a element a valid element string appname.SH_element, eg. "amarok.SH_Analyzer"
61 *
62 * \a widget the widget to paint this element for. This parameter is mandatory, nullptr will return 0!
63 *
64 * \since 5.3
65 */
66KWIDGETSADDONS_EXPORT QStyle::StyleHint customStyleHint(const QString &element, const QWidget *widget);
67/*!
68 * Resolve a dynamic QStyle::SubElement for eg. QStyle::subElementRect()
69 *
70 * Returns a unique QStyle::SubElement or 0 in case the style doesn't support this element
71 *
72 * \a element a valid element string appname.SE_element, eg. "amarok.SE_AnalyzerCanvas"
73 *
74 * \a widget the widget to paint this element for. This parameter is mandatory, nullptr will return 0!
75 *
76 * \since 5.3
77 */
78KWIDGETSADDONS_EXPORT QStyle::SubElement customSubElement(const QString &element, const QWidget *widget);
79}
80
81#endif // KSTYLEEXTENSIONS_H
82

source code of kwidgetsaddons/src/kstyleextensions.h