kalarm/soundpicker.h

   1 /*
   2  *  soundpicker.h  -  widget to select a sound file or a beep
   3  *  Program:  kalarm
   4  *  Copyright © 2002,2004-2007,2009 by David Jarvie <djarvie@kde.org>
   5  *
   6  *  This program is free software; you can redistribute it and/or modify
   7  *  it under the terms of the GNU General Public License as published by
   8  *  the Free Software Foundation; either version 2 of the License, or
   9  *  (at your option) any later version.
  10  *
  11  *  This program is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  14  *  GNU General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU General Public License along
  17  *  with this program; if not, write to the Free Software Foundation, Inc.,
  18  *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  19  */
  20
  21 #ifndef SOUNDPICKER_H
  22 #define SOUNDPICKER_H
  23
  24 #include "preferences.h"
  25
  26 #include <kurl.h>
  27 #include <QFrame>
  28 #include <QString>
  29
  30 class KHBox;
  31 class ComboBox;
  32 class PushButton;
  33
  34
  35 class SoundPicker : public QFrame
  36 {
  37         Q_OBJECT
  38     public:
  39         /** Constructor.
  40          *  @param parent The parent object of this widget.
  41          */
  42         explicit SoundPicker(QWidget* parent);
  43         /** Initialises the widget's state.
  44          *  @param type     The option to select.
  45          *  @param filename The full path or URL of the sound file to select. If the 'file' option is
  46          *                  not initially selected, @p filename provides the default should 'file'
  47          *                  later be selected by the user.
  48          *  @param volume   The volume to play a sound file, or < 0 for no volume setting. If the
  49          *                  'file' option is not initially selected, @p volume provides the default
  50          *                  should 'file' later be selected by the user.
  51          *  @param fadeVolume The initial volume to play a sound file if fading is to be used, or < 0
  52          *                  for no fading. If the 'file' option is not initially selected, @p fadeVolume
  53          *                  provides the default should 'file' later be selected by the user.
  54          *  @param fadeSeconds The number of seconds over which the sound file volume should be faded,
  55          *                  or 0 for no fading. If the 'file' option is not initially selected,
  56          *                  @p fadeSeconds provides the default should 'file' later be selected by the user.
  57          *  @param repeat   True to play the sound file repeatedly. If the 'file' option is not initially
  58          *                  selected, @p repeat provides the default should 'file' later be selected by
  59          *                  the user.
  60          */
  61         void           set(Preferences::SoundType type, const QString& filename, float volume, float fadeVolume, int fadeSeconds, bool repeat);
  62         /** Returns true if the widget is read only for the user. */
  63         bool           isReadOnly() const          { return mReadOnly; }
  64         /** Sets whether the widget can be changed the user.
  65          *  @param readOnly True to set the widget read-only, false to set it read-write.
  66          */
  67         void           setReadOnly(bool readOnly);
  68         /** Show or hide the 'speak' option.
  69          *  If it is to be hidden and it is currently selected, sound is turned off.
  70          */
  71         void           showSpeak(bool show);
  72         /** Returns the selected option. */
  73         Preferences::SoundType sound() const;
  74         /** If the 'file' option is selected, returns the URL of the chosen file.
  75          *  Otherwise returns an empty URL.
  76          */
  77         KUrl           file() const;
  78         /** Returns the volume and fade characteristics for playing a sound file.
  79          *  @param fadeVolume Receives the initial volume if the volume is to be faded, else -1.
  80          *  @param fadeSeconds Receives the number of seconds over which the volume is to be faded, else 0.
  81          *  @return Volume to play the sound file, or < 0 if the 'file' option is not selected.
  82          */
  83         float          volume(float& fadeVolume, int& fadeSeconds) const;
  84         /** Returns true if a sound file is to be played repeatedly.
  85          *  If the 'file' option is not selected, returns false.
  86          */
  87         bool           repeat() const;
  88         /** Returns the current file URL regardless of whether the 'file' option is selected. */
  89         KUrl           fileSetting() const   { return mFile; }
  90         /** Returns the current file repetition setting regardless of whether the 'file' option is selected. */
  91         bool           repeatSetting() const { return mRepeat; }
  92         /** Display a dialog to choose a sound file, initially highlighting
  93          *  @p initialFile if non-null.
  94          *  @param initialDir  Initial directory to display if @p initialFile is null. If a file is
  95          *                     chosen, this is updated to the directory containing the chosen file.
  96          *  @param initialFile Full path name or URL of file to be highlighted initially.
  97          *                     If null, no file will be highlighted.
  98          *  @return URL selected, in human readable format. If none is selected, URL.isEmpty() is true.
  99          */
 100         static QString browseFile(QString& initialDir, const QString& initialFile = QString());
 101
 102         static QString i18n_label_Sound();  // text of Sound label
 103         static QString i18n_combo_None();   // text of None combo box item
 104         static QString i18n_combo_Beep();   // text of Beep combo box item
 105         static QString i18n_combo_Speak();  // text of Speak combo box item
 106         static QString i18n_combo_File();   // text of File combo box item
 107
 108     signals:
 109         void           changed();     // emitted when any contents change
 110
 111     private slots:
 112         void           slotTypeSelected(int id);
 113         void           slotPickFile();
 114         void           setLastType();
 115
 116     private:
 117         ComboBox*      mTypeCombo;
 118         KHBox*         mTypeBox;
 119         PushButton*    mFilePicker;
 120         QString        mDefaultDir;
 121         KUrl           mFile;         // sound file to play when alarm is triggered
 122         float          mVolume;       // volume for file, or < 0 to not set volume
 123         float          mFadeVolume;   // initial volume for file, or < 0 for no fading
 124         int            mFadeSeconds;  // fade interval in seconds
 125         Preferences::SoundType mLastType;     // last selected sound option
 126         bool           mSpeakShowing; // Speak option is shown in combo box
 127         bool           mRevertType;   // reverting to last selected sound option
 128         bool           mRepeat;       // repeat the sound file
 129         bool           mReadOnly;
 130 };
 131
 132 #endif // SOUNDPICKER_H
 133
 134 // vim: et sw=4: