1/* This file is part of the KDE libraries
2 Copyright (C) 1999 Torben Weis <weis@kde.org>
3 Copyright (C) 2007 Matthias Kretz <kretz@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License version 2 as published by the Free Software Foundation.
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#ifndef KCOMPONENTDATA_H
20#define KCOMPONENTDATA_H
21
22#include <kdecore_export.h>
23#include <ksharedconfig.h>
24
25class QByteArray;
26class QString;
27class KAboutData;
28class KStandardDirs;
29class KComponentDataPrivate;
30
31/**
32 * @short Per component data.
33 *
34 * This class holds a KAboutData object or only a component name, a KStandardDirs object and a
35 * KSharedConfig object. Those objects normally are different per component but the same per
36 * instance of one component.
37 *
38 * The application component data can always be accessed using KGlobal::mainComponent() (or the
39 * convenience function KGlobal::dirs() and KGlobal::config()) while the
40 * component data of the currently active component (mainly used for KParts) can be accessed using
41 * KGlobal::activeComponent().
42 *
43 * @author Torben Weis
44 * @author Matthias Kretz <kretz@kde.org>
45 */
46class KDECORE_EXPORT KComponentData // krazy:exclude=dpointer (implicitly shared)
47{
48public:
49 /**
50 * Creates an invalid KComponentData object.
51 *
52 * @see isValid()
53 */
54 KComponentData();
55
56 /**
57 * Copy constructor.
58 *
59 * It does not copy the data. The data is shared between the old and new objects.
60 */
61 KComponentData(const KComponentData&);
62
63 /**
64 * Assignment operator.
65 *
66 * It does not copy the data. The data is shared between the old and new objects.
67 *
68 * If the data of the left hand side object was only referenced
69 * from this object and no referenced KSharedConfig object needs
70 * it anymore, it is deleted
71 */
72 KComponentData &operator=(const KComponentData&);
73
74 /**
75 * Returns whether two KComponentData objects reference the same data.
76 */
77 bool operator==(const KComponentData&) const;
78
79 /**
80 * Returns whether two KComponentData objects do not reference the same data.
81 */
82 bool operator!=(const KComponentData &rhs) const { return !operator==(rhs); }
83
84 enum MainComponentRegistration {
85 RegisterAsMainComponent,
86 SkipMainComponentRegistration
87 };
88
89 /**
90 * Constructor.
91 *
92 * @param componentName the name of the component.
93 * @param catalogName the name of the translation catalog;
94 * if left empty @p componentName is used
95 * @param registerAsMain whether to register the component as the main component
96 * of the application. This has no effect, if the application
97 * already has a main component.
98 * @see KGlobal::mainComponent
99 */
100 explicit KComponentData(const QByteArray &componentName, const QByteArray &catalogName = QByteArray(),
101 MainComponentRegistration registerAsMain = RegisterAsMainComponent);
102
103 /**
104 * Constructor.
105 *
106 * A copy of the aboutData object is made.
107 *
108 * @param aboutData data about this component
109 * @param registerAsMain whether to register the component as the main component
110 * of the application. This has no effect, if the application
111 * already has a main component.
112 * @see KGlobal::mainComponent
113 *
114 * @see KAboutData
115 */
116 explicit KComponentData(const KAboutData &aboutData, MainComponentRegistration registerAsMain = RegisterAsMainComponent);
117 explicit KComponentData(const KAboutData *aboutData, MainComponentRegistration registerAsMain = RegisterAsMainComponent);
118
119 /**
120 * Destructor.
121 */
122 virtual ~KComponentData();
123
124 /**
125 * Returns whether this is a valid object.
126 *
127 * Don't call any functions on invalid objects, that will crash. Assignment (and of course
128 * destruction) is the only valid operation you may do.
129 */
130 bool isValid() const;
131
132 /**
133 * Returns the application standard dirs object.
134 * @return The KStandardDirs of the application.
135 */
136 KStandardDirs *dirs() const;
137
138 /**
139 * Returns the general config object ("appnamerc").
140 * @return the KConfig object for the component.
141 */
142 const KSharedConfig::Ptr &config() const; //krazy:exclude=constref
143
144 /**
145 * Returns the about data of this component.
146 *
147 * @return The about data of the component. If none has been set in the
148 * constructor but a component name was set, a default constructed
149 * KAboutData object is returned.
150 */
151 const KAboutData *aboutData() const;
152
153 /**
154 * Sets the about data of this component.
155 *
156 * @since 4.5
157 */
158 void setAboutData(const KAboutData &aboutData);
159
160 /**
161 * Returns the name of the component.
162 *
163 * @return The component name.
164 */
165 QString componentName() const;
166
167 /**
168 * Returns the name of the translation catalog.
169 *
170 * @return The catalog name.
171 */
172 QString catalogName() const;
173
174protected:
175 friend class KApplicationPrivate;
176
177 /**
178 * Set name of default config file.
179 * @param name the name of the default config file
180 */
181 void setConfigName(const QString &name);
182
183 /** Standard trick to add virtuals later. @internal */
184 virtual void virtual_hook( int id, void* data );
185
186private:
187 // Ref-counted data
188 KComponentDataPrivate* d;
189 friend class KComponentDataPrivate;
190};
191
192#endif // KCOMPONENTDATA_H
193