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 / kuserprofile.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-14  |  9.4 KB  |  283 lines
  1. /* This file is part of the KDE project
  2.    Copyright (C) 1998, 1999 Torben Weis <weis@kde.org>
  3.  
  4.    This library is free software; you can redistribute it and/or
  5.    modify it under the terms of the GNU Library General Public
  6.    License as published by the Free Software Foundation; either
  7.    version 2 of the License, or (at your option) any later version.
  8.  
  9.    This library is distributed in the hope that it will be useful,
  10.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12.    Library General Public License for more details.
  13.  
  14.    You should have received a copy of the GNU Library General Public License
  15.    along with this library; see the file COPYING.LIB.  If not, write to
  16.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17.    Boston, MA 02110-1301, USA.
  18. */
  19.  
  20. #ifndef __kuserprofile_h__
  21. #define __kuserprofile_h__
  22.  
  23. #include <qmap.h>
  24. #include <qstring.h>
  25. #include <qptrlist.h>
  26. #include <qvaluelist.h>
  27.  
  28. #include <kservice.h>
  29.  
  30. /**
  31.  * This class holds the user-specific preferences of a service
  32.  * (whether it can be a default offer or not, how big is the preference
  33.  * for this offer, ...). Basically it is a reference to a
  34.  * KService, a number that represents the user's preference (bigger
  35.  * is better) and a flag whether the KService can be used as default.
  36.  *
  37.  * @see KService
  38.  * @short Holds the user's preference of a service.
  39.  */
  40. class KIO_EXPORT KServiceOffer
  41. {
  42. public:
  43.   /**
  44.    * Create an invalid service offer.
  45.    */
  46.   KServiceOffer();
  47.  
  48.   /**
  49.    * Copy constructor.
  50.    * Shallow copy (the KService will not be copied).
  51.    */
  52.   KServiceOffer( const KServiceOffer& );
  53.  
  54.   /**
  55.    * Creates a new KServiceOffer.
  56.    * @param _service a pointer to the KService
  57.    * @param _pref the user's preference value, must be positive,
  58.    *              bigger is better
  59.    * @param _default true if the service should be used as
  60.    *                 default
  61.    */
  62.   KServiceOffer( KService::Ptr _service,
  63.          int _pref, bool _default );
  64.  
  65.   /**
  66.    * A service is bigger that the other when it can be default
  67.    * (and the other is not) and its preference value it higher.
  68.    */
  69.   bool operator< ( const KServiceOffer& ) const;
  70.   /**
  71.    * Is it allowed to use this service for default actions
  72.    * (e.g. Left Click in a file manager, or KRun in general).
  73.    * @return true if the service is a allowed as default
  74.    */
  75.   bool allowAsDefault() const { return m_bAllowAsDefault; }
  76.   /**
  77.    * The bigger this number is, the better is this service.
  78.    * @return the preference number (negative numbers will be
  79.    *         returned by invalid service offers)
  80.    */
  81.   int preference() const { return m_iPreference; }
  82.   /**
  83.    * The service which this offer is about.
  84.    * @return the service this offer is about, can be 0
  85.    *         in valid offers or when not set
  86.    */
  87.   KService::Ptr service() const { return m_pService; }
  88.   /**
  89.    * Check whether the entry is valid. A service is valid if
  90.    * its preference value is positive.
  91.    * @return true if the service offer is valid
  92.    */
  93.   bool isValid() const { return m_iPreference >= 0; }
  94.  
  95. private:
  96.   int m_iPreference;
  97.   bool m_bAllowAsDefault;
  98.   KService::Ptr m_pService;
  99. private:
  100.   class KServiceOfferPrivate;
  101. };
  102.  
  103. /**
  104.  * KServiceTypeProfile represents the user's preferences for services
  105.  * of a service type.
  106.  * It consists of a list of services (service offers) for the service type
  107.  * that is sorted by the user's preference.
  108.  * KTrader uses KServiceTypeProfile to sort its results, so usually
  109.  * you can just use KTrader to find the user's preferred service.
  110.  *
  111.  * @see KService
  112.  * @see KServiceType
  113.  * @see KServiceOffer
  114.  * @see KTrader
  115.  * @short Represents the user's preferences for services of a service type
  116.  */
  117. class KIO_EXPORT KServiceTypeProfile
  118. {
  119. public:
  120.   typedef QValueList<KServiceOffer> OfferList;
  121.  
  122.   ~KServiceTypeProfile();
  123.  
  124.   /**
  125.    * @deprecated Remove in KDE 4, unused.
  126.    * Returns the users preference of the given service.
  127.    * @param _service the name of the service to check
  128.    * @return the user's preference number of the given
  129.    *         @p _service, or 0 the service is unknown.
  130.    */
  131.   int preference( const QString& _service ) const;
  132.  
  133.   /**
  134.    * @deprecated Remove in KDE 4, unused.
  135.    * Checks whether the given @p _service can be used as default.
  136.    * @param _service the name of the service to check
  137.    * @return true if allowed as default
  138.    */
  139.   bool allowAsDefault( const QString& _service ) const;
  140.  
  141.   /**
  142.    * Returns the list of all service offers for the service types
  143.    * that are represented by this profile.
  144.    * @return the list of KServiceOffer instances
  145.    */
  146.   OfferList offers() const;
  147.  
  148.   /**
  149.    * Returns the preferred service for @p _serviceType and @p _genericServiceType
  150.    * ("Application", type of component, or null).
  151.    *
  152.    * @param serviceType the service type (e.g. a MIME type)
  153.    * @param genericServiceType the generic service type (e.g. "Application" or
  154.    *                           "KParts/ReadOnlyPart")
  155.    * @return the preferred service, or 0 if no service is available
  156.    */
  157.   static KService::Ptr preferredService( const QString & serviceType, const QString & genericServiceType );
  158.  
  159.   /**
  160.    * Returns the profile for the requested service type.
  161.    * @param servicetype the service type (e.g. a MIME type)
  162.    * @param genericServiceType the generic service type (e.g. "Application"
  163.    *                           or "KParts/ReadOnlyPart"). Can be QString::null,
  164.    *                           then the "Application" generic type will be used
  165.    * @return the KServiceTypeProfile with the given arguments, or 0 if not found
  166.    */
  167.   static KServiceTypeProfile* serviceTypeProfile( const QString& servicetype, const QString & genericServiceType = QString::null );
  168.  
  169.   /**
  170.    * Returns the offers associated with a given servicetype, sorted by preference.
  171.    * This is what KTrader uses to get the list of offers, before applying the
  172.    * constraints and preferences.
  173.    *
  174.    * If @p genericServiceType is specified, a list is returned with
  175.    * the offers associated with the combination of the two service types.
  176.    * This is almost like an "foo in ServiceTypes" constraint in the KTrader,
  177.    * but the difference is that to order the offers, we will look at entries
  178.    * specifically for those two service types. Typically, this is used for
  179.    * getting the list of embeddable components that can handle a given mimetype.
  180.    * In that case, @p servicetype is the mimetype and @p genericServiceType is "KParts/ReadOnlyPart".
  181.    *
  182.    * @param servicetype the service type (e.g. a MIME type)
  183.    * @param genericServiceType the generic service type (e.g. "Application"
  184.    *                           or "KParts/ReadOnlyPart"). Can be QString::null,
  185.    *                           then all generic types will be included
  186.    * @return the list of offers witht he given parameters
  187.    */
  188.   static OfferList offers( const QString& servicetype, const QString& genericServiceType = QString::null );
  189.  
  190.   /**
  191.    * Returns a list of all KServiceTypeProfiles.
  192.    * @return a list of all KServiceTypeProfiles
  193.    */
  194.   static const QPtrList<KServiceTypeProfile>& serviceTypeProfiles() { return *s_lstProfiles; }
  195.  
  196.   /**
  197.    * Clear all cached information
  198.    */
  199.   static void clear();
  200.  
  201.   /**
  202.    * This method activates a special mode of KServiceTypeProfile, in which all/all
  203.    * and all/allfiles are excluded from the results of the queries.
  204.    * It is meant for the configuration module _only_.
  205.    * @internal
  206.    */
  207.   static void setConfigurationMode() { s_configurationMode = true; }
  208.  
  209.   /**
  210.    * This method deactivates the special mode above of KServiceTypeProfile
  211.    * It is meant for the configuration module _only_.
  212.    * @internal
  213.    * @since 3.5.7
  214.    */
  215.   static void unsetConfigurationMode() { s_configurationMode = false; }
  216.  
  217.   /**
  218.    * @internal
  219.    */
  220.   static bool configurationMode() { return s_configurationMode; }
  221.  
  222. protected:
  223.   /**
  224.    * Constructor is called when the user profile is read for the
  225.    * first time.
  226.    * @param serviceType the service type (e.g. a MIME type)
  227.    * @param genericServiceType the generic service type (e.g. "Application"
  228.    *                           or "KParts/ReadOnlyPart"). Can be QString::null,
  229.    *                           then the "Application" generic type will be used
  230.    */
  231.   KServiceTypeProfile( const QString& serviceType,
  232.                        const QString& genericServiceType = QString::null );
  233.  
  234.   /**
  235.    * Add a service to this profile.
  236.    * @param _service the name of the service
  237.    * @param _preference the user's preference value, must be positive,
  238.    *              bigger is better
  239.    * @param _allow_as_default true if the service should be used as
  240.    *                 default
  241.    */
  242.   void addService( const QString& _service, int _preference = 1, bool _allow_as_default = true );
  243.  
  244. private:
  245.   /**
  246.    * Represents the users assessment of a special service
  247.    */
  248.   struct Service
  249.   {
  250.     /**
  251.      * The bigger this number is, the better is this service.
  252.      */
  253.     int m_iPreference;
  254.     /**
  255.      * Is it allowed to use this service for default actions.
  256.      */
  257.     bool m_bAllowAsDefault;
  258.   };
  259.  
  260.   /**
  261.    * Map of all services for which we have assessments.
  262.    */
  263.   QMap<QString,Service> m_mapServices;
  264.  
  265.   /**
  266.    * ServiceType of this profile.
  267.    */
  268.   QString m_strServiceType;
  269.  
  270.   /**
  271.    * Secondary ServiceType of this profile.
  272.    */
  273.   QString m_strGenericServiceType;
  274.  
  275.   static void initStatic();
  276.   static QPtrList<KServiceTypeProfile>* s_lstProfiles;
  277.   static bool s_configurationMode;
  278. private:
  279.   class KServiceTypeProfilePrivate* d;
  280. };
  281.  
  282. #endif
  283.