File indexing completed on 2024-03-24 15:27:17

0001 /* This file is part of the KDE libraries
0002    Copyright (C) 1999 Torben Weis <weis@kde.org>
0003    Copyright (C) 2007 Matthias Kretz <kretz@kde.org>
0004 
0005    This library is free software; you can redistribute it and/or
0006    modify it under the terms of the GNU Library General Public
0007    License version 2 as published by the Free Software Foundation.
0008 
0009    This library is distributed in the hope that it will be useful,
0010    but WITHOUT ANY WARRANTY; without even the implied warranty of
0011    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0012    Library General Public License for more details.
0013 
0014    You should have received a copy of the GNU Library General Public License
0015    along with this library; see the file COPYING.LIB.  If not, write to
0016    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
0017    Boston, MA 02110-1301, USA.
0018 */
0019 #ifndef KCOMPONENTDATA_H
0020 #define KCOMPONENTDATA_H
0021 
0022 #include <kdelibs4support_export.h>
0023 
0024 #ifdef KDELIBS4SUPPORT_NO_DEPRECATED_NOISE
0025 #warning "This file is deprecated."
0026 #endif
0027 
0028 #include <ksharedconfig.h>
0029 #include <kaboutdata.h>
0030 
0031 class QByteArray;
0032 class QString;
0033 class K4AboutData;
0034 class KComponentDataPrivate;
0035 
0036 /**
0037  * @short Per component data.
0038  *
0039  * This class holds a K4AboutData object or only a component name, and a KSharedConfig object.
0040  * Those objects normally are different per component but the same per
0041  * instance of one component.
0042  *
0043  * The application component data can always be accessed using KComponentData::mainComponent() (or the
0044  * convenience function KGlobal::dirs() and KSharedConfig::openConfig()) while the
0045  * component data of the currently active component (mainly used for KParts) can be accessed using
0046  * KGlobal::activeComponent().
0047  *
0048  * @note This class has been deprecated, you should port code away from it;
0049  * see https://community.kde.org/Frameworks/Porting_Notes#KComponentData for porting notes.
0050  *
0051  * @author Torben Weis
0052  * @author Matthias Kretz <kretz@kde.org>
0053  */
0054 class KDELIBS4SUPPORT_DEPRECATED_EXPORT_NOISE KComponentData // krazy:exclude=dpointer (implicitly shared)
0055 {
0056 public:
0057     /**
0058      * Creates an invalid KComponentData object.
0059      *
0060      * @see isValid()
0061      */
0062     KComponentData();
0063 
0064     /**
0065      * Copy constructor.
0066      *
0067      * It does not copy the data. The data is shared between the old and new objects.
0068      */
0069     KComponentData(const KComponentData &);
0070 
0071     /**
0072      * Assignment operator.
0073      *
0074      * It does not copy the data. The data is shared between the old and new objects.
0075      *
0076      * If the data of the left hand side object was only referenced
0077      * from this object and no referenced KSharedConfig object needs
0078      * it anymore, it is deleted
0079      */
0080     KComponentData &operator=(const KComponentData &);
0081 
0082     /**
0083      * Returns whether two KComponentData objects reference the same data.
0084      */
0085     bool operator==(const KComponentData &) const;
0086 
0087     /**
0088      * Returns whether two KComponentData objects do not reference the same data.
0089      */
0090     bool operator!=(const KComponentData &rhs) const;
0091 
0092     enum MainComponentRegistration {
0093         RegisterAsMainComponent,
0094         SkipMainComponentRegistration
0095     };
0096 
0097     /**
0098      * Constructor.
0099      *
0100      * @param componentName the name of the component.
0101      * @param catalogName the name of the translation catalog;
0102      *                    if left empty @p componentName is used
0103      * @param registerAsMain whether to register the component as the main component
0104      *                       of the application. This has no effect, if the application
0105      *                       already has a main component.
0106      *                       @see KComponentData::mainComponent
0107      */
0108     KDELIBS4SUPPORT_DEPRECATED explicit KComponentData(const QByteArray &componentName, const QByteArray &catalogName = QByteArray(),
0109                             MainComponentRegistration registerAsMain = RegisterAsMainComponent);
0110 
0111     /**
0112      * Constructor.
0113      *
0114      * A copy of the aboutData object is made.
0115      *
0116      * @param aboutData data about this component
0117      * @param registerAsMain whether to register the component as the main component
0118      *                       of the application. This has no effect, if the application
0119      *                       already has a main component.
0120      *                       @see KComponentData::mainComponent
0121      *
0122      * @see K4AboutData
0123      */
0124     KDELIBS4SUPPORT_DEPRECATED explicit KComponentData(const K4AboutData &aboutData, MainComponentRegistration registerAsMain = RegisterAsMainComponent);
0125     KDELIBS4SUPPORT_DEPRECATED explicit KComponentData(const K4AboutData *aboutData, MainComponentRegistration registerAsMain = RegisterAsMainComponent);
0126 
0127     /**
0128      * Destructor.
0129      */
0130     virtual ~KComponentData();
0131 
0132     /**
0133      * Implicit conversion to KAboutData, to be able to call setComponentData(myComponentData)
0134      * even if the method is now setComponentData(const KAboutData &)
0135      */
0136     operator KAboutData() const;
0137 
0138     /**
0139      * Returns whether this is a valid object.
0140      *
0141      * Don't call any functions on invalid objects, that will crash. Assignment (and of course
0142      * destruction) is the only valid operation you may do.
0143      */
0144     bool isValid() const;
0145 
0146     /**
0147      * Returns the general config object ("appnamerc").
0148      * @return the KConfig object for the component.
0149      */
0150     const KSharedConfig::Ptr &config() const; //krazy:exclude=constref
0151 
0152     /**
0153      * Returns the about data of this component.
0154      *
0155      * @return The about data of the component. If none has been set in the
0156      *         constructor but a component name was set, a default constructed
0157      *         K4AboutData object is returned.
0158      */
0159     KDELIBS4SUPPORT_DEPRECATED const K4AboutData *aboutData() const;
0160 
0161     /**
0162      * Sets the about data of this component.
0163      *
0164      * @since 4.5
0165      */
0166     KDELIBS4SUPPORT_DEPRECATED void setAboutData(const K4AboutData &aboutData);
0167 
0168     /**
0169      * Returns the name of the component.
0170      *
0171      * @return The component name.
0172      */
0173     QString componentName() const;
0174 
0175     /**
0176      * Returns the name of the translation catalog.
0177      *
0178      * @return The catalog name.
0179      */
0180     QString catalogName() const;
0181 
0182     /**
0183      * @internal
0184      * Returns whether a main KComponentData is available.
0185      * @since 5.0
0186      */
0187     static bool hasMainComponent();
0188 
0189     /**
0190      * Returns the global component data, if one was set.
0191      * @since 5.0
0192      */
0193     static const KComponentData &mainComponent(); //krazy:exclude=constref (don't mess up ref-counting)
0194 
0195     /**
0196      * The component currently active (useful in a multi-component
0197      * application, such as a KParts application).
0198      * Don't use this - it was mainly for KAboutDialog and KBugReport.
0199      *
0200      * They now use KAboutData::applicationData() by default, or a specific KAboutData can be given
0201      * to them. KHelpMenu always creates them with the application data.
0202      * So this is now obsolete, the about-app and bug-report dialog simply use the app data
0203      * rather than the active plugin data.
0204      *
0205      * @internal
0206      * @since 5.0 (moved from KGlobal, but later on KComponentData was deprecated anyway)
0207      */
0208     static const KComponentData &activeComponent(); //krazy:exclude=constref (don't mess up ref-counting)
0209 
0210     /**
0211      * Set the active component for use by KAboutDialog and KBugReport.
0212      * To be used only by a multi-component (KParts) application.
0213      *
0214      * Since 5.0, KAboutDialog and KBugReport don't look at this anymore,
0215      * so consider just removing the call. See activeComponent() for more details.
0216      *
0217      * @see activeComponent()
0218      * @since 5.0 (moved from KGlobal, but later on KComponentData was deprecated anyway)
0219      */
0220     static void setActiveComponent(const KComponentData &d);
0221 
0222 protected:
0223     friend class KApplicationPrivate;
0224 
0225     /**
0226      * Set name of default config file.
0227      * @param name the name of the default config file
0228      */
0229     void setConfigName(const QString &name);
0230 
0231     /** Standard trick to add virtuals later. @internal */
0232     virtual void virtual_hook(int id, void *data);
0233 
0234 private:
0235     // Ref-counted data
0236     KComponentDataPrivate *d;
0237     friend class KComponentDataPrivate;
0238 };
0239 
0240 #endif // KCOMPONENTDATA_H