Development/Tutorials/KConfig - Revision history

AnneW at 16:17, 13 July 2012

2012-07-13T16:17:39Z

Djszapi: /* Design Essentials */ Typo fix

2012-01-17T10:48:50Z

‎Design Essentials: Typo fix

Icwiener: Fix syntax highlighting.

2011-06-27T14:35:09Z

Fix syntax highlighting.

Torch: fix broken link to desktop file spec

2010-02-09T13:11:12Z

fix broken link to desktop file spec

Jörg Steffens: bugfix: entryIsImmutable -> isEntryImmutable

2009-09-04T10:04:36Z

bugfix: entryIsImmutable -> isEntryImmutable

Trueg: reverting changes which turned out to be wrong.

2009-02-19T06:21:52Z

reverting changes which turned out to be wrong.

Trueg: Undo revision 38722 by Trueg (Talk)

2009-02-19T06:18:35Z

Undo revision 38722 by Trueg (Talk)

Trueg: /* Writing Entries */

2009-02-18T18:56:59Z

‎Writing Entries

Trueg: Calling KConfigGroup::sync is mandatory.

2009-02-18T18:56:29Z

Calling KConfigGroup::sync is mandatory.

Dfaure: got the question on irc "where does it save"

2009-02-10T10:45:43Z

got the question on irc "where does it save"

← Older revision		Revision as of 16:17, 13 July 2012
Line 1:		Line 1:
−	~~{{Template:I18n/Language Navigation Bar\|Development/Tutorials/KConfig}}~~	+
	{{TutorialBrowser\|		{{TutorialBrowser\|

@@ Line 24: / Line 24: @@
 These configuration objects are broken down into a two level hierarchy: groups and keys. A configuration object can have any number of groups and each group can have one or more keys with associated values.
-Values stored may be of any number of data types. They are stored and retreived as the objects themselves. For example, a {{qt|QColor}} object is passed to a config object directly when storing a color value and when retreived a {{qt|QColor}} object is returned. Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.
+Values stored may be of any number of data types. They are stored and retrieved as the objects themselves. For example, a {{qt|QColor}} object is passed to a config object directly when storing a color value and when retrieved a {{qt|QColor}} object is returned. Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.
 == The KConfig Class ==

@@ Line 30: / Line 30: @@
 The {{class|KConfig}} object is used to access a given configuration object. There are a number of ways to create a config object:
-<code cppqt n>
+<syntaxhighlight lang="cpp-qt" line="">
 // a plain old read/write config object
 KConfig config("myapprc");
@@ Line 49: / Line 49: @@
 // outside the standard config resource
 KConfig dataResource( "data", "myapp/somefile" );
-</code>
+</syntaxhighlight>
 The KConfig object create on line 2 is a regular config object. We can read values from it, write new entries and ask for various properties of the object.  This object will be loaded from the config resource as determined by {{class|KStandardDirs}}, meaning that every instance of the <tt>myapprc</tt> object in each of the directories in the config resource hierarchy will be merged to create the values seen in this object. This is how system wide and per-user/group profiles are generated and supported and it all happens transparently to the application itself.
@@ Line 67: / Line 67: @@
 Each application has its own configuration object that uses the name provided to {{class|KAboutData}} appended with "rc" as its name. So an app named "myapp" would have the default configuration object of "myapprc" (located in $KDEHOME/share/config/). This configuration file can be retrieved in this way:
-<code cppqt n>
+<syntaxhighlight lang="cpp-qt" line="">
 #include <KComponentData>
 #include <KConfig>
@@ Line 78: / Line 78: @@
      KConfig* config = KGlobal::config();
+}
-</code>
+</syntaxhighlight>
 The default configuration object for the application is accessed when no name is specified when creating a {{class|KConfig}} object. So we could also do this instead - but it would be slower because it would have to parse the whole file again:
-<code cppqt n>
+<syntaxhighlight lang="cpp-qt" line="">
 #include <KConfig>
@@ Line 89: / Line 89: @@
      KConfig config;
+}
-</code>
+</syntaxhighlight>
 Additionally, each component may have its own configuration object. This is generally accessed via the plugin's <tt>componentData()</tt> rather than <tt>{{class|KGlobal}}::mainComponent()</tt>.
@@ Line 105: / Line 105: @@
 Listing all groups in a configuration object is as simple as calling <tt>groupList()</tt> as in this code snippet:
-<code cppqt n>
+<syntaxhighlight lang="cpp-qt">
 KSharedConfigPtr config = KGlobal::mainComponent().config();
@@ Line 111: / Line 111: @@
      kDebug() << "next group:" << group;
+}
-</code>
+</syntaxhighlight>
 == KSharedConfig ==
@@ Line 119: / Line 119: @@
 Accessing a {{class|KSharedConfig}} object is as easy as this:
-<code cppqt n>
+<syntaxhighlight lang="cpp-qt">
 KSharedConfigPtr config = KSharedConfig::openConfig("ksomefilerc");
-</code>
+</syntaxhighlight>
 <tt>openConfig()</tt> take the same parameters as {{class|KConfig}}'s constructors do, allowing one to define which configuration file to open, flags to control merging and non-<tt>config</tt> resources.
@@ Line 131: / Line 131: @@
 Now that we have a configuration object, the next step is to actually use it. The first thing we must do is to define which group of key/value pairs we wish to access in the object. We do this by creating a KConfigGroup object:
-<code cppqt n>
+<syntaxhighlight lang="cpp-qt">
 KConfig config;
 KConfigGroup generalGroup( &config, "General" );
 KConfigGroup colorsGroup = config.group( "Colors" ); // ... or a bit differently ...
-</code>
+</syntaxhighlight>
 You can pass {{class|KConfig}} or {{class|KSharedConfig}} objects to {{class|KConfigGroup}}.
@@ Line 141: / Line 141: @@
 Config groups can be nested as well:
-<code cppqt n>
+<syntaxhighlight lang="cpp-qt">
 KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
 KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
-</code>
+</syntaxhighlight>
 == Reading Entries ==
@@ Line 150: / Line 150: @@
 With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:
-<code cppqt n>
+<syntaxhighlight lang="cpp-qt">
 QString accountName = generalGroup.readEntry( "Account",
                                                QString() );
@@ Line 159: / Line 159: @@
 QString path = generalGroup.readPathEntry( "SaveTo",
                                             defaultPath );
-</code>
+</syntaxhighlight>
 As can be seen from the above, you can mix reads from different {{class|KConfigGroup}} objects created on the same {{class|KConfig}} object. The read methods take the key, which is case sensitive, as the first argument and the default value as the second argument. This argument controls what kind of data, e.g. a color in line 3 above, is to be expected as well as the type of object returned. The returned object is wrapped in a {{qt|QVariant}} to make this magic happen.
@@ Line 171: / Line 171: @@
 Setting new values is similarly straightforward:
-<code cppqt n>
+<syntaxhighlight lang="cpp-qt">
 generalGroup.writeEntry( "Account", accountName );
 generalGroup.writePathEntry( "SaveTo", savePath );
 colorGroup.writeEntry( "background", color );
 generalGroup.config()->sync();
-</code>
+</syntaxhighlight>
 Note the use of <tt>writePathEntry</tt> and how the type of object we use, such as {{qt|QColor}} on line 3, dictates how the data is serialized. Additionally, once we are done writing entries, <tt>sync()</tt> must be called on the config object for it to be saved to disk. We can also simply wait for the object to be destroyed, which triggers an automatic <tt>sync()</tt> if necessary.
@@ Line 192: / Line 192: @@
 Entries in configuration objects that are locked down using the kiosk facilities are said to be ''immutable''. An application can check for immutability of entire configuration objects, groups or keys as shown in this example:
-<code cppqt n>
+<syntaxhighlight lang="cpp-qt">
 KSharedConfigPtr config = KGlobal::config();
@@ Line 207: / Line 207: @@
      kDebug() << "URL entry in group General is immutable";
+}
-</code>
+</syntaxhighlight>
 This can be useful in particular situations where an action should be taken when an item is immutable. For instance, the KDE panels will not offer configuration options to the user or allow them to otherwise change the order of applets and icons when the panel's configuration object is marked as immutable.

