diff options
Diffstat (limited to 'kdemm/player.h')
| -rw-r--r-- | kdemm/player.h | 259 |
1 files changed, 259 insertions, 0 deletions
diff --git a/kdemm/player.h b/kdemm/player.h new file mode 100644 index 000000000..b753073a7 --- /dev/null +++ b/kdemm/player.h @@ -0,0 +1,259 @@ +/* This file is part of the KDE project + Copyright (C) 2004 Matthias Kretz <kretz@kde.org> + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public + License version 2 as published by the Free Software Foundation. + + 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 + Library General Public License for more details. + + You should have received a copy of the GNU Library General Public License + along with this library; see the file COPYING.LIB. If not, write to + the Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. + +*/ + +#ifndef PLAYOBJECT_H +#define PLAYOBJECT_H + +#include <kdelibs_export.h> +#include <tqobject.h> + +class KURL; + +namespace KDE +{ +namespace Multimedia +{ + class Channel; + /** + * \short Interface for accessing media playback functions + * + * \author Matthias Kretz <kretz@kde.org> + * \since 4.0 + */ + class Player : public QObject + { + Q_OBJECT + public: + /** + * The state the playobject is in at the moment + */ + enum State + { + /** + * The load method wasn't called or didn't succeed. If the + * object is in this state the next thing you have to do is to + * call load. + */ + NoMedia, + /** + * After calling load it might take a while before the Player is + * ready to play(). Normally this doesn't happen for local + * files, but can happen for remote files where the asynchronous + * mimetype detection can take a while. + */ + Loading, + /** + * The Player has a valid media file loaded and is ready for + * playing. + */ + Stopped, + /** + * The Player is playing a media file. + */ + Playing, + /** + * The Player is waiting for data to be able to continue + * playing. + */ + Buffering, + /** + * The Player is paused currently. + */ + Paused + }; + + virtual ~Player(); + + /** + * Set the output device the Player should use. + * + * @return Returns \p true on success. If it returns \p false the + * output device wasn't changed. This could happen if you pass a + * Channel with Channel::direction() == Channel::Input. + */ + virtual bool setOutputChannel( Channel * device ) = 0; + + /** + * Get the current state. + */ + virtual State state() const; + + /** + * Check whether the Player supports to control the volume. + * + * @returns Return \p true if the Player can change its volume. + */ + virtual bool hasVolumeControl() const = 0; + + /** + * Get the current volume. + * + * @returns the current volume + */ + virtual float volume() const = 0; + + /** + * Get the total time (in milliseconds) of the file currently being played. + */ + virtual long totalTime() const = 0; + + /** + * Get the remaining time (in milliseconds) of the file currently being played. + */ + virtual long remainingTime() const = 0; + + /** + * Get the current time (in milliseconds) of the file currently being played. + */ + virtual long currentTime() const = 0; + + /** + * If the current media may be seeked returns true. + * + * @returns whether the current media may be seeked. + */ + virtual bool seekable() const = 0; + + /** + * Return the time interval in milliseconds between two ticks. + */ + virtual long tickInterval() const = 0; + + public slots: + /** + * Load a media file. If another media is currently loaded it is + * stopped and unloaded. + * + * @param url The location of the media file + * + * @returns If the call was successfull (the media file was found + * and can be read and decoded) returns \p true + */ + virtual bool load( const KURL & url ) = 0; + + /** + * Play the media file. + */ + virtual bool play() = 0; + + /** + * Pause a playing media. If it was paused before nothing changes. + */ + virtual bool pause() = 0; + + /** + * Stop a playback. + */ + virtual bool stop() = 0; + + /** + * Set the volume of the playback + * + * @param volume 0.0 is complete silence and 1.0 is full volume. + * Higher values than 1.0 are possible but might + * result in distortion of the sound. + * + * @returns returns \p true if the call was successfull, returns \p + * false if the volume change didn't work and therefor didn't + * change. + */ + virtual bool setVolume( float volume ) = 0; + + /** + * Seek to the time indicated. + * + * @param time The time in milliseconds where to continue playing. + * + * @returns whether the seek was successfull. + */ + virtual bool seek( long time ) = 0; + + /** + * Change the interval the tick signal is emitted. If you set \p ms + * to 0 the signal gets disabled. + * + * \param ms tick interval in milliseconds + * + * @returns Returns \p true if the tick intervall was changed. + */ + virtual bool setTickInterval( long ms ) = 0; + + signals: + /** + * Emitted when the file has finished playing on its own. + * I.e. it is not emitted if you call stop(), pause() or + * load(), but only on end-of-file or a critical error. + */ + void finished(); + + //XXX do we want a aboutToFinish() signal? + + /** + * Emitted when the state of the Player has changed. + * In case you're not interested in the old state you can also + * connect to a slot that only has one State argument. + * + * @param newstate The state the Player is in now + * @param oldstate The state the Player was in before + */ + void stateChanged( KDE::Multimedia::Player::State newstate, KDE::Multimedia::Player::State oldstate ); + + /** + * This signal gets emitted every tickInterval milliseconds. + * + * \param time The position of the media file in milliseconds. + * + * \see setTickInterval, tickInterval + */ + void tick( long time ); + + /** + * This signal is emitted as soon as the length of the media file is + * known or has changed. + * + * @param length The length of the media file in milliseconds. + */ + void length( long length ); + + protected: + /** + * You can not instantiate players yourself, use the Factory to + * create them. + */ + Player( TQObject * parent, const char * name ); + + /** + * Call this in your reimplementation for state changes. + * It emits the stateChanged signal if the state has really changed. + * + * @param newstate The new state of the Player. If \p newstate is + * equal to the old state() the call will be ignored. + */ + void setState( State newstate ); + + private: + class Private; + Private * d; + + State m_state; + }; +}} //namespaces + +// vim: sw=4 ts=4 tw=80 noet +#endif // PLAYOBJECT_H |