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 | |
35 | namespace 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 | */ |
42 | class 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 | , /**< \returns a QList<MediaController::NavigationMenu> |
58 | containing all supported navigation menu types */ |
59 | /**< 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 | |
176 | Q_DECLARE_INTERFACE(Phonon::AddonInterface, "AddonInterface0.2.phonon.kde.org" ) |
177 | |
178 | #endif //QT_NO_PHONON_MEDIACONTROLLER |
179 | |
180 | |
181 | #endif // PHONON_ADDONINTERFACE_H |
182 | |