File indexing completed on 2024-05-12 09:58:05
0001 /* 0002 SPDX-FileCopyrightText: 2003 Csaba Karai <krusader@users.sourceforge.net> 0003 SPDX-FileCopyrightText: 2004-2022 Krusader Krew <https://krusader.org> 0004 0005 SPDX-License-Identifier: GPL-2.0-or-later 0006 */ 0007 0008 #ifndef KONFIGURATORPAGE_H 0009 #define KONFIGURATORPAGE_H 0010 0011 // QtWidgets 0012 #include <QGridLayout> 0013 #include <QGroupBox> 0014 #include <QLabel> 0015 #include <QLayout> 0016 #include <QScrollArea> 0017 0018 #include "konfiguratoritems.h" 0019 0020 struct KONFIGURATOR_CHECKBOX_PARAM; 0021 0022 /** 0023 * KonfiguratorPage is responsible for handling pages in Konfigurator. 0024 * It provides simple methods for create and manage Konfigurator pages. 0025 * 0026 * @short The base class of a page in Konfigurator 0027 */ 0028 class KonfiguratorPage : public QScrollArea 0029 { 0030 Q_OBJECT 0031 0032 public: 0033 /** 0034 * The constructor of the KonfiguratorPage class. 0035 * 0036 * @param firstTime this parameter is true if it is the first call of Konfigurator 0037 * @param parent reference to the parent widget 0038 */ 0039 KonfiguratorPage(bool firstTime, QWidget *parent); 0040 0041 /** 0042 * Applies the changes in the Konfigurator page. 0043 * 0044 * Writes out all relevant information to the configuration object and synchronizes 0045 * it with the file storage (hard disk, krusaderrc file). This function calls the apply() 0046 * method of each konfigurator item and finally performs the synchronization. 0047 * 0048 * @return a boolean value indicates that Krusader restart is needed for the correct change 0049 */ 0050 virtual bool apply(); 0051 0052 /** 0053 * Sets every konfigurator item to its default value on the page. 0054 * 0055 * This method calls the setDefaults() method of each konfigurator item. This function 0056 * doesn't modify the current configuration, only the values of the GUI items. The 0057 * apply() method must be called for finalizing the changes. 0058 */ 0059 virtual void setDefaults(); 0060 0061 /** 0062 * Reloads the original value of each konfigurator item from the configuration object. 0063 * 0064 * This function calls the loadInitialValue() method of each konfigurator item. 0065 * Used to rollback the changes on the konfigurator page. Called if the user 0066 * responds 'No' to the "Apply changes" question. 0067 */ 0068 virtual void loadInitialValues(); 0069 0070 /** 0071 * Checks whether the page was changed. 0072 * 0073 * This function calls the isChanged() method of each konfigurator item and 0074 * performs logical OR operation on them. Actually, this function returns true 0075 * if any of the konfigurator items was changed. 0076 * 0077 * @return true if at least one of the konfigurator items was changed 0078 */ 0079 virtual bool isChanged(); 0080 0081 /** 0082 * Flag, indicates the first call of Konfigurator 0083 * @return true if konfigurator was started at the first time 0084 */ 0085 inline bool isFirst() 0086 { 0087 return firstCall; 0088 } 0089 0090 /** 0091 * This method is used to query the active subpage from the Konfigurator 0092 * @return the active page (by default the first page) 0093 */ 0094 virtual int activeSubPage() 0095 { 0096 return FIRST_PAGE; 0097 } 0098 0099 /** 0100 * Adds a new checkbox item to the page. 0101 * <br>The checkbox widget's name is QString(configGroup + "/" + name).ascii()<br> 0102 * 0103 * Sample:<br><br> 0104 * KonfiguratorCheckBox *myCheckBox = createCheckBox( "class", "name", false, parentWidget);<br> 0105 * myLayout->addWidget( myCheckBox, 0, 0 ); 0106 * 0107 * @param configGroup The class name used in KConfig (ex. "Archives") 0108 * @param name The item name used in KConfig (ex. "Do Tar") 0109 * @param defaultValue The default value of the checkbox 0110 * @param text The text field of the checkbox 0111 * @param parent Reference to the parent widget 0112 * @param restart The change of this parameter requires Krusader restart 0113 * @param toolTip Tooltip used for this checkbox 0114 * @param page The subpage of a Konfigurator page (because of setDefaults) 0115 * 0116 * @return reference to the newly created checkbox 0117 */ 0118 KonfiguratorCheckBox *createCheckBox(QString configGroup, 0119 QString name, 0120 bool defaultValue, 0121 QString text, 0122 QWidget *parent = nullptr, 0123 bool restart = false, 0124 const QString &toolTip = QString(), 0125 int page = FIRST_PAGE); 0126 0127 /** 0128 * Adds a new spinbox item to the page. 0129 * <br>The spinbox widget's name is QString(configGroup + "/" + name).ascii()<br> 0130 * 0131 * Sample:<br><br> 0132 * KonfiguratorSpinBox *mySpinBox = createSpinBox( "class", "name", 10, 1, 100, parentWidget);<br> 0133 * myLayout->addWidget( mySpinBox, 0, 0 ); 0134 * 0135 * @param configGroup The class name used in KConfig (ex. "Archives") 0136 * @param configName The item name used in KConfig (ex. "Do Tar") 0137 * @param defaultValue The default value of the spinbox 0138 * @param min The minimum value of the spinbox 0139 * @param max The maximum value of the spinbox 0140 * @param label The label that is associated to the spinbox 0141 * @param parent Reference to the parent widget 0142 * @param restart The change of this parameter requires Krusader restart 0143 * @param toolTip Tooltip used for this spinbox 0144 * @param page The subpage of a Konfigurator page (because of setDefaults) 0145 * 0146 * @return reference to the newly created spinbox 0147 */ 0148 KonfiguratorSpinBox *createSpinBox(QString configGroup, 0149 QString configName, 0150 int defaultValue, 0151 int min, 0152 int max, 0153 QLabel *label, 0154 QWidget *parent = nullptr, 0155 bool restart = false, 0156 const QString &toolTip = QString(), 0157 int page = FIRST_PAGE); 0158 0159 /** 0160 * Adds a new editbox item to the page. 0161 * <br>The editbox widget's name is QString(configGroup + "/" + name).ascii()<br> 0162 * 0163 * Sample:<br><br> 0164 * KonfiguratorEditBox *myEditBox = createEditBox( "class", "name", "default", parentWidget);<br> 0165 * myLayout->addWidget( myEditBox, 0, 0 ); 0166 * 0167 * @param configGroup The class name used in KConfig (ex. "Archives") 0168 * @param name The itemname used in KConfig (ex. "Do Tar") 0169 * @param defaultValue The default value of the editbox 0170 * @param label The label that is associated to the editbox 0171 * @param parent Reference to the parent widget 0172 * @param restart The change of this parameter requires Krusader restart 0173 * @param toolTip Tooltip used for this editbox 0174 * @param page The subpage of a Konfigurator page (because of setDefaults) 0175 * 0176 * @return reference to the newly created editbox 0177 */ 0178 KonfiguratorEditBox *createEditBox(QString configGroup, 0179 QString name, 0180 QString defaultValue, 0181 QLabel *label, 0182 QWidget *parent = nullptr, 0183 bool restart = false, 0184 const QString &toolTip = QString(), 0185 int page = FIRST_PAGE); 0186 0187 /** 0188 * Adds a new listbox item to the page. 0189 * <br>The listbox widget's name is QString(configGroup + "/" + name).ascii()<br> 0190 * 0191 * Sample:<br><br> 0192 * QStringList valueList;<br> 0193 * valueList += "item";<br> 0194 * KonfiguratorListBox *myListBox = createListBox( "class", "name", valueList, parentWidget);<br> 0195 * myLayout->addWidget( myListBox, 0, 0 ); 0196 * 0197 * @param configGroup The class name used in KConfig (ex. "Archives") 0198 * @param name The itemname used in KConfig (ex. "Do Tar") 0199 * @param defaultValue The default value of the listbox 0200 * @param parent Reference to the parent widget 0201 * @param restart The change of this parameter requires Krusader restart 0202 * @param toolTip Tooltip used for this listbox 0203 * @param page The subpage of a Konfigurator page (because of setDefaults) 0204 * 0205 * @return reference to the newly created editbox 0206 */ 0207 KonfiguratorListBox *createListBox(QString configGroup, 0208 QString name, 0209 QStringList defaultValue, 0210 QWidget *parent = nullptr, 0211 bool restart = false, 0212 const QString &toolTip = QString(), 0213 int page = FIRST_PAGE); 0214 0215 /** 0216 * Adds a new URL requester item to the page. 0217 * <br>The URL requester widget's name is QString(configGroup + "/" + name).ascii()<br> 0218 * 0219 * Sample:<br><br> 0220 * KonfiguratorURLRequester *myURLRequester = createURLRequester( "class", "name", "default", parentWidget );<br> 0221 * myLayout->addWidget( myURLRequester, 0, 0 ); 0222 * 0223 * @param configGroup The class name used in KConfig (ex. "Archives") 0224 * @param name The itemname used in KConfig (ex. "Do Tar") 0225 * @param defaultValue The default value of the URL requester 0226 * @param label The label that is associated to the URL requester 0227 * @param parent Reference to the parent widget 0228 * @param restart The change of this parameter requires Krusader restart 0229 * @param toolTip Tooltip used for this URL requester 0230 * @param page The subpage of a Konfigurator page (because of setDefaults) 0231 * @param expansion Whether to perform url expansion 0232 * 0233 * @return reference to the newly created URL requester 0234 */ 0235 KonfiguratorURLRequester *createURLRequester(QString configGroup, 0236 QString name, 0237 QString defaultValue, 0238 QLabel *label, 0239 QWidget *parent, 0240 bool restart, 0241 const QString &toolTip = QString(), 0242 int page = FIRST_PAGE, 0243 bool expansion = true); 0244 0245 /** 0246 * Adds a new font chooser item to the page. 0247 * <br>The font chooser widget's name is QString(configGroup + "/" + name).ascii()<br> 0248 * 0249 * Sample:<br><br> 0250 * KonfiguratorFontChooser *myFontChooser = createFontChooser( "class", "name", QFont(), parentWidget );<br> 0251 * myLayout->addWidget( myFontChooser, 0, 0 ); 0252 * 0253 * @param configGroup The class name used in KConfig (ex. "Archives") 0254 * @param name The item name used in KConfig (ex. "Do Tar") 0255 * @param defaultValue The default value of the font chooser 0256 * @param label The label that is associated to the font chooser 0257 * @param parent Reference to the parent widget 0258 * @param restart The change of this parameter requires Krusader restart 0259 * @param page The subpage of a Konfigurator page (because of setDefaults) 0260 * 0261 * @return reference to the newly created font chooser 0262 */ 0263 KonfiguratorFontChooser *createFontChooser(QString configGroup, 0264 QString name, 0265 const QFont &defaultValue, 0266 QLabel *label, 0267 QWidget *parent = nullptr, 0268 bool restart = false, 0269 const QString &toolTip = QString(), 0270 int page = FIRST_PAGE); 0271 0272 /** 0273 * Adds a new combobox item to the page. 0274 * <br>The combobox widget's name is QString(configGroup + "/" + name).ascii()<br> 0275 * 0276 * Sample:<br><br> 0277 * KONFIGURATOR_NAME_VALUE_PAIR comboInfo[] =<br> 0278 * {{ i18n( "combo text1" ), "value1" },<br> 0279 * { i18n( "combo text2" ), "value2" },<br> 0280 * { i18n( "combo text3" ), "value3" }};<br><br> 0281 * KonfiguratorComboBox *myComboBox = createComboBox( "class", "name", "value2", comboInfo, 3, parentWidget );<br> 0282 * myLayout->addWidget( myComboBox, 0, 0 ); 0283 * 0284 * @param configGroup The class name used in KConfig (ex. "Archives") 0285 * @param name The item name used in KConfig (ex. "Do Tar") 0286 * @param defaultValue The default value of the combobox 0287 * @param params Pointer to the name-value pair array (combo elements) 0288 * @param paramNum Number of the combobox elements 0289 * @param label The label that is associated to the combobox 0290 * @param parent Reference to the parent widget 0291 * @param restart The change of this parameter requires Krusader restart 0292 * @param editable Flag indicates that the combo can be edited 0293 * @param toolTip Tooltip used for this combobox 0294 * @param page The subpage of a Konfigurator page (because of setDefaults) 0295 * 0296 * @return reference to the newly created combobox 0297 */ 0298 KonfiguratorComboBox *createComboBox(QString configGroup, 0299 QString name, 0300 QString defaultValue, 0301 KONFIGURATOR_NAME_VALUE_PAIR *params, 0302 int paramNum, 0303 QLabel *label, 0304 QWidget *parent = nullptr, 0305 bool restart = false, 0306 bool editable = false, 0307 const QString &toolTip = QString(), 0308 int page = FIRST_PAGE); 0309 0310 /** 0311 * Creates a frame on the page. 0312 * 0313 * Sample:<br><br> 0314 * QGroupBox *myGroup = createFrame( i18n( "MyFrameName" ), parentWidget, "frameName" );<br> 0315 * myLayout->addWidget( myGroup, 0, 0 ); 0316 * 0317 * @param text The text written out onto the frame 0318 * @param parent Reference to the parent widget 0319 * 0320 * @return reference to the newly created frame 0321 */ 0322 QGroupBox *createFrame(const QString &text = QString(), QWidget *parent = nullptr); 0323 0324 /** 0325 * Creates a new QGridLayout element and sets its margins. 0326 * 0327 * Sample:<br><br> 0328 * QGroupBox *myGroup = createFrame( i18n( "MyFrameName" ), parentWidget, "frameName" );<br> 0329 * QGridLayout *myLayout = createGridLayout( myGroup ) );<br> 0330 * myLayout->addWidget( myGroup, 0, 0 ); 0331 * 0332 * @param parent Reference to the parent layout 0333 * 0334 * @return reference to the newly created QGridLayout 0335 */ 0336 QGridLayout *createGridLayout(QWidget *parent); 0337 0338 /** 0339 * Adds a new label to a grid layout. 0340 * 0341 * Sample:<br><br> 0342 * QGroupBox *myGroup = createFrame( i18n( "MyFrameName" ), parentWidget, "frameName" );<br> 0343 * QGridLayout *myLayout = createGridLayout( myGroup->layout() );<br> 0344 * addLabel( myLayout, 0, 0, i18n( "Hello world!" ), myGroup, "myLabel" );<br> 0345 * mainLayout->addWidget( myGroup, 0, 0 ); 0346 * 0347 * @param layout The grid layout on which the item will be placed 0348 * @param x the column to which the label will be placed 0349 * @param y the row to which the label will be placed 0350 * @param label the text of the label 0351 * @param parent Reference to the parent widget 0352 * 0353 * @return reference to the newly created label 0354 */ 0355 QLabel *addLabel(QGridLayout *layout, int x, int y, const QString &label, QWidget *parent = nullptr); 0356 0357 /** 0358 * Creates a spacer object (for justifying in QHBox). 0359 * 0360 * Sample:<br><br> 0361 * QHBox *hbox = new QHBox( myParent, "hbox" );<br> 0362 * createSpinBox( "class", "spin", 5, 1, 10, hbox );<br> 0363 * createSpacer( hbox );<br> 0364 * myLayout->addWidget( hbox, 0, 0 ); 0365 * 0366 * @param parent Reference to the parent widget 0367 * 0368 * @return reference to the newly created spacer widget 0369 */ 0370 QWidget *createSpacer(QWidget *parent = nullptr); 0371 0372 /** 0373 * Creates a separator line. 0374 * 0375 * Sample:<br><br> 0376 * QFrame *myLine = createLine( myParent, "myLine" );<br> 0377 * myLayout->addWidget( myLine, 1, 0 );<br> 0378 * 0379 * @param parent Reference to the parent widget 0380 * @param vertical Means vertical line 0381 * 0382 * @return reference to the newly created spacer widget 0383 */ 0384 QFrame *createLine(QWidget *parent = nullptr, bool vertical = false); 0385 0386 /** 0387 * Creates a checkbox group. A checkbox group contains a lot of checkboxes. 0388 * The grouped checkboxes are embedded into one widget, which can be placed anywhere 0389 * on the GUI. The placing of the elements can be horizontal or vertical in the group. 0390 * At horizontal placing the sizex integer defines the maximum element number in 0391 * one row, sizey is 0. At vertical placing sizex is 0, and sizey defines the 0392 * maximum row number in one column. <br> 0393 * 0394 * One specific element can be reached by its name or index with the find methods. 0395 * The first element is checkBoxGroup->find( 0 ), "myCb" element is checkBoxGroup->find( "myCb") ... 0396 * 0397 * Sample:<br><br> 0398 * KONFIGURATOR_CHECKBOX_PARAM myCBArray[] =<br> 0399 * {{"CbClass","CbName1", false, i18n( "name1" ), false, "tooltip1"},<br> 0400 * {"CbClass","CbName2", true, i18n( "name2" ), false, "tooltip2"},<br> 0401 * {"CbClass","CbName3", true, i18n( "name3" ), false, "tooltip3"}};<br><br> 0402 * KonfiguratorCheckBoxGroup *myCheckBoxGroup = createCheckBoxGroup( 1, 0, myCBArray, 3, myParent, "myCheckboxGroup" );<br> 0403 * myCheckBoxGroup->find( 0 )->setEnabled( false );<br><br> 0404 * myLayout->addWidget( myCheckBoxGroup, 0, 0 );<br> 0405 * 0406 * @param sizex the maximum column number at horizontal placing 0407 * @param sizey the maximum row number at vertical placing 0408 * @param params pointer to the checkbox array 0409 * @param paramNum number of the checkbox elements 0410 * @param parent Reference to the parent widget 0411 * @param page The subpage of a Konfigurator page (because of setDefaults) 0412 * 0413 * @return reference to the newly created checkbox group widget 0414 */ 0415 KonfiguratorCheckBoxGroup * 0416 createCheckBoxGroup(int sizex, int sizey, KONFIGURATOR_CHECKBOX_PARAM *params, int paramNum, QWidget *parent = nullptr, int page = FIRST_PAGE); 0417 /** 0418 * Creates a radio button group. A radio button group contains a lot of radio buttons. 0419 * The grouped buttons are embedded into one widget, which can be placed anywhere 0420 * on the GUI. The placing of the elements can be horizontal or vertical in the group. 0421 * At horizontal placing the sizex integer defines the maximum element number in 0422 * one row, sizey is 0. At vertical placing sizex is 0, and sizey defines the 0423 * maximum row number in one column.<br> 0424 * 0425 * The references of the buttons can be accessed by the find methods of KonfiguratorRadioButtons. 0426 * The first element is myRadioGrp->find( 0 ), "myRadio" element is myRadioGrp->find( "myRadio") ... 0427 * 0428 * Sample:<br><br> 0429 * KONFIGURATOR_NAME_VALUE_TIP radioInfo[] =<br> 0430 * {{ i18n( "radio text1" ), "value1", i18n( "tooltip1" ) },<br> 0431 * { i18n( "radio text2" ), "value2", i18n( "tooltip2" ) },<br> 0432 * { i18n( "radio text3" ), "value3", i18n( "tooltip3" ) }};<br><br> 0433 * KonfiguratorRadioButtons *myRadioGroup = createRadioButtonGroup( "class", "name", "value1", 0434 * 1, 0, radioInfo, 3, myParent, "myRadioGroup" );<br> 0435 * myRadioGroup->find( i18n( "radio text1" ) )->setEnabled( false );<br> 0436 * myLayout->addWidget( myRadioGroup, 0, 0 );<br> 0437 * 0438 * @param configGroup The class name used in KConfig (ex. "Archives") 0439 * @param name The item name used in KConfig (ex. "Do Tar") 0440 * @param defaultValue The default value of the radio buttons 0441 * @param sizex the maximum column number at horizontal placing 0442 * @param sizey the maximum row number at vertical placing 0443 * @param params pointer to the checkbox array 0444 * @param paramNum number of the checkbox elements 0445 * @param parent Reference to the parent widget 0446 * @param restart The change of this parameter requires Krusader restart 0447 * @param page The subpage of a Konfigurator page (because of setDefaults) 0448 * 0449 * @return reference to the newly created radio button group widget 0450 */ 0451 KonfiguratorRadioButtons *createRadioButtonGroup(QString configGroup, 0452 QString name, 0453 QString defaultValue, 0454 int sizex, 0455 int sizey, 0456 KONFIGURATOR_NAME_VALUE_TIP *params, 0457 int paramNum, 0458 QWidget *parent = nullptr, 0459 bool restart = false, 0460 int page = FIRST_PAGE); 0461 0462 /** 0463 * This function is used to insert new, unknown items into KonfiguratorPage. The 0464 * item must be derived from KonfiguratorExtension class, which have 0465 * isChanged(), apply(), setDefaults, loadInitialValue() methods. After that, the 0466 * object is properly handled by Konfigurator page. 0467 * 0468 * 0469 * @param item The item to be added to KonfiguratorPage 0470 */ 0471 void registerObject(KonfiguratorExtension *item); 0472 0473 /** 0474 * This function is used to remove elements from KonfiguratorPage. 0475 * 0476 * Sample:<br><br> 0477 * KonfiguratorEditBox *myEditBox = createEditBox( "class", "name", "default", parentWidget);<br> 0478 * myLayout->addWidget( myEditBox, 0, 0 );<br> 0479 * removeObject( myEditBox->extension() ); 0480 * 0481 * After the removeObject myEditBox will be untouched at apply(), setDefaults(), isChanged(), 0482 * loadInitialValues() methods of the KonfiguratorPage. 0483 * 0484 * @param item The item to be removed from KonfiguratorPage 0485 */ 0486 void removeObject(KonfiguratorExtension *item); 0487 0488 /** 0489 * Adds a new color chooser combobox item to the page. 0490 * <br>The chooser's widget's name is QString(configGroup + "/" + name).ascii()<br> 0491 * 0492 * Sample:<br><br> 0493 * KonfiguratorColorChooser *myColorChooser = createColorChooser( "class", "name", QColor( 255, 0, 255 ), parentWidget );<br> 0494 * myLayout->addWidget( myColorChooser, 0, 0 ); 0495 * 0496 * @param configGroup The class name used in KConfig (ex. "Archives") 0497 * @param name The item name used in KConfig (ex. "Do Tar") 0498 * @param defaultValue The default value of the color chooser 0499 * @param parent Reference to the parent widget 0500 * @param restart The change of this parameter requires Krusader restart 0501 * @param addColPtr The additional color values 0502 * @param addColNum Number of additional colors 0503 * @param page The subpage of a Konfigurator page (because of setDefaults) 0504 * 0505 * @return reference to the newly created combobox 0506 */ 0507 KonfiguratorColorChooser *createColorChooser(QString configGroup, 0508 QString name, 0509 QColor defaultValue, 0510 QWidget *parent = nullptr, 0511 bool restart = false, 0512 ADDITIONAL_COLOR *addColPtr = nullptr, 0513 int addColNum = 0, 0514 int page = FIRST_PAGE); 0515 signals: 0516 /** 0517 * The signal is emitted if the changed flag was modified in any konfigurator item. 0518 * Used for enabling/disabling the apply button. 0519 */ 0520 void sigChanged(); 0521 0522 protected: 0523 QList<KonfiguratorExtension *> itemList; 0524 0525 private: 0526 bool firstCall; 0527 }; 0528 0529 /** 0530 * KONFIGURATOR_CHECKBOX_PARAM is the basic item of checkbox arrays. It contains 0531 * every information related to a checkbox. 0532 */ 0533 struct KONFIGURATOR_CHECKBOX_PARAM { 0534 /** 0535 * The class used in KConfig (ex. "Archives") 0536 */ 0537 QString configClass; 0538 /** 0539 * The item name used in KConfig (ex. "Do Tar") 0540 */ 0541 QString configName; 0542 /** 0543 * The default value of the checkbox 0544 */ 0545 bool defaultValue; 0546 /** 0547 * The text field of the checkbox 0548 */ 0549 QString text; 0550 /** 0551 * The change of this parameter requires Krusader restart 0552 */ 0553 bool restart; 0554 /** 0555 * The checkbox's tooltip 0556 */ 0557 QString toolTip; 0558 }; 0559 0560 #endif /* __KONFIGURATOR_PAGE_H__ */