konfiguratorpage.h

LINUX 下, 以 QT/KDE 写的档案管理员

/* **************************************************************************
                       konfiguratorpage.h  -  description
                             -------------------
    copyright            : (C) 2003 by Csaba Karai
    e-mail               : [e-mail]
    web site             : http://krusader.sourceforge.net
 ---------------------------------------------------------------------------
  Description
 ***************************************************************************

  A

     db   dD d8888b. db    db .d8888.  .d8b.  d8888b. d88888b d8888b.
     88 ,8P' 88  `8D 88    88 88'  YP d8' `8b 88  `8D 88'     88  `8D
     88,8P   88oobY' 88    88 `8bo.   88ooo88 88   88 88ooooo 88oobY'
     88`8b   88`8b   88    88   `Y8b. 88~~~88 88   88 88~~~~~ 88`8b
     88 `88. 88 `88. 88b  d88 db   8D 88   88 88  .8D 88.     88 `88.
     YP   YD 88   YD ~Y8888P' `8888Y' YP   YP Y8888D' Y88888P 88   YD

                                                     H e a d e r    F i l e

 ***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 ***************************************************************************/

#ifndef __KONFIGURATOR_PAGE_H__
#define __KONFIGURATOR_PAGE_H__
 
#include "konfiguratoritems.h"
#include <qframe.h>
#include <qptrlist.h>
#include <qgroupbox.h>
#include <qlabel.h>
#include <qlayout.h>

struct KONFIGURATOR_CHECKBOX_PARAM;
struct KONFIGURATOR_NAME_VALUE_TIP;
struct KONFIGURATOR_NAME_VALUE_PAIR;

/**
  * KonfiguratorPage is responsible for handling pages in Konfigurator.
  * It provides simple methods for create and manage Konfigurator pages.
  *
  * @short The base class of a page in Konfigurator
  */  
class KonfiguratorPage : public QFrame
{
  Q_OBJECT
   
public:
/**
  * The constructor of the KonfiguratorPage class.
  *
  * @param firstTime    this parameter is true if it is the first call of Konfigurator
  * @param parent       reference to the parent widget
  * @param name         name of the newly generated Konfigurator page widget
  */
  KonfiguratorPage( bool firstTime, QWidget* parent,  const char* name );

  /**
    * Applies the changes in the Konfigurator page.
    *
    * Writes out all relevent information to the konfiguration object and synchronizes
    * it with the file storage (hard disk, krusaderrc file). This function calls the apply()
    * method of each konfigurator item and finally performs the synchronization.
    *
    * @return             a boolean value indicates that Krusader restart is needed for the correct change
    */
  virtual bool apply();

  /**
    * Sets every konfigurator item to its default value on the page.
    *
    * This method calls the setDefaults() method of each konfigurator item. This function
    * doesn't modify the current configuration, only the values of the GUI items. The
    * apply() method must be called for finalizing the changes.
    */
  virtual void setDefaults();

  /**
    * Reloads the original value of each konfigurator item from the configuration object.
    *
    * This function calls the loadInitialValue() method of each konfigurator item.
    * Used to rollback the changes on the konfigurator page. Called if the user
    * responds 'No' to the "Apply changes" question.
    */
  virtual void loadInitialValues();

  /**
    * Checks whether the page was changed.
    *
    * This function calls the isChanged() method of each konfigurator item and
    * performs logical OR operation on them. Actually, this function returns true
    * if any of the konfigurator items was changed.
    *
    * @return             true if at least one of the konfigurator items was changed
    */
  virtual bool isChanged();

  /**
    * Flag, indicates the first call of Konfigurator
    * @return             true if konfigurator was started at the first time
    */
  inline  bool isFirst()   {return firstCall;}

  /**
    * This method is used to query the active subpage from the Konfigurator
    * @return             the active page (by default the first page)
    */
  virtual int activeSubPage() {return FIRST_PAGE;}

  /**
    * Adds a new checkbox item to the page.
    * <br>The checkbox widget's name is QString(cls + "/" + name).ascii()<br>
    *
    * Sample:<br><br>
    * KonfiguratorCheckBox *myCheckBox = createCheckBox( "class", "name", false, parentWidget );<br>
    * myLayout->addWidget( myCheckBox, 0, 0 );
    *
    * @param  cls         The class name used in KConfig (ex. "Archives")
    * @param  name        The item name used in KConfig (ex. "Do Tar")
    * @param  dflt        The default value of the checkbox
    * @param  text        The text field of the checkbox
    * @param  parent      Reference to the parent widget
    * @param  rst         The change of this parameter requires Krusader restart
    * @param  toolTip     Tooltip used for this checkbox
    * @param  pg          The subpage of a Konfigurator page (because of setDefaults)
    *
    * @return             reference to the newly created checkbox
    */
  KonfiguratorCheckBox    *createCheckBox( QString cls, QString name, bool dflt,
                                           QString text, QWidget *parent=0, bool rst=false,
                                           QString toolTip = QString::null, int pg=FIRST_PAGE );

  /**
    * Adds a new spinbox item to the page.
    * <br>The spinbox widget's name is QString(cls + "/" + name).ascii()<br>
    *
    * Sample:<br><br>
    * KonfiguratorSpinBox *mySpinBox = createSpinBox( "class", "name", 10, 1, 100, parentWidget );<br>
    * myLayout->addWidget( mySpinBox, 0, 0 );
    *
    * @param  cls         The class name used in KConfig (ex. "Archives")
    * @param  name        The item name used in KConfig (ex. "Do Tar")
    * @param  dflt        The default value of the spinbox
    * @param  min         The minimum value of the spinbox
    * @param  max         The maximum value of the spinbox
    * @param  parent      Reference to the parent widget
    * @param  rst         The change of this parameter requires Krusader restart
    * @param  pg          The subpage of a Konfigurator page (because of setDefaults)
    *
    * @return             reference to the newly created spinbox
    */
  KonfiguratorSpinBox     *createSpinBox(  QString cls, QString name, int dflt, int min,
                                           int max, QWidget *parent = 0, bool rst = false, int pg=FIRST_PAGE );

