File indexing completed on 2024-04-28 08:34:52

 /*  This file is part of the KDE project
     Copyright (C) 2007-2008 Matthias Kretz <kretz@kde.org>
     Copyright (C) 2011 Harald Sitter <sitter@kde.org>
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
     License as published by the Free Software Foundation; either
     version 2.1 of the License, or (at your option) version 3, or any
     later version accepted by the membership of KDE e.V. (or its
     successor approved by the membership of KDE e.V.), Nokia Corporation
     (or its successors, if any) and the KDE Free Qt Foundation, which shall
     act as a proxy defined in Section 6 of version 3 of the license.
 
     This library is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     Lesser General Public License for more details.
 
     You should have received a copy of the GNU Lesser General Public
     License along with this library.  If not, see <http://www.gnu.org/licenses/>.
 
 */
 
 #ifndef PHONON_ADDONINTERFACE_H
 #define PHONON_ADDONINTERFACE_H
 
 #include "phononnamespace.h"
 
 #include <QList>
 #include <QVariant>
 
 
 #ifndef QT_NO_PHONON_MEDIACONTROLLER
 
 namespace Phonon
 {
 /** \class AddonInterface addoninterface.h phonon/AddonInterface
  * \short Interface for Menu, Chapter, Angle and Title/Track control.
  *
  * \author Matthias Kretz <kretz@kde.org>
  */
 class AddonInterface
 {
     public:
         virtual ~AddonInterface() {}
 
         enum Interface {
             NavigationInterface   = 1, /**< Interface for (menu) navigation */
             ChapterInterface      = 2, /**< Interface for chapter control */
             AngleInterface        = 3, /**< Interface for angle control */
             TitleInterface        = 4, /**< Interface for title control */
             SubtitleInterface     = 5, /**< Interface for subtitle control */
             AudioChannelInterface = 6  /**< Interface for audio channel control */
         };
 
         enum NavigationCommand {
             availableMenus, /**< \returns a QList<MediaController::NavigationMenu>
                                  containing all supported navigation menu types */
             setMenu         /**< Sets the current menu to the first
                                  \c MediaController::NavigationMenu in a QList */
         };
 
         enum ChapterCommand {
             availableChapters, /**< \returns an \c int representing the amount of
                                     available chapters on the media source */
             chapter,           /**< \returns an \c int representing the current chapter */
             setChapter         /**< Sets the current chapter to the first \c int in the QList */
         };
 
         enum AngleCommand {
             availableAngles, /**< \returns \c int representing the amount of
                                   available angles on the media source */
             angle,           /**< \returns an \c int representing the current angle */
             setAngle         /**< Sets the current angle to the first \c int in the QList */
         };
 
         enum TitleCommand {
             availableTitles, /**< \returns \c int representing the amount of
                                   available titles on the media source */
             title,           /**< \returns \c int representing the current title */
             setTitle,        /**< Sets the current title to the first \c int in the QList */
             autoplayTitles,  /**< \returns \c bool whether autoplay of titles is on */
             setAutoplayTitles /**< Sets autoplay to \c true or \c false as
                                    indicated in the first \c bool in the QList */
         };
 
         enum SubtitleCommand {
             availableSubtitles, /**< \returns \c int representing the amount of
                                       available subtitles on the media source */
             currentSubtitle,    /**< \returns \c int representing the current subtitle */
             setCurrentSubtitle, /**< Sets the current subtitle to the first
                                      \c int in the QList */
             setCurrentSubtitleFile, /**< Sets the current subtitle to the first QUrl \since 4.7.0 */
             subtitleAutodetect, /**< \returns \c bool representing if subtitles
                                       autodetection is enabled \since 4.7.0 */
             setSubtitleAutodetect, /**< Sets/Unsets subtitles autodetection \since 4.7.0 */
             subtitleEncoding, /**< \returns a QString representing the current encoding
                                    used to render subtitles \since 4.7.0 */
             setSubtitleEncoding, /** Sets the current encoding used to render subtitles \since 4.7.0 */
             subtitleFont, /**< \returns a QFont representing the current font used
                               to render subtitles \since 4.7.0 */
             setSubtitleFont /**< Sets the current font used to render subtitles \since 4.7.0 */
         };
 
         enum AudioChannelCommand {
             availableAudioChannels, /**< \returns \c int representing the amount
                                           of all available audio channels on the
                                           media source */
             currentAudioChannel,    /**< \returns \c int representing the current
                                           audio channel */
             setCurrentAudioChannel  /**< Sets the current audio channel to the first
                                          \c int in the QList */
         };
 
         /**
          * Queries whether the backend supports a specific interface.
          *
          * \param iface The interface to query support information about
          * \returns \c true when the backend supports the interface, \c false otherwise
          * 
          * \ingroup backend
          **/
         virtual bool hasInterface(Interface iface) const = 0;
 
         /**
          * Calls an interface on the backend.
          *
          * \param iface The interface to call.
          * \param command The command the interface shall execute. This can be
          * any value of the Command enumeration associated with the command. The
          * backend casts this appropriately.
          * \param arguments The arguments for the command. This list can contain
          * a QVariant supported format + additions specific to Phonon. The
          * content entirely depends on the command (e.g. a getter may simply use
          * an empty list).
          * 
          * \return \c QVariant, as with the arguments this can be anything ranging
          * from an empty QVariant to custom types used within Phonon
          * 
          * Setting the chapter of a Media could be done like this: 
          * \code
          * AddonInterface *iface = d->iface();
          * iface->interfaceCall(AddonInterface::ChapterInterface,
          *                      AddonInterface::setChapter,
          *                      QList<QVariant>() << QVariant(titleNumber));
          * \endcode
          * 
          * Handling such a request in the backend is done as follows:
          * \code
          * switch (iface) {
          * case AddonInterface::ChapterInterface:
          *     switch (static_cast<AddonInterface::ChapterCommand>(command)) {
          *     case setChapter:
          *         setCurrentChapter(arguments.first().toInt());
          *         return QVariant();
          *     }
          * }
          * \endcode
          * 
          * \see Interface
          * \see NavigationCommand
          * \see ChapterCommand
          * \see AngleCommand
          * \see TitleCommand
          * \see SubtitleCommand
          * \see AudioChannelCommand
          * 
          * \ingroup backend
          **/
         virtual QVariant interfaceCall(Interface iface, int command,
                 const QList<QVariant> &arguments = QList<QVariant>()) = 0;
 };
 
 } // namespace Phonon
 
 Q_DECLARE_INTERFACE(Phonon::AddonInterface, "AddonInterface0.2.phonon.kde.org")
 
 #endif //QT_NO_PHONON_MEDIACONTROLLER
 
 
 #endif // PHONON_ADDONINTERFACE_H