konfiguratorpage.h

来自「LINUX 下, 以 QT/KDE 写的档案管理员」· C头文件 代码 · 共 523 行 · 第 1/2 页

    * @param  parent      Reference to the parent widget
    * @param  rst         The change of this parameter requires Krusader restart
    * @param  editable    Flag indicates that the combo can be edited
    * @param  pg          The subpage of a Konfigurator page (because of setDefaults)
    *
    * @return             reference to the newly created combobox
    */
  KonfiguratorComboBox    *createComboBox(  QString cls, QString name, QString dflt,
                                           KONFIGURATOR_NAME_VALUE_PAIR *params, int paramNum,
                                           QWidget *parent=0, bool rst=false, bool editable=false, int pg=FIRST_PAGE );

  /**
    * Creates a frame on the page.
    *
    * Sample:<br><br>
    * QGroupBox *myGroup = createFrame( i18n( "MyFrameName" ), parentWidget, "frameName" );<br>
    * myLayout->addWidget( myGroup, 0, 0 );
    *
    * @param  text        The text written out onto the frame
    * @param  parent      Reference to the parent widget
    * @param  widgetName  The name of the widget
    *
    * @return             reference to the newly created frame
    */
  QGroupBox               *createFrame( QString text = QString::null, QWidget *parent=0,
                                           const char *widgetName=0 );

  /**
    * Creates a new QGridLayout element and sets its margins.
    *
    * Sample:<br><br>
    * QGroupBox *myGroup = createFrame( i18n( "MyFrameName" ), parentWidget, "frameName" );<br>
    * QGridLayout *myLayout = createGridLayout( myGroup->layout() );<br>
    * myLayout->addWidget( myGroup, 0, 0 );
    *
    * @param  parent      Reference to the parent layout
    *
    * @return             reference to the newly created QGridLayout
    */
  QGridLayout             *createGridLayout( QLayout *parent );

  /**
    * Adds a new label to a grid layout.
    *
    * Sample:<br><br>
    * QGroupBox *myGroup = createFrame( i18n( "MyFrameName" ), parentWidget, "frameName" );<br>
    * QGridLayout *myLayout = createGridLayout( myGroup->layout() );<br>
    * addLabel( myLayout, 0, 0, i18n( "Hello world!" ), myGroup, "myLabel" );<br>
    * mainLayout->addWidget( myGroup, 0, 0 );
    *
    * @param  layout      The grid layout on which the item will be placed
    * @param  x           the column to which the label will be placed
    * @param  y           the row to which the label will be placed
    * @param  label       the text of the label
    * @param  parent      Reference to the parent widget
    * @param  widgetName  The name of the newly generated label widget
    *
    * @return             reference to the newly created label
    */
  QLabel                  *addLabel( QGridLayout *layout, int x, int y, QString label,
                                           QWidget *parent=0, const char *widgetName=0 );

  /**
    * Creates a spacer object (for justifying in QHBox).
    *
    * Sample:<br><br>
    * QHBox *hbox = new QHBox( myParent, "hbox" );<br>
    * createSpinBox( "class", "spin", 5, 1, 10, hbox );<br>
    * createSpacer( hbox, "mySpacer" );<br>
    * myLayout->addWidget( hbox, 0, 0 );
    *
    * @param  parent      Reference to the parent widget
    * @param  widgetName  The name of the newly generated label widget
    *
    * @return             reference to the newly created spacer widget
    */
  QWidget                 *createSpacer( QWidget *parent=0, const char *widgetName=0 );

  /**
    * Creates a separator line.
    *
    * Sample:<br><br>
    * QFrame *myLine = createLine( myParent, "myLine" );<br>
    * myLayout->addWidget( myLine, 1, 0 );<br>
    *
    * @param  parent      Reference to the parent widget
    * @param  widgetName  The name of the newly generated label widget
    * @param  vertical    Means vertical line
    *
    * @return             reference to the newly created spacer widget
    */
  QFrame                  *createLine( QWidget *parent=0, const char *widgetName=0, bool vertical = false );

  /**
    * Creates a checkbox group. A checkbox group contains a lot of checkboxes.
    * The grouped checkboxes are embedded into one widget, which can be placed anywhere
    * on the GUI. The placing of the elements can be horizontal or vertical in the group.
    * At horizontal placing the sizex integer defines the maximum element number in
    * one row, sizey is 0. At vertical placing sizex is 0, and sizey defines the
    * maximum row number in one column. <br>
    *
    * One specific element can be reached by its name or index with the find methods.
    * The first element is checkBoxGroup->find( 0 ), "myCb" element is checkBoxGroup->find( "myCb" ) ...
    *
    * Sample:<br><br>
    * KONFIGURATOR_CHECKBOX_PARAM myCBArray[] =<br>
    * &nbsp;{{"CbClass","CbName1", false, i18n( "name1" ), false, "tooltip1"},<br>
    * &nbsp;&nbsp;{"CbClass","CbName2", true, i18n( "name2" ), false, "tooltip2"},<br>
    * &nbsp;&nbsp;{"CbClass","CbName3", true, i18n( "name3" ), false, "tooltip3"}};<br><br>
    * KonfiguratorCheckBoxGroup *myCheckBoxGroup = createCheckBoxGroup( 1, 0, myCBArray, 3, myParent, "myCheckboxGroup" );<br>
    * myCheckBoxGroup->find( 0 )->setEnabled( false );<br><br>
    * myLayout->addWidget( myCheckBoxGroup, 0, 0 );<br>
    *
    * @param  sizex       the maximum column number at horizontal placing
    * @param  sizey       the maximum row number at vertical placing
    * @param  params      pointer to the checkbox array
    * @param  paramNum    number of the checkbox elements
    * @param  parent      Reference to the parent widget
    * @param  widgetName  The name of the newly created checkbox group widget
    * @param  pg          The subpage of a Konfigurator page (because of setDefaults)
    *
    * @return             reference to the newly created checkbox group widget
    */
  KonfiguratorCheckBoxGroup *createCheckBoxGroup( int sizex, int sizey,
                                           KONFIGURATOR_CHECKBOX_PARAM *params, int paramNum,
                                           QWidget *parent=0, const char *widgetName=0, int pg=FIRST_PAGE );
  /**
    * Creates a radio button group. A radio button group contains a lot of radio buttons.
    * The grouped buttons are embedded into one widget, which can be placed anywhere
    * on the GUI. The placing of the elements can be horizontal or vertical in the group.
    * At horizontal placing the sizex integer defines the maximum element number in
    * one row, sizey is 0. At vertical placing sizex is 0, and sizey defines the
    * maximum row number in one column.<br>
    *
    * The references of the buttons can be accessed by the find methods of KonfiguratorRadioButtons.
    * The first element is myRadioGrp->find( 0 ), "myRadio" element is myRadioGrp->find( "myRadio" ) ...
    *
    * Sample:<br><br>
    * KONFIGURATOR_NAME_VALUE_TIP radioInfo[] =<br>
    * &nbsp;{{ i18n( "radio text1" ), "value1", i18n( "tooltip1" ) },<br>
    * &nbsp;&nbsp;{ i18n( "radio text2" ), "value2", i18n( "tooltip2" ) },<br>
    * &nbsp;&nbsp;{ i18n( "radio text3" ), "value3", i18n( "tooltip3" ) }};<br><br>
    * KonfiguratorRadioButtons *myRadioGroup = createRadioButtonGroup( "class", "name", "value1", 1, 0, radioInfo, 3, myParent, "myRadioGroup" );<br>
    * myRadioGroup->find( i18n( "radio text1" ) )->setEnabled( false );<br>
    * myLayout->addWidget( myRadioGroup, 0, 0 );<br>
    *
    * @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 radio buttons
    * @param  sizex       the maximum column number at horizontal placing
    * @param  sizey       the maximum row number at vertical placing
    * @param  params      pointer to the checkbox array
    * @param  paramNum    number of the checkbox elements
    * @param  parent      Reference to the parent widget
    * @param  widgetName  The name of the newly created button group 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 radio button group widget
    */
  KonfiguratorRadioButtons *createRadioButtonGroup( QString cls, QString name, 
                                           QString dflt, int sizex, int sizey,
                                           KONFIGURATOR_NAME_VALUE_TIP *params, int paramNum,
                                           QWidget *parent=0, const char *widgetName=0, bool rst=false, int pg=FIRST_PAGE );

  /**
    * This function is used to insert new, unknown items into KonfiguratorPage. The
    * item must be derived from KonfiguratorExtension class, which have
    * isChanged(), apply(), setDefaults, loadInitialValue() methods. After that, the
    * object is properly handled by Konfigurator page.
    *
    *
    * @param  item        The item to be added to KonfiguratorPage
    */
  void                    registerObject( KonfiguratorExtension *item );

  /**
    * This function is used to remove elements from KonfiguratorPage.
    *
    * Sample:<br><br>
    * KonfiguratorEditBox *myEditBox = createEditBox( "class", "name", "default", parentWidget );<br>
    * myLayout->addWidget( myEditBox, 0, 0 );<br>
    * removeObject( myEditBox->extension() );
    *
    * After the removeObject myEditBox will be untouched at apply(), setDefaults(), isChanged(),
    * loadInitialValues() methods of the KonfiguratorPage.
    *
    * @param  item        The item to be removed from KonfiguratorPage
    */
  void                    removeObject( KonfiguratorExtension *item );

  /**
    * Adds a new color chooser combobox item to the page.
    * <br>The chooser's widget's name is QString(cls + "/" + name).ascii()<br>
    *
    * Sample:<br><br>
    * KonfiguratorColorChooser *myColorChooser = createColorChooser( "class", "name", QColor( 255, 0, 255 ), parentWidget );<br>
    * myLayout->addWidget( myColorChooser, 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 color chooser
    * @param  parent      Reference to the parent widget
    * @param  rst         The change of this parameter requires Krusader restart
    * @param  addColPtr   The additional color values
    * @param  rst         Number of additional colors
    * @param  pg          The subpage of a Konfigurator page (because of setDefaults)
    *
    * @return             reference to the newly created combobox
    */
  KonfiguratorColorChooser *createColorChooser(  QString cls, QString name, QColor dflt,
                                                 QWidget *parent=0, bool rst=false,
                                                 ADDITIONAL_COLOR *addColPtr = 0, int addColNum = 0, int pg=FIRST_PAGE );
signals:
  /**
    * The signal is emitted if the changed flag was modified in any konfigurator item.
    * Used for enabling/disabling the apply button.
    */
  void  sigChanged();
  
protected:
  QPtrList<KonfiguratorExtension> itemList;

private:
  bool  firstCall;
};

/**
  * KONFIGURATOR_CHECKBOX_PARAM is the basic item of checkbox arrays. It contains
  * every information related to a checkbox.
  */
struct KONFIGURATOR_CHECKBOX_PARAM
{
  /**
    * The class used in KConfig (ex. "Archives")
    */
  QString configClass;
  /**
    * The item name used in KConfig (ex. "Do Tar")
    */
  QString configName;
  /**
    * The default value of the checkbox
    */
  bool    defaultValue;
  /**
    * The text field of the checkbox
    */
  QString text;
  /**
    * The change of this parameter requires Krusader restart
    */
  bool    restart;
  /**
    * The checkbox's tooltip
    */
  QString toolTip;
};

#endif /* __KONFIGURATOR_PAGE_H__ */