@@ Line 182: / Line 182: @@
 == KDesktopFile: A Special Case ==
-When is a configuration file not a configuration file? When it is a [http://freedesktop.org/wiki/Standards_2fdesktop_2dentry_2dspec desktop file]. These files, which are essentially configuration files at their heart, are used  to describe entries for application menus, mimetypes, plugins and various services.
+When is a configuration file not a configuration file? When it is a [http://freedesktop.org/wiki/Specifications/desktop-entry-spec desktop file]. These files, which are essentially configuration files at their heart, are used  to describe entries for application menus, mimetypes, plugins and various services.
 When accessing a .desktop file, one should instead use the {{class|KDesktopFile}} class which, while a {{class|KConfig}} class offering all the capabilities described above, offers a set of methods designed to make accessing standard attributes of these files consistent and reliable.

@@ Line 204: / Line 204: @@
+}
-if ( group.entryIsImmutable("URL") ) {
+if ( group.isEntryImmutable("URL") ) {
      kDebug() << "URL entry in group General is immutable";
+}

@@ Line 176: / Line 176: @@
 colorGroup.writeEntry( "background", color );
 generalGroup.sync();
 </code>

@@ Line 65: / Line 65: @@
 === Special Configuration Objects ===
-Each application has its own configuration object that uses the name provided to {{class|KAboutData}} appended with "rc" as its name. So an app named "myapp" would have the default configuration object of "myapprc". This configuration file can be retrieved in this way:
+Each application has its own configuration object that uses the name provided to {{class|KAboutData}} appended with "rc" as its name. So an app named "myapp" would have the default configuration object of "myapprc" (located in $KDEHOME/share/config/). This configuration file can be retrieved in this way:
 <code cppqt n>