1/* This file is part of the KDE project
2 Copyright (C) 2007-2008 Matthias Kretz <kretz@kde.org>
3 Copyright (C) 2011 Harald Sitter <sitter@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Lesser General Public
7 License as published by the Free Software Foundation; either
8 version 2.1 of the License, or (at your option) version 3, or any
9 later version accepted by the membership of KDE e.V. (or its
10 successor approved by the membership of KDE e.V.), Nokia Corporation
11 (or its successors, if any) and the KDE Free Qt Foundation, which shall
12 act as a proxy defined in Section 6 of version 3 of the license.
13
14 This library is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 Lesser General Public License for more details.
18
19 You should have received a copy of the GNU Lesser General Public
20 License along with this library. If not, see <http://www.gnu.org/licenses/>.
21
22*/
23
24#ifndef PHONON_ADDONINTERFACE_H
25#define PHONON_ADDONINTERFACE_H
26
27#include "phononnamespace.h"
28
29#include <QList>
30#include <QVariant>
31
32
33#ifndef QT_NO_PHONON_MEDIACONTROLLER
34
35namespace Phonon
36{
37/** \class AddonInterface addoninterface.h phonon/AddonInterface
38 * \short Interface for Menu, Chapter, Angle and Title/Track control.
39 *
40 * \author Matthias Kretz <kretz@kde.org>
41 */
42class AddonInterface
43{
44 public:
45 virtual ~AddonInterface() {}
46
47 enum Interface {
48 NavigationInterface = 1, /**< Interface for (menu) navigation */
49 ChapterInterface = 2, /**< Interface for chapter control */
50 AngleInterface = 3, /**< Interface for angle control */
51 TitleInterface = 4, /**< Interface for title control */
52 SubtitleInterface = 5, /**< Interface for subtitle control */
53 AudioChannelInterface = 6 /**< Interface for audio channel control */
54 };
55
56 enum NavigationCommand {
57 availableMenus, /**< \returns a QList<MediaController::NavigationMenu>
58 containing all supported navigation menu types */
59 setMenu /**< Sets the current menu to the first
60 \c MediaController::NavigationMenu in a QList */
61 };
62
63 enum ChapterCommand {
64 availableChapters, /**< \returns an \c int representing the amount of
65 available chapters on the media source */
66 chapter, /**< \returns an \c int representing the current chapter */
67 setChapter /**< Sets the current chapter to the first \c int in the QList */
68 };
69
70 enum AngleCommand {
71 availableAngles, /**< \returns \c int representing the amount of
72 available angles on the media source */
73 angle, /**< \returns an \c int representing the current angle */
74 setAngle /**< Sets the current angle to the first \c int in the QList */
75 };
76
77 enum TitleCommand {
78 availableTitles, /**< \returns \c int representing the amount of
79 available titles on the media source */
80 title, /**< \returns \c int representing the current title */
81 setTitle, /**< Sets the current title to the first \c int in the QList */
82 autoplayTitles, /**< \returns \c bool whether autoplay of titles is on */
83 setAutoplayTitles /**< Sets autoplay to \c true or \c false as
84 indicated in the first \c bool in the QList */
85 };
86
87 enum SubtitleCommand {
88 availableSubtitles, /**< \returns \c int representing the amount of
89 available subtitles on the media source */
90 currentSubtitle, /**< \returns \c int representing the current subtitle */
91 setCurrentSubtitle, /**< Sets the current subtitle to the first
92 \c int in the QList */
93 setCurrentSubtitleFile, /**< Sets the current subtitle to the first QUrl \since 4.7.0 */
94 subtitleAutodetect, /**< \returns \c bool representing if subtitles
95 autodetection is enabled \since 4.7.0 */
96 setSubtitleAutodetect, /**< Sets/Unsets subtitles autodetection \since 4.7.0 */
97 subtitleEncoding, /**< \returns a QString representing the current encoding
98 used to render subtitles \since 4.7.0 */
99 setSubtitleEncoding, /** Sets the current encoding used to render subtitles \since 4.7.0 */
100 subtitleFont, /**< \returns a QFont representing the current font used
101 to render subtitles \since 4.7.0 */
102 setSubtitleFont /**< Sets the current font used to render subtitles \since 4.7.0 */
103 };
104
105 enum AudioChannelCommand {
106 availableAudioChannels, /**< \returns \c int representing the amount
107 of all available audio channels on the
108 media source */
109 currentAudioChannel, /**< \returns \c int representing the current
110 audio channel */
111 setCurrentAudioChannel /**< Sets the current audio channel to the first
112 \c int in the QList */
113 };
114
115 /**
116 * Queries whether the backend supports a specific interface.
117 *
118 * \param iface The interface to query support information about
119 * \returns \c true when the backend supports the interface, \c false otherwise
120 *
121 * \ingroup backend
122 **/
123 virtual bool hasInterface(Interface iface) const = 0;
124
125 /**
126 * Calls an interface on the backend.
127 *
128 * \param iface The interface to call.
129 * \param command The command the interface shall execute. This can be
130 * any value of the Command enumeration associated with the command. The
131 * backend casts this appropriately.
132 * \param arguments The arguments for the command. This list can contain
133 * a QVariant supported format + additions specific to Phonon. The
134 * content entirely depends on the command (e.g. a getter may simply use
135 * an empty list).
136 *
137 * \return \c QVariant, as with the arguments this can be anything ranging
138 * from an empty QVariant to custom types used within Phonon
139 *
140 * Setting the chapter of a Media could be done like this:
141 * \code
142 * AddonInterface *iface = d->iface();
143 * iface->interfaceCall(AddonInterface::ChapterInterface,
144 * AddonInterface::setChapter,
145 * QList<QVariant>() << QVariant(titleNumber));
146 * \endcode
147 *
148 * Handling such a request in the backend is done as follows:
149 * \code
150 * switch (iface) {
151 * case AddonInterface::ChapterInterface:
152 * switch (static_cast<AddonInterface::ChapterCommand>(command)) {
153 * case setChapter:
154 * setCurrentChapter(arguments.first().toInt());
155 * return QVariant();
156 * }
157 * }
158 * \endcode
159 *
160 * \see Interface
161 * \see NavigationCommand
162 * \see ChapterCommand
163 * \see AngleCommand
164 * \see TitleCommand
165 * \see SubtitleCommand
166 * \see AudioChannelCommand
167 *
168 * \ingroup backend
169 **/
170 virtual QVariant interfaceCall(Interface iface, int command,
171 const QList<QVariant> &arguments = QList<QVariant>()) = 0;
172};
173
174} // namespace Phonon
175
176Q_DECLARE_INTERFACE(Phonon::AddonInterface, "AddonInterface0.2.phonon.kde.org")
177
178#endif //QT_NO_PHONON_MEDIACONTROLLER
179
180
181#endif // PHONON_ADDONINTERFACE_H
182

source code of phonon/phonon/addoninterface.h