KDE::PlayObject Class Reference

`#include <kplayobject.h>`

Inherits QObject.

## Signals

void | playObjectCreated ()

## Public Member Functions

Arts::PlayObject | object ()
bool | isNull ()
bool | stream ()
void | play ()
void | seek (Arts::poTime newTime)
void | pause ()
void | halt ()
QString | description ()
Arts::poTime | currentTime ()
Arts::poTime | overallTime ()
Arts::poCapabilities | capabilities ()
QString | mediaName ()
Arts::poState | state ()

## Friends

class | KDE::PlayObjectFactory

## Detailed Description

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:

KArtsDispatcher dispatcher;
KArtsServer server;
KDE::PlayObjectFactory factory( server.server() );
KDE::PlayObject* playobj = factory.createPlayObject( someURL, true );
playobj->play();

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.

Definition at line 188 of file kplayobject.h.

## Member Function Documentation

Arts::poCapabilities KDE::PlayObject::capabilities | ( |  | ) |

returns the capabilities of the PlayObject.

The return value is a binary OR of Arts::capSeek and Arts::capPause, or 0.

Definition at line 263 of file kplayobject.cc.

Arts::poTime KDE::PlayObject::currentTime | ( |  | ) |

Reimplemented (Arts::PlayObject Wrapper)

Definition at line 249 of file kplayobject.cc.

QString KDE::PlayObject::description | ( |  | ) |

Reimplemented (Arts::PlayObject Wrapper)

Definition at line 242 of file kplayobject.cc.

void KDE::PlayObject::halt | ( |  | ) |

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.

Definition at line 229 of file kplayobject.cc.

bool KDE::PlayObject::isNull | ( |  | ) |

return true if this != 0.

in essence, ((KDE::PlayObject*)0)->isNull() will not crash

Definition at line 289 of file kplayobject.cc.

QString KDE::PlayObject::mediaName | ( |  | ) |

Reimplemented (Arts::PlayObject Wrapper)

Definition at line 270 of file kplayobject.cc.

Arts::PlayObject KDE::PlayObject::object | ( |  | ) |

Returns the internal Arts::PlayObject.

Definition at line 284 of file kplayobject.cc.

Arts::poTime KDE::PlayObject::overallTime | ( |  | ) |

Reimplemented (Arts::PlayObject Wrapper)

Definition at line 256 of file kplayobject.cc.

void KDE::PlayObject::pause | ( |  | ) |

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.

Definition at line 222 of file kplayobject.cc.

void KDE::PlayObject::play | ( |  | ) |

causes the PlayObject to start the play back.

Definition at line 173 of file kplayobject.cc.

void KDE::PlayObject::playObjectCreated | ( |  | ) |

signal

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 KDE::PlayObject::seek | ( | Arts::poTime | newTime | ) |

causes the PlayObject to skip to the time `newTime`.

You don't need to stop or restart the play back after calling seek.

Definition at line 212 of file kplayobject.cc.

Arts::poState KDE::PlayObject::state | ( |  | ) |

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.

Definition at line 277 of file kplayobject.cc.

bool KDE::PlayObject::stream | ( |  | ) |

returns "true" if the content to play is delivered as a stream.

Definition at line 298 of file kplayobject.cc.

The documentation for this class was generated from the following files:

- kplayobject.h
- kplayobject.cc

KDE Home | KDE Accessibility Home | Description of Access Keys