1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
|
// Copyright (C) 2016 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example tools/styleplugin
\title Style Plugin Example
\ingroup examples-widgets-tools
\brief This example shows how to create a plugin that extends Qt with a new
GUI look and feel.
\image stylepluginexample.png
A plugin in Qt is a class stored in a shared library that can be
loaded by a QPluginLoader at run-time. When you create plugins in
Qt, they either extend a Qt application or Qt itself. Writing a
plugin that extends Qt itself is achieved by inheriting one of the
plugin \l{Plugin Classes}{base classes}, reimplementing functions
from that class, and adding a macro. In this example we extend Qt
by adding a new GUI look and feel (i.e., making a new QStyle
available). A high-level introduction to plugins is given in the
plugin \l{How to Create Qt Plugins}{overview document}.
Plugins that provide new styles inherit the QStylePlugin base
class. Style plugins are loaded by Qt and made available through
QStyleFactory; we will look at this later. We have implemented \c
SimpleStylePlugin, which provides \c SimpleStyle. The new style
contributes to widget styling by changing the text color of the
text edit widget to red - not a major contribution, but it still
makes a new style.
The new style is platform agnostic in the sense that it is not
based on any specific style implementation, but uses QProxyStyle
to merely tweak the looks in the current application style that
defaults to the native system style.
\note On some platforms, the native style may overwrite some custom
stylings, e.g., button background color. In that case, try to run
your application in another style (e.g., fusion). You may do this
by passing \c{-style fusion} as a command line argument to your
application.
We test the plugin with \c StyleWindow, in which we display a
QTextEdit. The \c SimpleStyle and \c StyleWindow classes do not
contain any plugin specific functionality and their implementations
are trivial; we will therefore leap past them and head on to the \c
SimpleStylePlugin and the \c main() function. After we have looked
at that, we examine the plugin's profile.
\section1 SimpleStylePlugin Class Definition
\c SimpleStylePlugin inherits QStylePlugin and is the plugin
class.
\snippet tools/styleplugin/plugin/simplestyleplugin.h 0
\c keys() returns a list of style names that this plugin can
create, while \c create() takes such a string and returns the
QStyle corresponding to the key. Both functions are pure virtual
functions reimplemented from QStylePlugin. When an application
requests an instance of the \c SimpleStyle style, which this
plugin creates, Qt will create it with this plugin.
\section1 SimpleStylePlugin Class Implementation
Here is the implementation of \c keys():
\snippet tools/styleplugin/plugin/simplestyleplugin.cpp 0
Since this plugin only supports one style, we return a QStringList
with the class name of that style.
Here is the \c create() function:
\snippet tools/styleplugin/plugin/simplestyleplugin.cpp 1
Note that the key for style plugins are case insensitive.
The case sensitivity varies from plugin to plugin, so you need to
check this when implementing new plugins.
\section1 The \c main() function
\snippet tools/styleplugin/stylewindow/main.cpp 0
Qt loads the available style plugins when the QApplication object
is initialized. The QStyleFactory class knows about all styles and
produces them with \l{QStyleFactory::}{create()} (it is a
wrapper around all the style plugins).
\section1 The Simple Style Plugin Profile
The \c SimpleStylePlugin lives in its own directory and have
its own profile:
\snippet tools/styleplugin/plugin/plugin.pro 0
In the plugin profile we need to set the lib template as we are
building a shared library instead of an executable. We must also
set the config to plugin. We set the library to be stored in the
\c{styles} folder next to the main executable because this is a path
in which Qt will search for style plugins.
\section2 Using CMake to Set up the Simple Style Plugin
When using CMake, we use \l{qt6_add_plugin}{qt_add_plugin}
to create the \c simplestyleplugin plugin:
\snippet tools/styleplugin/plugin/CMakeLists.txt 0
On Windows and Linux, we place the plugin into the \c{styles} folder
next to the main executable, i.e., \c{styleplugin.exe}:
\snippet tools/styleplugin/plugin/CMakeLists.txt 2
And on macOS, we store the \c simplestyleplugin into the
\c{Contents/PlugIns/styles} folder of the App Bundle.
\snippet tools/styleplugin/plugin/CMakeLists.txt 1
\note On macOS, when creating an App Bundle, store the plugins in
the \c PlugIns folder and not next to the main executable in
the \c MacOS folder as the latter will cause issues during signing
and distribution of the app.
\section1 Related Articles and Examples
In addition to the plugin \l{How to Create Qt Plugins}{overview
document}, we have other examples and articles that concern
plugins.
In the \l{Echo Plugin Example}{echo plugin example} we show how to
implement plugins that extends Qt applications rather than Qt
itself, which is the case with the style plugin of this example.
The \l{Plug & Paint Example}{plug & paint} example shows how to
implement a static plugin as well as being a more involved example
on plugins that extend applications.
*/
|
