mirror of
https://github.com/crystalidea/qt6windows7.git
synced 2025-07-04 00:05:25 +08:00
140 lines
5.7 KiB
Plaintext
140 lines
5.7 KiB
Plaintext
// 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 \c{.pro} file.
|
|
|
|
|
|
\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's QMake Project File
|
|
|
|
The \c SimpleStylePlugin lives in its own directory and has
|
|
its own \c{.pro} file:
|
|
|
|
\snippet tools/styleplugin/plugin/plugin.pro 0
|
|
|
|
In the plugin \c{.pro} file 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.
|
|
*/
|