|  | Home · All Classes · Main Classes · Grouped Classes · Modules · Functions |

# Path Class Reference
(Phonon::Path)
[Phonon module]

Connection object providing convenient effect insertion More...

- List of all members, including inherited members

### Public Functions

- Path ()
- Path ( const Path & )
- ~Path ()
- bool disconnect ()
- QList<Effect *> effects () const
- Effect * insertEffect ( const EffectDescription & desc, Effect * insertBefore = 0 )
- bool insertEffect ( Effect * newEffect, Effect * insertBefore = 0 )
- bool isValid () const
- bool reconnect ( MediaNode * source, MediaNode * sink )
- bool removeEffect ( Effect * effect )
- bool operator!= ( const Path & p ) const
- Path & operator= ( const Path & p )
- bool operator== ( const Path & p ) const

### Related Non-Members

- Path createPath ( MediaNode * source, MediaNode * sink )

## Detailed Description

Connection object providing convenient effect insertion

         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 effect
         QList<EffectDescription> effectList = BackendCapabilities::availableAudioEffects();
         if (!effectList.isEmpty()) {
             Effect *effect = path.insertEffect(effectList.first());
         }

Author: Matthias Kretz <kretz@kde.org> Author: Thierry Bastian <thierry.bastian@trolltech.com>

## Member Function Documentation

### Path::Path ()

Creates an invalid path.

You can still make it a valid path by calling reconnect. To create a path you should use createPath, though.

See also Phonon::createPath() and isValid().

### Path::Path ( const Path & )

Constructs a copy of the given path.

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 also disconnect().

### 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 also insertEffect() and removeEffect().

### Effect * Path::insertEffect ( const EffectDescription & 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 the EffectDescription object for the effect to be inserted.

If you already inserted an effect you can tell with insertBefore in which order the data gets processed. If this is `0` 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 return `false`.

Returns a pointer to the effect object if it could be inserted at the specified position. If `0` 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 also removeEffect() and effects().

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

This is an overloaded member function, provided for convenience.

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.

newEffect An Effect object.

insertBefore If you already inserted an effect you can tell with this parameter in which order the data gets processed. If this is `0` 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 return `false`.

Returns Returns whether the effect could be inserted at the specified position. If `false` is returned the effect was not inserted.

See also removeEffect() and effects().

### bool Path::isValid () const

Returns whether the path object connects two MediaNodes or not.

Returns true when the path connects two MediaNodes Returns false when the path is disconnected

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

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

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

### bool Path::removeEffect ( Effect * effect )

Removes an effect from the path.

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

effect The effect to be removed.

Returns Returns whether the call was successful. If it returns `false` the effect could not be found in the path, meaning it has not been inserted before.

See also insertEffect() and effects().

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

Returns true if this Path is not equal to p; otherwise returns false;

### Path & Path::operator= ( const Path & p )

Assigns p to this Path and returns a reference to this Path.

This operation is fast thanks to explicit sharing.

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

Returns true if this Path is equal to p; otherwise returns false;

## Related Non-Members

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

Creates a new Path connecting the two MediaNodes source and sink.

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

source The MediaNode to connect an output from sink The MediaNode to connect to.