.TH "KDE::PlayObject" kde3 "11 Jun 2005" "Version Version 3.4.1" "arts Library" \" -*- nroff -*-
.ad l
.nh
.SH NAME
KDE::PlayObject \- This class acts as a general interface to the \fBKDE\fP multimedia framework.  

.PP
.SH SYNOPSIS
.br
.PP
\fC#include <kplayobject.h>\fP
.PP
Inherits \fBQObject\fP.
.PP
.SS "Signals"

.in +1c
.ti -1c
.RI "void \fBplayObjectCreated\fP ()"
.br
.in -1c
.SS "Public Member Functions"

.in +1c
.ti -1c
.RI "Arts::PlayObject \fBobject\fP ()"
.br
.ti -1c
.RI "bool \fBisNull\fP ()"
.br
.ti -1c
.RI "bool \fBstream\fP ()"
.br
.ti -1c
.RI "void \fBplay\fP ()"
.br
.ti -1c
.RI "void \fBseek\fP (Arts::poTime newTime)"
.br
.ti -1c
.RI "void \fBpause\fP ()"
.br
.ti -1c
.RI "void \fBhalt\fP ()"
.br
.ti -1c
.RI "\fBQString\fP \fBdescription\fP ()"
.br
.ti -1c
.RI "Arts::poTime \fBcurrentTime\fP ()"
.br
.ti -1c
.RI "Arts::poTime \fBoverallTime\fP ()"
.br
.ti -1c
.RI "Arts::poCapabilities \fBcapabilities\fP ()"
.br
.ti -1c
.RI "\fBQString\fP \fBmediaName\fP ()"
.br
.ti -1c
.RI "Arts::poState \fBstate\fP ()"
.br
.in -1c
.SS "Friends"

.in +1c
.ti -1c
.RI "class \fBKDE::PlayObjectFactory\fP"
.br
.in -1c
.SH "Detailed Description"
.PP 
This class acts as a general interface to the \fBKDE\fP 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.
.PP
A KDE::PlayObject is never created directly with new, but only through a \fBKDE::PlayObjectFactory\fP.
.PP
Basically, it is used like this: 
.PP
.nf
 KArtsDispatcher dispatcher;
 KArtsServer server;
 KDE::PlayObjectFactory factory( server.server() );
 KDE::PlayObject* playobj = factory.createPlayObject( someURL, true );
 playobj->play();

.fi
.PP
.PP
Internally, the KDE::PlayObject acts as a wrapper for an Arts::PlayObject.
.PP
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.
.PP
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 \fBplay()\fP method, a connection to the media source is made, and as soon as the mimetype is known, the appropriate Arts::PlayObject is created.
.PP
This has some side effects that developers need to be aware of: Until the real Arts::PlayObject got created,
.IP "\(bu" 2
the \fBcapabilities()\fP method returns 'zero' capabilities,
.IP "\(bu" 2
\fBdescription()\fP and \fBmediaName()\fP will return a null \fBQString\fP,
.IP "\(bu" 2
\fBcurrentTime()\fP and \fBoverallTime()\fP will return 'zero',
.IP "\(bu" 2
despite the fact that \fBisNull()\fP returns 'false', \fBobject()\fP.\fBisNull()\fP will return 'true'. If you need to directly access methods of the internal Arts::PlayObject, be sure to use \fBobject()\fP.\fBisNull()\fP to guard your access.
.PP
.PP
A KDE::PlayObject will emit the signal \fBplayObjectCreated()\fP 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.
.PP
However, KDE::PlayObject will try to act reasonable on calls to \fBplay()\fP, \fBhalt()\fP, \fBpause()\fP and \fBstate()\fP. If you call \fBplay()\fP and then \fBpause()\fP before the connection to the media source was established, it will not start playing once the connection got established. Calling \fBhalt()\fP will cancel the connection process. KDE::PlayObject will maintain an internal state variable, and calling \fBstate()\fP will return this internal state until the real Arts::PlayObject got created, afterwards the state of the Arts::PlayObject will be returned. 
.PP
Definition at line 188 of file kplayobject.h.
.SH "Member Function Documentation"
.PP 
.SS "Arts::PlayObject KDE::PlayObject::object ()"
.PP
Returns the internal Arts::PlayObject. 
.PP
Definition at line 284 of file kplayobject.cc.
.PP
Referenced by capabilities(), currentTime(), description(), halt(), isNull(), mediaName(), overallTime(), pause(), play(), seek(), and state().
.SS "bool KDE::PlayObject::isNull ()"
.PP
return true if this != 0. 
.PP
in essence, ((KDE::PlayObject*)0)->\fBisNull()\fP will not crash 
.PP
Definition at line 289 of file kplayobject.cc.
.PP
References QString::isNull(), and object().
.PP
Referenced by capabilities(), currentTime(), description(), halt(), mediaName(), overallTime(), pause(), play(), seek(), and state().
.SS "bool KDE::PlayObject::stream ()"
.PP
returns 'true' if the content to play is delivered as a stream. 
.PP

