1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:FDL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Free Documentation License Usage
18** Alternatively, this file may be used under the terms of the GNU Free
19** Documentation License version 1.3 as published by the Free Software
20** Foundation and appearing in the file included in the packaging of
21** this file. Please review the following information to ensure
22** the GNU Free Documentation License version 1.3 requirements
23** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29    \headerfile <QtPlugin>
30    \title Defining Plugins
31    \keyword qtplugin-defining-plugins
32    \ingroup plugins
33
34    \brief The <QtPlugin> header file defines macros for defining plugins.
35
36    \sa {How to Create Qt Plugins}
37*/
38
39/*!
40    \macro Q_DECLARE_INTERFACE(ClassName, Identifier)
41    \relates <QtPlugin>
42
43    This macro associates the given \a Identifier (a string literal)
44    to the interface class called \a ClassName. The \a Identifier must
45    be unique. For example:
46
47    \snippet plugandpaint/app/interfaces.h 3
48
49    This macro is normally used right after the class definition for
50    \a ClassName, in a header file. See the
51    \l{tools/plugandpaint/app}{Plug & Paint} example for details.
52
53    If you want to use Q_DECLARE_INTERFACE with interface classes
54    declared in a namespace then you have to make sure the Q_DECLARE_INTERFACE
55    is not inside a namespace though. For example:
56    \snippet code/doc_src_qplugin.cpp 0
57
58    \sa Q_INTERFACES(), {How to Create Qt Plugins}
59*/
60
61/*!
62    \macro Q_PLUGIN_METADATA(...)
63    \relates <QtPlugin>
64    \since 5.0
65
66    This macro is being used to declare meta data that is part of a plugin
67    that instantiates this object.
68
69    The macro needs to declare the IID of the interface implemented through
70    the object, and reference a file containing the meta data for the plugin.
71
72    There should be exactly one occurrence of this macro in the source code
73    for a Qt plugin.
74
75    Example:
76
77    \snippet code/doc_src_qplugin.cpp 1
78
79    See the \l{tools/plugandpaint/app}{Plug & Paint} example for details.
80
81    Note that the class this macro appears on must be default-constructible.
82
83    FILE is optional and points to a json file.
84
85    The json file must reside in one of the include directories specified
86    by the build-system.
87    moc exits with an error when it could not find the specified file.
88
89    \sa Q_DECLARE_INTERFACE(), {How to Create Qt Plugins}
90*/
91
92/*!
93    \macro Q_IMPORT_PLUGIN(PluginName)
94    \relates <QtPlugin>
95
96    This macro imports the plugin named \a PluginName, which corresponds
97    with the name of the class that declares metadata for the plugin with
98    Q_PLUGIN_METADATA().
99
100    Inserting this macro into your application's source code will allow
101    you to make use of a static plugin.
102
103    Example:
104
105    \snippet code/doc_src_qplugin.cpp 2
106
107    Static plugins must also be included by the linker when your
108    application is built. For Qt's predefined plugins,
109    you can use the \c QTPLUGIN to add
110    the required plugins to your build. For example:
111
112    \snippet code/doc_src_qplugin.pro 3
113    \sa {Static Plugins}, {How to Create Qt Plugins}, {qmake-getting-started}{Getting Started with qmake}
114
115*/
116