// Copyright (C) 2019 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
\group cmake-commands-qtdbus
\title CMake Commands in Qt6 DBus
\brief Lists CMake commands defined in Qt6::DBus.

The following CMake commands are defined when Qt6::DBus is loaded, for instance
with

\code
find_package(Qt6 REQUIRED COMPONENTS DBus)
\endcode

\sa{CMake Command Reference}
*/

/*!
\page qtdbus-cmake-qt-add-dbus-interface.html
\ingroup cmake-commands-qtdbus

\title qt_add_dbus_interface
\keyword qt6_add_dbus_interface

\summary {Generates C++ sources implementing an interface for a D-Bus interface
description file.}

\include cmake-find-package-dbus.qdocinc

\cmakecommandsince 6.0

\section1 Synopsis

\badcode
qt_add_dbus_interface(<VAR> dbus_spec basename)
\endcode

\versionlessCMakeCommandsNote qt6_add_dbus_interface()

\section1 Description

Generates C++ sources implementing an interface for a D-Bus interface description
file defined in \c{dbus_spec}. The generated files are named after \c{basename}:
\c{basename.h}, \c{basename.cpp}, \c{basename.moc}. The paths of the files
are added to \c{<VAR>}.

The function sets up a call to the \l{Qt D-Bus XML compiler (qdbusxml2cpp)}
in interface (proxy) mode. By default, \c{qdbusxml2cpp} generates a C++
class named after the interface name, with a namespaced alias:

\table
\header
  \li D-Bus Interface Name
  \li Class name
  \li Namespaced name
\row
  \li \c{org.example.chat}
  \li \c{OrgExampleChatInterface}
  \li \c{org.example.chat}
\endtable

\section1 Options

Options can be set using \c set_source_files_properties on the \c dbus_spec:

\table
\header
  \li Option
  \li Value
  \li Description
\row
  \li \c CLASSNAME
  \li \c class_name
  \li Override the default interface class name with \c{class_name}.
\row
  \li \c NO_NAMESPACE
  \li boolean
  \li Do not generate the namespaced name if set to \c{ON}.
\row
  \li \c INCLUDE
  \li \c path
  \li Add an \c{#include "path"} in the generated code.
\endtable
*/

/*!
\page qtdbus-cmake-qt-add-dbus-interfaces.html
\ingroup cmake-commands-qtdbus

\title qt_add_dbus_interfaces
\keyword qt6_add_dbus_interfaces

\summary {Generates C++ sources implementing interfaces for D-Bus interface
description files.}

\include cmake-find-package-dbus.qdocinc

\cmakecommandsince 6.0

\section1 Synopsis

\badcode
qt_add_dbus_interfaces(<VAR> dbus_spec1 [dbus_spec2 ...])
\endcode

\versionlessCMakeCommandsNote qt6_add_dbus_interfaces()

\section1 Description

Generates C++ sources implementing D-Bus interfaces defined in \c{dbus_spec1},
\c{dbus_spec2}, where each argument needs to be the path to a valid D-Bus
interface description file. The paths of the generated files are added to
\c{<VAR>}.

For each argument, a call to the \l{Qt D-Bus XML compiler (qdbusxml2cpp)}
in interface (proxy) mode is set up.

The generated C++ source files are named after the XML file: For the file
\c{org.example.chat.xml} the generated header will be named
\c{orgexamplechatinterface.h}.

\section1 Options

Options can be set using \c set_source_files_properties on each of the file
arguments:

\table
\header
  \li Option
  \li Value
  \li Description
\row
  \li \c CLASSNAME
  \li \c class_name
  \li Override the default interface class name with \c{class_name}.
\row
  \li \c NO_NAMESPACE
  \li boolean
  \li Do not generate the namespaced name if set to \c{ON}.
\row
  \li \c INCLUDE
  \li \c path
  \li Add an \c{#include "path"} in the generated code.
\endtable
*/

