FrameworkIntegration

kstyle.h
1 /*
2  KStyle for KDE5 (KDE Integration)
3  SPDX-FileCopyrightText: 2013 Alejandro Fiestas Olivares <[email protected]>
4 
5  KStyle for KDE4
6  SPDX-FileCopyrightText: 2004-2005 Maksim Orlovich <[email protected]>
7  SPDX-FileCopyrightText: 2005, 2006 Sandro Giessl <[email protected]>
8 
9  Based in part on the following software:
10 
11  KStyle for KDE3
12  SPDX-FileCopyrightText: 2001-2002 Karol Szwed <[email protected]>
13  Portions
14  SPDX-FileCopyrightText: 1998-2000 TrollTech AS
15 
16  Keramik for KDE3,
17  SPDX-FileCopyrightText: 2002 Malte Starostik <[email protected]>
18  SPDX-FileCopyrightText: 2002-2003 Maksim Orlovich <[email protected]>
19  Portions
20  SPDX-FileCopyrightText: 2001-2002 Karol Szwed <[email protected]>
21  SPDX-FileCopyrightText: 2001-2002 Fredrik Höglund <[email protected]>
22  SPDX-FileCopyrightText: 2000 Daniel M. Duley <[email protected]>
23  SPDX-FileCopyrightText: 2000 Dirk Mueller <[email protected]>
24  SPDX-FileCopyrightText: 2001 Martijn Klingens <[email protected]>
25  SPDX-FileCopyrightText: 2003 Sandro Giessl <[email protected]>
26 
27  SPDX-License-Identifier: LGPL-2.0-or-later
28 */
29 
30 #ifndef KDE_KSTYLE_H
31 #define KDE_KSTYLE_H
32 
33 #include <kstyle_export.h>
34 
35 #include <QCommonStyle>
36 #include <QPalette>
37 
38 class KStylePrivate;
39 /**
40  * Provides integration with KDE Plasma Workspace settings for Qt styles.
41  *
42  * Derive your Qt style from KStyle to automatically inherit
43  * various settings from the KDE Plasma Workspace, providing a
44  * consistent user experience. For example, this will ensure a
45  * consistent single-click or double-click activation setting,
46  * and the use of standard themed icons.
47  *
48  * @author Maksim Orlovich (maksim\@kde.org)
49  * @author Sandro Giessl (giessl\@kde.org)
50  * @author Àlex Fiestas (afiestas\@kde.org)
51  */
52 
53 class KSTYLE_EXPORT KStyle : public QCommonStyle
54 {
55  Q_OBJECT
56 
57 public:
58  KStyle();
59  ~KStyle() override;
60 
61  /**
62  * Runtime element extension
63  * This is just convenience and does /not/ require the using widgets style to inherit KStyle
64  * (i.e. calling this while using cleanlooks won't segfault or so but just return 0)
65  * Returns a unique id for an element string (e.g. "CE_CapacityBar")
66  *
67  * For simplicity, only StyleHints, ControlElements and their SubElements are supported
68  * If you don't need extended SubElement functionality, just drop it
69  *
70  * @param element The style element, represented as string.
71  * Naming convention: "appname.(2-char-element-type)_element"
72  * where the 2-char-element-type is of {SH, CE, SE}
73  * (widgets in kdelibs don't have to pass the appname)
74  * examples: "CE_CapacityBar", "amarok.CE_Analyzer"
75  * @param widget Your widget ("this") passing this is mandatory, passing NULL will just return 0
76  * @returns a unique id for the @p element string or 0, if the element is not supported by the
77  * widgets current style
78  *
79  * Important notes:
80  * 1) If your string lacks the matching "SH_", "CE_" or "SE_" token the element
81  * request will be ignored (return is 0)
82  * 2) Try to avoid custom elements and use default ones (if possible) to get better style support
83  * and keep UI coherency
84  * 3) If you cache this value (good idea, this requires a map lookup) don't (!) forget to catch
85  * style changes in QWidget::changeEvent()
86  */
87  static StyleHint customStyleHint(const QString &element, const QWidget *widget);
88  static ControlElement customControlElement(const QString &element, const QWidget *widget);
89  static SubElement customSubElement(const QString &element, const QWidget *widget);
90 
91 protected:
92  /**
93  * Runtime element extension, allows inheriting styles to add support custom elements
94  * merges supporting inherit chains
95  * Supposed to be called e.g. in your constructor.
96  *
97  * NOTICE: in order to have this work, your style must provide
98  * an "X-KDE-CustomElements" classinfo, i.e.
99  * class MyStyle : public KStyle
100  * {
101  * Q_OBJECT
102  * Q_CLASSINFO ("X-KDE-CustomElements", "true")
103  *
104  * public:
105  * .....
106  * }
107  *
108  * @param element The style element, represented as string.
109  * Suggested naming convention: appname.(2-char-element-type)_element
110  * where the 2-char-element-type is of {SH, CE, SE}
111  * widgets in kdelibs don't have to pass the appname
112  * examples: "CE_CapacityBar", "amarok.CE_Analyzer"
113  *
114  * Important notes:
115  * 1) If your string lacks the matching "SH_", "CE_" or "SE_" token the element
116  * request will be ignored (return is 0)
117  * 2) To keep UI coherency, don't support any nonsense in your style, but convince app developers
118  * to use standard elements - if available
119  */
120  StyleHint newStyleHint(const QString &element);
121  ControlElement newControlElement(const QString &element);
122  SubElement newSubElement(const QString &element);
123 
124 public:
125  //@{
126  int pixelMetric(PixelMetric m, const QStyleOption *opt = nullptr, const QWidget *widget = nullptr) const override;
127  virtual int styleHint(StyleHint hint, const QStyleOption *opt, const QWidget *w, QStyleHintReturn *returnData) const override;
128 
129  void polish(QWidget *) override;
130  using QCommonStyle::polish; //! needed to avoid warnings at compilation time
131 
132  QPalette standardPalette() const override;
133 
134  virtual QIcon standardIcon(StandardPixmap standardIcon, const QStyleOption *option = nullptr, const QWidget *widget = nullptr) const override;
135  //@}
136 private:
137  KStylePrivate *const d;
138 };
139 
140 #endif // KDE_KSTYLE_H
virtual void polish(QPalette &pal) override
virtual int pixelMetric(QStyle::PixelMetric m, const QStyleOption *opt, const QWidget *widget) const const override
virtual QIcon standardIcon(QStyle::StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const const =0
Provides integration with KDE Plasma Workspace settings for Qt styles.
Definition: kstyle.h:53
virtual QPalette standardPalette() const const
virtual int styleHint(QStyle::StyleHint sh, const QStyleOption *opt, const QWidget *widget, QStyleHintReturn *hret) const const override
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu Mar 4 2021 22:48:18 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.