Contents

• Public Functions
• Related Non-Members
• Detailed Description

Detailed Description

The Path class describes connections between media nodes.

In amedia graph,MediaNodes are connected by Paths. The multimedia travels in streams over these paths.

You create a path between two media nodes using the static Phonon::createPath() function, which takes two nodes as arguments. The first argument will send the media stream to the second. Please refer to the class description of the individual media nodes and the Phononoverview to see which nodes can be connected to each other.

Paths are also used to insert audioEffects between two media nodes. The effect will then alter the stream on the path. Notice thatEffects also are media nodes, but thatinsertEffect() - instead of Phonon::createPath() - is used to insert them into the media graph.

The following code example shows how to create a path between two media nodes and insert an effect on that path.

MediaObject*media=new MediaObject;AudioOutput*output=new AudioOutput(Phonon::MusicCategory);Path path= Phonon::createPath(media, output);Q_ASSERT(path.isValid());// for this simple case the path should always be//valid - there are unit tests to ensure it// insert an effectQList<EffectDescription> effectList= BackendCapabilities::availableAudioEffects();if (!effectList.isEmpty()) {    Effect*effect= path.insertEffect(effectList.first());}

Member Function Documentation

Path::Path()

Creates an invalid path.

You can still make it a valid path by calling reconnect. It is recommended to use the Phonon::createPath() function to create paths.

See alsoPhonon::createPath() andisValid().

Path::Path(constPath & path)

Constructs a copy of the otherpath specified.

This constructor is fast thanks to explicit sharing.

Path::~Path()

Destroys this reference to the Path. If the path was valid the connection is not broken as both the source and the sink MediaNodes still keep a reference to the Path.

See alsodisconnect().

bool Path::disconnect()

Tries to disconnect the path from the MediaNodes it is connected to, returning true if successful or false if unsuccessful.

If successful, the path is invalidated:isValid() will returns false.

QList<Effect *> Path::effects() const

Returns a list of Effect objects that are currently used as effects. The order in the list determines the order the signal is sent through the effects.

Returns A list with all current effects.

See alsoinsertEffect() andremoveEffect().

Effect * Path::insertEffect(constEffectDescription & desc,Effect * insertBefore = 0)

Creates and inserts an effect into the path.

You may insert effects of the same class as often as you like, but if you insert the same object, the call will fail.

desc is theEffectDescription object for the effect to be inserted.

If you already inserted an effect you can tell withinsertBefore in which order the data gets processed. If this is0 the effect is appended at the end of the processing list. If the effect has not been inserted before the method will do nothing and returnfalse.

Returns a pointer to the effect object if it could be inserted at the specified position. If0 is returned, the effect was not inserted.

Below is a code example for inserting an effect into a path:

QList<Phonon::EffectDescription> effectDescriptions=            Phonon::BackendCapabilities::availableAudioEffects();    Phonon::EffectDescription effectDescription= effectDescriptions.at(4);    Phonon::Path path= Phonon::createPath(mediaObject, audioOutput);    Phonon::Effect*effect=new Phonon::Effect(effectDescription);    path.insertEffect(effect);

See alsoremoveEffect() andeffects().

bool Path::insertEffect(Effect * effect,Effect * insertBefore = 0)

Inserts the giveneffect into the path before the effect specified byinsertBefore and returns true if successful; otherwise returns false.

IfinsertBefore is zero, the effect is appended to the processing list.

You may insert effects of the same class as often as you like, but if you insert the same object, the call will fail.

effect will be inserted right beforeinsertBefore. IfinsertBefore is0, the effect is appended at the end of the processing list. If the effect has not been inserted before the method will do nothing and returnfalse.

Returns whether the effect could be inserted at the specified position. Iffalse is returned the effect was not inserted.

See alsoremoveEffect() andeffects().

bool Path::isValid() const

A path is considered valid if it is connected to two media nodes, in which case this function returns true. If it is connected to one or no media nodes, it is consider invalid, and this function will then return false.

bool Path::reconnect(MediaNode * source,MediaNode * sink)

Changes the media nodes the path is connected to by connecting the path to thesource andsink nodes specified. Returns true if successful; otherwise returns false.

If unsuccessful, the path remains connected to the same nodes as before.

See alsoPhonon::createPath() andPhonon Overview.

bool Path::removeEffect(Effect * effect)

Removes the giveneffect from the path and returns true; otherwise returns false.

Removes aneffect from the path.

If the effect is deleted while it is still connected, the effect will be removed automatically.

See alsoinsertEffect() andeffects().

MediaNode * Path::sink() const

Returns the sinkMediaNode used by the path.

MediaNode * Path::source() const

Returns the sourceMediaNode used by the path.

bool Path::operator!=(constPath & p) const

Returns true if this Path is not equal top; otherwise returns false.

Path & Path::operator=(constPath & p)

Assignsp to this Path and returns a reference to this Path.

This operation is fast thanks to explicit sharing.

bool Path::operator==(constPath & p) const

Returns true if this Path is equal top; otherwise returns false;

Related Non-Members

Path Phonon::createPath(MediaNode * source,MediaNode * sink)

Creates a new Path connecting the two MediaNodessource andsink.

The implementation will automatically select the right format and media type. E.g. connecting aMediaObject andAudioOutput will create a Path object connecting the audio. This might be represented as PCM or perhaps even AC3 depending on theAudioOutput object.

source TheMediaNode to connect an output fromsink TheMediaNode to connect to.