summaryrefslogtreecommitdiffstats
path: root/arts/kde/kplayobject.h
diff options
context:
space:
mode:
Diffstat (limited to 'arts/kde/kplayobject.h')
-rw-r--r--arts/kde/kplayobject.h306
1 files changed, 306 insertions, 0 deletions
diff --git a/arts/kde/kplayobject.h b/arts/kde/kplayobject.h
new file mode 100644
index 000000000..959e46810
--- /dev/null
+++ b/arts/kde/kplayobject.h
@@ -0,0 +1,306 @@
+ /*
+
+ Copyright (C) 2001 Nikolas Zimmermann <wildfox@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 as published by the Free Software Foundation; either
+ version 2 of the License, or (at your option) any later version.
+
+ 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., 51 Franklin Street, Fifth Floor,
+ Boston, MA 02110-1301, USA.
+
+ */
+
+#ifndef KPLAYOBJECT_H
+#define KPLAYOBJECT_H
+
+#include "kmedia2.h"
+#include "soundserver.h"
+#include <kurl.h>
+#include <qobject.h>
+
+class KDE_EXPORT KPlayObject : public QObject
+{
+Q_OBJECT
+public:
+ KPlayObject();
+ KPlayObject(Arts::PlayObject playobject, bool isStream);
+ ~KPlayObject();
+
+ /**
+ * Sets the internal Arts::PlayObject
+ * to @a playObject
+ */
+ void setObject(Arts::PlayObject playObject);
+
+ /**
+ * Returns the internal Arts::PlayObject
+ */
+ Arts::PlayObject object();
+
+ /**
+ * return true if both this != 0, and object.isNull()
+ *
+ * in essence, ((KPlayObject*)0)->isNull() will not
+ * crash
+ **/
+ bool isNull();
+
+ /**
+ * returns true if the internally playobject
+ * is used to play a stream
+ */
+ bool stream();
+
+ /**
+ * Reimplemented (Arts::PlayObject Wrapper)
+ */
+ void play();
+
+ /**
+ * Reimplemented (Arts::PlayObject Wrapper)
+ */
+ void seek(Arts::poTime newTime);
+
+ /**
+ * Reimplemented (Arts::PlayObject Wrapper)
+ */
+ void pause();
+
+ /**
+ * Reimplemented (Arts::PlayObject Wrapper)
+ */
+
+ void halt();
+
+ /**
+ * Reimplemented (Arts::PlayObject Wrapper)
+ */
+ QString description();
+
+ /**
+ * Reimplemented (Arts::PlayObject Wrapper)
+ */
+ Arts::poTime currentTime();
+
+ /**
+ * Reimplemented (Arts::PlayObject Wrapper)
+ */
+ Arts::poTime overallTime();
+
+ /**
+ * Reimplemented (Arts::PlayObject Wrapper)
+ */
+ Arts::poCapabilities capabilities();
+
+ /**
+ * Reimplemented (Arts::PlayObject Wrapper)
+ */
+ QString mediaName();
+
+ /**
+ * Reimplemented (Arts::PlayObject Wrapper)
+ */
+ Arts::poState state();
+
+private:
+ Arts::PlayObject m_playObject;
+ bool m_isStream;
+};
+
+
+
+namespace KDE {
+
+class PlayObjectFactory;
+
+/**
+ * This class acts as a general interface to the KDE multimedia framework.
+ * You basically point the Playobject to an URL and say "play", and it will
+ * automatically decode and play and / or display the file or stream.
+ * For non-local media, it will make extensive use of KIOInputStream to
+ * directly play the content from the remote location without having to
+ * download it to a temporary local file first.
+ *
+ * A KDE::PlayObject is never created directly with new, but only through
+ * a KDE::PlayObjectFactory.
+ *
+ * Basically, it is used like this:
+ * \code
+ * KArtsDispatcher dispatcher;
+ * KArtsServer server;
+ * KDE::PlayObjectFactory factory( server.server() );
+ * KDE::PlayObject* playobj = factory.createPlayObject( someURL, true );
+ * playobj->play();
+ * \endcode
+ *
+ * Internally, the KDE::PlayObject acts as a wrapper for an Arts::PlayObject.
+ *
+ * Special care needs to be taken for non-local media. In general, you
+ * cannot safely figure out the mimetype of the remote media content, by
+ * looking at the URL alone. You need to download some data to analyze
+ * the content. Since KDE::PlayObject is only a wrapper for an
+ * Arts::PlayObject, and an Arts::PlayObject needs to know the mimetype
+ * of the data it plays in order to pick the correct decoder, one cannot
+ * directly create an Arts::PlayObject and attach it to a stream. Therefore,
+ * the following approach is used.
+ *
+ * Whenever a the factory creates a KDE::PlayObject for a non-local content,
+ * it first generates a so called "Proxy" Playobject. This is a
+ * KDE::PlayObject that does not contain a real Arts::PlayObject yet.
+ * As soon as you invoke the play() method, a connection to the media
+ * source is made, and as soon as the mimetype is known, the appropriate
+ * Arts::PlayObject is created.
+ *
+ * This has some side effects that developers need to be aware of:
+ * Until the real Arts::PlayObject got created,
+ * - the capabilities() method returns "zero" capabilities,
+ * - description() and mediaName() will return a null QString,
+ * - currentTime() and overallTime() will return "zero",
+ * - despite the fact that isNull() returns "false", object().isNull()
+ * will return "true". If you need to directly access methods of the
+ * internal Arts::PlayObject, be sure to use object().isNull() to guard
+ * your access.
+ *
+ * A KDE::PlayObject will emit the signal playObjectCreated()
+ * as soon as the real internal Arts::PlayObject got created. This is also
+ * true for local media files. So you can generally connect to this signal
+ * and act on it if your application needs to know about the real capabilities
+ * of the Arts::PlayObject.
+ *
+ * However, KDE::PlayObject will try to act reasonable on calls to play(),
+ * halt(), pause() and state(). If you call play() and then pause()
+ * before the connection to the media source was established, it will
+ * not start playing once the connection got established. Calling halt()
+ * will cancel the connection process. KDE::PlayObject will maintain
+ * an internal state variable, and calling state() will return this
+ * internal state until the real Arts::PlayObject got created, afterwards
+ * the state of the Arts::PlayObject will be returned.
+ */
+class KDE_EXPORT PlayObject : public QObject
+{
+Q_OBJECT
+public:
+ ~PlayObject();
+
+ /**
+ * Returns the internal Arts::PlayObject
+ */
+ Arts::PlayObject object();
+
+ /**
+ * return true if this != 0.
+ *
+ * in essence, ((KDE::PlayObject*)0)->isNull() will not
+ * crash
+ **/
+ bool isNull();
+
+ /**
+ * returns "true" if the content to play is delivered as a stream.
+ */
+ bool stream();
+
+ /**
+ * causes the PlayObject to start the play back.
+ */
+ void play();
+
+ /**
+ * causes the PlayObject to skip to the time @p newTime.
+ * You don't need to stop or restart the play back after calling seek.
+ */
+ void seek(Arts::poTime newTime);
+
+ /**
+ * causes the PlayObject to pause play back immediately. It will not
+ * restart until you call play(). This also works on streams, the
+ * connection to the media source will be maintained while the
+ * PlayObject is paused.
+ */
+ void pause();
+
+ /**
+ * immediately stops the play back and resets the media to the
+ * start of the content. If playing from a stream, halt() causes
+ * the connection to be canceled.
+ */
+
+ void halt();
+
+ /**
+ * Reimplemented (Arts::PlayObject Wrapper)
+ */
+ QString description();
+
+ /**
+ * Reimplemented (Arts::PlayObject Wrapper)
+ */
+ Arts::poTime currentTime();
+
+ /**
+ * Reimplemented (Arts::PlayObject Wrapper)
+ */
+ Arts::poTime overallTime();
+
+ /**
+ * returns the capabilities of the PlayObject. The return value is
+ * a binary OR of Arts::capSeek and Arts::capPause, or 0.
+ */
+ Arts::poCapabilities capabilities();
+
+ /**
+ * Reimplemented (Arts::PlayObject Wrapper)
+ */
+ QString mediaName();
+
+ /**
+ * returns the internal state of the PlayObject. The state can be
+ * either Arts::posIdle, Arts::posPaused or Arts::posPlaying. A
+ * PlayObject in state Arts::posIdle is stopped. Once you call
+ * play(), the state changes to Arts::posPlaying. pause() causes
+ * the PlayObject to change to Arts::posPaused.
+ */
+ Arts::poState state();
+
+signals:
+ /**
+ * this signal is emitted as soon as the internal Arts::PlayObject
+ * is created and ready to play. It is granted that the Arts::PlayObject
+ * has not started playing, but KDE::PlayObject will call
+ * object().play() immediately after emitting this signal, so you
+ * need not do it yourself.
+ */
+ void playObjectCreated();
+
+private slots:
+ void attachPlayObject( Arts::PlayObject );
+
+private:
+ Arts::PlayObject m_playObject;
+ bool m_isStream;
+
+ struct PrivateData;
+ PrivateData* d;
+
+ /* private constructors, to prevent instantiation and copying */
+ PlayObject();
+ PlayObject( const PlayObject& ) : QObject() {};
+ PlayObject(Arts::PlayObject playobject, bool isStream);
+ PlayObject( Arts::SoundServerV2 server, const KURL& url, bool isStream, bool createBUS );
+
+ friend class KDE::PlayObjectFactory;
+
+};
+
+}
+
+#endif