kalarm/soundpicker.h

   1 /*
   2  *  soundpicker.h  -  widget to select a sound file or a beep
   3  *  Program:  kalarm
   4  *  Copyright © 2002,2004-2012 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 <QFrame>
  27 #include <QString>
  28 #include <QUrl>
  29
  30 class ComboBox;
  31 class PushButton;
  32
  33
  34 class SoundPicker : public QFrame
  35 {
  36         Q_OBJECT
  37     public:
  38         /** Constructor.
  39          *  @param parent The parent object of this widget.
  40          */
  41         explicit SoundPicker(QWidget* parent);
  42         /** Initialises the widget's state.
  43          *  @param type     The option to select.
  44          *  @param filename The full path or URL of the sound file to select.
  45          *                  If the 'file' option is not initially selected,
  46          *                  @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
  49          *                  volume setting. If the 'file' option is not
  50          *                  initially selected, @p volume provides the default
  51          *                  should 'file' later be selected by the user.
  52          *  @param fadeVolume  The initial volume to play a sound file if fading
  53          *                     is to be used, or < 0 for no fading. If the
  54          *                     'file' option is not initially selected, @p
  55          *                     fadeVolume provides the default should 'file'
  56          *                     later be selected by the user.
  57          *  @param fadeSeconds The number of seconds over which the sound file
  58          *                     volume should be faded, or 0 for no fading. If
  59          *                     the 'file' option is not initially selected,
  60          *                     @p fadeSeconds provides the default should
  61          *                     'file' later be selected by the user.
  62          *  @param repeatPause Number of seconds to pause between sound file
  63          *                     repetitions, or -1 for no repetition. If the
  64          *                     'file' option is not initially selected,
  65          *                     @p repeatPause provides the default should 'file'
  66          *                     later be selected by the user.
  67          */
  68         void           set(Preferences::SoundType type, const QString& filename, float volume, float fadeVolume, int fadeSeconds, int repeatPause);
  69
  70         /** Returns true if the widget is read only for the user. */
  71         bool           isReadOnly() const          { return mReadOnly; }
  72
  73         /** Sets whether the widget can be changed the user.
  74          *  @param readOnly True to set the widget read-only, false to set it read-write.
  75          */
  76         void           setReadOnly(bool readOnly);
  77
  78         /** Show or hide the 'speak' option.
  79          *  If it is to be hidden and it is currently selected, sound is turned off.
  80          */
  81         void           showSpeak(bool show);
  82
  83         /** Returns the selected option. */
  84         Preferences::SoundType sound() const;
  85
  86         /** If the 'file' option is selected, returns the URL of the chosen file.
  87          *  Otherwise returns an empty URL.
  88          */
  89         QUrl           file() const;
  90
  91         /** Returns the volume and fade characteristics for playing a sound file.
  92          *  @param fadeVolume  Receives the initial volume if the volume is to
  93          *                     be faded, else -1.
  94          *  @param fadeSeconds Receives the number of seconds over which the
  95          *                     volume is to be faded, else 0.
  96          *  @return            Volume to play the sound file, or < 0 if the
  97          *                     'file' option is not selected.
  98          */
  99         float          volume(float& fadeVolume, int& fadeSeconds) const;
 100
 101         /** Returns pause in seconds between repetitions of the sound file,
 102          *  or -1 if no repeat or 'file' option is not selected.
 103          */
 104         int            repeatPause() const;
 105
 106         /** Returns the current file URL regardless of whether the 'file' option is selected. */
 107         QUrl           fileSetting() const   { return mFile; }
 108
 109         /** Returns the current file repetition setting regardless of whether
 110          *  the 'file' option is selected.
 111          */
 112         bool           repeatPauseSetting() const { return mRepeatPause; }
 113
 114         /** Display a dialog to choose a sound file, initially highlighting
 115          *  @p initialFile if non-null.
 116          *  @param initialDir  Initial directory to display if @p initialFile
 117          *                     is null. If a file is chosen, this is updated to
 118          *                     the directory containing the chosen file.
 119          *  @param initialFile Full path name or URL of file to be highlighted
 120          *                     initially.  If null, no file will be highlighted.
 121          *  @return            URL selected, in human readable format. If none
 122          *                     is selected, URL.isEmpty() is true.
 123          */
 124         static QString browseFile(QString& initialDir, const QString& initialFile = QString());
 125
 126         static QString i18n_label_Sound();  // text of Sound label
 127         static QString i18n_combo_None();   // text of None combo box item
 128         static QString i18n_combo_Beep();   // text of Beep combo box item
 129         static QString i18n_combo_Speak();  // text of Speak combo box item
 130         static QString i18n_combo_File();   // text of File combo box item
 131
 132     Q_SIGNALS:
 133         void           changed();     // emitted when any contents change
 134
 135     private Q_SLOTS:
 136         void           slotTypeSelected(int id);
 137         void           slotPickFile();
 138         void           setLastType();
 139
 140     private:
 141         ComboBox*      mTypeCombo;
 142         QWidget*       mTypeBox;
 143         PushButton*    mFilePicker;
 144         QUrl           mFile;         // sound file to play when alarm is triggered
 145         float          mVolume;       // volume for file, or < 0 to not set volume
 146         float          mFadeVolume;   // initial volume for file, or < 0 for no fading
 147         int            mFadeSeconds;  // fade interval in seconds
 148         int            mRepeatPause;  // seconds to pause between repetitions of the sound file, or -1 if no repeat
 149         Preferences::SoundType mLastType;     // last selected sound option
 150         bool           mSpeakShowing; // Speak option is shown in combo box
 151         bool           mRevertType;   // reverting to last selected sound option
 152         bool           mReadOnly;
 153 };
 154
 155 #endif // SOUNDPICKER_H
 156
 157 // vim: et sw=4: