File indexing completed on 2024-07-14 14:35:17

0001 // Copyright (C) 2002 Neil Stevens <neil@qualityassistant.com>
0002 //
0003 // Permission is hereby granted, free of charge, to any person obtaining a copy
0004 // of this software and associated documentation files (the "Software"), to deal
0005 // in the Software without restriction, including without limitation the rights
0006 // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
0007 // copies of the Software, and to permit persons to whom the Software is
0008 // furnished to do so, subject to the following conditions:
0009 //
0010 // The above copyright notice and this permission notice shall be included in
0011 // all copies or substantial portions of the Software.
0012 //
0013 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
0014 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
0015 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
0016 // THE AUTHOR(S) BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
0017 // AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
0018 // CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
0019 //
0020 // Except as contained in this notice, the name(s) of the author(s) shall not be
0021 // used in advertising or otherwise to promote the sale, use or other dealings
0022 // in this Software without prior written authorization from the author(s).
0023 
0024 #ifndef KMEDIAPLAYERPLAYER_H
0025 #define KMEDIAPLAYERPLAYER_H
0026 
0027 #include <kparts/readonlypart.h>
0028 #include "view.h"
0029 
0030 #include "kmediaplayer_export.h"
0031 
0032 #include <memory>
0033 
0034 /**
0035  * An interface for media playback parts.
0036  */
0037 namespace KMediaPlayer
0038 {
0039 
0040 /**
0041  * KPart interface to allow controlling and querying playback of a media track.
0042  *
0043  * This class provides methods to control playback of a single media track, as
0044  * well as providing information on the current playback state. It can
0045  * optionally provide access to a user interface that can be displayed to the
0046  * user.
0047  *
0048  * There are two servicetypes for this KParts interface:  KMediaPlayer/Player
0049  * and KMediaPlayer/Engine. KMediaPlayer/Player provides a user interface (see
0050  * view()), while KMediaPlayer/Engine just provides direct control via this
0051  * class.
0052  */
0053 class KMEDIAPLAYER_EXPORT Player : public KParts::ReadOnlyPart
0054 {
0055     Q_OBJECT
0056     Q_ENUMS(State)
0057     /**
0058      * Whether the length property is valid.
0059      *
0060      * Not all media tracks have a length (for example, some streams are
0061      * continuous).
0062      */
0063     Q_PROPERTY(bool hasLength READ hasLength)
0064     /**
0065      * The length of the media track in milliseconds.
0066      *
0067      * The value is undefined if hasLength is @c false.
0068      */
0069     Q_PROPERTY(qlonglong length READ length)
0070     /**
0071      * Whether playback should loop.
0072      *
0073      * As this interface has no concept of a playlist, this indicates
0074      * whether the current media track will play repeatedly.
0075      */
0076     Q_PROPERTY(bool looping READ isLooping WRITE setLooping)
0077     /**
0078      * The position in the media track in milliseconds.
0079      */
0080     Q_PROPERTY(qlonglong position READ position)
0081     /**
0082      * Whether seek() can be expected to work on the current media track.
0083      *
0084      * Some streams cannot be seeked.
0085      */
0086     Q_PROPERTY(bool seekable READ isSeekable)
0087     /**
0088      * The current state of the player.
0089      */
0090     Q_PROPERTY(State state READ state WRITE setState NOTIFY stateChanged)
0091 
0092 public:
0093     /**
0094      * Constructs a Player instance with no associated GUI.
0095      *
0096      * This should be used when a KMediaPlayer/Engine is requested.
0097      */
0098     explicit Player(QObject *parent);
0099 
0100     /**
0101      * Constructs a Player instance with a GUI.
0102      *
0103      * This should be used when a KMediaPlayer/Player is requested.
0104      */
0105     Player(QWidget *parentWidget, const char *widgetName, QObject *parent);
0106 
0107     /**
0108      * Cleans up any associated resources.
0109      *
0110      * This should not explicitly delete any widget returned by view(): if it
0111      * has been reparented, it is up to the caller to dispose of it properly.
0112      */
0113     ~Player() override;
0114 
0115     /**
0116      * Returns the widget associated with this player.
0117      *
0118      * If the part's service type is KMediaPlayer/Player, this should not return
0119      * 0. However, if the part's service is just KMediaPlayer/Engine, this may
0120      * return 0.
0121      *
0122      * @returns  A widget to view and control this Player instance, or 0 if
0123      *           there is no GUI.
0124      */
0125     virtual View *view() = 0;
0126 
0127 public Q_SLOTS:
0128     /**
0129      * Pauses playback of the media track.
0130      *
0131      * If the media track is not already paused, this should have no effect.
0132      */
0133     virtual void pause() = 0;
0134 
0135     /**
0136      * Starts playing the media track.
0137      *
0138      * If the media track is already playing, this should have no effect.
0139      */
0140     virtual void play() = 0;
0141 
0142     /**
0143      * Stops playback of the media track and returns it to the beginning.
0144      */
0145     virtual void stop() = 0;
0146 
0147     /**
0148      * Moves the current playback position.
0149      *
0150      * This will have no effect if isSeekable() is @c false.
0151      *
0152      * @param msec  The new playback position in milliseconds.
0153      */
0154     virtual void seek(qlonglong msec) = 0;
0155 public:
0156     /**
0157      * Returns whether seek() can be expected to work on the current media
0158      * track.
0159      */
0160     virtual bool isSeekable() const = 0;
0161 
0162     /**
0163      * Returns the current playback position in milliseconds.
0164      */
0165     virtual qlonglong position() const = 0;
0166 
0167     /**
0168      * Returns whether the current media track has a length.
0169      */
0170     virtual bool hasLength() const = 0;
0171 
0172     /**
0173      * Returns the length of the current media track.
0174      *
0175      * The returned value is undefined if hasLength() returns @c false.
0176      */
0177     virtual qlonglong length() const = 0;
0178 
0179 public Q_SLOTS:
0180     /**
0181      * Sets whether playback should loop.
0182      *
0183      * @param on  If @c true, playback will resume from the start of the
0184      *            track when the end is reached; if @c false it will not.
0185      */
0186     void setLooping(bool on);
0187 public:
0188     /**
0189      * Returns whether playback will loop.
0190      */
0191     bool isLooping() const;
0192 Q_SIGNALS:
0193     /**
0194      * Indicates that the value of isLooping() has changed.
0195      *
0196      * @param isLooping  The new value.
0197      */
0198     void loopingChanged(bool isLooping);
0199 
0200 public:
0201     /**
0202      * The possible states of the player.
0203      */
0204     enum State {
0205         /**
0206          * No track is loaded.
0207          *
0208          * Most functions will not work in this state.
0209          */
0210         Empty,
0211         /**
0212          * A track is loaded, but playback is stopped.
0213          *
0214          * The position should always be 0 in this state. Playback will start
0215          * from the beginning when play() is called.
0216          */
0217         Stop,
0218         /**
0219          * Playback is temporarily suspended.
0220          *
0221          * Playback will resume from the current position when play() is called.
0222          */
0223         Pause,
0224         /**
0225          * The media is currently being output.
0226          */
0227         Play
0228     };
0229     /**
0230      * Returns the current state of the player.
0231      */
0232     State state() const;
0233 Q_SIGNALS:
0234     /**
0235      * Indicates that the value returned by state() has changed.
0236      *
0237      * @param newState  The new value.
0238      */
0239     void stateChanged(KMediaPlayer::Player::State newState);
0240 
0241 protected Q_SLOTS:
0242     /**
0243      * Sets the current state.
0244      *
0245      * This allows implementors to alter the playback state. This will emit the
0246      * stateChanged() signal as appropriate.
0247      */
0248     void setState(State state);
0249 
0250 protected:
0251     /* Enable the stateChanged(QString&, ...) method that was hidden by
0252        the stateChanged(State) signal */
0253     using KXMLGUIClient::stateChanged;
0254 
0255 private:
0256     std::unique_ptr<class PlayerPrivate> const d;
0257 };
0258 
0259 }
0260 
0261 Q_DECLARE_METATYPE(KMediaPlayer::Player::State)
0262 
0263 #endif