/*!
\page qtdbus-cmake-qt-generate-dbus-interface.html
\ingroup cmake-commands-qtdbus

\title qt_generate_dbus_interface
\keyword qt6_generate_dbus_interface

\summary {Generates a D-Bus interface from a header file.}

\include cmake-find-package-dbus.qdocinc

\cmakecommandsince 6.0

\section1 Synopsis

\badcode
qt_generate_dbus_interface(header
    [customName]
    [OPTIONS options]
)
\endcode

\versionlessCMakeCommandsNote qt6_generate_dbus_interface()

\section1 Description

Parses the C++ source or header file containing a QObject-derived class
declaration and generates a file containing the D-Bus Introspection XML.

By default, the generated XML file is stored in the current binary directory,
and has the same base name as the header. You can specify a different name or
path by adding \c{customName} as an optional second argument.

\section1 Options

The function sets up a call to the \c{qdbuscpp2xml} command line tool. Further
arguments to the tool can be set after \c{OPTIONS}.
*/

/*!
\page qtdbus-cmake-qt-add-dbus-adaptor.html
\ingroup cmake-commands-qtdbus

\title qt_add_dbus_adaptor
\keyword qt6_add_dbus_adaptor

\summary {Generates an adaptor class for a D-Bus interface.}

\include cmake-find-package-dbus.qdocinc

\cmakecommandsince 6.0

\section1 Synopsis

\badcode
qt_add_dbus_adaptor(<VAR> dbus_spec header
    [parent_class]
    [basename]
    [classname]
)
\endcode

\versionlessCMakeCommandsNote qt6_add_dbus_adaptor()

\section1 Description

Generates a C++ header file implementing an adaptor for a D-Bus interface
description file defined in \c{dbus_spec}. The path of the generated file is
added to \c{<VAR>}. The generated adaptor class takes a pointer to
\c{parent_class} as QObject parent. \c{parent_class} should be declared in
\c{header}, which is included in the generated code as \c{#include "header"}.

The function sets up a call to the \l{Qt D-Bus XML compiler (qdbusxml2cpp)}
in adaptor mode. The default file and class name are generated from the last
segment in the \c{dbus_spec} base name:

\table
\header
  \li XML file
  \li Header file
  \li Class name
\row
  \li \c{org.example.chat}
  \li \c{chatadaptor.h}
  \li \c{ChatAdaptor}
\endtable


You can change the name of the header file to be generated by passing
\c{basename} as the fifth argument. The \c{.h} suffix is always added.

You can change the default class name by passing \c{classname} as the sixth
argument.

\section1 Examples

\snippet cmake/examples.cmake qt_add_dbus_adaptor
*/

/*!
\group cmake-source-file-properties-qtdbus
\title CMake Source File Properties in Qt6 DBus
\brief Lists CMake file properties used in Qt6::DBus.

\l{CMake Commands in Qt6 DBus}{CMake Commands} know about the following CMake
source file properties:

\sa{CMake Property Reference}
*/

/*!
\page cmake-source-file-property-classname.html
\ingroup cmake-source-file-properties-qtdbus

\title CLASSNAME
\target cmake-source-file-property-CLASSNAME

\summary {Overrides the default interface class name.}

\cmakepropertysince 5.0

When this property is set, the generated C++ class name is overridden
with the provided property value.

\sa{qt6_add_dbus_interface}{qt_add_dbus_interface}
*/

/*!
\page cmake-source-file-property-include.html
\ingroup cmake-source-file-properties-qtdbus

\title INCLUDE
\target cmake-source-file-property-INCLUDE

\summary {Adds an include path.}

\cmakepropertysince 5.0

When this property is set, an #include "path" is added
to the generated C++ file.

\sa{qt6_add_dbus_interface}{qt_add_dbus_interface}
*/

/*!
\page cmake-source-file-property-no-namespace.html
\ingroup cmake-source-file-properties-qtdbus

\title NO_NAMESPACE
\target cmake-source-file-property-NO_NAMESPACE

\summary {Disables generation of a namespaced name.}

\cmakepropertysince 5.0

When this property is set, the generated C++ class will not contain a namespaced alias.

\sa{qt6_add_dbus_interface}{qt_add_dbus_interface}
*/