home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kcmodule.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-10-08  |  10.5 KB  |  362 lines
  1. /*
  2.    This file is part of the KDE libraries
  3.  
  4.    Copyright (c) 1999 Matthias Hoelzer-Kluepfel <hoelzer@kde.org>
  5.  
  6.    This library 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 library 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 License
  17.    along with this library; see the file COPYING.LIB.  If not, write to
  18.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  19.    Boston, MA 02110-1301, USA.
  20.  
  21. */
  22.  
  23. #ifndef KCMODULE_H
  24. #define KCMODULE_H
  25.  
  26. #include <qwidget.h>
  27.  
  28. #include <kdelibs_export.h>
  29.  
  30. class QStringList;
  31.  
  32. class KAboutData;
  33. class KConfigDialogManager;
  34. class KConfigSkeleton;
  35. class KCModulePrivate;
  36. class KInstance;
  37.  
  38. /**
  39.  * The base class for control center modules.
  40.  *
  41.  * Starting from KDE 2.0, control center modules are realized as shared
  42.  * libraries that are loaded into the control center at runtime.
  43.  *
  44.  * The module in principle is a simple widget displaying the
  45.  * item to be changed. The module has a very small interface.
  46.  *
  47.  * All the necessary glue logic and the GUI bells and whistles
  48.  * are provided by the control center and must not concern
  49.  * the module author.
  50.  *
  51.  * To write a config module, you have to create a library
  52.  * that contains at one factory function like this:
  53.  *
  54.  * \code
  55.  * #include <kgenericfactory.h>
  56.  *
  57.  * typedef KGenericFactory<YourKCModule, QWidget> YourKCModuleFactory;
  58.  * K_EXPORT_COMPONENT_FACTORY( yourLibName, YourKCModuleFactory("name_of_the_po_file") );
  59.  * \endcode
  60.  *
  61.  * The parameter "name_of_the_po_file" has to correspond with the messages target
  62.  * that you created in your Makefile.am.
  63.  *
  64.  * See http://developer.kde.org/documentation/other/kcm_howto.html
  65.  * for more detailed documentation.
  66.  *
  67.  * @author Matthias Hoelzer-Kluepfel <hoelzer@kde.org>
  68.  */
  69. class KDEUI_EXPORT KCModule : public QWidget
  70. {
  71.   Q_OBJECT
  72.  
  73. public:
  74.  
  75.   /**
  76.    * An enumeration type for the buttons used by this module.
  77.    * You should only use Help, Default and Apply. The rest is obsolete.
  78.    *
  79.    * @see KCModule::buttons @see KCModule::setButtons
  80.    */
  81.   enum Button {Help=1, Default=2, Apply=16,
  82.                Reset=4, /* obsolete, do not use! */
  83.                Cancel=8, /* obsolete, do not use! */
  84.                Ok=32, /* obsolete, do not use! */
  85.              SysDefault=64 /* obsolete, do not use! */ };
  86.  
  87.   /*
  88.    * Base class for all KControlModules.
  89.    * Make sure you have a QStringList argument in your
  90.    * implementation.
  91.    */
  92.   KCModule(QWidget *parent=0, const char *name=0, const QStringList &args=QStringList() );
  93.  
  94.   KCModule(KInstance *instance, QWidget *parent=0, const QStringList &args=QStringList() );
  95.  
  96.   /*
  97.    * Destroys the module.
  98.    */
  99.   ~KCModule();
  100.  
  101.   /**
  102.    * Load the configuration data into the module.
  103.    *
  104.    * The load method sets the user interface elements of the
  105.    * module to reflect the current settings stored in the
  106.    * configuration files.
  107.    *
  108.    * This method is invoked whenever the module should read its configuration
  109.    * (most of the times from a config file) and update the user interface.
  110.    * This happens when the user clicks the "Reset" button in the control
  111.    * center, to undo all of his changes and restore the currently valid
  112.    * settings. 
  113.    *
  114.    * If you use KConfigXT, loading is taken care of automatically and 
  115.    * you do not need to do it manually. However, if you for some reason reimplement it and
  116.    * also are using KConfigXT, you must call this function otherwise the loading of KConfigXT 
  117.    * options will not work.
  118.    *
  119.    */
  120.   virtual void load();
  121.   // ### KDE 4: Call load() automatically through a single-shot timer
  122.   //            from the constructor // and change documentation
  123.  
  124.   /**
  125.    * Save the configuration data.
  126.    *
  127.    * The save method stores the config information as shown
  128.    * in the user interface in the config files.
  129.    *
  130.    * If necessary, this method also updates the running system,
  131.    * e.g. by restarting applications. This normally does not apply for
  132.    * KSettings::Dialog modules where the updating is taken care of by
  133.    * KSettings::Dispatcher.
  134.    *
  135.    * save is called when the user clicks "Apply" or "Ok".
  136.    *
  137.    * If you use KConfigXT, saving is taken care off automatically and 
  138.    * you do not need to load manually. However, if you for some reason reimplement it and
  139.    * also are using KConfigXT, you must call this function, otherwise the saving of KConfigXT 
  140.    * options will not work. Call it at the very end of your reimplementation, to avoid
  141.    * changed() signals getting emitted when you modify widgets.
  142.    */
  143.   virtual void save();
  144.  
  145.   /**
  146.    * Sets the configuration to sensible default values.
  147.    *
  148.    * This method is called when the user clicks the "Default"
  149.    * button. It should set the display to useful values.
  150.    *
  151.    * If you use KConfigXT, you do not have to reimplement this function since
  152.    * the fetching and settings of default values is done automatically. However, if you 
  153.    * reimplement and also are using KConfigXT, remember to call the base function at the 
  154.    * very end of your reimplementation.
  155.    */
  156.   virtual void defaults();
  157.  
  158.   /**
  159.    * Set the configuration to system default values.
  160.    *
  161.    * This method is called when the user clicks the "System-Default"
  162.    * button. It should set the display to the system default values.
  163.    *
  164.    * @note The default behavior is to call defaults().
  165.    */
  166.   virtual void sysdefaults() { defaults(); }
  167.   // KDE 4 deprecate
  168.  
  169.   /**
  170.    * Return a quick-help text.
  171.    *
  172.    * This method is called when the module is docked.
  173.    * The quick-help text should contain a short description of the module and
  174.    * links to the module's help files. You can use QML formatting tags in the text.
  175.    *
  176.    * @note make sure the quick help text gets translated (use i18n()).
  177.    */
  178.   virtual QString quickHelp() const;
  179.  
  180.   /**
  181.    * This is generally only called for the KBugReport.
  182.    * If you override you should  have it return a pointer to a constant.
  183.    *
  184.    *
  185.    * @returns the KAboutData for this module
  186.    */
  187.   virtual const KAboutData *aboutData() const;
  188.   
  189.   /**
  190.    * This sets the KAboutData returned by aboutData()
  191.    * @since 3.3
  192.    */
  193.    void setAboutData( KAboutData* about );
  194.  
  195.   /**
  196.    * Indicate which buttons will be used.
  197.    *
  198.    * The return value is a value or'ed together from
  199.    * the Button enumeration type.
  200.    *
  201.    * @see KCModule::setButtons
  202.    */
  203.   int buttons() const { return _btn; }
  204.  
  205.   /**
  206.    * Get the RootOnly message for this module.
  207.    *
  208.    * When the module must be run as root, or acts differently
  209.    * for root and a normal user, it is sometimes useful to
  210.    * customize the message that appears at the top of the module
  211.    * when used as a normal user. This function returns this
  212.    * customized message. If none has been set, a default message
  213.    * will be used.
  214.    *
  215.    * @see KCModule::setRootOnlyMsg
  216.    */
  217.   QString rootOnlyMsg() const;
  218.  
  219.   /**
  220.    * Tell if KControl should show a RootOnly message when run as
  221.    * a normal user.
  222.    *
  223.    * In some cases, the module don't want a RootOnly message to
  224.    * appear (for example if it has already one). This function
  225.    * tells KControl if a RootOnly message should be shown
  226.    *
  227.    * @see KCModule::setUseRootOnlyMsg
  228.    */
  229.   bool useRootOnlyMsg() const;
  230.  
  231.   KInstance *instance() const;
  232.  
  233.   /**
  234.    * @return a list of @ref KConfigDialogManager's in use, if any.
  235.    * @since 3.4
  236.    */
  237.   const QPtrList<KConfigDialogManager>& configs() const;
  238.  
  239. protected:
  240.   /**
  241.    * Adds a KConfigskeleton @p config to watch the widget @p widget
  242.    *
  243.    * This function is useful if you need to handle multiple configuration files.
  244.    *
  245.    * @since 3.3
  246.    * @return a pointer to the KConfigDialogManager in use
  247.    * @param config the KConfigSkeleton to use
  248.    * @param widget the widget to watch
  249.    */
  250.   KConfigDialogManager* addConfig( KConfigSkeleton *config, QWidget* widget );
  251.  
  252.   /**
  253.    * Sets the quick help.
  254.    *
  255.    * @since 3.3
  256.    */
  257.   void setQuickHelp( const QString& help );
  258.  
  259. signals:
  260.  
  261.   /**
  262.    * Indicate that the state of the modules contents has changed.
  263.    *
  264.    * This signal is emitted whenever the state of the configuration
  265.    * shown in the module changes. It allows the control center to
  266.    * keep track of unsaved changes.
  267.    */
  268.   void changed(bool state);
  269.  
  270.   /**
  271.    * Indicate that the module's quickhelp has changed.
  272.    *
  273.    * Emit this signal whenever the module's quickhelp changes.
  274.    * Modules implemented as tabbed dialogs might want to implement
  275.    * per-tab quickhelp for example.
  276.    *
  277.    */
  278.   void quickHelpChanged();
  279.  
  280. protected slots:
  281.  
  282.   /**
  283.    * Calling this slot is equivalent to emitting changed(true).
  284.    * @since 3.3
  285.    */
  286.   void changed();
  287.  
  288.   /**
  289.    * A managed widget was changed, the widget settings and the current
  290.    * settings are compared and a corresponding changed() signal is emitted
  291.    * @since 3.4
  292.    */
  293.    void widgetChanged();
  294.  
  295. protected:
  296.  
  297.   /**
  298.    * Sets the buttons to display.
  299.    *
  300.    * Help: shows a "Help" button.
  301.    * Default: shows a "Use Defaults" button
  302.    * Apply: in kcontrol this will show an "Apply" and "Reset" button
  303.    *        in kcmshell this will show an "Ok", "Apply" and "Cancel" button
  304.    *
  305.    * If Apply is not specified, kcmshell will show a "Close" button.
  306.    *
  307.    * @see KCModule::buttons
  308.    */
  309.   void setButtons(int btn) { _btn = btn; }
  310.  
  311.   /**
  312.    * Sets the RootOnly message.
  313.    *
  314.    * This message will be shown at the top of the module of the
  315.    * corresponding desktop file contains the line X-KDE-RootOnly=true.
  316.    * If no message is set, a default one will be used.
  317.    *
  318.    * @see KCModule::rootOnlyMsg
  319.    */
  320.   void setRootOnlyMsg(const QString& msg);
  321.  
  322.   /**
  323.    * Change whether or not the RootOnly message should be shown.
  324.    *
  325.    * Following the value of @p on, the RootOnly message will be
  326.    * shown or not.
  327.    *
  328.    * @see KCModule::useRootOnlyMsg
  329.    */
  330.   void setUseRootOnlyMsg(bool on);
  331.  
  332.   /**
  333.    * Returns the changed state of automatically managed widgets in this dialog
  334.    * @since 3.5
  335.    */
  336.   bool managedWidgetChangeState() const;
  337.  
  338.   /**
  339.    * Call this method when your manually managed widgets change state between
  340.    * changed and not changed
  341.    * @since 3.5
  342.    */
  343.   void unmanagedWidgetChangeState(bool);
  344.  
  345. private:
  346.  
  347.   int _btn;
  348. protected:
  349.   virtual void virtual_hook( int id, void* data );
  350. private:
  351.   KCModulePrivate *d;
  352.  
  353.   /**
  354.    * Internal function for initialization of the class.
  355.    */
  356.   void init();
  357.  
  358. };
  359.  
  360. #endif //KCMODULE_H
  361.  
  362.