.PP
Definition at line 298 of file kplayobject.cc.
.SS "void KDE::PlayObject::play ()"
.PP
causes the \fBPlayObject\fP to start the play back. 
.PP

.PP
Definition at line 173 of file kplayobject.cc.
.PP
References endl(), isNull(), kdDebug(), and object().
.SS "void KDE::PlayObject::seek (Arts::poTime newTime)"
.PP
causes the \fBPlayObject\fP to skip to the time \fCnewTime\fP. 
.PP
You don't need to stop or restart the play back after calling seek.
.PP
Definition at line 212 of file kplayobject.cc.
.PP
References endl(), isNull(), kdDebug(), and object().
.SS "void KDE::PlayObject::pause ()"
.PP
causes the \fBPlayObject\fP to pause play back immediately. 
.PP
It will not restart until you call \fBplay()\fP. This also works on streams, the connection to the media source will be maintained while the \fBPlayObject\fP is paused.
.PP
Definition at line 222 of file kplayobject.cc.
.PP
References isNull(), and object().
.SS "void KDE::PlayObject::halt ()"
.PP
immediately stops the play back and resets the media to the start of the content. 
.PP
If playing from a stream, \fBhalt()\fP causes the connection to be canceled.
.PP
Definition at line 229 of file kplayobject.cc.
.PP
References endl(), isNull(), kdDebug(), and object().
.SS "\fBQString\fP KDE::PlayObject::description ()"
.PP
Reimplemented (Arts::PlayObject Wrapper). 
.PP
Definition at line 242 of file kplayobject.cc.
.PP
References QString::fromLatin1(), isNull(), and object().
.SS "Arts::poTime KDE::PlayObject::currentTime ()"
.PP
Reimplemented (Arts::PlayObject Wrapper). 
.PP
Definition at line 249 of file kplayobject.cc.
.PP
References isNull(), and object().
.SS "Arts::poTime KDE::PlayObject::overallTime ()"
.PP
Reimplemented (Arts::PlayObject Wrapper). 
.PP
Definition at line 256 of file kplayobject.cc.
.PP
References isNull(), and object().
.SS "Arts::poCapabilities KDE::PlayObject::capabilities ()"
.PP
returns the capabilities of the \fBPlayObject\fP. 
.PP
The return value is a binary OR of Arts::capSeek and Arts::capPause, or 0.
.PP
Definition at line 263 of file kplayobject.cc.
.PP
References isNull(), and object().
.SS "\fBQString\fP KDE::PlayObject::mediaName ()"
.PP
Reimplemented (Arts::PlayObject Wrapper). 
.PP
Definition at line 270 of file kplayobject.cc.
.PP
References QString::fromLatin1(), isNull(), and object().
.SS "Arts::poState KDE::PlayObject::state ()"
.PP
returns the internal state of the \fBPlayObject\fP. 
.PP
The state can be either Arts::posIdle, Arts::posPaused or Arts::posPlaying. A \fBPlayObject\fP in state Arts::posIdle is stopped. Once you call \fBplay()\fP, the state changes to Arts::posPlaying. \fBpause()\fP causes the \fBPlayObject\fP to change to Arts::posPaused.
.PP
Definition at line 277 of file kplayobject.cc.
.PP
References isNull(), and object().
.SS "void KDE::PlayObject::playObjectCreated ()\fC [signal]\fP"
.PP
this signal is emitted as soon as the internal Arts::PlayObject is created and ready to play. 
.PP
It is granted that the Arts::PlayObject has not started playing, but KDE::PlayObject will call \fBobject()\fP.\fBplay()\fP immediately after emitting this signal, so you need not do it yourself.

.SH "Author"
.PP 
Generated automatically by Doxygen for arts Library from the source code.
