From 683a9a9f7fabd23ed9caf7ab18cb90dacb51da2d Mon Sep 17 00:00:00 2001 From: trialuser02 Date: Fri, 13 Mar 2009 20:58:52 +0000 Subject: SoundCore class documentation, fixed other documentation git-svn-id: http://svn.code.sf.net/p/qmmp-dev/code/trunk/qmmp@847 90c681e8-e032-0410-971d-27865f9a5e38 --- src/qmmp/buffer.h | 21 ++++-- src/qmmp/decoder.h | 9 +-- src/qmmp/decoderfactory.h | 12 ++-- src/qmmp/effect.h | 4 +- src/qmmp/effectfactory.h | 6 +- src/qmmp/fileinfo.h | 62 +++++++++++++++--- src/qmmp/output.h | 2 +- src/qmmp/outputfactory.h | 8 +-- src/qmmp/qmmp.h | 64 ++++++++++++++++-- src/qmmp/recycler.h | 68 +++++++++++++++---- src/qmmp/soundcore.h | 134 ++++++++++++++++++++++++++------------ src/qmmp/statehandler.h | 93 ++++++++++++++++++++++---- src/qmmp/visual.h | 6 +- src/qmmp/visualfactory.h | 6 +- src/qmmp/volumecontrol.h | 79 ++++++++++++++++++---- src/qmmpui/abstractplaylistitem.h | 2 +- src/qmmpui/commandlinemanager.h | 2 +- src/qmmpui/filedialog.h | 9 ++- src/qmmpui/filedialogfactory.h | 3 +- src/qmmpui/fileloader.h | 2 +- src/qmmpui/general.h | 8 +-- src/qmmpui/generalfactory.h | 8 +-- src/qmmpui/generalhandler.h | 10 +-- src/qmmpui/mediaplayer.h | 2 +- src/qmmpui/playlistitem.h | 5 +- src/qmmpui/playlistmodel.h | 22 +++---- src/qmmpui/playlistparser.h | 2 +- src/qmmpui/playstate.h | 4 +- 28 files changed, 485 insertions(+), 168 deletions(-) diff --git a/src/qmmp/buffer.h b/src/qmmp/buffer.h index 6c9e84f21..13fd42e0e 100644 --- a/src/qmmp/buffer.h +++ b/src/qmmp/buffer.h @@ -9,13 +9,15 @@ #include "constants.h" -/*! +/*! @brief Audio buffer class. * @author Brad Hughes */ - class Buffer { public: + /*! + * Constructs an empty buffer object. + */ Buffer() { data = new unsigned char[Buffer::size()]; @@ -23,6 +25,9 @@ public: rate = 0; exceeding = 0; } + /*! + * Destructor. + */ ~Buffer() { delete data; @@ -32,11 +37,13 @@ public: exceeding = 0; } - unsigned char *data; - unsigned long nbytes; - unsigned long rate; - unsigned long exceeding; - + unsigned char *data; /*!< Audio data */ + unsigned long nbytes; /*!< Audio data size */ + unsigned long rate; /*!< Buffer bitrate */ + unsigned long exceeding; /*!< The number of bytes on which the size of buffer exceeds the size of the block */ + /*! + * Returns block size. + */ static unsigned long size() { return globalBlockSize; diff --git a/src/qmmp/decoder.h b/src/qmmp/decoder.h index 224ffc33e..8093ad58e 100644 --- a/src/qmmp/decoder.h +++ b/src/qmmp/decoder.h @@ -106,7 +106,7 @@ public: StateHandler *stateHandler(); /*! * Sets StateHandler pointer. May be used to override default state handler. - * @param hanlder StateHandler pointer; + * @param handler StateHandler pointer; */ void setStateHandler(StateHandler *handler); /*! @@ -120,7 +120,7 @@ public: */ virtual void setEQEnabled(bool on); /*! - * Returns \b true if \b file is supported by input plugins, otherwise \b false + * Returns \b true if \b file is supported by input plugins, otherwise returns \b false */ static bool supports(const QString &file); /*! @@ -166,11 +166,11 @@ public: /*! * Sets whether the input plugin is enabled. * @param factory Decoder plugin factory. - * @param enabled Plugin enable state (\b true - enable, \b false - disable) + * @param enable Plugin enable state (\b true - enable, \b false - disable) */ static void setEnabled(DecoderFactory* factory, bool enable = TRUE); /*! - * Returns \b true if input plugin is enabled, otherwise \b false + * Returns \b true if input plugin is enabled, otherwise returns \b false * @param factory Decoder plugin factory. */ static bool isEnabled(DecoderFactory* factory); @@ -193,6 +193,7 @@ protected: * Sends audio data to the output plugin. * @param data Pointer to audio data. * @param size Audio data size. + * @param brate Current bitrate (in kbps) * @param chan Number of channels. */ qint64 produceSound(char *data, qint64 size, quint32 brate, int chan); diff --git a/src/qmmp/decoderfactory.h b/src/qmmp/decoderfactory.h index cd7345e32..f96057e97 100644 --- a/src/qmmp/decoderfactory.h +++ b/src/qmmp/decoderfactory.h @@ -54,10 +54,10 @@ public: QString description; /*!< File filter description */ QString contentType; /*!< Supported content types */ QString protocols; /*!< Supported protocols. Should be empty if plugin uses stream input. */ - bool hasAbout; /*!< Should be \b true if plugin has about dialog, otherwise \b false */ - bool hasSettings; /*!< Should be \b true if plugin has settings dialog, otherwise \b false */ - bool noInput; /*!< Should be \b true if plugin has own input, otherwise \b false */ - bool noOutput; /*!< Should be \b true if plugin has own output, otherwise \b false */ + bool hasAbout; /*!< Should be \b true if plugin has about dialog, otherwise returns \b false */ + bool hasSettings; /*!< Should be \b true if plugin has settings dialog, otherwise returns \b false */ + bool noInput; /*!< Should be \b true if plugin has own input, otherwise returns \b false */ + bool noOutput; /*!< Should be \b true if plugin has own output, otherwise returns \b false */ }; /*! @brief Input plugin interface (decoder factory). * @author Ilya Kotov @@ -70,11 +70,11 @@ public: */ virtual ~DecoderFactory() {} /*! - * Returns \b true if plugin supports \b source, otherwise \b false + * Returns \b true if plugin supports \b source, otherwise returns \b false */ virtual bool supports(const QString &source) const = 0; /*! - * Returns \b true if plugin can decode data provided by \b d, otherwise \b false + * Returns \b true if plugin can decode data provided by \b d, otherwise returns \b false */ virtual bool canDecode(QIODevice *d) const = 0; /*! diff --git a/src/qmmp/effect.h b/src/qmmp/effect.h index 7d0e325b1..2ed82269c 100644 --- a/src/qmmp/effect.h +++ b/src/qmmp/effect.h @@ -85,11 +85,11 @@ public: /*! * Sets whether the effect plugin is enabled. * @param factory Effect plugin factory. - * @param enabled Plugin enable state (\b true - enable, \b false - disable) + * @param enable Plugin enable state (\b true - enable, \b false - disable) */ static void setEnabled(EffectFactory* factory, bool enable = TRUE); /*! - * Returns \b true if input plugin is enabled, otherwise \b false + * Returns \b true if input plugin is enabled, otherwise returns \b false * @param factory Effect plugin factory. */ static bool isEnabled(EffectFactory* factory); diff --git a/src/qmmp/effectfactory.h b/src/qmmp/effectfactory.h index 8ca8f2af2..b22580e59 100644 --- a/src/qmmp/effectfactory.h +++ b/src/qmmp/effectfactory.h @@ -43,10 +43,10 @@ public: } QString name; /*!< Effect plugin full name */ QString shortName; /*!< Effect plugin short name for internal usage */ - bool hasAbout; /*!< Should be \b true if plugin has about dialog, otherwise \b false */ - bool hasSettings; /*!< Should be \b true if plugin has settings dialog, otherwise \b false */ + bool hasAbout; /*!< Should be \b true if plugin has about dialog, otherwise returns \b false */ + bool hasSettings; /*!< Should be \b true if plugin has settings dialog, otherwise returns \b false */ }; -/*! @brief Effect plugin interface (effect factory). +/*! @brief %Effect plugin interface (effect factory). * @author Ilya Kotov */ class EffectFactory diff --git a/src/qmmp/fileinfo.h b/src/qmmp/fileinfo.h index 418d78795..e2e04e57e 100644 --- a/src/qmmp/fileinfo.h +++ b/src/qmmp/fileinfo.h @@ -1,5 +1,5 @@ /*************************************************************************** - * Copyright (C) 2008 by Ilya Kotov * + * Copyright (C) 2008-2009 by Ilya Kotov * * forkotov02@hotmail.ru * * * * This program is free software; you can redistribute it and/or modify * @@ -26,31 +26,75 @@ #include "qmmp.h" -/** - @author Ilya Kotov -*/ +/*! @brief The FileInfo class stores metadata and audio information about media file or stream. + * @author Ilya Kotov + */ class FileInfo { public: + /*! + * Constructs a new empty FileInfo that with file \b path + */ FileInfo(const QString &path = QString()); - FileInfo(const FileInfo &other); - + /*! + * Constructs a new FileInfo that is a copy of the given \b info + */ + FileInfo(const FileInfo &info); + /*! + * Destructor. + */ ~FileInfo(); - + /*! + * Makes a copy of the given \b info + */ void operator=(const FileInfo &info); + /*! + * Returns \b true if this FileInfo object refers to \b info; otherwise returns \b false. + */ bool operator==(const FileInfo &info); + /*! + * Returns \b false if this FileInfo object refers to \b info; otherwise returns \b true. + */ bool operator!=(const FileInfo &info); - + /*! + * Returnds file duration in seconds. + */ qint64 length () const; + /*! + * Returns the metdata string associated with the given \b key. + */ const QString metaData (Qmmp::MetaData key) const; + /*! + * Returns all meta data in map. + */ const QMap metaData () const; + /*! + * Returns \b true if stream/file has no metadata, otherwise returns \b false + */ bool isEmpty() const; + /*! + * Returns file path or stream url. + */ const QString path() const; - + /*! + * Sets file duration to \b length in seconds. + */ void setLength(qint64 length); + /*! + * Sets metadata \b key to \b value + */ void setMetaData(Qmmp::MetaData key, const QString &value); + /*! + * Sets metadata \b key to \b value (integer is converted to string) + */ void setMetaData(Qmmp::MetaData key, int value); + /*! + * Changes all metadata to \b metaData + */ void setMetaData(const QMap &metaData); + /*! + * Sets file path or stream url to \b path + */ void setPath(const QString &path); private: diff --git a/src/qmmp/output.h b/src/qmmp/output.h index 7dab61180..f217eadb1 100644 --- a/src/qmmp/output.h +++ b/src/qmmp/output.h @@ -84,7 +84,7 @@ public: QMutex *mutex(); /*! * Sets StateHandler pointer. May be used to override default state handler. - * @param hanlder StateHandler pointer; + * @param handler StateHandler pointer; */ void setStateHandler(StateHandler *handler); /*! diff --git a/src/qmmp/outputfactory.h b/src/qmmp/outputfactory.h index f05332e64..3871552d1 100644 --- a/src/qmmp/outputfactory.h +++ b/src/qmmp/outputfactory.h @@ -46,10 +46,10 @@ public: } QString name; /*!< Effect plugin full name */ QString shortName; /*!< Effect plugin short name for internal usage */ - bool hasAbout; /*!< Should be \b true if plugin has about dialog, otherwise \b false */ - bool hasSettings; /*!< Should be \b true if plugin has settings dialog, otherwise \b false */ + bool hasAbout; /*!< Should be \b true if plugin has about dialog, otherwise returns \b false */ + bool hasSettings; /*!< Should be \b true if plugin has settings dialog, otherwise returns \b false */ }; -/*! @brief Output plugin interface (output factory). +/*! @brief %Output plugin interface (output factory). * @author Ilya Kotov */ class OutputFactory @@ -73,7 +73,7 @@ public: * Returns \b 0 if volume control is not supported by plugin. * @param parent Parent object. */ - virtual VolumeControl *createVolumeControl(QObject *) = 0; + virtual VolumeControl *createVolumeControl(QObject *parent) = 0; /*! * Shows settings dialog. * @param parent Parent widget. diff --git a/src/qmmp/qmmp.h b/src/qmmp/qmmp.h index bb5ae6830..54fe2984a 100644 --- a/src/qmmp/qmmp.h +++ b/src/qmmp/qmmp.h @@ -22,23 +22,75 @@ #include -/** - @author Ilya Kotov -*/ +/*! @brief The Qmmp class stores global settings and enums. + * @author Ilya Kotov + */ class Qmmp { public: - enum State {Playing = 0, Paused, Stopped, Buffering, NormalError, FatalError}; - enum MetaData {TITLE = 0, ARTIST, ALBUM, COMMENT, GENRE, YEAR, TRACK, URL}; + /*! + * Playback state enum + */ + enum State + { + Playing = 0, /*!< The player is playing source */ + Paused, /*!< The player has currently paused its playback */ + Stopped, /*!< The player is ready to play source */ + Buffering, /*!< The Player is waiting for data to be able to start playing. */ + NormalError, /*!< Input source is invalid or unsupported. Player should skip this file */ + FatalError /*!< This means unrecorvable error die audio output problems. Player should abort playback. */ + }; + /*! + * Metadata keys + */ + enum MetaData + { + TITLE = 0, /*!< Title */ + ARTIST, /*!< Artist */ + ALBUM, /*!< Album */ + COMMENT, /*!< Comment */ + GENRE, /*!< Genre */ + YEAR, /*!< Year */ + TRACK, /*!< Track number */ + URL /*!< Stream url or local file path */ + }; + /*! + * Returns configuration file path. + */ static QString configFile(); + /*! + * Overrides default configuration file path. + */ static void setConfigFile(const QString &path); + /*! + * Returns %Qmmp library version. + */ static QString strVersion(); - //global proxy + /*! + * Returns \b true if global proxy is enabled, otherwise returns \b false + */ static bool useProxy(); + /*! + * Returns \b true if global proxy authentication is enabled, otherwise returns \b false + */ static bool useProxyAuth(); + /*! + * Returns global proxy url. + */ static QUrl proxy(); + /*! + * Enables or disables global proxy. + * @param yes Proxy enable state (\b true - enabled, \b false - disabled) + */ static void setProxyEnabled(bool yes); + /*! + * Enables or disables global proxy authentication. + * @param yes Proxy authentication enable state (\b true - enabled, \b false - disabled) + */ static void setProxyAuthEnabled(bool yes); + /*! + * Sets global proxy url to \b proxy + */ static void setProxy (const QUrl &proxy); private: diff --git a/src/qmmp/recycler.h b/src/qmmp/recycler.h index d73e08702..66ab6e147 100644 --- a/src/qmmp/recycler.h +++ b/src/qmmp/recycler.h @@ -12,34 +12,76 @@ class Buffer; -/*! +/*! @brief The Recycler class provides a queue of audio buffers. * @author Brad Hughes */ class Recycler { public: - Recycler(unsigned int sz); // sz = size in bytes + /*! + * Constructor. + * @param sz Preferd total size of the all buffers in bytes. + */ + Recycler(unsigned int sz); + /*! + * Destructor. + */ ~Recycler(); - + /*! + * Returns \b true if queue if full, otherwise returns \b false + */ bool full() const; + /*! + * Returns \b true if queue if empty, otherwise returns \b false + */ bool empty() const; - + /*! + * Returns a number of available buffers. + */ int available() const; + /*! + * Returns a number of used buffers. + */ int used() const; - - Buffer *next(); // get next in queue + /*! + * Returns next buffer in queue. + */ + Buffer *next(); + /*! + * Returns current buffer for writing. + * @param size Buffer size. + */ Buffer *get(unsigned long size); // get next in recycle - + /*! + * Adds current buffer to queue. + */ void add(); // add to queue + /*! + * Removes current buffer from queue. + */ void done(); // add to recycle - + /*! + * Clears queue. + */ void clear(); // clear queue - + /*! + * Returns size of all buffers in bytes. + */ unsigned int size() const; // size in bytes - - QMutex *mutex() { return &mtx; } - QWaitCondition *cond() { return &cnd; } - + /*! + * Returns mutex pointer. + */ + QMutex *mutex() + { + return &mtx; + } + /*! + * Returns wait condition pointer. + */ + QWaitCondition *cond() + { + return &cnd; + } private: unsigned int buffer_count, add_index, done_index, current_count; diff --git a/src/qmmp/soundcore.h b/src/qmmp/soundcore.h index c34d9cb3a..3023b7ca9 100644 --- a/src/qmmp/soundcore.h +++ b/src/qmmp/soundcore.h @@ -1,5 +1,5 @@ /*************************************************************************** - * Copyright (C) 2006-2008 by Ilya Kotov * + * Copyright (C) 2006-2009 by Ilya Kotov * * forkotov02@hotmail.ru * * * * This program is free software; you can redistribute it and/or modify * @@ -20,10 +20,8 @@ #ifndef SOUNDCORE_H #define SOUNDCORE_H - #include #include - #include "decoder.h" #include "output.h" #include "visual.h" @@ -32,54 +30,79 @@ class QIODevice; class VolumeControl; -/*! - * @author Ilya Kotov +/*! \brief The SoundCore class provides a simple interface for audio playback. + * @author Ilya Kotov */ class SoundCore : public QObject { Q_OBJECT public: + /*! + * Object constructor. + * @param parent Parent object. + */ SoundCore(QObject *parent = 0); - + /*! + * Destructor. + */ ~SoundCore(); - /*! - * Returns length in seconds + * Returns length in milliseconds */ qint64 totalTime() const; - /*! * Sets equalizer settings. Each item of \p bands[] and \p reamp should be * \b -20.0..20.0 */ void setEQ(double bands[10], double preamp); - /*! - * Enables equalizer if \p on is \b TRUE or disables it if \p on is \b FALSE + * Enables equalizer if \p on is \b true or disables it if \p on is \b false */ void setEQEnabled(bool on); - + /*! + * Returns left volume level. + */ int leftVolume(); + /*! + * Returns left volume level. + */ int rightVolume(); + /*! + * Returns \b true if software volume is used, otherwise returns \b false + */ bool softwareVolume(); - + /*! + * Returns the current time (in milliseconds). + */ qint64 elapsed(); + /*! + * Returns current bitrate (in kbps) + */ int bitrate(); + /*! + * Returns current sample rate (in Hz). + */ int frequency(); + /*! + * Returns sample size (in bits). + */ int precision(); + /*! + * Returns channels number. + */ int channels(); - /*! * Returns the current state. - * - * \return the state of the object. */ Qmmp::State state() const; - + /*! + * Returns all meta data in map. + */ QMap metaData(); - + /*! + * Returns the metdata string associated with the given \b key. + */ QString metaData(Qmmp::MetaData key); - /*! * Returns a pointer to the SoundCore instance. */ @@ -87,61 +110,88 @@ public: public slots: - - void setSoftwareVolume(bool); - + /*! + * This funtion allows to force software volume for all output plugins. + * @param yes Software volume enable state (\b true - enable, \b false - disable) + */ + void setSoftwareVolume(bool yes); /*! * Sets volume. - * \p left - volume of the left channel. - * \p right - volume of the right channel. - * \b left and \b right should be \b 0..100. + * @param left - volume of the left channel \b [0..100]. + * @param right - volume of the right channel \b [0..100]. */ void setVolume(int left, int right); - /*! - * This function plays file with the given path \p source. - * - * \return \b TRUE if playback started successful or source is not a local file. - * \return \b FALSE otherwise. + * This function plays file or stream with the given path \p source. + * Returns \b true if playback started successful or source is not a local file, + * otherwise returns \b false. Useful for invalid files skipping. */ bool play(const QString &source); - /*! * Stops playback */ void stop(); - /*! * Pauses/resumes playback */ void pause(); - /*! - * This function sets the current play position to \p pos. - */ + * This function sets the current play position to \p pos in milliseconds. + */ void seek(qint64 pos); - /*! - * This function returns file path or stream url. - */ + * This function returns file path or stream url. + */ const QString url(); signals: - /*! - * This signal is emited when the stream reader fills it's buffer. - * The argument \b progress indicates the current percentage of buffering completed + * This signal is emitted when the stream reader fills it's buffer. + * The argument \b progress indicates the current percentage of buffering completed. */ - void bufferingProgress(int progress); + /*! + * Tracks elapesed time. + * @param time New track position in milliseconds. + */ void elapsedChanged(qint64 time); + /*! + * Emitted when bitrate has changed. + * @param bitrate New bitrate (in kbps) + */ void bitrateChanged(int bitrate); + /*! + * Emitted when samplerate has changed. + * @param frequency New sample rate (in Hz) + */ void frequencyChanged(int frequency); + /*! + * Emitted when sample size has changed. + * @param precision New sample size (in bits) + */ void precisionChanged(int precision); + /*! + * Emitted when channels number has changed. + * @param channels New channels number. + */ void channelsChanged(int channels); + /*! + * Emitted when new metadata is available. + */ void metaDataChanged (); + /*! + * This signal is emitted when the state of the SoundCore has changed. + */ void stateChanged (Qmmp::State newState); + /*! + * Emitted when playback has finished. + */ void finished(); + /*! + * Emitted when volume has changed. + * @param left Left channel volume level. It should be \b [0..100] + * @param right Right channel volume level. It should be \b [0..100] + */ void volumeChanged(int left, int right); private slots: diff --git a/src/qmmp/statehandler.h b/src/qmmp/statehandler.h index 702a24c1b..af44c2597 100644 --- a/src/qmmp/statehandler.h +++ b/src/qmmp/statehandler.h @@ -1,5 +1,5 @@ /*************************************************************************** - * Copyright (C) 2008 by Ilya Kotov * + * Copyright (C) 2008-2009 by Ilya Kotov * * forkotov02@hotmail.ru * * * * This program is free software; you can redistribute it and/or modify * @@ -26,50 +26,119 @@ #include "qmmp.h" -/** - @author Ilya Kotov -*/ +/*! @brief The StateHandler class allows to track information about playback progress. + * @author Ilya Kotov + */ class StateHandler : public QObject { Q_OBJECT public: + /*! + * Object constructor. + * @param parent Parent object. + */ StateHandler(QObject *parent = 0); - + /*! + * Destructor. + */ ~StateHandler(); - + /*! + * Sends information about playback progress. + * @param elapsed Current time (in milliseconds). + * @param totalTime Total track length (in milliseconds). + * @param bitrate Current bitrate (in kbps). + * @param frequency Current samplerate (in Hz). + * @param precision Sample size (in bits). + * @param channels Number of channels. + */ virtual void dispatch(qint64 elapsed, qint64 totalTime, int bitrate, int frequency, int precision, int channels); - + /*! + * Sends metadata \b metaData + */ virtual void dispatch(const QMap &metaData); - + /*! + * Sends playback state. + */ virtual void dispatch(const Qmmp::State &state); - + /*! + * Returns the current time (in milliseconds). + */ qint64 elapsed(); + /*! + * Returns current bitrate (in kbps) + */ int bitrate(); + /*! + * Returns current sample rate (in Hz). + */ int frequency(); + /*! + * Returns sample size (in bits). + */ int precision(); + /*! + * Returns channels number. + */ int channels(); - Qmmp::State state(); + /*! + * Returns the current state. + */ + Qmmp::State state() const; + /*! + * Returns all meta data in map. + */ QMap metaData(); + /*! + * Returns the metdata string associated with the given \b key. + */ QString metaData(Qmmp::MetaData key); - /*! - * Returns a pointer to the StateHandler instance. + * Returns a pointer to the first created StateHandler instance. */ static StateHandler* instance(); signals: + /*! + * Tracks elapesed time. + * @param time New track position in milliseconds. + */ void elapsedChanged(qint64 time); + /*! + * Emitted when bitrate has changed. + * @param bitrate New bitrate (in kbps) + */ void bitrateChanged(int bitrate); + /*! + * Emitted when samplerate has changed. + * @param frequency New sample rate (in Hz) + */ void frequencyChanged(int frequency); + /*! + * Emitted when sample size has changed. + * @param precision New sample size (in bits) + */ void precisionChanged(int precision); + /*! + * Emitted when channels number has changed. + * @param channels New channels number. + */ void channelsChanged(int channels); + /*! + * Emitted when new metadata is available. + */ void metaDataChanged (); + /*! + * This signal is emitted when the playback state has changed. + */ void stateChanged (Qmmp::State newState); + /*! + * Emitted when playback has finished. + */ void finished(); private: diff --git a/src/qmmp/visual.h b/src/qmmp/visual.h index f1b510899..7f3739384 100644 --- a/src/qmmp/visual.h +++ b/src/qmmp/visual.h @@ -75,11 +75,11 @@ public: /*! * Sets whether the visual plugin is enabled. * @param factory Visual plugin factory. - * @param enabled Plugin enable state (\b true - enable, \b false - disable) + * @param enable Plugin enable state (\b true - enable, \b false - disable) */ static void setEnabled(VisualFactory* factory, bool enable = TRUE); /*! - * Returns \b true if visual plugin is enabled, otherwise \b false + * Returns \b true if visual plugin is enabled, otherwise returns \b false * @param factory Effect plugin factory. */ static bool isEnabled(VisualFactory* factory); @@ -111,7 +111,7 @@ public: signals: /*! - * Emited when visual widget is closed by user. + * Emitted when visual widget is closed by user. */ void closedByUser(); diff --git a/src/qmmp/visualfactory.h b/src/qmmp/visualfactory.h index 1f631392f..fdb3a1abf 100644 --- a/src/qmmp/visualfactory.h +++ b/src/qmmp/visualfactory.h @@ -43,10 +43,10 @@ public: } QString name; /*!< Effect plugin full name */ QString shortName; /*!< Effect plugin short name for internal usage */ - bool hasAbout; /*!< Should be \b true if plugin has about dialog, otherwise \b false */ - bool hasSettings; /*!< Should be \b true if plugin has settings dialog, otherwise \b false */ + bool hasAbout; /*!< Should be \b true if plugin has about dialog, otherwise returns \b false */ + bool hasSettings; /*!< Should be \b true if plugin has settings dialog, otherwise returns \b false */ }; -/*! Visual plugin interface (visual factory). +/*! @brief %Visual plugin interface (visual factory). * @author Ilya Kotov */ class VisualFactory diff --git a/src/qmmp/volumecontrol.h b/src/qmmp/volumecontrol.h index 5be1d253f..f993057b7 100644 --- a/src/qmmp/volumecontrol.h +++ b/src/qmmp/volumecontrol.h @@ -22,60 +22,113 @@ #include -/** - @author Ilya Kotov -*/ +/*! @brief The VolumeControl class provides the base interface class for volume control. + * @author Ilya Kotov + */ class VolumeControl : public QObject { Q_OBJECT public: + /*! + * Object constructor. + * @param parent Parent object. + */ VolumeControl(QObject *parent = 0); - + /*! + * Destructor. + */ ~VolumeControl(); - + /*! + * Setups volume level. + * Subclass should reimplement this fucntion. + * @param left Left channel volume level. It should be \b 0..100 + * @param right Right channel volume level. It should be \b 0..100 + */ virtual void setVolume(int left, int right) = 0; - + /*! + * Returns left channel volume. + */ int left(); + /*! + * Returns right channel volume. + */ int right(); - + /*! + * Creates output volume control object if implemented, \b otherwise it creates SoftwareVolume object. + * @param parent Parent object. + */ static VolumeControl *create(QObject *parent = 0); signals: + /*! + * Emitted when volume is changed. + * @param left Left channel volume level. It should be \b 0..100 + * @param right Right channel volume level. It should be \b 0..100 + */ void volumeChanged(int left, int right); public slots: + /*! + * Forces the volumeChanged signal to emit. + */ void checkVolume(); protected: + /*! + * Gets current volume. + * @param left Pointer to the left volume level. + * @param right Pointer to the right volume level + */ virtual void volume(int *left, int *right) = 0; private: int m_left, m_right; }; -/*! @internal - * @author Ilya Kotov +/*! @brief The SoftwareVolume provides access to the software volume control. + * @author Ilya Kotov */ class SoftwareVolume : public VolumeControl { Q_OBJECT public: + /*! + * Object constructor. + * @param parent Parent object. + */ SoftwareVolume(QObject *parent = 0); - + /*! + * Destructor. + */ ~SoftwareVolume(); - + /*! + * Setups volume level. + * Subclass should reimplement this fucntion. + * @param left Left channel volume level. It should be \b 0..100 + * @param right Right channel volume level. It should be \b 0..100 + */ void setVolume(int left, int right); - + /*! + * Returns software volume object instance. + */ static SoftwareVolume *instance(); + /*! + * This funtion allows to force software volume for all output plugins. + * @param b Software volume enable state (\b true - enable, \b false - disable) + */ static void setEnabled(bool b); protected: + /*! @internal + * Gets current volume. + * @param left Pointer to the left volume level. + * @param right Pointer to the right volume level + */ void volume(int *left, int *right); private: int m_left, m_right; static SoftwareVolume *m_instance; - }; #endif diff --git a/src/qmmpui/abstractplaylistitem.h b/src/qmmpui/abstractplaylistitem.h index cf594e6e3..2294ff73a 100644 --- a/src/qmmpui/abstractplaylistitem.h +++ b/src/qmmpui/abstractplaylistitem.h @@ -90,7 +90,7 @@ public: /*! * Loads one metadata value. * @param key Metadata key. - * @param key Metadata vlaue. + * @param value Metadata value. */ virtual void setMetaData(Qmmp::MetaData key, const QString &value); /*! diff --git a/src/qmmpui/commandlinemanager.h b/src/qmmpui/commandlinemanager.h index 8f0660fb6..6bae654ee 100644 --- a/src/qmmpui/commandlinemanager.h +++ b/src/qmmpui/commandlinemanager.h @@ -46,7 +46,7 @@ public: */ void executeCommand(const QString& opt_str); /*! - * Return \b true if command \b opt_str is supported, otherwise \b false + * Return \b true if command \b opt_str is supported, otherwise returns \b false */ static bool hasOption(const QString &opt_str); /*! diff --git a/src/qmmpui/filedialog.h b/src/qmmpui/filedialog.h index c5ccff59b..7395ffea0 100644 --- a/src/qmmpui/filedialog.h +++ b/src/qmmpui/filedialog.h @@ -115,7 +115,6 @@ public: * @param caption Dialog title. * @param filters Filer used by file dialog * (example: "Audio (*.mp3 *.ogg);;Text files (*.txt);;XML files (*.xml)"). - * @param selectedFilter Default selected filter. * * Usage: FileDialog::popup(this, FileDialog::AddDirs, &m_lastDir, * m_playListModel, SLOT(addFileList(const QStringList&)), @@ -133,7 +132,7 @@ public: */ static QList registeredFactories(); /*! - * Returns \b true if selected file dialog doesn't support nonmodal mode, otherwise \b false + * Returns \b true if selected file dialog doesn't support nonmodal mode, otherwise returns \b false */ static bool isModal(); /*! @@ -141,7 +140,7 @@ public: */ static void setEnabled(FileDialogFactory *factory); /*! - * Returns \b true if file dialog \b factory is used by default, otherwise \b false + * Returns \b true if file dialog \b factory is used by default, otherwise returns \b false */ static bool isEnabled(FileDialogFactory *factory); @@ -215,7 +214,7 @@ protected: const QString &filter , QString *selectedFilter); /*! - * Returns \b true if file dialog doesn't support nonmodal mode, otherwise \b false + * Returns \b true if file dialog doesn't support nonmodal mode, otherwise returns \b false * Subclass should reimplement this function. */ virtual bool modal()const @@ -258,7 +257,7 @@ protected: static FileDialog* defaultInstance(); /*! * Registers file dialog \b factory - * Returns \b false if \b factory is already registered, otherwise \b true + * Returns \b false if \b factory is already registered, otherwise returns \b true */ static bool registerFactory(FileDialogFactory *factory); diff --git a/src/qmmpui/filedialogfactory.h b/src/qmmpui/filedialogfactory.h index 115d619d1..d5b790b18 100644 --- a/src/qmmpui/filedialogfactory.h +++ b/src/qmmpui/filedialogfactory.h @@ -36,7 +36,8 @@ public: { hasAbout = FALSE; } - bool hasAbout; /*!< Should be \b true if the file dialog plugin has about dialog, otherwise \b false */ + bool hasAbout; /*!< Should be \b true if the file dialog plugin has about dialog, otherwise should be + * \b false */ QString name; /*!< File dialog plugin full name */ QString shortName; /*!< File dialog short name for internal usage */ }; diff --git a/src/qmmpui/fileloader.h b/src/qmmpui/fileloader.h index e89f4a166..50899ccba 100644 --- a/src/qmmpui/fileloader.h +++ b/src/qmmpui/fileloader.h @@ -62,7 +62,7 @@ public: void setDirectoryToLoad(const QString&); signals: /*! - * Emited when new playlist item is available. + * Emitted when new playlist item is available. * @param item Pointer of the new PlayListItem object. */ void newPlayListItem(PlayListItem *item); diff --git a/src/qmmpui/general.h b/src/qmmpui/general.h index e4f636354..244d02114 100644 --- a/src/qmmpui/general.h +++ b/src/qmmpui/general.h @@ -52,22 +52,22 @@ public: /*! * Sets whether the general plugin is enabled. * @param factory General plugin factory. - * @param enabled Plugin enable state (\b true - enable, \b false - disable) + * @param enable Plugin enable state (\b true - enable, \b false - disable) */ static void setEnabled(GeneralFactory* factory, bool enable = TRUE); /*! - * Return \b true if general plugin is enabled, otherwise \b false + * Returns \b true if general plugin is enabled, otherwise returns \b false * @param factory General plugin factory. */ static bool isEnabled(GeneralFactory* factory); signals: /*! - * Emited when exit() slot is called. + * Emitted when exit() slot is called. */ void exitCalled(); /*! - * Emited when toggleVisibility() slot is called. + * Emitted when toggleVisibility() slot is called. */ void toggleVisibilityCalled(); diff --git a/src/qmmpui/generalfactory.h b/src/qmmpui/generalfactory.h index c1bcc72ae..02fcedd57 100644 --- a/src/qmmpui/generalfactory.h +++ b/src/qmmpui/generalfactory.h @@ -42,12 +42,12 @@ public: } QString name; /*!< File dialog plugin full name */ QString shortName; /*!< File dialog short name for internal usage */ - bool hasAbout; /*!< Should be \b true if plugin has about dialog, otherwise \b false */ - bool hasSettings; /*!< Should be \b true if plugin has settings dialog, otherwise \b false */ + bool hasAbout; /*!< Should be \b true if plugin has about dialog, otherwise returns \b false */ + bool hasSettings; /*!< Should be \b true if plugin has settings dialog, otherwise returns \b false */ bool visibilityControl; /*!< Should be \b true if plugin can show/hide main window of the player, - * otherwise \b false */ + * otherwise returns \b false */ }; -/*! @brief General plugin interface. +/*! @brief %General plugin interface. * @author Ilya Kotov */ class GeneralFactory diff --git a/src/qmmpui/generalhandler.h b/src/qmmpui/generalhandler.h index 179c956d8..fa064f3ee 100644 --- a/src/qmmpui/generalhandler.h +++ b/src/qmmpui/generalhandler.h @@ -60,7 +60,7 @@ public: /*! * Sets whether the general plugin is enabled. * @param factory General plugin factory. - * @param enabled Plugin enable state (\b true - enable, \b false - disable) + * @param enable Plugin enable state (\b true - enable, \b false - disable) */ void setEnabled(GeneralFactory* factory, bool enable); /*! @@ -70,7 +70,7 @@ public: */ void showSettings(GeneralFactory* factory, QWidget* parentWidget); /*! - * Returns \b true if one of the general plugin can change visibility, otherwise \b false + * Returns \b true if one of the general plugin can change visibility, otherwise returns \b false */ bool visibilityControl(); /*! @@ -97,7 +97,7 @@ public: * Creates menu with type \b type * @param type Menu type. * @param title Menu title. - * @param paren Parent widget + * @param parent Parent widget */ QMenu *createMenu(MenuType type, const QString &title = QString(), QWidget *parent = 0); /*! @@ -107,12 +107,12 @@ public: signals: /*! - * Emited when some general plugin requires to exit. + * Emitted when some general plugin requires to exit. * Use it to quit application. */ void exitCalled(); /*! - * Emited when some general plugin requires to toggle visibility. + * Emitted when some general plugin requires to toggle visibility. * Use it to show/hide player's window. */ void toggleVisibilityCalled(); diff --git a/src/qmmpui/mediaplayer.h b/src/qmmpui/mediaplayer.h index 51d56a5f0..7c03bf3a3 100644 --- a/src/qmmpui/mediaplayer.h +++ b/src/qmmpui/mediaplayer.h @@ -56,7 +56,7 @@ public: */ PlayListModel *playListModel(); /*! - * Returns \b true if "Repeate Track" option is enabled, otherwise \b false + * Returns \b true if "Repeate Track" option is enabled, otherwise returns \b false */ bool isRepeatable() const; diff --git a/src/qmmpui/playlistitem.h b/src/qmmpui/playlistitem.h index dd2898f64..5dc67d2df 100644 --- a/src/qmmpui/playlistitem.h +++ b/src/qmmpui/playlistitem.h @@ -64,8 +64,7 @@ public: */ void setSelected(bool select); /*! - * Return \b true if item is selected, otherwise \b false. - * @param yes State of current (\b true - set flag, \b false - unset flag) + * Return \b true if item is selected, otherwise returns \b false. */ bool isSelected() const; /*! @@ -73,7 +72,7 @@ public: */ void setCurrent(bool yes); /*! - * Returns \b true if the item is the current item; otherwise returns \b false. + * Returns \b true if the item is the current item; otherwise returns returns \b false. */ bool isCurrent() const; /*! diff --git a/src/qmmpui/playlistmodel.h b/src/qmmpui/playlistmodel.h index e22334b07..b3e89aef7 100644 --- a/src/qmmpui/playlistmodel.h +++ b/src/qmmpui/playlistmodel.h @@ -47,7 +47,7 @@ struct SimpleSelection ; } /*! - * Returns \p true if this selection is valid; otherwise returns \p false. + * Returns \p true if this selection is valid; otherwise returns returns \p false. */ inline bool isValid()const { @@ -67,10 +67,10 @@ struct SimpleSelection { return m_bottom - m_top + 1; } - int m_bottom; - int m_top; - int m_anchor; - QListm_selected_rows; + int m_bottom; /*!< */ + int m_top; /*!< */ + int m_anchor; /*!< */ + QListm_selected_rows; /*!< Selected rows numbers */ }; /*! @internal * @brief Helper class used for tags update after details dialog closing. @@ -132,12 +132,12 @@ public: int currentRow(); /*! * Sets current row number. - * Returns \b false if item with this number doesn't exist, otherwise \b true + * Returns \b false if item with this number doesn't exist, otherwise returns \b true * @param row Number of item. */ bool setCurrent (int row); /*! - * Returns \b true if \b row is selected, otherwise \b false + * Returns \b true if \b row is selected, otherwise returns \b false */ bool isSelected(int row); /*! @@ -148,12 +148,12 @@ public: void setSelected(int row, bool select); /*! * Advances to the next item. Returns \b false if next iten doesn't exist, - * otherwise \b true + * otherwise returns \b true */ bool next(); /*! * Goes back to the previous item. Returns \b false if previous iten doesn't exist, - * otherwise \b true + * otherwise returns \b true */ bool previous(); /*! @@ -181,7 +181,7 @@ public: */ void setCurrentToQueued(); /*! - * Returns \b true if play queue is empty,otherwise - \b false. + * Returns \b true if play queue is empty,otherwise returns - \b false. */ bool isEmptyQueue()const; /*! @@ -339,7 +339,7 @@ public slots: /*! * Removes previous items and loads list of files (regular files or directories), * returns \b TRUE if at least one file has been successfully loaded, - * otherwise \b FALSE + * otherwise returns \b FALSE */ bool setFileList(const QStringList &l); /*! diff --git a/src/qmmpui/playlistparser.h b/src/qmmpui/playlistparser.h index 7b9688a52..5197feefe 100644 --- a/src/qmmpui/playlistparser.h +++ b/src/qmmpui/playlistparser.h @@ -45,7 +45,7 @@ public: */ QStringList getExtensions(); /*! - * Returns \b true if file \b filePath is supported, otherwise \b false + * Returns \b true if file \b filePath is supported, otherwise returns \b false */ bool supports(const QString &filePath); /*! diff --git a/src/qmmpui/playstate.h b/src/qmmpui/playstate.h index a2b525f7d..554afcf11 100644 --- a/src/qmmpui/playstate.h +++ b/src/qmmpui/playstate.h @@ -31,12 +31,12 @@ class PlayState { public: /*! Makes single step forward through songs list. - * If the step has done returns \b true, otherwise \b false + * If the step has done returns \b true, otherwise returns \b false */ virtual bool next() = 0; /*! Makes single step back through songs list. - * If the step has done returns \b true, otherwise \b false + * If the step has done returns \b true, otherwise returns \b false */ virtual bool previous() = 0; -- cgit v1.2.3-13-gbd6f