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 / kcmoduleloader.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-05-22  |  7.1 KB  |  221 lines
  1. /*
  2.   Copyright (c) 1999 Matthias Hoelzer-Kluepfel <hoelzer@kde.org>
  3.   Copyright (c) 2002-2003 Daniel Molkentin <molkentin@kde.org>
  4.   
  5.   This file is part of the KDE project
  6.   
  7.   This library is free software; you can redistribute it and/or
  8.   modify it under the terms of the GNU Library General Public
  9.   License version 2, as published by the Free Software Foundation.
  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. #ifndef MODLOADER_H
  22. #define MODLOADER_H
  23.  
  24. #include <kcmodule.h>
  25. #include <kcmoduleinfo.h>
  26.  
  27. class QWidget;
  28. class KLibLoader;
  29.  
  30. /**
  31.  * @ingroup kcmodule
  32.  * @brief Loads a KControl Module.
  33.  *
  34.  * KCModuleLoader tries in several ways 
  35.  * to locate and load a KCModule. If loading fails a 
  36.  * zero pointer is returned. \n
  37.  * It is very unlikely KCModuleLoader is what you want 
  38.  * and @ref KCModuleProxy suits your needs.
  39.  * 
  40.  * @author Matthias Hoelzer-Kluepfel <mhk@kde.org>
  41.  * @author Frans Englich <frans.englich@telia.com>
  42.  * @since 3.2
  43.  * @internal
  44. **/
  45. class KUTILS_EXPORT KCModuleLoader
  46. {
  47.   public:
  48.  
  49.     /**
  50.      * Loads a @ref KCModule. If loading fails a zero pointer is returned.
  51.      * @param module what module to load
  52.      * @param withFallback if true and loading failed a separate window
  53.      * with the module may appear and a zero pointer is a returned
  54.      * @param parent The parent widget
  55.      * @param name The widget's name
  56.      * @param args A list of arguments for the module to load
  57.      *
  58.      * @return a pointer to the loaded @ref KCModule
  59.      *
  60.      * @deprecated use the function which explicitly states the error reporting
  61.      * method
  62.      */
  63.     static KCModule *loadModule(const KCModuleInfo &module, bool withFallback=true, 
  64.         QWidget * parent = 0, const char * name = 0,
  65.         const QStringList & args = QStringList() ) KDE_DEPRECATED;
  66.  
  67.     /**
  68.      * Loads a @ref KCModule. If loading fails a zero pointer is returned.
  69.      * @param module what module to load
  70.      * with the module may appear and a zero pointer is a returned
  71.      * @param parent The parent widget
  72.      * @param name The widget's name
  73.      * @param args A list of arguments for the module to load
  74.      *
  75.      * @deprecated use the function which explicitly states the error reporting
  76.      * method
  77.      */
  78.     static KCModule *loadModule(const QString &module, QWidget *parent = 0,
  79.         const char *name = 0, const QStringList & args = QStringList()) KDE_DEPRECATED;
  80.  
  81.     /**
  82.      * Determines the way errors are reported
  83.      */
  84.     enum ErrorReporting {
  85.       /** 
  86.        * no error reporting is done 
  87.        * */
  88.       None = 0,
  89.       /**
  90.        * the error report is shown instead of the 
  91.        * KCModule that should have * been loaded 
  92.        */
  93.       Inline = 1,
  94.       /** 
  95.        * shows a dialog with the error report 
  96.        */
  97.       Dialog = 2,
  98.       /** 
  99.        * does both Inline and Dialog 
  100.        */
  101.       Both = 3
  102.     };
  103.  
  104.     /**
  105.      * Loads a @ref KCModule. If loading fails a zero pointer is returned.
  106.      * @param module what module to load
  107.      * @param report see ErrorReporting
  108.      * @param withFallback if true and loading failed a separate window
  109.      * with the module may appear and a zero pointer is a returned
  110.      * @param parent The parent widget
  111.      * @param name The widget's name
  112.      * @param args A list of arguments for the module to load
  113.      *
  114.      * @return a pointer to the loaded @ref KCModule
  115.      * @since 3.4
  116.      */
  117.     static KCModule *loadModule(const KCModuleInfo &module, ErrorReporting
  118.         report, bool withFallback=true, QWidget * parent = 0,
  119.         const char * name = 0, const QStringList & args = QStringList() );
  120.  
  121.     /**
  122.      * Loads a @ref KCModule. If loading fails a zero pointer is returned.
  123.      * @param module what module to load
  124.      * @param report see ErrorReporting
  125.      * with the module may appear and a zero pointer is a returned
  126.      * @param parent The parent widget
  127.      * @param name The widget's name
  128.      * @param args A list of arguments for the module to load
  129.      *
  130.      * @return a pointer to the loaded @ref KCModule
  131.      * @since 3.4
  132.      */
  133.     static KCModule *loadModule(const QString &module, ErrorReporting
  134.         report, QWidget *parent = 0, const char *name = 0,
  135.         const QStringList & args = QStringList());
  136.  
  137.     /**
  138.      * Unloads the module's library
  139.      * @param mod What module to unload for
  140.      */
  141.     static void unloadModule(const KCModuleInfo &mod);
  142.  
  143.     /**
  144.      * Display a message box explaining an error occured and possible
  145.      * reasons to why.
  146.      *
  147.      * @deprecated Use a constructor with ErrorReporting set to Dialog to show a
  148.      * message box like this function did.
  149.      */
  150.     static void showLastLoaderError(QWidget *parent) KDE_DEPRECATED;
  151.  
  152.  
  153.     /**
  154.      * Checks whether an KCModule should be shown by running its 
  155.      * test function. If it is unsure whether a module should be shown, it should 
  156.      * be made available, leaving the decision to the user.
  157.      * If false is returned, the module should not be loaded in any interface.
  158.      * 
  159.      * A module declares it needs to be tested by having "X-KDE-Test-Module=true" in 
  160.      * its desktop file. When that line exists, the following code must be available 
  161.      * in the module's library:
  162.      *
  163.      * \code
  164.      * extern "C"
  165.      * {
  166.      *    bool test_moduleName()
  167.      *    {
  168.      *      // Code testing for hardware/software presence.
  169.      *      return true; // and the modue will be loaded.
  170.      *    }
  171.      *
  172.      * }
  173.      * \endcode
  174.      *
  175.      * where moduleName is the library name for the module.
  176.      *
  177.      * @param module the module to check
  178.      * @returns true if the module should be loaded
  179.      * @since 3.4
  180.      */
  181.     static bool testModule( const QString& module );
  182.  
  183.     /**
  184.      * Convenience function, essentially the same as above.
  185.      *
  186.      * @param module the module to check
  187.      * @returns true if the module should be loaded
  188.      * @since 3.4
  189.      */
  190.     static bool testModule( const KCModuleInfo& module );
  191.  
  192.     /**
  193.      * Returns a KCModule containing the messages @p report and @p text.
  194.      *
  195.      * @param report the type of error reporting, see ErrorReporting
  196.      * @param text the main message
  197.      * @param details any additional details
  198.      * @param parent The parent widget
  199.      *
  200.      * @since 3.4
  201.      * @internal
  202.      */
  203.     static KCModule* reportError( ErrorReporting report, const QString & text,
  204.         QString details, QWidget * parent );
  205.  
  206.   private:
  207.  
  208.     /**
  209.      * Internal loader called by the public loaders.
  210.      * @internal
  211.      */
  212.     static KCModule* load(const KCModuleInfo &mod, const QString &libname, 
  213.         KLibLoader *loader, ErrorReporting report, QWidget * parent = 0,
  214.         const char * name = 0, const QStringList & args = QStringList() );
  215.  
  216. };
  217.  
  218. // vim: ts=2 sw=2 et
  219. #endif // MODLOADER_H
  220.  
  221.