1 /* 2 * KMix -- KDE's full featured mini mixer 3 * 4 * Copyright (C) 2017 Jonathan Marten <jjm@keelhaul.me.uk> 5 * 6 * This program is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU Library General Public 8 * License as published by the Free Software Foundation; either 9 * version 2 of the License, or (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 GNU 14 * Library General Public License for more details. 15 * 16 * You should have received a copy of the GNU Library General Public 17 * License along with this program; if not, see 18 * http://www.gnu.org/licenses/lgpl.html 19 */ 20 21 #ifndef DIALOGBASE_H 22 #define DIALOGBASE_H 23 24 #include <qdialog.h> 25 #include <qdialogbuttonbox.h> 26 27 class QSpacerItem; 28 class QVBoxLayout; 29 class KGuiItem; 30 class KConfigGroup; 31 class DialogStateSaver; 32 33 34 /** 35 * @short A wrapper for QDialog incorporating some convenience functions. 36 * 37 * This is a lightweight wrapper around QDialog, incorporating some useful 38 * functions which used to be provided by KDialog in KDE4. These are: 39 * 40 * - Managing the button box and providing access to its buttons 41 * - Managing the top level layout 42 * - Saving and restoring the dialog size 43 * 44 * @author Jonathan Marten 45 **/ 46 47 class DialogBase : public QDialog 48 { 49 Q_OBJECT 50 51 public: 52 /** 53 * Destructor. 54 * 55 **/ 56 virtual ~DialogBase() = default; 57 58 /** 59 * Retrieve the main widget. 60 * 61 * @return the main widget 62 **/ mainWidget()63 QWidget *mainWidget() const { return (mMainWidget); } 64 65 /** 66 * Get a spacing hint suitable for use within the dialog layout. 67 * 68 * @return The spacing hint 69 * @deprecated Kept for compatibility with KDE4. 70 * Use @c verticalSpacing() or @c horizontalSpacing() as appropriate. 71 **/ 72 static Q_DECL_DEPRECATED int spacingHint(); 73 74 /** 75 * Get a vertical spacing suitable for use within the dialog layout. 76 * 77 * @return The spacing hint 78 **/ 79 static int verticalSpacing(); 80 81 /** 82 * Get a horizontal spacing suitable for use within the dialog layout. 83 * 84 * @return The spacing hint 85 **/ 86 static int horizontalSpacing(); 87 88 /** 89 * Create a spacer item suitable for use within a vertical layout. 90 * 91 * @return The spacer item 92 **/ 93 static QSpacerItem *verticalSpacerItem(); 94 95 /** 96 * Create a spacer item suitable for use within a horizontal layout. 97 * 98 * @return The spacer item 99 **/ 100 static QSpacerItem *horizontalSpacerItem(); 101 102 /** 103 * Access the dialog's button box. 104 * 105 * @return the button box 106 **/ buttonBox()107 QDialogButtonBox *buttonBox() const { return (mButtonBox); } 108 109 /** 110 * Set the standard buttons to be displayed within the button box. 111 * 112 * @param buttons The buttons required 113 * 114 * @note This can be called at any time and the buttons will change 115 * accordingly. However, the buttons will be regenerated which means 116 * that any special button text or icons, or any signal connections from 117 * them, will be lost. 118 **/ 119 void setButtons(QDialogButtonBox::StandardButtons buttons); 120 121 /** 122 * Set the enable state of a button. 123 * 124 * @param button The button to set 125 * @param state The enable state for the button 126 **/ 127 void setButtonEnabled(QDialogButtonBox::StandardButton button, bool state = true); 128 129 /** 130 * Set the text of a button. 131 * 132 * @param button The button to set 133 * @param state The new text for the button 134 * 135 * @note This can be called at any time, and the button will change 136 * accordingly. 137 **/ 138 void setButtonText(QDialogButtonBox::StandardButton button, const QString &text); 139 140 /** 141 * Set the icon of a button. 142 * 143 * @param button The button to set 144 * @param state The new icon for the button 145 * 146 * @note This can be called at any time, and the button will change 147 * accordingly. 148 **/ 149 void setButtonIcon(QDialogButtonBox::StandardButton button, const QIcon &icon); 150 151 /** 152 * Set up a button from a @c KGuiItem. 153 * 154 * @param button The button to set 155 * @param guiItem The @c KGuiItem for the button 156 * 157 * @note This can be called at any time, and the button will change 158 * accordingly. 159 **/ 160 void setButtonGuiItem(QDialogButtonBox::StandardButton button, const KGuiItem &guiItem); 161 162 /** 163 * Set a state saver for the dialog. 164 * 165 * This may be a subclass of a DialogStateSaver, reimplemented in 166 * order to save special dialog settings (e.g. the column states of 167 * a list view). If this is not set then a default DialogStateSaver 168 * will be created and used internally. If a NULL state saver is 169 * set explicitly using this function, then no state restoring or 170 * saving will be done. 171 * 172 * @param saver the state saver 173 * 174 * @note The saver should be set before the dialog is shown for 175 * the first time. 176 * @note The DialogBase will take ownership of the specified 177 * state saver, and delete it when finished. 178 * @see DialogStateSaver 179 **/ 180 void setStateSaver(DialogStateSaver *saver); 181 182 /** 183 * Access the state saver used by the dialog. 184 * 185 * This may be the default one, or that set by @c setStateSaver(). 186 * 187 * @return the state saver 188 **/ stateSaver()189 DialogStateSaver *stateSaver() const { return (mStateSaver); } 190 191 protected: 192 /** 193 * Constructor. 194 * 195 * @param pnt Parent widget 196 **/ 197 explicit DialogBase(QWidget *pnt = nullptr); 198 199 /** 200 * Set the main widget to be displayed within the dialog. 201 * 202 * @param w The widget 203 **/ 204 void setMainWidget(QWidget *w); 205 206 private: 207 QVBoxLayout *mMainLayout; 208 QDialogButtonBox *mButtonBox; 209 QWidget *mMainWidget; 210 DialogStateSaver *mStateSaver; 211 }; 212 213 #endif // DIALOGBASE_H 214