  /**
    * Adds a new editbox item to the page.
    * <br>The editbox widget's name is QString(cls + "/" + name).ascii()<br>
    *
    * Sample:<br><br>
    * KonfiguratorEditBox *myEditBox = createEditBox( "class", "name", "default", parentWidget );<br>
    * myLayout->addWidget( myEditBox, 0, 0 );
    *
    * @param  cls         The class name used in KConfig (ex. "Archives")
    * @param  name        The itemname used in KConfig (ex. "Do Tar")
    * @param  dflt        The default value of the editbox
    * @param  parent      Reference to the parent widget
    * @param  rst         The change of this parameter requires Krusader restart
    * @param  pg          The subpage of a Konfigurator page (because of setDefaults)
    *
    * @return             reference to the newly created editbox
    */
  KonfiguratorEditBox     *createEditBox(  QString cls, QString name, QString dflt,
                                           QWidget *parent=0, bool rst=false, int pg=FIRST_PAGE );

  /**
    * Adds a new listbox item to the page.
    * <br>The listbox widget's name is QString(cls + "/" + name).ascii()<br>
    *
    * Sample:<br><br>
    * QStringList valueList;<br>
    * valueList += "item";<br>
    * KonfiguratorListBox *myListBox = createListBox( "class", "name", valueList, parentWidget );<br>
    * myLayout->addWidget( myListBox, 0, 0 );
    *
    * @param  cls         The class name used in KConfig (ex. "Archives")
    * @param  name        The itemname used in KConfig (ex. "Do Tar")
    * @param  dflt        The default value of the listbox
    * @param  parent      Reference to the parent widget
    * @param  rst         The change of this parameter requires Krusader restart
    * @param  pg          The subpage of a Konfigurator page (because of setDefaults)
    *
    * @return             reference to the newly created editbox
    */
  KonfiguratorListBox     *createListBox(  QString cls, QString name, QStringList dflt,
                                           QWidget *parent=0, bool rst=false, int pg=FIRST_PAGE );

  /**
    * Adds a new URL requester item to the page.
    * <br>The URL requester widget's name is QString(cls + "/" + name).ascii()<br>
    *
    * Sample:<br><br>
    * KonfiguratorURLRequester *myURLRequester = createURLRequester( "class", "name", "default", parentWidget );<br>
    * myLayout->addWidget( myURLRequester, 0, 0 );
    *
    * @param  cls         The class name used in KConfig (ex. "Archives")
    * @param  name        The itemname used in KConfig (ex. "Do Tar")
    * @param  dflt        The default value of the URL requester
    * @param  text        The text field of the URL requester
    * @param  parent      Reference to the parent widget
    * @param  rst         The change of this parameter requires Krusader restart
    * @param  pg          The subpage of a Konfigurator page (because of setDefaults)
    *
    * @return             reference to the newly created URL requester
    */
  KonfiguratorURLRequester *createURLRequester(  QString cls, QString name,
                                           QString dflt, QWidget *parent, bool rst, int pg=FIRST_PAGE );

  /**
    * Adds a new font chooser item to the page.
    * <br>The font chooser widget's name is QString(cls + "/" + name).ascii()<br>
    *
    * Sample:<br><br>
    * KonfiguratorFontChooser *myFontChooser = createFontChooser( "class", "name", new QFont(), parentWidget );<br>
    * myLayout->addWidget( myFontChooser, 0, 0 );
    *
    * @param  cls         The class name used in KConfig (ex. "Archives")
    * @param  name        The item name used in KConfig (ex. "Do Tar")
    * @param  dflt        The default value of the font chooser
    * @param  parent      Reference to the parent widget
    * @param  rst         The change of this parameter requires Krusader restart
    * @param  pg          The subpage of a Konfigurator page (because of setDefaults)
    *
    * @return             reference to the newly created font chooser
    */
  KonfiguratorFontChooser *createFontChooser(  QString cls, QString name, QFont *dflt,
                                           QWidget *parent=0, bool rst=false, int pg=FIRST_PAGE );

  /**
    * Adds a new combobox item to the page.
    * <br>The combobox widget's name is QString(cls + "/" + name).ascii()<br>
    *
    * Sample:<br><br>
    * KONFIGURATOR_NAME_VALUE_PAIR comboInfo[] =<br>
    * &nbsp;{{ i18n( "combo text1" ), "value1" },<br>
    * &nbsp;&nbsp;{ i18n( "combo text2" ), "value2" },<br>
    * &nbsp;&nbsp;{ i18n( "combo text3" ), "value3" }};<br><br>
    * KonfiguratorComboBox *myComboBox = createComboBox( "class", "name", "value2", comboInfo, 3, parentWidget );<br>
    * myLayout->addWidget( myComboBox, 0, 0 );
    *
    * @param  cls         The class name used in KConfig (ex. "Archives")
    * @param  name        The item name used in KConfig (ex. "Do Tar")
    * @param  dflt        The default value of the combobox
    * @param  params      Pointer to the name-value pair array (combo elements)
    * @param  paramNum    Number of the combobox elements
    * @param  text        The text field of the combobox