kalarm/pickfileradio.h

   1 /*
   2  *  pickfileradio.h  -  radio button with an associated file picker
   3  *  Program:  kalarm
   4  *  Copyright © 2005,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 PICKFILERADIO_H
  22 #define PICKFILERADIO_H
  23
  24 /** @file pickfileradio.h - radio button with an associated file picker */
  25
  26 #include "radiobutton.h"
  27
  28 class QPushButton;
  29 class ButtonGroup;
  30 class LineEdit;
  31
  32 /**
  33  *  @short Radio button with associated file picker controls.
  34  *
  35  *  The PickFileRadio class is a radio button with an associated button to choose
  36  *  a file, and an optional file name edit box. Its purpose is to ensure that while
  37  *  the radio button is selected, the chosen file name is never blank.
  38  *
  39  *  To achieve this, whenever the button is newly selected and the
  40  *  file name is currently blank, the file picker dialog is displayed to choose a
  41  *  file. If the dialog exits without a file being chosen, the radio button selection
  42  *  is reverted to the previously selected button in the parent button group.
  43  *
  44  *  The class handles the activation of the file picker dialog (via a virtual method
  45  *  which must be supplied by deriving a class from this one). It also handles all
  46  *  enabling and disabling of the browse button and edit box when the enable state of
  47  *  the radio button is changed, and when the radio button selection changes.
  48  *
  49  *  @author David Jarvie <djarvie@kde.org>
  50  */
  51 class PickFileRadio : public RadioButton
  52 {
  53         Q_OBJECT
  54     public:
  55         /** Constructor.
  56          *  @param button Push button to invoke the file picker dialog.
  57          *  @param edit File name edit widget, or null if there is none.
  58          *  @param text Radio button's text.
  59          *  @param parent Button group which is to be the parent object for the radio button.
  60          */
  61         PickFileRadio(QPushButton* button, LineEdit* edit, const QString& text, ButtonGroup* group, QWidget* parent);
  62         /** Constructor.
  63          *  The init() method must be called before the widget can be used.
  64          *  @param text Radio button's text.
  65          *  @param parent Button group which is to be the parent object for the radio button.
  66          */
  67         PickFileRadio(const QString& text, ButtonGroup* group, QWidget* parent);
  68         /** Initialises the widget.
  69          *  @param button Push button to invoke the file picker dialog.
  70          *  @param edit File name edit widget, or null if there is none.
  71          */
  72         void            init(QPushButton* button, LineEdit* edit = 0);
  73         /** Sets whether the radio button and associated widgets are read-only for the user.
  74          *  If read-only, their states cannot be changed by the user.
  75          *  @param readOnly True to set the widgets read-only, false to set them read-write.
  76          */
  77         virtual void    setReadOnly(bool readOnly);
  78         /** Chooses a file, for example by displaying a file selection dialog.
  79          *  This method is called when the push button is clicked - the client
  80          *  should not activate a file selection dialog directly.
  81          *  @return Selected file name, or QString() if no selection made.
  82          */
  83         virtual QString pickFile() = 0;
  84         /** Notifies the widget of the currently selected file name.
  85          *  This should only be used when no file name edit box is used.
  86          *  It should be called to initialise the widget's data, and also any time the file
  87          *  name is changed without using the push button.
  88          */
  89         void            setFile(const QString& file);
  90         /** Returns the currently selected file name. */
  91         QString         file() const;
  92         /** Returns the associated file name edit widget, or null if none. */
  93         LineEdit*       fileEdit() const    { return mEdit; }
  94         /** Returns the associated file browse push button. */
  95         QPushButton*    pushButton() const  { return mButton; }
  96
  97     public slots:
  98         /** Enables or disables the radio button, and adjusts the enabled state of the
  99          *  associated browse button and file name edit box.
 100          */
 101         virtual void    setEnabled(bool);
 102
 103     signals:
 104         void          fileChanged();   // emitted whenever the selected file changes
 105
 106     private slots:
 107         void          slotSelectionChanged(QAbstractButton*);
 108         QString       slotPickFile();
 109         void          setLastButton();
 110
 111     private:
 112         bool          pickFileIfNone();
 113
 114         ButtonGroup*     mGroup;         // button group which radio button is in
 115         LineEdit*        mEdit;          // file name edit box, or null if none
 116         QPushButton*     mButton;        // push button to pick a file
 117         QString          mFile;          // saved file name (if mEdit is null)
 118         QAbstractButton* mLastButton;    // previous radio button selected
 119         bool             mRevertButton;  // true to revert to the previous radio button selection
 120 };
 121
 122 #endif // PICKFILERADIO_H
 123
 124 // vim: et sw=4: