KDE TechBase - User contributions [en]

Projects/Plasma/SynoxiDesktopInteractionPrinciples

2009-02-23T19:16:35Z

Rememberme:

== Synoxi Desktop Interaction Principles ==

This is a preliminary Version of my Dektop Interaction Principles. These are aimed to provide a high usability and consistency. They're also supposed to reduce the stress of looking for ones files. This is archieved thruogh its non-hierarchic file visualization management. I have already made some mockups for the panel.

=== The Principles ===

1.What you see is what you get: Icons don't represent the file, they are the file

2.No hierarchic Folder Arrangement: All Views a user gets are virtual folders and represent all files who match a certain criteria (e.g. all Pictures / all Files edited last week / all Files sent to me by Peter) This includes semantic information. A user doesn't want to care about WHERE to save his files, he cares about the content. So a file save dialogue would ask for additional metadata rather than a place to save.

3.There are 3 types of objects for the user. These types will be called states further on: “Empty Objects” (create new file of a certain type) represented by an icon, “Closed Objects” (closed files) represented by a preview and “Open Objects” (open windows) represented by the window itself. A minimized Window is treated as a closed object. It is just placed in a special containment (see point 4 for visualization details of objects).

4.“Containers” are virtual views that collect various information about objects and are able to filter them in awareness of these. They are the general way of representing objects. They are aware of the state of an object (empty or new / closed / open). Containers act like a folder view that looks for data that matches filter criteria. It has to be very easy to customize them → reasonable set of filters visible (depending on which filters are already in use). To add or remove a criteria you can drag and drop from a list. This idea of filters is shared among all file views.

5.A user can interact with an object by holding the mouse or finger over the object for a certain amount of time (1-2 s) or by right clicking. Then, a menu appears. It shows contextual actions (delete / duplicate / rate / tag / send to …), semantic information (which can depend on the filters used in the container) and gathers all notifications for an object. Notifications are treated similarly as tags and can have actions associated with them, as have tags.
An object can call for attention by sending a visual and/or audible signal – it can also open parts of its menu (the notification area) by itself, if there is urgent information. By hovering this partial menu, the full menu is shown.

6.No systemtray exclusive notifications. All objects (which to the user are pieces of information with actions associated to them) are treated the same (from a visualization point of view). The information belongs to the object associated with it.
Application Notifications are stuck to the objects representation, be it an open or closed object.

7.Containers are no Window switchers. There is the window switcher applet or composite animation for that. Containers are used to look at and change the state of objects. So they can open a closed object or create an empty one. There can still be a window switcher applet.

8.You don't start an application, you start a task. If you have several applications, you can choose between them. The user doesn't care about applications, they just want it to work. The user wants to write a new text document as opposed to opening a certain application that can edit text documents.
So applications are started by clicking on a certain task which is represented by an icon. By staying on the icon for a while (1-2 seconds) an action menu is shown (see point 4)
Every action a user does is a task. Tasks can be dragged into the application launcher bar.
9.When a new notification arrives from a process, of whom there is no visible object, a new task appears in the task bar.(!English relative clause!?) It has a pop-up that shows the message. By hovering, a full context menu appears. It shows more information and allows for more actions.

10.New Tasks (application sessions) are treated the same way as closed documents or windows (open documents) are, because to the user, they basically represent empty documents or empty sessions of a chat application or an new browser page.

11.Closed Objects, Windows and new Tasks have to be distinguishable. It is important to have useful and intuitive filters.

12.An open file has to have the same contextual menu as a closed one. The problem here are notifications: In this file-centric system a notification would have to be attached to the application itself. This has to be either aggregated in a menu or attached to the bottom / top of the window. The former seems to be more viable.

13.Closing a window NEVER is a destructive task. It has nothing to do with deleting a file. A new file is saved automatically. By closing an application that has unsaved changes, the changes are saved automatically. Change History has to be preserved. Deleting a file is done by using the objects context menu.

=== Mockups ===

==== Panel ====

Here some Mockups of a possible panel:

[[Image:SinoxyMockup1.png]]

The user is hovering over the "new text document" icon. Not much to see here.

===== Notifications =====

[[Image:SinoxyMockup2.png]]

This is slightly more intresting: Here, a task is calling for attention. Two new mails have arrived and the user is being informed. Hovering the icon or the notification will cause this:

[[Image:SinoxyMockup3.png]]

Here the user is presented with options. 1) Open the Mail application 2) ignore the notification (the dialog will disappear).

This behaviour for notifications also applies for tasks who are not in the panel. All notifications for new or closed tasks appear this way.

Minimized windows can also call for attention with a dialog and an associated action menu.

===== Manage Lots of Tasks =====

A problem with this kind of application starting behaviour is how to handle big masses of applications (or in sinoxy "tasks"). In Sinoxy this problem is solved by being able to invoke an extender who displays all tasks available on the system (Partially this is also solved by grouping applications, who have the same purpose, under one "task"). To invoke this extender, you click on the KDE-icon. Herefrom you can drag tasks to the panel and also start them directly.

[[Image:SinoxyMockup4.png]]

Probably, a search mechanism would be very convenient.

=== What this would mean for plasma ===

Some of these changes can probably already be archieved by creating a new plasmoid.

But still some things would require a change in the theming system. What I showed in these mockups cannot be reproduced at the moment.

The notification system would probably require some work too. I can see that there is some work going here, probably this improves the situation.

Needed are a new minimized task manager applet and a new task starting applet (I haven't talked about that yet). Folder view needs improvement.

User:Rememberme

2009-02-23T19:01:55Z

Rememberme:

I am currently working on the Synoxy Desktop Interaction Principles.

Projects/Plasma/SynoxiDesktopInteractionPrinciples

2009-02-23T18:43:13Z

Rememberme:

== Synoxi Desktop Interaction Principles ==

This is a preliminary Version of my Dektop Interaction Principles. These are aimed to provide a high usability and consistency. They're also supposed to reduce the stress of looking for ones files. This is archieved thruogh its non-hierarchic file visualization management.

=== The Principles ===

1.What you see is what you get: Icons don't represent the file, they are the file

2.No hierarchic Folder Arrangement: All Views a user gets are virtual folders and represent all files who match a certain criteria (e.g. all Pictures / all Files edited last week / all Files sent to me by Peter) This includes semantic information. A user doesn't want to care about WHERE to save his files, he cares about the content. So a file save dialogue would ask for additional metadata rather than a place to save.

3.There are 3 types of objects for the user. These types will be called states further on: “Empty Objects” (create new file of a certain type) represented by an icon, “Closed Objects” (closed files) represented by a preview and “Open Objects” (open windows) represented by the window itself. A minimized Window is treated as a closed object. It is just placed in a special containment (see point 4 for visualization details of objects).

4.“Containers” are virtual views that collect various information about objects and are able to filter them in awareness of these. They are the general way of representing objects. They are aware of the state of an object (empty or new / closed / open). Containers act like a folder view that looks for data that matches filter criteria. It has to be very easy to customize them → reasonable set of filters visible (depending on which filters are already in use). To add or remove a criteria you can drag and drop from a list. This idea of filters is shared among all file views.

5.A user can interact with an object by holding the mouse or finger over the object for a certain amount of time (1-2 s) or by right clicking. Then, a menu appears. It shows contextual actions (delete / duplicate / rate / tag / send to …), semantic information (which can depend on the filters used in the container) and gathers all notifications for an object. Notifications are treated similarly as tags and can have actions associated with them, as have tags.
An object can call for attention by sending a visual and/or audible signal – it can also open parts of its menu (the notification area) by itself, if there is urgent information. By hovering this partial menu, the full menu is shown.

6.No systemtray exclusive notifications. All objects (which to the user are pieces of information with actions associated to them) are treated the same (from a visualization point of view). The information belongs to the object associated with it.
Application Notifications are stuck to the objects representation, be it an open or closed object.

7.Containers are no explicit Window switchers. There is the window switcher applet or composite animation for that. Containers are used to look at and change the state of objects. So they can open a closed object or create an empty one. There can still be a window switcher applet.

8.You don't start an application, you start a task. If you have several applications, you can choose between them. The user doesn't care about applications, they just want it to work. The user wants to write a new text document as opposed to opening a certain application that can edit text documents.
So applications are started by clicking on a certain task which is represented by an icon. By staying on the icon for a while (1-2 seconds) an action menu is shown (see point 4)
Every action a user does is a task. Tasks can be dragged into the application launcher bar.
9.When a new notification arrives from a process, of whom there is no visible object, a new task appears in the task bar.(!English relative clause!?) It has a pop-up that shows the message. By hovering, a full context menu appears. It shows more information and allows for more actions.

10.New Tasks (application sessions) are treated the same way as closed documents or windows (open documents) are, because to the user, they basically represent empty documents or empty sessions of a chat application or an new browser page.

11.Closed Objects, Windows and new Tasks have to be distinguishable. It is important to have useful and intuitive filters.

12.An open file has to have the same contextual menu as a closed one. The problem here are notifications: In this file-centric system a notification would have to be attached to the application itself. This has to be either aggregated in a menu or attached to the bottom / top of the window. The former seems to be more viable.

13.Closing a window NEVER is a destructive task. It has nothing to do with deleting a file. A new file is saved automatically. By closing an application that has unsaved changes, the changes are saved automatically. Change History has to be preserved. Deleting a file is done by using the objects context menu.

=== Mockups ===

==== Panel ====

Here some Mockups of a possible panel:

[[Image:SinoxyMockup1.png]]

The user is hovering over the "new text document" icon. Not much to see here.

===== Notifications =====

[[Image:SinoxyMockup2.png]]

This is slightly more intresting: Here, a task is calling for attention. Two new mails have arrived and the user is being informed. Hovering the icon or the notification will cause this:

[[Image:SinoxyMockup3.png]]

Here the user is presented with options. 1) Open the Mail application 2) ignore the notification (the dialog will disappear).

This behaviour for notifications also applies for tasks who are not in the panel. All notifications for new or closed tasks appear this way.

Minimized windows can also call for attention with a dialog and an associated action menu.

===== Manage Lots of Tasks =====

A problem with this kind of application starting behaviour is how to handle big masses of applications (or in sinoxy "tasks"). In Sinoxy this problem is solved by being able to invoke a dialog who displays all tasks available on the system (Partially this is also solved by grouping applications, who have the same purpose, under one "task"). To invoke this dialog, you click on the KDE-icon. Herefrom you can drag tasks to the panel and also start them directly.

[[Image:SinoxyMockup4.png]]

Probably, a search mechanism would be very convenient.

Projects/Plasma/SynoxiDesktopInteractionPrinciples

2009-02-23T18:31:16Z

Rememberme: /* Mockups */

== Synoxi Desktop Interaction Principles ==

This is a preliminary Version of my Dektop Interaction Principles. These are aimed to provide a high usability and consistency. They're also supposed to reduce the stress of looking for ones files. This is archieved thruogh its non-hierarchic file visualization management.

=== The Principles ===

1.What you see is what you get: Icons don't represent the file, they are the file

2.No hierarchic Folder Arrangement: All Views a user gets are virtual folders and represent all files who match a certain criteria (e.g. all Pictures / all Files edited last week / all Files sent to me by Peter) This includes semantic information. A user doesn't want to care about WHERE to save his files, he cares about the content. So a file save dialogue would ask for additional metadata rather than a place to save.

3.There are 3 types of objects for the user. These types will be called states further on: “Empty Objects” (create new file of a certain type) represented by an icon, “Closed Objects” (closed files) represented by a preview and “Open Objects” (open windows) represented by the window itself. A minimized Window is treated as a closed object. It is just placed in a special containment (see point 4 for visualization details of objects).

4.“Containers” are virtual views that collect various information about objects and are able to filter them in awareness of these. They are the general way of representing objects. They are aware of the state of an object (empty or new / closed / open). Containers act like a folder view that looks for data that matches filter criteria. It has to be very easy to customize them → reasonable set of filters visible (depending on which filters are already in use). To add or remove a criteria you can drag and drop from a list. This idea of filters is shared among all file views.

5.A user can interact with an object by holding the mouse or finger over the object for a certain amount of time (1-2 s) or by right clicking. Then, a menu appears. It shows contextual actions (delete / duplicate / rate / tag / send to …), semantic information (which can depend on the filters used in the container) and gathers all notifications for an object. Notifications are treated similarly as tags and canhave actions associated with them, as have tags.
An object can call for attention by sending a visual and/or audible signal – it can also open parts of its menu (the notification area) by itself, if there is urgent information. By hovering this partial menu, the full menu is shown.

6.No systemtray exclusive notifications. All objects (which to the user are pieces of information with actions associated to them) are treated the same (from a visualization point of view). The information belongs to the object associated with it.
Application Notifications are stuck to the objects representation, be it an open or closed object.

7.Containers are no explicit Window switchers. There is the window switcher applet or composite animation for that. Containers are used to look at and change the state of objects. So they can open a closed object or create an empty one. There can still be a window switcher applet.

8.You don't start an application, you start a task. If you have several applications, you can choose between them. The user doesn't care about applications, they just want it to work. The user wants to write a new text document as opposed to opening a certain application that can edit text documents.
So applications are started by clicking on a certain task which is represented by an icon. By staying on the icon for a while (1-2 seconds) an action menu is shown (see point 4)
Every action a user does is a task. Tasks can be dragged into the application launcher bar.
9.When a new notification arrives from a process, of whom there is no visible object, a new task appears in the task bar.(!English relative clause!?) It has a pop-up that shows the message. By hovering, a full context menu appears. It shows more information and allows for more actions.

10.New Tasks (application sessions) are treated the same way as closed documents or windows (open documents) are, because to the user, they basically represent empty documents or empty sessions of a chat application or an new browser page.

11.Closed Objects, Windows and new Tasks have to be distinguishable. It is important to have useful and intuitive filters.

12.An open file has to have the same contextual menu as a closed one. The problem here are notifications: In this file-centric system a notification would have to be attached to the application itself. This has to be either aggregated in a menu or attached to the bottom / top of the window. The former seems to be more viable.

13.Closing a window NEVER is a destructive task. It has nothing to do with deleting a file. A new file is saved automatically. By closing an application that has unsaved changes, the changes are saved automatically. Change History has to be preserved. Deleting a file is done by using the objects context menu.

=== Mockups ===

==== Panel ====

Here some Mockups of a possible panel:

[[Image:SinoxyMockup1.png]]

The user is hovering over the "new text document" icon. Not much to see here.

===== Notifications =====

[[Image:SinoxyMockup2.png]]

This is slightly more intresting: Here, a task is calling for attention. Two new mails have arrived and the user is being informed. Hovering the icon or the notification will cause this:

[[Image:SinoxyMockup3.png]]

Here the user is presented with options. 1) Open the Mail application 2) ignore the notification (the dialog will disappear).

This behaviour for notifications also applies for tasks who are not in the panel. All notifications for new or closed tasks appear this way.

Minimized windows can also call for attention with a dialog and an associated action menu.

===== Manage Lots of Tasks =====

A problem with this kind of application starting behaviour is how to handle big masses of applications (or in sinoxy "tasks"). In Sinoxy this problem is solved by being able to invoke a dialog who displays all tasks available on the system (Partially this is also solved by grouping applications, who have the same purpose, under one "task"). To invoke this dialog, you click on the KDE-icon. Herefrom you can drag tasks to the panel and also start them directly.

[[Image:SinoxyMockup4.png]]

Probably, a search mechanism would be very convenient.

Projects/Plasma/SynoxiDesktopInteractionPrinciples

2009-02-23T18:22:38Z

Rememberme:

== Synoxi Desktop Interaction Principles ==

This is a preliminary Version of my Dektop Interaction Principles. These are aimed to provide a high usability and consistency. They're also supposed to reduce the stress of looking for ones files. This is archieved thruogh its non-hierarchic file visualization management.

=== The Principles ===

1.What you see is what you get: Icons don't represent the file, they are the file

2.No hierarchic Folder Arrangement: All Views a user gets are virtual folders and represent all files who match a certain criteria (e.g. all Pictures / all Files edited last week / all Files sent to me by Peter) This includes semantic information. A user doesn't want to care about WHERE to save his files, he cares about the content. So a file save dialogue would ask for additional metadata rather than a place to save.

3.There are 3 types of objects for the user. These types will be called states further on: “Empty Objects” (create new file of a certain type) represented by an icon, “Closed Objects” (closed files) represented by a preview and “Open Objects” (open windows) represented by the window itself. A minimized Window is treated as a closed object. It is just placed in a special containment (see point 4 for visualization details of objects).

4.“Containers” are virtual views that collect various information about objects and are able to filter them in awareness of these. They are the general way of representing objects. They are aware of the state of an object (empty or new / closed / open). Containers act like a folder view that looks for data that matches filter criteria. It has to be very easy to customize them → reasonable set of filters visible (depending on which filters are already in use). To add or remove a criteria you can drag and drop from a list. This idea of filters is shared among all file views.

5.A user can interact with an object by holding the mouse or finger over the object for a certain amount of time (1-2 s) or by right clicking. Then, a menu appears. It shows contextual actions (delete / duplicate / rate / tag / send to …), semantic information (which can depend on the filters used in the container) and gathers all notifications for an object. Notifications are treated similarly as tags and canhave actions associated with them, as have tags.
An object can call for attention by sending a visual and/or audible signal – it can also open parts of its menu (the notification area) by itself, if there is urgent information. By hovering this partial menu, the full menu is shown.

6.No systemtray exclusive notifications. All objects (which to the user are pieces of information with actions associated to them) are treated the same (from a visualization point of view). The information belongs to the object associated with it.
Application Notifications are stuck to the objects representation, be it an open or closed object.

7.Containers are no explicit Window switchers. There is the window switcher applet or composite animation for that. Containers are used to look at and change the state of objects. So they can open a closed object or create an empty one. There can still be a window switcher applet.

8.You don't start an application, you start a task. If you have several applications, you can choose between them. The user doesn't care about applications, they just want it to work. The user wants to write a new text document as opposed to opening a certain application that can edit text documents.
So applications are started by clicking on a certain task which is represented by an icon. By staying on the icon for a while (1-2 seconds) an action menu is shown (see point 4)
Every action a user does is a task. Tasks can be dragged into the application launcher bar.
9.When a new notification arrives from a process, of whom there is no visible object, a new task appears in the task bar.(!English relative clause!?) It has a pop-up that shows the message. By hovering, a full context menu appears. It shows more information and allows for more actions.

10.New Tasks (application sessions) are treated the same way as closed documents or windows (open documents) are, because to the user, they basically represent empty documents or empty sessions of a chat application or an new browser page.

11.Closed Objects, Windows and new Tasks have to be distinguishable. It is important to have useful and intuitive filters.

12.An open file has to have the same contextual menu as a closed one. The problem here are notifications: In this file-centric system a notification would have to be attached to the application itself. This has to be either aggregated in a menu or attached to the bottom / top of the window. The former seems to be more viable.

13.Closing a window NEVER is a destructive task. It has nothing to do with deleting a file. A new file is saved automatically. By closing an application that has unsaved changes, the changes are saved automatically. Change History has to be preserved. Deleting a file is done by using the objects context menu.

=== Mockups ===

Here some Mockups of a possible panel:

[[Image:SinoxyMockup1.png]]

The user is hovering over the "new text document" icon. Not much to see here.

[[Image:SinoxyMockup2.png]]

This is slightly more intresting: Here a task is calling for attention. Two new mails have arrived and the user is being informed. Hovering the icon or the notification will cause this:

[[Image:SinoxyMockup3.png]]

Here the user is presented with options. 1) Open the Mail application 2) ignore the notification (the dialog will disappear).

This behaviour for notifications also applies for tasks who are not in the panel. All notifications for new or closed tasks appear this way.

Minimized windows can also call for attention with a dialog and an associated action menu.

A problem with this kind of application starting behaviour is how to handle big masses of applications (or in sinoxy "tasks"). In Sinoxy this problem is solved by being able to invoke a dialog who displays all tasks available on the system (Partially this is also solved by grouping applications, who have the same purpose, under one "task"). To invoke this dialog, you click on the KDE-icon. Herefrom you can drag tasks to the panel and also start them directly.

[[Image:SinoxyMockup4.png]]

Probably, a search mechanism would be very convenient.

Projects/Plasma/SynoxiDesktopInteractionPrinciples

2009-02-23T17:47:49Z

Rememberme:

Synoxi Desktop Interaction Principles:

This is a preliminary Version of my Dektop Interaction Principles. These are aimed to provide a high usability and consistency. They're also supposed to reduce the stress of looking for ones files. This is archieved thruogh its non-hierarchic file visualization management.

1.What you see is what you get: Icons don't represent the file, they are the file

2.No hierarchic Folder Arrangement: All Views a user gets are virtual folders and represent all files who match a certain criteria (e.g. all Pictures / all Files edited last week / all Files sent to me by Peter) This includes semantic information. A user doesn't want to care about WHERE to save his files, he cares about the content. So a file save dialogue would ask for additional metadata rather than a place to save.

3.There are 3 types of objects for the user. These types will be called states further on: “Empty Objects” (create new file of a certain type) represented by an icon, “Closed Objects” (closed files) represented by a preview and “Open Objects” (open windows) represented by the window itself. A minimized Window is treated as a closed object. It is just placed in a special containment (see point 4 for visualization details of objects).

4.“Containers” are virtual views that collect various information about objects and are able to filter them in awareness of these. They are the general way of representing objects. They are aware of the state of an object (empty or new / closed / open). Containers act like a folder view that looks for data that matches filter criteria. It has to be very easy to customize them → reasonable set of filters visible (depending on which filters are already in use). To add or remove a criteria you can drag and drop from a list. This idea of filters is shared among all file views.

5.A user can interact with an object by holding the mouse or finger over the object for a certain amount of time (1-2 s) or by right clicking. Then, a menu appears. It shows contextual actions (delete / duplicate / rate / tag / send to …), semantic information (which can depend on the filters used in the container) and gathers all notifications for an object. Notifications are treated similarly as tags and canhave actions associated with them, as have tags.
An object can call for attention by sending a visual and/or audible signal – it can also open parts of its menu (the notification area) by itself, if there is urgent information. By hovering this partial menu, the full menu is shown.

6.No systemtray exclusive notifications. All objects (which to the user are pieces of information with actions associated to them) are treated the same (from a visualization point of view). The information belongs to the object associated with it.
Application Notifications are stuck to the objects representation, be it an open or closed object.

7.Containers are no explicit Window switchers. There is the window switcher applet or composite animation for that. Containers are used to look at and change the state of objects. So they can open a closed object or create an empty one. There can still be a window switcher applet.

8.You don't start an application, you start a task. If you have several applications, you can choose between them. The user doesn't care about applications, they just want it to work. The user wants to write a new text document as opposed to opening a certain application that can edit text documents.
So applications are started by clicking on a certain task which is represented by an icon. By staying on the icon for a while (1-2 seconds) an action menu is shown (see point 4)
Every action a user does is a task. Tasks can be dragged into the application launcher bar.
9.When a new notification arrives from a process, of whom there is no visible object, a new task appears in the task bar.(!English relative clause!?) It has a pop-up that shows the message. By hovering, a full context menu appears. It shows more information and allows for more actions.

10.New Tasks (application sessions) are treated the same way as closed documents or windows (open documents) are, because to the user, they basically represent empty documents or empty sessions of a chat application or an new browser page.

11.Closed Objects, Windows and new Tasks have to be distinguishable. It is important to have useful and intuitive filters.

12.An open file has to have the same contextual menu as a closed one. The problem here are notifications: In this file-centric system a notification would have to be attached to the application itself. This has to be either aggregated in a menu or attached to the bottom / top of the window. The former seems to be more viable.

13.Closing a window NEVER is a destructive task. It has nothing to do with deleting a file. A new file is saved automatically. By closing an application that has unsaved changes, the changes are saved automatically. Change History has to be preserved. Deleting a file is done by using the objects context menu.

Here some Mockups of a possible panel:

[[Image:SinoxyMockup1.png]]

The user is hovering over the "new text document" icon. Not much to see here.

[[Image:SinoxyMockup2.png]]

This is slightly more intresting: Here a task is calling for attention. Two new mails have arrived and the user is being informed. Hovering the icon or the notification will cause this:

[[Image:SinoxyMockup3.png]]

Here the user is presented with options. 1) Open the Mail application 2) ignore the notification (the dialog will disappear).

This behaviour for notifications also applies for tasks who are not in the panel. All notifications for new or closed tasks appear this way.

Minimized windows can also call for attention with a dialog and an associated action menu.

A problem with this kind of application starting behaviour is how to handle big masses of applications (or in sinoxy "tasks"). In Sinoxy this problem is solved by being able to invoke a dialog who displays all tasks available on the system (Partially this is also solved by grouping applications, who have the same purpose, under one "task"). To invoke this dialog, you click on the KDE-icon. Herefrom you can drag tasks to the panel and also start them directly.

[[Image:SinoxyMockup4.png]]

Probably, a search mechanism would be very convenient.

File:SinoxyMockup4.png

2009-02-23T17:36:58Z

Rememberme: mockup for sinoxy desktop

mockup for sinoxy desktop

Projects/Plasma/SynoxiDesktopInteractionPrinciples

2009-02-23T17:36:12Z

Rememberme:

Synoxi Desktop Interaction Principles:

This is a preliminary Version of my Dektop Interaction Principles. These are aimed to provide a high usability and consistency. They're also supposed to reduce the stress of looking for ones files. This is archieved thruogh its non-hierarchic file visualization management.
I admit it might seem a bite vague now; I will provide some mockups and application examples.

1.What you see is what you get: Icons don't represent the file, they are the file

2.No hierarchic Folder Arrangement: All Views a user gets are virtual folders and represent all files who match a certain criteria (e.g. all Pictures / all Files edited last week / all Files sent to me by Peter) This includes semantic information. A user doesn't want to care about WHERE to save his files, he cares about the content. So a file save dialogue would ask for additional metadata rather than a place to save.

3.There are 3 types of objects for the user. These types will be called states further on: “Empty Objects” (create new file of a certain type) represented by an icon, “Closed Objects” (closed files) represented by a preview and “Open Objects” (open windows) represented by the window itself. A minimized Window is treated as a closed object. It is just placed in a special containment (see point 4 for visualization details of objects).

4.“Containers” are virtual views that collect various information about objects and are able to filter them in awareness of these. They are the general way of representing objects. They are aware of the state of an object (empty or new / closed / open). Containers act like a folder view that looks for data that matches filter criteria. It has to be very easy to customize them → reasonable set of filters visible (depending on which filters are already in use). To add or remove a criteria you can drag and drop from a list. This idea of filters is shared among all file views.

5.A user can interact with an object by holding the mouse or finger over the object for a certain amount of time (1-2 s) or by right clicking. Then, a menu appears. It shows contextual actions (delete / duplicate / rate / tag / send to …), semantic information (which can depend on the filters used in the container) and gathers all notifications for an object. Notifications are treated similarly as tags and canhave actions associated with them, as have tags.
An object can call for attention by sending a visual and/or audible signal – it can also open parts of its menu (the notification area) by itself, if there is urgent information. By hovering this partial menu, the full menu is shown.

6.No systemtray exclusive notifications. All objects (which to the user are pieces of information with actions associated to them) are treated the same (from a visualization point of view). The information belongs to the object associated with it.
Application Notifications are stuck to the objects representation, be it an open or closed object.

7.Containers are no explicit Window switchers. There is the window switcher applet or composite animation for that. Containers are used to look at and change the state of objects. So they can open a closed object or create an empty one. There can still be a window switcher applet.

8.You don't start an application, you start a task. If you have several applications, you can choose between them. The user doesn't care about applications, they just want it to work. The user wants to write a new text document as opposed to opening a certain application that can edit text documents.
So applications are started by clicking on a certain task which is represented by an icon. By staying on the icon for a while (1-2 seconds) an action menu is shown (see point 4)
Every action a user does is a task. Tasks can be dragged into the application launcher bar.
9.When a new notification arrives from a process, of whom there is no visible object, a new task appears in the task bar.(!English relative clause!?) It has a pop-up that shows the message. By hovering, a full context menu appears. It shows more information and allows for more actions.

10.New Tasks (application sessions) are treated the same way as closed documents or windows (open documents) are, because to the user, they basically represent empty documents or empty sessions of a chat application or an new browser page.

11.Closed Objects, Windows and new Tasks have to be distinguishable. It is important to have useful and intuitive filters.

12.An open file has to have the same contextual menu as a closed one. The problem here are notifications: In this file-centric system a notification would have to be attached to the application itself. This has to be either aggregated in a menu or attached to the bottom / top of the window. The former seems to be more viable.

13.Closing a window NEVER is a destructive task. It has nothing to do with deleting a file. A new file is saved automatically. By closing an application that has unsaved changes, the changes are saved automatically. Change History has to be preserved. Deleting a file is done by using the objects context menu.

Here some Mockups of a possible panel:

[[Image:SinoxyMockup1.png]]

The user is hovering over the "new text document" icon. Not much to see here.

[[Image:SinoxyMockup2.png]]

This is slightly more intresting: Here a task is calling for attention. Two new mails have arrived and the user is being informed. Hovering the icon or the notification will cause this:

[[Image:SinoxyMockup3.png]]

Here the user is presented with options. 1) Open the Mail application 2) ignore the notification (the dialog will disappear).

This behaviour for notifications also applies for tasks who are not in the panel. All notifications for new or closed tasks appear this way.

Minimized windows can also call for attention with a dialog and an associated action menu.

File:SinoxyMockup3.png

2009-02-23T17:31:09Z

Rememberme: mockup for sinoxy desktop

mockup for sinoxy desktop

File:SinoxyMockup2.png

2009-02-23T17:28:46Z

Rememberme: mockup for sinoxy desktop

mockup for sinoxy desktop

File:SinoxyMockup1.png

2009-02-23T17:26:47Z

Rememberme:

Projects/Plasma/SynoxiDesktopInteractionPrinciples

2009-02-23T17:25:38Z

Rememberme:

Synoxi Desktop Interaction Principles:

This is a preliminary Version of my Dektop Interaction Principles. These are aimed to provide a high usability and consistency. They're also supposed to reduce the stress of looking for ones files. This is archieved thruogh its non-hierarchic file visualization management.
I admit it might seem a bite vague now; I will provide some mockups and application examples.

1.What you see is what you get: Icons don't represent the file, they are the file

2.No hierarchic Folder Arrangement: All Views a user gets are virtual folders and represent all files who match a certain criteria (e.g. all Pictures / all Files edited last week / all Files sent to me by Peter) This includes semantic information. A user doesn't want to care about WHERE to save his files, he cares about the content. So a file save dialogue would ask for additional metadata rather than a place to save.

3.There are 3 types of objects for the user. These types will be called states further on: “Empty Objects” (create new file of a certain type) represented by an icon, “Closed Objects” (closed files) represented by a preview and “Open Objects” (open windows) represented by the window itself. A minimized Window is treated as a closed object. It is just placed in a special containment (see point 4 for visualization details of objects).

4.“Containers” are virtual views that collect various information about objects and are able to filter them in awareness of these. They are the general way of representing objects. They are aware of the state of an object (empty or new / closed / open). Containers act like a folder view that looks for data that matches filter criteria. It has to be very easy to customize them → reasonable set of filters visible (depending on which filters are already in use). To add or remove a criteria you can drag and drop from a list. This idea of filters is shared among all file views.

5.A user can interact with an object by holding the mouse or finger over the object for a certain amount of time (1-2 s) or by right clicking. Then, a menu appears. It shows contextual actions (delete / duplicate / rate / tag / send to …), semantic information (which can depend on the filters used in the container) and gathers all notifications for an object. Notifications are treated similarly as tags and canhave actions associated with them, as have tags.
An object can call for attention by sending a visual and/or audible signal – it can also open parts of its menu (the notification area) by itself, if there is urgent information. By hovering this partial menu, the full menu is shown.

6.No systemtray exclusive notifications. All objects (which to the user are pieces of information with actions associated to them) are treated the same (from a visualization point of view). The information belongs to the object associated with it.
Application Notifications are stuck to the objects representation, be it an open or closed object.

7.Containers are no explicit Window switchers. There is the window switcher applet or composite animation for that. Containers are used to look at and change the state of objects. So they can open a closed object or create an empty one. There can still be a window switcher applet.

8.You don't start an application, you start a task. If you have several applications, you can choose between them. The user doesn't care about applications, they just want it to work. The user wants to write a new text document as opposed to opening a certain application that can edit text documents.
So applications are started by clicking on a certain task which is represented by an icon. By staying on the icon for a while (1-2 seconds) an action menu is shown (see point 4)
Every action a user does is a task. Tasks can be dragged into the application launcher bar.
9.When a new notification arrives from a process, of whom there is no visible object, a new task appears in the task bar.(!English relative clause!?) It has a pop-up that shows the message. By hovering, a full context menu appears. It shows more information and allows for more actions.

10.New Tasks (application sessions) are treated the same way as closed documents or windows (open documents) are, because to the user, they basically represent empty documents or empty sessions of a chat application or an new browser page.

11.Closed Objects, Windows and new Tasks have to be distinguishable. It is important to have useful and intuitive filters.

12.An open file has to have the same contextual menu as a closed one. The problem here are notifications: In this file-centric system a notification would have to be attached to the application itself. This has to be either aggregated in a menu or attached to the bottom / top of the window. The former seems to be more viable.

13.Closing a window NEVER is a destructive task. It has nothing to do with deleting a file. A new file is saved automatically. By closing an application that has unsaved changes, the changes are saved automatically. Change History has to be preserved. Deleting a file is done by using the objects context menu.

Here some Mockups of a possible panel:

[[Image:Mockup1.png]]

The user is hovering over the "new text document" icon.

File:Mockup1.png

2009-02-23T17:20:58Z

Rememberme: Possible Standard Panel view for Sinoxy (Mockup). Create new text document is hovered.

Possible Standard Panel view for Sinoxy (Mockup).
Create new text document is hovered.

Projects/Plasma/SynoxiDesktopInteractionPrinciples

2009-02-04T21:56:27Z

Rememberme: This is a preliminary Version of my Dektop Interaction Principles

Synoxi Desktop Interaction Principles:

This is a preliminary Version of my Dektop Interaction Principles. These are aimed to provide a high usability and consistency. They're also supposed to reduce the stress of looking for ones files. This is archieved thruogh its non-hierarchic file visualization management.
I admit it might seem a bite vague now; I will provide some mockups and application examples.

1.What you see is what you get: Icons don't represent the file, they are the file

2.No hierarchic Folder Arrangement: All Views a user gets are virtual folders and represent all files who match a certain criteria (e.g. all Pictures / all Files edited last week / all Files sent to me by Peter) This includes semantic information. A user doesn't want to care about WHERE to save his files, he cares about the content. So a file save dialogue would ask for additional metadata rather than a place to save.

3.There are 3 types of objects for the user. These types will be called states further on: “Empty Objects” (create new file of a certain type) represented by an icon, “Closed Objects” (closed files) represented by a preview and “Open Objects” (open windows) represented by the window itself. A minimized Window is treated as a closed object. It is just placed in a special containment (see point 4 for visualization details of objects).

4.“Containers” are virtual views that collect various information about objects and are able to filter them in awareness of these. They are the general way of representing objects. They are aware of the state of an object (empty or new / closed / open). Containers act like a folder view that looks for data that matches filter criteria. It has to be very easy to customize them → reasonable set of filters visible (depending on which filters are already in use). To add or remove a criteria you can drag and drop from a list. This idea of filters is shared among all file views.

5.A user can interact with an object by holding the mouse or finger over the object for a certain amount of time (1-2 s) or by right clicking. Then, a menu appears. It shows contextual actions (delete / duplicate / rate / tag / send to …), semantic information (which can depend on the filters used in the container) and gathers all notifications for an object. Notifications are treated similarly as tags and canhave actions associated with them, as have tags.
An object can call for attention by sending a visual and/or audible signal – it can also open parts of its menu (the notification area) by itself, if there is urgent information. By hovering this partial menu, the full menu is shown.

6.No systemtray exclusive notifications. All objects (which to the user are pieces of information with actions associated to them) are treated the same (from a visualization point of view). The information belongs to the object associated with it.
Application Notifications are stuck to the objects representation, be it an open or closed object.

7.Containers are no explicit Window switchers. There is the window switcher applet or composite animation for that. Containers are used to look at and change the state of objects. So they can open a closed object or create an empty one. There can still be a window switcher applet.

8.You don't start an application, you start a task. If you have several applications, you can choose between them. The user doesn't care about applications, they just want it to work. The user wants to write a new text document as opposed to opening a certain application that can edit text documents.
So applications are started by clicking on a certain task which is represented by an icon. By staying on the icon for a while (1-2 seconds) an action menu is shown (see point 4)
Every action a user does is a task. Tasks can be dragged into the application launcher bar.
9.When a new notification arrives from a process, of whom there is no visible object, a new task appears in the task bar.(!English relative clause!?) It has a pop-up that shows the message. By hovering, a full context menu appears. It shows more information and allows for more actions.

10.New Tasks (application sessions) are treated the same way as closed documents or windows (open documents) are, because to the user, they basically represent empty documents or empty sessions of a chat application or an new browser page.

11.Closed Objects, Windows and new Tasks have to be distinguishable. It is important to have useful and intuitive filters.

12.An open file has to have the same contextual menu as a closed one. The problem here are notifications: In this file-centric system a notification would have to be attached to the application itself. This has to be either aggregated in a menu or attached to the bottom / top of the window. The former seems to be more viable.

13.Closing a window NEVER is a destructive task. It has nothing to do with deleting a file. A new file is saved automatically. By closing an application that has unsaved changes, the changes are saved automatically. Change History has to be preserved. Deleting a file is done by using the objects context menu.

Development/Tutorials/KConfig (de)

2008-05-26T18:35:29Z

Rememberme:

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

{{improve (de)}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer- und Gruppenprofile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

Anwendungen selbst müssen sich deshalb nicht um das Gliedern und Entgliedern von Objekten kümmern.

== Die KConfig Klasse ==

Das {{class|KConfig}}-Objekt wird benutzt um ein bestehendes Konfigurationsobjekt anzusteuern. Es gibt eine Reihe von Möglichkeiten ein Konfigurationsobjekt zu erstellen.

<code cppqt n>
// ein einfaches, altes lesen/schreiben Konfigurationsobjekt
KConfig config("myapprc");

// eine bestimmte Datei im Dateisystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// nicht mit globalen Werten verflochten
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// nicht mit globalen Werten orde der $KDEDIRS Hierarchie verflochten
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// Komponenten-spezifische Konfiguration, in diesem Fall ein Plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// Ausserhalb der normalen Konfigurations-Ressource
KConfig dataResource( "data", "myapp/somefile" );
</code>

{{note (de)|wie soll "merged" in den folgenden Fällen übersetzt werden? <br> <tt>"verschmolzen" oder "verflochten"</tt> <br> der Anwendung selber transparent" tönt auch nicht sehr gut}}

Das Kconfig Objekt, das wir auf Zeile 2 erstellen ist ein gewöhnliches Konfigurationsobjekt. Wir können Werte aus ihm lesen, neue Einträge schreiben und nach verschiedenen Eigenschaften des Objekts fragen. Dieses Objekt wird aus der Konfigurations-Ressource geladen, wie es durch {{class|KStandardDirs}} bestimmt wird, das heisst, dass jede Instanz des <tt>myapprc</tt>-Objekts in jedem der Ordner in der Konfigurations-Ressourcen-Hierarchie verschmolzen werden um die Werte zu erzeugen, die in diesem Objekt gesehen werden. So werden Systemweite und
pro-Benutzer/Gruppen Profile erstellt und unterstützt. Das alles geschieht der Anwendung selber transparent.

{{tip| Für mehr Informationen, wie das Verschmelzen funktioniert, siehe diesen Artikel über die [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Dateisystem Hierarchie]].}}

Auf Zeile 6 öffnen wir eine bestimmte Lokale Datei, in diesem Fall {{path|/etc/kderc}}. Das führt kein Verschmelzen von Werten aus und erwartet eine Datei im INI Format.

Zeile 9 erzeugt ein Konfigurationsobjekt, dass nicht mit dem globalen <tt>kdeglobals</tt>-Konfigurationsobjekt verflochten ist, während das Konfigurationsobjekt auf Zeile 12 zusätzlich mit keinem der Dateien in der <tt>$KDEDIRS</tt>-Hierarchie verflochten ist. Das kann die Leistung spürbar verbessern, falls man einfach nur Werte aus einer einfachen Konfuguration liest und globale Werte keine Rolle spielen.

Zeile 15 erzeugt ein Konfigurationsobjekt unter Benutzung des {{class|KComponentData}}-Objekts das zu einem Plugin oder einer anderen Komponente gehört. Das Plugin kann verschiedene Ordner aufweisen, die in seinen {{class|KStandardDirs}} definiert sind und das ist eine Möglichkeit sich zu versichern, dass {{class|KConfig}} das respektiert.

Und schliesslich auf Zeile 18 erzeugen wir ein Konfigurationsobjekt, das nicht in der <tt>config</tt>-Ressource sondern in der <tt>data</tt>-Ressource existiert. Man kann kann auf diese Weise jede Ressource verwenden, von denen {{class|KStandardDirs}} Kenntnis hat, auch solche die während der Laufzeit hinzugefügt werden.

=== Spezielle Konfigurationsobjekte ===

Jede Anwendung hat sein eigenes Konfigurationsobjekt das den Namen benutzt, der von {{class|KAboutData}} bereitgestellt wird mit angehängtem "rc". Also hätte eine Anwendung mit dem Namen "myapp" das Standard-Konfigurationsobjekt "myapprc". Dieses Konfigurationsobjekt kann auf diese Weise aufgerufen werden:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// beachten sie, dass dies eigentlich ein KSharedConfig ist
// mehr über diese Klasse siehe weiter unten
KConfig* config = KGlobal::config();
}
</code>

Auf das Standard-Konfigurationsobjekt für die Anwendung wird zugegriffen, wenn kein Name definiert wurde, als das {{class|KConfig}}-Objekt erzeugt wurde. Also könnten wir stattdessen auch das tun:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

Zusätzlich könnte jede Komponente sein eigenes Konfigurationsobjekt haben. Auf dieses wird normalerweise durch die <tt>componentData()</tt> des Plugins zugegriffen, anstatt durch die <tt>{{class|KGlobal}}::mainComponent()</tt>.

Und schliesslich gibt es noch ein globales Konfigurationsobjekt, <tt>kdeglobals</tt>, das von jeder Anwendung verwendet wird. Es enthält Informationen wie die Standard-Tatenkombinationen für verschiedene Aktionen. Es wird in das Konfigurationsobjekt "gemischt" wenn der <tt>KConfig::IncludeGlobals</tt> Bitschalter dem {{class|KConfig}} Konstruktor übergeben wird, was standardmässig der Fall ist.

=== Allgemein nützliche Methoden ===

Um den momentanen Zustand des Konfigurationsobjektes zu speichern, rufen wir die <tt>sync()</tt>-Methode auf. Diese Methode wird also aufgerufen, wenn ein Objekt zerstört wird. Falls keine Änderungen gemacht wurden, oder die Ressource weist sich als nicht beschreibbar aus (Wenn der Benutzer zum Beispiel nicht genug Rechte hat, um die Datei zu bearbeiten), dann wird keine Beschäftigung der Festplatte hervorgerufen. <tt>sync()</tt> verschmilzt Änderungen die gleichzeitig von anderen Prozessen ausgeführt werden - lokale Änderungen haben aber trotzdem Vorrang.

Wenn wir sicher gehen wollen, dass wir die aktuellsten Werte von der Festplatte haben, dann rufen wir <tt>reparseConfiguration()</tt> auf, welches <tt>sync()</tt> aufruft und dann die Daten von der Festplatte aktualisiert.

Falls wir verhindern müssen, dass das Konfigurationsobjekt bereits gemachte Änderungen nicht auf die Festplatte speichert, müssen wir <tt>markAsClean()</tt> aufrufen. Ein besonderer Anwendungsfall ist es, die Konfiguration zum Festplatten-Zustand zurückzusetzen indem man <tt>markAsClean()</tt> gefolgt von <tt>reparseConfiguration()</tt> aufruft.

Alle Gruppen in einem Konfigurationsobjekt aufzurufen ist so einfach wie hier in diesem Code-Abschnitt <tt>groupList()</tt> aufzurufen.

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

Die {{class|KSharedConfig}} Klasse ist eine Referenz-gezählte Version von {{class|KConfig}}. Darum stellt es eine Möglichkeit bereit, das selbe Konfigurationsobjekt von unterschiedlichen Orten zu referenzieren ohne zusätzlich die Objekte trennen zu müssen oder sich um die Synchronisation des Schreibvorgangs zu kümmern, selbst wenn das Konfigurationsobjekt von verschiedenen Code-Pfaden aktualisiert wird.

Auf ein {{class|KSharedConfig}}-Objekt zuzugreifen ist so einfach wie das hier:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<tt>openConfig()</tt> nimmt die selben Parameter wie {{class|KConfig}}'s Konstruktoren, was es einem ermöglicht zu definieren, welche Konfigurationsdatei zu öffnen und Markierungen das Verschmelzen von nicht-<tt>config</tt>-Ressourcen zu kontrollieren.

Es wird grundsätzlich empfohlen {{class|KSharedConfig}} anstatt {{class|KConfig}} selbst zu benutzen, und auch das Objekt, das von {{class|KComponentData}} zurückgegeben wird ist in der Tat ein {{class|KSharedConfig}}-Objekt.

== KConfigGroup ==

Nun da wir ein Konfigurationsobjekt haben, ist der nächste Schritt es tatsächlich zu nutzen. Das erste, das wir tun müssen, ist zu bestimmen, auf welche Gruppe von Schlüssel-/Wertepaare wir in unserem Objekt zugreifen wollen. Wir tun das, indem wir ein KConfigGroup-Objekt erstellen.

<code cppqt n>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ...oder so ähnlich...
</code>

Man kann{{class|KConfigGroup}} {{class|KConfig}}- oder {{class|KSharedConfig}}-Objekte übergeben.

Konfigurationsgruppen können ebenfalls verschachtelt werden.

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Lesen von Einträgen ==

Wenn man erst einmal ein {{class|KConfigGroup}}-Objekt erstellt hat, ist das Lesen von Einträgen ziemlich einfach:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

Wie man hier oben sehen kann, kann man Lesevorgänge von verschiedenen {{class|KConfigGroup}}-Objekten, die auf dem selben {{class|KConfig}}-Objekt erstellt wurden, problemlos mischen. Die Lese-Methoden nehmen den Schlüssel, der Gross- und Kleinschreibung unterscheidet, als erstes Argument und den Standardwert als zweites Argument. Dieses Argument bestimmt auch welche Art von Daten, also z.B. eine Farbe in Zeile 3, erwartet wird und auch die Art von Objekt, die zurückgegeben werden soll.Das zurückgegebene Objekt wird in eine {{qt|QVariant}} gepackt um diese Hexerei zu ermöglichen.

Es gibt eine Anzahl von speziellen Methoden, zum Beispiel <tt>readPathEntry</tt>, das einen Datei-Systempfad zurückgibt. Es ist entscheidend, dass man <tt>readPathEntry</tt> benutzt, wenn man nach einem Pfad fragt, das es Funktionen wie Erreichbarkeits-Profile ermöglicht richtig zu funktionieren.

Wenn kein solcher Schlüssel im Konfigurationsobjekt existiert, dann wird stattdessen der Standardwert zurückgegeben. Falls es eine lokalisierte (d.h. in eine andere Sprache übersetzte) Version für den Schlüssel gibt, die der eingestellten Sprache entspricht, dann wird diese zurückgegeben.

== Schreiben neuer Einträge ==

Neue Werte zu definieren ist ähnlich einfach:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

Beachten sie die Benutzung von <tt>writePathEntry</tt> und wie die Art von Objekt, das wir benutzen, wie zum Beispiel {{qt|QColor}} auf Zeile 3, bestimmt, wie die Daten angeordnet werden. Zusätzlich, wenn wir mit den Einträgen fertig sind, muss <tt>sync()</tt> auf das Konfigurationsobjekt ausgeführt werden, um es auf die Festplatte zu speichern. Man kann auch einfach warten, bis das Objekt zerstört wird, was falls nötig automatisch einen <tt>sync()</tt> auslöst.

== KDesktopFile: Ein besonderer Fall ==

Wann ist eine Konfigurationsdatei keine Konfigurationsdatei? Wenn es eine [http://freedesktop.org/wiki/Standards_2fdesktop_2dentry_2dspec Desktop-Datei] ist. Diese Dateien, die im Grunde genommen Konfigurationsdateien sind, werden benutzt um Einträge für Anwendungsmenüs, Dateitypen, Plugins und verschiedene Services.

Wenn auf eine .desktop Datei zugegriffen wird, sollte man stattdessen die {{class|KDesktopFile}}-Klasse verwenden, die, während eine {{class|KConfig}}-Klasse über alle oben genannten Ressourcen verfügt, über eine Anzahl von Methoden verfügt, um das Zugreifen auf Standard-Attribute dieser Dateien konsistent und zuverlässig zu machen.

== Kiosk: Abriegelung und Benutzer-/Gruppenprofile ==

KConfig stellt eine Reihe von leistungsstarken Abriegelungs- und Konfigurations-Definitionen bereit, insgesamt als "Kiosk" bekannt, worauf viele System-Administratoren und -Integratoren basieren. Während ein Grossteil dieses Systems der Anwendung transparent bereitgestellt wird, ist es möglich dass man den Schreib/Lese-Status eines Konfigurationsobjekts prüfen will.

Einträge in Konfigurationsobjekten die mithilfe von Kiosk abgeriegelt sind, werden "unveränderlich" genannt. Eine Anwendung kann nach der Unveränderlichkeit von ganzen Konfigurationsobjekten, Gruppen oder Schlüsseln, wie in diesem Beispiel gezeigt, fragen:

<code cppqt n>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "Konfigurationsobjekt ist unveränderlich";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "Die Gruppe 'General' ist unveränderlich";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "Der URL Eintrag in der Gruppe 'General' ist unveränderlich";
}
</code>

Das kann in gewissen Situationen, wo eine Aktion ausgeführt werden soll, falls ein Objekt unveränderlich ist.

== KConfig XT ==

Es gibt einen Weg, gewisse Anwendungsfälle von KConfig einfacher, schneller und zuverlässiger zu machen: KConfig XT. Im Bestimmten kann KConfig XT bei Hauptanwendungs- oder Plug-In-Konfigurationsobjekten und bei Konfigurationsdialogen und anderen Benutzeroberflächen mit diesen Werten sehr hilfreich sein. Es dokumentiert gleichzeitig auch alle verfügbaren Konfigurations-Optionen, was alle System-Administratoren und -Integratoren, die KDE benutzen so viel glücklicher macht.

[[../Using_KConfig_XT_(de)|Die nächste Anleitung handelt über KConfig XT und seine Verwendung.]]

Talk:Development/Tutorials/Plasma/ThemeDetails

2008-03-14T14:51:51Z

Rememberme: New page: Shouldn't this be added to Tutorials in some kind of way (e.g. "create Plasma themes")?

Shouldn't this be added to Tutorials in some kind of way (e.g. "create Plasma themes")?

Development/Tutorials/Updating KConfig Files (de)

2008-02-23T11:11:34Z

Rememberme:

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Updating_KConfig_Files}}
{{TutorialBrowser|

series=KConfig|

pre=[[../KConfig| Einführung in KConfig (de)]]|

name=Aktualisieren von KConfig Dateien|

}}

{{improve (de)}}

=KConfig Update=

Diese Seite beschreibt wie ein Entwickler den KConfig-Aktualisierungs-Mechanismus (kconf_update), der in kdelibs verfügbar ist, verwenden kann, um eine bereits existierende Konfigurationsdatei eines Benutzers zu aktualisieren um sich an Änderungen die am Format der Standard-Datei vorgenommen wurden anzupassen.

==Warum sollte man Kconfig Update Benutzen?==

..todo

Over time applications sometimes need to rearrange the way configuration options are stored. Since such an update shouldn't influence the configuration options that the user has selected, the application must take care that the options stored in the old way will still be honored.

What used to happen is that the application looks up both the old and the
new configuration option and then decides which one to use. This method has several drawbacks:
* The application may need to read more configuration files than strictly needed, resulting in a slower startup.
* The application becomes bigger with code that will only be used once.

kconf_update addresses these problems by offering a framework to update configuration files without adding code to the application itself.

==How it works==

Applications can install so called "update files" under
{{Path|$KDEDIR/share/apps/kconf_update.}} An update file has {{Path|.upd}} as an extension and contains instructions for transferring/converting configuration information from one place to another.

Updating the configuration happens automatically, either when KDE gets started
or when kded detects a new update file in the above mentioned location.

Update files are separated into sections. Each section has an id. When a
section describing a configuration change has been applied, the id will be
stored in the file {{Path|kconf_updaterc}}. This information is used to make sure that a configuration update is only performed once.

If you overwrite an existing update file with a new version that contains a
new section, only the update instructions from this extra section will be
performed.

==File format of the update file==

Empty lines or lines that start with '#' are considered comments
Commas (,) are used to seperate fields and may not occur as part
of any field and all of the keywords are case-sensitive, i.e. you
cannot say "key" instead of "Key" for example.

For the rest the file is parsed and executed sequentially from top to bottom.
Each line can contain one entry. The following entries are recognized:

<code>Id=<id></code>

With <id> identifying the group of update entries that follows. Once a group
of entries have been applied, their <id> is stored and this group of entries
will not be applied again.

<code>
File=<oldfile>,<newfile>
File=<oldfile>
</code>

Specifies that configuration information is read from <oldfile> and written
to <newfile>. If you only specify <oldfile>, the information is read from
and as written to <oldfile>. Note that if the file does not exist
at the time kconf_update first checks, no related update will be performed.

<code>
Script=<script>[,<interpreter>]
</code>

<script> is the program that will be performing the updates. All entries from <oldfile> are piped into <script>. The output of <script>is used as new entries for <newfile>. Existing entries can be deleted by adding lines with "# DELETE [group]key" in the output of the script. To delete a whole group use "# DELETEGROUP [group]".

There are two types of kconf_update scripts:
*Non-Compiled
*Compiled

If <script> is written in a non-compiled language (such as ruby or perl), then it should be installed into
{{Path|${KCONF_UPDATE_INSTALL_DIR} }}.

If <script> is a compiled application, it should be installed in {{Path|${BIN_INSTALL_DIR}/kconf_update_bin}}

If the script command is issued after a "Group" command the behavior is slightly
different:

All entries from <oldfile> in <oldgroup> are piped into <script>. The output
of script is used as new entries for <newfile> in <newgroup>, unless a different
group is specified with "[group]". Existing entries can be deleted from
<oldgroup> by adding lines with "# DELETE key" in the output of the script.·
To delete <oldgroup> use "# DELETEGROUP".

<interpreter> can be something like "perl" or "ruby".

It is also possible to have a script command without specifying <oldfile> or <newfile>. In that case the script is run but it will not be fed any input and its output will simply be discarded.

<code>
ScriptArguments=<arguments>
</code>

If specified, the arguments will be passed to <script>.
IMPORTANT: It has to be specified before Script=.

<code>
Group=<oldgroup>,<newgroup>
Group=<oldgroup>
</code>

Specifies that configuration information is read from the group <oldgroup>
and written to <newgroup>. If you only specify <oldgroup>, the information
is read from as well as written to <oldgroup>. You can use <default> to
specify keys that are not under any group.

<code>
RemoveGroup=<oldgroup>
</code>

Specifies that <oldgroup> is removed entirely. This can be used
to remove obsolete entries or to force a revert to default values.

<code>
Options=<option1>, <option2>,
</code>

With this entry you can specify options that apply to the next "Script",
"Key" or "AllKeys" entry (only to the first!). Possible options are:

*"copy" Copy the configuration item instead of moving it. This means that
the configuration item will not be deleted from <oldfile>/<oldgroup>

*"overwrite" Normally, a configuration item is not moved if an item with the
new name already exists. When this option is specified the old configuration item will overwrite any existing item.

Key=<oldkey>,<newkey>
Key=<oldkey>

Specifies that configuration information is read from the key <oldkey>
and written to <newkey>. If you only specify <oldkey>, the information
is read from as well as written to <oldkey>.

<code>
AllKeys
</code>

Specifies that all configuration information in the selected group should
be moved (All keys).

<code>
AllGroups
</code>

Specifies that all configuration information from all keys in ALL·
groups should be moved.

<code>
RemoveKey=<oldkey>
</code>

Specifies that <oldkey> is removed from the selected group. This can be used
to remove obsolete entries or to force a revert to default values.

Development/Tutorials/Updating KConfig Files (de)

2008-02-23T11:09:48Z

Rememberme: Initial Translation

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Updating_KConfig_Files}}
{{TutorialBrowser|

series=KConfig|

pre=[[../KConfig| Einführung in KConfig]]|

name=Aktualisieren von KConfig Dateien|

}}

=KConfig Update=

Diese Seite beschreibt wie ein Entwickler den KConfig-Aktualisierungs-Mechanismus (kconf_update), der in kdelibs verfügbar ist, verwenden kann, um eine bereits existierende Konfigurationsdatei eines Benutzers zu aktualisieren um sich an Änderungen die am Format der Standard-Datei vorgenommen wurden anzupassen.

==Warum sollte man Kconfig Update Benutzen?==

...todo

Over time applications sometimes need to rearrange the way configuration options are stored. Since such an update shouldn't influence the configuration options that the user has selected, the application must take care that the options stored in the old way will still be honored.

What used to happen is that the application looks up both the old and the
new configuration option and then decides which one to use. This method has several drawbacks:
* The application may need to read more configuration files than strictly needed, resulting in a slower startup.
* The application becomes bigger with code that will only be used once.

kconf_update addresses these problems by offering a framework to update configuration files without adding code to the application itself.

==How it works==

Applications can install so called "update files" under
{{Path|$KDEDIR/share/apps/kconf_update.}} An update file has {{Path|.upd}} as an extension and contains instructions for transferring/converting configuration information from one place to another.

Updating the configuration happens automatically, either when KDE gets started
or when kded detects a new update file in the above mentioned location.

Update files are separated into sections. Each section has an id. When a
section describing a configuration change has been applied, the id will be
stored in the file {{Path|kconf_updaterc}}. This information is used to make sure that a configuration update is only performed once.

If you overwrite an existing update file with a new version that contains a
new section, only the update instructions from this extra section will be
performed.

==File format of the update file==

Empty lines or lines that start with '#' are considered comments
Commas (,) are used to seperate fields and may not occur as part
of any field and all of the keywords are case-sensitive, i.e. you
cannot say "key" instead of "Key" for example.

For the rest the file is parsed and executed sequentially from top to bottom.
Each line can contain one entry. The following entries are recognized:

<code>Id=<id></code>

With <id> identifying the group of update entries that follows. Once a group
of entries have been applied, their <id> is stored and this group of entries
will not be applied again.

<code>
File=<oldfile>,<newfile>
File=<oldfile>
</code>

Specifies that configuration information is read from <oldfile> and written
to <newfile>. If you only specify <oldfile>, the information is read from
and as written to <oldfile>. Note that if the file does not exist
at the time kconf_update first checks, no related update will be performed.

<code>
Script=<script>[,<interpreter>]
</code>

<script> is the program that will be performing the updates. All entries from <oldfile> are piped into <script>. The output of <script>is used as new entries for <newfile>. Existing entries can be deleted by adding lines with "# DELETE [group]key" in the output of the script. To delete a whole group use "# DELETEGROUP [group]".

There are two types of kconf_update scripts:
*Non-Compiled
*Compiled

If <script> is written in a non-compiled language (such as ruby or perl), then it should be installed into
{{Path|${KCONF_UPDATE_INSTALL_DIR} }}.

If <script> is a compiled application, it should be installed in {{Path|${BIN_INSTALL_DIR}/kconf_update_bin}}

If the script command is issued after a "Group" command the behavior is slightly
different:

All entries from <oldfile> in <oldgroup> are piped into <script>. The output
of script is used as new entries for <newfile> in <newgroup>, unless a different
group is specified with "[group]". Existing entries can be deleted from
<oldgroup> by adding lines with "# DELETE key" in the output of the script.·
To delete <oldgroup> use "# DELETEGROUP".

<interpreter> can be something like "perl" or "ruby".

It is also possible to have a script command without specifying <oldfile> or <newfile>. In that case the script is run but it will not be fed any input and its output will simply be discarded.

<code>
ScriptArguments=<arguments>
</code>

If specified, the arguments will be passed to <script>.
IMPORTANT: It has to be specified before Script=.

<code>
Group=<oldgroup>,<newgroup>
Group=<oldgroup>
</code>

Specifies that configuration information is read from the group <oldgroup>
and written to <newgroup>. If you only specify <oldgroup>, the information
is read from as well as written to <oldgroup>. You can use <default> to
specify keys that are not under any group.

<code>
RemoveGroup=<oldgroup>
</code>

Specifies that <oldgroup> is removed entirely. This can be used
to remove obsolete entries or to force a revert to default values.

<code>
Options=<option1>, <option2>,
</code>

With this entry you can specify options that apply to the next "Script",
"Key" or "AllKeys" entry (only to the first!). Possible options are:

*"copy" Copy the configuration item instead of moving it. This means that
the configuration item will not be deleted from <oldfile>/<oldgroup>

*"overwrite" Normally, a configuration item is not moved if an item with the
new name already exists. When this option is specified the old configuration item will overwrite any existing item.

Key=<oldkey>,<newkey>
Key=<oldkey>

Specifies that configuration information is read from the key <oldkey>
and written to <newkey>. If you only specify <oldkey>, the information
is read from as well as written to <oldkey>.

<code>
AllKeys
</code>

Specifies that all configuration information in the selected group should
be moved (All keys).

<code>
AllGroups
</code>

Specifies that all configuration information from all keys in ALL·
groups should be moved.

<code>
RemoveKey=<oldkey>
</code>

Specifies that <oldkey> is removed from the selected group. This can be used
to remove obsolete entries or to force a revert to default values.

Development/Tutorials/KConfig (de)

2008-02-23T10:59:47Z

Rememberme: /* Die KConfig Klasse */

Development/Tutorials/KConfig (de)

2008-02-23T10:58:59Z

Rememberme: /* Die KConfig Klasse */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

{{improve (de)}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer- und Gruppenprofile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

Anwendungen selbst müssen sich deshalb nicht um das Gliedern und Entgliedern von Objekten kümmern.

== Die KConfig Klasse ==

Das {{class|KConfig}}-Objekt wird benutzt um ein bestehendes Konfigurationsobjekt anzusteuern. Es gibt eine Reihe von Möglichkeiten ein Konfigurationsobjekt zu erstellen.

<code cppqt n>
// ein einfaches, altes lesen/schreiben Konfigurationsobjekt
KConfig config("myapprc");

// eine bestimmte Datei im Dateisystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// nicht mit globalen Werten verflochten
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// nicht mit globalen Werten orde der $KDEDIRS Hierarchie verflochten
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// Komponenten-spezifische Konfiguration, in diesem Fall ein Plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// Ausserhalb der normalen Konfigurations-Ressource
KConfig dataResource( "data", "myapp/somefile" );
</code>

{{note (de)|wie soll "merged" in den folgenden Fällen übersetzt werden? <br> <tt>"verschmolzen" oder "verflochten"</tt> <br> der Anwendung selber transparent" tönt auch nicht sehr gut}}

Das Kconfig Objekt, das wir auf Zeile 2 erstellen ist ein gewöhnliches Konfigurationsobjekt. Wir können Werte aus ihm lesen, neue Einträge schreiben und nach verschiedenen Eigenschaften des Objekts fragen. Dieses Objekt wird aus der Konfigurations-Ressource geladen, wie es durch {{class|KStandardDirs}} bestimmt wird, das heisst, dass jede Instanz des <tt>myapprc</tt>-Objekts in jedem der Ordner in der Konfigurations-Ressourcen-Hierarchie verschmolzen werden um die Werte zu erzeugen, die in diesem Objekt gesehen werden. So werden Systemweite und
pro-Benutzer/Gruppen Profile erstellt und unterstützt. Das alles geschieht der Anwendung selber transparent.

{{tip| Für mehr Informationen, wie das Verschmelzen funktioniert, siehe diesen Artikel über die [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Dateisystem Hierarchie]].}}

Auf Zeile 6 öffnen wir eine bestimmte Lokale Datei, in diesem Fall {{path|/etc/kderc}}. Das führt kein verschmelzen von Werten aus und erwartet eine Datei im INI Format.

Zeile 9 erzeugt ein Konfigurationsobjekt, dass nicht mit dem globalen <tt>kdeglobals</tt>-Konfigurationsobjekt verflochten ist, während das Konfigurationsobjekt auf Zeile 12 zusätzlich mit keinem der Dateien in der <tt>$KDEDIRS</tt>-Hierarchie verflochten ist. Das kann die Leistung spürbar verbessern, falls man einfach nur Werte aus einer einfachen Konfuguration liest und globale Werte keine Rolle spielen.

Zeile 15 erzeugt ein Konfigurationsobjekt unter Benutzung des {{class|KComponentData}}-Objekts das zu einem Plugin oder einer anderen Komponente gehört. Das Plugin kann verschiedene Ordner aufweisen, die in seinen {{class|KStandardDirs}} definiert sind und das ist eine Möglichkeit sich zu versichern, dass {{class|KConfig}} das respektiert.

Und schliesslich auf Zeile 18 erzeugen wir ein Konfigurationsobjekt, das nicht in der <tt>config</tt>-Ressource sondern in der <tt>data</tt>-Ressource existiert. Man kann kann auf diese Weise jede Ressource verwenden, von denen {{class|KStandardDirs}} Kenntnis hat, auch solche die während der Laufzeit hinzugefügt werden.

=== Spezielle Konfigurationsobjekte ===

Jede Anwendung hat sein eigenes Konfigurationsobjekt das den Namen benutzt, der von {{class|KAboutData}} bereitgestellt wird mit angehängtem "rc". Also hätte eine Anwendung mit dem Namen "myapp" das Standard-Konfigurationsobjekt "myapprc". Dieses Konfigurationsobjekt kann auf diese Weise aufgerufen werden:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// beachten sie, dass dies eigentlich ein KSharedConfig ist
// mehr über diese Klasse siehe weiter unten
KConfig* config = KGlobal::config();
}
</code>

Auf das Standard-Konfigurationsobjekt für die Anwendung wird zugegriffen, wenn kein Name definiert wurde, als das {{class|KConfig}}-Objekt erzeugt wurde. Also könnten wir stattdessen auch das tun:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

Zusätzlich könnte jede Komponente sein eigenes Konfigurationsobjekt haben. Auf dieses wird normalerweise durch die <tt>componentData()</tt> des Plugins zugegriffen, anstatt durch die <tt>{{class|KGlobal}}::mainComponent()</tt>.

Und schliesslich gibt es noch ein globales Konfigurationsobjekt, <tt>kdeglobals</tt>, das von jeder Anwendung verwendet wird. Es enthält Informationen wie die Standard-Tatenkombinationen für verschiedene Aktionen. Es wird in das Konfigurationsobjekt "gemischt" wenn der <tt>KConfig::IncludeGlobals</tt> Bitschalter dem {{class|KConfig}} Konstruktor übergeben wird, was standardmässig der Fall ist.

=== Allgemein nützliche Methoden ===

Um den momentanen Zustand des Konfigurationsobjektes zu speichern, rufen wir die <tt>sync()</tt>-Methode auf. Diese Methode wird also aufgerufen, wenn ein Objekt zerstört wird. Falls keine Änderungen gemacht wurden, oder die Ressource weist sich als nicht beschreibbar aus (Wenn der Benutzer zum Beispiel nicht genug Rechte hat, um die Datei zu bearbeiten), dann wird keine Beschäftigung der Festplatte hervorgerufen. <tt>sync()</tt> verschmilzt Änderungen die gleichzeitig von anderen Prozessen ausgeführt werden - lokale Änderungen haben aber trotzdem Vorrang.

Wenn wir sicher gehen wollen, dass wir die aktuellsten Werte von der Festplatte haben, dann rufen wir <tt>reparseConfiguration()</tt> auf, welches <tt>sync()</tt> aufruft und dann die Daten von der Festplatte aktualisiert.

Falls wir verhindern müssen, dass das Konfigurationsobjekt bereits gemachte Änderungen nicht auf die Festplatte speichert, müssen wir <tt>markAsClean()</tt> aufrufen. Ein besonderer Anwendungsfall ist es, die Konfiguration zum Festplatten-Zustand zurückzusetzen indem man <tt>markAsClean()</tt> gefolgt von <tt>reparseConfiguration()</tt> aufruft.

Alle Gruppen in einem Konfigurationsobjekt aufzurufen ist so einfach wie hier in diesem Code-Abschnitt <tt>groupList()</tt> aufzurufen.

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

Die {{class|KSharedConfig}} Klasse ist eine Referenz-gezählte Version von {{class|KConfig}}. Darum stellt es eine Möglichkeit bereit, das selbe Konfigurationsobjekt von unterschiedlichen Orten zu referenzieren ohne zusätzlich die Objekte trennen zu müssen oder sich um die Synchronisation des Schreibvorgangs zu kümmern, selbst wenn das Konfigurationsobjekt von verschiedenen Code-Pfaden aktualisiert wird.

Auf ein {{class|KSharedConfig}}-Objekt zuzugreifen ist so einfach wie das hier:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<tt>openConfig()</tt> nimmt die selben Parameter wie {{class|KConfig}}'s Konstruktoren, was es einem ermöglicht zu definieren, welche Konfigurationsdatei zu öffnen und Markierungen das Verschmelzen von nicht-<tt>config</tt>-Ressourcen zu kontrollieren.

Es wird grundsätzlich empfohlen {{class|KSharedConfig}} anstatt {{class|KConfig}} selbst zu benutzen, und auch das Objekt, das von {{class|KComponentData}} zurückgegeben wird ist in der Tat ein {{class|KSharedConfig}}-Objekt.

== KConfigGroup ==

Nun da wir ein Konfigurationsobjekt haben, ist der nächste Schritt es tatsächlich zu nutzen. Das erste, das wir tun müssen, ist zu bestimmen, auf welche Gruppe von Schlüssel-/Wertepaare wir in unserem Objekt zugreifen wollen. Wir tun das, indem wir ein KConfigGroup-Objekt erstellen.

<code cppqt n>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ...oder so ähnlich...
</code>

Man kann{{class|KConfigGroup}} {{class|KConfig}}- oder {{class|KSharedConfig}}-Objekte übergeben.

Konfigurationsgruppen können ebenfalls verschachtelt werden.

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Lesen von Einträgen ==

Wenn man erst einmal ein {{class|KConfigGroup}}-Objekt erstellt hat, ist das Lesen von Einträgen ziemlich einfach:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

Wie man hier oben sehen kann, kann man Lesevorgänge von verschiedenen {{class|KConfigGroup}}-Objekten, die auf dem selben {{class|KConfig}}-Objekt erstellt wurden, problemlos mischen. Die Lese-Methoden nehmen den Schlüssel, der Gross- und Kleinschreibung unterscheidet, als erstes Argument und den Standardwert als zweites Argument. Dieses Argument bestimmt auch welche Art von Daten, also z.B. eine Farbe in Zeile 3, erwartet wird und auch die Art von Objekt, die zurückgegeben werden soll.Das zurückgegebene Objekt wird in eine {{qt|QVariant}} gepackt um diese Hexerei zu ermöglichen.

Es gibt eine Anzahl von speziellen Methoden, zum Beispiel <tt>readPathEntry</tt>, das einen Datei-Systempfad zurückgibt. Es ist entscheidend, dass man <tt>readPathEntry</tt> benutzt, wenn man nach einem Pfad fragt, das es Funktionen wie Erreichbarkeits-Profile ermöglicht richtig zu funktionieren.

Wenn kein solcher Schlüssel im Konfigurationsobjekt existiert, dann wird stattdessen der Standardwert zurückgegeben. Falls es eine lokalisierte (d.h. in eine andere Sprache übersetzte) Version für den Schlüssel gibt, die der eingestellten Sprache entspricht, dann wird diese zurückgegeben.

== Schreiben neuer Einträge ==

Neue Werte zu definieren ist ähnlich einfach:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

Beachten sie die Benutzung von <tt>writePathEntry</tt> und wie die Art von Objekt, das wir benutzen, wie zum Beispiel {{qt|QColor}} auf Zeile 3, bestimmt, wie die Daten angeordnet werden. Zusätzlich, wenn wir mit den Einträgen fertig sind, muss <tt>sync()</tt> auf das Konfigurationsobjekt ausgeführt werden, um es auf die Festplatte zu speichern. Man kann auch einfach warten, bis das Objekt zerstört wird, was falls nötig automatisch einen <tt>sync()</tt> auslöst.

== KDesktopFile: Ein besonderer Fall ==

Wann ist eine Konfigurationsdatei keine Konfigurationsdatei? Wenn es eine [http://freedesktop.org/wiki/Standards_2fdesktop_2dentry_2dspec Desktop-Datei] ist. Diese Dateien, die im Grunde genommen Konfigurationsdateien sind, werden benutzt um Einträge für Anwendungsmenüs, Dateitypen, Plugins und verschiedene Services.

Wenn auf eine .desktop Datei zugegriffen wird, sollte man stattdessen die {{class|KDesktopFile}}-Klasse verwenden, die, während eine {{class|KConfig}}-Klasse über alle oben genannten Ressourcen verfügt, über eine Anzahl von Methoden verfügt, um das Zugreifen auf Standard-Attribute dieser Dateien konsistent und zuverlässig zu machen.

== Kiosk: Abriegelung und Benutzer-/Gruppenprofile ==

KConfig stellt eine Reihe von leistungsstarken Abriegelungs- und Konfigurations-Definitionen bereit, insgesamt als "Kiosk" bekannt, worauf viele System-Administratoren und -Integratoren basieren. Während ein Grossteil dieses Systems der Anwendung transparent bereitgestellt wird, ist es möglich dass man den Schreib/Lese-Status eines Konfigurationsobjekts prüfen will.

Einträge in Konfigurationsobjekten die mithilfe von Kiosk abgeriegelt sind, werden "unveränderlich" genannt. Eine Anwendung kann nach der Unveränderlichkeit von ganzen Konfigurationsobjekten, Gruppen oder Schlüsseln, wie in diesem Beispiel gezeigt, fragen:

<code cppqt n>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "Konfigurationsobjekt ist unveränderlich";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "Die Gruppe 'General' ist unveränderlich";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "Der URL Eintrag in der Gruppe 'General' ist unveränderlich";
}
</code>

Das kann in gewissen Situationen, wo eine Aktion ausgeführt werden soll, falls ein Objekt unveränderlich ist.

== KConfig XT ==

Es gibt einen Weg, gewisse Anwendungsfälle von KConfig einfacher, schneller und zuverlässiger zu machen: KConfig XT. Im Bestimmten kann KConfig XT bei Hauptanwendungs- oder Plug-In-Konfigurationsobjekten und bei Konfigurationsdialogen und anderen Benutzeroberflächen mit diesen Werten sehr hilfreich sein. Es dokumentiert gleichzeitig auch alle verfügbaren Konfigurations-Optionen, was alle System-Administratoren und -Integratoren, die KDE benutzen so viel glücklicher macht.

[[../Using_KConfig_XT_(de)|Die nächste Anleitung handelt über KConfig XT und wie es zu benutzen.]]

Development/Tutorials/KConfig (de)

2008-02-23T10:57:35Z

Rememberme: /* Grundlegender Aufbau */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

{{improve (de)}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer- und Gruppenprofile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

Anwendungen selbst müssen sich deshalb nicht um das Gliedern und Entgliedern von Objekten kümmern.

== Die KConfig Klasse ==

Das {{class|KConfig}}-Objekt wird benutzt um ein bestehendes Konfigurationsobjekt anzusteuern. Es gibt eine Reihe von Möglichkeiten ein Konfigurationsobjekt zu erstellen.

<code cppqt n>
// ein einfaches, altes lesen/schreiben Konfigurationsobjekt
KConfig config("myapprc");

// eine bestimmte Datei im Dateisystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// nicht mit globalen Werten verflochten
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// nicht mit globalen Werten orde der $KDEDIRS Hierarchie verflochten
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// Komponenten-spezifische Konfiguration, in diesem Fall ein Plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// Ausserhalb der normalen Konfigurations-Ressource
KConfig dataResource( "data", "myapp/somefile" );
</code>

{{note (de)|wie soll "merged" in den folgenden Fällen übersetzt werden? <br> <tt>"verschmolzen" oder "verflochten"</tt> <br> der Anwendung selber transparent" tönt auch nicht sehr gut}}

Das Kconfig Objekt, das wir auf Zeile 2 erstellen ist ein gewöhnliches Konfigurationsobjekt. Wir können Werte aus ihm lesen, neue Einträge schreiben und nach verschiedenen Eigenschaften des Objekts fragen. Dieses Objekt wird aus der Konfigurations-Ressource geladen, wie es durch {{class|KStandardDirs}} bestimmt wird, das heisst, dass jede Instanz des <tt>myapprc</tt>-Objekts in jedem der Ordner in der Konfigurations-Ressourcen-Hierarchie verschmolzen werden um die Werte zu erzeugen, die in diesem Objekt gesehen werden. So werden Systemweite und
pro-Benutzer/Gruppen Profile erstellt und unterstützt. Das alles geschieht der Anwendung selber transparent.

{{tip| Für mehr Informationen, wie das Verschmelzen funktioniert, siehe diesen Artikel über die [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Dateisystem Hierarchie]].}}

{{note (de)|Ist das so gemeint mit "expects an INI style file"<br> <tt> On line 6 we open a specific local file, this case /etc/kderc. This performs no merging of values and expects an INI style file.</tt>}}

Auf Zeile 6 öffnen wir eine bestimmte Lokale Datei, in diesem Fall {{path|/etc/kderc}}. Das führt kein verschmelzen von Werten aus und erwartet eine Datei im INI Format.

Zeile 9 erzeugt ein Konfigurationsobjekt, dass nicht mit dem globalen <tt>kdeglobals</tt>-Konfigurationsobjekt verflochten ist, während das Konfigurationsobjekt auf Zeile 12 zusätzlich mit keinem der Dateien in der <tt>$KDEDIRS</tt>-Hierarchie verflochten ist. Das kann die Leistung spürbar verbessern, falls man einfach nur Werte aus einer einfachen Konfuguration liest und globale Werte keine Rolle spielen.

Zeile 15 erzeugt ein Konfigurationsobjekt unter Benutzung des {{class|KComponentData}}-Objekts das zu einem Plugin oder einer anderen Komponente gehört. Das Plugin kann verschiedene Ordner aufweisen, die in seinen {{class|KStandardDirs}} definiert sind und das ist eine Möglichkeit sich zu versichern, dass {{class|KConfig}} das respektiert.

Und schliesslich auf Zeile 18 erzeugen wir ein Konfigurationsobjekt, das nicht in der <tt>config</tt>-Ressource sondern in der <tt>data</tt>-Ressource existiert. Man kann kann auf diese Weise jede Ressource verwenden, von denen {{class|KStandardDirs}} Kenntnis hat, auch solche die während der Laufzeit hinzugefügt werden.

=== Spezielle Konfigurationsobjekte ===

Jede Anwendung hat sein eigenes Konfigurationsobjekt das den Namen benutzt, der von {{class|KAboutData}} bereitgestellt wird mit angehängtem "rc". Also hätte eine Anwendung mit dem Namen "myapp" das Standard-Konfigurationsobjekt "myapprc". Dieses Konfigurationsobjekt kann auf diese Weise aufgerufen werden:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// beachten sie, dass dies eigentlich ein KSharedConfig ist
// mehr über diese Klasse siehe weiter unten
KConfig* config = KGlobal::config();
}
</code>

Auf das Standard-Konfigurationsobjekt für die Anwendung wird zugegriffen, wenn kein Name definiert wurde, als das {{class|KConfig}}-Objekt erzeugt wurde. Also könnten wir stattdessen auch das tun:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

Zusätzlich könnte jede Komponente sein eigenes Konfigurationsobjekt haben. Auf dieses wird normalerweise durch die <tt>componentData()</tt> des Plugins zugegriffen, anstatt durch die <tt>{{class|KGlobal}}::mainComponent()</tt>.

Und schliesslich gibt es noch ein globales Konfigurationsobjekt, <tt>kdeglobals</tt>, das von jeder Anwendung verwendet wird. Es enthält Informationen wie die Standard-Tatenkombinationen für verschiedene Aktionen. Es wird in das Konfigurationsobjekt "gemischt" wenn der <tt>KConfig::IncludeGlobals</tt> Bitschalter dem {{class|KConfig}} Konstruktor übergeben wird, was standardmässig der Fall ist.

=== Allgemein nützliche Methoden ===

Um den momentanen Zustand des Konfigurationsobjektes zu speichern, rufen wir die <tt>sync()</tt>-Methode auf. Diese Methode wird also aufgerufen, wenn ein Objekt zerstört wird. Falls keine Änderungen gemacht wurden, oder die Ressource weist sich als nicht beschreibbar aus (Wenn der Benutzer zum Beispiel nicht genug Rechte hat, um die Datei zu bearbeiten), dann wird keine Beschäftigung der Festplatte hervorgerufen. <tt>sync()</tt> verschmilzt Änderungen die gleichzeitig von anderen Prozessen ausgeführt werden - lokale Änderungen haben aber trotzdem Vorrang.

Wenn wir sicher gehen wollen, dass wir die aktuellsten Werte von der Festplatte haben, dann rufen wir <tt>reparseConfiguration()</tt> auf, welches <tt>sync()</tt> aufruft und dann die Daten von der Festplatte aktualisiert.

Falls wir verhindern müssen, dass das Konfigurationsobjekt bereits gemachte Änderungen nicht auf die Festplatte speichert, müssen wir <tt>markAsClean()</tt> aufrufen. Ein besonderer Anwendungsfall ist es, die Konfiguration zum Festplatten-Zustand zurückzusetzen indem man <tt>markAsClean()</tt> gefolgt von <tt>reparseConfiguration()</tt> aufruft.

Alle Gruppen in einem Konfigurationsobjekt aufzurufen ist so einfach wie hier in diesem Code-Abschnitt <tt>groupList()</tt> aufzurufen.

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

Die {{class|KSharedConfig}} Klasse ist eine Referenz-gezählte Version von {{class|KConfig}}. Darum stellt es eine Möglichkeit bereit, das selbe Konfigurationsobjekt von unterschiedlichen Orten zu referenzieren ohne zusätzlich die Objekte trennen zu müssen oder sich um die Synchronisation des Schreibvorgangs zu kümmern, selbst wenn das Konfigurationsobjekt von verschiedenen Code-Pfaden aktualisiert wird.

Auf ein {{class|KSharedConfig}}-Objekt zuzugreifen ist so einfach wie das hier:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<tt>openConfig()</tt> nimmt die selben Parameter wie {{class|KConfig}}'s Konstruktoren, was es einem ermöglicht zu definieren, welche Konfigurationsdatei zu öffnen und Markierungen das Verschmelzen von nicht-<tt>config</tt>-Ressourcen zu kontrollieren.

Es wird grundsätzlich empfohlen {{class|KSharedConfig}} anstatt {{class|KConfig}} selbst zu benutzen, und auch das Objekt, das von {{class|KComponentData}} zurückgegeben wird ist in der Tat ein {{class|KSharedConfig}}-Objekt.

== KConfigGroup ==

Nun da wir ein Konfigurationsobjekt haben, ist der nächste Schritt es tatsächlich zu nutzen. Das erste, das wir tun müssen, ist zu bestimmen, auf welche Gruppe von Schlüssel-/Wertepaare wir in unserem Objekt zugreifen wollen. Wir tun das, indem wir ein KConfigGroup-Objekt erstellen.

<code cppqt n>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ...oder so ähnlich...
</code>

Man kann{{class|KConfigGroup}} {{class|KConfig}}- oder {{class|KSharedConfig}}-Objekte übergeben.

Konfigurationsgruppen können ebenfalls verschachtelt werden.

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Lesen von Einträgen ==

Wenn man erst einmal ein {{class|KConfigGroup}}-Objekt erstellt hat, ist das Lesen von Einträgen ziemlich einfach:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

Wie man hier oben sehen kann, kann man Lesevorgänge von verschiedenen {{class|KConfigGroup}}-Objekten, die auf dem selben {{class|KConfig}}-Objekt erstellt wurden, problemlos mischen. Die Lese-Methoden nehmen den Schlüssel, der Gross- und Kleinschreibung unterscheidet, als erstes Argument und den Standardwert als zweites Argument. Dieses Argument bestimmt auch welche Art von Daten, also z.B. eine Farbe in Zeile 3, erwartet wird und auch die Art von Objekt, die zurückgegeben werden soll.Das zurückgegebene Objekt wird in eine {{qt|QVariant}} gepackt um diese Hexerei zu ermöglichen.

Es gibt eine Anzahl von speziellen Methoden, zum Beispiel <tt>readPathEntry</tt>, das einen Datei-Systempfad zurückgibt. Es ist entscheidend, dass man <tt>readPathEntry</tt> benutzt, wenn man nach einem Pfad fragt, das es Funktionen wie Erreichbarkeits-Profile ermöglicht richtig zu funktionieren.

Wenn kein solcher Schlüssel im Konfigurationsobjekt existiert, dann wird stattdessen der Standardwert zurückgegeben. Falls es eine lokalisierte (d.h. in eine andere Sprache übersetzte) Version für den Schlüssel gibt, die der eingestellten Sprache entspricht, dann wird diese zurückgegeben.

== Schreiben neuer Einträge ==

Neue Werte zu definieren ist ähnlich einfach:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

Beachten sie die Benutzung von <tt>writePathEntry</tt> und wie die Art von Objekt, das wir benutzen, wie zum Beispiel {{qt|QColor}} auf Zeile 3, bestimmt, wie die Daten angeordnet werden. Zusätzlich, wenn wir mit den Einträgen fertig sind, muss <tt>sync()</tt> auf das Konfigurationsobjekt ausgeführt werden, um es auf die Festplatte zu speichern. Man kann auch einfach warten, bis das Objekt zerstört wird, was falls nötig automatisch einen <tt>sync()</tt> auslöst.

== KDesktopFile: Ein besonderer Fall ==

Wann ist eine Konfigurationsdatei keine Konfigurationsdatei? Wenn es eine [http://freedesktop.org/wiki/Standards_2fdesktop_2dentry_2dspec Desktop-Datei] ist. Diese Dateien, die im Grunde genommen Konfigurationsdateien sind, werden benutzt um Einträge für Anwendungsmenüs, Dateitypen, Plugins und verschiedene Services.

Wenn auf eine .desktop Datei zugegriffen wird, sollte man stattdessen die {{class|KDesktopFile}}-Klasse verwenden, die, während eine {{class|KConfig}}-Klasse über alle oben genannten Ressourcen verfügt, über eine Anzahl von Methoden verfügt, um das Zugreifen auf Standard-Attribute dieser Dateien konsistent und zuverlässig zu machen.

== Kiosk: Abriegelung und Benutzer-/Gruppenprofile ==

KConfig stellt eine Reihe von leistungsstarken Abriegelungs- und Konfigurations-Definitionen bereit, insgesamt als "Kiosk" bekannt, worauf viele System-Administratoren und -Integratoren basieren. Während ein Grossteil dieses Systems der Anwendung transparent bereitgestellt wird, ist es möglich dass man den Schreib/Lese-Status eines Konfigurationsobjekts prüfen will.

Einträge in Konfigurationsobjekten die mithilfe von Kiosk abgeriegelt sind, werden "unveränderlich" genannt. Eine Anwendung kann nach der Unveränderlichkeit von ganzen Konfigurationsobjekten, Gruppen oder Schlüsseln, wie in diesem Beispiel gezeigt, fragen:

<code cppqt n>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "Konfigurationsobjekt ist unveränderlich";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "Die Gruppe 'General' ist unveränderlich";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "Der URL Eintrag in der Gruppe 'General' ist unveränderlich";
}
</code>

Das kann in gewissen Situationen, wo eine Aktion ausgeführt werden soll, falls ein Objekt unveränderlich ist.

== KConfig XT ==

Es gibt einen Weg, gewisse Anwendungsfälle von KConfig einfacher, schneller und zuverlässiger zu machen: KConfig XT. Im Bestimmten kann KConfig XT bei Hauptanwendungs- oder Plug-In-Konfigurationsobjekten und bei Konfigurationsdialogen und anderen Benutzeroberflächen mit diesen Werten sehr hilfreich sein. Es dokumentiert gleichzeitig auch alle verfügbaren Konfigurations-Optionen, was alle System-Administratoren und -Integratoren, die KDE benutzen so viel glücklicher macht.

[[../Using_KConfig_XT_(de)|Die nächste Anleitung handelt über KConfig XT und wie es zu benutzen.]]

Development/Tutorials/KConfig (de)

2008-02-07T13:39:50Z

Rememberme:

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

{{improve (de)}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer- und Gruppenprofile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

{{note (de)| deserialization entgliedern? <br> <tt> "do not have to perform serialization and deserialization of objects themselves" </tt>}}

Anwendungen selbst müssen darum normalerweise Objekte nicht selber gliedern und entgliedern.

== Die KConfig Klasse ==

Das {{class|KConfig}}-Objekt wird benutzt um ein bestehendes Konfigurationsobjekt anzusteuern. Es gibt eine Reihe von Möglichkeiten ein Konfigurationsobjekt zu erstellen.

<code cppqt n>
// ein einfaches, altes lesen/schreiben Konfigurationsobjekt
KConfig config("myapprc");

// eine bestimmte Datei im Dateisystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// nicht mit globalen Werten verflochten
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// nicht mit globalen Werten orde der $KDEDIRS Hierarchie verflochten
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// Komponenten-spezifische Konfiguration, in diesem Fall ein Plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// Ausserhalb der normalen Konfigurations-Ressource
KConfig dataResource( "data", "myapp/somefile" );
</code>

{{note (de)|wie soll "merged" in den folgenden Fällen übersetzt werden? <br> <tt>"verschmolzen" oder "verflochten"</tt> <br> der Anwendung selber transparent" tönt auch nicht sehr gut}}

Das Kconfig Objekt, das wir auf Zeile 2 erstellen ist ein gewöhnliches Konfigurationsobjekt. Wir können Werte aus ihm lesen, neue Einträge schreiben und nach verschiedenen Eigenschaften des Objekts fragen. Dieses Objekt wird aus der Konfigurations-Ressource geladen, wie es durch {{class|KStandardDirs}} bestimmt wird, das heisst, dass jede Instanz des <tt>myapprc</tt>-Objekts in jedem der Ordner in der Konfigurations-Ressourcen-Hierarchie verschmolzen werden um die Werte zu erzeugen, die in diesem Objekt gesehen werden. So werden Systemweite und
pro-Benutzer/Gruppen Profile erstellt und unterstützt. Das alles geschieht der Anwendung selber transparent.

{{tip| Für mehr Informationen, wie das Verschmelzen funktioniert, siehe diesen Artikel über die [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Dateisystem Hierarchie]].}}

{{note (de)|Ist das so gemeint mit "expects an INI style file"<br> <tt> On line 6 we open a specific local file, this case /etc/kderc. This performs no merging of values and expects an INI style file.</tt>}}

Auf Zeile 6 öffnen wir eine bestimmte Lokale Datei, in diesem Fall {{path|/etc/kderc}}. Das führt kein verschmelzen von Werten aus und erwartet eine Datei im INI Format.

Zeile 9 erzeugt ein Konfigurationsobjekt, dass nicht mit dem globalen <tt>kdeglobals</tt>-Konfigurationsobjekt verflochten ist, während das Konfigurationsobjekt auf Zeile 12 zusätzlich mit keinem der Dateien in der <tt>$KDEDIRS</tt>-Hierarchie verflochten ist. Das kann die Leistung spürbar verbessern, falls man einfach nur Werte aus einer einfachen Konfuguration liest und globale Werte keine Rolle spielen.

Zeile 15 erzeugt ein Konfigurationsobjekt unter Benutzung des {{class|KComponentData}}-Objekts das zu einem Plugin oder einer anderen Komponente gehört. Das Plugin kann verschiedene Ordner aufweisen, die in seinen {{class|KStandardDirs}} definiert sind und das ist eine Möglichkeit sich zu versichern, dass {{class|KConfig}} das respektiert.

Und schliesslich auf Zeile 18 erzeugen wir ein Konfigurationsobjekt, das nicht in der <tt>config</tt>-Ressource sondern in der <tt>data</tt>-Ressource existiert. Man kann kann auf diese Weise jede Ressource verwenden, von denen {{class|KStandardDirs}} Kenntnis hat, auch solche die während der Laufzeit hinzugefügt werden.

=== Spezielle Konfigurationsobjekte ===

Jede Anwendung hat sein eigenes Konfigurationsobjekt das den Namen benutzt, der von {{class|KAboutData}} bereitgestellt wird mit angehängtem "rc". Also hätte eine Anwendung mit dem Namen "myapp" das Standard-Konfigurationsobjekt "myapprc". Dieses Konfigurationsobjekt kann auf diese Weise aufgerufen werden:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// beachten sie, dass dies eigentlich ein KSharedConfig ist
// mehr über diese Klasse siehe weiter unten
KConfig* config = KGlobal::config();
}
</code>

Auf das Standard-Konfigurationsobjekt für die Anwendung wird zugegriffen, wenn kein Name definiert wurde, als das {{class|KConfig}}-Objekt erzeugt wurde. Also könnten wir stattdessen auch das tun:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

Zusätzlich könnte jede Komponente sein eigenes Konfigurationsobjekt haben. Auf dieses wird normalerweise durch die <tt>componentData()</tt> des Plugins zugegriffen, anstatt durch die <tt>{{class|KGlobal}}::mainComponent()</tt>.

Und schliesslich gibt es noch ein globales Konfigurationsobjekt, <tt>kdeglobals</tt>, das von jeder Anwendung verwendet wird. Es enthält Informationen wie die Standard-Tatenkombinationen für verschiedene Aktionen. Es wird in das Konfigurationsobjekt "gemischt" wenn der <tt>KConfig::IncludeGlobals</tt> Bitschalter dem {{class|KConfig}} Konstruktor übergeben wird, was standardmässig der Fall ist.

=== Allgemein nützliche Methoden ===

Um den momentanen Zustand des Konfigurationsobjektes zu speichern, rufen wir die <tt>sync()</tt>-Methode auf. Diese Methode wird also aufgerufen, wenn ein Objekt zerstört wird. Falls keine Änderungen gemacht wurden, oder die Ressource weist sich als nicht beschreibbar aus (Wenn der Benutzer zum Beispiel nicht genug Rechte hat, um die Datei zu bearbeiten), dann wird keine Beschäftigung der Festplatte hervorgerufen. <tt>sync()</tt> verschmilzt Änderungen die gleichzeitig von anderen Prozessen ausgeführt werden - lokale Änderungen haben aber trotzdem Vorrang.

Wenn wir sicher gehen wollen, dass wir die aktuellsten Werte von der Festplatte haben, dann rufen wir <tt>reparseConfiguration()</tt> auf, welches <tt>sync()</tt> aufruft und dann die Daten von der Festplatte aktualisiert.

Falls wir verhindern müssen, dass das Konfigurationsobjekt bereits gemachte Änderungen nicht auf die Festplatte speichert, müssen wir <tt>markAsClean()</tt> aufrufen. Ein besonderer Anwendungsfall ist es, die Konfiguration zum Festplatten-Zustand zurückzusetzen indem man <tt>markAsClean()</tt> gefolgt von <tt>reparseConfiguration()</tt> aufruft.

Alle Gruppen in einem Konfigurationsobjekt aufzurufen ist so einfach wie hier in diesem Code-Abschnitt <tt>groupList()</tt> aufzurufen.

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

Die {{class|KSharedConfig}} Klasse ist eine Referenz-gezählte Version von {{class|KConfig}}. Darum stellt es eine Möglichkeit bereit, das selbe Konfigurationsobjekt von unterschiedlichen Orten zu referenzieren ohne zusätzlich die Objekte trennen zu müssen oder sich um die Synchronisation des Schreibvorgangs zu kümmern, selbst wenn das Konfigurationsobjekt von verschiedenen Code-Pfaden aktualisiert wird.

Auf ein {{class|KSharedConfig}}-Objekt zuzugreifen ist so einfach wie das hier:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<tt>openConfig()</tt> nimmt die selben Parameter wie {{class|KConfig}}'s Konstruktoren, was es einem ermöglicht zu definieren, welche Konfigurationsdatei zu öffnen und Markierungen das Verschmelzen von nicht-<tt>config</tt>-Ressourcen zu kontrollieren.

Es wird grundsätzlich empfohlen {{class|KSharedConfig}} anstatt {{class|KConfig}} selbst zu benutzen, und auch das Objekt, das von {{class|KComponentData}} zurückgegeben wird ist in der Tat ein {{class|KSharedConfig}}-Objekt.

== KConfigGroup ==

Nun da wir ein Konfigurationsobjekt haben, ist der nächste Schritt es tatsächlich zu nutzen. Das erste, das wir tun müssen, ist zu bestimmen, auf welche Gruppe von Schlüssel-/Wertepaare wir in unserem Objekt zugreifen wollen. Wir tun das, indem wir ein KConfigGroup-Objekt erstellen.

<code cppqt n>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ...oder so ähnlich...
</code>

Man kann{{class|KConfigGroup}} {{class|KConfig}}- oder {{class|KSharedConfig}}-Objekte übergeben.

Konfigurationsgruppen können ebenfalls verschachtelt werden.

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Lesen von Einträgen ==

Wenn man erst einmal ein {{class|KConfigGroup}}-Objekt erstellt hat, ist das Lesen von Einträgen ziemlich einfach:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

Wie man hier oben sehen kann, kann man Lesevorgänge von verschiedenen {{class|KConfigGroup}}-Objekten, die auf dem selben {{class|KConfig}}-Objekt erstellt wurden, problemlos mischen. Die Lese-Methoden nehmen den Schlüssel, der Gross- und Kleinschreibung unterscheidet, als erstes Argument und den Standardwert als zweites Argument. Dieses Argument bestimmt auch welche Art von Daten, also z.B. eine Farbe in Zeile 3, erwartet wird und auch die Art von Objekt, die zurückgegeben werden soll.Das zurückgegebene Objekt wird in eine {{qt|QVariant}} gepackt um diese Hexerei zu ermöglichen.

Es gibt eine Anzahl von speziellen Methoden, zum Beispiel <tt>readPathEntry</tt>, das einen Datei-Systempfad zurückgibt. Es ist entscheidend, dass man <tt>readPathEntry</tt> benutzt, wenn man nach einem Pfad fragt, das es Funktionen wie Erreichbarkeits-Profile ermöglicht richtig zu funktionieren.

Wenn kein solcher Schlüssel im Konfigurationsobjekt existiert, dann wird stattdessen der Standardwert zurückgegeben. Falls es eine lokalisierte (d.h. in eine andere Sprache übersetzte) Version für den Schlüssel gibt, die der eingestellten Sprache entspricht, dann wird diese zurückgegeben.

== Schreiben neuer Einträge ==

Neue Werte zu definieren ist ähnlich einfach:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

Beachten sie die Benutzung von <tt>writePathEntry</tt> und wie die Art von Objekt, das wir benutzen, wie zum Beispiel {{qt|QColor}} auf Zeile 3, bestimmt, wie die Daten angeordnet werden. Zusätzlich, wenn wir mit den Einträgen fertig sind, muss <tt>sync()</tt> auf das Konfigurationsobjekt ausgeführt werden, um es auf die Festplatte zu speichern. Man kann auch einfach warten, bis das Objekt zerstört wird, was falls nötig automatisch einen <tt>sync()</tt> auslöst.

== KDesktopFile: Ein besonderer Fall ==

Wann ist eine Konfigurationsdatei keine Konfigurationsdatei? Wenn es eine [http://freedesktop.org/wiki/Standards_2fdesktop_2dentry_2dspec Desktop-Datei] ist. Diese Dateien, die im Grunde genommen Konfigurationsdateien sind, werden benutzt um Einträge für Anwendungsmenüs, Dateitypen, Plugins und verschiedene Services.

Wenn auf eine .desktop Datei zugegriffen wird, sollte man stattdessen die {{class|KDesktopFile}}-Klasse verwenden, die, während eine {{class|KConfig}}-Klasse über alle oben genannten Ressourcen verfügt, über eine Anzahl von Methoden verfügt, um das Zugreifen auf Standard-Attribute dieser Dateien konsistent und zuverlässig zu machen.

== Kiosk: Abriegelung und Benutzer-/Gruppenprofile ==

KConfig stellt eine Reihe von leistungsstarken Abriegelungs- und Konfigurations-Definitionen bereit, insgesamt als "Kiosk" bekannt, worauf viele System-Administratoren und -Integratoren basieren. Während ein Grossteil dieses Systems der Anwendung transparent bereitgestellt wird, ist es möglich dass man den Schreib/Lese-Status eines Konfigurationsobjekts prüfen will.

Einträge in Konfigurationsobjekten die mithilfe von Kiosk abgeriegelt sind, werden "unveränderlich" genannt. Eine Anwendung kann nach der Unveränderlichkeit von ganzen Konfigurationsobjekten, Gruppen oder Schlüsseln, wie in diesem Beispiel gezeigt, fragen:

<code cppqt n>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "Konfigurationsobjekt ist unveränderlich";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "Die Gruppe 'General' ist unveränderlich";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "Der URL Eintrag in der Gruppe 'General' ist unveränderlich";
}
</code>

Das kann in gewissen Situationen, wo eine Aktion ausgeführt werden soll, falls ein Objekt unveränderlich ist.

== KConfig XT ==

Es gibt einen Weg, gewisse Anwendungsfälle von KConfig einfacher, schneller und zuverlässiger zu machen: KConfig XT. Im Bestimmten kann KConfig XT bei Hauptanwendungs- oder Plug-In-Konfigurationsobjekten und bei Konfigurationsdialogen und anderen Benutzeroberflächen mit diesen Werten sehr hilfreich sein. Es dokumentiert gleichzeitig auch alle verfügbaren Konfigurations-Optionen, was alle System-Administratoren und -Integratoren, die KDE benutzen so viel glücklicher macht.

[[../Using_KConfig_XT_(de)|Die nächste Anleitung handelt über KConfig XT und wie es zu benutzen.]]

Development/Tutorials/KConfig (de)

2008-02-07T13:38:35Z

Rememberme: /* KConfig XT */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT|Benutzen von KConfig XT]]|

reading=Keine

}}

{{improve (de)}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer- und Gruppenprofile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

{{note (de)| deserialization entgliedern? <br> <tt> "do not have to perform serialization and deserialization of objects themselves" </tt>}}

Anwendungen selbst müssen darum normalerweise Objekte nicht selber gliedern und entgliedern.

== Die KConfig Klasse ==

Das {{class|KConfig}}-Objekt wird benutzt um ein bestehendes Konfigurationsobjekt anzusteuern. Es gibt eine Reihe von Möglichkeiten ein Konfigurationsobjekt zu erstellen.

<code cppqt n>
// ein einfaches, altes lesen/schreiben Konfigurationsobjekt
KConfig config("myapprc");

// eine bestimmte Datei im Dateisystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// nicht mit globalen Werten verflochten
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// nicht mit globalen Werten orde der $KDEDIRS Hierarchie verflochten
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// Komponenten-spezifische Konfiguration, in diesem Fall ein Plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// Ausserhalb der normalen Konfigurations-Ressource
KConfig dataResource( "data", "myapp/somefile" );
</code>

{{note (de)|wie soll "merged" in den folgenden Fällen übersetzt werden? <br> <tt>"verschmolzen" oder "verflochten"</tt> <br> der Anwendung selber transparent" tönt auch nicht sehr gut}}

Das Kconfig Objekt, das wir auf Zeile 2 erstellen ist ein gewöhnliches Konfigurationsobjekt. Wir können Werte aus ihm lesen, neue Einträge schreiben und nach verschiedenen Eigenschaften des Objekts fragen. Dieses Objekt wird aus der Konfigurations-Ressource geladen, wie es durch {{class|KStandardDirs}} bestimmt wird, das heisst, dass jede Instanz des <tt>myapprc</tt>-Objekts in jedem der Ordner in der Konfigurations-Ressourcen-Hierarchie verschmolzen werden um die Werte zu erzeugen, die in diesem Objekt gesehen werden. So werden Systemweite und
pro-Benutzer/Gruppen Profile erstellt und unterstützt. Das alles geschieht der Anwendung selber transparent.

{{tip| Für mehr Informationen, wie das Verschmelzen funktioniert, siehe diesen Artikel über die [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Dateisystem Hierarchie]].}}

{{note (de)|Ist das so gemeint mit "expects an INI style file"<br> <tt> On line 6 we open a specific local file, this case /etc/kderc. This performs no merging of values and expects an INI style file.</tt>}}

Auf Zeile 6 öffnen wir eine bestimmte Lokale Datei, in diesem Fall {{path|/etc/kderc}}. Das führt kein verschmelzen von Werten aus und erwartet eine Datei im INI Format.

Zeile 9 erzeugt ein Konfigurationsobjekt, dass nicht mit dem globalen <tt>kdeglobals</tt>-Konfigurationsobjekt verflochten ist, während das Konfigurationsobjekt auf Zeile 12 zusätzlich mit keinem der Dateien in der <tt>$KDEDIRS</tt>-Hierarchie verflochten ist. Das kann die Leistung spürbar verbessern, falls man einfach nur Werte aus einer einfachen Konfuguration liest und globale Werte keine Rolle spielen.

Zeile 15 erzeugt ein Konfigurationsobjekt unter Benutzung des {{class|KComponentData}}-Objekts das zu einem Plugin oder einer anderen Komponente gehört. Das Plugin kann verschiedene Ordner aufweisen, die in seinen {{class|KStandardDirs}} definiert sind und das ist eine Möglichkeit sich zu versichern, dass {{class|KConfig}} das respektiert.

Und schliesslich auf Zeile 18 erzeugen wir ein Konfigurationsobjekt, das nicht in der <tt>config</tt>-Ressource sondern in der <tt>data</tt>-Ressource existiert. Man kann kann auf diese Weise jede Ressource verwenden, von denen {{class|KStandardDirs}} Kenntnis hat, auch solche die während der Laufzeit hinzugefügt werden.

=== Spezielle Konfigurationsobjekte ===

Jede Anwendung hat sein eigenes Konfigurationsobjekt das den Namen benutzt, der von {{class|KAboutData}} bereitgestellt wird mit angehängtem "rc". Also hätte eine Anwendung mit dem Namen "myapp" das Standard-Konfigurationsobjekt "myapprc". Dieses Konfigurationsobjekt kann auf diese Weise aufgerufen werden:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// beachten sie, dass dies eigentlich ein KSharedConfig ist
// mehr über diese Klasse siehe weiter unten
KConfig* config = KGlobal::config();
}
</code>

Auf das Standard-Konfigurationsobjekt für die Anwendung wird zugegriffen, wenn kein Name definiert wurde, als das {{class|KConfig}}-Objekt erzeugt wurde. Also könnten wir stattdessen auch das tun:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

Zusätzlich könnte jede Komponente sein eigenes Konfigurationsobjekt haben. Auf dieses wird normalerweise durch die <tt>componentData()</tt> des Plugins zugegriffen, anstatt durch die <tt>{{class|KGlobal}}::mainComponent()</tt>.

Und schliesslich gibt es noch ein globales Konfigurationsobjekt, <tt>kdeglobals</tt>, das von jeder Anwendung verwendet wird. Es enthält Informationen wie die Standard-Tatenkombinationen für verschiedene Aktionen. Es wird in das Konfigurationsobjekt "gemischt" wenn der <tt>KConfig::IncludeGlobals</tt> Bitschalter dem {{class|KConfig}} Konstruktor übergeben wird, was standardmässig der Fall ist.

=== Allgemein nützliche Methoden ===

Um den momentanen Zustand des Konfigurationsobjektes zu speichern, rufen wir die <tt>sync()</tt>-Methode auf. Diese Methode wird also aufgerufen, wenn ein Objekt zerstört wird. Falls keine Änderungen gemacht wurden, oder die Ressource weist sich als nicht beschreibbar aus (Wenn der Benutzer zum Beispiel nicht genug Rechte hat, um die Datei zu bearbeiten), dann wird keine Beschäftigung der Festplatte hervorgerufen. <tt>sync()</tt> verschmilzt Änderungen die gleichzeitig von anderen Prozessen ausgeführt werden - lokale Änderungen haben aber trotzdem Vorrang.

Wenn wir sicher gehen wollen, dass wir die aktuellsten Werte von der Festplatte haben, dann rufen wir <tt>reparseConfiguration()</tt> auf, welches <tt>sync()</tt> aufruft und dann die Daten von der Festplatte aktualisiert.

Falls wir verhindern müssen, dass das Konfigurationsobjekt bereits gemachte Änderungen nicht auf die Festplatte speichert, müssen wir <tt>markAsClean()</tt> aufrufen. Ein besonderer Anwendungsfall ist es, die Konfiguration zum Festplatten-Zustand zurückzusetzen indem man <tt>markAsClean()</tt> gefolgt von <tt>reparseConfiguration()</tt> aufruft.

Alle Gruppen in einem Konfigurationsobjekt aufzurufen ist so einfach wie hier in diesem Code-Abschnitt <tt>groupList()</tt> aufzurufen.

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

Die {{class|KSharedConfig}} Klasse ist eine Referenz-gezählte Version von {{class|KConfig}}. Darum stellt es eine Möglichkeit bereit, das selbe Konfigurationsobjekt von unterschiedlichen Orten zu referenzieren ohne zusätzlich die Objekte trennen zu müssen oder sich um die Synchronisation des Schreibvorgangs zu kümmern, selbst wenn das Konfigurationsobjekt von verschiedenen Code-Pfaden aktualisiert wird.

Auf ein {{class|KSharedConfig}}-Objekt zuzugreifen ist so einfach wie das hier:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<tt>openConfig()</tt> nimmt die selben Parameter wie {{class|KConfig}}'s Konstruktoren, was es einem ermöglicht zu definieren, welche Konfigurationsdatei zu öffnen und Markierungen das Verschmelzen von nicht-<tt>config</tt>-Ressourcen zu kontrollieren.

Es wird grundsätzlich empfohlen {{class|KSharedConfig}} anstatt {{class|KConfig}} selbst zu benutzen, und auch das Objekt, das von {{class|KComponentData}} zurückgegeben wird ist in der Tat ein {{class|KSharedConfig}}-Objekt.

== KConfigGroup ==

Nun da wir ein Konfigurationsobjekt haben, ist der nächste Schritt es tatsächlich zu nutzen. Das erste, das wir tun müssen, ist zu bestimmen, auf welche Gruppe von Schlüssel-/Wertepaare wir in unserem Objekt zugreifen wollen. Wir tun das, indem wir ein KConfigGroup-Objekt erstellen.

<code cppqt n>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ...oder so ähnlich...
</code>

Man kann{{class|KConfigGroup}} {{class|KConfig}}- oder {{class|KSharedConfig}}-Objekte übergeben.

Konfigurationsgruppen können ebenfalls verschachtelt werden.

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Lesen von Einträgen ==

Wenn man erst einmal ein {{class|KConfigGroup}}-Objekt erstellt hat, ist das Lesen von Einträgen ziemlich einfach:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

Wie man hier oben sehen kann, kann man Lesevorgänge von verschiedenen {{class|KConfigGroup}}-Objekten, die auf dem selben {{class|KConfig}}-Objekt erstellt wurden, problemlos mischen. Die Lese-Methoden nehmen den Schlüssel, der Gross- und Kleinschreibung unterscheidet, als erstes Argument und den Standardwert als zweites Argument. Dieses Argument bestimmt auch welche Art von Daten, also z.B. eine Farbe in Zeile 3, erwartet wird und auch die Art von Objekt, die zurückgegeben werden soll.Das zurückgegebene Objekt wird in eine {{qt|QVariant}} gepackt um diese Hexerei zu ermöglichen.

Es gibt eine Anzahl von speziellen Methoden, zum Beispiel <tt>readPathEntry</tt>, das einen Datei-Systempfad zurückgibt. Es ist entscheidend, dass man <tt>readPathEntry</tt> benutzt, wenn man nach einem Pfad fragt, das es Funktionen wie Erreichbarkeits-Profile ermöglicht richtig zu funktionieren.

Wenn kein solcher Schlüssel im Konfigurationsobjekt existiert, dann wird stattdessen der Standardwert zurückgegeben. Falls es eine lokalisierte (d.h. in eine andere Sprache übersetzte) Version für den Schlüssel gibt, die der eingestellten Sprache entspricht, dann wird diese zurückgegeben.

== Schreiben neuer Einträge ==

Neue Werte zu definieren ist ähnlich einfach:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

Beachten sie die Benutzung von <tt>writePathEntry</tt> und wie die Art von Objekt, das wir benutzen, wie zum Beispiel {{qt|QColor}} auf Zeile 3, bestimmt, wie die Daten angeordnet werden. Zusätzlich, wenn wir mit den Einträgen fertig sind, muss <tt>sync()</tt> auf das Konfigurationsobjekt ausgeführt werden, um es auf die Festplatte zu speichern. Man kann auch einfach warten, bis das Objekt zerstört wird, was falls nötig automatisch einen <tt>sync()</tt> auslöst.

== KDesktopFile: Ein besonderer Fall ==

Wann ist eine Konfigurationsdatei keine Konfigurationsdatei? Wenn es eine [http://freedesktop.org/wiki/Standards_2fdesktop_2dentry_2dspec Desktop-Datei] ist. Diese Dateien, die im Grunde genommen Konfigurationsdateien sind, werden benutzt um Einträge für Anwendungsmenüs, Dateitypen, Plugins und verschiedene Services.

Wenn auf eine .desktop Datei zugegriffen wird, sollte man stattdessen die {{class|KDesktopFile}}-Klasse verwenden, die, während eine {{class|KConfig}}-Klasse über alle oben genannten Ressourcen verfügt, über eine Anzahl von Methoden verfügt, um das Zugreifen auf Standard-Attribute dieser Dateien konsistent und zuverlässig zu machen.

== Kiosk: Abriegelung und Benutzer-/Gruppenprofile ==

KConfig stellt eine Reihe von leistungsstarken Abriegelungs- und Konfigurations-Definitionen bereit, insgesamt als "Kiosk" bekannt, worauf viele System-Administratoren und -Integratoren basieren. Während ein Grossteil dieses Systems der Anwendung transparent bereitgestellt wird, ist es möglich dass man den Schreib/Lese-Status eines Konfigurationsobjekts prüfen will.

Einträge in Konfigurationsobjekten die mithilfe von Kiosk abgeriegelt sind, werden "unveränderlich" genannt. Eine Anwendung kann nach der Unveränderlichkeit von ganzen Konfigurationsobjekten, Gruppen oder Schlüsseln, wie in diesem Beispiel gezeigt, fragen:

<code cppqt n>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "Konfigurationsobjekt ist unveränderlich";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "Die Gruppe 'General' ist unveränderlich";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "Der URL Eintrag in der Gruppe 'General' ist unveränderlich";
}
</code>

Das kann in gewissen Situationen, wo eine Aktion ausgeführt werden soll, falls ein Objekt unveränderlich ist.

== KConfig XT ==

Es gibt einen Weg, gewisse Anwendungsfälle von KConfig einfacher, schneller und zuverlässiger zu machen: KConfig XT. Im Bestimmten kann KConfig XT bei Hauptanwendungs- oder Plug-In-Konfigurationsobjekten und bei Konfigurationsdialogen und anderen Benutzeroberflächen mit diesen Werten sehr hilfreich sein. Es dokumentiert gleichzeitig auch alle verfügbaren Konfigurations-Optionen, was alle System-Administratoren und -Integratoren, die KDE benutzen so viel glücklicher macht.

[[../Using_KConfig_XT_de|Die nächste Anleitung handelt über KConfig XT und wie es zu benutzen.]]

Development/Tutorials/KConfig (de)

2008-02-07T13:02:20Z

Rememberme: /* Kiosk: Lockdown and User/Group Profiles */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT|Benutzen von KConfig XT]]|

reading=Keine

}}

{{improve (de)}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer- und Gruppenprofile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

{{note (de)| deserialization entgliedern? <br> <tt> "do not have to perform serialization and deserialization of objects themselves" </tt>}}

Anwendungen selbst müssen darum normalerweise Objekte nicht selber gliedern und entgliedern.

== Die KConfig Klasse ==

Das {{class|KConfig}}-Objekt wird benutzt um ein bestehendes Konfigurationsobjekt anzusteuern. Es gibt eine Reihe von Möglichkeiten ein Konfigurationsobjekt zu erstellen.

<code cppqt n>
// ein einfaches, altes lesen/schreiben Konfigurationsobjekt
KConfig config("myapprc");

// eine bestimmte Datei im Dateisystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// nicht mit globalen Werten verflochten
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// nicht mit globalen Werten orde der $KDEDIRS Hierarchie verflochten
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// Komponenten-spezifische Konfiguration, in diesem Fall ein Plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// Ausserhalb der normalen Konfigurations-Ressource
KConfig dataResource( "data", "myapp/somefile" );
</code>

{{note (de)|wie soll "merged" in den folgenden Fällen übersetzt werden? <br> <tt>"verschmolzen" oder "verflochten"</tt> <br> der Anwendung selber transparent" tönt auch nicht sehr gut}}

Das Kconfig Objekt, das wir auf Zeile 2 erstellen ist ein gewöhnliches Konfigurationsobjekt. Wir können Werte aus ihm lesen, neue Einträge schreiben und nach verschiedenen Eigenschaften des Objekts fragen. Dieses Objekt wird aus der Konfigurations-Ressource geladen, wie es durch {{class|KStandardDirs}} bestimmt wird, das heisst, dass jede Instanz des <tt>myapprc</tt>-Objekts in jedem der Ordner in der Konfigurations-Ressourcen-Hierarchie verschmolzen werden um die Werte zu erzeugen, die in diesem Objekt gesehen werden. So werden Systemweite und
pro-Benutzer/Gruppen Profile erstellt und unterstützt. Das alles geschieht der Anwendung selber transparent.

{{tip| Für mehr Informationen, wie das Verschmelzen funktioniert, siehe diesen Artikel über die [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Dateisystem Hierarchie]].}}

{{note (de)|Ist das so gemeint mit "expects an INI style file"<br> <tt> On line 6 we open a specific local file, this case /etc/kderc. This performs no merging of values and expects an INI style file.</tt>}}

Auf Zeile 6 öffnen wir eine bestimmte Lokale Datei, in diesem Fall {{path|/etc/kderc}}. Das führt kein verschmelzen von Werten aus und erwartet eine Datei im INI Format.

Zeile 9 erzeugt ein Konfigurationsobjekt, dass nicht mit dem globalen <tt>kdeglobals</tt>-Konfigurationsobjekt verflochten ist, während das Konfigurationsobjekt auf Zeile 12 zusätzlich mit keinem der Dateien in der <tt>$KDEDIRS</tt>-Hierarchie verflochten ist. Das kann die Leistung spürbar verbessern, falls man einfach nur Werte aus einer einfachen Konfuguration liest und globale Werte keine Rolle spielen.

Zeile 15 erzeugt ein Konfigurationsobjekt unter Benutzung des {{class|KComponentData}}-Objekts das zu einem Plugin oder einer anderen Komponente gehört. Das Plugin kann verschiedene Ordner aufweisen, die in seinen {{class|KStandardDirs}} definiert sind und das ist eine Möglichkeit sich zu versichern, dass {{class|KConfig}} das respektiert.

Und schliesslich auf Zeile 18 erzeugen wir ein Konfigurationsobjekt, das nicht in der <tt>config</tt>-Ressource sondern in der <tt>data</tt>-Ressource existiert. Man kann kann auf diese Weise jede Ressource verwenden, von denen {{class|KStandardDirs}} Kenntnis hat, auch solche die während der Laufzeit hinzugefügt werden.

=== Spezielle Konfigurationsobjekte ===

Jede Anwendung hat sein eigenes Konfigurationsobjekt das den Namen benutzt, der von {{class|KAboutData}} bereitgestellt wird mit angehängtem "rc". Also hätte eine Anwendung mit dem Namen "myapp" das Standard-Konfigurationsobjekt "myapprc". Dieses Konfigurationsobjekt kann auf diese Weise aufgerufen werden:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// beachten sie, dass dies eigentlich ein KSharedConfig ist
// mehr über diese Klasse siehe weiter unten
KConfig* config = KGlobal::config();
}
</code>

Auf das Standard-Konfigurationsobjekt für die Anwendung wird zugegriffen, wenn kein Name definiert wurde, als das {{class|KConfig}}-Objekt erzeugt wurde. Also könnten wir stattdessen auch das tun:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

Zusätzlich könnte jede Komponente sein eigenes Konfigurationsobjekt haben. Auf dieses wird normalerweise durch die <tt>componentData()</tt> des Plugins zugegriffen, anstatt durch die <tt>{{class|KGlobal}}::mainComponent()</tt>.

Und schliesslich gibt es noch ein globales Konfigurationsobjekt, <tt>kdeglobals</tt>, das von jeder Anwendung verwendet wird. Es enthält Informationen wie die Standard-Tatenkombinationen für verschiedene Aktionen. Es wird in das Konfigurationsobjekt "gemischt" wenn der <tt>KConfig::IncludeGlobals</tt> Bitschalter dem {{class|KConfig}} Konstruktor übergeben wird, was standardmässig der Fall ist.

=== Allgemein nützliche Methoden ===

Um den momentanen Zustand des Konfigurationsobjektes zu speichern, rufen wir die <tt>sync()</tt>-Methode auf. Diese Methode wird also aufgerufen, wenn ein Objekt zerstört wird. Falls keine Änderungen gemacht wurden, oder die Ressource weist sich als nicht beschreibbar aus (Wenn der Benutzer zum Beispiel nicht genug Rechte hat, um die Datei zu bearbeiten), dann wird keine Beschäftigung der Festplatte hervorgerufen. <tt>sync()</tt> verschmilzt Änderungen die gleichzeitig von anderen Prozessen ausgeführt werden - lokale Änderungen haben aber trotzdem Vorrang.

Wenn wir sicher gehen wollen, dass wir die aktuellsten Werte von der Festplatte haben, dann rufen wir <tt>reparseConfiguration()</tt> auf, welches <tt>sync()</tt> aufruft und dann die Daten von der Festplatte aktualisiert.

Falls wir verhindern müssen, dass das Konfigurationsobjekt bereits gemachte Änderungen nicht auf die Festplatte speichert, müssen wir <tt>markAsClean()</tt> aufrufen. Ein besonderer Anwendungsfall ist es, die Konfiguration zum Festplatten-Zustand zurückzusetzen indem man <tt>markAsClean()</tt> gefolgt von <tt>reparseConfiguration()</tt> aufruft.

Alle Gruppen in einem Konfigurationsobjekt aufzurufen ist so einfach wie hier in diesem Code-Abschnitt <tt>groupList()</tt> aufzurufen.

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

Die {{class|KSharedConfig}} Klasse ist eine Referenz-gezählte Version von {{class|KConfig}}. Darum stellt es eine Möglichkeit bereit, das selbe Konfigurationsobjekt von unterschiedlichen Orten zu referenzieren ohne zusätzlich die Objekte trennen zu müssen oder sich um die Synchronisation des Schreibvorgangs zu kümmern, selbst wenn das Konfigurationsobjekt von verschiedenen Code-Pfaden aktualisiert wird.

Auf ein {{class|KSharedConfig}}-Objekt zuzugreifen ist so einfach wie das hier:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<tt>openConfig()</tt> nimmt die selben Parameter wie {{class|KConfig}}'s Konstruktoren, was es einem ermöglicht zu definieren, welche Konfigurationsdatei zu öffnen und Markierungen das Verschmelzen von nicht-<tt>config</tt>-Ressourcen zu kontrollieren.

Es wird grundsätzlich empfohlen {{class|KSharedConfig}} anstatt {{class|KConfig}} selbst zu benutzen, und auch das Objekt, das von {{class|KComponentData}} zurückgegeben wird ist in der Tat ein {{class|KSharedConfig}}-Objekt.

== KConfigGroup ==

Nun da wir ein Konfigurationsobjekt haben, ist der nächste Schritt es tatsächlich zu nutzen. Das erste, das wir tun müssen, ist zu bestimmen, auf welche Gruppe von Schlüssel-/Wertepaare wir in unserem Objekt zugreifen wollen. Wir tun das, indem wir ein KConfigGroup-Objekt erstellen.

<code cppqt n>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ...oder so ähnlich...
</code>

Man kann{{class|KConfigGroup}} {{class|KConfig}}- oder {{class|KSharedConfig}}-Objekte übergeben.

Konfigurationsgruppen können ebenfalls verschachtelt werden.

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Lesen von Einträgen ==

Wenn man erst einmal ein {{class|KConfigGroup}}-Objekt erstellt hat, ist das Lesen von Einträgen ziemlich einfach:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

Wie man hier oben sehen kann, kann man Lesevorgänge von verschiedenen {{class|KConfigGroup}}-Objekten, die auf dem selben {{class|KConfig}}-Objekt erstellt wurden, problemlos mischen. Die Lese-Methoden nehmen den Schlüssel, der Gross- und Kleinschreibung unterscheidet, als erstes Argument und den Standardwert als zweites Argument. Dieses Argument bestimmt auch welche Art von Daten, also z.B. eine Farbe in Zeile 3, erwartet wird und auch die Art von Objekt, die zurückgegeben werden soll.Das zurückgegebene Objekt wird in eine {{qt|QVariant}} gepackt um diese Hexerei zu ermöglichen.

Es gibt eine Anzahl von speziellen Methoden, zum Beispiel <tt>readPathEntry</tt>, das einen Datei-Systempfad zurückgibt. Es ist entscheidend, dass man <tt>readPathEntry</tt> benutzt, wenn man nach einem Pfad fragt, das es Funktionen wie Erreichbarkeits-Profile ermöglicht richtig zu funktionieren.

Wenn kein solcher Schlüssel im Konfigurationsobjekt existiert, dann wird stattdessen der Standardwert zurückgegeben. Falls es eine lokalisierte (d.h. in eine andere Sprache übersetzte) Version für den Schlüssel gibt, die der eingestellten Sprache entspricht, dann wird diese zurückgegeben.

== Schreiben neuer Einträge ==

Neue Werte zu definieren ist ähnlich einfach:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

Beachten sie die Benutzung von <tt>writePathEntry</tt> und wie die Art von Objekt, das wir benutzen, wie zum Beispiel {{qt|QColor}} auf Zeile 3, bestimmt, wie die Daten angeordnet werden. Zusätzlich, wenn wir mit den Einträgen fertig sind, muss <tt>sync()</tt> auf das Konfigurationsobjekt ausgeführt werden, um es auf die Festplatte zu speichern. Man kann auch einfach warten, bis das Objekt zerstört wird, was falls nötig automatisch einen <tt>sync()</tt> auslöst.

== KDesktopFile: Ein besonderer Fall ==

Wann ist eine Konfigurationsdatei keine Konfigurationsdatei? Wenn es eine [http://freedesktop.org/wiki/Standards_2fdesktop_2dentry_2dspec Desktop-Datei] ist. Diese Dateien, die im Grunde genommen Konfigurationsdateien sind, werden benutzt um Einträge für Anwendungsmenüs, Dateitypen, Plugins und verschiedene Services.

Wenn auf eine .desktop Datei zugegriffen wird, sollte man stattdessen die {{class|KDesktopFile}}-Klasse verwenden, die, während eine {{class|KConfig}}-Klasse über alle oben genannten Ressourcen verfügt, über eine Anzahl von Methoden verfügt, um das Zugreifen auf Standard-Attribute dieser Dateien konsistent und zuverlässig zu machen.

== Kiosk: Abriegelung und Benutzer-/Gruppenprofile ==

KConfig stellt eine Reihe von leistungsstarken Abriegelungs- und Konfigurations-Definitionen bereit, insgesamt als "Kiosk" bekannt, worauf viele System-Administratoren und -Integratoren basieren. Während ein Grossteil dieses Systems der Anwendung transparent bereitgestellt wird, ist es möglich dass man den Schreib/Lese-Status eines Konfigurationsobjekts prüfen will.

Einträge in Konfigurationsobjekten die mithilfe von Kiosk abgeriegelt sind, werden "unveränderlich" genannt. Eine Anwendung kann nach der Unveränderlichkeit von ganzen Konfigurationsobjekten, Gruppen oder Schlüsseln, wie in diesem Beispiel gezeigt, fragen:

<code cppqt n>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "Konfigurationsobjekt ist unveränderlich";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "Die Gruppe 'General' ist unveränderlich";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "Der URL Eintrag in der Gruppe 'General' ist unveränderlich";
}
</code>

Das kann in gewissen Situationen, wo eine Aktion ausgeführt werden soll, falls ein Objekt unveränderlich ist.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/Saving and loading (de)

2008-01-21T21:19:39Z

Rememberme:

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Saving_and_loading}}

{{TutorialBrowser (de)|

series=Anleitung für Anfänger|

name=Laden und Speichern von Dateien|

pre=[[Development/Tutorials/Using_KActions (de)|Anleitung 3 - KActions benutzen]]|

next=[[Development/Tutorials/KCmdLineArgs (de)|Anleitung 5 - KCmdLineArgs benutzen]]|

reading=KIO::{{class|NetAccess}} {{qt|QFile}}
}}

==Zusammenfassung==

In diesem Kapitel werden sie lernen, wie man grundsätzliche Datei-Aktionen wie Laden und Speichern mithilfe der KIO Bibliothek einbindet.

KDE stellt eine Anzahl von Klassen bereit um das Arbeiten mit Dateien für die Entwickler deutlich zu vereinfachen. Die KIO Bibliothek ermöglicht es Dateien auf einfache Weise über Netzwerk-transparente Protokolle anzusteuern und stellt auch Standard Dateidialoge bereit.

[[image:introtokdetutorial4.png|frame|center]]

== Der Code ==

===main.cpp===
<code cppqt n>
#include <KApplication>
#include <KAboutData>
#include <KCmdLineArgs>

#include "mainwindow.h"

int main (int argc, char *argv[])
{
KAboutData aboutData( "tutorial4", "tutorial4",
ki18n("Tutorial 4"), "1.0",
ki18n("A simple text area which can load and save."),
KAboutData::License_GPL,
ki18n("Copyright (c) 2007 Developer") );
KCmdLineArgs::init( argc, argv, &aboutData );
KApplication app;

MainWindow* window = new MainWindow();
window->show();
return app.exec();
}
</code>
<tt>main.cpp</tt> hat sich seit der dritten Anleitung nicht verändert, ausser das jeder Bezug zu 'tutorial 3' zu 'tutorial 4' geändert wurde.

===mainwindow.h===
<code cppqt n>
#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include <KXmlGuiWindow>
#include <KTextEdit>

class MainWindow : public KXmlGuiWindow
{
Q_OBJECT //neu seit Anleitung 3

public:
MainWindow(QWidget *parent=0);

private:
KTextEdit* textArea;
void setupActions();
QString fileName; //neu

private slots: //neu
void newFile(); //neu
void openFile(); //neu
void saveFile(); //neu
void saveFileAs(); //neu
void saveFileAs(const QString &outputFileName); //neu
};

#endif
</code>
Da wir unserem Programm die Fähigkeit geben wollen, Dateien zu laden und zu speichern müssen wir Funktionen hinzufügen, die diese Arbeit erledigen werden. Da die Funktionen durch Qt's [http://doc.trolltech.com/latest/signalsandslots.html signal/slot]-Mechanismus aufgerufen werden, müssen wir definieren, dass diese Funktionen Slots sind, wie wir dies auf Zeile 19 machen. Da wir Slots in diesem Header-File benutzen, müssen wir auch das [http://doc.trolltech.com/latest/qobject.html#Q_OBJECT <tt>Q_OBJECT</tt>] Makro hinzufügen.

Wir werden auch den Dateinamen der momentan geöffneten Datei verfügbar haben wollen, also definieren wir einen <tt>{{qt|QString}} fileName</tt>.

===mainwindow.cpp===
<code cppqt n>
#include "mainwindow.h"

#include <KApplication>
#include <KAction>
#include <KLocale>
#include <KActionCollection>
#include <KStandardAction>
#include <KFileDialog> //neu
#include <KMessageBox> //neu
#include <KIO/NetAccess> //neu
#include <KSaveFile> //neu
#include <QTextStream> //neu

MainWindow::MainWindow(QWidget *parent)
: KXmlGuiWindow(parent),
fileName(QString()) //neu
{
textArea = new KTextEdit;
setCentralWidget(textArea);

setupActions();
}

void MainWindow::setupActions()
{
KAction* clearAction = new KAction(this);
clearAction->setText(i18n("Clear"));
clearAction->setIcon(KIcon("document-new"));
clearAction->setShortcut(Qt::CTRL + Qt::Key_W);
actionCollection()->addAction("clear", clearAction);
connect(clearAction, SIGNAL(triggered(bool)),
textArea, SLOT(clear()));

KStandardAction::quit(kapp, SLOT(quit()),
actionCollection());

KStandardAction::open(this, SLOT(openFile()),
actionCollection()); //neu

KStandardAction::save(this, SLOT(saveFile()),
actionCollection()); //neu

KStandardAction::saveAs(this, SLOT(saveFileAs()),
actionCollection()); //neu

KStandardAction::openNew(this, SLOT(newFile()),
actionCollection()); //neu

setupGUI();
}

//Neu ab hier

void MainWindow::newFile()
{
fileName.clear();
textArea->clear();
}

void MainWindow::saveFileAs(const QString &outputFileName)
{
KSaveFile file(outputFileName);
file.open();

QByteArray outputByteArray;
outputByteArray.append(textArea->toPlainText());
file.write(outputByteArray);
file.finalize();
file.close();

fileName = outputFileName;
}

void MainWindow::saveFileAs()
{
saveFileAs(KFileDialog::getSaveFileName());
}

void MainWindow::saveFile()
{
if(!fileName.isEmpty())
{
saveFileAs(fileName);
}
else
{
saveFileAs();
}
}

void MainWindow::openFile()
{
QString fileNameFromDialog = KFileDialog::getOpenFileName();

QString tmpFile;
if(KIO::NetAccess::download(fileNameFromDialog, tmpFile,
this))
{
QFile file(tmpFile);
file.open(QIODevice::ReadOnly);
textArea->setPlainText(QTextStream(&file).readAll());
fileName = fileNameFromDialog;

KIO::NetAccess::removeTempFile(tmpFile);
}
else
{
KMessageBox::error(this,
KIO::NetAccess::lastErrorString());
}
}
</code>

===tutorial4ui.rc===
<code xml n>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kpartgui SYSTEM "kpartgui.dtd">
<gui name="tutorial4" version="1">
<ToolBar name="mainToolBar" >
<text>Main Toolbar</text>
<Action name="clear" />
</ToolBar>
<MenuBar>
<Menu name="file" >
<Action name="clear" />
</Menu>
</MenuBar>
</gui>
</code>
Dies ist identisch mit <tt>tutorial3ui.rc</tt> aus Anleitung 3 ausser dass <tt>name</tt> zu 'tutorial4' geändert wurde. Wir müssen keine Informationen über irgendeine der <tt>KStandardActions</tt> hinzuzufügen da die Platzierung dieser Aktionen automatisch durch KDE erfolgt.

==Erklärung==

Nun kommen wir zum Code, der das Laden und Speichern erledigen wird. Das wird alles in <tt>mainwindow.cpp</tt> passieren.

Als erstes fügen wir
<code cppqt>
fileName(QString())
</code>
der <tt>MainWindow</tt> Konstruktor-Liste auf Zeile 16 hinzu. Das stellt sicher, dass <tt>fileName</tt> von Anfang an leer ist.

===Hinzufügen der Aktionen===

Als nächstes werden wir das äusserliche Interface für den Benutzer bereitstellen, so dass er der Anwendung mitteilen kann zu laden und zu speichern. Wie mit der <tt>quit</tt> Aktion in Anleitung 3 werden wir <tt>KStandardActions</tt> verwenden. Auf Zeilen 37 bis 47 werden wir die Aktionen auf die selbe Weise hinzufügen wie für die <tt>quit</tt> Aktion. Für jedes einzelne werden wir es mit dem richtigen Slot verbinden den wir in der Header Datei definiert haben.

===Erstellen eines neuen Dokuments===

Die erste Funktion die wir erstellen ist <tt>newFile()</tt>.

<code cppqt>
void MainWindow::newFile()
{
fileName.clear();
textArea->clear();
}
</code>
<tt>fileName.clear()</tt> setzt den <tt>fileName</tt> QString auf leer um zu zeigen, dass dieses Dokument noch keine Präsenz auf der Festplatte hat. <tt>textArea->clear()</tt> leert dann das zentrale Textfeld unter Verwendung der gleichen Funktion mit der wir die <tt>clear</tt> <tt>KAction</tt> in Anleitung 3 verbunden haben.

===Speichern einer Datei===

====saveFileAs(QString)====

Jetzt kommen wir zum ersten Datei-Handhabungs-Code. Wir werden eine Funktion einführen, die die Inhalte des Textfeldes in den Dateinamen, der als Parameter gegeben ist, speichert. KDE stellt die {{class|KSaveFile}} Klasse bereit, mit der man sicher Dateien speichern kann. Sie ist von Qt's {{qt|QFile}} abgeleitet.

Der Prototyp für unsere Funktion ist
<code cppqt>
void MainWindow::saveFileAs(const QString &outputFileName)
</code>
Wir erstellen dann unser <tt>KSaveFile</tt> Objekt und öffnen es mit
<code cppqt>
KSaveFile file(outputFileName);
file.open();
</code>

Nun da wir unsere Datei zum beschreiben haben, müssen wir den Text im Textfeld so formatieren, dass er in eine Datei geschrieben werden kann. Dazu erstellen wir ein {{qt|QByteArray}} und füllen es mit der einfachen Text Version von was auch immer im Textfeld ist:
<code cppqt>
QByteArray outputByteArray;
outputByteArray.append(textArea->toPlainText());
</code>
Jetzt haben wir unser <tt>QByteArray</tt>, das wir dazu verwenden mit <tt>KSaveFile::write()</tt> in die Datei zu schreiben. Wenn wir ein normales <tt>QFile</tt> benutzen würden, würde dies die Änderungen sofort ausführen. Falls aber während dem Schreiben ein Fehler passieren würde, würde die Datei beschädigt werden. Darum speichert <tt>KSaveFile</tt> zuerst in eine temporäre Datei und dann, wenn man <tt>KSaveFile::finalize()</tt> aufruft, werden die Änderungen in die eigentliche Datei geschrieben.
<code cppqt>
file.write(outputByteArray);
file.finalize();
file.close();
</code>
Schliesslich setzen wir <tt>MainWindows</tt>'s <tt>fileName</tt> Element dazu auf den Dateinamen zu zeigen, in den wir gerade geschrieben haben.
<code cppqt>
fileName = outputFileName;
</code>

====saveFileAs()====

Dies ist die Funktion mit der der <tt>saveAs</tt> Slot verbunden ist. Sie ruft einfach eine normale <tt>saveFileAs(QString)</tt> Funktion auf und übergibt den Dateinamen der von <tt>{{class|KFileDialog}}::[http://api.kde.org/4.0-api/kdelibs-apidocs/kio/html/classKFileDialog.html#8891356c249c5911e1ab15cc2739a89b getSaveFileName()]</tt> zurückgegeben wird.

<code cppqt>
void MainWindow::saveFileAs()
{
saveFileAs(KFileDialog::getSaveFileName());
}
</code>

Dies ist unser erster eigentlicher Gebrauch der KIO Bibliothek. {{class|KFileDialog}} Stellt eine Anzahl statischer Funktionen bereit um den gemeinsamen Dateidialog, der von allen KDE Anwendungen genutzt wird, anzuzeigen.
<tt>KFileDialog::getSaveFileName()</tt> aufzurufen wird einen Dialog anzeigen wo der Benutzer den Namen der Datei eingeben kann in die er speichern will oder einen neuen Namen angeben. Diese Funktion gibt den vollständigen Dateinamen zurück, den wir dann <tt>saveFileAs(QString)</tt> übergeben.

====saveFile()====

<code cppqt>
void MainWindow::saveFile()
{
if(!fileName.isEmpty())
{
saveFileAs(fileName);
}
else
{
saveFileAs();
}
}
</code>

Es gibt nichts neues oder aufregendes an dieser Funktion, nur die Logik zu entscheiden den Speicher-Dialog zu zeigen, oder nicht. Wenn <tt>fileName</tt> nicht leer ist, dann wird die Datei zu <tt>fileName</tt> gespeichert. Andernfalls wird der Dialog angezeigt damit der Benutzer einen Dateinamen bestimmen kann.

===Laden einer Datei===

Endlich werden wir in der Lage sein eine Datei zu öffnen. Der ganze Code hierfür ist in <tt>MainWindow::openFile()</tt> enthalten.

Als erstes müssen wir den Benutzer nach dem Namen der Datei fragen, die er öffnen möchte. Dazu benutzen wir eine weitere <tt>KFileDialog</tt> Funktion diesmal <tt>getOpenFileName()</tt>:

<code cppqt>
QString fileNameFromDialog = KFileDialog::getOpenFileName();
</code>

Dann nutzen wir die KIO Bibliothek um unsere Datei aufzurufen. Das ermöglicht es uns die Datei mit QFile zu öffnen, selbst wenn sie sich auf einem externen Speicherort befindet, wie auf einer FTP-Seite. Wir machen den folgenden Aufruf an die {{class|NetAccess}} <tt>download()</tt> Funktion:

<code cppqt>
KIO::NetAccess::download(fileNameFromDialog, tmpFile, this)
</code>

Diese Funktion speichert die Datei temporär auf der Festplatte. Das erste Argument ist der Name der Datei, die man öffnen möchte. Das zweite ist ein QString der, nachdem der Download abgeschlossen ist den Speicherort der temporären Datei enthalten wird. Es ist mit diesem <tt>tmpFile</tt>, mit dem wir von nun an arbeiten werden.

Die Funktion gibt <tt>true</tt> oder <tt>false</tt> zurück, je nachdem ob die Übertragung erfolgreich war oder nicht. Falls sie fehlgeschlagen ist, wird eine Fehlermeldung angezeigt:

<code cppqt>
KMessageBox::error(this, KIO::NetAccess::lastErrorString());
</code>

Ansonsten fahren wir fort, die Datei zu öffnen.

Wir erstellen ein QFile indem wir die temporäre Datei die durch <tt>NetAccess::download()</tt> erzeugt wurde ihrem Konstruktor übergeben und dann in schreibgeschütztem Modus öffnen:

<code cppqt>
QFile file(tmpFile);
file.open(QIODevice::ReadOnly);
</code>

Um den Inhalt der Datei anzuzeigen, müssen wir Gebrauch von einem {{class|QTextStream}} machen. Wir erstellen einen, indem wir den Inhalt unserer Datei seinem Konstruktor übergeben und dann QFile's <tt>readAll()</tt> Funktion aufrufen um den Text von der Datei zu erhalten. Dieser wird dann zu der <tt>setPlainText()</tt> Funktion unseres Textfelds übergeben:

<code cppqt>
textArea->setPlainText(QTextStream(&file).readAll());
</code>

Wir speichern dann den Pfad der Datei, die wir gerade geöffnet haben:

<code cppqt>
fileName = fileNameFromDialog;
</code>

Und schliesslich entfernen wir die temporäre Datei, die durch <tt>NetAccess::download()</tt> erstellt wurde:

<code cppqt>
KIO::NetAccess::removeTempFile(tmpFile);
</code>

==Erzeugen, Installieren und Ausführen==

===CMakeLists.txt===
<code ini n>
project(tutorial4)

find_package(KDE4 REQUIRED)
include_directories(${KDE4_INCLUDES})

set(tutorial4_SRCS
main.cpp
mainwindow.cpp
)

kde4_add_executable(tutorial4 ${tutorial4_SRCS})

target_link_libraries(tutorial4 ${KDE4_KDEUI_LIBS}
${KDE4_KIO_LIBS})

install(TARGETS tutorial4 DESTINATION ${BIN_INSTALL_DIR})
install(FILES tutorial4ui.rc
DESTINATION ${DATA_INSTALL_DIR}/tutorial4)
</code>
Da wir nun die KIO Bibliothek verwenden, müssen wir CMake mitteilen es einzubinden. Wir machen das indem wir <tt>${KDE4_KIO_LIBS}</tt> der <tt>target_link_libraries()</tt> Funktion übergeben.

Mit dieser Datei kann die Anleitung auf die selbe Weise erzeugt und ausgeführt werden wie in Anleitung 3. Für weitere Informationen, siehe [[Development/Tutorials/Using KActions (de)|Anleitung 3]].

mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=$HOME
make install
$HOME/bin/tutorial4

==Weiter geht's==
Jetzt können sie mit dem Kapitel [[Development/Tutorials/KCmdLineArgs (de)|KCmdLineArgs]] forfahren.

[[Category:C++]]

Development/Tutorials (de)

2008-01-21T21:18:17Z

Rememberme: /* Konfigurationen mit KConfig verwalten */

{{Template:I18n/Language Navigation Bar|Development/Tutorials}}

Tutorials sind der schnellste Weg um herauszufinden, was man mit KDE anstellen kann und wie man das macht. Es folgt eine Liste der verfügbaren Tutorials '''für KDE4'''. Tutorials und Anleitungen zu KDE3 und KDE2 finden Sie am Ende dieser Seite.

== Einführung in die KDE4 Programmierung ==
Sind Sie an der Entwicklung von Programmen für KDE 4 interesiert? Wenn ja sind Sie hier genau richtig. Diese Artikelserie richtet sich an alle, die noch nie mit KDE programmiert haben.
;[[Development/Tutorials/First program (de)|Hallo Welt!]]
:''Einführung in die Grundlagen der KDE Programmierung''

;[[Development/Tutorials/Using KXmlGuiWindow (de)|Erstellen eines Hauptfensters]]
:''Dieser Artikel erklärt, wie der wichtigste Teil eines grafischen Programmes erstellt wird: das Hauptfenster.''

;[[Development/Tutorials/Using KActions (de)|Die Verwendung von KActions]]
:''In diesem Artikel erfahren Sie, wie Aktionen und Werkzeugleisten (Toolbars) im Menü hinzugefügt werden können.''

;[[Development/Tutorials/Saving and loading (de)|Laden und Speichern von Dateien]]
:''Dieser Artikel führt die KIO Bibliothek ein und erklärt wie man Dateien laden und speichern kann.''

;[[Development/Tutorials/KCmdLineArgs (de)|Befehlszeilen Argumente (todo)]]
:''In diesem Artikel werden Sie lernen Ihrer Anwendung zu ermöglichen, Dateien über die Befehlszeile oder sogar unter Dolphin mit 'Öffnen mit' zu laden''

== Grundlagen ==
;[[Development/Tutorials/KDE4 Porting Guide (de)|Ihre Applikation nach KDE 4 portieren]]
:''Anleitungen Qt3/KDE3 Applikationen nach Qt4/KDE4 zu portieren''

;[[Development/Tutorials/CMake (de)|Einführung in CMake]]
:''Wie man CMake in KDE 4 benutzt''

;[[Development/Tutorials/Common Programming Mistakes (de)|Häufige Programmierfehler]]
:''Einige häufige Fehler die man während der Entwicklung von Qt und KDE Applikationen machen kann und wie man sie vermeidet.''

;[[Development/Tutorials/Using Qt Designer (de)|Den Qt Designer benutzen um Benutzerschnittstellen zu erzeugen]]
:''Wie man UI Dateien mit dem Designer erzeugt und wie man diese in einem KDE Programm integriert.''

== Testen und Fehler beheben ==

;[[Development/Tutorials/Debugging (de)|Debugging Ihrer Applikation]]
:''Tips, Tools und Techniken zum Debuggen von KDE Applikationen''

;[[Development/Tutorials/Unittests|Schreiben von Unit-Tests für Qt4 und KDE4 mit QTestLib]] ([http://developer.kde.org/documentation/tutorials/writingunittests/writingunittests.html Original link])
:''Tutorial von [mailto:bradh@frogmouth.net Brad Hards] das beschreibt, wie man Unit-Tests mit dem QTestLib Framework erstellt. Das Tutorial wird anhand eines Beispiels beschrieben und befindet sich zur Zeit noch in Entwicklung.''

;[[Development/Tutorials/Code_Checking|Halbautomatische Werge zur Erkennung von Programmierfehlern]]
:''Techniken um Fehler in KDE Code aufzuspüren''

== Konfigurationen mit KConfig verwalten ==
;[[Development/Tutorials/KConfig (de)|Einführung in KConfig]]
:''Eine Übersicht über die zu KConfig gehörenden Klassen und wie Sie diese in Ihre Anwendung einbinden können''

;[[Development/Tutorials/Using KConfig XT|Benutzung von KConfig XT]]
:''Tutorial über das effiziente Benutzen des KConfig XT Frameworks.''

;[[Development/Tutorials/Updating KConfig Files|Update von KConfig Dateien]]
:''Tutorial das beschreibt, wie man ein Update-Skript erstellt, dass Veränderungen am Format der Konfiguration Ihrer Anwendung mit den bereits vorgenommenen Einstellungen des Anwenders abgleicht.''

== Dienste: Applikationen und Plugins ==
;[[Development/Tutorials/Services/Introduction (de)|Einführung in das Dienst-Framework]]
:''Eine Einführung über das Dienst-Framework in KDE und was es dem Applikationsentwickler zur Verfügung stellen kann. Beschäftigt sich mit dem system configuration cache (SyCoCa), den benötigten Dateien und wie indizierte Informationen benutzt werden.

;[[Development/Tutorials/Services/Traders (de)|Dienste über Trader Queries finden]]
:''Wie man mit der Trader Query Syntax Dienste wie Plugins oder Mimetypes findet, die im SyCoCa zwischengespeichert wurden. ''

;[[Development/Tutorials/Services/Plugins|Erstellen und Laden von Plugins mit KService]]
:''Zeigt, wie man eigene Plugintypen definiert, installiere Plugins findet (einschließlich denen von anderen Herstellern) und wie man diese einfach und portabel läd, indem man KService benutzt.''

== Lokalisierung ==
;[[Development/Tutorials/Localization/Unicode (de)|Einführung in Unicode]]
:''Eine Einführung was Unicode ist und wie KDE Applikationen damit umgehen.''

; [[Development/Tutorials/Localization/i18n (de)|Beim Schreiben der Applikation an die Lokalisierung denken]]
:''Diese Anleitung beschäftigt sich damit, was Lokalisation ist, warum sie wichtig ist und wie man sicherstellt, dass die eigene Applikation bereit ist, lokalisiert zu werden. Jeder Applikationsentwickler sollte das lesen.''

; [[Development/Tutorials/Localization/i18n Mistakes (de)|Häufige Fehler vermeiden]]
:''Es gibt einige häufige Fehler, die es verhindern, dass eine Applikation angemesssen übersetzt werden kann. Diese Anleitung zeigt diese Fehler auf und zeigt, wie man sie vermeidet.''

; [[Development/Tutorials/Localization/Building KDE's l10n Module|Erstellen von KDE's Lokalisierungs Modul]]
:''Das Erstellen und Installieren der Sprachunterstützung mit KDE's Lokalisierungs-Modul (l10n) ist ratsam für alle, die an Anwendungen im KDE Haupt-Repository arbeiten. Hierdurch erreichen Sie, das Sie Ihre Anwendung in anderen Sprachen testen und somit auftauchende Probleme erkennen können. Dieses Tutorial bringt Ihnen genau das bei.''

; [[Development/Tutorials/Localization/i18n Build Systems|Einbeziehen von i18n in das Build System]]
:''Sobald Ihre Anwendung bereit dazu ist lokalisiert zu werden, ist es der nächste Schritt sicherzustellen, dass die Übersetzungsdateien automatisch erstellt und aktuell gehalten werden. Dieses Tutorial behandelt die nötigen Änderungen an den CMakeFile.txt Dateien sowie den Prozess um den resultierenden Nachrichten-Katalog mit Ihrer Applikation zu verteilen.''

; [[Development/Tutorials/Localization/i18n Challenges|i18n - Herausforderungen and Lösungen]]
:''Dieses Tutorial behandelt die Aufgaben und Fallstricke, die bei der Lokalisierung auftreten wie das Übersetzen von Handbüchern und anderen Daten die ausserhalb des Quellcodes auftreten, das Behandeln von nicht mehr gültigen .po-Dateien, das Umgehen mit Freezes, programmieren in anderen Sprachen als Englisch und Erstellung unabhängiger Releases oder das Verschieben von Anwendungen zwischen KDE Modulen.''

; [[Development/Tutorials/Localization/i18n_Semantics|Semantisches Markup für Nachrichten]]
:''Um eine konsistente und semantisch korrekte Darstellung von Nachrichten in Anwendungen sicherzustellen, können semantische Kommentare zu den Nachrichten, die übersetzt werden sollen, mit dem KUIT System hinzugefügt werden. Dieses Tutorial beschreibt die Funktionsweise dieses Systems.''

; [[Development/Tutorials/Localization/i18n Krazy|Automatisierte i18n Codeüberprüfung]]
:''Der Krazy Code-Checker durchsucht KDE's Code und meldet häufige i18n Fehler.''

; [[Development/Tutorials/Localization/Language Change (de)|Mit Sprachänderungen umgehen]]
:''Wie man seiner Applikation beibringt beim nächsten Start oder zur Laufzeit eine andere Sprache zu benutzen.''

== Dokumentation ==

;[[Development/Tutorials/API_Documentation|API Dokumentation]]
:''Dieses Tutorial erklärt, wie Sie Ihre APIs korrekt dokumentieren.''

;[[Development/Tutorials/Man_Pages|Man Seiten]]
:''Das Schreiben und Erstellen von Referenz-Handbüchern.''

== Anwendungsautomatisierung und Skripting ==

=== D-Bus ===
; [[Development/Tutorials/D-Bus/Introduction|Einführung in D-Bus]]
:''Eine unkomplizierte Einführung in die Kernkonzepte von D-Bus aus der Sicht eines Anwendungs-Programmierers. Dieses Tutorial behandet was D-Bus ist, und wie Sie es in Ihren Anwendungen einsetzen können.''

; [[Development/Tutorials/D-Bus/Accessing Interfaces|Zugriff auf D-Bus Schnittstellen]]
:''Eine Schrittweise Anleitung zum Aufruf von D-Bus-Methoden und zur Verbindung mit D-Bus-Signalen unter Verwendung von QtDBus.''

; [[Development/Tutorials/D-Bus/Intermediate_D-Bus|D-Bus für Fortgeschrittene]]
:''Tips zur Verwendung von QtDBus wenn sie mit problematischen Realwelt-Schnittstellen konfrontiert werden.''

; [[Development/Tutorials/D-Bus/Creating Interfaces|Erstellen von D-Bus Schnittstellen]]
:''Lernen Sie, wie sie Funktionalität Ihrer Applikationen bereit stellen, indem Sie eigene D-Bus Schnittstellen erstellen und benutzen. Beschreibt das Erstellen von XML-Beschreibungen, die Bereitstellung von Schnittstellen zur Laufzeit und das Aufsetzen des Build-Systems mit CMake.''

; [[Development/Tutorials/D-Bus/Autostart Services|D-Bus Autostart Dienste]]
:''Machen Sie mit diesem Tutorial aus Ihrer Anwendung einen D-Bus-Autostart-Dienst. Dieses Feature, dass auch als "D-Bus Dienst Aktivierung" bekannt ist, ermöglicht es, dass D-Bus Aufrufe zu Ihrer Applikation selbst dann funktionieren, wenn sie gerade nicht läuft indem sie den D-Bus-Daemon Ihre Applikation starten lassen, wenn deren Funktionen benötigt werden.''

; [[Development/Tutorials/Porting_to_D-Bus|Portieren von DCOP nach D-Bus]]
: ''Portieren Sie mit Hilfe dieser Anleitung Ihre Anwendungen von DCOP nach D-Bus.''

=== Konqueror ===
; [[Development/Tutorials/Creating Konqueror Service Menus|Erstellung von Konqueror Dienstmenus]]
:''Dieses Tutorial zeigt Ihnen wie Sie MIME-Typ-spezifische Aktionen in Konquerors Kontextmenu bereitstellen.''

=== Kross ===
; [[Development/Tutorials/Kross/Introduction|Einführung in Kross]]
:''Eine Einführung in das Kross Scripting Framework.''

; [[Development/Tutorials/Kross/Hello_World|Hallo Welt]]
:''Eine erste Anwendung mit funktionierendem Kross Code.''

; [[Development/Tutorials/Kross/Connecting_Signals_and_slots_in_Kross|Verbinden von Signalen und Slots in Kross]]
:''Einfache Demonstration, wie man Signale von Objekten mit Slots von Skripten verbindet.''

; [[Development/Tutorials/Kross/Scripts-as-Plugins|Skripte als Plugins mit Kross]]
:''Dieses Tutorial bietet eine schrittweise Einführung, wie Sie Skripte als Plugins in eine KDE Anwendung integrieren.''

=== KOffice ===
; [[Development/Tutorials/KOffice Overview|KOffice Übersicht]]
:''Dieses Dokument zeigt eine Übersicht über die verschiedenen KOffice Plugin Typen sowie ihren jeweiligen Nutzen und Stärken.'' Wenn KOffice Plugins neu für Sie sind, ist dieses Tutorial für Sie geeignet.

; [[Development/Tutorials/Write a Flake Plugin|Erstellen von KOffice Flake Plugins]]
:''Dieses Tutorial zeigt Ihnen wie Sie ein Plugin für KOffice Anwendungen erstellen das Ihnen mit Hilfe von Flake erlaubt, Inhalte in ODF-Dokumente einzubetten.''

; [[Development/Tutorials/KWord Scripting|KWord Scripting]]
:''Dieses Tutorial zeigt, wie man KWord mit Skriptsprachen wie Python, Ruby oder JavaScript über Kross anspricht.''

; [[Development/Tutorials/KSpread Scripting|KSpread Scripting]]
:''Dieses Tutorial zeigt, wie man KSpread mit Skriptsprachen wie Python, Ruby oder JavaScript über Kross anspricht.''

; [[Development/Tutorials/Krita Scripting|Krita Scripting]]
:''Dieses Tutorial zeigt, wie man Krita mit Skriptsprachen wie Python, Ruby oder JavaScript über Kross anspricht.''

=== SuperKaramba ===
; [[Development/Tutorials/SuperKaramba|SuperKaramba Tutorial]]
:''Dieses Tutorial bietet einen Einblick in SuperKaramba, Themen-Dateien und das Skripten mit Python, Ruby und JavaScript.

== Suche und Meta-Daten ==

=== Strigi ===

; [[Development/Tutorials/Writing file analyzers|Schreiben von Datei-Analysierern]]
:''Datei-Analysierer extrahieren Daten aus Dateien um Sie in Datei-Dialogen und Datei-Managern anzeigen können. Die Daten die auf diesem Weg erhalten werden, werden auch für die Suche nach Dateien verwendet. KDE4 erlaubt die Benutzung von mehreren Analysierern pro Dateityp. Dieses Tutorial beschreibt, wie Sie neue Analysierer schreiben können.''

=== Nepomuk ===

; [[Development/Tutorials/Metadata/KMetaData first steps|Erste Schritte mit Nepomuk]]
:''Nepomuk ist die KDE-Bibliothek die einfachen Zugriff auf Metadaten im [http://nepomuk-kde.semanticdesktop.org Nepomuk-KDE] System erlaubt. Lernen Sie, wie Ihre Applikation mit Hilfe von Nepomuk Metadaten bereitstellen und verwenden kann.''

== Ansprechen von Hardware (Solid) ==

;[[Development/Tutorials/Solid_Tutorials|Einführung in Solid]]
:''Eine Einführung in die Benutzung der Solid Hardware-Erkennung und -Verwendung in KDE Applikationen.''

;[[Development/Tutorials/Solid_Network_Tutorial|Zugriff auf Netzwerk-Informationen]]
:''Wie man Solid benutzt um Informationen über das Netzwerk herauszufinden''

== Multimedia (Phonon) ==

;[[Development/Tutorials/Phonon/Introduction|Phonon]]
:''Erste Schritte mit der Multimedia API''

:''Erstellung und Benutzung von Phonon und seinem GStreamer Backend unter Linux mit Qt 4.3.x''
::''Dieser Artikel gibt Ihnen eine kurze Anleitung wie Sie Phonon und sein GStreamer Backend unter GNU/Linux mit lediglich Qt 4.3.x beziehen, kompilieren und benutzen können. Gegen Ende beschreibt der Artikel zusätzlich, wie ein Entwickler Phonon benutzen kann um einfache Audio- und Video-Spieler zu erstellen. Sie können den Artikel [http://www.vcreatelogic.com/oss/docs/CompilingPhononOnLinux.pdf hier] lesen.
Sie können die editierbare OpenDocumentText Datei von [http://www.prashanthudupa.com/phonon/CompilingPhononOnLinux.odt hier]. herunterladen''

== Plasma ==

;[[Development/Tutorials/Plasma/GettingStarted|Erste Schritte mit Plasmoids]]
:''Erstellung Ihres ersten Plasma-Widgets oder Plasmoids in C++ mit einem SVG Hintergrund, einem Icon und etwas Text''

;[[Development/Tutorials/Plasma/DataEngines|Schreiben einer DataEngine]]
:''DataEngines bieten eine standardisierte Schnittstelle zur Darstellung von Daten aus verschiedenen Datenquellen. Lernen Sie was eine DataEngine ist und wie Sie selbst ein schreiben können.''

;[[Development/Tutorials/Plasma/UsingDataEngines|Benutzung von DataEngines in Plasmoids]]
:''Mit einer DataEngine ist es möglich, Daten auf einfache und standardisierte Art und Weise zu empfangen und darzustellen. Dieses Tutorial behandelt das Thema, wie man DataEngines zu diesem Zweck in Plasma einsetzt.''

;[[Development/Tutorials/Plasma/AbstractRunner|Erstellen von Runners]]
:''Runners sind Plugins die Aktions-basierte Suchfunkionalität im Plasma Ausführen-Dialog erlauben. Diese Plugins können von jeder Applikation verwendet werden, die libplasma einbindet.''

== Kate / Kwrite ==

;[[Development/Tutorials/Kate/KTextEditor Plugins|Erste Schritte mit KTextEditor Plugins]]
:''Erstellung Ihres ersten KTextEditor Plugins''

== Drucken ==

;[[Development/Tutorials/Printing Hello World|Hallo Welt]]
:''Einführung in das KDE Drucksystem''

;[[Development/Tutorials/Printing Print Dialog|Druckdialog]]
:''Benutzung des KDE Druckdialogs''

== Neue Dinge herunterladen ==
; [[Development/Tutorials/Introduction to Get Hot New Stuff|Einführung in "Neue Dinge herunterladen"]]
:''Eine Einführung in das Entwickler-freundliche Netzwerk-Update-System das KDE Applikationen erlaubt, neue Anwendungsdaten zur Laufzeit auf benutzerfreundliche Weise herunterzuladen.''

;[[Development/Tutorials/KNewStuffSecure|Sicherheit mit KNewStuff]] ([http://developer.kde.org/documentation/tutorials/knewstuffsecure/index.html Original Link])
:''Tutorial das zeigt, wie man Ressourcen auf sichere Weise teilt (KDE 3.4 und später).'' Geschrieben von András Mantia <amantia@kde.org>.

== Schnelle Anwendungsentwicklung ==

=== Python ===

;[[Development/Tutorials/Python introduction to signals and slots|101 Einführung in Signale und Slots]]
:''Eine einfache Einführung in Qt's Signal- und Slot-Architektur.''

=== Ruby ===

;[http://developer.kde.org/language-bindings/ruby/kde3tutorial/index.html KDE Ruby Korundum Tutorial]
:''Eine Ruby-Version von Antonio Larossa Jiménezs KDE Tutorial von Richard Dale. Sehen Sie sich for Qt Tutorials und andere Informationen auch die [http://developer.kde.org/language-bindings/ruby/index.html Ruby Developers Corner] an.''

;[[Development/Tutorials/Qt4_Ruby_Tutorial|Qt4 Ruby Tutorial]]
:''Trolltechs sagenhaftes Einstiegstutorial in Qt, übersetzt für Ruby.''

=== Shell ===

;[[Development/Tutorials/Shell_Scripting_with_KDE_Dialogs|Shell Scripting mit KDE Dialogen]] ([http://developer.kde.org/documentation/tutorials/kdialog/t1.html Original Link])
:''Tutorial von [mailto:bradh@frogmouth.net Brad Hards] das beschreibt, wie man KDE Dialoge mit Hilfe von kdialog in Shell-Skripten verwendet. Das Tutorial wird anhand eines Beispiels durchgeführt.''

== Andere Tutorials ==

=== Benutzung der KDE Games Bibliothek ===
;[[Development/Tutorials/Games/KStandardGameAction| KStandardGameAction]]
:''Benutzung von libkdegames um Ihr Spiel dem kdegames Standard anzupassen''
;[[Development/Tutorials/Games/Highscores| Highscores]]
:''Implementierung einer einfachen Highscore-Tabelle in Ihrem Spiel''
;[[Development/Tutorials/Games/Theme Selector| Themen-Auswahl]]
:'' Benutzung des libkdegames Themen-Auswahl-Dialogs''

=== 2D Plotting (KPlotWidget) ===
;[[Development/Tutorials/KPlotWidget|Benutzen des KDE Daten-Plotting Widgets]]
:''Dieses Tutorial führt KPlotWidget ein, welches zum plotten zweidimensionaler Daten verwendet werden kann. Es enthält Informationen zu einfachen Benutzung des Widgets (inklusive Hinzufügen und Änderung von Datensätzen sowie Anpassung der Koordinatenachsen und deren Beschriftung) sowie erweiterten Anwendungsfällen (inklusive Erweiterung des Widgets durch Vererbung).''

=== Rechtschreib- und Grammatikprüfung (Sonnet) ===
;[[Development/Tutorials/Sonnet/SonnetTutorial|Rechtschreib- oder Grammatikprüfung in KDE Applikationen einbinden]]
:''Diess Tutorial führt in Sonnet ein und wie man es benutzt um Sprachkorrekturen in der eigenen KDE Anwendung zu verwenden. Sonnets Hilffunktionen sollen in einem weiteren Tutorial beschrieben werden.''

=== Pixmap cache (KPixmapCache) ===
;[[Development/Tutorials/KPixmapCache|Benutzung des KDE Pixmap Caches]]
:''Dieses Tutorial demonstriert die Benutzung von KPixmapCache zum Zwischenspeichern von beispielsweise Pixmaps die aus SVGs oder Daten erstellt wurden.''

== Material für KDE2 und KDE3 ==

;[[Development/Tutorials/KDE3|KDE3 Tutorials]]
:''Diese Tutorials behandeln Themen im Bezug auf KDE3.''

;[[Development/Tutorials/KDE2|KDE2 Tutorials]]
:''Diese Tutorials behandeln Themen im Bezug auf KDE2.''

[[Category:KDE4]]

Development/Tutorials/KConfig (de)

2008-01-04T21:02:58Z

Rememberme: /* KDesktopFile: Ein besonderer Fall */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

{{improve (de)}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer- und Gruppenprofile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

{{note (de)| deserialization entgliedern? <br> <tt> "do not have to perform serialization and deserialization of objects themselves" </tt>}}

Anwendungen selbst müssen darum normalerweise Objekte nicht selber gliedern und entgliedern.

Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== Die KConfig Klasse ==

Das {{class|KConfig}}-Objekt wird benutzt um ein bestehendes Konfigurationsobjekt anzusteuern. Es gibt eine Reihe von Möglichkeiten ein Konfigurationsobjekt zu erstellen.

<code cppqt n>
// ein einfaches, altes lesen/schreiben Konfigurationsobjekt
KConfig config("myapprc");

// eine bestimmte Datei im Dateisystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// nicht mit globalen Werten verflochten
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// nicht mit globalen Werten orde der $KDEDIRS Hierarchie verflochten
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// Komponenten-spezifische Konfiguration, in diesem Fall ein Plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// Ausserhalb der normalen Konfigurations-Ressource
KConfig dataResource( "data", "myapp/somefile" );
</code>

{{note (de)|wie soll "merged" in den folgenden Fällen übersetzt werden? <br> <tt>"verschmolzen" oder "verflochten"</tt> <br> der Anwendung selber transparent" tönt auch nicht sehr gut}}

Das Kconfig Objekt, das wir auf Zeile 2 erstellen ist ein gewöhnliches Konfigurationsobjekt. Wir können Werte aus ihm lesen, neue Einträge schreiben und nach verschiedenen Eigenschaften des Objekts fragen. Dieses Objekt wird aus der Konfigurations-Ressource geladen, wie es durch {{class|KStandardDirs}} bestimmt wird, das heisst, dass jede Instanz des <tt>myapprc</tt>-Objekts in jedem der Ordner in der Konfigurations-Ressourcen-Hierarchie verschmolzen werden um die Werte zu erzeugen, die in diesem Objekt gesehen werden. So werden Systemweite und
pro-Benutzer/Gruppen Profile erstellt und unterstützt. Das alles geschieht der Anwendung selber transparent.

{{tip| Für mehr Informationen, wie das Verschmelzen funktioniert, siehe diesen Artikel über die [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Dateisystem Hierarchie]].}}

{{note (de)|Ist das so gemeint mit "expects an INI style file"<br> <tt> On line 6 we open a specific local file, this case /etc/kderc. This performs no merging of values and expects an INI style file.</tt>}}

Auf Zeile 6 öffnen wir eine bestimmte Lokale Datei, in diesem Fall {{path|/etc/kderc}}. Das führt kein verschmelzen von Werten aus und erwartet eine Datei im INI Format.

Zeile 9 erzeugt ein Konfigurationsobjekt, dass nicht mit dem globalen <tt>kdeglobals</tt>-Konfigurationsobjekt verflochten ist, während das Konfigurationsobjekt auf Zeile 12 zusätzlich mit keinem der Dateien in der <tt>$KDEDIRS</tt>-Hierarchie verflochten ist. Das kann die Leistung spürbar verbessern, falls man einfach nur Werte aus einer einfachen Konfuguration liest und globale Werte keine Rolle spielen.

Zeile 15 erzeugt ein Konfigurationsobjekt unter Benutzung des {{class|KComponentData}}-Objekts das zu einem Plugin oder einer anderen Komponente gehört. Das Plugin kann verschiedene Ordner aufweisen, die in seinen {{class|KStandardDirs}} definiert sind und das ist eine Möglichkeit sich zu versichern, dass {{class|KConfig}} das respektiert.

Und schliesslich auf Zeile 18 erzeugen wir ein Konfigurationsobjekt, das nicht in der <tt>config</tt>-Ressource sondern in der <tt>data</tt>-Ressource existiert. Man kann kann auf diese Weise jede Ressource verwenden, von denen {{class|KStandardDirs}} Kenntnis hat, auch solche die während der Laufzeit hinzugefügt werden.

=== Spezielle Konfigurationsobjekte ===

Jede Anwendung hat sein eigenes Konfigurationsobjekt das den Namen benutzt, der von {{class|KAboutData}} bereitgestellt wird mit angehängtem "rc". Also hätte eine Anwendung mit dem Namen "myapp" das Standard-Konfigurationsobjekt "myapprc". Dieses Konfigurationsobjekt kann auf diese Weise aufgerufen werden:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// beachten sie, dass dies eigentlich ein KSharedConfig ist
// mehr über diese Klasse siehe weiter unten
KConfig* config = KGlobal::config();
}
</code>

Auf das Standard-Konfigurationsobjekt für die Anwendung wird zugegriffen, wenn kein Name definiert wurde, als das {{class|KConfig}}-Objekt erzeugt wurde. Also könnten wir stattdessen auch das tun:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

Zusätzlich könnte jede Komponente sein eigenes Konfigurationsobjekt haben. Auf dieses wird normalerweise durch die <tt>componentData()</tt> des Plugins zugegriffen, anstatt durch die <tt>{{class|KGlobal}}::mainComponent()</tt>.

Und schliesslich gibt es noch ein globales Konfigurationsobjekt, <tt>kdeglobals</tt>, das von jeder Anwendung verwendet wird. Es enthält Informationen wie die Standard-Tatenkombinationen für verschiedene Aktionen. Es wird in das Konfigurationsobjekt "gemischt" wenn der <tt>KConfig::IncludeGlobals</tt> Bitschalter dem {{class|KConfig}} Konstruktor übergeben wird, was standardmässig der Fall ist.

=== Allgemein nützliche Methoden ===

Um den momentanen Zustand des Konfigurationsobjektes zu speichern, rufen wir die <tt>sync()</tt>-Methode auf. Diese Methode wird also aufgerufen, wenn ein Objekt zerstört wird. Falls keine Änderungen gemacht wurden, oder die Ressource weist sich als nicht beschreibbar aus (Wenn der Benutzer zum Beispiel nicht genug Rechte hat, um die Datei zu bearbeiten), dann wird keine Beschäftigung der Festplatte hervorgerufen. <tt>sync()</tt> verschmilzt Änderungen die gleichzeitig von anderen Prozessen ausgeführt werden - lokale Änderungen haben aber trotzdem Vorrang.

Wenn wir sicher gehen wollen, dass wir die aktuellsten Werte von der Festplatte haben, dann rufen wir <tt>reparseConfiguration()</tt> auf, welches <tt>sync()</tt> aufruft und dann die Daten von der Festplatte aktualisiert.

Falls wir verhindern müssen, dass das Konfigurationsobjekt bereits gemachte Änderungen nicht auf die Festplatte speichert, müssen wir <tt>markAsClean()</tt> aufrufen. Ein besonderer Anwendungsfall ist es, die Konfiguration zum Festplatten-Zustand zurückzusetzen indem man <tt>markAsClean()</tt> gefolgt von <tt>reparseConfiguration()</tt> aufruft.

Alle Gruppen in einem Konfigurationsobjekt aufzurufen ist so einfach wie hier in diesem Code-Abschnitt <tt>groupList()</tt> aufzurufen.

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

Die {{class|KSharedConfig}} Klasse ist eine Referenz-gezählte Version von {{class|KConfig}}. Darum stellt es eine Möglichkeit bereit, das selbe Konfigurationsobjekt von unterschiedlichen Orten zu referenzieren ohne zusätzlich die Objekte trennen zu müssen oder sich um die Synchronisation des Schreibvorgangs zu kümmern, selbst wenn das Konfigurationsobjekt von verschiedenen Code-Pfaden aktualisiert wird.

Auf ein {{class|KSharedConfig}}-Objekt zuzugreifen ist so einfach wie das hier:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<tt>openConfig()</tt> nimmt die selben Parameter wie {{class|KConfig}}'s Konstruktoren, was es einem ermöglicht zu definieren, welche Konfigurationsdatei zu öffnen und Markierungen das Verschmelzen von nicht-<tt>config</tt>-Ressourcen zu kontrollieren.

Es wird grundsätzlich empfohlen {{class|KSharedConfig}} anstatt {{class|KConfig}} selbst zu benutzen, und auch das Objekt, das von {{class|KComponentData}} zurückgegeben wird ist in der Tat ein {{class|KSharedConfig}}-Objekt.

== KConfigGroup ==

Nun da wir ein Konfigurationsobjekt haben, ist der nächste Schritt es tatsächlich zu nutzen. Das erste, das wir tun müssen, ist zu bestimmen, auf welche Gruppe von Schlüssel-/Wertepaare wir in unserem Objekt zugreifen wollen. Wir tun das, indem wir ein KConfigGroup-Objekt erstellen.

<code cppqt n>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ...oder so ähnlich...
</code>

Man kann{{class|KConfigGroup}} {{class|KConfig}}- oder {{class|KSharedConfig}}-Objekte übergeben.

Konfigurationsgruppen können ebenfalls verschachtelt werden.

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Lesen von Einträgen ==

Wenn man erst einmal ein {{class|KConfigGroup}}-Objekt erstellt hat, ist das Lesen von Einträgen ziemlich einfach:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

Wie man hier oben sehen kann, kann man Lesevorgänge von verschiedenen {{class|KConfigGroup}}-Objekten, die auf dem selben {{class|KConfig}}-Objekt erstellt wurden, problemlos mischen. Die Lese-Methoden nehmen den Schlüssel, der Gross- und Kleinschreibung unterscheidet, als erstes Argument und den Standardwert als zweites Argument. Dieses Argument bestimmt auch welche Art von Daten, also z.B. eine Farbe in Zeile 3, erwartet wird und auch die Art von Objekt, die zurückgegeben werden soll.Das zurückgegebene Objekt wird in eine {{qt|QVariant}} gepackt um diese Hexerei zu ermöglichen.

Es gibt eine Anzahl von speziellen Methoden, zum Beispiel <tt>readPathEntry</tt>, das einen Datei-Systempfad zurückgibt. Es ist entscheidend, dass man <tt>readPathEntry</tt> benutzt, wenn man nach einem Pfad fragt, das es Funktionen wie Erreichbarkeits-Profile ermöglicht richtig zu funktionieren.

Wenn kein solcher Schlüssel im Konfigurationsobjekt existiert, dann wird stattdessen der Standardwert zurückgegeben. Falls es eine lokalisierte (d.h. in eine andere Sprache übersetzte) Version für den Schlüssel gibt, die der eingestellten Sprache entspricht, dann wird diese zurückgegeben.

== Schreiben neuer Einträge ==

Neue Werte zu definieren ist ähnlich einfach:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

Beachten sie die Benutzung von <tt>writePathEntry</tt> und wie die Art von Objekt, das wir benutzen, wie zum Beispiel {{qt|QColor}} auf Zeile 3, bestimmt, wie die Daten angeordnet werden. Zusätzlich, wenn wir mit den Einträgen fertig sind, muss <tt>sync()</tt> auf das Konfigurationsobjekt ausgeführt werden, um es auf die Festplatte zu speichern. Man kann auch einfach warten, bis das Objekt zerstört wird, was falls nötig automatisch einen <tt>sync()</tt> auslöst.

== KDesktopFile: Ein besonderer Fall ==

Wann ist eine Konfigurationsdatei keine Konfigurationsdatei? Wenn es eine [http://freedesktop.org/wiki/Standards_2fdesktop_2dentry_2dspec Desktop-Datei] ist. Diese Dateien, die im Grunde genommen Konfigurationsdateien sind, werden benutzt um Einträge für Anwendungsmenüs, Dateitypen, Plugins und verschiedene Services.

Wenn auf eine .desktop Datei zugegriffen wird, sollte man stattdessen die {{class|KDesktopFile}}-Klasse verwenden, die, während eine {{class|KConfig}}-Klasse über alle oben genannten Ressourcen verfügt, über eine Anzahl von Methoden verfügt, um das Zugreifen auf Standard-Attribute dieser Dateien konsistent und zuverlässig zu machen.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KConfig (de)

2008-01-03T20:40:11Z

Rememberme: /* Writing Entries */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

{{improve (de)}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer- und Gruppenprofile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

{{note (de)| deserialization entgliedern? <br> <tt> "do not have to perform serialization and deserialization of objects themselves" </tt>}}

Anwendungen selbst müssen darum normalerweise Objekte nicht selber gliedern und entgliedern.

Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== Die KConfig Klasse ==

Das {{class|KConfig}}-Objekt wird benutzt um ein bestehendes Konfigurationsobjekt anzusteuern. Es gibt eine Reihe von Möglichkeiten ein Konfigurationsobjekt zu erstellen.

<code cppqt n>
// ein einfaches, altes lesen/schreiben Konfigurationsobjekt
KConfig config("myapprc");

// eine bestimmte Datei im Dateisystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// nicht mit globalen Werten verflochten
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// nicht mit globalen Werten orde der $KDEDIRS Hierarchie verflochten
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// Komponenten-spezifische Konfiguration, in diesem Fall ein Plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// Ausserhalb der normalen Konfigurations-Ressource
KConfig dataResource( "data", "myapp/somefile" );
</code>

{{note (de)|wie soll "merged" in den folgenden Fällen übersetzt werden? <br> <tt>"verschmolzen" oder "verflochten"</tt> <br> der Anwendung selber transparent" tönt auch nicht sehr gut}}

Das Kconfig Objekt, das wir auf Zeile 2 erstellen ist ein gewöhnliches Konfigurationsobjekt. Wir können Werte aus ihm lesen, neue Einträge schreiben und nach verschiedenen Eigenschaften des Objekts fragen. Dieses Objekt wird aus der Konfigurations-Ressource geladen, wie es durch {{class|KStandardDirs}} bestimmt wird, das heisst, dass jede Instanz des <tt>myapprc</tt>-Objekts in jedem der Ordner in der Konfigurations-Ressourcen-Hierarchie verschmolzen werden um die Werte zu erzeugen, die in diesem Objekt gesehen werden. So werden Systemweite und
pro-Benutzer/Gruppen Profile erstellt und unterstützt. Das alles geschieht der Anwendung selber transparent.

{{tip| Für mehr Informationen, wie das Verschmelzen funktioniert, siehe diesen Artikel über die [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Dateisystem Hierarchie]].}}

{{note (de)|Ist das so gemeint mit "expects an INI style file"<br> <tt> On line 6 we open a specific local file, this case /etc/kderc. This performs no merging of values and expects an INI style file.</tt>}}

Auf Zeile 6 öffnen wir eine bestimmte Lokale Datei, in diesem Fall {{path|/etc/kderc}}. Das führt kein verschmelzen von Werten aus und erwartet eine Datei im INI Format.

Zeile 9 erzeugt ein Konfigurationsobjekt, dass nicht mit dem globalen <tt>kdeglobals</tt>-Konfigurationsobjekt verflochten ist, während das Konfigurationsobjekt auf Zeile 12 zusätzlich mit keinem der Dateien in der <tt>$KDEDIRS</tt>-Hierarchie verflochten ist. Das kann die Leistung spürbar verbessern, falls man einfach nur Werte aus einer einfachen Konfuguration liest und globale Werte keine Rolle spielen.

Zeile 15 erzeugt ein Konfigurationsobjekt unter Benutzung des {{class|KComponentData}}-Objekts das zu einem Plugin oder einer anderen Komponente gehört. Das Plugin kann verschiedene Ordner aufweisen, die in seinen {{class|KStandardDirs}} definiert sind und das ist eine Möglichkeit sich zu versichern, dass {{class|KConfig}} das respektiert.

Und schliesslich auf Zeile 18 erzeugen wir ein Konfigurationsobjekt, das nicht in der <tt>config</tt>-Ressource sondern in der <tt>data</tt>-Ressource existiert. Man kann kann auf diese Weise jede Ressource verwenden, von denen {{class|KStandardDirs}} Kenntnis hat, auch solche die während der Laufzeit hinzugefügt werden.

=== Spezielle Konfigurationsobjekte ===

Jede Anwendung hat sein eigenes Konfigurationsobjekt das den Namen benutzt, der von {{class|KAboutData}} bereitgestellt wird mit angehängtem "rc". Also hätte eine Anwendung mit dem Namen "myapp" das Standard-Konfigurationsobjekt "myapprc". Dieses Konfigurationsobjekt kann auf diese Weise aufgerufen werden:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// beachten sie, dass dies eigentlich ein KSharedConfig ist
// mehr über diese Klasse siehe weiter unten
KConfig* config = KGlobal::config();
}
</code>

Auf das Standard-Konfigurationsobjekt für die Anwendung wird zugegriffen, wenn kein Name definiert wurde, als das {{class|KConfig}}-Objekt erzeugt wurde. Also könnten wir stattdessen auch das tun:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

Zusätzlich könnte jede Komponente sein eigenes Konfigurationsobjekt haben. Auf dieses wird normalerweise durch die <tt>componentData()</tt> des Plugins zugegriffen, anstatt durch die <tt>{{class|KGlobal}}::mainComponent()</tt>.

Und schliesslich gibt es noch ein globales Konfigurationsobjekt, <tt>kdeglobals</tt>, das von jeder Anwendung verwendet wird. Es enthält Informationen wie die Standard-Tatenkombinationen für verschiedene Aktionen. Es wird in das Konfigurationsobjekt "gemischt" wenn der <tt>KConfig::IncludeGlobals</tt> Bitschalter dem {{class|KConfig}} Konstruktor übergeben wird, was standardmässig der Fall ist.

=== Allgemein nützliche Methoden ===

Um den momentanen Zustand des Konfigurationsobjektes zu speichern, rufen wir die <tt>sync()</tt>-Methode auf. Diese Methode wird also aufgerufen, wenn ein Objekt zerstört wird. Falls keine Änderungen gemacht wurden, oder die Ressource weist sich als nicht beschreibbar aus (Wenn der Benutzer zum Beispiel nicht genug Rechte hat, um die Datei zu bearbeiten), dann wird keine Beschäftigung der Festplatte hervorgerufen. <tt>sync()</tt> verschmilzt Änderungen die gleichzeitig von anderen Prozessen ausgeführt werden - lokale Änderungen haben aber trotzdem Vorrang.

Wenn wir sicher gehen wollen, dass wir die aktuellsten Werte von der Festplatte haben, dann rufen wir <tt>reparseConfiguration()</tt> auf, welches <tt>sync()</tt> aufruft und dann die Daten von der Festplatte aktualisiert.

Falls wir verhindern müssen, dass das Konfigurationsobjekt bereits gemachte Änderungen nicht auf die Festplatte speichert, müssen wir <tt>markAsClean()</tt> aufrufen. Ein besonderer Anwendungsfall ist es, die Konfiguration zum Festplatten-Zustand zurückzusetzen indem man <tt>markAsClean()</tt> gefolgt von <tt>reparseConfiguration()</tt> aufruft.

Alle Gruppen in einem Konfigurationsobjekt aufzurufen ist so einfach wie hier in diesem Code-Abschnitt <tt>groupList()</tt> aufzurufen.

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

Die {{class|KSharedConfig}} Klasse ist eine Referenz-gezählte Version von {{class|KConfig}}. Darum stellt es eine Möglichkeit bereit, das selbe Konfigurationsobjekt von unterschiedlichen Orten zu referenzieren ohne zusätzlich die Objekte trennen zu müssen oder sich um die Synchronisation des Schreibvorgangs zu kümmern, selbst wenn das Konfigurationsobjekt von verschiedenen Code-Pfaden aktualisiert wird.

Auf ein {{class|KSharedConfig}}-Objekt zuzugreifen ist so einfach wie das hier:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<tt>openConfig()</tt> nimmt die selben Parameter wie {{class|KConfig}}'s Konstruktoren, was es einem ermöglicht zu definieren, welche Konfigurationsdatei zu öffnen und Markierungen das Verschmelzen von nicht-<tt>config</tt>-Ressourcen zu kontrollieren.

Es wird grundsätzlich empfohlen {{class|KSharedConfig}} anstatt {{class|KConfig}} selbst zu benutzen, und auch das Objekt, das von {{class|KComponentData}} zurückgegeben wird ist in der Tat ein {{class|KSharedConfig}}-Objekt.

== KConfigGroup ==

Nun da wir ein Konfigurationsobjekt haben, ist der nächste Schritt es tatsächlich zu nutzen. Das erste, das wir tun müssen, ist zu bestimmen, auf welche Gruppe von Schlüssel-/Wertepaare wir in unserem Objekt zugreifen wollen. Wir tun das, indem wir ein KConfigGroup-Objekt erstellen.

<code cppqt n>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ...oder so ähnlich...
</code>

Man kann{{class|KConfigGroup}} {{class|KConfig}}- oder {{class|KSharedConfig}}-Objekte übergeben.

Konfigurationsgruppen können ebenfalls verschachtelt werden.

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Lesen von Einträgen ==

{{note (de)| Der Rest muss noch übersetzt werden}}

Wenn man erst einmal ein {{class|KConfigGroup}}-Objekt erstellt hat, ist das Lesen von Einträgen ziemlich einfach:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

Wie man hier oben sehen kann, kann man Lesevorgänge von verschiedenen {{class|KConfigGroup}}-Objekten, die auf dem selben {{class|KConfig}}-Objekt erstellt wurden, problemlos mischen. Die Lese-Methoden nehmen den Schlüssel, der Gross- und Kleinschreibung unterscheidet, als erstes Argument und den Standardwert als zweites Argument. Dieses Argument bestimmt auch welche Art von Daten, also z.B. eine Farbe in Zeile 3, erwartet wird und auch die Art von Objekt, die zurückgegeben werden soll.Das zurückgegebene Objekt wird in eine {{qt|QVariant}} gepackt um diese Hexerei zu ermöglichen.

Es gibt eine Anzahl von speziellen Methoden, zum Beispiel <tt>readPathEntry</tt>, das einen Datei-Systempfad zurückgibt. Es ist entscheidend, dass man <tt>readPathEntry</tt> benutzt, wenn man nach einem Pfad fragt, das es Funktionen wie Erreichbarkeits-Profile ermöglicht richtig zu funktionieren.

Wenn kein solcher Schlüssel im Konfigurationsobjekt existiert, dann wird stattdessen der Standardwert zurückgegeben. Falls es eine lokalisierte (d.h. in eine andere Sprache übersetzte) Version für den Schlüssel gibt, die der eingestellten Sprache entspricht, dann wird diese zurückgegeben.

== Schreiben neuer Einträge ==

Neue Werte zu definieren ist ähnlich einfach:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

Beachten sie die Benutzung von <tt>writePathEntry</tt> und wie die Art von Objekt, das wir benutzen, wie zum Beispiel {{qt|QColor}} auf Zeile 3, bestimmt, wie die Daten angeordnet werden. Zusätzlich, wenn wir mit den Einträgen fertig sind, muss <tt>sync()</tt> auf das Konfigurationsobjekt ausgeführt werden, um es auf die Festplatte zu speichern. Man kann auch einfach warten, bis das Objekt zerstört wird, was falls nötig automatisch einen <tt>sync()</tt> auslöst.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KConfig (de)

2008-01-03T14:03:22Z

Rememberme: /* Lesen von Einträgen */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

{{improve (de)}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer- und Gruppenprofile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

{{note (de)| deserialization entgliedern? <br> <tt> "do not have to perform serialization and deserialization of objects themselves" </tt>}}

Anwendungen selbst müssen darum normalerweise Objekte nicht selber gliedern und entgliedern.

Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== Die KConfig Klasse ==

Das {{class|KConfig}}-Objekt wird benutzt um ein bestehendes Konfigurationsobjekt anzusteuern. Es gibt eine Reihe von Möglichkeiten ein Konfigurationsobjekt zu erstellen.

<code cppqt n>
// ein einfaches, altes lesen/schreiben Konfigurationsobjekt
KConfig config("myapprc");

// eine bestimmte Datei im Dateisystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// nicht mit globalen Werten verflochten
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// nicht mit globalen Werten orde der $KDEDIRS Hierarchie verflochten
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// Komponenten-spezifische Konfiguration, in diesem Fall ein Plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// Ausserhalb der normalen Konfigurations-Ressource
KConfig dataResource( "data", "myapp/somefile" );
</code>

{{note (de)|wie soll "merged" in den folgenden Fällen übersetzt werden? <br> <tt>"verschmolzen" oder "verflochten"</tt> <br> der Anwendung selber transparent" tönt auch nicht sehr gut}}

Das Kconfig Objekt, das wir auf Zeile 2 erstellen ist ein gewöhnliches Konfigurationsobjekt. Wir können Werte aus ihm lesen, neue Einträge schreiben und nach verschiedenen Eigenschaften des Objekts fragen. Dieses Objekt wird aus der Konfigurations-Ressource geladen, wie es durch {{class|KStandardDirs}} bestimmt wird, das heisst, dass jede Instanz des <tt>myapprc</tt>-Objekts in jedem der Ordner in der Konfigurations-Ressourcen-Hierarchie verschmolzen werden um die Werte zu erzeugen, die in diesem Objekt gesehen werden. So werden Systemweite und
pro-Benutzer/Gruppen Profile erstellt und unterstützt. Das alles geschieht der Anwendung selber transparent.

{{tip| Für mehr Informationen, wie das Verschmelzen funktioniert, siehe diesen Artikel über die [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Dateisystem Hierarchie]].}}

{{note (de)|Ist das so gemeint mit "expects an INI style file"<br> <tt> On line 6 we open a specific local file, this case /etc/kderc. This performs no merging of values and expects an INI style file.</tt>}}

Auf Zeile 6 öffnen wir eine bestimmte Lokale Datei, in diesem Fall {{path|/etc/kderc}}. Das führt kein verschmelzen von Werten aus und erwartet eine Datei im INI Format.

Zeile 9 erzeugt ein Konfigurationsobjekt, dass nicht mit dem globalen <tt>kdeglobals</tt>-Konfigurationsobjekt verflochten ist, während das Konfigurationsobjekt auf Zeile 12 zusätzlich mit keinem der Dateien in der <tt>$KDEDIRS</tt>-Hierarchie verflochten ist. Das kann die Leistung spürbar verbessern, falls man einfach nur Werte aus einer einfachen Konfuguration liest und globale Werte keine Rolle spielen.

Zeile 15 erzeugt ein Konfigurationsobjekt unter Benutzung des {{class|KComponentData}}-Objekts das zu einem Plugin oder einer anderen Komponente gehört. Das Plugin kann verschiedene Ordner aufweisen, die in seinen {{class|KStandardDirs}} definiert sind und das ist eine Möglichkeit sich zu versichern, dass {{class|KConfig}} das respektiert.

Und schliesslich auf Zeile 18 erzeugen wir ein Konfigurationsobjekt, das nicht in der <tt>config</tt>-Ressource sondern in der <tt>data</tt>-Ressource existiert. Man kann kann auf diese Weise jede Ressource verwenden, von denen {{class|KStandardDirs}} Kenntnis hat, auch solche die während der Laufzeit hinzugefügt werden.

=== Spezielle Konfigurationsobjekte ===

Jede Anwendung hat sein eigenes Konfigurationsobjekt das den Namen benutzt, der von {{class|KAboutData}} bereitgestellt wird mit angehängtem "rc". Also hätte eine Anwendung mit dem Namen "myapp" das Standard-Konfigurationsobjekt "myapprc". Dieses Konfigurationsobjekt kann auf diese Weise aufgerufen werden:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// beachten sie, dass dies eigentlich ein KSharedConfig ist
// mehr über diese Klasse siehe weiter unten
KConfig* config = KGlobal::config();
}
</code>

Auf das Standard-Konfigurationsobjekt für die Anwendung wird zugegriffen, wenn kein Name definiert wurde, als das {{class|KConfig}}-Objekt erzeugt wurde. Also könnten wir stattdessen auch das tun:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

Zusätzlich könnte jede Komponente sein eigenes Konfigurationsobjekt haben. Auf dieses wird normalerweise durch die <tt>componentData()</tt> des Plugins zugegriffen, anstatt durch die <tt>{{class|KGlobal}}::mainComponent()</tt>.

Und schliesslich gibt es noch ein globales Konfigurationsobjekt, <tt>kdeglobals</tt>, das von jeder Anwendung verwendet wird. Es enthält Informationen wie die Standard-Tatenkombinationen für verschiedene Aktionen. Es wird in das Konfigurationsobjekt "gemischt" wenn der <tt>KConfig::IncludeGlobals</tt> Bitschalter dem {{class|KConfig}} Konstruktor übergeben wird, was standardmässig der Fall ist.

=== Allgemein nützliche Methoden ===

Um den momentanen Zustand des Konfigurationsobjektes zu speichern, rufen wir die <tt>sync()</tt>-Methode auf. Diese Methode wird also aufgerufen, wenn ein Objekt zerstört wird. Falls keine Änderungen gemacht wurden, oder die Ressource weist sich als nicht beschreibbar aus (Wenn der Benutzer zum Beispiel nicht genug Rechte hat, um die Datei zu bearbeiten), dann wird keine Beschäftigung der Festplatte hervorgerufen. <tt>sync()</tt> verschmilzt Änderungen die gleichzeitig von anderen Prozessen ausgeführt werden - lokale Änderungen haben aber trotzdem Vorrang.

Wenn wir sicher gehen wollen, dass wir die aktuellsten Werte von der Festplatte haben, dann rufen wir <tt>reparseConfiguration()</tt> auf, welches <tt>sync()</tt> aufruft und dann die Daten von der Festplatte aktualisiert.

Falls wir verhindern müssen, dass das Konfigurationsobjekt bereits gemachte Änderungen nicht auf die Festplatte speichert, müssen wir <tt>markAsClean()</tt> aufrufen. Ein besonderer Anwendungsfall ist es, die Konfiguration zum Festplatten-Zustand zurückzusetzen indem man <tt>markAsClean()</tt> gefolgt von <tt>reparseConfiguration()</tt> aufruft.

Alle Gruppen in einem Konfigurationsobjekt aufzurufen ist so einfach wie hier in diesem Code-Abschnitt <tt>groupList()</tt> aufzurufen.

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

Die {{class|KSharedConfig}} Klasse ist eine Referenz-gezählte Version von {{class|KConfig}}. Darum stellt es eine Möglichkeit bereit, das selbe Konfigurationsobjekt von unterschiedlichen Orten zu referenzieren ohne zusätzlich die Objekte trennen zu müssen oder sich um die Synchronisation des Schreibvorgangs zu kümmern, selbst wenn das Konfigurationsobjekt von verschiedenen Code-Pfaden aktualisiert wird.

Auf ein {{class|KSharedConfig}}-Objekt zuzugreifen ist so einfach wie das hier:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<tt>openConfig()</tt> nimmt die selben Parameter wie {{class|KConfig}}'s Konstruktoren, was es einem ermöglicht zu definieren, welche Konfigurationsdatei zu öffnen und Markierungen das Verschmelzen von nicht-<tt>config</tt>-Ressourcen zu kontrollieren.

Es wird grundsätzlich empfohlen {{class|KSharedConfig}} anstatt {{class|KConfig}} selbst zu benutzen, und auch das Objekt, das von {{class|KComponentData}} zurückgegeben wird ist in der Tat ein {{class|KSharedConfig}}-Objekt.

== KConfigGroup ==

Nun da wir ein Konfigurationsobjekt haben, ist der nächste Schritt es tatsächlich zu nutzen. Das erste, das wir tun müssen, ist zu bestimmen, auf welche Gruppe von Schlüssel-/Wertepaare wir in unserem Objekt zugreifen wollen. Wir tun das, indem wir ein KConfigGroup-Objekt erstellen.

<code cppqt n>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ...oder so ähnlich...
</code>

Man kann{{class|KConfigGroup}} {{class|KConfig}}- oder {{class|KSharedConfig}}-Objekte übergeben.

Konfigurationsgruppen können ebenfalls verschachtelt werden.

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Lesen von Einträgen ==

{{note (de)| Der Rest muss noch übersetzt werden}}

Wenn man erst einmal ein {{class|KConfigGroup}}-Objekt erstellt hat, ist das Lesen von Einträgen ziemlich einfach:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

Wie man hier oben sehen kann, kann man Lesevorgänge von verschiedenen {{class|KConfigGroup}}-Objekten, die auf dem selben {{class|KConfig}}-Objekt erstellt wurden, problemlos mischen. Die Lese-Methoden nehmen den Schlüssel, der Gross- und Kleinschreibung unterscheidet, als erstes Argument und den Standardwert als zweites Argument. Dieses Argument bestimmt auch welche Art von Daten, also z.B. eine Farbe in Zeile 3, erwartet wird und auch die Art von Objekt, die zurückgegeben werden soll.Das zurückgegebene Objekt wird in eine {{qt|QVariant}} gepackt um diese Hexerei zu ermöglichen.

Es gibt eine Anzahl von speziellen Methoden, zum Beispiel <tt>readPathEntry</tt>, das einen Datei-Systempfad zurückgibt. Es ist entscheidend, dass man <tt>readPathEntry</tt> benutzt, wenn man nach einem Pfad fragt, das es Funktionen wie Erreichbarkeits-Profile ermöglicht richtig zu funktionieren.

Wenn kein solcher Schlüssel im Konfigurationsobjekt existiert, dann wird stattdessen der Standardwert zurückgegeben. Falls es eine lokalisierte (d.h. in eine andere Sprache übersetzte) Version für den Schlüssel gibt, die der eingestellten Sprache entspricht, dann wird diese zurückgegeben.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KConfig (de)

2008-01-02T17:01:35Z

Rememberme: /* Reading Entries */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

{{improve (de)}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer- und Gruppenprofile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

{{note (de)| deserialization entgliedern? <br> <tt> "do not have to perform serialization and deserialization of objects themselves" </tt>}}

Anwendungen selbst müssen darum normalerweise Objekte nicht selber gliedern und entgliedern.

Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== Die KConfig Klasse ==

Das {{class|KConfig}}-Objekt wird benutzt um ein bestehendes Konfigurationsobjekt anzusteuern. Es gibt eine Reihe von Möglichkeiten ein Konfigurationsobjekt zu erstellen.

<code cppqt n>
// ein einfaches, altes lesen/schreiben Konfigurationsobjekt
KConfig config("myapprc");

// eine bestimmte Datei im Dateisystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// nicht mit globalen Werten verflochten
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// nicht mit globalen Werten orde der $KDEDIRS Hierarchie verflochten
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// Komponenten-spezifische Konfiguration, in diesem Fall ein Plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// Ausserhalb der normalen Konfigurations-Ressource
KConfig dataResource( "data", "myapp/somefile" );
</code>

{{note (de)|wie soll "merged" in den folgenden Fällen übersetzt werden? <br> <tt>"verschmolzen" oder "verflochten"</tt> <br> der Anwendung selber transparent" tönt auch nicht sehr gut}}

Das Kconfig Objekt, das wir auf Zeile 2 erstellen ist ein gewöhnliches Konfigurationsobjekt. Wir können Werte aus ihm lesen, neue Einträge schreiben und nach verschiedenen Eigenschaften des Objekts fragen. Dieses Objekt wird aus der Konfigurations-Ressource geladen, wie es durch {{class|KStandardDirs}} bestimmt wird, das heisst, dass jede Instanz des <tt>myapprc</tt>-Objekts in jedem der Ordner in der Konfigurations-Ressourcen-Hierarchie verschmolzen werden um die Werte zu erzeugen, die in diesem Objekt gesehen werden. So werden Systemweite und
pro-Benutzer/Gruppen Profile erstellt und unterstützt. Das alles geschieht der Anwendung selber transparent.

{{tip| Für mehr Informationen, wie das Verschmelzen funktioniert, siehe diesen Artikel über die [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Dateisystem Hierarchie]].}}

{{note (de)|Ist das so gemeint mit "expects an INI style file"<br> <tt> On line 6 we open a specific local file, this case /etc/kderc. This performs no merging of values and expects an INI style file.</tt>}}

Auf Zeile 6 öffnen wir eine bestimmte Lokale Datei, in diesem Fall {{path|/etc/kderc}}. Das führt kein verschmelzen von Werten aus und erwartet eine Datei im INI Format.

Zeile 9 erzeugt ein Konfigurationsobjekt, dass nicht mit dem globalen <tt>kdeglobals</tt>-Konfigurationsobjekt verflochten ist, während das Konfigurationsobjekt auf Zeile 12 zusätzlich mit keinem der Dateien in der <tt>$KDEDIRS</tt>-Hierarchie verflochten ist. Das kann die Leistung spürbar verbessern, falls man einfach nur Werte aus einer einfachen Konfuguration liest und globale Werte keine Rolle spielen.

Zeile 15 erzeugt ein Konfigurationsobjekt unter Benutzung des {{class|KComponentData}}-Objekts das zu einem Plugin oder einer anderen Komponente gehört. Das Plugin kann verschiedene Ordner aufweisen, die in seinen {{class|KStandardDirs}} definiert sind und das ist eine Möglichkeit sich zu versichern, dass {{class|KConfig}} das respektiert.

Und schliesslich auf Zeile 18 erzeugen wir ein Konfigurationsobjekt, das nicht in der <tt>config</tt>-Ressource sondern in der <tt>data</tt>-Ressource existiert. Man kann kann auf diese Weise jede Ressource verwenden, von denen {{class|KStandardDirs}} Kenntnis hat, auch solche die während der Laufzeit hinzugefügt werden.

=== Spezielle Konfigurationsobjekte ===

Jede Anwendung hat sein eigenes Konfigurationsobjekt das den Namen benutzt, der von {{class|KAboutData}} bereitgestellt wird mit angehängtem "rc". Also hätte eine Anwendung mit dem Namen "myapp" das Standard-Konfigurationsobjekt "myapprc". Dieses Konfigurationsobjekt kann auf diese Weise aufgerufen werden:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// beachten sie, dass dies eigentlich ein KSharedConfig ist
// mehr über diese Klasse siehe weiter unten
KConfig* config = KGlobal::config();
}
</code>

Auf das Standard-Konfigurationsobjekt für die Anwendung wird zugegriffen, wenn kein Name definiert wurde, als das {{class|KConfig}}-Objekt erzeugt wurde. Also könnten wir stattdessen auch das tun:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

Zusätzlich könnte jede Komponente sein eigenes Konfigurationsobjekt haben. Auf dieses wird normalerweise durch die <tt>componentData()</tt> des Plugins zugegriffen, anstatt durch die <tt>{{class|KGlobal}}::mainComponent()</tt>.

Und schliesslich gibt es noch ein globales Konfigurationsobjekt, <tt>kdeglobals</tt>, das von jeder Anwendung verwendet wird. Es enthält Informationen wie die Standard-Tatenkombinationen für verschiedene Aktionen. Es wird in das Konfigurationsobjekt "gemischt" wenn der <tt>KConfig::IncludeGlobals</tt> Bitschalter dem {{class|KConfig}} Konstruktor übergeben wird, was standardmässig der Fall ist.

=== Allgemein nützliche Methoden ===

Um den momentanen Zustand des Konfigurationsobjektes zu speichern, rufen wir die <tt>sync()</tt>-Methode auf. Diese Methode wird also aufgerufen, wenn ein Objekt zerstört wird. Falls keine Änderungen gemacht wurden, oder die Ressource weist sich als nicht beschreibbar aus (Wenn der Benutzer zum Beispiel nicht genug Rechte hat, um die Datei zu bearbeiten), dann wird keine Beschäftigung der Festplatte hervorgerufen. <tt>sync()</tt> verschmilzt Änderungen die gleichzeitig von anderen Prozessen ausgeführt werden - lokale Änderungen haben aber trotzdem Vorrang.

Wenn wir sicher gehen wollen, dass wir die aktuellsten Werte von der Festplatte haben, dann rufen wir <tt>reparseConfiguration()</tt> auf, welches <tt>sync()</tt> aufruft und dann die Daten von der Festplatte aktualisiert.

Falls wir verhindern müssen, dass das Konfigurationsobjekt bereits gemachte Änderungen nicht auf die Festplatte speichert, müssen wir <tt>markAsClean()</tt> aufrufen. Ein besonderer Anwendungsfall ist es, die Konfiguration zum Festplatten-Zustand zurückzusetzen indem man <tt>markAsClean()</tt> gefolgt von <tt>reparseConfiguration()</tt> aufruft.

Alle Gruppen in einem Konfigurationsobjekt aufzurufen ist so einfach wie hier in diesem Code-Abschnitt <tt>groupList()</tt> aufzurufen.

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

Die {{class|KSharedConfig}} Klasse ist eine Referenz-gezählte Version von {{class|KConfig}}. Darum stellt es eine Möglichkeit bereit, das selbe Konfigurationsobjekt von unterschiedlichen Orten zu referenzieren ohne zusätzlich die Objekte trennen zu müssen oder sich um die Synchronisation des Schreibvorgangs zu kümmern, selbst wenn das Konfigurationsobjekt von verschiedenen Code-Pfaden aktualisiert wird.

Auf ein {{class|KSharedConfig}}-Objekt zuzugreifen ist so einfach wie das hier:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<tt>openConfig()</tt> nimmt die selben Parameter wie {{class|KConfig}}'s Konstruktoren, was es einem ermöglicht zu definieren, welche Konfigurationsdatei zu öffnen und Markierungen das Verschmelzen von nicht-<tt>config</tt>-Ressourcen zu kontrollieren.

Es wird grundsätzlich empfohlen {{class|KSharedConfig}} anstatt {{class|KConfig}} selbst zu benutzen, und auch das Objekt, das von {{class|KComponentData}} zurückgegeben wird ist in der Tat ein {{class|KSharedConfig}}-Objekt.

== KConfigGroup ==

Nun da wir ein Konfigurationsobjekt haben, ist der nächste Schritt es tatsächlich zu nutzen. Das erste, das wir tun müssen, ist zu bestimmen, auf welche Gruppe von Schlüssel-/Wertepaare wir in unserem Objekt zugreifen wollen. Wir tun das, indem wir ein KConfigGroup-Objekt erstellen.

<code cppqt n>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ...oder so ähnlich...
</code>

Man kann{{class|KConfigGroup}} {{class|KConfig}}- oder {{class|KSharedConfig}}-Objekte übergeben.

Konfigurationsgruppen können ebenfalls verschachtelt werden.

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Lesen von Einträgen ==

{{note (de)| Der Rest muss noch übersetzt werden}}

With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

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.

There are a couple of special read methods, including <tt>readPathEntry</tt> which returns a file system path. It is vital that one uses <tt>readPathEntry</tt> if it is a path as this enables such features as roaming profiles to work properly.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KConfig (de)

2008-01-02T17:01:19Z

Rememberme: /* Reading Entries */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

{{improve (de)}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer- und Gruppenprofile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

{{note (de)| deserialization entgliedern? <br> <tt> "do not have to perform serialization and deserialization of objects themselves" </tt>}}

Anwendungen selbst müssen darum normalerweise Objekte nicht selber gliedern und entgliedern.

Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== Die KConfig Klasse ==

Das {{class|KConfig}}-Objekt wird benutzt um ein bestehendes Konfigurationsobjekt anzusteuern. Es gibt eine Reihe von Möglichkeiten ein Konfigurationsobjekt zu erstellen.

<code cppqt n>
// ein einfaches, altes lesen/schreiben Konfigurationsobjekt
KConfig config("myapprc");

// eine bestimmte Datei im Dateisystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// nicht mit globalen Werten verflochten
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// nicht mit globalen Werten orde der $KDEDIRS Hierarchie verflochten
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// Komponenten-spezifische Konfiguration, in diesem Fall ein Plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// Ausserhalb der normalen Konfigurations-Ressource
KConfig dataResource( "data", "myapp/somefile" );
</code>

{{note (de)|wie soll "merged" in den folgenden Fällen übersetzt werden? <br> <tt>"verschmolzen" oder "verflochten"</tt> <br> der Anwendung selber transparent" tönt auch nicht sehr gut}}

Das Kconfig Objekt, das wir auf Zeile 2 erstellen ist ein gewöhnliches Konfigurationsobjekt. Wir können Werte aus ihm lesen, neue Einträge schreiben und nach verschiedenen Eigenschaften des Objekts fragen. Dieses Objekt wird aus der Konfigurations-Ressource geladen, wie es durch {{class|KStandardDirs}} bestimmt wird, das heisst, dass jede Instanz des <tt>myapprc</tt>-Objekts in jedem der Ordner in der Konfigurations-Ressourcen-Hierarchie verschmolzen werden um die Werte zu erzeugen, die in diesem Objekt gesehen werden. So werden Systemweite und
pro-Benutzer/Gruppen Profile erstellt und unterstützt. Das alles geschieht der Anwendung selber transparent.

{{tip| Für mehr Informationen, wie das Verschmelzen funktioniert, siehe diesen Artikel über die [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Dateisystem Hierarchie]].}}

{{note (de)|Ist das so gemeint mit "expects an INI style file"<br> <tt> On line 6 we open a specific local file, this case /etc/kderc. This performs no merging of values and expects an INI style file.</tt>}}

Auf Zeile 6 öffnen wir eine bestimmte Lokale Datei, in diesem Fall {{path|/etc/kderc}}. Das führt kein verschmelzen von Werten aus und erwartet eine Datei im INI Format.

Zeile 9 erzeugt ein Konfigurationsobjekt, dass nicht mit dem globalen <tt>kdeglobals</tt>-Konfigurationsobjekt verflochten ist, während das Konfigurationsobjekt auf Zeile 12 zusätzlich mit keinem der Dateien in der <tt>$KDEDIRS</tt>-Hierarchie verflochten ist. Das kann die Leistung spürbar verbessern, falls man einfach nur Werte aus einer einfachen Konfuguration liest und globale Werte keine Rolle spielen.

Zeile 15 erzeugt ein Konfigurationsobjekt unter Benutzung des {{class|KComponentData}}-Objekts das zu einem Plugin oder einer anderen Komponente gehört. Das Plugin kann verschiedene Ordner aufweisen, die in seinen {{class|KStandardDirs}} definiert sind und das ist eine Möglichkeit sich zu versichern, dass {{class|KConfig}} das respektiert.

Und schliesslich auf Zeile 18 erzeugen wir ein Konfigurationsobjekt, das nicht in der <tt>config</tt>-Ressource sondern in der <tt>data</tt>-Ressource existiert. Man kann kann auf diese Weise jede Ressource verwenden, von denen {{class|KStandardDirs}} Kenntnis hat, auch solche die während der Laufzeit hinzugefügt werden.

=== Spezielle Konfigurationsobjekte ===

Jede Anwendung hat sein eigenes Konfigurationsobjekt das den Namen benutzt, der von {{class|KAboutData}} bereitgestellt wird mit angehängtem "rc". Also hätte eine Anwendung mit dem Namen "myapp" das Standard-Konfigurationsobjekt "myapprc". Dieses Konfigurationsobjekt kann auf diese Weise aufgerufen werden:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// beachten sie, dass dies eigentlich ein KSharedConfig ist
// mehr über diese Klasse siehe weiter unten
KConfig* config = KGlobal::config();
}
</code>

Auf das Standard-Konfigurationsobjekt für die Anwendung wird zugegriffen, wenn kein Name definiert wurde, als das {{class|KConfig}}-Objekt erzeugt wurde. Also könnten wir stattdessen auch das tun:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

Zusätzlich könnte jede Komponente sein eigenes Konfigurationsobjekt haben. Auf dieses wird normalerweise durch die <tt>componentData()</tt> des Plugins zugegriffen, anstatt durch die <tt>{{class|KGlobal}}::mainComponent()</tt>.

Und schliesslich gibt es noch ein globales Konfigurationsobjekt, <tt>kdeglobals</tt>, das von jeder Anwendung verwendet wird. Es enthält Informationen wie die Standard-Tatenkombinationen für verschiedene Aktionen. Es wird in das Konfigurationsobjekt "gemischt" wenn der <tt>KConfig::IncludeGlobals</tt> Bitschalter dem {{class|KConfig}} Konstruktor übergeben wird, was standardmässig der Fall ist.

=== Allgemein nützliche Methoden ===

Um den momentanen Zustand des Konfigurationsobjektes zu speichern, rufen wir die <tt>sync()</tt>-Methode auf. Diese Methode wird also aufgerufen, wenn ein Objekt zerstört wird. Falls keine Änderungen gemacht wurden, oder die Ressource weist sich als nicht beschreibbar aus (Wenn der Benutzer zum Beispiel nicht genug Rechte hat, um die Datei zu bearbeiten), dann wird keine Beschäftigung der Festplatte hervorgerufen. <tt>sync()</tt> verschmilzt Änderungen die gleichzeitig von anderen Prozessen ausgeführt werden - lokale Änderungen haben aber trotzdem Vorrang.

Wenn wir sicher gehen wollen, dass wir die aktuellsten Werte von der Festplatte haben, dann rufen wir <tt>reparseConfiguration()</tt> auf, welches <tt>sync()</tt> aufruft und dann die Daten von der Festplatte aktualisiert.

Falls wir verhindern müssen, dass das Konfigurationsobjekt bereits gemachte Änderungen nicht auf die Festplatte speichert, müssen wir <tt>markAsClean()</tt> aufrufen. Ein besonderer Anwendungsfall ist es, die Konfiguration zum Festplatten-Zustand zurückzusetzen indem man <tt>markAsClean()</tt> gefolgt von <tt>reparseConfiguration()</tt> aufruft.

Alle Gruppen in einem Konfigurationsobjekt aufzurufen ist so einfach wie hier in diesem Code-Abschnitt <tt>groupList()</tt> aufzurufen.

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

Die {{class|KSharedConfig}} Klasse ist eine Referenz-gezählte Version von {{class|KConfig}}. Darum stellt es eine Möglichkeit bereit, das selbe Konfigurationsobjekt von unterschiedlichen Orten zu referenzieren ohne zusätzlich die Objekte trennen zu müssen oder sich um die Synchronisation des Schreibvorgangs zu kümmern, selbst wenn das Konfigurationsobjekt von verschiedenen Code-Pfaden aktualisiert wird.

Auf ein {{class|KSharedConfig}}-Objekt zuzugreifen ist so einfach wie das hier:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<tt>openConfig()</tt> nimmt die selben Parameter wie {{class|KConfig}}'s Konstruktoren, was es einem ermöglicht zu definieren, welche Konfigurationsdatei zu öffnen und Markierungen das Verschmelzen von nicht-<tt>config</tt>-Ressourcen zu kontrollieren.

Es wird grundsätzlich empfohlen {{class|KSharedConfig}} anstatt {{class|KConfig}} selbst zu benutzen, und auch das Objekt, das von {{class|KComponentData}} zurückgegeben wird ist in der Tat ein {{class|KSharedConfig}}-Objekt.

== KConfigGroup ==

Nun da wir ein Konfigurationsobjekt haben, ist der nächste Schritt es tatsächlich zu nutzen. Das erste, das wir tun müssen, ist zu bestimmen, auf welche Gruppe von Schlüssel-/Wertepaare wir in unserem Objekt zugreifen wollen. Wir tun das, indem wir ein KConfigGroup-Objekt erstellen.

<code cppqt n>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ...oder so ähnlich...
</code>

Man kann{{class|KConfigGroup}} {{class|KConfig}}- oder {{class|KSharedConfig}}-Objekte übergeben.

Konfigurationsgruppen können ebenfalls verschachtelt werden.

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Reading Entries ==

{{note (de)| Der Rest muss noch übersetzt werden}}

With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

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.

There are a couple of special read methods, including <tt>readPathEntry</tt> which returns a file system path. It is vital that one uses <tt>readPathEntry</tt> if it is a path as this enables such features as roaming profiles to work properly.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KConfig (de)

2008-01-02T17:00:04Z

Rememberme: /* KConfigGroup */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

{{improve (de)}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer- und Gruppenprofile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

{{note (de)| deserialization entgliedern? <br> <tt> "do not have to perform serialization and deserialization of objects themselves" </tt>}}

Anwendungen selbst müssen darum normalerweise Objekte nicht selber gliedern und entgliedern.

Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== Die KConfig Klasse ==

Das {{class|KConfig}}-Objekt wird benutzt um ein bestehendes Konfigurationsobjekt anzusteuern. Es gibt eine Reihe von Möglichkeiten ein Konfigurationsobjekt zu erstellen.

<code cppqt n>
// ein einfaches, altes lesen/schreiben Konfigurationsobjekt
KConfig config("myapprc");

// eine bestimmte Datei im Dateisystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// nicht mit globalen Werten verflochten
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// nicht mit globalen Werten orde der $KDEDIRS Hierarchie verflochten
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// Komponenten-spezifische Konfiguration, in diesem Fall ein Plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// Ausserhalb der normalen Konfigurations-Ressource
KConfig dataResource( "data", "myapp/somefile" );
</code>

{{note (de)|wie soll "merged" in den folgenden Fällen übersetzt werden? <br> <tt>"verschmolzen" oder "verflochten"</tt> <br> der Anwendung selber transparent" tönt auch nicht sehr gut}}

Das Kconfig Objekt, das wir auf Zeile 2 erstellen ist ein gewöhnliches Konfigurationsobjekt. Wir können Werte aus ihm lesen, neue Einträge schreiben und nach verschiedenen Eigenschaften des Objekts fragen. Dieses Objekt wird aus der Konfigurations-Ressource geladen, wie es durch {{class|KStandardDirs}} bestimmt wird, das heisst, dass jede Instanz des <tt>myapprc</tt>-Objekts in jedem der Ordner in der Konfigurations-Ressourcen-Hierarchie verschmolzen werden um die Werte zu erzeugen, die in diesem Objekt gesehen werden. So werden Systemweite und
pro-Benutzer/Gruppen Profile erstellt und unterstützt. Das alles geschieht der Anwendung selber transparent.

{{tip| Für mehr Informationen, wie das Verschmelzen funktioniert, siehe diesen Artikel über die [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Dateisystem Hierarchie]].}}

{{note (de)|Ist das so gemeint mit "expects an INI style file"<br> <tt> On line 6 we open a specific local file, this case /etc/kderc. This performs no merging of values and expects an INI style file.</tt>}}

Auf Zeile 6 öffnen wir eine bestimmte Lokale Datei, in diesem Fall {{path|/etc/kderc}}. Das führt kein verschmelzen von Werten aus und erwartet eine Datei im INI Format.

Zeile 9 erzeugt ein Konfigurationsobjekt, dass nicht mit dem globalen <tt>kdeglobals</tt>-Konfigurationsobjekt verflochten ist, während das Konfigurationsobjekt auf Zeile 12 zusätzlich mit keinem der Dateien in der <tt>$KDEDIRS</tt>-Hierarchie verflochten ist. Das kann die Leistung spürbar verbessern, falls man einfach nur Werte aus einer einfachen Konfuguration liest und globale Werte keine Rolle spielen.

Zeile 15 erzeugt ein Konfigurationsobjekt unter Benutzung des {{class|KComponentData}}-Objekts das zu einem Plugin oder einer anderen Komponente gehört. Das Plugin kann verschiedene Ordner aufweisen, die in seinen {{class|KStandardDirs}} definiert sind und das ist eine Möglichkeit sich zu versichern, dass {{class|KConfig}} das respektiert.

Und schliesslich auf Zeile 18 erzeugen wir ein Konfigurationsobjekt, das nicht in der <tt>config</tt>-Ressource sondern in der <tt>data</tt>-Ressource existiert. Man kann kann auf diese Weise jede Ressource verwenden, von denen {{class|KStandardDirs}} Kenntnis hat, auch solche die während der Laufzeit hinzugefügt werden.

=== Spezielle Konfigurationsobjekte ===

Jede Anwendung hat sein eigenes Konfigurationsobjekt das den Namen benutzt, der von {{class|KAboutData}} bereitgestellt wird mit angehängtem "rc". Also hätte eine Anwendung mit dem Namen "myapp" das Standard-Konfigurationsobjekt "myapprc". Dieses Konfigurationsobjekt kann auf diese Weise aufgerufen werden:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// beachten sie, dass dies eigentlich ein KSharedConfig ist
// mehr über diese Klasse siehe weiter unten
KConfig* config = KGlobal::config();
}
</code>

Auf das Standard-Konfigurationsobjekt für die Anwendung wird zugegriffen, wenn kein Name definiert wurde, als das {{class|KConfig}}-Objekt erzeugt wurde. Also könnten wir stattdessen auch das tun:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

Zusätzlich könnte jede Komponente sein eigenes Konfigurationsobjekt haben. Auf dieses wird normalerweise durch die <tt>componentData()</tt> des Plugins zugegriffen, anstatt durch die <tt>{{class|KGlobal}}::mainComponent()</tt>.

Und schliesslich gibt es noch ein globales Konfigurationsobjekt, <tt>kdeglobals</tt>, das von jeder Anwendung verwendet wird. Es enthält Informationen wie die Standard-Tatenkombinationen für verschiedene Aktionen. Es wird in das Konfigurationsobjekt "gemischt" wenn der <tt>KConfig::IncludeGlobals</tt> Bitschalter dem {{class|KConfig}} Konstruktor übergeben wird, was standardmässig der Fall ist.

=== Allgemein nützliche Methoden ===

Um den momentanen Zustand des Konfigurationsobjektes zu speichern, rufen wir die <tt>sync()</tt>-Methode auf. Diese Methode wird also aufgerufen, wenn ein Objekt zerstört wird. Falls keine Änderungen gemacht wurden, oder die Ressource weist sich als nicht beschreibbar aus (Wenn der Benutzer zum Beispiel nicht genug Rechte hat, um die Datei zu bearbeiten), dann wird keine Beschäftigung der Festplatte hervorgerufen. <tt>sync()</tt> verschmilzt Änderungen die gleichzeitig von anderen Prozessen ausgeführt werden - lokale Änderungen haben aber trotzdem Vorrang.

Wenn wir sicher gehen wollen, dass wir die aktuellsten Werte von der Festplatte haben, dann rufen wir <tt>reparseConfiguration()</tt> auf, welches <tt>sync()</tt> aufruft und dann die Daten von der Festplatte aktualisiert.

Falls wir verhindern müssen, dass das Konfigurationsobjekt bereits gemachte Änderungen nicht auf die Festplatte speichert, müssen wir <tt>markAsClean()</tt> aufrufen. Ein besonderer Anwendungsfall ist es, die Konfiguration zum Festplatten-Zustand zurückzusetzen indem man <tt>markAsClean()</tt> gefolgt von <tt>reparseConfiguration()</tt> aufruft.

Alle Gruppen in einem Konfigurationsobjekt aufzurufen ist so einfach wie hier in diesem Code-Abschnitt <tt>groupList()</tt> aufzurufen.

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

Die {{class|KSharedConfig}} Klasse ist eine Referenz-gezählte Version von {{class|KConfig}}. Darum stellt es eine Möglichkeit bereit, das selbe Konfigurationsobjekt von unterschiedlichen Orten zu referenzieren ohne zusätzlich die Objekte trennen zu müssen oder sich um die Synchronisation des Schreibvorgangs zu kümmern, selbst wenn das Konfigurationsobjekt von verschiedenen Code-Pfaden aktualisiert wird.

Auf ein {{class|KSharedConfig}}-Objekt zuzugreifen ist so einfach wie das hier:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<tt>openConfig()</tt> nimmt die selben Parameter wie {{class|KConfig}}'s Konstruktoren, was es einem ermöglicht zu definieren, welche Konfigurationsdatei zu öffnen und Markierungen das Verschmelzen von nicht-<tt>config</tt>-Ressourcen zu kontrollieren.

Es wird grundsätzlich empfohlen {{class|KSharedConfig}} anstatt {{class|KConfig}} selbst zu benutzen, und auch das Objekt, das von {{class|KComponentData}} zurückgegeben wird ist in der Tat ein {{class|KSharedConfig}}-Objekt.

== KConfigGroup ==

Nun da wir ein Konfigurationsobjekt haben, ist der nächste Schritt es tatsächlich zu nutzen. Das erste, das wir tun müssen, ist zu bestimmen, auf welche Gruppe von Schlüssel-/Wertepaare wir in unserem Objekt zugreifen wollen. Wir tun das, indem wir ein KConfigGroup-Objekt erstellen.

<code cppqt n>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ...oder so ähnlich...
</code>

Man kann{{class|KConfigGroup}} {{class|KConfig}}- oder {{class|KSharedConfig}}-Objekte übergeben.

Konfigurationsgruppen können ebenfalls verschachtelt werden.

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Reading Entries ==

With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

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.

There are a couple of special read methods, including <tt>readPathEntry</tt> which returns a file system path. It is vital that one uses <tt>readPathEntry</tt> if it is a path as this enables such features as roaming profiles to work properly.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KConfig (de)

2008-01-02T16:53:54Z

Rememberme: /* KSharedConfig */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

{{improve (de)}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer- und Gruppenprofile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

{{note (de)| deserialization entgliedern? <br> <tt> "do not have to perform serialization and deserialization of objects themselves" </tt>}}

Anwendungen selbst müssen darum normalerweise Objekte nicht selber gliedern und entgliedern.

Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== Die KConfig Klasse ==

Das {{class|KConfig}}-Objekt wird benutzt um ein bestehendes Konfigurationsobjekt anzusteuern. Es gibt eine Reihe von Möglichkeiten ein Konfigurationsobjekt zu erstellen.

<code cppqt n>
// ein einfaches, altes lesen/schreiben Konfigurationsobjekt
KConfig config("myapprc");

// eine bestimmte Datei im Dateisystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// nicht mit globalen Werten verflochten
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// nicht mit globalen Werten orde der $KDEDIRS Hierarchie verflochten
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// Komponenten-spezifische Konfiguration, in diesem Fall ein Plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// Ausserhalb der normalen Konfigurations-Ressource
KConfig dataResource( "data", "myapp/somefile" );
</code>

{{note (de)|wie soll "merged" in den folgenden Fällen übersetzt werden? <br> <tt>"verschmolzen" oder "verflochten"</tt> <br> der Anwendung selber transparent" tönt auch nicht sehr gut}}

Das Kconfig Objekt, das wir auf Zeile 2 erstellen ist ein gewöhnliches Konfigurationsobjekt. Wir können Werte aus ihm lesen, neue Einträge schreiben und nach verschiedenen Eigenschaften des Objekts fragen. Dieses Objekt wird aus der Konfigurations-Ressource geladen, wie es durch {{class|KStandardDirs}} bestimmt wird, das heisst, dass jede Instanz des <tt>myapprc</tt>-Objekts in jedem der Ordner in der Konfigurations-Ressourcen-Hierarchie verschmolzen werden um die Werte zu erzeugen, die in diesem Objekt gesehen werden. So werden Systemweite und
pro-Benutzer/Gruppen Profile erstellt und unterstützt. Das alles geschieht der Anwendung selber transparent.

{{tip| Für mehr Informationen, wie das Verschmelzen funktioniert, siehe diesen Artikel über die [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Dateisystem Hierarchie]].}}

{{note (de)|Ist das so gemeint mit "expects an INI style file"<br> <tt> On line 6 we open a specific local file, this case /etc/kderc. This performs no merging of values and expects an INI style file.</tt>}}

Auf Zeile 6 öffnen wir eine bestimmte Lokale Datei, in diesem Fall {{path|/etc/kderc}}. Das führt kein verschmelzen von Werten aus und erwartet eine Datei im INI Format.

Zeile 9 erzeugt ein Konfigurationsobjekt, dass nicht mit dem globalen <tt>kdeglobals</tt>-Konfigurationsobjekt verflochten ist, während das Konfigurationsobjekt auf Zeile 12 zusätzlich mit keinem der Dateien in der <tt>$KDEDIRS</tt>-Hierarchie verflochten ist. Das kann die Leistung spürbar verbessern, falls man einfach nur Werte aus einer einfachen Konfuguration liest und globale Werte keine Rolle spielen.

Zeile 15 erzeugt ein Konfigurationsobjekt unter Benutzung des {{class|KComponentData}}-Objekts das zu einem Plugin oder einer anderen Komponente gehört. Das Plugin kann verschiedene Ordner aufweisen, die in seinen {{class|KStandardDirs}} definiert sind und das ist eine Möglichkeit sich zu versichern, dass {{class|KConfig}} das respektiert.

Und schliesslich auf Zeile 18 erzeugen wir ein Konfigurationsobjekt, das nicht in der <tt>config</tt>-Ressource sondern in der <tt>data</tt>-Ressource existiert. Man kann kann auf diese Weise jede Ressource verwenden, von denen {{class|KStandardDirs}} Kenntnis hat, auch solche die während der Laufzeit hinzugefügt werden.

=== Spezielle Konfigurationsobjekte ===

Jede Anwendung hat sein eigenes Konfigurationsobjekt das den Namen benutzt, der von {{class|KAboutData}} bereitgestellt wird mit angehängtem "rc". Also hätte eine Anwendung mit dem Namen "myapp" das Standard-Konfigurationsobjekt "myapprc". Dieses Konfigurationsobjekt kann auf diese Weise aufgerufen werden:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// beachten sie, dass dies eigentlich ein KSharedConfig ist
// mehr über diese Klasse siehe weiter unten
KConfig* config = KGlobal::config();
}
</code>

Auf das Standard-Konfigurationsobjekt für die Anwendung wird zugegriffen, wenn kein Name definiert wurde, als das {{class|KConfig}}-Objekt erzeugt wurde. Also könnten wir stattdessen auch das tun:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

Zusätzlich könnte jede Komponente sein eigenes Konfigurationsobjekt haben. Auf dieses wird normalerweise durch die <tt>componentData()</tt> des Plugins zugegriffen, anstatt durch die <tt>{{class|KGlobal}}::mainComponent()</tt>.

Und schliesslich gibt es noch ein globales Konfigurationsobjekt, <tt>kdeglobals</tt>, das von jeder Anwendung verwendet wird. Es enthält Informationen wie die Standard-Tatenkombinationen für verschiedene Aktionen. Es wird in das Konfigurationsobjekt "gemischt" wenn der <tt>KConfig::IncludeGlobals</tt> Bitschalter dem {{class|KConfig}} Konstruktor übergeben wird, was standardmässig der Fall ist.

=== Allgemein nützliche Methoden ===

Um den momentanen Zustand des Konfigurationsobjektes zu speichern, rufen wir die <tt>sync()</tt>-Methode auf. Diese Methode wird also aufgerufen, wenn ein Objekt zerstört wird. Falls keine Änderungen gemacht wurden, oder die Ressource weist sich als nicht beschreibbar aus (Wenn der Benutzer zum Beispiel nicht genug Rechte hat, um die Datei zu bearbeiten), dann wird keine Beschäftigung der Festplatte hervorgerufen. <tt>sync()</tt> verschmilzt Änderungen die gleichzeitig von anderen Prozessen ausgeführt werden - lokale Änderungen haben aber trotzdem Vorrang.

Wenn wir sicher gehen wollen, dass wir die aktuellsten Werte von der Festplatte haben, dann rufen wir <tt>reparseConfiguration()</tt> auf, welches <tt>sync()</tt> aufruft und dann die Daten von der Festplatte aktualisiert.

Falls wir verhindern müssen, dass das Konfigurationsobjekt bereits gemachte Änderungen nicht auf die Festplatte speichert, müssen wir <tt>markAsClean()</tt> aufrufen. Ein besonderer Anwendungsfall ist es, die Konfiguration zum Festplatten-Zustand zurückzusetzen indem man <tt>markAsClean()</tt> gefolgt von <tt>reparseConfiguration()</tt> aufruft.

Alle Gruppen in einem Konfigurationsobjekt aufzurufen ist so einfach wie hier in diesem Code-Abschnitt <tt>groupList()</tt> aufzurufen.

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

Die {{class|KSharedConfig}} Klasse ist eine Referenz-gezählte Version von {{class|KConfig}}. Darum stellt es eine Möglichkeit bereit, das selbe Konfigurationsobjekt von unterschiedlichen Orten zu referenzieren ohne zusätzlich die Objekte trennen zu müssen oder sich um die Synchronisation des Schreibvorgangs zu kümmern, selbst wenn das Konfigurationsobjekt von verschiedenen Code-Pfaden aktualisiert wird.

Auf ein {{class|KSharedConfig}}-Objekt zuzugreifen ist so einfach wie das hier:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<tt>openConfig()</tt> nimmt die selben Parameter wie {{class|KConfig}}'s Konstruktoren, was es einem ermöglicht zu definieren, welche Konfigurationsdatei zu öffnen und Markierungen das Verschmelzen von nicht-<tt>config</tt>-Ressourcen zu kontrollieren.

Es wird grundsätzlich empfohlen {{class|KSharedConfig}} anstatt {{class|KConfig}} selbst zu benutzen, und auch das Objekt, das von {{class|KComponentData}} zurückgegeben wird ist in der Tat ein {{class|KSharedConfig}}-Objekt.

== KConfigGroup ==

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>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ... or a bit differently ...
</code>

You can pass {{class|KConfig}} or {{class|KSharedConfig}} objects to {{class|KConfigGroup}}.

Config groups can be nested as well:

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Reading Entries ==

With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

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.

There are a couple of special read methods, including <tt>readPathEntry</tt> which returns a file system path. It is vital that one uses <tt>readPathEntry</tt> if it is a path as this enables such features as roaming profiles to work properly.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KConfig (de)

2008-01-02T16:34:54Z

Rememberme: /* Allgemein nützliche Methoden */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

{{improve (de)}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer- und Gruppenprofile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

{{note (de)| deserialization entgliedern? <br> <tt> "do not have to perform serialization and deserialization of objects themselves" </tt>}}

Anwendungen selbst müssen darum normalerweise Objekte nicht selber gliedern und entgliedern.

Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== Die KConfig Klasse ==

Das {{class|KConfig}}-Objekt wird benutzt um ein bestehendes Konfigurationsobjekt anzusteuern. Es gibt eine Reihe von Möglichkeiten ein Konfigurationsobjekt zu erstellen.

<code cppqt n>
// ein einfaches, altes lesen/schreiben Konfigurationsobjekt
KConfig config("myapprc");

// eine bestimmte Datei im Dateisystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// nicht mit globalen Werten verflochten
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// nicht mit globalen Werten orde der $KDEDIRS Hierarchie verflochten
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// Komponenten-spezifische Konfiguration, in diesem Fall ein Plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// Ausserhalb der normalen Konfigurations-Ressource
KConfig dataResource( "data", "myapp/somefile" );
</code>

{{note (de)|wie soll "merged" in den folgenden Fällen übersetzt werden? <br> <tt>"verschmolzen" oder "verflochten"</tt> <br> der Anwendung selber transparent" tönt auch nicht sehr gut}}

Das Kconfig Objekt, das wir auf Zeile 2 erstellen ist ein gewöhnliches Konfigurationsobjekt. Wir können Werte aus ihm lesen, neue Einträge schreiben und nach verschiedenen Eigenschaften des Objekts fragen. Dieses Objekt wird aus der Konfigurations-Ressource geladen, wie es durch {{class|KStandardDirs}} bestimmt wird, das heisst, dass jede Instanz des <tt>myapprc</tt>-Objekts in jedem der Ordner in der Konfigurations-Ressourcen-Hierarchie verschmolzen werden um die Werte zu erzeugen, die in diesem Objekt gesehen werden. So werden Systemweite und
pro-Benutzer/Gruppen Profile erstellt und unterstützt. Das alles geschieht der Anwendung selber transparent.

{{tip| Für mehr Informationen, wie das Verschmelzen funktioniert, siehe diesen Artikel über die [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Dateisystem Hierarchie]].}}

{{note (de)|Ist das so gemeint mit "expects an INI style file"<br> <tt> On line 6 we open a specific local file, this case /etc/kderc. This performs no merging of values and expects an INI style file.</tt>}}

Auf Zeile 6 öffnen wir eine bestimmte Lokale Datei, in diesem Fall {{path|/etc/kderc}}. Das führt kein verschmelzen von Werten aus und erwartet eine Datei im INI Format.

Zeile 9 erzeugt ein Konfigurationsobjekt, dass nicht mit dem globalen <tt>kdeglobals</tt>-Konfigurationsobjekt verflochten ist, während das Konfigurationsobjekt auf Zeile 12 zusätzlich mit keinem der Dateien in der <tt>$KDEDIRS</tt>-Hierarchie verflochten ist. Das kann die Leistung spürbar verbessern, falls man einfach nur Werte aus einer einfachen Konfuguration liest und globale Werte keine Rolle spielen.

Zeile 15 erzeugt ein Konfigurationsobjekt unter Benutzung des {{class|KComponentData}}-Objekts das zu einem Plugin oder einer anderen Komponente gehört. Das Plugin kann verschiedene Ordner aufweisen, die in seinen {{class|KStandardDirs}} definiert sind und das ist eine Möglichkeit sich zu versichern, dass {{class|KConfig}} das respektiert.

Und schliesslich auf Zeile 18 erzeugen wir ein Konfigurationsobjekt, das nicht in der <tt>config</tt>-Ressource sondern in der <tt>data</tt>-Ressource existiert. Man kann kann auf diese Weise jede Ressource verwenden, von denen {{class|KStandardDirs}} Kenntnis hat, auch solche die während der Laufzeit hinzugefügt werden.

=== Spezielle Konfigurationsobjekte ===

Jede Anwendung hat sein eigenes Konfigurationsobjekt das den Namen benutzt, der von {{class|KAboutData}} bereitgestellt wird mit angehängtem "rc". Also hätte eine Anwendung mit dem Namen "myapp" das Standard-Konfigurationsobjekt "myapprc". Dieses Konfigurationsobjekt kann auf diese Weise aufgerufen werden:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// beachten sie, dass dies eigentlich ein KSharedConfig ist
// mehr über diese Klasse siehe weiter unten
KConfig* config = KGlobal::config();
}
</code>

Auf das Standard-Konfigurationsobjekt für die Anwendung wird zugegriffen, wenn kein Name definiert wurde, als das {{class|KConfig}}-Objekt erzeugt wurde. Also könnten wir stattdessen auch das tun:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

Zusätzlich könnte jede Komponente sein eigenes Konfigurationsobjekt haben. Auf dieses wird normalerweise durch die <tt>componentData()</tt> des Plugins zugegriffen, anstatt durch die <tt>{{class|KGlobal}}::mainComponent()</tt>.

Und schliesslich gibt es noch ein globales Konfigurationsobjekt, <tt>kdeglobals</tt>, das von jeder Anwendung verwendet wird. Es enthält Informationen wie die Standard-Tatenkombinationen für verschiedene Aktionen. Es wird in das Konfigurationsobjekt "gemischt" wenn der <tt>KConfig::IncludeGlobals</tt> Bitschalter dem {{class|KConfig}} Konstruktor übergeben wird, was standardmässig der Fall ist.

=== Allgemein nützliche Methoden ===

Um den momentanen Zustand des Konfigurationsobjektes zu speichern, rufen wir die <tt>sync()</tt>-Methode auf. Diese Methode wird also aufgerufen, wenn ein Objekt zerstört wird. Falls keine Änderungen gemacht wurden, oder die Ressource weist sich als nicht beschreibbar aus (Wenn der Benutzer zum Beispiel nicht genug Rechte hat, um die Datei zu bearbeiten), dann wird keine Beschäftigung der Festplatte hervorgerufen. <tt>sync()</tt> verschmilzt Änderungen die gleichzeitig von anderen Prozessen ausgeführt werden - lokale Änderungen haben aber trotzdem Vorrang.

Wenn wir sicher gehen wollen, dass wir die aktuellsten Werte von der Festplatte haben, dann rufen wir <tt>reparseConfiguration()</tt> auf, welches <tt>sync()</tt> aufruft und dann die Daten von der Festplatte aktualisiert.

Falls wir verhindern müssen, dass das Konfigurationsobjekt bereits gemachte Änderungen nicht auf die Festplatte speichert, müssen wir <tt>markAsClean()</tt> aufrufen. Ein besonderer Anwendungsfall ist es, die Konfiguration zum Festplatten-Zustand zurückzusetzen indem man <tt>markAsClean()</tt> gefolgt von <tt>reparseConfiguration()</tt> aufruft.

Alle Gruppen in einem Konfigurationsobjekt aufzurufen ist so einfach wie hier in diesem Code-Abschnitt <tt>groupList()</tt> aufzurufen.

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

The {{class|KSharedConfig}} class is a reference counted version of {{class|KConfig}}. It thus provides a way to reference the same configuration object from multiple places in your application without the extra overhead of separate objects or concerns about syncronizing writes to disk even if the configuration object is updated from multiple code paths.

Accessing a {{class|KSharedConfig}} object is as easy as this:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<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.

{{class|KSharedConfig}} is generally recommended over using {{class|KConfig}} itself, and the object returned from {{class|KComponentData}} is indeed a {{class|KSharedConfig}} object.

== KConfigGroup ==

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>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ... or a bit differently ...
</code>

You can pass {{class|KConfig}} or {{class|KSharedConfig}} objects to {{class|KConfigGroup}}.

Config groups can be nested as well:

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Reading Entries ==

With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

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.

There are a couple of special read methods, including <tt>readPathEntry</tt> which returns a file system path. It is vital that one uses <tt>readPathEntry</tt> if it is a path as this enables such features as roaming profiles to work properly.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KConfig (de)

2008-01-02T16:34:09Z

Rememberme: /* Spezielle Konfigurationsobjekte */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

{{improve (de)}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer- und Gruppenprofile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

{{note (de)| deserialization entgliedern? <br> <tt> "do not have to perform serialization and deserialization of objects themselves" </tt>}}

Anwendungen selbst müssen darum normalerweise Objekte nicht selber gliedern und entgliedern.

Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== Die KConfig Klasse ==

Das {{class|KConfig}}-Objekt wird benutzt um ein bestehendes Konfigurationsobjekt anzusteuern. Es gibt eine Reihe von Möglichkeiten ein Konfigurationsobjekt zu erstellen.

<code cppqt n>
// ein einfaches, altes lesen/schreiben Konfigurationsobjekt
KConfig config("myapprc");

// eine bestimmte Datei im Dateisystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// nicht mit globalen Werten verflochten
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// nicht mit globalen Werten orde der $KDEDIRS Hierarchie verflochten
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// Komponenten-spezifische Konfiguration, in diesem Fall ein Plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// Ausserhalb der normalen Konfigurations-Ressource
KConfig dataResource( "data", "myapp/somefile" );
</code>

{{note (de)|wie soll "merged" in den folgenden Fällen übersetzt werden? <br> <tt>"verschmolzen" oder "verflochten"</tt> <br> der Anwendung selber transparent" tönt auch nicht sehr gut}}

Das Kconfig Objekt, das wir auf Zeile 2 erstellen ist ein gewöhnliches Konfigurationsobjekt. Wir können Werte aus ihm lesen, neue Einträge schreiben und nach verschiedenen Eigenschaften des Objekts fragen. Dieses Objekt wird aus der Konfigurations-Ressource geladen, wie es durch {{class|KStandardDirs}} bestimmt wird, das heisst, dass jede Instanz des <tt>myapprc</tt>-Objekts in jedem der Ordner in der Konfigurations-Ressourcen-Hierarchie verschmolzen werden um die Werte zu erzeugen, die in diesem Objekt gesehen werden. So werden Systemweite und
pro-Benutzer/Gruppen Profile erstellt und unterstützt. Das alles geschieht der Anwendung selber transparent.

{{tip| Für mehr Informationen, wie das Verschmelzen funktioniert, siehe diesen Artikel über die [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Dateisystem Hierarchie]].}}

{{note (de)|Ist das so gemeint mit "expects an INI style file"<br> <tt> On line 6 we open a specific local file, this case /etc/kderc. This performs no merging of values and expects an INI style file.</tt>}}

Auf Zeile 6 öffnen wir eine bestimmte Lokale Datei, in diesem Fall {{path|/etc/kderc}}. Das führt kein verschmelzen von Werten aus und erwartet eine Datei im INI Format.

Zeile 9 erzeugt ein Konfigurationsobjekt, dass nicht mit dem globalen <tt>kdeglobals</tt>-Konfigurationsobjekt verflochten ist, während das Konfigurationsobjekt auf Zeile 12 zusätzlich mit keinem der Dateien in der <tt>$KDEDIRS</tt>-Hierarchie verflochten ist. Das kann die Leistung spürbar verbessern, falls man einfach nur Werte aus einer einfachen Konfuguration liest und globale Werte keine Rolle spielen.

Zeile 15 erzeugt ein Konfigurationsobjekt unter Benutzung des {{class|KComponentData}}-Objekts das zu einem Plugin oder einer anderen Komponente gehört. Das Plugin kann verschiedene Ordner aufweisen, die in seinen {{class|KStandardDirs}} definiert sind und das ist eine Möglichkeit sich zu versichern, dass {{class|KConfig}} das respektiert.

Und schliesslich auf Zeile 18 erzeugen wir ein Konfigurationsobjekt, das nicht in der <tt>config</tt>-Ressource sondern in der <tt>data</tt>-Ressource existiert. Man kann kann auf diese Weise jede Ressource verwenden, von denen {{class|KStandardDirs}} Kenntnis hat, auch solche die während der Laufzeit hinzugefügt werden.

=== Spezielle Konfigurationsobjekte ===

Jede Anwendung hat sein eigenes Konfigurationsobjekt das den Namen benutzt, der von {{class|KAboutData}} bereitgestellt wird mit angehängtem "rc". Also hätte eine Anwendung mit dem Namen "myapp" das Standard-Konfigurationsobjekt "myapprc". Dieses Konfigurationsobjekt kann auf diese Weise aufgerufen werden:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// beachten sie, dass dies eigentlich ein KSharedConfig ist
// mehr über diese Klasse siehe weiter unten
KConfig* config = KGlobal::config();
}
</code>

Auf das Standard-Konfigurationsobjekt für die Anwendung wird zugegriffen, wenn kein Name definiert wurde, als das {{class|KConfig}}-Objekt erzeugt wurde. Also könnten wir stattdessen auch das tun:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

Zusätzlich könnte jede Komponente sein eigenes Konfigurationsobjekt haben. Auf dieses wird normalerweise durch die <tt>componentData()</tt> des Plugins zugegriffen, anstatt durch die <tt>{{class|KGlobal}}::mainComponent()</tt>.

Und schliesslich gibt es noch ein globales Konfigurationsobjekt, <tt>kdeglobals</tt>, das von jeder Anwendung verwendet wird. Es enthält Informationen wie die Standard-Tatenkombinationen für verschiedene Aktionen. Es wird in das Konfigurationsobjekt "gemischt" wenn der <tt>KConfig::IncludeGlobals</tt> Bitschalter dem {{class|KConfig}} Konstruktor übergeben wird, was standardmässig der Fall ist.

=== Allgemein nützliche Methoden ===

Um den momentanen Zustand des Konfigurationsobjektes zu speichern, rufen wir die <tt>sync()</tt-Methode auf. Diese Methode wird also aufgerufen, wenn ein Objekt zerstört wird. Falls keine Änderungen gemacht wurden, oder die Ressource weist sich als nicht beschreibbar aus (Wenn der Benutzer zum Beispiel nicht genug Rechte hat, um die Datei zu bearbeiten), dann wird keine Beschäftigung der Festplatte hervorgerufen. <tt>sync()</tt> verschmilzt Änderungen die gleichzeitig von anderen Prozessen ausgeführt werden - lokale Änderungen haben aber trotzdem Vorrang.

Wenn wir sicher gehen wollen, dass wir die aktuellsten Werte von der Festplatte haben, dann rufen wir <tt>reparseConfiguration()</tt> auf, welches <tt>sync()</tt> aufruft und dann die Daten von der Festplatte aktualisiert.

Falls wir verhindern müssen, dass das Konfigurationsobjekt bereits gemachte Änderungen nicht auf die Festplatte speichert, müssen wir <tt>markAsClean()</tt> aufrufen. Ein besonderer Anwendungsfall ist es, die Konfiguration zum Festplatten-Zustand zurückzusetzen indem man <tt>markAsClean()</tt> gefolgt von <tt>reparseConfiguration()</tt> aufruft.

Alle Gruppen in einem Konfigurationsobjekt aufzurufen ist so einfach wie hier in diesem Code-Abschnitt <tt>groupList()</tt> aufzurufen.

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

The {{class|KSharedConfig}} class is a reference counted version of {{class|KConfig}}. It thus provides a way to reference the same configuration object from multiple places in your application without the extra overhead of separate objects or concerns about syncronizing writes to disk even if the configuration object is updated from multiple code paths.

Accessing a {{class|KSharedConfig}} object is as easy as this:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<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.

{{class|KSharedConfig}} is generally recommended over using {{class|KConfig}} itself, and the object returned from {{class|KComponentData}} is indeed a {{class|KSharedConfig}} object.

== KConfigGroup ==

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>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ... or a bit differently ...
</code>

You can pass {{class|KConfig}} or {{class|KSharedConfig}} objects to {{class|KConfigGroup}}.

Config groups can be nested as well:

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Reading Entries ==

With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

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.

There are a couple of special read methods, including <tt>readPathEntry</tt> which returns a file system path. It is vital that one uses <tt>readPathEntry</tt> if it is a path as this enables such features as roaming profiles to work properly.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KConfig (de)

2008-01-02T16:33:44Z

Rememberme: /* Die KConfig Klasse */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

{{improve (de)}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer- und Gruppenprofile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

{{note (de)| deserialization entgliedern? <br> <tt> "do not have to perform serialization and deserialization of objects themselves" </tt>}}

Anwendungen selbst müssen darum normalerweise Objekte nicht selber gliedern und entgliedern.

Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== Die KConfig Klasse ==

Das {{class|KConfig}}-Objekt wird benutzt um ein bestehendes Konfigurationsobjekt anzusteuern. Es gibt eine Reihe von Möglichkeiten ein Konfigurationsobjekt zu erstellen.

<code cppqt n>
// ein einfaches, altes lesen/schreiben Konfigurationsobjekt
KConfig config("myapprc");

// eine bestimmte Datei im Dateisystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// nicht mit globalen Werten verflochten
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// nicht mit globalen Werten orde der $KDEDIRS Hierarchie verflochten
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// Komponenten-spezifische Konfiguration, in diesem Fall ein Plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// Ausserhalb der normalen Konfigurations-Ressource
KConfig dataResource( "data", "myapp/somefile" );
</code>

{{note (de)|wie soll "merged" in den folgenden Fällen übersetzt werden? <br> <tt>"verschmolzen" oder "verflochten"</tt> <br> der Anwendung selber transparent" tönt auch nicht sehr gut}}

Das Kconfig Objekt, das wir auf Zeile 2 erstellen ist ein gewöhnliches Konfigurationsobjekt. Wir können Werte aus ihm lesen, neue Einträge schreiben und nach verschiedenen Eigenschaften des Objekts fragen. Dieses Objekt wird aus der Konfigurations-Ressource geladen, wie es durch {{class|KStandardDirs}} bestimmt wird, das heisst, dass jede Instanz des <tt>myapprc</tt>-Objekts in jedem der Ordner in der Konfigurations-Ressourcen-Hierarchie verschmolzen werden um die Werte zu erzeugen, die in diesem Objekt gesehen werden. So werden Systemweite und
pro-Benutzer/Gruppen Profile erstellt und unterstützt. Das alles geschieht der Anwendung selber transparent.

{{tip| Für mehr Informationen, wie das Verschmelzen funktioniert, siehe diesen Artikel über die [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Dateisystem Hierarchie]].}}

{{note (de)|Ist das so gemeint mit "expects an INI style file"<br> <tt> On line 6 we open a specific local file, this case /etc/kderc. This performs no merging of values and expects an INI style file.</tt>}}

Auf Zeile 6 öffnen wir eine bestimmte Lokale Datei, in diesem Fall {{path|/etc/kderc}}. Das führt kein verschmelzen von Werten aus und erwartet eine Datei im INI Format.

Zeile 9 erzeugt ein Konfigurationsobjekt, dass nicht mit dem globalen <tt>kdeglobals</tt>-Konfigurationsobjekt verflochten ist, während das Konfigurationsobjekt auf Zeile 12 zusätzlich mit keinem der Dateien in der <tt>$KDEDIRS</tt>-Hierarchie verflochten ist. Das kann die Leistung spürbar verbessern, falls man einfach nur Werte aus einer einfachen Konfuguration liest und globale Werte keine Rolle spielen.

Zeile 15 erzeugt ein Konfigurationsobjekt unter Benutzung des {{class|KComponentData}}-Objekts das zu einem Plugin oder einer anderen Komponente gehört. Das Plugin kann verschiedene Ordner aufweisen, die in seinen {{class|KStandardDirs}} definiert sind und das ist eine Möglichkeit sich zu versichern, dass {{class|KConfig}} das respektiert.

Und schliesslich auf Zeile 18 erzeugen wir ein Konfigurationsobjekt, das nicht in der <tt>config</tt>-Ressource sondern in der <tt>data</tt>-Ressource existiert. Man kann kann auf diese Weise jede Ressource verwenden, von denen {{class|KStandardDirs}} Kenntnis hat, auch solche die während der Laufzeit hinzugefügt werden.

=== Spezielle Konfigurationsobjekte ===

Jede Anwendung hat sein eigenes Konfigurationsobjekt das den Namen benutzt, der von {{class|KAboutData}} bereitgestellt wird mit angehängtem "rc". Also hätte eine Anwendung mit dem Namen "myapp" das Standard-Konfigurationsobjekt "myapprc". Dieses Konfigurationsobjekt kann auf diese Weise aufgerufen werden:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// beachten sie, dass dies eigentlich ein KSharedConfig ist
// mehr über diese Klasse siehe weiter unten
KConfig* config = KGlobal::config();
}
</code>

Auf das Standard-Konfigurationsobjekt für die Anwendung wird zugegriffen, wenn kein Name definiert wurde, als das {{class|KConfig}}-Objekt erzeugt wurde. Also könnten wir stattdessen auch das tun:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

Zusätzlich könnte jede Komponente sein eigenes Konfigurationsobjekt haben. Auf dieses wird normalerweise durch die <tt>componentData()</tt> des Plugins zugegriffen, anstatt durch die <tt>{{class|KGlobal}}::mainComponent()</tt>.

Und schliesslich gibt es noch ein globales Konfigurationsobjekt, <tt>kdeglobals</tt>, das von jeder Anwendung verwendet wird. Es enthält Informationen wie die Standard-Tatenkombinationen für verschiedene Aktionen. Es wird in das Konfigurationsobjekt "gemischt" wenn der <tt>KConfig::IncludeGlobals</tt> Bitschalter dem {{class|KConfig}} Konstruktor übergeben wird, was standardmässig der Fall ist.

{{note (de)|Der Rest muss noch übersetzt werden}}

=== Allgemein nützliche Methoden ===

Um den momentanen Zustand des Konfigurationsobjektes zu speichern, rufen wir die <tt>sync()</tt-Methode auf. Diese Methode wird also aufgerufen, wenn ein Objekt zerstört wird. Falls keine Änderungen gemacht wurden, oder die Ressource weist sich als nicht beschreibbar aus (Wenn der Benutzer zum Beispiel nicht genug Rechte hat, um die Datei zu bearbeiten), dann wird keine Beschäftigung der Festplatte hervorgerufen. <tt>sync()</tt> verschmilzt Änderungen die gleichzeitig von anderen Prozessen ausgeführt werden - lokale Änderungen haben aber trotzdem Vorrang.

Wenn wir sicher gehen wollen, dass wir die aktuellsten Werte von der Festplatte haben, dann rufen wir <tt>reparseConfiguration()</tt> auf, welches <tt>sync()</tt> aufruft und dann die Daten von der Festplatte aktualisiert.

Falls wir verhindern müssen, dass das Konfigurationsobjekt bereits gemachte Änderungen nicht auf die Festplatte speichert, müssen wir <tt>markAsClean()</tt> aufrufen. Ein besonderer Anwendungsfall ist es, die Konfiguration zum Festplatten-Zustand zurückzusetzen indem man <tt>markAsClean()</tt> gefolgt von <tt>reparseConfiguration()</tt> aufruft.

Alle Gruppen in einem Konfigurationsobjekt aufzurufen ist so einfach wie hier in diesem Code-Abschnitt <tt>groupList()</tt> aufzurufen.

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

The {{class|KSharedConfig}} class is a reference counted version of {{class|KConfig}}. It thus provides a way to reference the same configuration object from multiple places in your application without the extra overhead of separate objects or concerns about syncronizing writes to disk even if the configuration object is updated from multiple code paths.

Accessing a {{class|KSharedConfig}} object is as easy as this:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<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.

{{class|KSharedConfig}} is generally recommended over using {{class|KConfig}} itself, and the object returned from {{class|KComponentData}} is indeed a {{class|KSharedConfig}} object.

== KConfigGroup ==

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>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ... or a bit differently ...
</code>

You can pass {{class|KConfig}} or {{class|KSharedConfig}} objects to {{class|KConfigGroup}}.

Config groups can be nested as well:

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Reading Entries ==

With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

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.

There are a couple of special read methods, including <tt>readPathEntry</tt> which returns a file system path. It is vital that one uses <tt>readPathEntry</tt> if it is a path as this enables such features as roaming profiles to work properly.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KConfig (de)

2008-01-02T13:07:57Z

Rememberme: /* Die KConfig Klasse */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

{{improve (de)}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer- und Gruppenprofile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

{{note (de)| deserialization entgliedern? <br> <tt> "do not have to perform serialization and deserialization of objects themselves" </tt>}}

Anwendungen selbst müssen darum normalerweise Objekte nicht selber gliedern und entgliedern.

Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== Die KConfig Klasse ==

Das {{class|KConfig}}-Objekt wird benutzt um ein bestehendes Konfigurationsobjekt anzusteuern. Es gibt eine Reihe von Möglichkeiten ein Konfigurationsobjekt zu erstellen.

<code cppqt n>
// ein einfaches, altes lesen/schreiben Konfigurationsobjekt
KConfig config("myapprc");

// eine bestimmte Datei im Dateisystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// nicht mit globalen Werten verflochten
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// nicht mit globalen Werten orde der $KDEDIRS Hierarchie verflochten
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// Komponenten-spezifische Konfiguration, in diesem Fall ein Plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// Ausserhalb der normalen Konfigurations-Ressource
KConfig dataResource( "data", "myapp/somefile" );
</code>

{{note (de)|wie soll "merged" in den folgenden Fällen übersetzt werden? <br> <tt>"verschmolzen" oder "verflochten"</tt> <br> der Anwendung selber transparent" tönt auch nicht sehr gut}}

Das Kconfig Objekt, das wir auf Zeile 2 erstellen ist ein gewöhnliches Konfigurationsobjekt. Wir können Werte aus ihm lesen, neue Einträge schreiben und nach verschiedenen Eigenschaften des Objekts fragen. Dieses Objekt wird aus der Konfigurations-Ressource geladen, wie es durch {{class|KStandardDirs}} bestimmt wird, das heisst, dass jede Instanz des <tt>myapprc</tt>-Objekts in jedem der Ordner in der Konfigurations-Ressourcen-Hierarchie verschmolzen werden um die Werte zu erzeugen, die in diesem Objekt gesehen werden. So werden Systemweite und
pro-Benutzer/Gruppen Profile erstellt und unterstützt. Das alles geschieht der Anwendung selber transparent.

{{tip| Für mehr Informationen, wie das Verschmelzen funktioniert, siehe diesen Artikel über die [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Dateisystem Hierarchie]].}}

{{note (de)|Ist das so gemeint mit "expects an INI style file"<br> <tt> On line 6 we open a specific local file, this case /etc/kderc. This performs no merging of values and expects an INI style file.</tt>}}

Auf Zeile 6 öffnen wir eine bestimmte Lokale Datei, in diesem Fall {{path|/etc/kderc}}. Das führt kein verschmelzen von Werten aus und erwartet eine Datei im INI Format.

Zeile 9 erzeugt ein Konfigurationsobjekt, dass nicht mit dem globalen <tt>kdeglobals</tt>-Konfigurationsobjekt verflochten ist, während das Konfigurationsobjekt auf Zeile 12 zusätzlich mit keinem der Dateien in der <tt>$KDEDIRS</tt>-Hierarchie verflochten ist. Das kann die Leistung spürbar verbessern, falls man einfach nur Werte aus einer einfachen Konfuguration liest und globale Werte keine Rolle spielen.

Zeile 15 erzeugt ein Konfigurationsobjekt unter Benutzung des {{class|KComponentData}}-Objekts das zu einem Plugin oder einer anderen Komponente gehört. Das Plugin kann verschiedene Ordner aufweisen, die in seinen {{class|KStandardDirs}} definiert sind und das ist eine Möglichkeit sich zu versichern, dass {{class|KConfig}} das respektiert.

Und schliesslich auf Zeile 18 erzeugen wir ein Konfigurationsobjekt, das nicht in der <tt>config</tt>-Ressource sondern in der <tt>data</tt>-Ressource existiert. Man kann kann auf diese Weise jede Ressource verwenden, von denen {{class|KStandardDirs}} Kenntnis hat, auch solche die während der Laufzeit hinzugefügt werden.

=== Spezielle Konfigurationsobjekte ===

Jede Anwendung hat sein eigenes Konfigurationsobjekt das den Namen benutzt, der von {{class|KAboutData}} bereitgestellt wird mit angehängtem "rc". Also hätte eine Anwendung mit dem Namen "myapp" das Standard-Konfigurationsobjekt "myapprc". Dieses Konfigurationsobjekt kann auf diese Weise aufgerufen werden:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// beachten sie, dass dies eigentlich ein KSharedConfig ist
// mehr über diese Klasse siehe weiter unten
KConfig* config = KGlobal::config();
}
</code>

Auf das Standard-Konfigurationsobjekt für die Anwendung wird zugegriffen, wenn kein Name definiert wurde, als das {{class|KConfig}}-Objekt erzeugt wurde. Also könnten wir stattdessen auch das tun:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

Zusätzlich könnte jede Komponente sein eigenes Konfigurationsobjekt haben. Auf dieses wird normalerweise durch die <tt>componentData()</tt> des Plugins zugegriffen, anstatt durch die <tt>{{class|KGlobal}}::mainComponent()</tt>.

Und schliesslich gibt es noch ein globales Konfigurationsobjekt, <tt>kdeglobals</tt>, das von jeder Anwendung verwendet wird. Es enthält Informationen wie die Standard-Tatenkombinationen für verschiedene Aktionen. Es wird in das Konfigurationsobjekt "gemischt" wenn der <tt>KConfig::IncludeGlobals</tt> Bitschalter dem {{class|KConfig}} Konstruktor übergeben wird, was standardmässig der Fall ist.

{{note (de)|Der Rest muss noch übersetzt werden}}

=== Commonly Useful Methods ===

To save the current state of the configuration object we call the <tt>sync()</tt> method. This method is also called when the object is destroyed. If no changes have been made or the resource reports itself as non-writable (such as in the case of the user not having write permissions to the file) then no disk activity occurs. <tt>sync()</tt> merges changes performed concurrently by other processes - local changes have priority, though.

If we want to make sure that we have the latest values from disk we can call <tt>reparseConfiguration()</tt> which calls <tt>sync()</tt> and then reloads the data from disk.

If we need to prevent the config object from saving already made modifications to disk we need to call <tt>markAsClean()</tt>. A particular use case for this is rolling back the configuration to the on-disk state by calling <tt>markAsClean()</tt> followed by <tt>reparseConfiguration()</tt>.

Listing all groups in a configuration object is as simple as calling <tt>groupList()</tt> as in this code snippet:

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

The {{class|KSharedConfig}} class is a reference counted version of {{class|KConfig}}. It thus provides a way to reference the same configuration object from multiple places in your application without the extra overhead of separate objects or concerns about syncronizing writes to disk even if the configuration object is updated from multiple code paths.

Accessing a {{class|KSharedConfig}} object is as easy as this:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<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.

{{class|KSharedConfig}} is generally recommended over using {{class|KConfig}} itself, and the object returned from {{class|KComponentData}} is indeed a {{class|KSharedConfig}} object.

== KConfigGroup ==

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>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ... or a bit differently ...
</code>

You can pass {{class|KConfig}} or {{class|KSharedConfig}} objects to {{class|KConfigGroup}}.

Config groups can be nested as well:

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Reading Entries ==

With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

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.

There are a couple of special read methods, including <tt>readPathEntry</tt> which returns a file system path. It is vital that one uses <tt>readPathEntry</tt> if it is a path as this enables such features as roaming profiles to work properly.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KConfig (de)

2008-01-02T12:30:14Z

Rememberme: /* Die KConfig Klasse */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

{{improve (de)}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer- und Gruppenprofile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

{{note (de)| deserialization entgliedern? <br> <tt> "do not have to perform serialization and deserialization of objects themselves" </tt>}}

Anwendungen selbst müssen darum normalerweise Objekte nicht selber gliedern und entgliedern.

Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== Die KConfig Klasse ==

Das {{class|KConfig}}-Objekt wird benutzt um ein bestehendes Konfigurationsobjekt anzusteuern. Es gibt eine Reihe von Möglichkeiten ein Konfigurationsobjekt zu erstellen.

<code cppqt n>
// ein einfaches, altes lesen/schreiben Konfigurationsobjekt
KConfig config("myapprc");

// eine bestimmte Datei im Dateisystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// nicht mit globalen Werten verflochten
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// nicht mit globalen Werten orde der $KDEDIRS Hierarchie verflochten
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// Komponenten-spezifische Konfiguration, in diesem Fall ein Plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// Ausserhalb der normalen Konfigurations-Ressource
KConfig dataResource( "data", "myapp/somefile" );
</code>

{{note (de)|wie soll "merged" in den folgenden Fällen übersetzt werden? <br> <tt>"verschmolzen" oder "verflochten"</tt> <br> der Anwendung selber transparent" tönt auch nicht sehr gut}}

Das Kconfig Objekt, das wir auf Zeile 2 erstellen ist ein gewöhnliches Konfigurationsobjekt. Wir können Werte aus ihm lesen, neue Einträge schreiben und nach verschiedenen Eigenschaften des Objekts fragen. Dieses Objekt wird aus der Konfigurations-Ressource geladen, wie es durch {{class|KStandardDirs}} bestimmt wird, das heisst, dass jede Instanz des <tt>myapprc</tt>-Objekts in jedem der Ordner in der Konfigurations-Ressourcen-Hierarchie verschmolzen werden um die Werte zu erzeugen, die in diesem Objekt gesehen werden. So werden Systemweite und
pro-Benutzer/Gruppen Profile erstellt und unterstützt. Das alles geschieht der Anwendung selber transparent.

{{tip| Für mehr Informationen, wie das Verschmelzen funktioniert, siehe diesen Artikel über die [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Dateisystem Hierarchie]].}}

{{note (de)|Ist das so gemeint mit "expects an INI style file"<br> <tt> On line 6 we open a specific local file, this case /etc/kderc. This performs no merging of values and expects an INI style file.</tt>}}

Auf Zeile 6 öffnen wir eine bestimmte Lokale Datei, in diesem Fall {{path|/etc/kderc}}. Das führt kein verschmelzen von Werten aus und erwartet eine Datei im INI Format.

Zeile 9 erzeugt ein Konfigurationsobjekt, dass nicht mit dem globalen <tt>kdeglobals</tt>-Konfigurationsobjekt verflochten ist, während das Konfigurationsobjekt auf Zeile 12 zusätzlich mit keinem der Dateien in der <tt>$KDEDIRS</tt>-Hierarchie verflochten ist. Das kann die Leistung spürbar verbessern, falls man einfach nur Werte aus einer einfachen Konfuguration liest und globale Werte keine Rolle spielen.

Zeile 15 erzeugt ein Konfigurationsobjekt unter Benutzung des {{class|KComponentData}}-Objekts das zu einem Plugin oder einer anderen Komponente gehört. Das Plugin kann verschiedene Ordner haben, die in seinen {{class|KStandardDirs}} definiert sind und das ist eine Möglichkeit sich zu versichern, dass {{class|KConfig}} das respektiert.

Und schliesslich auf Zeile 18 erzeugen wir ein Konfigurationsobjekt, das nicht in der <tt>config</tt>-Ressource sondern in der <tt>data</tt>-Ressource existiert. Man kann kann auf diese Weise jede Ressource verwenden, von denen {{class|KStandardDirs}} weiss, auch solche die während der Laufzeit hinzugefügt werden.

{{note (de)|Der Rest muss noch übersetzt werden}}

=== 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:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// note that this is actually a KSharedConfig
// more on that class in a bit!
KConfig* config = KGlobal::config();
}
</code>

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:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

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>.

Finally there is a global configuration object, <tt>kdeglobals</tt>, that is shared by every application. It holds such information as the default application shortcuts for various actions. It is "blended" into the configuration object if the <tt>KConfig::IncludeGlobals</tt> flag is passed to the {{class|KConfig}} constructor, which is the default.

=== Commonly Useful Methods ===

To save the current state of the configuration object we call the <tt>sync()</tt> method. This method is also called when the object is destroyed. If no changes have been made or the resource reports itself as non-writable (such as in the case of the user not having write permissions to the file) then no disk activity occurs. <tt>sync()</tt> merges changes performed concurrently by other processes - local changes have priority, though.

If we want to make sure that we have the latest values from disk we can call <tt>reparseConfiguration()</tt> which calls <tt>sync()</tt> and then reloads the data from disk.

If we need to prevent the config object from saving already made modifications to disk we need to call <tt>markAsClean()</tt>. A particular use case for this is rolling back the configuration to the on-disk state by calling <tt>markAsClean()</tt> followed by <tt>reparseConfiguration()</tt>.

Listing all groups in a configuration object is as simple as calling <tt>groupList()</tt> as in this code snippet:

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

The {{class|KSharedConfig}} class is a reference counted version of {{class|KConfig}}. It thus provides a way to reference the same configuration object from multiple places in your application without the extra overhead of separate objects or concerns about syncronizing writes to disk even if the configuration object is updated from multiple code paths.

Accessing a {{class|KSharedConfig}} object is as easy as this:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<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.

{{class|KSharedConfig}} is generally recommended over using {{class|KConfig}} itself, and the object returned from {{class|KComponentData}} is indeed a {{class|KSharedConfig}} object.

== KConfigGroup ==

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>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ... or a bit differently ...
</code>

You can pass {{class|KConfig}} or {{class|KSharedConfig}} objects to {{class|KConfigGroup}}.

Config groups can be nested as well:

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Reading Entries ==

With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

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.

There are a couple of special read methods, including <tt>readPathEntry</tt> which returns a file system path. It is vital that one uses <tt>readPathEntry</tt> if it is a path as this enables such features as roaming profiles to work properly.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KConfig (de)

2008-01-01T23:46:21Z

Rememberme: /* Die KConfig Klasse */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

{{improve (de)}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer- und Gruppenprofile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

{{note (de)| deserialization entgliedern? <br> <tt> "do not have to perform serialization and deserialization of objects themselves" </tt>}}

Anwendungen selbst müssen darum normalerweise Objekte nicht selber gliedern und entgliedern.

Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== Die KConfig Klasse ==

Das {{class|KConfig}}-Objekt wird benutzt um ein bestehendes Konfigurationsobjekt anzusteuern. Es gibt eine Reihe von Möglichkeiten ein Konfigurationsobjekt zu erstellen.

<code cppqt n>
// ein einfaches, altes lesen/schreiben Konfigurationsobjekt
KConfig config("myapprc");

// eine bestimmte Datei im Dateisystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// nicht mit globalen Werten verflochten
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// nicht mit globalen Werten orde der $KDEDIRS Hierarchie verflochten
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// Komponenten-spezifische Konfiguration, in diesem Fall ein Plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// Ausserhalb der normalen Konfigurations-Ressource
KConfig dataResource( "data", "myapp/somefile" );
</code>

{{note (de)|"der Anwendung selber transparent" tönt nicht sehr gut}}

Das Kconfig Objekt, das wir auf Zeile 2 erstellen ist ein gewöhnliches Konfigurationsobjekt. Wir können Werte aus ihm lesen, neue Einträge schreiben und nach verschiedenen Eigenschaften des Objekts fragen. Dieses Objekt wird aus der Konfigurations-Ressource geladen, wie es durch {{class|KStandardDirs}} bestimmt wird, das heisst, dass jede Instanz des <tt>myapprc</tt>-Objekts in jedem der Ordner in der Konfigurations-Ressourcen-Hierarchie verschmolzen werden um die Werte zu erzeugen, die in diesem Objekt gesehen werden. So werden Systemweite und
pro-Benutzer/Gruppen Profile erstellt und unterstützt. Das alles geschieht der Anwendung selber transparent.

{{tip| Für mehr Informationen, wie das Verschmelzen funktioniert, siehe diesen Artikel über die [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Dateisystem Hierarchie]].}}

{{note (de)|Ist das so gemeint mit "expects an INI style file"<br> <tt> On line 6 we open a specific local file, this case /etc/kderc. This performs no merging of values and expects an INI style file.</tt>}}

Auf Zeile 6 öffnen wir eine bestimmte Lokale Datei, in diesem Fall {{path|/etc/kderc}}. Das führt kein verschmelzen von Werten aus und erwartet eine Datei im INI Format.

{{note (de)|Der Rest muss noch übersetzt werden}}

Line 9 sees the creation of a configuration object that is not merged with the global <tt>kdeglobals</tt> configuration object, while the configuration file on line 12 is additionally not merged with any files in the <tt>$KDEDIRS</tt> hierarchy. This can noticeably improve performance in the case where one is simply reading values out of a simple configuration for which global values are not meaningful.

Line 15 creates a configuration object using the {{class|KComponentData}} object that belongs to a plugin or other component. The plugin may have a different set of directories defined in its {{class|KStandardDirs}} and this is a way of ensuring that {{class|KConfig}} respects this.

Finally on line 18 we see the creation of a configuration object that does not exist in the <tt>config</tt> resource but rather in the application <tt>data</tt> resource. You may use any resource that {{class|KStandardDirs}} is aware of, including ones that are added at runtime.

=== 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:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// note that this is actually a KSharedConfig
// more on that class in a bit!
KConfig* config = KGlobal::config();
}
</code>

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:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

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>.

Finally there is a global configuration object, <tt>kdeglobals</tt>, that is shared by every application. It holds such information as the default application shortcuts for various actions. It is "blended" into the configuration object if the <tt>KConfig::IncludeGlobals</tt> flag is passed to the {{class|KConfig}} constructor, which is the default.

=== Commonly Useful Methods ===

To save the current state of the configuration object we call the <tt>sync()</tt> method. This method is also called when the object is destroyed. If no changes have been made or the resource reports itself as non-writable (such as in the case of the user not having write permissions to the file) then no disk activity occurs. <tt>sync()</tt> merges changes performed concurrently by other processes - local changes have priority, though.

If we want to make sure that we have the latest values from disk we can call <tt>reparseConfiguration()</tt> which calls <tt>sync()</tt> and then reloads the data from disk.

If we need to prevent the config object from saving already made modifications to disk we need to call <tt>markAsClean()</tt>. A particular use case for this is rolling back the configuration to the on-disk state by calling <tt>markAsClean()</tt> followed by <tt>reparseConfiguration()</tt>.

Listing all groups in a configuration object is as simple as calling <tt>groupList()</tt> as in this code snippet:

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

The {{class|KSharedConfig}} class is a reference counted version of {{class|KConfig}}. It thus provides a way to reference the same configuration object from multiple places in your application without the extra overhead of separate objects or concerns about syncronizing writes to disk even if the configuration object is updated from multiple code paths.

Accessing a {{class|KSharedConfig}} object is as easy as this:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<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.

{{class|KSharedConfig}} is generally recommended over using {{class|KConfig}} itself, and the object returned from {{class|KComponentData}} is indeed a {{class|KSharedConfig}} object.

== KConfigGroup ==

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>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ... or a bit differently ...
</code>

You can pass {{class|KConfig}} or {{class|KSharedConfig}} objects to {{class|KConfigGroup}}.

Config groups can be nested as well:

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Reading Entries ==

With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

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.

There are a couple of special read methods, including <tt>readPathEntry</tt> which returns a file system path. It is vital that one uses <tt>readPathEntry</tt> if it is a path as this enables such features as roaming profiles to work properly.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KConfig (de)

2008-01-01T23:45:47Z

Rememberme: /* Grundlegender Aufbau */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

{{improve (de)}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer- und Gruppenprofile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

{{note (de)| deserialization entgliedern? <br> <tt> "do not have to perform serialization and deserialization of objects themselves" </tt>}}

Anwendungen selbst müssen darum normalerweise Objekte nicht selber gliedern und entgliedern.

Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== Die KConfig Klasse ==

Das {{class|KConfig}}-Objekt wird benutzt um ein bestehendes Konfigurationsobjekt anzusteuern. Es gibt eine Reihe von Möglichkeiten ein Konfigurationsobjekt zu erstellen.

<code cppqt n>
// ein einfaches, altes lesen/schreiben Konfigurationsobjekt
KConfig config("myapprc");

// eine bestimmte Datei im Dateisystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// nicht mit globalen Werten verflochten
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// nicht mit globalen Werten orde der $KDEDIRS Hierarchie verflochten
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// Komponenten-spezifische Konfiguration, in diesem Fall ein Plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// Ausserhalb der normalen Konfigurations-Ressource
KConfig dataResource( "data", "myapp/somefile" );
</code>

{{note (de)|"der Anwendung selber transparent" tönt nicht sehr gut}}

Das Kconfig Objekt, das wir auf Zeile 2 erstellen ist ein gewöhnliches Konfigurationsobjekt. Wir können Werte aus ihm lesen, neue Einträge schreiben und nach verschiedenen Eigenschaften des Objekts fragen. Dieses Objekt wird aus der Konfigurations-Ressource geladen, wie es durch {{class|KStandardDirs}} bestimmt wird, das heisst, dass jede Instanz des <tt>myapprc</tt>-Objekts in jedem der Ordner in der Konfigurations-Ressourcen-Hierarchie verschmolzen werden um die Werte zu erzeugen, die in diesem Objekt gesehen werden. So werden Systemweite und
pro-Benutzer/Gruppen Profile erstellt und unterstützt. Das alles geschieht der Anwendung selber transparent.

{{tip| Für mehr Informationen, wie das Verschmelzen funktioniert, siehe diesen Artikel über die [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Dateisystem Hierarchie]].}}

{{note (de)|Ist das so gemeint mit "expects an INI style file"<br> <tt> On line 6 we open a specific local file, this case /etc/kderc. This performs no merging of values and expects an INI style file.</tt>}}

Auf Zeile 6 öffnen wir eine bestimmte Lokale Datei, in diesem Fall {{path|/etc/kderc}. Das führt kein verschmelzen von Werten aus und erwartet eine Datei im INI Format.

{{note (de)|Der Rest muss noch übersetzt werden}}

Line 9 sees the creation of a configuration object that is not merged with the global <tt>kdeglobals</tt> configuration object, while the configuration file on line 12 is additionally not merged with any files in the <tt>$KDEDIRS</tt> hierarchy. This can noticeably improve performance in the case where one is simply reading values out of a simple configuration for which global values are not meaningful.

Line 15 creates a configuration object using the {{class|KComponentData}} object that belongs to a plugin or other component. The plugin may have a different set of directories defined in its {{class|KStandardDirs}} and this is a way of ensuring that {{class|KConfig}} respects this.

Finally on line 18 we see the creation of a configuration object that does not exist in the <tt>config</tt> resource but rather in the application <tt>data</tt> resource. You may use any resource that {{class|KStandardDirs}} is aware of, including ones that are added at runtime.

=== 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:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// note that this is actually a KSharedConfig
// more on that class in a bit!
KConfig* config = KGlobal::config();
}
</code>

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:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

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>.

Finally there is a global configuration object, <tt>kdeglobals</tt>, that is shared by every application. It holds such information as the default application shortcuts for various actions. It is "blended" into the configuration object if the <tt>KConfig::IncludeGlobals</tt> flag is passed to the {{class|KConfig}} constructor, which is the default.

=== Commonly Useful Methods ===

To save the current state of the configuration object we call the <tt>sync()</tt> method. This method is also called when the object is destroyed. If no changes have been made or the resource reports itself as non-writable (such as in the case of the user not having write permissions to the file) then no disk activity occurs. <tt>sync()</tt> merges changes performed concurrently by other processes - local changes have priority, though.

If we want to make sure that we have the latest values from disk we can call <tt>reparseConfiguration()</tt> which calls <tt>sync()</tt> and then reloads the data from disk.

If we need to prevent the config object from saving already made modifications to disk we need to call <tt>markAsClean()</tt>. A particular use case for this is rolling back the configuration to the on-disk state by calling <tt>markAsClean()</tt> followed by <tt>reparseConfiguration()</tt>.

Listing all groups in a configuration object is as simple as calling <tt>groupList()</tt> as in this code snippet:

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

The {{class|KSharedConfig}} class is a reference counted version of {{class|KConfig}}. It thus provides a way to reference the same configuration object from multiple places in your application without the extra overhead of separate objects or concerns about syncronizing writes to disk even if the configuration object is updated from multiple code paths.

Accessing a {{class|KSharedConfig}} object is as easy as this:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<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.

{{class|KSharedConfig}} is generally recommended over using {{class|KConfig}} itself, and the object returned from {{class|KComponentData}} is indeed a {{class|KSharedConfig}} object.

== KConfigGroup ==

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>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ... or a bit differently ...
</code>

You can pass {{class|KConfig}} or {{class|KSharedConfig}} objects to {{class|KConfigGroup}}.

Config groups can be nested as well:

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Reading Entries ==

With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

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.

There are a couple of special read methods, including <tt>readPathEntry</tt> which returns a file system path. It is vital that one uses <tt>readPathEntry</tt> if it is a path as this enables such features as roaming profiles to work properly.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KConfig (de)

2008-01-01T23:44:20Z

Rememberme: /* Grundlegender Aufbau */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

{{improve (de)}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer- und Gruppenprofile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

{{note (de)| deserialization? <tt> do not have to perform serialization and deserialization of objects themselves </tt>}}

Anwendungen selbst müssen darum normalerweise Objekte nicht selber gliedern und entgliedern.

Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== Die KConfig Klasse ==

Das {{class|KConfig}}-Objekt wird benutzt um ein bestehendes Konfigurationsobjekt anzusteuern. Es gibt eine Reihe von Möglichkeiten ein Konfigurationsobjekt zu erstellen.

<code cppqt n>
// ein einfaches, altes lesen/schreiben Konfigurationsobjekt
KConfig config("myapprc");

// eine bestimmte Datei im Dateisystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// nicht mit globalen Werten verflochten
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// nicht mit globalen Werten orde der $KDEDIRS Hierarchie verflochten
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// Komponenten-spezifische Konfiguration, in diesem Fall ein Plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// Ausserhalb der normalen Konfigurations-Ressource
KConfig dataResource( "data", "myapp/somefile" );
</code>

{{note (de)|"der Anwendung selber transparent" tönt nicht sehr gut}}

Das Kconfig Objekt, das wir auf Zeile 2 erstellen ist ein gewöhnliches Konfigurationsobjekt. Wir können Werte aus ihm lesen, neue Einträge schreiben und nach verschiedenen Eigenschaften des Objekts fragen. Dieses Objekt wird aus der Konfigurations-Ressource geladen, wie es durch {{class|KStandardDirs}} bestimmt wird, das heisst, dass jede Instanz des <tt>myapprc</tt>-Objekts in jedem der Ordner in der Konfigurations-Ressourcen-Hierarchie verschmolzen werden um die Werte zu erzeugen, die in diesem Objekt gesehen werden. So werden Systemweite und
pro-Benutzer/Gruppen Profile erstellt und unterstützt. Das alles geschieht der Anwendung selber transparent.

{{tip| Für mehr Informationen, wie das Verschmelzen funktioniert, siehe diesen Artikel über die [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Dateisystem Hierarchie]].}}

{{note (de)|Ist das so gemeint mit "expects an INI style file"<br> <tt> On line 6 we open a specific local file, this case /etc/kderc. This performs no merging of values and expects an INI style file.</tt>}}

Auf Zeile 6 öffnen wir eine bestimmte Lokale Datei, in diesem Fall {{path|/etc/kderc}. Das führt kein verschmelzen von Werten aus und erwartet eine Datei im INI Format.

{{note (de)|Der Rest muss noch übersetzt werden}}

Line 9 sees the creation of a configuration object that is not merged with the global <tt>kdeglobals</tt> configuration object, while the configuration file on line 12 is additionally not merged with any files in the <tt>$KDEDIRS</tt> hierarchy. This can noticeably improve performance in the case where one is simply reading values out of a simple configuration for which global values are not meaningful.

Line 15 creates a configuration object using the {{class|KComponentData}} object that belongs to a plugin or other component. The plugin may have a different set of directories defined in its {{class|KStandardDirs}} and this is a way of ensuring that {{class|KConfig}} respects this.

Finally on line 18 we see the creation of a configuration object that does not exist in the <tt>config</tt> resource but rather in the application <tt>data</tt> resource. You may use any resource that {{class|KStandardDirs}} is aware of, including ones that are added at runtime.

=== 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:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// note that this is actually a KSharedConfig
// more on that class in a bit!
KConfig* config = KGlobal::config();
}
</code>

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:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

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>.

Finally there is a global configuration object, <tt>kdeglobals</tt>, that is shared by every application. It holds such information as the default application shortcuts for various actions. It is "blended" into the configuration object if the <tt>KConfig::IncludeGlobals</tt> flag is passed to the {{class|KConfig}} constructor, which is the default.

=== Commonly Useful Methods ===

To save the current state of the configuration object we call the <tt>sync()</tt> method. This method is also called when the object is destroyed. If no changes have been made or the resource reports itself as non-writable (such as in the case of the user not having write permissions to the file) then no disk activity occurs. <tt>sync()</tt> merges changes performed concurrently by other processes - local changes have priority, though.

If we want to make sure that we have the latest values from disk we can call <tt>reparseConfiguration()</tt> which calls <tt>sync()</tt> and then reloads the data from disk.

If we need to prevent the config object from saving already made modifications to disk we need to call <tt>markAsClean()</tt>. A particular use case for this is rolling back the configuration to the on-disk state by calling <tt>markAsClean()</tt> followed by <tt>reparseConfiguration()</tt>.

Listing all groups in a configuration object is as simple as calling <tt>groupList()</tt> as in this code snippet:

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

The {{class|KSharedConfig}} class is a reference counted version of {{class|KConfig}}. It thus provides a way to reference the same configuration object from multiple places in your application without the extra overhead of separate objects or concerns about syncronizing writes to disk even if the configuration object is updated from multiple code paths.

Accessing a {{class|KSharedConfig}} object is as easy as this:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<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.

{{class|KSharedConfig}} is generally recommended over using {{class|KConfig}} itself, and the object returned from {{class|KComponentData}} is indeed a {{class|KSharedConfig}} object.

== KConfigGroup ==

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>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ... or a bit differently ...
</code>

You can pass {{class|KConfig}} or {{class|KSharedConfig}} objects to {{class|KConfigGroup}}.

Config groups can be nested as well:

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Reading Entries ==

With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

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.

There are a couple of special read methods, including <tt>readPathEntry</tt> which returns a file system path. It is vital that one uses <tt>readPathEntry</tt> if it is a path as this enables such features as roaming profiles to work properly.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KConfig (de)

2008-01-01T23:43:23Z

Rememberme:

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

{{improve (de)}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer- und Gruppenprofile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

TODO: (deserialization?)

Anwendungen selbst müssen darum normalerweise Objekte nicht selber gliedern und entgliedern.

Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== Die KConfig Klasse ==

Das {{class|KConfig}}-Objekt wird benutzt um ein bestehendes Konfigurationsobjekt anzusteuern. Es gibt eine Reihe von Möglichkeiten ein Konfigurationsobjekt zu erstellen.

<code cppqt n>
// ein einfaches, altes lesen/schreiben Konfigurationsobjekt
KConfig config("myapprc");

// eine bestimmte Datei im Dateisystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// nicht mit globalen Werten verflochten
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// nicht mit globalen Werten orde der $KDEDIRS Hierarchie verflochten
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// Komponenten-spezifische Konfiguration, in diesem Fall ein Plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// Ausserhalb der normalen Konfigurations-Ressource
KConfig dataResource( "data", "myapp/somefile" );
</code>

{{note (de)|"der Anwendung selber transparent" tönt nicht sehr gut}}

Das Kconfig Objekt, das wir auf Zeile 2 erstellen ist ein gewöhnliches Konfigurationsobjekt. Wir können Werte aus ihm lesen, neue Einträge schreiben und nach verschiedenen Eigenschaften des Objekts fragen. Dieses Objekt wird aus der Konfigurations-Ressource geladen, wie es durch {{class|KStandardDirs}} bestimmt wird, das heisst, dass jede Instanz des <tt>myapprc</tt>-Objekts in jedem der Ordner in der Konfigurations-Ressourcen-Hierarchie verschmolzen werden um die Werte zu erzeugen, die in diesem Objekt gesehen werden. So werden Systemweite und
pro-Benutzer/Gruppen Profile erstellt und unterstützt. Das alles geschieht der Anwendung selber transparent.

{{tip| Für mehr Informationen, wie das Verschmelzen funktioniert, siehe diesen Artikel über die [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Dateisystem Hierarchie]].}}

{{note (de)|Ist das so gemeint mit "expects an INI style file"<br> <tt> On line 6 we open a specific local file, this case /etc/kderc. This performs no merging of values and expects an INI style file.</tt>}}

Auf Zeile 6 öffnen wir eine bestimmte Lokale Datei, in diesem Fall {{path|/etc/kderc}. Das führt kein verschmelzen von Werten aus und erwartet eine Datei im INI Format.

{{note (de)|Der Rest muss noch übersetzt werden}}

Line 9 sees the creation of a configuration object that is not merged with the global <tt>kdeglobals</tt> configuration object, while the configuration file on line 12 is additionally not merged with any files in the <tt>$KDEDIRS</tt> hierarchy. This can noticeably improve performance in the case where one is simply reading values out of a simple configuration for which global values are not meaningful.

Line 15 creates a configuration object using the {{class|KComponentData}} object that belongs to a plugin or other component. The plugin may have a different set of directories defined in its {{class|KStandardDirs}} and this is a way of ensuring that {{class|KConfig}} respects this.

Finally on line 18 we see the creation of a configuration object that does not exist in the <tt>config</tt> resource but rather in the application <tt>data</tt> resource. You may use any resource that {{class|KStandardDirs}} is aware of, including ones that are added at runtime.

=== 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:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// note that this is actually a KSharedConfig
// more on that class in a bit!
KConfig* config = KGlobal::config();
}
</code>

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:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

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>.

Finally there is a global configuration object, <tt>kdeglobals</tt>, that is shared by every application. It holds such information as the default application shortcuts for various actions. It is "blended" into the configuration object if the <tt>KConfig::IncludeGlobals</tt> flag is passed to the {{class|KConfig}} constructor, which is the default.

=== Commonly Useful Methods ===

To save the current state of the configuration object we call the <tt>sync()</tt> method. This method is also called when the object is destroyed. If no changes have been made or the resource reports itself as non-writable (such as in the case of the user not having write permissions to the file) then no disk activity occurs. <tt>sync()</tt> merges changes performed concurrently by other processes - local changes have priority, though.

If we want to make sure that we have the latest values from disk we can call <tt>reparseConfiguration()</tt> which calls <tt>sync()</tt> and then reloads the data from disk.

If we need to prevent the config object from saving already made modifications to disk we need to call <tt>markAsClean()</tt>. A particular use case for this is rolling back the configuration to the on-disk state by calling <tt>markAsClean()</tt> followed by <tt>reparseConfiguration()</tt>.

Listing all groups in a configuration object is as simple as calling <tt>groupList()</tt> as in this code snippet:

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

The {{class|KSharedConfig}} class is a reference counted version of {{class|KConfig}}. It thus provides a way to reference the same configuration object from multiple places in your application without the extra overhead of separate objects or concerns about syncronizing writes to disk even if the configuration object is updated from multiple code paths.

Accessing a {{class|KSharedConfig}} object is as easy as this:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<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.

{{class|KSharedConfig}} is generally recommended over using {{class|KConfig}} itself, and the object returned from {{class|KComponentData}} is indeed a {{class|KSharedConfig}} object.

== KConfigGroup ==

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>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ... or a bit differently ...
</code>

You can pass {{class|KConfig}} or {{class|KSharedConfig}} objects to {{class|KConfigGroup}}.

Config groups can be nested as well:

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Reading Entries ==

With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

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.

There are a couple of special read methods, including <tt>readPathEntry</tt> which returns a file system path. It is vital that one uses <tt>readPathEntry</tt> if it is a path as this enables such features as roaming profiles to work properly.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KConfig (de)

2008-01-01T23:41:15Z

Rememberme: /* Die KConfig Klasse */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer- und Gruppenprofile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

TODO: (deserialization?)

Anwendungen selbst müssen darum normalerweise Objekte nicht selber gliedern und entgliedern.

Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== Die KConfig Klasse ==

Das {{class|KConfig}}-Objekt wird benutzt um ein bestehendes Konfigurationsobjekt anzusteuern. Es gibt eine Reihe von Möglichkeiten ein Konfigurationsobjekt zu erstellen.

<code cppqt n>
// ein einfaches, altes lesen/schreiben Konfigurationsobjekt
KConfig config("myapprc");

// eine bestimmte Datei im Dateisystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// nicht mit globalen Werten verflochten
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// nicht mit globalen Werten orde der $KDEDIRS Hierarchie verflochten
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// Komponenten-spezifische Konfiguration, in diesem Fall ein Plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// Ausserhalb der normalen Konfigurations-Ressource
KConfig dataResource( "data", "myapp/somefile" );
</code>

{{note (de)|"der Anwendung selber transparent" tönt nicht sehr gut}}

Das Kconfig Objekt, das wir auf Zeile 2 erstellen ist ein gewöhnliches Konfigurationsobjekt. Wir können Werte aus ihm lesen, neue Einträge schreiben und nach verschiedenen Eigenschaften des Objekts fragen. Dieses Objekt wird aus der Konfigurations-Ressource geladen, wie es durch {{class|KStandardDirs}} bestimmt wird, das heisst, dass jede Instanz des <tt>myapprc</tt>-Objekts in jedem der Ordner in der Konfigurations-Ressourcen-Hierarchie verschmolzen werden um die Werte zu erzeugen, die in diesem Objekt gesehen werden. So werden Systemweite und
pro-Benutzer/Gruppen Profile erstellt und unterstützt. Das alles geschieht der Anwendung selber transparent.

{{tip| Für mehr Informationen, wie das Verschmelzen funktioniert, siehe diesen Artikel über die [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Dateisystem Hierarchie]].}}

{{note (de)|Ist das so gemeint mit "expects an INI style file"<br> <tt> On line 6 we open a specific local file, this case /etc/kderc. This performs no merging of values and expects an INI style file.</tt>}}

Auf Zeile 6 öffnen wir eine bestimmte Lokale Datei, in diesem Fall {{path|/etc/kderc}. Das führt kein verschmelzen von Werten aus und erwartet eine Datei im INI Format.

{{note (de)|Der Rest muss noch übersetzt werden}}

Line 9 sees the creation of a configuration object that is not merged with the global <tt>kdeglobals</tt> configuration object, while the configuration file on line 12 is additionally not merged with any files in the <tt>$KDEDIRS</tt> hierarchy. This can noticeably improve performance in the case where one is simply reading values out of a simple configuration for which global values are not meaningful.

Line 15 creates a configuration object using the {{class|KComponentData}} object that belongs to a plugin or other component. The plugin may have a different set of directories defined in its {{class|KStandardDirs}} and this is a way of ensuring that {{class|KConfig}} respects this.

Finally on line 18 we see the creation of a configuration object that does not exist in the <tt>config</tt> resource but rather in the application <tt>data</tt> resource. You may use any resource that {{class|KStandardDirs}} is aware of, including ones that are added at runtime.

=== 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:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// note that this is actually a KSharedConfig
// more on that class in a bit!
KConfig* config = KGlobal::config();
}
</code>

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:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

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>.

Finally there is a global configuration object, <tt>kdeglobals</tt>, that is shared by every application. It holds such information as the default application shortcuts for various actions. It is "blended" into the configuration object if the <tt>KConfig::IncludeGlobals</tt> flag is passed to the {{class|KConfig}} constructor, which is the default.

=== Commonly Useful Methods ===

To save the current state of the configuration object we call the <tt>sync()</tt> method. This method is also called when the object is destroyed. If no changes have been made or the resource reports itself as non-writable (such as in the case of the user not having write permissions to the file) then no disk activity occurs. <tt>sync()</tt> merges changes performed concurrently by other processes - local changes have priority, though.

If we want to make sure that we have the latest values from disk we can call <tt>reparseConfiguration()</tt> which calls <tt>sync()</tt> and then reloads the data from disk.

If we need to prevent the config object from saving already made modifications to disk we need to call <tt>markAsClean()</tt>. A particular use case for this is rolling back the configuration to the on-disk state by calling <tt>markAsClean()</tt> followed by <tt>reparseConfiguration()</tt>.

Listing all groups in a configuration object is as simple as calling <tt>groupList()</tt> as in this code snippet:

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

The {{class|KSharedConfig}} class is a reference counted version of {{class|KConfig}}. It thus provides a way to reference the same configuration object from multiple places in your application without the extra overhead of separate objects or concerns about syncronizing writes to disk even if the configuration object is updated from multiple code paths.

Accessing a {{class|KSharedConfig}} object is as easy as this:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<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.

{{class|KSharedConfig}} is generally recommended over using {{class|KConfig}} itself, and the object returned from {{class|KComponentData}} is indeed a {{class|KSharedConfig}} object.

== KConfigGroup ==

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>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ... or a bit differently ...
</code>

You can pass {{class|KConfig}} or {{class|KSharedConfig}} objects to {{class|KConfigGroup}}.

Config groups can be nested as well:

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Reading Entries ==

With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

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.

There are a couple of special read methods, including <tt>readPathEntry</tt> which returns a file system path. It is vital that one uses <tt>readPathEntry</tt> if it is a path as this enables such features as roaming profiles to work properly.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KConfig (de)

2008-01-01T16:31:40Z

Rememberme: /* The KConfig Class */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer- und Gruppenprofile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

TODO: (deserialization?)

Anwendungen selbst müssen darum normalerweise Objekte nicht selber gliedern und entgliedern.

Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== Die KConfig Klasse ==

Das {{class|KConfig}}-Objekt wird benutzt um ein bestehendes Konfigurationsobjekt anzusteuern. Es gibt eine Reihe von Möglichkeiten ein Konfigurationsobjekt zu erstellen.

<code cppqt n>
// ein einfaches, altes lesen/schreiben Konfigurationsobjekt
KConfig config("myapprc");

// eine bestimmte Datei im Dateisystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// nicht mit globalen Werten verflochten
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// nicht mit globalen Werten orde der $KDEDIRS Hierarchie verflochten
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// Komponenten-spezifische Konfiguration, in diesem Fall ein Plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// Ausserhalb der normalen Konfigurations-Ressource
KConfig dataResource( "data", "myapp/somefile" );
</code>

TODO: (will be merged - "verschmolzen werden", "der Anwendung selber transparent")

Das Kconfig Objekt, das wir auf Zeile 2 erstellen ist ein gewöhnliches Konfigurationsobjekt. Wir können Werte aus ihm lesen, neue Einträge schreiben und nach verschiedenen Eigenschaften des Objekts fragen. Dieses Objekt wird aus der Konfigurations-Ressource geladen, wie es durch {{class|KStandardDirs}} bestimmt wird, das heisst, dass jede Instanz des <tt>myapprc</tt>-Objekts in jedem der Ordner in der Konfigurations-Ressourcen-Hierarchie verschmolzen werden um die Werte zu erzeugen, die in diesem Objekt gesehen werden. So werden Systemweite und
pro-Benutzer/Gruppen Profile erstellt und unterstützt. Das alles geschieht der Anwendung selber transparent.

{{tip| Für mehr Informationen, wie das Verschmelzen funktioniert, siehe diesen Artikel über das [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Dateisystem Hierarchie]].}}

TODO:Rest übersetzen

On line 6 we open a specific local file, this case {{path|/etc/kderc}}. This performs no merging of values and expects an INI style file.

Line 9 sees the creation of a configuration object that is not merged with the global <tt>kdeglobals</tt> configuration object, while the configuration file on line 12 is additionally not merged with any files in the <tt>$KDEDIRS</tt> hierarchy. This can noticeably improve performance in the case where one is simply reading values out of a simple configuration for which global values are not meaningful.

Line 15 creates a configuration object using the {{class|KComponentData}} object that belongs to a plugin or other component. The plugin may have a different set of directories defined in its {{class|KStandardDirs}} and this is a way of ensuring that {{class|KConfig}} respects this.

Finally on line 18 we see the creation of a configuration object that does not exist in the <tt>config</tt> resource but rather in the application <tt>data</tt> resource. You may use any resource that {{class|KStandardDirs}} is aware of, including ones that are added at runtime.

=== 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:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// note that this is actually a KSharedConfig
// more on that class in a bit!
KConfig* config = KGlobal::config();
}
</code>

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:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

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>.

Finally there is a global configuration object, <tt>kdeglobals</tt>, that is shared by every application. It holds such information as the default application shortcuts for various actions. It is "blended" into the configuration object if the <tt>KConfig::IncludeGlobals</tt> flag is passed to the {{class|KConfig}} constructor, which is the default.

=== Commonly Useful Methods ===

To save the current state of the configuration object we call the <tt>sync()</tt> method. This method is also called when the object is destroyed. If no changes have been made or the resource reports itself as non-writable (such as in the case of the user not having write permissions to the file) then no disk activity occurs. <tt>sync()</tt> merges changes performed concurrently by other processes - local changes have priority, though.

If we want to make sure that we have the latest values from disk we can call <tt>reparseConfiguration()</tt> which calls <tt>sync()</tt> and then reloads the data from disk.

If we need to prevent the config object from saving already made modifications to disk we need to call <tt>markAsClean()</tt>. A particular use case for this is rolling back the configuration to the on-disk state by calling <tt>markAsClean()</tt> followed by <tt>reparseConfiguration()</tt>.

Listing all groups in a configuration object is as simple as calling <tt>groupList()</tt> as in this code snippet:

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

The {{class|KSharedConfig}} class is a reference counted version of {{class|KConfig}}. It thus provides a way to reference the same configuration object from multiple places in your application without the extra overhead of separate objects or concerns about syncronizing writes to disk even if the configuration object is updated from multiple code paths.

Accessing a {{class|KSharedConfig}} object is as easy as this:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<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.

{{class|KSharedConfig}} is generally recommended over using {{class|KConfig}} itself, and the object returned from {{class|KComponentData}} is indeed a {{class|KSharedConfig}} object.

== KConfigGroup ==

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>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ... or a bit differently ...
</code>

You can pass {{class|KConfig}} or {{class|KSharedConfig}} objects to {{class|KConfigGroup}}.

Config groups can be nested as well:

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Reading Entries ==

With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

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.

There are a couple of special read methods, including <tt>readPathEntry</tt> which returns a file system path. It is vital that one uses <tt>readPathEntry</tt> if it is a path as this enables such features as roaming profiles to work properly.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KConfig (de)

2008-01-01T15:28:56Z

Rememberme: /* Zusammenfassung */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer- und Gruppenprofile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

TODO: (deserialization?)

Anwendungen selbst müssen darum normalerweise Objekte nicht selber gliedern und entgliedern.

Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== The KConfig Class ==

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>
// a plain old read/write config object
KConfig config("myapprc");

// a specific file in the filesystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// not merged with global values
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// not merged with globals or the $KDEDIRS hierarchy
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// config specific to a component, in this case a plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// outside the standard config resource
KConfig dataResource( "data", "myapp/somefile" );
</code>

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.

{{tip|For more information on how the merging works, see the [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Filesystem Hierarchy]] article.}}

On line 6 we open a specific local file, this case {{path|/etc/kderc}}. This performs no merging of values and expects an INI style file.

Line 9 sees the creation of a configuration object that is not merged with the global <tt>kdeglobals</tt> configuration object, while the configuration file on line 12 is additionally not merged with any files in the <tt>$KDEDIRS</tt> hierarchy. This can noticeably improve performance in the case where one is simply reading values out of a simple configuration for which global values are not meaningful.

Line 15 creates a configuration object using the {{class|KComponentData}} object that belongs to a plugin or other component. The plugin may have a different set of directories defined in its {{class|KStandardDirs}} and this is a way of ensuring that {{class|KConfig}} respects this.

Finally on line 18 we see the creation of a configuration object that does not exist in the <tt>config</tt> resource but rather in the application <tt>data</tt> resource. You may use any resource that {{class|KStandardDirs}} is aware of, including ones that are added at runtime.

=== 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:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// note that this is actually a KSharedConfig
// more on that class in a bit!
KConfig* config = KGlobal::config();
}
</code>

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:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

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>.

Finally there is a global configuration object, <tt>kdeglobals</tt>, that is shared by every application. It holds such information as the default application shortcuts for various actions. It is "blended" into the configuration object if the <tt>KConfig::IncludeGlobals</tt> flag is passed to the {{class|KConfig}} constructor, which is the default.

=== Commonly Useful Methods ===

To save the current state of the configuration object we call the <tt>sync()</tt> method. This method is also called when the object is destroyed. If no changes have been made or the resource reports itself as non-writable (such as in the case of the user not having write permissions to the file) then no disk activity occurs. <tt>sync()</tt> merges changes performed concurrently by other processes - local changes have priority, though.

If we want to make sure that we have the latest values from disk we can call <tt>reparseConfiguration()</tt> which calls <tt>sync()</tt> and then reloads the data from disk.

If we need to prevent the config object from saving already made modifications to disk we need to call <tt>markAsClean()</tt>. A particular use case for this is rolling back the configuration to the on-disk state by calling <tt>markAsClean()</tt> followed by <tt>reparseConfiguration()</tt>.

Listing all groups in a configuration object is as simple as calling <tt>groupList()</tt> as in this code snippet:

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

The {{class|KSharedConfig}} class is a reference counted version of {{class|KConfig}}. It thus provides a way to reference the same configuration object from multiple places in your application without the extra overhead of separate objects or concerns about syncronizing writes to disk even if the configuration object is updated from multiple code paths.

Accessing a {{class|KSharedConfig}} object is as easy as this:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<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.

{{class|KSharedConfig}} is generally recommended over using {{class|KConfig}} itself, and the object returned from {{class|KComponentData}} is indeed a {{class|KSharedConfig}} object.

== KConfigGroup ==

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>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ... or a bit differently ...
</code>

You can pass {{class|KConfig}} or {{class|KSharedConfig}} objects to {{class|KConfigGroup}}.

Config groups can be nested as well:

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Reading Entries ==

With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

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.

There are a couple of special read methods, including <tt>readPathEntry</tt> which returns a file system path. It is vital that one uses <tt>readPathEntry</tt> if it is a path as this enables such features as roaming profiles to work properly.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KConfig (de)

2008-01-01T15:28:33Z

Rememberme: /* Zusammenfassung */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über den grundlegenden Aufbau aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer und Gruppen Profile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

TODO: (deserialization?)

Anwendungen selbst müssen darum normalerweise Objekte nicht selber gliedern und entgliedern.

Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== The KConfig Class ==

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>
// a plain old read/write config object
KConfig config("myapprc");

// a specific file in the filesystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// not merged with global values
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// not merged with globals or the $KDEDIRS hierarchy
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// config specific to a component, in this case a plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// outside the standard config resource
KConfig dataResource( "data", "myapp/somefile" );
</code>

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.

{{tip|For more information on how the merging works, see the [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Filesystem Hierarchy]] article.}}

On line 6 we open a specific local file, this case {{path|/etc/kderc}}. This performs no merging of values and expects an INI style file.

Line 9 sees the creation of a configuration object that is not merged with the global <tt>kdeglobals</tt> configuration object, while the configuration file on line 12 is additionally not merged with any files in the <tt>$KDEDIRS</tt> hierarchy. This can noticeably improve performance in the case where one is simply reading values out of a simple configuration for which global values are not meaningful.

Line 15 creates a configuration object using the {{class|KComponentData}} object that belongs to a plugin or other component. The plugin may have a different set of directories defined in its {{class|KStandardDirs}} and this is a way of ensuring that {{class|KConfig}} respects this.

Finally on line 18 we see the creation of a configuration object that does not exist in the <tt>config</tt> resource but rather in the application <tt>data</tt> resource. You may use any resource that {{class|KStandardDirs}} is aware of, including ones that are added at runtime.

=== 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:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// note that this is actually a KSharedConfig
// more on that class in a bit!
KConfig* config = KGlobal::config();
}
</code>

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:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

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>.

Finally there is a global configuration object, <tt>kdeglobals</tt>, that is shared by every application. It holds such information as the default application shortcuts for various actions. It is "blended" into the configuration object if the <tt>KConfig::IncludeGlobals</tt> flag is passed to the {{class|KConfig}} constructor, which is the default.

=== Commonly Useful Methods ===

To save the current state of the configuration object we call the <tt>sync()</tt> method. This method is also called when the object is destroyed. If no changes have been made or the resource reports itself as non-writable (such as in the case of the user not having write permissions to the file) then no disk activity occurs. <tt>sync()</tt> merges changes performed concurrently by other processes - local changes have priority, though.

If we want to make sure that we have the latest values from disk we can call <tt>reparseConfiguration()</tt> which calls <tt>sync()</tt> and then reloads the data from disk.

If we need to prevent the config object from saving already made modifications to disk we need to call <tt>markAsClean()</tt>. A particular use case for this is rolling back the configuration to the on-disk state by calling <tt>markAsClean()</tt> followed by <tt>reparseConfiguration()</tt>.

Listing all groups in a configuration object is as simple as calling <tt>groupList()</tt> as in this code snippet:

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

The {{class|KSharedConfig}} class is a reference counted version of {{class|KConfig}}. It thus provides a way to reference the same configuration object from multiple places in your application without the extra overhead of separate objects or concerns about syncronizing writes to disk even if the configuration object is updated from multiple code paths.

Accessing a {{class|KSharedConfig}} object is as easy as this:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<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.

{{class|KSharedConfig}} is generally recommended over using {{class|KConfig}} itself, and the object returned from {{class|KComponentData}} is indeed a {{class|KSharedConfig}} object.

== KConfigGroup ==

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>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ... or a bit differently ...
</code>

You can pass {{class|KConfig}} or {{class|KSharedConfig}} objects to {{class|KConfigGroup}}.

Config groups can be nested as well:

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Reading Entries ==

With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

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.

There are a couple of special read methods, including <tt>readPathEntry</tt> which returns a file system path. It is vital that one uses <tt>readPathEntry</tt> if it is a path as this enables such features as roaming profiles to work properly.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KConfig (de)

2008-01-01T15:27:57Z

Rememberme: /* Grundlegender Aufbau */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über die Grundlagen des Aufbaus aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer und Gruppen Profile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

Diese Konfigurationsobjekte sind nach einer zweistufigen Hierarchie getrennt: Gruppen und Schlüssel. Ein Konfigurationsobjekt kann eine beliebige Anzahl an Gruppen haben und jede Gruppe kann einen oder mehrere Schlüssel mit zugehörigen Werten haben.

Die gespeicherten Werte können aus beliebig vielen verschiedenen Datentypen bestehen. Sie werden gespeichert und abgerufen als das Objekt selbst. Zum Beispiel wird ein {{qt|QObject}}-Objekt direkt einem Konfigurationsobjekt übergeben, wenn es einen Farbwert speichert und wenn ein Farbwert abgerufen wird, wird ein {{qt|QObject}}-Objekt zurückgegeben.

TODO: (deserialization?)

Anwendungen selbst müssen darum normalerweise Objekte nicht selber gliedern und entgliedern.

Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== The KConfig Class ==

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>
// a plain old read/write config object
KConfig config("myapprc");

// a specific file in the filesystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// not merged with global values
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// not merged with globals or the $KDEDIRS hierarchy
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// config specific to a component, in this case a plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// outside the standard config resource
KConfig dataResource( "data", "myapp/somefile" );
</code>

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.

{{tip|For more information on how the merging works, see the [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Filesystem Hierarchy]] article.}}

On line 6 we open a specific local file, this case {{path|/etc/kderc}}. This performs no merging of values and expects an INI style file.

Line 9 sees the creation of a configuration object that is not merged with the global <tt>kdeglobals</tt> configuration object, while the configuration file on line 12 is additionally not merged with any files in the <tt>$KDEDIRS</tt> hierarchy. This can noticeably improve performance in the case where one is simply reading values out of a simple configuration for which global values are not meaningful.

Line 15 creates a configuration object using the {{class|KComponentData}} object that belongs to a plugin or other component. The plugin may have a different set of directories defined in its {{class|KStandardDirs}} and this is a way of ensuring that {{class|KConfig}} respects this.

Finally on line 18 we see the creation of a configuration object that does not exist in the <tt>config</tt> resource but rather in the application <tt>data</tt> resource. You may use any resource that {{class|KStandardDirs}} is aware of, including ones that are added at runtime.

=== 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:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// note that this is actually a KSharedConfig
// more on that class in a bit!
KConfig* config = KGlobal::config();
}
</code>

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:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

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>.

Finally there is a global configuration object, <tt>kdeglobals</tt>, that is shared by every application. It holds such information as the default application shortcuts for various actions. It is "blended" into the configuration object if the <tt>KConfig::IncludeGlobals</tt> flag is passed to the {{class|KConfig}} constructor, which is the default.

=== Commonly Useful Methods ===

To save the current state of the configuration object we call the <tt>sync()</tt> method. This method is also called when the object is destroyed. If no changes have been made or the resource reports itself as non-writable (such as in the case of the user not having write permissions to the file) then no disk activity occurs. <tt>sync()</tt> merges changes performed concurrently by other processes - local changes have priority, though.

If we want to make sure that we have the latest values from disk we can call <tt>reparseConfiguration()</tt> which calls <tt>sync()</tt> and then reloads the data from disk.

If we need to prevent the config object from saving already made modifications to disk we need to call <tt>markAsClean()</tt>. A particular use case for this is rolling back the configuration to the on-disk state by calling <tt>markAsClean()</tt> followed by <tt>reparseConfiguration()</tt>.

Listing all groups in a configuration object is as simple as calling <tt>groupList()</tt> as in this code snippet:

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

The {{class|KSharedConfig}} class is a reference counted version of {{class|KConfig}}. It thus provides a way to reference the same configuration object from multiple places in your application without the extra overhead of separate objects or concerns about syncronizing writes to disk even if the configuration object is updated from multiple code paths.

Accessing a {{class|KSharedConfig}} object is as easy as this:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<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.

{{class|KSharedConfig}} is generally recommended over using {{class|KConfig}} itself, and the object returned from {{class|KComponentData}} is indeed a {{class|KSharedConfig}} object.

== KConfigGroup ==

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>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ... or a bit differently ...
</code>

You can pass {{class|KConfig}} or {{class|KSharedConfig}} objects to {{class|KConfigGroup}}.

Config groups can be nested as well:

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Reading Entries ==

With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

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.

There are a couple of special read methods, including <tt>readPathEntry</tt> which returns a file system path. It is vital that one uses <tt>readPathEntry</tt> if it is a path as this enables such features as roaming profiles to work properly.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KConfig (de)

2008-01-01T14:49:24Z

Rememberme: /* Grundlagen des Aufbaus */

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über die Grundlagen des Aufbaus aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer und Gruppen Profile) Integration fort.

== Grundlegender Aufbau ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

Das behält alle KDE Anwendungen konsistent in ihrer Art, Konfigurationen handzuhaben und nimmt einem Anwendungs-Entwickler die Arbeit so ein System von Grund auf neu zu schreiben, was ein sehr fehleranfälliger Prozess sein kann.

Jedes KConfig Objekt verkörpert ein einziges Konfigurationsobjekt. Jedes Konfigurationsobjekt ist durch seinen einzigartigen Namen gekennzeichnet und kann von mehreren lokalen oder externen Daten oder Services gelesen werden. Jede Anwendung hat standardmässig ein zugehöriges Konfigurationsobjekt und es gibt auch ein globales Konfigurationsobjekt.

TODO:

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|QObject}} object is passed to a config object directly when storing a color value and when retreived a {{qt|QObject}} object is returned. Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== The KConfig Class ==

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>
// a plain old read/write config object
KConfig config("myapprc");

// a specific file in the filesystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// not merged with global values
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// not merged with globals or the $KDEDIRS hierarchy
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// config specific to a component, in this case a plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// outside the standard config resource
KConfig dataResource( "data", "myapp/somefile" );
</code>

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.

{{tip|For more information on how the merging works, see the [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Filesystem Hierarchy]] article.}}

On line 6 we open a specific local file, this case {{path|/etc/kderc}}. This performs no merging of values and expects an INI style file.

Line 9 sees the creation of a configuration object that is not merged with the global <tt>kdeglobals</tt> configuration object, while the configuration file on line 12 is additionally not merged with any files in the <tt>$KDEDIRS</tt> hierarchy. This can noticeably improve performance in the case where one is simply reading values out of a simple configuration for which global values are not meaningful.

Line 15 creates a configuration object using the {{class|KComponentData}} object that belongs to a plugin or other component. The plugin may have a different set of directories defined in its {{class|KStandardDirs}} and this is a way of ensuring that {{class|KConfig}} respects this.

Finally on line 18 we see the creation of a configuration object that does not exist in the <tt>config</tt> resource but rather in the application <tt>data</tt> resource. You may use any resource that {{class|KStandardDirs}} is aware of, including ones that are added at runtime.

=== 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:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// note that this is actually a KSharedConfig
// more on that class in a bit!
KConfig* config = KGlobal::config();
}
</code>

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:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

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>.

Finally there is a global configuration object, <tt>kdeglobals</tt>, that is shared by every application. It holds such information as the default application shortcuts for various actions. It is "blended" into the configuration object if the <tt>KConfig::IncludeGlobals</tt> flag is passed to the {{class|KConfig}} constructor, which is the default.

=== Commonly Useful Methods ===

To save the current state of the configuration object we call the <tt>sync()</tt> method. This method is also called when the object is destroyed. If no changes have been made or the resource reports itself as non-writable (such as in the case of the user not having write permissions to the file) then no disk activity occurs. <tt>sync()</tt> merges changes performed concurrently by other processes - local changes have priority, though.

If we want to make sure that we have the latest values from disk we can call <tt>reparseConfiguration()</tt> which calls <tt>sync()</tt> and then reloads the data from disk.

If we need to prevent the config object from saving already made modifications to disk we need to call <tt>markAsClean()</tt>. A particular use case for this is rolling back the configuration to the on-disk state by calling <tt>markAsClean()</tt> followed by <tt>reparseConfiguration()</tt>.

Listing all groups in a configuration object is as simple as calling <tt>groupList()</tt> as in this code snippet:

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

The {{class|KSharedConfig}} class is a reference counted version of {{class|KConfig}}. It thus provides a way to reference the same configuration object from multiple places in your application without the extra overhead of separate objects or concerns about syncronizing writes to disk even if the configuration object is updated from multiple code paths.

Accessing a {{class|KSharedConfig}} object is as easy as this:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<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.

{{class|KSharedConfig}} is generally recommended over using {{class|KConfig}} itself, and the object returned from {{class|KComponentData}} is indeed a {{class|KSharedConfig}} object.

== KConfigGroup ==

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>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ... or a bit differently ...
</code>

You can pass {{class|KConfig}} or {{class|KSharedConfig}} objects to {{class|KConfigGroup}}.

Config groups can be nested as well:

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Reading Entries ==

With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

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.

There are a couple of special read methods, including <tt>readPathEntry</tt> which returns a file system path. It is vital that one uses <tt>readPathEntry</tt> if it is a path as this enables such features as roaming profiles to work properly.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KConfig (de)

2008-01-01T12:45:04Z

Rememberme:

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über die Grundlagen des Aufbaus aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer und Gruppen Profile) Integration fort.

== Grundlagen des Aufbaus ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

TODO:

This keeps all KDE applications consistent in their handling of configurations while alleviating each and every application author to build such a system on their own from scratch, which can be a highly error prone exercise.

A KConfig object represents a single configuration object. Each configuration object is referenced by its unique name and may be actually read from multiple local or remote files or services. Each application has a default configuration object associated with it and there is also a global configuration object.

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|QObject}} object is passed to a config object directly when storing a color value and when retreived a {{qt|QObject}} object is returned. Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== The KConfig Class ==

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>
// a plain old read/write config object
KConfig config("myapprc");

// a specific file in the filesystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// not merged with global values
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// not merged with globals or the $KDEDIRS hierarchy
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// config specific to a component, in this case a plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// outside the standard config resource
KConfig dataResource( "data", "myapp/somefile" );
</code>

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.

{{tip|For more information on how the merging works, see the [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Filesystem Hierarchy]] article.}}

On line 6 we open a specific local file, this case {{path|/etc/kderc}}. This performs no merging of values and expects an INI style file.

Line 9 sees the creation of a configuration object that is not merged with the global <tt>kdeglobals</tt> configuration object, while the configuration file on line 12 is additionally not merged with any files in the <tt>$KDEDIRS</tt> hierarchy. This can noticeably improve performance in the case where one is simply reading values out of a simple configuration for which global values are not meaningful.

Line 15 creates a configuration object using the {{class|KComponentData}} object that belongs to a plugin or other component. The plugin may have a different set of directories defined in its {{class|KStandardDirs}} and this is a way of ensuring that {{class|KConfig}} respects this.

Finally on line 18 we see the creation of a configuration object that does not exist in the <tt>config</tt> resource but rather in the application <tt>data</tt> resource. You may use any resource that {{class|KStandardDirs}} is aware of, including ones that are added at runtime.

=== 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:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// note that this is actually a KSharedConfig
// more on that class in a bit!
KConfig* config = KGlobal::config();
}
</code>

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:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

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>.

Finally there is a global configuration object, <tt>kdeglobals</tt>, that is shared by every application. It holds such information as the default application shortcuts for various actions. It is "blended" into the configuration object if the <tt>KConfig::IncludeGlobals</tt> flag is passed to the {{class|KConfig}} constructor, which is the default.

=== Commonly Useful Methods ===

To save the current state of the configuration object we call the <tt>sync()</tt> method. This method is also called when the object is destroyed. If no changes have been made or the resource reports itself as non-writable (such as in the case of the user not having write permissions to the file) then no disk activity occurs. <tt>sync()</tt> merges changes performed concurrently by other processes - local changes have priority, though.

If we want to make sure that we have the latest values from disk we can call <tt>reparseConfiguration()</tt> which calls <tt>sync()</tt> and then reloads the data from disk.

If we need to prevent the config object from saving already made modifications to disk we need to call <tt>markAsClean()</tt>. A particular use case for this is rolling back the configuration to the on-disk state by calling <tt>markAsClean()</tt> followed by <tt>reparseConfiguration()</tt>.

Listing all groups in a configuration object is as simple as calling <tt>groupList()</tt> as in this code snippet:

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

The {{class|KSharedConfig}} class is a reference counted version of {{class|KConfig}}. It thus provides a way to reference the same configuration object from multiple places in your application without the extra overhead of separate objects or concerns about syncronizing writes to disk even if the configuration object is updated from multiple code paths.

Accessing a {{class|KSharedConfig}} object is as easy as this:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<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.

{{class|KSharedConfig}} is generally recommended over using {{class|KConfig}} itself, and the object returned from {{class|KComponentData}} is indeed a {{class|KSharedConfig}} object.

== KConfigGroup ==

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>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ... or a bit differently ...
</code>

You can pass {{class|KConfig}} or {{class|KSharedConfig}} objects to {{class|KConfigGroup}}.

Config groups can be nested as well:

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Reading Entries ==

With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

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.

There are a couple of special read methods, including <tt>readPathEntry</tt> which returns a file system path. It is vital that one uses <tt>readPathEntry</tt> if it is a path as this enables such features as roaming profiles to work properly.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KConfig (de)

2008-01-01T12:44:47Z

Rememberme:

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

pre=Keine

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über die Grundlagen des Aufbaus aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer und Gruppen Profile) Integration fort.

== Grundlagen des Aufbaus ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

TODO:

This keeps all KDE applications consistent in their handling of configurations while alleviating each and every application author to build such a system on their own from scratch, which can be a highly error prone exercise.

A KConfig object represents a single configuration object. Each configuration object is referenced by its unique name and may be actually read from multiple local or remote files or services. Each application has a default configuration object associated with it and there is also a global configuration object.

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|QObject}} object is passed to a config object directly when storing a color value and when retreived a {{qt|QObject}} object is returned. Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== The KConfig Class ==

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>
// a plain old read/write config object
KConfig config("myapprc");

// a specific file in the filesystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// not merged with global values
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// not merged with globals or the $KDEDIRS hierarchy
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// config specific to a component, in this case a plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// outside the standard config resource
KConfig dataResource( "data", "myapp/somefile" );
</code>

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.

{{tip|For more information on how the merging works, see the [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Filesystem Hierarchy]] article.}}

On line 6 we open a specific local file, this case {{path|/etc/kderc}}. This performs no merging of values and expects an INI style file.

Line 9 sees the creation of a configuration object that is not merged with the global <tt>kdeglobals</tt> configuration object, while the configuration file on line 12 is additionally not merged with any files in the <tt>$KDEDIRS</tt> hierarchy. This can noticeably improve performance in the case where one is simply reading values out of a simple configuration for which global values are not meaningful.

Line 15 creates a configuration object using the {{class|KComponentData}} object that belongs to a plugin or other component. The plugin may have a different set of directories defined in its {{class|KStandardDirs}} and this is a way of ensuring that {{class|KConfig}} respects this.

Finally on line 18 we see the creation of a configuration object that does not exist in the <tt>config</tt> resource but rather in the application <tt>data</tt> resource. You may use any resource that {{class|KStandardDirs}} is aware of, including ones that are added at runtime.

=== 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:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// note that this is actually a KSharedConfig
// more on that class in a bit!
KConfig* config = KGlobal::config();
}
</code>

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:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

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>.

Finally there is a global configuration object, <tt>kdeglobals</tt>, that is shared by every application. It holds such information as the default application shortcuts for various actions. It is "blended" into the configuration object if the <tt>KConfig::IncludeGlobals</tt> flag is passed to the {{class|KConfig}} constructor, which is the default.

=== Commonly Useful Methods ===

To save the current state of the configuration object we call the <tt>sync()</tt> method. This method is also called when the object is destroyed. If no changes have been made or the resource reports itself as non-writable (such as in the case of the user not having write permissions to the file) then no disk activity occurs. <tt>sync()</tt> merges changes performed concurrently by other processes - local changes have priority, though.

If we want to make sure that we have the latest values from disk we can call <tt>reparseConfiguration()</tt> which calls <tt>sync()</tt> and then reloads the data from disk.

If we need to prevent the config object from saving already made modifications to disk we need to call <tt>markAsClean()</tt>. A particular use case for this is rolling back the configuration to the on-disk state by calling <tt>markAsClean()</tt> followed by <tt>reparseConfiguration()</tt>.

Listing all groups in a configuration object is as simple as calling <tt>groupList()</tt> as in this code snippet:

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

The {{class|KSharedConfig}} class is a reference counted version of {{class|KConfig}}. It thus provides a way to reference the same configuration object from multiple places in your application without the extra overhead of separate objects or concerns about syncronizing writes to disk even if the configuration object is updated from multiple code paths.

Accessing a {{class|KSharedConfig}} object is as easy as this:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<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.

{{class|KSharedConfig}} is generally recommended over using {{class|KConfig}} itself, and the object returned from {{class|KComponentData}} is indeed a {{class|KSharedConfig}} object.

== KConfigGroup ==

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>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ... or a bit differently ...
</code>

You can pass {{class|KConfig}} or {{class|KSharedConfig}} objects to {{class|KConfigGroup}}.

Config groups can be nested as well:

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Reading Entries ==

With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

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.

There are a couple of special read methods, including <tt>readPathEntry</tt> which returns a file system path. It is vital that one uses <tt>readPathEntry</tt> if it is a path as this enables such features as roaming profiles to work properly.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KConfig (de)

2008-01-01T12:44:05Z

Rememberme: New page: {{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}} {{TutorialBrowser (de)| series=KConfig| name=Einführung in KConfig| next=[[../Using_KConfig_XT (de)|Benutzen vo...

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}

{{TutorialBrowser (de)|

series=KConfig|

name=Einführung in KConfig|

next=[[../Using_KConfig_XT (de)|Benutzen von KConfig XT]]|

reading=Keine

}}

== Zusammenfassung ==

Dieser Artikel beschäftigt sich mir dem KDE Einstellungdaten-System, angefangen mit einer Übersicht über die Grundlagen des Aufbaus aus der Sicht eines Entwicklers. Es wirft ausserdem einen Blick auf jede der Klassen, die für die Entwicklung von Anwendungen relevant sind und fährt dann mit kiosk (Benutzer und Gruppen Profile) Integration fort.

== Grundlagen des Aufbaus ==

KConfig ist ausgelegt um das Konzept vom eigentlichen Speichern und Auffinden von Konfigurationsdaten hinter eine Programmierschnittstelle zu abstrahieren die es ermöglicht, auf einfache Weise Informationen abzurufen und zu setzen. Wo oder in welcher Form Daten gespeichert werden ist für eine Anwendung die KConfig benutzt irrelevant.

TODO:

This keeps all KDE applications consistent in their handling of configurations while alleviating each and every application author to build such a system on their own from scratch, which can be a highly error prone exercise.

A KConfig object represents a single configuration object. Each configuration object is referenced by its unique name and may be actually read from multiple local or remote files or services. Each application has a default configuration object associated with it and there is also a global configuration object.

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|QObject}} object is passed to a config object directly when storing a color value and when retreived a {{qt|QObject}} object is returned. Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== The KConfig Class ==

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>
// a plain old read/write config object
KConfig config("myapprc");

// a specific file in the filesystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// not merged with global values
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// not merged with globals or the $KDEDIRS hierarchy
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// config specific to a component, in this case a plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// outside the standard config resource
KConfig dataResource( "data", "myapp/somefile" );
</code>

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.

{{tip|For more information on how the merging works, see the [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Filesystem Hierarchy]] article.}}

On line 6 we open a specific local file, this case {{path|/etc/kderc}}. This performs no merging of values and expects an INI style file.

Line 9 sees the creation of a configuration object that is not merged with the global <tt>kdeglobals</tt> configuration object, while the configuration file on line 12 is additionally not merged with any files in the <tt>$KDEDIRS</tt> hierarchy. This can noticeably improve performance in the case where one is simply reading values out of a simple configuration for which global values are not meaningful.

Line 15 creates a configuration object using the {{class|KComponentData}} object that belongs to a plugin or other component. The plugin may have a different set of directories defined in its {{class|KStandardDirs}} and this is a way of ensuring that {{class|KConfig}} respects this.

Finally on line 18 we see the creation of a configuration object that does not exist in the <tt>config</tt> resource but rather in the application <tt>data</tt> resource. You may use any resource that {{class|KStandardDirs}} is aware of, including ones that are added at runtime.

=== 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:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// note that this is actually a KSharedConfig
// more on that class in a bit!
KConfig* config = KGlobal::config();
}
</code>

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:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

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>.

Finally there is a global configuration object, <tt>kdeglobals</tt>, that is shared by every application. It holds such information as the default application shortcuts for various actions. It is "blended" into the configuration object if the <tt>KConfig::IncludeGlobals</tt> flag is passed to the {{class|KConfig}} constructor, which is the default.

=== Commonly Useful Methods ===

To save the current state of the configuration object we call the <tt>sync()</tt> method. This method is also called when the object is destroyed. If no changes have been made or the resource reports itself as non-writable (such as in the case of the user not having write permissions to the file) then no disk activity occurs. <tt>sync()</tt> merges changes performed concurrently by other processes - local changes have priority, though.

If we want to make sure that we have the latest values from disk we can call <tt>reparseConfiguration()</tt> which calls <tt>sync()</tt> and then reloads the data from disk.

If we need to prevent the config object from saving already made modifications to disk we need to call <tt>markAsClean()</tt>. A particular use case for this is rolling back the configuration to the on-disk state by calling <tt>markAsClean()</tt> followed by <tt>reparseConfiguration()</tt>.

Listing all groups in a configuration object is as simple as calling <tt>groupList()</tt> as in this code snippet:

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

The {{class|KSharedConfig}} class is a reference counted version of {{class|KConfig}}. It thus provides a way to reference the same configuration object from multiple places in your application without the extra overhead of separate objects or concerns about syncronizing writes to disk even if the configuration object is updated from multiple code paths.

Accessing a {{class|KSharedConfig}} object is as easy as this:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<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.

{{class|KSharedConfig}} is generally recommended over using {{class|KConfig}} itself, and the object returned from {{class|KComponentData}} is indeed a {{class|KSharedConfig}} object.

== KConfigGroup ==

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>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ... or a bit differently ...
</code>

You can pass {{class|KConfig}} or {{class|KSharedConfig}} objects to {{class|KConfigGroup}}.

Config groups can be nested as well:

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Reading Entries ==

With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

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.

There are a couple of special read methods, including <tt>readPathEntry</tt> which returns a file system path. It is vital that one uses <tt>readPathEntry</tt> if it is a path as this enables such features as roaming profiles to work properly.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KCmdLineArgs (de)

2008-01-01T11:44:14Z

Rememberme:

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KCmdLineArgs}}

{{TutorialBrowser (de)|

series=Anleitung für Anfänger|

name=Befehlszeilen Argumente (Under construction)|

pre=[[Development/Tutorials/Saving and loading (de)|Anleitung 4 - Laden und Speichern von Dateien]]|

next=[[Development/Tutorials/###|Tutorial 6 - ###]])|

reading={{class|KCmdLineArgs}} {{class|KCmdLineOptions}}
}}

==Zusammenfassung==

In diesem Kapitel werden sie lernen ihrer Anwendung zu ermöglichen, Dateien über die Befehlszeile zu öffnen oder sogar mit 'Öffnen mit' von Dolphin aus zu verwenden.

[[image:introtokdetutorial5.png|frame|center]]

== The Code ==

===main.cpp===
<code cppqt n>
#include <KApplication>
#include <KAboutData>
#include <KCmdLineArgs>
#include <KUrl> //new

#include "mainwindow.h"

int main (int argc, char *argv[])
{
KAboutData aboutData( "tutorial5", "tutorial5",
ki18n("Tutorial 5"), "1.0",
ki18n("A simple text area which can load and save."),
KAboutData::License_GPL,
ki18n("Copyright (c) 2007 Developer") );
KCmdLineArgs::init( argc, argv, &aboutData );

KCmdLineOptions options; //new
options.add("+[file]", ki18n("Document to open")); //new
KCmdLineArgs::addCmdLineOptions(options); //new

KApplication app;

MainWindow* window = new MainWindow();
window->show();

KCmdLineArgs *args = KCmdLineArgs::parsedArgs(); //new
if(args->count()) //new
{
window->openFile(args->url(0).url()); //new
}

return app.exec();
}
</code>

===mainwindow.h===
<code cppqt n>
#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include <KXmlGuiWindow>
#include <KTextEdit>

class MainWindow : public KXmlGuiWindow
{
Q_OBJECT

public:
MainWindow(QWidget *parent=0);
void openFile(const QString &inputFileName); //new

private:
KTextEdit* textArea;
void setupActions();
QString fileName;

private slots:
void newFile();
void openFile();
void saveFile();
void saveFileAs();
void saveFileAs(const QString &outputFileName);
};

#endif
</code>

===mainwindow.cpp===
<code cppqt n>
#include "mainwindow.h"

#include <KApplication>
#include <KAction>
#include <KLocale>
#include <KActionCollection>
#include <KStandardAction>
#include <KFileDialog>
#include <KMessageBox>
#include <KIO/NetAccess>
#include <KSaveFile>
#include <QTextStream>

MainWindow::MainWindow(QWidget *parent)
: KXmlGuiWindow(parent),
fileName(QString())
{
textArea = new KTextEdit;
setCentralWidget(textArea);

setupActions();
}

void MainWindow::setupActions()
{
KAction* clearAction = new KAction(this);
clearAction->setText(i18n("Clear"));
clearAction->setIcon(KIcon("document-new"));
clearAction->setShortcut(Qt::CTRL + Qt::Key_W);
actionCollection()->addAction("clear", clearAction);
connect(clearAction, SIGNAL(triggered(bool)),
textArea, SLOT(clear()));

KStandardAction::quit(kapp, SLOT(quit()),
actionCollection());

KStandardAction::open(this, SLOT(openFile()),
actionCollection());

KStandardAction::save(this, SLOT(saveFile()),
actionCollection());

KStandardAction::saveAs(this, SLOT(saveFileAs()),
actionCollection());

KStandardAction::openNew(this, SLOT(newFile()),
actionCollection());

setupGUI();
}

void MainWindow::newFile()
{
fileName.clear();
textArea->clear();
}

void MainWindow::saveFileAs(const QString &outputFileName)
{
KSaveFile file(outputFileName);
file.open();

QByteArray outputByteArray;
outputByteArray.append(textArea->toPlainText());
file.write(outputByteArray);
file.finalize();
file.close();

fileName = outputFileName;
}

void MainWindow::saveFileAs()
{
saveFileAs(KFileDialog::getSaveFileName());
}

void MainWindow::saveFile()
{
if(!fileName.isEmpty())
{
saveFileAs(fileName);
}
else
{
saveFileAs();
}
}

void MainWindow::openFile() //changed
{
openFile(KFileDialog::getOpenFileName());
}

void MainWindow::openFile(const QString &inputFileName) //new
{
QString tmpFile;
if(KIO::NetAccess::download(inputFileName, tmpFile,
this))
{
QFile file(tmpFile);
file.open(QIODevice::ReadOnly);
textArea->setPlainText(QTextStream(&file).readAll());
fileName = inputFileName;

KIO::NetAccess::removeTempFile(tmpFile);
}
else
{
KMessageBox::error(this,
KIO::NetAccess::lastErrorString());
}
}
</code>

===tutorial4ui.rc===
<code xml n>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kpartgui SYSTEM "kpartgui.dtd">
<gui name="tutorial5" version="1">
<ToolBar name="mainToolBar" >
<text>Main Toolbar</text>
<Action name="clear" />
</ToolBar>
<MenuBar>
<Menu name="file" >
<Action name="clear" />
</Menu>
</MenuBar>
</gui>
</code>
Dies ist identisch mit <tt>tutorial'X'ui.rc</tt> aus den letzten beiden Anleitungen ausser dass <tt>name</tt> zu 'tutorial5' geändert wurde.

==Erklärung==

===mainwindow.h===

Hier haben wir nichts weiteres gemacht als eine neue <tt>openFile</tt> Funktion hinzuzufügen, die einen <tt>QString</tt> annimmt:

<code cppqt>
void openFile(const QString &inputFileName);
</code>

===mainwindow.cpp===

Hier gibt es keinen neuen Code, nur Umordnen. Alles aus <tt>void openFile()</tt> wurde in <tt>void openFile(const QString &inputFileName)</tt> verschoben, ausser der Aufruf an <tt>KFileDialog::getOpenFileName()</tt>.

Auf diese Weise können wir <tt>openFile()</tt> aufrufen, wenn wir einen Dialog anzeigen möchten, oder wir können <tt>openFile(QString)</tt> aufrufen, falls wir den Namen der Datei bereits kennen.

===main.cpp===

Hier passiert die ganze {{class|KCmdLineArgs}} Hexerei.

==Erzeugen, Installieren und Ausführen==

===CMakeLists.txt===
<code ini n>
project(tutorial5)

find_package(KDE4 REQUIRED)
include_directories( ${KDE4_INCLUDES} )

set(tutorial5_SRCS
main.cpp
mainwindow.cpp
)

kde4_add_executable(tutorial5 ${tutorial5_SRCS})

target_link_libraries(tutorial5 ${KDE4_KDEUI_LIBS}
${KDE4_KIO_LIBS})

install(TARGETS tutorial5 DESTINATION ${BIN_INSTALL_DIR})
install( FILES tutorial5ui.rc
DESTINATION ${DATA_INSTALL_DIR}/tutorial5 )
</code>

Mit dieser Datei kann die Anleitung auf die gleiche Weise erstellt und ausgeführt werden wie Anleitung 3 und 4. Für mehr Informationen siehe [[Development/Tutorials/Using KActions (de)|Anleitung 3]].

mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=$HOME
make install
$HOME/bin/tutorial5

==Weiter Geht's==
Now you can move on to the ### (TODO [[User:milliams]]) tutorial.

[[Category:C++]]

Development/Tutorials (de)

2008-01-01T11:41:03Z

Rememberme:

{{Template:I18n/Language Navigation Bar|Development/Tutorials}}

{{improve (de)|Bitte hilf, die englische Seite vollständig ins Deutsche zu übersetzen.}}

== Einführung in die KDE 4 Programmierung ==
Sind Sie an der Entwicklung von Programmen für KDE 4 interesiert? Wenn ja sind Sie hier genau richtig. Diese Artikelserie richtet sich an alle, die noch nie mit KDE programmiert haben.
;[[Development/Tutorials/First program (de)|Hallo Welt!]]
:''Einführung in die Grundlagen der KDE Programmierung''

;[[Development/Tutorials/Using KXmlGuiWindow (de)|Erstellen eines Hauptfensters]]
:''Dieser Artikel erklärt, wie der wichtigste Teil eines grafischen Programmes erstellt wird: das Hauptfenster.''

;[[Development/Tutorials/Using KActions (de)|Die Verwendung von KActions]]
:''In diesem Artikel erfahren Sie, wie Aktionen und Werkzeugleisten (Toolbars) im Menü hinzugefügt werden können.''

;[[Development/Tutorials/Saving and loading (de)|Laden und Speichern von Dateien]]
:''Dieser Artikel führt die KIO Bibliothek ein und erklärt wie man Dateien laden und speichern kann.''

;[[Development/Tutorials/KCmdLineArgs (de)|Befehlszeilen Argumente (todo)]]
:''In diesem Artikel werden sie lernen ihrer Anwendung zu ermöglichen, Dateien über die Befehlszeile zu öffnen oder sogar mit 'Öffnen mit' von Dolphin aus zu verwenden.''

== Grundlagen ==
;[[Development/Tutorials/KDE4 Porting Guide (de)|Ihre Applikation nach KDE 4 portieren]]
:''Anleitungen Qt3/KDE3 Applikationen nach Qt4/KDE4 zu portieren''

;[[Development/Tutorials/CMake (de)|Einführung in CMake]]
:''Wie man CMake in KDE 4 benutzt''

;[[Development/Tutorials/Common Programming Mistakes (de)|Häufige Programmierfehler]]
:''Einige häufige Fehler die man während der Entwicklung von Qt und KDE Applikationen machen kann und wie man sie vermeidet.''

;[[Development/Tutorials/Using Qt Designer (de)|Den Qt Designer benutzen um Benutzerschnittstellen zu erzeugen]]
:''Wie man UI Dateien mit dem Designer erzeugt und wie man diese in einem KDE Programm integriert.''

== Dienste: Applicationen and Plugins ==
;[[Development/Tutorials/Services/Introduction (de)|Einführung in das Dienst-Framework]]
:''Eine Einführung über das Dienst-Framework in KDE und was es dem Applikationsentwickler zur Verfügung stellen kann. Beschäftigt sich mit dem system configuration cache (SyCoCa), den benötigten Dateien und wie indizierte Informationen benutzt werden.

;[[Development/Tutorials/Services/Traders (de)|Dienste über Trader Queries finden]]
:''Wie man mit der Trader Query Syntax Dienste wie Plugins oder Mimetypes findet, die im SyCoCa zwischengespeichert wurden. ''

;[[Development/Tutorials/Services/Plugins (de)|Erstellen und Laden von Plugins mit KService]]
:''Zeigt, wie man eigene Plugintypen definiert, installiere Plugins findet (einschließlich denen von anderen Herstellern) und wie man diese einfach und portabel läd, indem man KService benutzt.''

== Lokalisation ==
;[[Development/Tutorials/Localization/Unicode (de)|Einführung in Unicode]]
:''Eine Einführung was Unicode ist und wie KDE Applikationen damit umgehen.''

; [[Development/Tutorials/Localization/i18n (de)|Beim Schreiben der Applikation an die Lokalisation denken]]
:''Diese Anleitung beschäftigt sich damit, was Lokalisation ist, warum sie wichtig ist und wie man sicherstellt, dass die eigene Applikation bereit ist, lokalisiert zu werden. Jeder Applikationsentwickler sollte das lesen.''

; [[Development/Tutorials/Localization/i18n Mistakes (de)|Häufige Fehler vermeiden]]
:''Es gibt einige häufige Fehler, die es verhindern, dass eine Applikation angemesssen übersetzt werden kann. Diese Anleitung zeigt diese Fehler auf und zeigt, wie man sie vermeidet.''

; [[Development/Tutorials/Localization/Language Change (de)|Mit Sprachänderungen umgehen]]
:''Wie man seiner Applikation beibringt beim nächsten Start oder zur Laufzeit eine andere Sprache zu benutzen.''

Development/Tutorials/Using KActions (de)

2008-01-01T11:36:45Z

Rememberme:

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Using_KActions}}

{{TutorialBrowser (de)|

series=Anleitungen für Anfänger|

name=KActions benutzen|

pre=[[Development/Tutorials/Using_KXmlGuiWindow (de)|Anleitung 2 - KXmlGuiWindow]]|

next=[[Development/Tutorials/Saving_and_loading (de)|Anleitung 4 - Laden und Speichern von Dateien]]|

reading=Keine
}}

==Zusammenfassung==
In diesem Kapitel wird das Konzept der Aktionen eingeführt. Aktionen sind ein vereinheitlichter Weg, dem Benutzer eine Interaktion mit Ihrem Programm zu ermöglichen

Soll zum Beispiel durch das Klicken eines Buttons, einem Eintrag im Dateimenü oder einem Tastaturshortcut das Textfeld geleert werden, wird dies alles durch eine {{class|KAction}} bewerkstelligt.

[[image:introtokdetutorial3.png|frame|center]]

==KAction==
Eine {{class|KAction}} ist ein Objekt, welches alle Informationen über das Icon und Shortcuts enthält, welche mit einer bestimmten Aktion assoziiert sind. Diese Aktion läßt sich mit einem [http://doc.trolltech.com/latest/signalsandslots.html slot] verbinden, welcher dann bestimmte Arbeiten ausführt, die bei dieser Aktion vorgesehen sind.

===Eine eigene Aktion erzeugen===
Um eine Aktion zu erzeugen, muss <tt>#include <KAction></tt> in die <tt>.cpp</tt> Datei eingefügt werden.

=====Das Objekt erzeugen=====
Wir werden hier eine Aktion erzeugen, welche die Applikation aus Kapitel 2 dahingehend erweitert, dass durch sie das Textfeld geleert wird. Die KAction wird in einer Reihe einzelner Schritte zusammengestellt. Zunächst wird das Objekt selber erzeugt:
<code cppqt>KAction* clearAction = new KAction(this);</code>
Das erzeugt ein KAction-Objekt welches <tt>clearAction</tt> heißt.

=====Text=====
Bei dem jetzt erzeugten KAction Objekt können jetzt die Eigenschaften gesetzt werden. Zunächst setzen wir einen Text der im Menü und unter seinem Icon in der Werkzeugleiste angezeigt wird:
<code cppqt>clearAction->setText(i18n("Clear"));</code>
Wie man sieht, muss dieser Text durch die <tt>i18n()</tt> Funktion geleitet werden, wenn man das Benutzerinterface später übersetzen möchte.

=====Icon=====
Soll in der Werkzeugleiste die Aktion angezeigt werden, muss man ein Icon verknüpfen, welches die Aktion bildlich beschreibt. Um das zu bewekstelligen, benutzen wir die <tt>setIcon()</tt> Funktion:
<code cppqt>clearAction->setIcon(KIcon("document-new"));</code>
Hier wird das Standardicon <tt>document-new</tt> von KDE benutzt.

=====Shortcut=====
Wir können auch einen Tastaturshortcut definieren, welcher die Aktion ausführt.. Das wird ganz einfach durch <code cppqt>clearAction->setShortcut(Qt::CTRL+Qt::Key_W);</code> bewekstelligt. In diesem Fall wird Ctrl+W mit der Aktion verknüpft.

=====Zur Sammlung hinzufügen=====
Damit das XmlGui Framework auf unsere Aktion zugreifen kann, muss diese in die ''action collection'' (Sammlung der Aktionen) der Applikation eingefügt werden. Auf diese wird über die <tt>actionCollection()</tt> Funktion zugegriffen:
<code cppqt>
actionCollection()->addAction("clear", clearAction);
</code>
Dieser Code fügt die <tt>clearAction</tt> KAction in die Sammlung ein und gibt ihr den Namen ''clear''. Dieser Name wird vom XmlGui Framework benutzt.

=====Die Aktion verbinden=====
Jetzt ist unsere Aktion vollständig aufgesetzt und sie muss nun noch verknüpft werden, damit sie etwas sinnvolles macht. Wir werden unsere Aktion mit dem <tt>clear()</tt> Slot, der zu einem KTextArea Objekt gehört, verknüpfen:
<code cppqt>
connect( clearAction, SIGNAL( triggered(bool) ),
textArea, SLOT( clear() ) );
</code>
Das gleiche würden wir in Qt mit einer {{qt|QAction}} machen

===KStandardAction===

Manche Aktionen, wie zum Beispiel 'beenden', 'speichern' und 'laden', benötigt fast jede KDE Applikation. Daher gibt es zur Vereinfachung vorgefertigte KActions, auf welche über {{class|KStandardAction}} zugegriffen wird.

Diese sind sehr einfach zu benutzen. Sobald man <tt>#include <KStandardAction></tt> im Quellcode eingefügt hat, muss man nur noch festlegen, welche Funktion bei Auslösung aufgerufen werden soll und zu welcher <tt>KActionCollection</tt> die Aktion hinzugefügt werden soll. Beispiel:

<code cppqt>KStandardAction::quit(kapp, SLOT(quit()), actionCollection());</code>
Dieser Code erzeugt ein KAction Objekt mit dem entsprechenden Icon, Text und Shortcut und fügt dieses sogar zum Datei-Menü hinzu.

==Der Code==
===mainwindow.h===
<code cppqt n>
#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include <KXmlGuiWindow>
#include <KTextEdit>

class MainWindow : public KXmlGuiWindow
{
public:
MainWindow(QWidget *parent=0);

private:
KTextEdit* textArea;
void setupActions();
};

#endif
</code>

===mainwindow.cpp===
<code cppqt n>
#include "mainwindow.h"

#include <KApplication>
#include <KAction>
#include <KLocale>
#include <KActionCollection>
#include <KStandardAction>

MainWindow::MainWindow(QWidget *parent)
: KXmlGuiWindow(parent)
{
textArea = new KTextEdit;
setCentralWidget(textArea);

setupActions();
}

void MainWindow::setupActions()
{
KAction* clearAction = new KAction(this);
clearAction->setText(i18n("Clear"));
clearAction->setIcon(KIcon("document-new"));
clearAction->setShortcut(Qt::CTRL+Qt::Key_W);
actionCollection()->addAction("clear", clearAction);
connect(clearAction, SIGNAL(triggered(bool)),
textArea, SLOT(clear()));

KStandardAction::quit(kapp, SLOT(quit()),
actionCollection());

setupGUI();
}
</code>

===main.cpp===
<code cppqt n>
#include <KApplication>
#include <KAboutData>
#include <KCmdLineArgs>

#include "mainwindow.h"

int main (int argc, char *argv[])
{
KAboutData aboutData( "tutorial3", "tutorial3",
ki18n("Tutorial 3"), "1.0",
ki18n("A simple text area using KAction etc."),
KAboutData::License_GPL,
ki18n("Copyright (c) 2007 Developer") );
KCmdLineArgs::init( argc, argv, &aboutData );
KApplication app;

MainWindow* window = new MainWindow();
window->show();
return app.exec();
}
</code>

==Die Aktionen mit den Menüs und Werkzeugleisten verknüpfen==
Zur Zeit haben wir nur unsere neue "Clear" Aktion erzeugt. Zum jetzigen Zeitpunkt würde diese weder in den Menüs noch in den Werkzeugleisten erscheinen. Um der Applikation mitzuteilen wo die Aktion eingefügt werden soll (und dem Benutzer zu ermöglichen, diese dann beliebig umherzuschieben) wird die KDE-Technik namens XmlGui genutzt.

===XmlGui===
{{note (de)|In einer späteren Version von KDE4 könnte XmlGui durch ein neues Framework namens liveui ersetzt werden. Doch zum jetzigen Zeitpunkt ist XmlGui die einzige und korrekte Art, das UI aufzusetzen.}}

Ruft man <tt>setupGUI()</tt> in der {{class|KXmlGuiWindow}} Klasse auf, wird das XmlGui System aufgerufen, welche eine XML Datei einliest, welche das entsprechende interface beschreibt und die Buttons und Menüeinträge entsprechend erzeugt. Diese Datei wird im nächsten Schritt für unsere Applikation erzeugt.

Natürlich muss das XmlGui System wissen, welche Beschreibungs-Datei zu der jeweiligen Applikation gehört. Es muss also dem Namen und den Pfad dieser Datei kennen. Standardmäßig soll die Datei <tt>appnameui.rc</tt> genannt werden(<tt>appname</tt> ist dabei der Name, der in {{class|KAboutData}}) gesetzt wurde). In unserem Beispiel wird die Datei also <tt>tutorial3ui.rc</tt> heißen. Wo die Datei zu finden ist, wird von CMake erledigt.

===Die ''appname''ui.rc Datei schreiben===

Da die Beschreibung unseres UI mit XML definiert wird, muss der Inhalt der Beschreibung strengen Regeln folgen. Wir werden hier nicht alle Regeln auflisten. Darüber wird es eine gesonderte und detailierte Seite geben (die aber noch nicht fertig ist).

===tutorial3ui.rc===
<code xml n>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kpartgui SYSTEM "kpartgui.dtd">
<gui name="tutorial3" version="1">

<ToolBar name="mainToolBar" >
<text>Main Toolbar</text>
<Action name="clear" />
<ActionList name="dynamicActionlist" />
</ToolBar>
<MenuBar>
<Menu name="file" >
<text>&File</text>
<Action name="clear" />
</Menu>
</MenuBar>
</gui>
</code>

Das <tt><Toolbar></tt> Tag beschreibt die Werkzeugleiste (der Balken mit Icons am oberen Rand des Fensters). Wir geben dieser hier den eindeutigen Namen ''mainToolBar'', setzen den Namen, der für den Benutzer sichtbar ist, auf ''Main Toolbar'', indem wir das <tt><text></tt> Tag anwenden und fügen letztlich unsere Clear-Aktion in die Werkzeugleiste ein, indem wir das <tt><Action></tt> Tag benutzen. Der Parameter "name" dieses Tags ist die gleiche Zeichenkette, die der <tt>addAction()</tt> Funktion im C++ Code übergeben wurde.

Neben der Werkzeugleiste können wir die Aktion auch in das Hauptmenü einfügen. Dieses erfolgt über das <tt><MenuBar></tt> Tag. Hier wird festgelegt, dass die Aktion in das ''File'' Menü eingefügt werden soll. Die Aktion selber wird auf die gleiche Art und Weise eingefügt wie bereits in der der Werkzeugleiste beschrieben.

Bitte beachten Sie, dass sie auch eine dynamische Aktionsliste in die Konfigurationsdatei einfügen können, wenn Sie das <tt><ActionList></tt> Tag benutzen. Mehr Informationen darüber finden Sie in der Methodenbeschreibung <tt>plugActionList()</tt> der {{class|KXMLGUIClient}} Dokumentation.

Ändern Sie jedesmal das "version" Attribut des Gui-Tags wenn Sie die .rc Datei geändert haben, damit ein Auffrisches des Systemcaches erfolgt.

==CMake==
Da wir jetzt XmlGui benutzen, muß die <tt>tutorial3ui.rc</tt> Datei irgendwo hin kopiert werden, wo KDE sie finden kann. '''Aus diesem Grund muss unser Programm irgendwo hin installiert werden.'''

===CMakeLists.txt===
<code>
project(tutorial3)

find_package(KDE4 REQUIRED)
include_directories( ${KDE4_INCLUDES} )

set(tutorial3_SRCS
main.cpp
mainwindow.cpp
)

kde4_add_executable(tutorial3 ${tutorial3_SRCS})

target_link_libraries(tutorial3 ${KDE4_KDEUI_LIBS})

install(TARGETS tutorial3 DESTINATION ${BIN_INSTALL_DIR})
install( FILES tutorial3ui.rc
DESTINATION ${DATA_INSTALL_DIR}/tutorial3 )
</code>

Diese Datei sieht fast genau so aus wie diejenige für Kapitel2, hat aber zwei extra Zeilen am Ende. Diese beschreiben, wohin die Dateien installiert werden sollen. Zunächst wird das <tt>tutorial3</tt> Ziel in das Verzeichnis <tt>BIN_INSTALL_DIR</tt> Verzeichnis installiert und anschließend die <tt>tutorial3ui.rc</tt> Datei, die das Layout unseres Userinterfaces beschreibt in das Datenverzeichnis unserer Applikation.

===Erzeugen, Installieren und Ausführen===
Wenn Sie keinen Schreibzugriff auf das KDE4 Installationsverzeichnis haben, können Sie das Programm auch in ein Verzeichnis innerhalb Ihres Heimatverzeichnissen installieren.

Um CMake mitzuteilen, wohin das Programm installiert werden soll, setzen Sie den <tt>DCMAKE_INSTALL_PREFIX</tt> Schalter. Um also das Programm in das KDE Verzeichnis zu installieren, rufen Sie
cmake . -DCMAKE_INSTALL_PREFIX=$KDEDIR
make install
tutorial3
auf.

Wenn man hingegen das Programm irgendwo lokal zu Testzwecken installieren will (bei der zurzeit etwas eingeschränkten Funktionalität unsere Applikation ist es vielleicht nicht unbedingt sinnvoll diese in das KDE Hauptverzeichnis zu installieren), wird mit dem Befehl
cmake . -DCMAKE_INSTALL_PREFIX=/home/kde-devel/kdetmp
eine KDE-artige Verzeichnisstruktur innerhalb des ~/kdetmp Verzeichnissen angelegt und die Applikation in das {{path|/home/kde-devel/kdetmp/bin/tutorial3}} Verzeichnis kopiert.

==Weiter geht's==
Jetzt können sie mit dem Kapitel [[Development/Tutorials/Saving_and_loading (de)| Laden und Speichern von Dateien]] fortfahren.

[[Category:C++]]

Development/Tutorials/KConfig

2007-12-31T18:18:52Z

Rememberme:

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}
{{TutorialBrowser|

series=KConfig|

name=Introduction to KConfig|

next=[[../Using_KConfig_XT|Using KConfig XT]]|

reading=None

}}

== Abstract ==

This tutorial looks at the KDE configuration data system, starting with an overview of the design fundamentals from an application developer's point of view. It then looks at the classes relevant to application development one by one before moving on to kiosk (user and group profiles) integration.

== Design Essentials ==

KConfig is designed to abstract away the concept of actual storage and retrieval of configuration settings behind an API that allows easy fetching and setting of information. Where and in what format the data is stored is not relevant to an application using KConfig. This keeps all KDE applications consistent in their handling of configurations while alleviating each and every application author to build such a system on their own from scratch, which can be a highly error prone exercise.

A KConfig object represents a single configuration object. Each configuration object is referenced by its unique name and may be actually read from multiple local or remote files or services. Each application has a default configuration object associated with it and there is also a global configuration object.

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|QObject}} object is passed to a config object directly when storing a color value and when retreived a {{qt|QObject}} object is returned. Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== The KConfig Class ==

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>
// a plain old read/write config object
KConfig config("myapprc");

// a specific file in the filesystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// not merged with global values
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// not merged with globals or the $KDEDIRS hierarchy
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// config specific to a component, in this case a plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// outside the standard config resource
KConfig dataResource( "data", "myapp/somefile" );
</code>

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.

{{tip|For more information on how the merging works, see the [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Filesystem Hierarchy]] article.}}

On line 6 we open a specific local file, this case {{path|/etc/kderc}}. This performs no merging of values and expects an INI style file.

Line 9 sees the creation of a configuration object that is not merged with the global <tt>kdeglobals</tt> configuration object, while the configuration file on line 12 is additionally not merged with any files in the <tt>$KDEDIRS</tt> hierarchy. This can noticeably improve performance in the case where one is simply reading values out of a simple configuration for which global values are not meaningful.

Line 15 creates a configuration object using the {{class|KComponentData}} object that belongs to a plugin or other component. The plugin may have a different set of directories defined in its {{class|KStandardDirs}} and this is a way of ensuring that {{class|KConfig}} respects this.

Finally on line 18 we see the creation of a configuration object that does not exist in the <tt>config</tt> resource but rather in the application <tt>data</tt> resource. You may use any resource that {{class|KStandardDirs}} is aware of, including ones that are added at runtime.

=== 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:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// note that this is actually a KSharedConfig
// more on that class in a bit!
KConfig* config = KGlobal::config();
}
</code>

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:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

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>.

Finally there is a global configuration object, <tt>kdeglobals</tt>, that is shared by every application. It holds such information as the default application shortcuts for various actions. It is "blended" into the configuration object if the <tt>KConfig::IncludeGlobals</tt> flag is passed to the {{class|KConfig}} constructor, which is the default.

=== Commonly Useful Methods ===

To save the current state of the configuration object we call the <tt>sync()</tt> method. This method is also called when the object is destroyed. If no changes have been made or the resource reports itself as non-writable (such as in the case of the user not having write permissions to the file) then no disk activity occurs. <tt>sync()</tt> merges changes performed concurrently by other processes - local changes have priority, though.

If we want to make sure that we have the latest values from disk we can call <tt>reparseConfiguration()</tt> which calls <tt>sync()</tt> and then reloads the data from disk.

If we need to prevent the config object from saving already made modifications to disk we need to call <tt>markAsClean()</tt>. A particular use case for this is rolling back the configuration to the on-disk state by calling <tt>markAsClean()</tt> followed by <tt>reparseConfiguration()</tt>.

Listing all groups in a configuration object is as simple as calling <tt>groupList()</tt> as in this code snippet:

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

The {{class|KSharedConfig}} class is a reference counted version of {{class|KConfig}}. It thus provides a way to reference the same configuration object from multiple places in your application without the extra overhead of separate objects or concerns about syncronizing writes to disk even if the configuration object is updated from multiple code paths.

Accessing a {{class|KSharedConfig}} object is as easy as this:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<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.

{{class|KSharedConfig}} is generally recommended over using {{class|KConfig}} itself, and the object returned from {{class|KComponentData}} is indeed a {{class|KSharedConfig}} object.

== KConfigGroup ==

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>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ... or a bit differently ...
</code>

You can pass {{class|KConfig}} or {{class|KSharedConfig}} objects to {{class|KConfigGroup}}.

Config groups can be nested as well:

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Reading Entries ==

With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

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.

There are a couple of special read methods, including <tt>readPathEntry</tt> which returns a file system path. It is vital that one uses <tt>readPathEntry</tt> if it is a path as this enables such features as roaming profiles to work properly.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/KConfig

2007-12-31T18:18:38Z

Rememberme:

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}
{{TutorialBrowser|

series=KConfig|

name=Introduction to KConfig|

next=[[../Using_KConfig_XT|Using KConfig XT]]|

reading=none

}}

== Abstract ==

This tutorial looks at the KDE configuration data system, starting with an overview of the design fundamentals from an application developer's point of view. It then looks at the classes relevant to application development one by one before moving on to kiosk (user and group profiles) integration.

== Design Essentials ==

KConfig is designed to abstract away the concept of actual storage and retrieval of configuration settings behind an API that allows easy fetching and setting of information. Where and in what format the data is stored is not relevant to an application using KConfig. This keeps all KDE applications consistent in their handling of configurations while alleviating each and every application author to build such a system on their own from scratch, which can be a highly error prone exercise.

A KConfig object represents a single configuration object. Each configuration object is referenced by its unique name and may be actually read from multiple local or remote files or services. Each application has a default configuration object associated with it and there is also a global configuration object.

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|QObject}} object is passed to a config object directly when storing a color value and when retreived a {{qt|QObject}} object is returned. Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== The KConfig Class ==

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>
// a plain old read/write config object
KConfig config("myapprc");

// a specific file in the filesystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// not merged with global values
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// not merged with globals or the $KDEDIRS hierarchy
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// config specific to a component, in this case a plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// outside the standard config resource
KConfig dataResource( "data", "myapp/somefile" );
</code>

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.

{{tip|For more information on how the merging works, see the [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Filesystem Hierarchy]] article.}}

On line 6 we open a specific local file, this case {{path|/etc/kderc}}. This performs no merging of values and expects an INI style file.

Line 9 sees the creation of a configuration object that is not merged with the global <tt>kdeglobals</tt> configuration object, while the configuration file on line 12 is additionally not merged with any files in the <tt>$KDEDIRS</tt> hierarchy. This can noticeably improve performance in the case where one is simply reading values out of a simple configuration for which global values are not meaningful.

Line 15 creates a configuration object using the {{class|KComponentData}} object that belongs to a plugin or other component. The plugin may have a different set of directories defined in its {{class|KStandardDirs}} and this is a way of ensuring that {{class|KConfig}} respects this.

Finally on line 18 we see the creation of a configuration object that does not exist in the <tt>config</tt> resource but rather in the application <tt>data</tt> resource. You may use any resource that {{class|KStandardDirs}} is aware of, including ones that are added at runtime.

=== 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:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// note that this is actually a KSharedConfig
// more on that class in a bit!
KConfig* config = KGlobal::config();
}
</code>

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:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

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>.

Finally there is a global configuration object, <tt>kdeglobals</tt>, that is shared by every application. It holds such information as the default application shortcuts for various actions. It is "blended" into the configuration object if the <tt>KConfig::IncludeGlobals</tt> flag is passed to the {{class|KConfig}} constructor, which is the default.

=== Commonly Useful Methods ===

To save the current state of the configuration object we call the <tt>sync()</tt> method. This method is also called when the object is destroyed. If no changes have been made or the resource reports itself as non-writable (such as in the case of the user not having write permissions to the file) then no disk activity occurs. <tt>sync()</tt> merges changes performed concurrently by other processes - local changes have priority, though.

If we want to make sure that we have the latest values from disk we can call <tt>reparseConfiguration()</tt> which calls <tt>sync()</tt> and then reloads the data from disk.

If we need to prevent the config object from saving already made modifications to disk we need to call <tt>markAsClean()</tt>. A particular use case for this is rolling back the configuration to the on-disk state by calling <tt>markAsClean()</tt> followed by <tt>reparseConfiguration()</tt>.

Listing all groups in a configuration object is as simple as calling <tt>groupList()</tt> as in this code snippet:

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

The {{class|KSharedConfig}} class is a reference counted version of {{class|KConfig}}. It thus provides a way to reference the same configuration object from multiple places in your application without the extra overhead of separate objects or concerns about syncronizing writes to disk even if the configuration object is updated from multiple code paths.

Accessing a {{class|KSharedConfig}} object is as easy as this:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<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.

{{class|KSharedConfig}} is generally recommended over using {{class|KConfig}} itself, and the object returned from {{class|KComponentData}} is indeed a {{class|KSharedConfig}} object.

== KConfigGroup ==

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>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ... or a bit differently ...
</code>

You can pass {{class|KConfig}} or {{class|KSharedConfig}} objects to {{class|KConfigGroup}}.

Config groups can be nested as well:

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Reading Entries ==

With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

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.

There are a couple of special read methods, including <tt>readPathEntry</tt> which returns a file system path. It is vital that one uses <tt>readPathEntry</tt> if it is a path as this enables such features as roaming profiles to work properly.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

Development/Tutorials/Using KConfig XT

2007-12-31T18:18:09Z

Rememberme:

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Using_KConfig_XT}}
{{TutorialBrowser|

series=KConfig|

pre=[[../KConfig|Introduction to KConfig]]|

next=None|

name=Using KConfig XT|

reading=[http://api.kde.org/4.0-api/kdelibs-apidocs/kdecore/html/kconfig_compiler.html The KDE Configuration Compiler (KDE 4)]<br>[http://api.kde.org/3.5-api/kdelibs-apidocs/kdecore/html/kconfig_compiler.html The KDE Configuration Compiler (KDE 3)]

}}

== Using KConfig XT ==
''Original Author'': Zack Rusin <[mailto:zack@kde.org zack@kde.org]>

This tutorial introduces the main concepts of the KconfigXT
configuration framework and shows how to efficiently use it in applications. It assumes that the reader has already developed a KDE application and is familiar with KConfig. A basic understanding of XML and concepts behind DTDs is also required.

The main idea behind KConfig XT is to make the life of application developers
easier while making the administration of large KDE installations more manageable.
The four basic parts of the new framework are:

* KConfigSkeleton - a class in the libkdecore library which grants a more flexible access to the configuration options,
* XML file containing information about configuration options (the {{path|.kcfg}} file)
* An ini like file which provides the code generation options (the {{path|.kcfgc}} file)
* kconfig_compiler - which generates C++ source code from {{path|.kcfg}} and {{path|.kcfgc}} files. The generated class is based on KConfigSkeleton and provides an API for the application to access its configuration data.

{{note|In this tutorial more advanced and optional features of KConfig XT and their descriptions are marked by ''italic text''. If you decide to skip them during the first reading, be sure to come back to them at some point. }}

== .kcfg DTD Structure ==

The structure of the {{path|.kcfg}} file is described by its DTD (kcfg.xsd - available from
[http://www.kde.org/standards/kcfg/1.0/kcfg.xsd here] (please note that browsers do not display DTDs in a visual form,
download the DTD directly and view it like a text file) or the kdecore
library). Please go through it before you go any further.

Lets create a simple .kcfg file. Please reference the code below as we go through each step.

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kcfg SYSTEM
"http://www.kde.org/standards/kcfg/1.0/kcfg.xsd">
<kcfg>
<kcfgfile name="kjotsrc"/>
<include>kglobalsettings.h</include>
<group name="kjots">
<entry name="SplitterSizes" type="IntList">
<label>How the main window is divided.</label>
</entry>
<entry name="Width" type="Int">
<label>Width of the main window.</label>
<default>600</default>
</entry>
<entry name="Height" type="Int">
<label>Height of the main window.</label>
<default>400</default>
</entry>
<entry name="OpenBooks" type="StringList">
<label>All books that are opened.</label>
</entry>
<entry name="CurrentBook" type="String">
<label>The book currently opened.</label>
</entry>
<entry name="Font" type="Font">
<label>The font used to display the contents of books.</label>
<default code="true">KGlobalSettings::generalFont()</default>
</entry>
</group>
</kcfg>
</code>

* Use your favorite code editor to open a your_application_name{{path|.kcfg}} file (of course replacing your_application_name with the name of the application you want to convert to KConfig XT).
* Start that file by opening the <kcfgfile> tag which controls which KConfig file the data will be stored in. There are three possibilities:
*# If the <kcfgfile> tag has no attributes the generated code will use the application's default KConfig file (normally {{path|$HOME/.kde/config/<appname>rc}}).
*# ''The "name" attribute is used to manually specify a file name. If the value assigned to "name" is not an absolute file path, the file will be created in the default KDE config directory (normally {{path|$HOME/.kde/config}}).''
*# ''If you would like to be able to specify the config file at construction time, use <kcfgfile arg="true">. This causes the constructor of the generated class to take a KSharedConfig::Ptr as an argument, allowing you to construct multiple instances pointing to different files.''
* ''Add the optional <include> tags which may contain C++ header files that are needed to compile the code required to compute the default values.''
* The remaining entries in the XML file are grouped by the tag <group> which describes the corresponding groups in the configuration file.
*#The individual entries must have at least a name or a key. The key is used as the key in the config file. The name is used to create accessor and modifier functions. If <key> is not given, the name is used as the config file key. If <key> is given, but not <name>, the name is constructed by removing all spaces from the <key> contents.
*# Always add a label or a whatsthis tags to your application in which you describe the configuration options. The label tag is used for short descriptions of the entry, while whatsthis contains more verbose documentation. ''It's important for tools like KConfigEditor which can be used by systems administrators to setup machines over on the network.''
*# An entry must also have a type. The allowed types are: String, StringList, Font, Rect, Size, Color, Point, Int, UInt, Bool, Double, DateTime, Int64, UInt64 and Password. '' Besides those basic type the following special types are supported and include:''
*#* Path - This is a string that is specially treated as a file-path. In particular paths in the home directory are prefixed with $HOME when being stored in the configuration file.
*#* Enum - This indicates an enumeration. The possible enum values should be provided via the <choices> tag. Enum values are accessed as integers by the application but stored as string in the configuration file. This makes it possible to add more values at a later date without breaking compatibility.
*#* IntList - This indicates a list of integers. This information is provided to the application as QValueList<int>. Useful for storing QSplitter geometries.
*#* PathList - List of Path elements.
*# The min and max tags can be set to limit the value of the integer-type options.
*#''An entry can optionally have a default value which is used as default when the value isn't specified in any config file. Default values are interpreted as literal constant values. If a default value needs to be computed or if it needs to be obtained from a function call, the <default> tag should contain the code="true" attribute. The contents of the <default> tag is then considered to be a C++ expression. ''
*#''Additional code for computing default values can be provided via the <code> tag. The contents of the <code> tag is inserted as-is. A typical use for this is to compute a common default value which can then be referenced by multiple entries that follow.''
*#''Optionally, the hidden option can also be added to the <entry>. The possible values are true and false.''

== .kcfgc files ==

After creating a {{path|.kcfg}} file create a {{path|.kcfgc}} file which describes the C++ file
generation options. The .kcfgc file is a simple ini file with the typical
"entry=value" format. To create a simple .kcfgc file follow these steps:

# Open a new file in your favorite text editor.
# Start it with the "File=your_application_name.kcfg" entry which specifies where the configuration options for your application are stored.
# Add the "ClassName=YourConfigClassName" entry which specifies the name of the class that will be generated from the .kcfg file. Remember that the generated class will be derived from KConfigSkeleton. PLease make sure that YourConfigClassName is not a class name already used in your application. Save this file under {{path|yourconfigclassname.kcfgc.}} This will ensure the generation of the yourconfigclassname.{h,cpp} files where your configuration class will reside.
# Add any additional entries, which your application might need. Those additional entries include:
#* NameSpace - specifies the namespace in which the generated config class should reside,
#* Inherits - if you need the generated class to inherit your custom class,
#* Singleton - if the configuration class should be a singleton,
#* MemberVariables - specifies the access to the member variables, default is private,
#* ItemAccessors - relates to the above item, if member variables are public then it might make little sense to generate accessors. By default they are generated,
#* Mutators - similar to the above one, but applies to the mutator methods,
#* GlobalEnums - specifies whether enums should be class wide of whether they should be always explicitly prefixed with their type name,
#* UseEnumTypes - specifies whether enum values should be passed as type int or as their enum type in the return value of accessor functions and the arguments of mutator and signal functions.

== Adjusting the CMakeLists.txt file ==

After creating the .kcfg and .kcfgc files the next step is to adjust the
build to let kconfig_compiler generate the required class at compile time. Fortunately doing this is trivial and requires only one step, adding this line to the CMakeLists.txt file example:

kde4_add_kcfg_files(<project name>_SRCS settings.kcfgc)

Alternatively, if a .moc file needs to be generated before compiling the generated source code, use

kde4_add_kcfg_files(<project name>_SRCS GENERATE_MOC settings.kcfgc)

This assures that the configuration class is properly generated and that the .kcfg is installed so it can be used by tools like
the KConfigEditor.

== Use and Dialogs ==

After making all of the above changes you're ready to use KConfig XT. The
kconfig_compiler generated header file will have the name equal to the name of the .kcfg file but with a ".h" extension. Simply include that file wherever you want to access your configuration options.

The use will depend on whether you have added the <tt>Singleton=true</tt> entry to your .kcfgc file.

One the nicest features of the KConfig XT is its seamless integration with the Qt
Designer generated dialogs. You can do that by using {{class|KConfigDialog}}. The
steps to do that are as follows:

# Create the KConfigDialog and pass the instance of your configuration data as one of the arguments. The construct would look like the following example:

<code cppqt>
KConfigDialog* dialog = new KConfigDialog(
this, "settings", YourAppSettings::self() );
</code>

assuming that YourAppSettings is the value of the ClassName variable from the kcfgc file and the settings class is a singelton.
# In Qt Designer create widgets which should be used to configure your options. In order to make those widgets interact with the kcfg you have name each one of them using the following scheme:
## Prefix the Name of the widget which should control one of the options with "kcfg_"
## Append the "name" attribute value from your kcfg file which corresponds to option the given widget should control.
# Add the Qt Designer generated widget to the KConfigDialog.
# Show the dialog when you're done.

== Example ==

Here's an example usage of KConfig XT for the application named Example.
With the following example.kcfg file:

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kcfg SYSTEM
"http://www.kde.org/standards/kcfg/1.0/kcfg.dtd">
<kcfg> <kcfgfile name="examplerc"/>
<group name="network">
<entry name="ServerName" type="String">
<label>Defines the sample server.</label>
</entry>
<entry name="Port" type="Int">
<label>Defines the server port</label>
<default>21</default>
<min>20</min>
<max>990</max>
</entry>
</group>
</kcfg>
</code>

And here's how to actually use the generated class. for the given kcfgc file.

<code ini>
File=example.kcfg
ClassName=ExampleSettings
Singleton=true
Mutators=true
</code>

The header files wouldn't change, but the cpp files must now contain the
following code to access and store the configuration data :

<code cppqt>
...
#include <ExampleSettings.h>
...
void ExampleClass::readConfig() {
m_server = ExampleSettings::serverName();
m_port = ExampleSettings::port();
}
void ExampleClass:saveSettings() {
ExampleSettings::setServerName( m_server );
ExampleSettings::setPort( m_port );
ExampleSettings::writeConfig();
}
</code>

To add a dialog you need to create a Qt Designer widget with the widget names
corresponding to the names of the options they should edit and prefixed with "kcfg_".
It could be something along the lines of:

[[Image:kconfigxt.png|center|256px]]

And you can use the dialog with the following code:

<code cppqt>
//An instance of your dialog could be already created and could be
// cached, in which case you want to display the cached dialog
// instead of creating another one
if ( KConfigDialog::showDialog( "settings" ) )
return;

// KConfigDialog didn't find an instance of this dialog, so lets
// create it :
KConfigDialog* dialog = new KConfigDialog(this, "settings",
ExampleSettings::self());
ExampleDesignerWidget* confWdg =
new ExampleDesignerWidget( 0, "Example" );

dialog->addPage( confWdg, i18n("Example"), "example" );

//User edited the configuration - update your local copies of the
//configuration data
connect( dialog, SIGNAL(settingsChanged()),
this, SLOT(updateConfiguration()) );

dialog->show();
</code>

And that's all it takes. You can have a look at [http://websvn.kde.org/trunk/KDE/kdegames/kreversi KReversi] and [http://websvn.kde.org/trunk/KDE/kdegames/ktron/ KTron] code in the [http://websvn.kde.org/trunk/KDE/kdegames kdegames module] to see a live example of KConfig XT!

== Common Pitfalls and Tips ==

* Do not forget to add the "type" attribute to the "entry" tag in your .kcfg file.
* Always try to add both the <label> and <whatsthis> tags to each entry.
* Putting the MemberVariables=public in your .kcfgc is usually a bad idea - you'll avoid accidental changes to those members by using the aggregation and forcing the use of the mutators.
* If your application doesn't have one central object (created before and destructed after; all others) then always put the Singleton=true entry in your .kcfgs file.
[[Category:C++]]

Development/Tutorials/Using KConfig XT

2007-12-31T18:17:30Z

Rememberme:

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Using_KConfig_XT}}
{{TutorialBrowser|

series=KConfig|

pre=[[../KConfig|Introduction to KConfig]]|

next=none|

name=Using KConfig XT|

reading=[http://api.kde.org/4.0-api/kdelibs-apidocs/kdecore/html/kconfig_compiler.html The KDE Configuration Compiler (KDE 4)]<br>[http://api.kde.org/3.5-api/kdelibs-apidocs/kdecore/html/kconfig_compiler.html The KDE Configuration Compiler (KDE 3)]

}}

== Using KConfig XT ==
''Original Author'': Zack Rusin <[mailto:zack@kde.org zack@kde.org]>

This tutorial introduces the main concepts of the KconfigXT
configuration framework and shows how to efficiently use it in applications. It assumes that the reader has already developed a KDE application and is familiar with KConfig. A basic understanding of XML and concepts behind DTDs is also required.

The main idea behind KConfig XT is to make the life of application developers
easier while making the administration of large KDE installations more manageable.
The four basic parts of the new framework are:

* KConfigSkeleton - a class in the libkdecore library which grants a more flexible access to the configuration options,
* XML file containing information about configuration options (the {{path|.kcfg}} file)
* An ini like file which provides the code generation options (the {{path|.kcfgc}} file)
* kconfig_compiler - which generates C++ source code from {{path|.kcfg}} and {{path|.kcfgc}} files. The generated class is based on KConfigSkeleton and provides an API for the application to access its configuration data.

{{note|In this tutorial more advanced and optional features of KConfig XT and their descriptions are marked by ''italic text''. If you decide to skip them during the first reading, be sure to come back to them at some point. }}

== .kcfg DTD Structure ==

The structure of the {{path|.kcfg}} file is described by its DTD (kcfg.xsd - available from
[http://www.kde.org/standards/kcfg/1.0/kcfg.xsd here] (please note that browsers do not display DTDs in a visual form,
download the DTD directly and view it like a text file) or the kdecore
library). Please go through it before you go any further.

Lets create a simple .kcfg file. Please reference the code below as we go through each step.

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kcfg SYSTEM
"http://www.kde.org/standards/kcfg/1.0/kcfg.xsd">
<kcfg>
<kcfgfile name="kjotsrc"/>
<include>kglobalsettings.h</include>
<group name="kjots">
<entry name="SplitterSizes" type="IntList">
<label>How the main window is divided.</label>
</entry>
<entry name="Width" type="Int">
<label>Width of the main window.</label>
<default>600</default>
</entry>
<entry name="Height" type="Int">
<label>Height of the main window.</label>
<default>400</default>
</entry>
<entry name="OpenBooks" type="StringList">
<label>All books that are opened.</label>
</entry>
<entry name="CurrentBook" type="String">
<label>The book currently opened.</label>
</entry>
<entry name="Font" type="Font">
<label>The font used to display the contents of books.</label>
<default code="true">KGlobalSettings::generalFont()</default>
</entry>
</group>
</kcfg>
</code>

* Use your favorite code editor to open a your_application_name{{path|.kcfg}} file (of course replacing your_application_name with the name of the application you want to convert to KConfig XT).
* Start that file by opening the <kcfgfile> tag which controls which KConfig file the data will be stored in. There are three possibilities:
*# If the <kcfgfile> tag has no attributes the generated code will use the application's default KConfig file (normally {{path|$HOME/.kde/config/<appname>rc}}).
*# ''The "name" attribute is used to manually specify a file name. If the value assigned to "name" is not an absolute file path, the file will be created in the default KDE config directory (normally {{path|$HOME/.kde/config}}).''
*# ''If you would like to be able to specify the config file at construction time, use <kcfgfile arg="true">. This causes the constructor of the generated class to take a KSharedConfig::Ptr as an argument, allowing you to construct multiple instances pointing to different files.''
* ''Add the optional <include> tags which may contain C++ header files that are needed to compile the code required to compute the default values.''
* The remaining entries in the XML file are grouped by the tag <group> which describes the corresponding groups in the configuration file.
*#The individual entries must have at least a name or a key. The key is used as the key in the config file. The name is used to create accessor and modifier functions. If <key> is not given, the name is used as the config file key. If <key> is given, but not <name>, the name is constructed by removing all spaces from the <key> contents.
*# Always add a label or a whatsthis tags to your application in which you describe the configuration options. The label tag is used for short descriptions of the entry, while whatsthis contains more verbose documentation. ''It's important for tools like KConfigEditor which can be used by systems administrators to setup machines over on the network.''
*# An entry must also have a type. The allowed types are: String, StringList, Font, Rect, Size, Color, Point, Int, UInt, Bool, Double, DateTime, Int64, UInt64 and Password. '' Besides those basic type the following special types are supported and include:''
*#* Path - This is a string that is specially treated as a file-path. In particular paths in the home directory are prefixed with $HOME when being stored in the configuration file.
*#* Enum - This indicates an enumeration. The possible enum values should be provided via the <choices> tag. Enum values are accessed as integers by the application but stored as string in the configuration file. This makes it possible to add more values at a later date without breaking compatibility.
*#* IntList - This indicates a list of integers. This information is provided to the application as QValueList<int>. Useful for storing QSplitter geometries.
*#* PathList - List of Path elements.
*# The min and max tags can be set to limit the value of the integer-type options.
*#''An entry can optionally have a default value which is used as default when the value isn't specified in any config file. Default values are interpreted as literal constant values. If a default value needs to be computed or if it needs to be obtained from a function call, the <default> tag should contain the code="true" attribute. The contents of the <default> tag is then considered to be a C++ expression. ''
*#''Additional code for computing default values can be provided via the <code> tag. The contents of the <code> tag is inserted as-is. A typical use for this is to compute a common default value which can then be referenced by multiple entries that follow.''
*#''Optionally, the hidden option can also be added to the <entry>. The possible values are true and false.''

== .kcfgc files ==

After creating a {{path|.kcfg}} file create a {{path|.kcfgc}} file which describes the C++ file
generation options. The .kcfgc file is a simple ini file with the typical
"entry=value" format. To create a simple .kcfgc file follow these steps:

# Open a new file in your favorite text editor.
# Start it with the "File=your_application_name.kcfg" entry which specifies where the configuration options for your application are stored.
# Add the "ClassName=YourConfigClassName" entry which specifies the name of the class that will be generated from the .kcfg file. Remember that the generated class will be derived from KConfigSkeleton. PLease make sure that YourConfigClassName is not a class name already used in your application. Save this file under {{path|yourconfigclassname.kcfgc.}} This will ensure the generation of the yourconfigclassname.{h,cpp} files where your configuration class will reside.
# Add any additional entries, which your application might need. Those additional entries include:
#* NameSpace - specifies the namespace in which the generated config class should reside,
#* Inherits - if you need the generated class to inherit your custom class,
#* Singleton - if the configuration class should be a singleton,
#* MemberVariables - specifies the access to the member variables, default is private,
#* ItemAccessors - relates to the above item, if member variables are public then it might make little sense to generate accessors. By default they are generated,
#* Mutators - similar to the above one, but applies to the mutator methods,
#* GlobalEnums - specifies whether enums should be class wide of whether they should be always explicitly prefixed with their type name,
#* UseEnumTypes - specifies whether enum values should be passed as type int or as their enum type in the return value of accessor functions and the arguments of mutator and signal functions.

== Adjusting the CMakeLists.txt file ==

After creating the .kcfg and .kcfgc files the next step is to adjust the
build to let kconfig_compiler generate the required class at compile time. Fortunately doing this is trivial and requires only one step, adding this line to the CMakeLists.txt file example:

kde4_add_kcfg_files(<project name>_SRCS settings.kcfgc)

Alternatively, if a .moc file needs to be generated before compiling the generated source code, use

kde4_add_kcfg_files(<project name>_SRCS GENERATE_MOC settings.kcfgc)

This assures that the configuration class is properly generated and that the .kcfg is installed so it can be used by tools like
the KConfigEditor.

== Use and Dialogs ==

After making all of the above changes you're ready to use KConfig XT. The
kconfig_compiler generated header file will have the name equal to the name of the .kcfg file but with a ".h" extension. Simply include that file wherever you want to access your configuration options.

The use will depend on whether you have added the <tt>Singleton=true</tt> entry to your .kcfgc file.

One the nicest features of the KConfig XT is its seamless integration with the Qt
Designer generated dialogs. You can do that by using {{class|KConfigDialog}}. The
steps to do that are as follows:

# Create the KConfigDialog and pass the instance of your configuration data as one of the arguments. The construct would look like the following example:

<code cppqt>
KConfigDialog* dialog = new KConfigDialog(
this, "settings", YourAppSettings::self() );
</code>

assuming that YourAppSettings is the value of the ClassName variable from the kcfgc file and the settings class is a singelton.
# In Qt Designer create widgets which should be used to configure your options. In order to make those widgets interact with the kcfg you have name each one of them using the following scheme:
## Prefix the Name of the widget which should control one of the options with "kcfg_"
## Append the "name" attribute value from your kcfg file which corresponds to option the given widget should control.
# Add the Qt Designer generated widget to the KConfigDialog.
# Show the dialog when you're done.

== Example ==

Here's an example usage of KConfig XT for the application named Example.
With the following example.kcfg file:

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kcfg SYSTEM
"http://www.kde.org/standards/kcfg/1.0/kcfg.dtd">
<kcfg> <kcfgfile name="examplerc"/>
<group name="network">
<entry name="ServerName" type="String">
<label>Defines the sample server.</label>
</entry>
<entry name="Port" type="Int">
<label>Defines the server port</label>
<default>21</default>
<min>20</min>
<max>990</max>
</entry>
</group>
</kcfg>
</code>

And here's how to actually use the generated class. for the given kcfgc file.

<code ini>
File=example.kcfg
ClassName=ExampleSettings
Singleton=true
Mutators=true
</code>

The header files wouldn't change, but the cpp files must now contain the
following code to access and store the configuration data :

<code cppqt>
...
#include <ExampleSettings.h>
...
void ExampleClass::readConfig() {
m_server = ExampleSettings::serverName();
m_port = ExampleSettings::port();
}
void ExampleClass:saveSettings() {
ExampleSettings::setServerName( m_server );
ExampleSettings::setPort( m_port );
ExampleSettings::writeConfig();
}
</code>

To add a dialog you need to create a Qt Designer widget with the widget names
corresponding to the names of the options they should edit and prefixed with "kcfg_".
It could be something along the lines of:

[[Image:kconfigxt.png|center|256px]]

And you can use the dialog with the following code:

<code cppqt>
//An instance of your dialog could be already created and could be
// cached, in which case you want to display the cached dialog
// instead of creating another one
if ( KConfigDialog::showDialog( "settings" ) )
return;

// KConfigDialog didn't find an instance of this dialog, so lets
// create it :
KConfigDialog* dialog = new KConfigDialog(this, "settings",
ExampleSettings::self());
ExampleDesignerWidget* confWdg =
new ExampleDesignerWidget( 0, "Example" );

dialog->addPage( confWdg, i18n("Example"), "example" );

//User edited the configuration - update your local copies of the
//configuration data
connect( dialog, SIGNAL(settingsChanged()),
this, SLOT(updateConfiguration()) );

dialog->show();
</code>

And that's all it takes. You can have a look at [http://websvn.kde.org/trunk/KDE/kdegames/kreversi KReversi] and [http://websvn.kde.org/trunk/KDE/kdegames/ktron/ KTron] code in the [http://websvn.kde.org/trunk/KDE/kdegames kdegames module] to see a live example of KConfig XT!

== Common Pitfalls and Tips ==

* Do not forget to add the "type" attribute to the "entry" tag in your .kcfg file.
* Always try to add both the <label> and <whatsthis> tags to each entry.
* Putting the MemberVariables=public in your .kcfgc is usually a bad idea - you'll avoid accidental changes to those members by using the aggregation and forcing the use of the mutators.
* If your application doesn't have one central object (created before and destructed after; all others) then always put the Singleton=true entry in your .kcfgs file.
[[Category:C++]]

Development/Tutorials/Updating KConfig Files

2007-12-31T18:16:59Z

Rememberme:

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Updating_KConfig_Files}}
{{TutorialBrowser|

series=KConfig|

pre=[[../KConfig| Introduction to KConfig]]|

name=Updating KConfig files|

}}

=KConfig Update=

This page describes how a developer can use the KConfig update mechanism (kconf_update) available in kdelibs to update a user's already existing config file to accomodate changes made to the format of the default config file.

==Why should you use it?==

Over time applications sometimes need to rearrange the way configuration options are stored. Since such an update shouldn't influence the configuration options that the user has selected, the application must take care that the options stored in the old way will still be honored.

What used to happen is that the application looks up both the old and the
new configuration option and then decides which one to use. This method has several drawbacks:
* The application may need to read more configuration files than strictly needed, resulting in a slower startup.
* The application becomes bigger with code that will only be used once.

kconf_update addresses these problems by offering a framework to update configuration files without adding code to the application itself.

==How it works==

Applications can install so called "update files" under
{{Path|$KDEDIR/share/apps/kconf_update.}} An update file has {{Path|.upd}} as an extension and contains instructions for transferring/converting configuration information from one place to another.

Updating the configuration happens automatically, either when KDE gets started
or when kded detects a new update file in the above mentioned location.

Update files are separated into sections. Each section has an id. When a
section describing a configuration change has been applied, the id will be
stored in the file {{Path|kconf_updaterc}}. This information is used to make sure that a configuration update is only performed once.

If you overwrite an existing update file with a new version that contains a
new section, only the update instructions from this extra section will be
performed.

==File format of the update file==

Empty lines or lines that start with '#' are considered comments
Commas (,) are used to seperate fields and may not occur as part
of any field and all of the keywords are case-sensitive, i.e. you
cannot say "key" instead of "Key" for example.

For the rest the file is parsed and executed sequentially from top to bottom.
Each line can contain one entry. The following entries are recognized:

<code>Id=<id></code>

With <id> identifying the group of update entries that follows. Once a group
of entries have been applied, their <id> is stored and this group of entries
will not be applied again.

<code>
File=<oldfile>,<newfile>
File=<oldfile>
</code>

Specifies that configuration information is read from <oldfile> and written
to <newfile>. If you only specify <oldfile>, the information is read from
and as written to <oldfile>. Note that if the file does not exist
at the time kconf_update first checks, no related update will be performed.

<code>
Script=<script>[,<interpreter>]
</code>

<script> is the program that will be performing the updates. All entries from <oldfile> are piped into <script>. The output of <script>is used as new entries for <newfile>. Existing entries can be deleted by adding lines with "# DELETE [group]key" in the output of the script. To delete a whole group use "# DELETEGROUP [group]".

There are two types of kconf_update scripts:
*Non-Compiled
*Compiled

If <script> is written in a non-compiled language (such as ruby or perl), then it should be installed into
{{Path|${KCONF_UPDATE_INSTALL_DIR} }}.

If <script> is a compiled application, it should be installed in {{Path|${BIN_INSTALL_DIR}/kconf_update_bin}}

If the script command is issued after a "Group" command the behavior is slightly
different:

All entries from <oldfile> in <oldgroup> are piped into <script>. The output
of script is used as new entries for <newfile> in <newgroup>, unless a different
group is specified with "[group]". Existing entries can be deleted from
<oldgroup> by adding lines with "# DELETE key" in the output of the script.·
To delete <oldgroup> use "# DELETEGROUP".

<interpreter> can be something like "perl" or "ruby".

It is also possible to have a script command without specifying <oldfile> or <newfile>. In that case the script is run but it will not be fed any input and its output will simply be discarded.

<code>
ScriptArguments=<arguments>
</code>

If specified, the arguments will be passed to <script>.
IMPORTANT: It has to be specified before Script=.

<code>
Group=<oldgroup>,<newgroup>
Group=<oldgroup>
</code>

Specifies that configuration information is read from the group <oldgroup>
and written to <newgroup>. If you only specify <oldgroup>, the information
is read from as well as written to <oldgroup>. You can use <default> to
specify keys that are not under any group.

<code>
RemoveGroup=<oldgroup>
</code>

Specifies that <oldgroup> is removed entirely. This can be used
to remove obsolete entries or to force a revert to default values.

<code>
Options=<option1>, <option2>,
</code>

With this entry you can specify options that apply to the next "Script",
"Key" or "AllKeys" entry (only to the first!). Possible options are:

*"copy" Copy the configuration item instead of moving it. This means that
the configuration item will not be deleted from <oldfile>/<oldgroup>

*"overwrite" Normally, a configuration item is not moved if an item with the
new name already exists. When this option is specified the old configuration item will overwrite any existing item.

Key=<oldkey>,<newkey>
Key=<oldkey>

Specifies that configuration information is read from the key <oldkey>
and written to <newkey>. If you only specify <oldkey>, the information
is read from as well as written to <oldkey>.

<code>
AllKeys
</code>

Specifies that all configuration information in the selected group should
be moved (All keys).

<code>
AllGroups
</code>

Specifies that all configuration information from all keys in ALL·
groups should be moved.

<code>
RemoveKey=<oldkey>
</code>

Specifies that <oldkey> is removed from the selected group. This can be used
to remove obsolete entries or to force a revert to default values.

Development/Tutorials/Updating KConfig Files

2007-12-31T18:15:31Z

Rememberme: Undo revision 19014 by Rememberme (Talk)

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Updating_KConfig_Files}}
{{TutorialBrowser|

series=KConfig|

pre=[[../Using_KConfig_XT| Using KConfig XT]]|

name=Updating KConfig files|

}}

=KConfig Update=

This page describes how a developer can use the KConfig update mechanism (kconf_update) available in kdelibs to update a user's already existing config file to accomodate changes made to the format of the default config file.

==Why should you use it?==

Over time applications sometimes need to rearrange the way configuration options are stored. Since such an update shouldn't influence the configuration options that the user has selected, the application must take care that the options stored in the old way will still be honored.

What used to happen is that the application looks up both the old and the
new configuration option and then decides which one to use. This method has several drawbacks:
* The application may need to read more configuration files than strictly needed, resulting in a slower startup.
* The application becomes bigger with code that will only be used once.

kconf_update addresses these problems by offering a framework to update configuration files without adding code to the application itself.

==How it works==

Applications can install so called "update files" under
{{Path|$KDEDIR/share/apps/kconf_update.}} An update file has {{Path|.upd}} as an extension and contains instructions for transferring/converting configuration information from one place to another.

Updating the configuration happens automatically, either when KDE gets started
or when kded detects a new update file in the above mentioned location.

Update files are separated into sections. Each section has an id. When a
section describing a configuration change has been applied, the id will be
stored in the file {{Path|kconf_updaterc}}. This information is used to make sure that a configuration update is only performed once.

If you overwrite an existing update file with a new version that contains a
new section, only the update instructions from this extra section will be
performed.

==File format of the update file==

Empty lines or lines that start with '#' are considered comments
Commas (,) are used to seperate fields and may not occur as part
of any field and all of the keywords are case-sensitive, i.e. you
cannot say "key" instead of "Key" for example.

For the rest the file is parsed and executed sequentially from top to bottom.
Each line can contain one entry. The following entries are recognized:

<code>Id=<id></code>

With <id> identifying the group of update entries that follows. Once a group
of entries have been applied, their <id> is stored and this group of entries
will not be applied again.

<code>
File=<oldfile>,<newfile>
File=<oldfile>
</code>

Specifies that configuration information is read from <oldfile> and written
to <newfile>. If you only specify <oldfile>, the information is read from
and as written to <oldfile>. Note that if the file does not exist
at the time kconf_update first checks, no related update will be performed.

<code>
Script=<script>[,<interpreter>]
</code>

<script> is the program that will be performing the updates. All entries from <oldfile> are piped into <script>. The output of <script>is used as new entries for <newfile>. Existing entries can be deleted by adding lines with "# DELETE [group]key" in the output of the script. To delete a whole group use "# DELETEGROUP [group]".

There are two types of kconf_update scripts:
*Non-Compiled
*Compiled

If <script> is written in a non-compiled language (such as ruby or perl), then it should be installed into
{{Path|${KCONF_UPDATE_INSTALL_DIR} }}.

If <script> is a compiled application, it should be installed in {{Path|${BIN_INSTALL_DIR}/kconf_update_bin}}

If the script command is issued after a "Group" command the behavior is slightly
different:

All entries from <oldfile> in <oldgroup> are piped into <script>. The output
of script is used as new entries for <newfile> in <newgroup>, unless a different
group is specified with "[group]". Existing entries can be deleted from
<oldgroup> by adding lines with "# DELETE key" in the output of the script.·
To delete <oldgroup> use "# DELETEGROUP".

<interpreter> can be something like "perl" or "ruby".

It is also possible to have a script command without specifying <oldfile> or <newfile>. In that case the script is run but it will not be fed any input and its output will simply be discarded.

<code>
ScriptArguments=<arguments>
</code>

If specified, the arguments will be passed to <script>.
IMPORTANT: It has to be specified before Script=.

<code>
Group=<oldgroup>,<newgroup>
Group=<oldgroup>
</code>

Specifies that configuration information is read from the group <oldgroup>
and written to <newgroup>. If you only specify <oldgroup>, the information
is read from as well as written to <oldgroup>. You can use <default> to
specify keys that are not under any group.

<code>
RemoveGroup=<oldgroup>
</code>

Specifies that <oldgroup> is removed entirely. This can be used
to remove obsolete entries or to force a revert to default values.

<code>
Options=<option1>, <option2>,
</code>

With this entry you can specify options that apply to the next "Script",
"Key" or "AllKeys" entry (only to the first!). Possible options are:

*"copy" Copy the configuration item instead of moving it. This means that
the configuration item will not be deleted from <oldfile>/<oldgroup>

*"overwrite" Normally, a configuration item is not moved if an item with the
new name already exists. When this option is specified the old configuration item will overwrite any existing item.

Key=<oldkey>,<newkey>
Key=<oldkey>

Specifies that configuration information is read from the key <oldkey>
and written to <newkey>. If you only specify <oldkey>, the information
is read from as well as written to <oldkey>.

<code>
AllKeys
</code>

Specifies that all configuration information in the selected group should
be moved (All keys).

<code>
AllGroups
</code>

Specifies that all configuration information from all keys in ALL·
groups should be moved.

<code>
RemoveKey=<oldkey>
</code>

Specifies that <oldkey> is removed from the selected group. This can be used
to remove obsolete entries or to force a revert to default values.

Development/Tutorials/Updating KConfig Files

2007-12-31T18:15:16Z

Rememberme: Undo revision 19015 by Rememberme (Talk)

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Updating_KConfig_Files}}
{{TutorialBrowser|

series=KConfig|

pre=[[../Using_KConfig_XT| Using KConfig XT]]|

next=none

name=Updating KConfig files|

}}

=KConfig Update=

This page describes how a developer can use the KConfig update mechanism (kconf_update) available in kdelibs to update a user's already existing config file to accomodate changes made to the format of the default config file.

==Why should you use it?==

Over time applications sometimes need to rearrange the way configuration options are stored. Since such an update shouldn't influence the configuration options that the user has selected, the application must take care that the options stored in the old way will still be honored.

What used to happen is that the application looks up both the old and the
new configuration option and then decides which one to use. This method has several drawbacks:
* The application may need to read more configuration files than strictly needed, resulting in a slower startup.
* The application becomes bigger with code that will only be used once.

kconf_update addresses these problems by offering a framework to update configuration files without adding code to the application itself.

==How it works==

Applications can install so called "update files" under
{{Path|$KDEDIR/share/apps/kconf_update.}} An update file has {{Path|.upd}} as an extension and contains instructions for transferring/converting configuration information from one place to another.

Updating the configuration happens automatically, either when KDE gets started
or when kded detects a new update file in the above mentioned location.

Update files are separated into sections. Each section has an id. When a
section describing a configuration change has been applied, the id will be
stored in the file {{Path|kconf_updaterc}}. This information is used to make sure that a configuration update is only performed once.

If you overwrite an existing update file with a new version that contains a
new section, only the update instructions from this extra section will be
performed.

==File format of the update file==

Empty lines or lines that start with '#' are considered comments
Commas (,) are used to seperate fields and may not occur as part
of any field and all of the keywords are case-sensitive, i.e. you
cannot say "key" instead of "Key" for example.

For the rest the file is parsed and executed sequentially from top to bottom.
Each line can contain one entry. The following entries are recognized:

<code>Id=<id></code>

With <id> identifying the group of update entries that follows. Once a group
of entries have been applied, their <id> is stored and this group of entries
will not be applied again.

<code>
File=<oldfile>,<newfile>
File=<oldfile>
</code>

Specifies that configuration information is read from <oldfile> and written
to <newfile>. If you only specify <oldfile>, the information is read from
and as written to <oldfile>. Note that if the file does not exist
at the time kconf_update first checks, no related update will be performed.

<code>
Script=<script>[,<interpreter>]
</code>

<script> is the program that will be performing the updates. All entries from <oldfile> are piped into <script>. The output of <script>is used as new entries for <newfile>. Existing entries can be deleted by adding lines with "# DELETE [group]key" in the output of the script. To delete a whole group use "# DELETEGROUP [group]".

There are two types of kconf_update scripts:
*Non-Compiled
*Compiled

If <script> is written in a non-compiled language (such as ruby or perl), then it should be installed into
{{Path|${KCONF_UPDATE_INSTALL_DIR} }}.

If <script> is a compiled application, it should be installed in {{Path|${BIN_INSTALL_DIR}/kconf_update_bin}}

If the script command is issued after a "Group" command the behavior is slightly
different:

All entries from <oldfile> in <oldgroup> are piped into <script>. The output
of script is used as new entries for <newfile> in <newgroup>, unless a different
group is specified with "[group]". Existing entries can be deleted from
<oldgroup> by adding lines with "# DELETE key" in the output of the script.·
To delete <oldgroup> use "# DELETEGROUP".

<interpreter> can be something like "perl" or "ruby".

It is also possible to have a script command without specifying <oldfile> or <newfile>. In that case the script is run but it will not be fed any input and its output will simply be discarded.

<code>
ScriptArguments=<arguments>
</code>

If specified, the arguments will be passed to <script>.
IMPORTANT: It has to be specified before Script=.

<code>
Group=<oldgroup>,<newgroup>
Group=<oldgroup>
</code>

Specifies that configuration information is read from the group <oldgroup>
and written to <newgroup>. If you only specify <oldgroup>, the information
is read from as well as written to <oldgroup>. You can use <default> to
specify keys that are not under any group.

<code>
RemoveGroup=<oldgroup>
</code>

Specifies that <oldgroup> is removed entirely. This can be used
to remove obsolete entries or to force a revert to default values.

<code>
Options=<option1>, <option2>,
</code>

With this entry you can specify options that apply to the next "Script",
"Key" or "AllKeys" entry (only to the first!). Possible options are:

*"copy" Copy the configuration item instead of moving it. This means that
the configuration item will not be deleted from <oldfile>/<oldgroup>

*"overwrite" Normally, a configuration item is not moved if an item with the
new name already exists. When this option is specified the old configuration item will overwrite any existing item.

Key=<oldkey>,<newkey>
Key=<oldkey>

Specifies that configuration information is read from the key <oldkey>
and written to <newkey>. If you only specify <oldkey>, the information
is read from as well as written to <oldkey>.

<code>
AllKeys
</code>

Specifies that all configuration information in the selected group should
be moved (All keys).

<code>
AllGroups
</code>

Specifies that all configuration information from all keys in ALL·
groups should be moved.

<code>
RemoveKey=<oldkey>
</code>

Specifies that <oldkey> is removed from the selected group. This can be used
to remove obsolete entries or to force a revert to default values.

Development/Tutorials/Using KConfig XT

2007-12-31T18:13:54Z

Rememberme: Undo revision 19012 by Rememberme (Talk)

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Using_KConfig_XT}}
{{TutorialBrowser|

series=KConfig|

pre=[[../KConfig|Introduction to KConfig]]|

name=Using KConfig XT|

reading=[http://api.kde.org/4.0-api/kdelibs-apidocs/kdecore/html/kconfig_compiler.html The KDE Configuration Compiler (KDE 4)]<br>[http://api.kde.org/3.5-api/kdelibs-apidocs/kdecore/html/kconfig_compiler.html The KDE Configuration Compiler (KDE 3)]

}}

== Using KConfig XT ==
''Original Author'': Zack Rusin <[mailto:zack@kde.org zack@kde.org]>

This tutorial introduces the main concepts of the KconfigXT
configuration framework and shows how to efficiently use it in applications. It assumes that the reader has already developed a KDE application and is familiar with KConfig. A basic understanding of XML and concepts behind DTDs is also required.

The main idea behind KConfig XT is to make the life of application developers
easier while making the administration of large KDE installations more manageable.
The four basic parts of the new framework are:

* KConfigSkeleton - a class in the libkdecore library which grants a more flexible access to the configuration options,
* XML file containing information about configuration options (the {{path|.kcfg}} file)
* An ini like file which provides the code generation options (the {{path|.kcfgc}} file)
* kconfig_compiler - which generates C++ source code from {{path|.kcfg}} and {{path|.kcfgc}} files. The generated class is based on KConfigSkeleton and provides an API for the application to access its configuration data.

{{note|In this tutorial more advanced and optional features of KConfig XT and their descriptions are marked by ''italic text''. If you decide to skip them during the first reading, be sure to come back to them at some point. }}

== .kcfg DTD Structure ==

The structure of the {{path|.kcfg}} file is described by its DTD (kcfg.xsd - available from
[http://www.kde.org/standards/kcfg/1.0/kcfg.xsd here] (please note that browsers do not display DTDs in a visual form,
download the DTD directly and view it like a text file) or the kdecore
library). Please go through it before you go any further.

Lets create a simple .kcfg file. Please reference the code below as we go through each step.

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kcfg SYSTEM
"http://www.kde.org/standards/kcfg/1.0/kcfg.xsd">
<kcfg>
<kcfgfile name="kjotsrc"/>
<include>kglobalsettings.h</include>
<group name="kjots">
<entry name="SplitterSizes" type="IntList">
<label>How the main window is divided.</label>
</entry>
<entry name="Width" type="Int">
<label>Width of the main window.</label>
<default>600</default>
</entry>
<entry name="Height" type="Int">
<label>Height of the main window.</label>
<default>400</default>
</entry>
<entry name="OpenBooks" type="StringList">
<label>All books that are opened.</label>
</entry>
<entry name="CurrentBook" type="String">
<label>The book currently opened.</label>
</entry>
<entry name="Font" type="Font">
<label>The font used to display the contents of books.</label>
<default code="true">KGlobalSettings::generalFont()</default>
</entry>
</group>
</kcfg>
</code>

* Use your favorite code editor to open a your_application_name{{path|.kcfg}} file (of course replacing your_application_name with the name of the application you want to convert to KConfig XT).
* Start that file by opening the <kcfgfile> tag which controls which KConfig file the data will be stored in. There are three possibilities:
*# If the <kcfgfile> tag has no attributes the generated code will use the application's default KConfig file (normally {{path|$HOME/.kde/config/<appname>rc}}).
*# ''The "name" attribute is used to manually specify a file name. If the value assigned to "name" is not an absolute file path, the file will be created in the default KDE config directory (normally {{path|$HOME/.kde/config}}).''
*# ''If you would like to be able to specify the config file at construction time, use <kcfgfile arg="true">. This causes the constructor of the generated class to take a KSharedConfig::Ptr as an argument, allowing you to construct multiple instances pointing to different files.''
* ''Add the optional <include> tags which may contain C++ header files that are needed to compile the code required to compute the default values.''
* The remaining entries in the XML file are grouped by the tag <group> which describes the corresponding groups in the configuration file.
*#The individual entries must have at least a name or a key. The key is used as the key in the config file. The name is used to create accessor and modifier functions. If <key> is not given, the name is used as the config file key. If <key> is given, but not <name>, the name is constructed by removing all spaces from the <key> contents.
*# Always add a label or a whatsthis tags to your application in which you describe the configuration options. The label tag is used for short descriptions of the entry, while whatsthis contains more verbose documentation. ''It's important for tools like KConfigEditor which can be used by systems administrators to setup machines over on the network.''
*# An entry must also have a type. The allowed types are: String, StringList, Font, Rect, Size, Color, Point, Int, UInt, Bool, Double, DateTime, Int64, UInt64 and Password. '' Besides those basic type the following special types are supported and include:''
*#* Path - This is a string that is specially treated as a file-path. In particular paths in the home directory are prefixed with $HOME when being stored in the configuration file.
*#* Enum - This indicates an enumeration. The possible enum values should be provided via the <choices> tag. Enum values are accessed as integers by the application but stored as string in the configuration file. This makes it possible to add more values at a later date without breaking compatibility.
*#* IntList - This indicates a list of integers. This information is provided to the application as QValueList<int>. Useful for storing QSplitter geometries.
*#* PathList - List of Path elements.
*# The min and max tags can be set to limit the value of the integer-type options.
*#''An entry can optionally have a default value which is used as default when the value isn't specified in any config file. Default values are interpreted as literal constant values. If a default value needs to be computed or if it needs to be obtained from a function call, the <default> tag should contain the code="true" attribute. The contents of the <default> tag is then considered to be a C++ expression. ''
*#''Additional code for computing default values can be provided via the <code> tag. The contents of the <code> tag is inserted as-is. A typical use for this is to compute a common default value which can then be referenced by multiple entries that follow.''
*#''Optionally, the hidden option can also be added to the <entry>. The possible values are true and false.''

== .kcfgc files ==

After creating a {{path|.kcfg}} file create a {{path|.kcfgc}} file which describes the C++ file
generation options. The .kcfgc file is a simple ini file with the typical
"entry=value" format. To create a simple .kcfgc file follow these steps:

# Open a new file in your favorite text editor.
# Start it with the "File=your_application_name.kcfg" entry which specifies where the configuration options for your application are stored.
# Add the "ClassName=YourConfigClassName" entry which specifies the name of the class that will be generated from the .kcfg file. Remember that the generated class will be derived from KConfigSkeleton. PLease make sure that YourConfigClassName is not a class name already used in your application. Save this file under {{path|yourconfigclassname.kcfgc.}} This will ensure the generation of the yourconfigclassname.{h,cpp} files where your configuration class will reside.
# Add any additional entries, which your application might need. Those additional entries include:
#* NameSpace - specifies the namespace in which the generated config class should reside,
#* Inherits - if you need the generated class to inherit your custom class,
#* Singleton - if the configuration class should be a singleton,
#* MemberVariables - specifies the access to the member variables, default is private,
#* ItemAccessors - relates to the above item, if member variables are public then it might make little sense to generate accessors. By default they are generated,
#* Mutators - similar to the above one, but applies to the mutator methods,
#* GlobalEnums - specifies whether enums should be class wide of whether they should be always explicitly prefixed with their type name,
#* UseEnumTypes - specifies whether enum values should be passed as type int or as their enum type in the return value of accessor functions and the arguments of mutator and signal functions.

== Adjusting the CMakeLists.txt file ==

After creating the .kcfg and .kcfgc files the next step is to adjust the
build to let kconfig_compiler generate the required class at compile time. Fortunately doing this is trivial and requires only one step, adding this line to the CMakeLists.txt file example:

kde4_add_kcfg_files(<project name>_SRCS settings.kcfgc)

Alternatively, if a .moc file needs to be generated before compiling the generated source code, use

kde4_add_kcfg_files(<project name>_SRCS GENERATE_MOC settings.kcfgc)

This assures that the configuration class is properly generated and that the .kcfg is installed so it can be used by tools like
the KConfigEditor.

== Use and Dialogs ==

After making all of the above changes you're ready to use KConfig XT. The
kconfig_compiler generated header file will have the name equal to the name of the .kcfg file but with a ".h" extension. Simply include that file wherever you want to access your configuration options.

The use will depend on whether you have added the <tt>Singleton=true</tt> entry to your .kcfgc file.

One the nicest features of the KConfig XT is its seamless integration with the Qt
Designer generated dialogs. You can do that by using {{class|KConfigDialog}}. The
steps to do that are as follows:

# Create the KConfigDialog and pass the instance of your configuration data as one of the arguments. The construct would look like the following example:

<code cppqt>
KConfigDialog* dialog = new KConfigDialog(
this, "settings", YourAppSettings::self() );
</code>

assuming that YourAppSettings is the value of the ClassName variable from the kcfgc file and the settings class is a singelton.
# In Qt Designer create widgets which should be used to configure your options. In order to make those widgets interact with the kcfg you have name each one of them using the following scheme:
## Prefix the Name of the widget which should control one of the options with "kcfg_"
## Append the "name" attribute value from your kcfg file which corresponds to option the given widget should control.
# Add the Qt Designer generated widget to the KConfigDialog.
# Show the dialog when you're done.

== Example ==

Here's an example usage of KConfig XT for the application named Example.
With the following example.kcfg file:

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kcfg SYSTEM
"http://www.kde.org/standards/kcfg/1.0/kcfg.dtd">
<kcfg> <kcfgfile name="examplerc"/>
<group name="network">
<entry name="ServerName" type="String">
<label>Defines the sample server.</label>
</entry>
<entry name="Port" type="Int">
<label>Defines the server port</label>
<default>21</default>
<min>20</min>
<max>990</max>
</entry>
</group>
</kcfg>
</code>

And here's how to actually use the generated class. for the given kcfgc file.

<code ini>
File=example.kcfg
ClassName=ExampleSettings
Singleton=true
Mutators=true
</code>

The header files wouldn't change, but the cpp files must now contain the
following code to access and store the configuration data :

<code cppqt>
...
#include <ExampleSettings.h>
...
void ExampleClass::readConfig() {
m_server = ExampleSettings::serverName();
m_port = ExampleSettings::port();
}
void ExampleClass:saveSettings() {
ExampleSettings::setServerName( m_server );
ExampleSettings::setPort( m_port );
ExampleSettings::writeConfig();
}
</code>

To add a dialog you need to create a Qt Designer widget with the widget names
corresponding to the names of the options they should edit and prefixed with "kcfg_".
It could be something along the lines of:

[[Image:kconfigxt.png|center|256px]]

And you can use the dialog with the following code:

<code cppqt>
//An instance of your dialog could be already created and could be
// cached, in which case you want to display the cached dialog
// instead of creating another one
if ( KConfigDialog::showDialog( "settings" ) )
return;

// KConfigDialog didn't find an instance of this dialog, so lets
// create it :
KConfigDialog* dialog = new KConfigDialog(this, "settings",
ExampleSettings::self());
ExampleDesignerWidget* confWdg =
new ExampleDesignerWidget( 0, "Example" );

dialog->addPage( confWdg, i18n("Example"), "example" );

//User edited the configuration - update your local copies of the
//configuration data
connect( dialog, SIGNAL(settingsChanged()),
this, SLOT(updateConfiguration()) );

dialog->show();
</code>

And that's all it takes. You can have a look at [http://websvn.kde.org/trunk/KDE/kdegames/kreversi KReversi] and [http://websvn.kde.org/trunk/KDE/kdegames/ktron/ KTron] code in the [http://websvn.kde.org/trunk/KDE/kdegames kdegames module] to see a live example of KConfig XT!

== Common Pitfalls and Tips ==

* Do not forget to add the "type" attribute to the "entry" tag in your .kcfg file.
* Always try to add both the <label> and <whatsthis> tags to each entry.
* Putting the MemberVariables=public in your .kcfgc is usually a bad idea - you'll avoid accidental changes to those members by using the aggregation and forcing the use of the mutators.
* If your application doesn't have one central object (created before and destructed after; all others) then always put the Singleton=true entry in your .kcfgs file.
[[Category:C++]]

Development/Tutorials/Updating KConfig Files

2007-12-31T18:12:22Z

Rememberme:

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Updating_KConfig_Files}}
{{TutorialBrowser|

series=KConfig|

pre=[[../Using_KConfig_XT| Using KConfig XT]]|

next=none|

name=Updating KConfig files|

}}

=KConfig Update=

This page describes how a developer can use the KConfig update mechanism (kconf_update) available in kdelibs to update a user's already existing config file to accomodate changes made to the format of the default config file.

==Why should you use it?==

Over time applications sometimes need to rearrange the way configuration options are stored. Since such an update shouldn't influence the configuration options that the user has selected, the application must take care that the options stored in the old way will still be honored.

What used to happen is that the application looks up both the old and the
new configuration option and then decides which one to use. This method has several drawbacks:
* The application may need to read more configuration files than strictly needed, resulting in a slower startup.
* The application becomes bigger with code that will only be used once.

kconf_update addresses these problems by offering a framework to update configuration files without adding code to the application itself.

==How it works==

Applications can install so called "update files" under
{{Path|$KDEDIR/share/apps/kconf_update.}} An update file has {{Path|.upd}} as an extension and contains instructions for transferring/converting configuration information from one place to another.

Updating the configuration happens automatically, either when KDE gets started
or when kded detects a new update file in the above mentioned location.

Update files are separated into sections. Each section has an id. When a
section describing a configuration change has been applied, the id will be
stored in the file {{Path|kconf_updaterc}}. This information is used to make sure that a configuration update is only performed once.

If you overwrite an existing update file with a new version that contains a
new section, only the update instructions from this extra section will be
performed.

==File format of the update file==

Empty lines or lines that start with '#' are considered comments
Commas (,) are used to seperate fields and may not occur as part
of any field and all of the keywords are case-sensitive, i.e. you
cannot say "key" instead of "Key" for example.

For the rest the file is parsed and executed sequentially from top to bottom.
Each line can contain one entry. The following entries are recognized:

<code>Id=<id></code>

With <id> identifying the group of update entries that follows. Once a group
of entries have been applied, their <id> is stored and this group of entries
will not be applied again.

<code>
File=<oldfile>,<newfile>
File=<oldfile>
</code>

Specifies that configuration information is read from <oldfile> and written
to <newfile>. If you only specify <oldfile>, the information is read from
and as written to <oldfile>. Note that if the file does not exist
at the time kconf_update first checks, no related update will be performed.

<code>
Script=<script>[,<interpreter>]
</code>

<script> is the program that will be performing the updates. All entries from <oldfile> are piped into <script>. The output of <script>is used as new entries for <newfile>. Existing entries can be deleted by adding lines with "# DELETE [group]key" in the output of the script. To delete a whole group use "# DELETEGROUP [group]".

There are two types of kconf_update scripts:
*Non-Compiled
*Compiled

If <script> is written in a non-compiled language (such as ruby or perl), then it should be installed into
{{Path|${KCONF_UPDATE_INSTALL_DIR} }}.

If <script> is a compiled application, it should be installed in {{Path|${BIN_INSTALL_DIR}/kconf_update_bin}}

If the script command is issued after a "Group" command the behavior is slightly
different:

All entries from <oldfile> in <oldgroup> are piped into <script>. The output
of script is used as new entries for <newfile> in <newgroup>, unless a different
group is specified with "[group]". Existing entries can be deleted from
<oldgroup> by adding lines with "# DELETE key" in the output of the script.·
To delete <oldgroup> use "# DELETEGROUP".

<interpreter> can be something like "perl" or "ruby".

It is also possible to have a script command without specifying <oldfile> or <newfile>. In that case the script is run but it will not be fed any input and its output will simply be discarded.

<code>
ScriptArguments=<arguments>
</code>

If specified, the arguments will be passed to <script>.
IMPORTANT: It has to be specified before Script=.

<code>
Group=<oldgroup>,<newgroup>
Group=<oldgroup>
</code>

Specifies that configuration information is read from the group <oldgroup>
and written to <newgroup>. If you only specify <oldgroup>, the information
is read from as well as written to <oldgroup>. You can use <default> to
specify keys that are not under any group.

<code>
RemoveGroup=<oldgroup>
</code>

Specifies that <oldgroup> is removed entirely. This can be used
to remove obsolete entries or to force a revert to default values.

<code>
Options=<option1>, <option2>,
</code>

With this entry you can specify options that apply to the next "Script",
"Key" or "AllKeys" entry (only to the first!). Possible options are:

*"copy" Copy the configuration item instead of moving it. This means that
the configuration item will not be deleted from <oldfile>/<oldgroup>

*"overwrite" Normally, a configuration item is not moved if an item with the
new name already exists. When this option is specified the old configuration item will overwrite any existing item.

Key=<oldkey>,<newkey>
Key=<oldkey>

Specifies that configuration information is read from the key <oldkey>
and written to <newkey>. If you only specify <oldkey>, the information
is read from as well as written to <oldkey>.

<code>
AllKeys
</code>

Specifies that all configuration information in the selected group should
be moved (All keys).

<code>
AllGroups
</code>

Specifies that all configuration information from all keys in ALL·
groups should be moved.

<code>
RemoveKey=<oldkey>
</code>

Specifies that <oldkey> is removed from the selected group. This can be used
to remove obsolete entries or to force a revert to default values.

Development/Tutorials/Updating KConfig Files

2007-12-31T18:12:05Z

Rememberme:

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Updating_KConfig_Files}}
{{TutorialBrowser|

series=KConfig|

pre=[[../Using_KConfig_XT| Using KConfig XT]]|

next=none

name=Updating KConfig files|

}}

=KConfig Update=

This page describes how a developer can use the KConfig update mechanism (kconf_update) available in kdelibs to update a user's already existing config file to accomodate changes made to the format of the default config file.

==Why should you use it?==

Over time applications sometimes need to rearrange the way configuration options are stored. Since such an update shouldn't influence the configuration options that the user has selected, the application must take care that the options stored in the old way will still be honored.

What used to happen is that the application looks up both the old and the
new configuration option and then decides which one to use. This method has several drawbacks:
* The application may need to read more configuration files than strictly needed, resulting in a slower startup.
* The application becomes bigger with code that will only be used once.

kconf_update addresses these problems by offering a framework to update configuration files without adding code to the application itself.

==How it works==

Applications can install so called "update files" under
{{Path|$KDEDIR/share/apps/kconf_update.}} An update file has {{Path|.upd}} as an extension and contains instructions for transferring/converting configuration information from one place to another.

Updating the configuration happens automatically, either when KDE gets started
or when kded detects a new update file in the above mentioned location.

Update files are separated into sections. Each section has an id. When a
section describing a configuration change has been applied, the id will be
stored in the file {{Path|kconf_updaterc}}. This information is used to make sure that a configuration update is only performed once.

If you overwrite an existing update file with a new version that contains a
new section, only the update instructions from this extra section will be
performed.

==File format of the update file==

Empty lines or lines that start with '#' are considered comments
Commas (,) are used to seperate fields and may not occur as part
of any field and all of the keywords are case-sensitive, i.e. you
cannot say "key" instead of "Key" for example.

For the rest the file is parsed and executed sequentially from top to bottom.
Each line can contain one entry. The following entries are recognized:

<code>Id=<id></code>

With <id> identifying the group of update entries that follows. Once a group
of entries have been applied, their <id> is stored and this group of entries
will not be applied again.

<code>
File=<oldfile>,<newfile>
File=<oldfile>
</code>

Specifies that configuration information is read from <oldfile> and written
to <newfile>. If you only specify <oldfile>, the information is read from
and as written to <oldfile>. Note that if the file does not exist
at the time kconf_update first checks, no related update will be performed.

<code>
Script=<script>[,<interpreter>]
</code>

<script> is the program that will be performing the updates. All entries from <oldfile> are piped into <script>. The output of <script>is used as new entries for <newfile>. Existing entries can be deleted by adding lines with "# DELETE [group]key" in the output of the script. To delete a whole group use "# DELETEGROUP [group]".

There are two types of kconf_update scripts:
*Non-Compiled
*Compiled

If <script> is written in a non-compiled language (such as ruby or perl), then it should be installed into
{{Path|${KCONF_UPDATE_INSTALL_DIR} }}.

If <script> is a compiled application, it should be installed in {{Path|${BIN_INSTALL_DIR}/kconf_update_bin}}

If the script command is issued after a "Group" command the behavior is slightly
different:

All entries from <oldfile> in <oldgroup> are piped into <script>. The output
of script is used as new entries for <newfile> in <newgroup>, unless a different
group is specified with "[group]". Existing entries can be deleted from
<oldgroup> by adding lines with "# DELETE key" in the output of the script.·
To delete <oldgroup> use "# DELETEGROUP".

<interpreter> can be something like "perl" or "ruby".

It is also possible to have a script command without specifying <oldfile> or <newfile>. In that case the script is run but it will not be fed any input and its output will simply be discarded.

<code>
ScriptArguments=<arguments>
</code>

If specified, the arguments will be passed to <script>.
IMPORTANT: It has to be specified before Script=.

<code>
Group=<oldgroup>,<newgroup>
Group=<oldgroup>
</code>

Specifies that configuration information is read from the group <oldgroup>
and written to <newgroup>. If you only specify <oldgroup>, the information
is read from as well as written to <oldgroup>. You can use <default> to
specify keys that are not under any group.

<code>
RemoveGroup=<oldgroup>
</code>

Specifies that <oldgroup> is removed entirely. This can be used
to remove obsolete entries or to force a revert to default values.

<code>
Options=<option1>, <option2>,
</code>

With this entry you can specify options that apply to the next "Script",
"Key" or "AllKeys" entry (only to the first!). Possible options are:

*"copy" Copy the configuration item instead of moving it. This means that
the configuration item will not be deleted from <oldfile>/<oldgroup>

*"overwrite" Normally, a configuration item is not moved if an item with the
new name already exists. When this option is specified the old configuration item will overwrite any existing item.

Key=<oldkey>,<newkey>
Key=<oldkey>

Specifies that configuration information is read from the key <oldkey>
and written to <newkey>. If you only specify <oldkey>, the information
is read from as well as written to <oldkey>.

<code>
AllKeys
</code>

Specifies that all configuration information in the selected group should
be moved (All keys).

<code>
AllGroups
</code>

Specifies that all configuration information from all keys in ALL·
groups should be moved.

<code>
RemoveKey=<oldkey>
</code>

Specifies that <oldkey> is removed from the selected group. This can be used
to remove obsolete entries or to force a revert to default values.

Development/Tutorials/Updating KConfig Files

2007-12-31T18:11:26Z

Rememberme:

Development/Tutorials/Using KConfig XT

2007-12-31T18:07:03Z

Rememberme:

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Using_KConfig_XT}}
{{TutorialBrowser|

series=KConfig|

pre=[[../KConfig|Introduction to KConfig]]|

next=[[../Updating_KConfig_Files|Updating Kconfig Files]]|

name=Using KConfig XT|

reading=[http://api.kde.org/4.0-api/kdelibs-apidocs/kdecore/html/kconfig_compiler.html The KDE Configuration Compiler (KDE 4)]<br>[http://api.kde.org/3.5-api/kdelibs-apidocs/kdecore/html/kconfig_compiler.html The KDE Configuration Compiler (KDE 3)]

}}

== Using KConfig XT ==
''Original Author'': Zack Rusin <[mailto:zack@kde.org zack@kde.org]>

This tutorial introduces the main concepts of the KconfigXT
configuration framework and shows how to efficiently use it in applications. It assumes that the reader has already developed a KDE application and is familiar with KConfig. A basic understanding of XML and concepts behind DTDs is also required.

The main idea behind KConfig XT is to make the life of application developers
easier while making the administration of large KDE installations more manageable.
The four basic parts of the new framework are:

* KConfigSkeleton - a class in the libkdecore library which grants a more flexible access to the configuration options,
* XML file containing information about configuration options (the {{path|.kcfg}} file)
* An ini like file which provides the code generation options (the {{path|.kcfgc}} file)
* kconfig_compiler - which generates C++ source code from {{path|.kcfg}} and {{path|.kcfgc}} files. The generated class is based on KConfigSkeleton and provides an API for the application to access its configuration data.

{{note|In this tutorial more advanced and optional features of KConfig XT and their descriptions are marked by ''italic text''. If you decide to skip them during the first reading, be sure to come back to them at some point. }}

== .kcfg DTD Structure ==

The structure of the {{path|.kcfg}} file is described by its DTD (kcfg.xsd - available from
[http://www.kde.org/standards/kcfg/1.0/kcfg.xsd here] (please note that browsers do not display DTDs in a visual form,
download the DTD directly and view it like a text file) or the kdecore
library). Please go through it before you go any further.

Lets create a simple .kcfg file. Please reference the code below as we go through each step.

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kcfg SYSTEM
"http://www.kde.org/standards/kcfg/1.0/kcfg.xsd">
<kcfg>
<kcfgfile name="kjotsrc"/>
<include>kglobalsettings.h</include>
<group name="kjots">
<entry name="SplitterSizes" type="IntList">
<label>How the main window is divided.</label>
</entry>
<entry name="Width" type="Int">
<label>Width of the main window.</label>
<default>600</default>
</entry>
<entry name="Height" type="Int">
<label>Height of the main window.</label>
<default>400</default>
</entry>
<entry name="OpenBooks" type="StringList">
<label>All books that are opened.</label>
</entry>
<entry name="CurrentBook" type="String">
<label>The book currently opened.</label>
</entry>
<entry name="Font" type="Font">
<label>The font used to display the contents of books.</label>
<default code="true">KGlobalSettings::generalFont()</default>
</entry>
</group>
</kcfg>
</code>

* Use your favorite code editor to open a your_application_name{{path|.kcfg}} file (of course replacing your_application_name with the name of the application you want to convert to KConfig XT).
* Start that file by opening the <kcfgfile> tag which controls which KConfig file the data will be stored in. There are three possibilities:
*# If the <kcfgfile> tag has no attributes the generated code will use the application's default KConfig file (normally {{path|$HOME/.kde/config/<appname>rc}}).
*# ''The "name" attribute is used to manually specify a file name. If the value assigned to "name" is not an absolute file path, the file will be created in the default KDE config directory (normally {{path|$HOME/.kde/config}}).''
*# ''If you would like to be able to specify the config file at construction time, use <kcfgfile arg="true">. This causes the constructor of the generated class to take a KSharedConfig::Ptr as an argument, allowing you to construct multiple instances pointing to different files.''
* ''Add the optional <include> tags which may contain C++ header files that are needed to compile the code required to compute the default values.''
* The remaining entries in the XML file are grouped by the tag <group> which describes the corresponding groups in the configuration file.
*#The individual entries must have at least a name or a key. The key is used as the key in the config file. The name is used to create accessor and modifier functions. If <key> is not given, the name is used as the config file key. If <key> is given, but not <name>, the name is constructed by removing all spaces from the <key> contents.
*# Always add a label or a whatsthis tags to your application in which you describe the configuration options. The label tag is used for short descriptions of the entry, while whatsthis contains more verbose documentation. ''It's important for tools like KConfigEditor which can be used by systems administrators to setup machines over on the network.''
*# An entry must also have a type. The allowed types are: String, StringList, Font, Rect, Size, Color, Point, Int, UInt, Bool, Double, DateTime, Int64, UInt64 and Password. '' Besides those basic type the following special types are supported and include:''
*#* Path - This is a string that is specially treated as a file-path. In particular paths in the home directory are prefixed with $HOME when being stored in the configuration file.
*#* Enum - This indicates an enumeration. The possible enum values should be provided via the <choices> tag. Enum values are accessed as integers by the application but stored as string in the configuration file. This makes it possible to add more values at a later date without breaking compatibility.
*#* IntList - This indicates a list of integers. This information is provided to the application as QValueList<int>. Useful for storing QSplitter geometries.
*#* PathList - List of Path elements.
*# The min and max tags can be set to limit the value of the integer-type options.
*#''An entry can optionally have a default value which is used as default when the value isn't specified in any config file. Default values are interpreted as literal constant values. If a default value needs to be computed or if it needs to be obtained from a function call, the <default> tag should contain the code="true" attribute. The contents of the <default> tag is then considered to be a C++ expression. ''
*#''Additional code for computing default values can be provided via the <code> tag. The contents of the <code> tag is inserted as-is. A typical use for this is to compute a common default value which can then be referenced by multiple entries that follow.''
*#''Optionally, the hidden option can also be added to the <entry>. The possible values are true and false.''

== .kcfgc files ==

After creating a {{path|.kcfg}} file create a {{path|.kcfgc}} file which describes the C++ file
generation options. The .kcfgc file is a simple ini file with the typical
"entry=value" format. To create a simple .kcfgc file follow these steps:

# Open a new file in your favorite text editor.
# Start it with the "File=your_application_name.kcfg" entry which specifies where the configuration options for your application are stored.
# Add the "ClassName=YourConfigClassName" entry which specifies the name of the class that will be generated from the .kcfg file. Remember that the generated class will be derived from KConfigSkeleton. PLease make sure that YourConfigClassName is not a class name already used in your application. Save this file under {{path|yourconfigclassname.kcfgc.}} This will ensure the generation of the yourconfigclassname.{h,cpp} files where your configuration class will reside.
# Add any additional entries, which your application might need. Those additional entries include:
#* NameSpace - specifies the namespace in which the generated config class should reside,
#* Inherits - if you need the generated class to inherit your custom class,
#* Singleton - if the configuration class should be a singleton,
#* MemberVariables - specifies the access to the member variables, default is private,
#* ItemAccessors - relates to the above item, if member variables are public then it might make little sense to generate accessors. By default they are generated,
#* Mutators - similar to the above one, but applies to the mutator methods,
#* GlobalEnums - specifies whether enums should be class wide of whether they should be always explicitly prefixed with their type name,
#* UseEnumTypes - specifies whether enum values should be passed as type int or as their enum type in the return value of accessor functions and the arguments of mutator and signal functions.

== Adjusting the CMakeLists.txt file ==

After creating the .kcfg and .kcfgc files the next step is to adjust the
build to let kconfig_compiler generate the required class at compile time. Fortunately doing this is trivial and requires only one step, adding this line to the CMakeLists.txt file example:

kde4_add_kcfg_files(<project name>_SRCS settings.kcfgc)

Alternatively, if a .moc file needs to be generated before compiling the generated source code, use

kde4_add_kcfg_files(<project name>_SRCS GENERATE_MOC settings.kcfgc)

This assures that the configuration class is properly generated and that the .kcfg is installed so it can be used by tools like
the KConfigEditor.

== Use and Dialogs ==

After making all of the above changes you're ready to use KConfig XT. The
kconfig_compiler generated header file will have the name equal to the name of the .kcfg file but with a ".h" extension. Simply include that file wherever you want to access your configuration options.

The use will depend on whether you have added the <tt>Singleton=true</tt> entry to your .kcfgc file.

One the nicest features of the KConfig XT is its seamless integration with the Qt
Designer generated dialogs. You can do that by using {{class|KConfigDialog}}. The
steps to do that are as follows:

# Create the KConfigDialog and pass the instance of your configuration data as one of the arguments. The construct would look like the following example:

<code cppqt>
KConfigDialog* dialog = new KConfigDialog(
this, "settings", YourAppSettings::self() );
</code>

assuming that YourAppSettings is the value of the ClassName variable from the kcfgc file and the settings class is a singelton.
# In Qt Designer create widgets which should be used to configure your options. In order to make those widgets interact with the kcfg you have name each one of them using the following scheme:
## Prefix the Name of the widget which should control one of the options with "kcfg_"
## Append the "name" attribute value from your kcfg file which corresponds to option the given widget should control.
# Add the Qt Designer generated widget to the KConfigDialog.
# Show the dialog when you're done.

== Example ==

Here's an example usage of KConfig XT for the application named Example.
With the following example.kcfg file:

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kcfg SYSTEM
"http://www.kde.org/standards/kcfg/1.0/kcfg.dtd">
<kcfg> <kcfgfile name="examplerc"/>
<group name="network">
<entry name="ServerName" type="String">
<label>Defines the sample server.</label>
</entry>
<entry name="Port" type="Int">
<label>Defines the server port</label>
<default>21</default>
<min>20</min>
<max>990</max>
</entry>
</group>
</kcfg>
</code>

And here's how to actually use the generated class. for the given kcfgc file.

<code ini>
File=example.kcfg
ClassName=ExampleSettings
Singleton=true
Mutators=true
</code>

The header files wouldn't change, but the cpp files must now contain the
following code to access and store the configuration data :

<code cppqt>
...
#include <ExampleSettings.h>
...
void ExampleClass::readConfig() {
m_server = ExampleSettings::serverName();
m_port = ExampleSettings::port();
}
void ExampleClass:saveSettings() {
ExampleSettings::setServerName( m_server );
ExampleSettings::setPort( m_port );
ExampleSettings::writeConfig();
}
</code>

To add a dialog you need to create a Qt Designer widget with the widget names
corresponding to the names of the options they should edit and prefixed with "kcfg_".
It could be something along the lines of:

[[Image:kconfigxt.png|center|256px]]

And you can use the dialog with the following code:

<code cppqt>
//An instance of your dialog could be already created and could be
// cached, in which case you want to display the cached dialog
// instead of creating another one
if ( KConfigDialog::showDialog( "settings" ) )
return;

// KConfigDialog didn't find an instance of this dialog, so lets
// create it :
KConfigDialog* dialog = new KConfigDialog(this, "settings",
ExampleSettings::self());
ExampleDesignerWidget* confWdg =
new ExampleDesignerWidget( 0, "Example" );

dialog->addPage( confWdg, i18n("Example"), "example" );

//User edited the configuration - update your local copies of the
//configuration data
connect( dialog, SIGNAL(settingsChanged()),
this, SLOT(updateConfiguration()) );

dialog->show();
</code>

And that's all it takes. You can have a look at [http://websvn.kde.org/trunk/KDE/kdegames/kreversi KReversi] and [http://websvn.kde.org/trunk/KDE/kdegames/ktron/ KTron] code in the [http://websvn.kde.org/trunk/KDE/kdegames kdegames module] to see a live example of KConfig XT!

== Common Pitfalls and Tips ==

* Do not forget to add the "type" attribute to the "entry" tag in your .kcfg file.
* Always try to add both the <label> and <whatsthis> tags to each entry.
* Putting the MemberVariables=public in your .kcfgc is usually a bad idea - you'll avoid accidental changes to those members by using the aggregation and forcing the use of the mutators.
* If your application doesn't have one central object (created before and destructed after; all others) then always put the Singleton=true entry in your .kcfgs file.
[[Category:C++]]

Development/Tutorials/Updating KConfig Files

2007-12-31T14:43:07Z

Rememberme:

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Updating_KConfig_Files}}
{{TutorialBrowser|

series=KConfig|

pre=[[../KConfig|Introduction to KConfig]]|

name=Updating KConfig files|

}}

=KConfig Update=

This page describes how a developer can use the KConfig update mechanism (kconf_update) available in kdelibs to update a user's already existing config file to accomodate changes made to the format of the default config file.

==Why should you use it?==

Over time applications sometimes need to rearrange the way configuration options are stored. Since such an update shouldn't influence the configuration options that the user has selected, the application must take care that the options stored in the old way will still be honored.

What used to happen is that the application looks up both the old and the
new configuration option and then decides which one to use. This method has several drawbacks:
* The application may need to read more configuration files than strictly needed, resulting in a slower startup.
* The application becomes bigger with code that will only be used once.

kconf_update addresses these problems by offering a framework to update configuration files without adding code to the application itself.

==How it works==

Applications can install so called "update files" under
{{Path|$KDEDIR/share/apps/kconf_update.}} An update file has {{Path|.upd}} as an extension and contains instructions for transferring/converting configuration information from one place to another.

Updating the configuration happens automatically, either when KDE gets started
or when kded detects a new update file in the above mentioned location.

Update files are separated into sections. Each section has an id. When a
section describing a configuration change has been applied, the id will be
stored in the file {{Path|kconf_updaterc}}. This information is used to make sure that a configuration update is only performed once.

If you overwrite an existing update file with a new version that contains a
new section, only the update instructions from this extra section will be
performed.

==File format of the update file==

Empty lines or lines that start with '#' are considered comments
Commas (,) are used to seperate fields and may not occur as part
of any field and all of the keywords are case-sensitive, i.e. you
cannot say "key" instead of "Key" for example.

For the rest the file is parsed and executed sequentially from top to bottom.
Each line can contain one entry. The following entries are recognized:

<code>Id=<id></code>

With <id> identifying the group of update entries that follows. Once a group
of entries have been applied, their <id> is stored and this group of entries
will not be applied again.

<code>
File=<oldfile>,<newfile>
File=<oldfile>
</code>

Specifies that configuration information is read from <oldfile> and written
to <newfile>. If you only specify <oldfile>, the information is read from
and as written to <oldfile>. Note that if the file does not exist
at the time kconf_update first checks, no related update will be performed.

<code>
Script=<script>[,<interpreter>]
</code>

<script> is the program that will be performing the updates. All entries from <oldfile> are piped into <script>. The output of <script>is used as new entries for <newfile>. Existing entries can be deleted by adding lines with "# DELETE [group]key" in the output of the script. To delete a whole group use "# DELETEGROUP [group]".

There are two types of kconf_update scripts:
*Non-Compiled
*Compiled

If <script> is written in a non-compiled language (such as ruby or perl), then it should be installed into
{{Path|${KCONF_UPDATE_INSTALL_DIR} }}.

If <script> is a compiled application, it should be installed in {{Path|${BIN_INSTALL_DIR}/kconf_update_bin}}

If the script command is issued after a "Group" command the behavior is slightly
different:

All entries from <oldfile> in <oldgroup> are piped into <script>. The output
of script is used as new entries for <newfile> in <newgroup>, unless a different
group is specified with "[group]". Existing entries can be deleted from
<oldgroup> by adding lines with "# DELETE key" in the output of the script.·
To delete <oldgroup> use "# DELETEGROUP".

<interpreter> can be something like "perl" or "ruby".

It is also possible to have a script command without specifying <oldfile> or <newfile>. In that case the script is run but it will not be fed any input and its output will simply be discarded.

<code>
ScriptArguments=<arguments>
</code>

If specified, the arguments will be passed to <script>.
IMPORTANT: It has to be specified before Script=.

<code>
Group=<oldgroup>,<newgroup>
Group=<oldgroup>
</code>

Specifies that configuration information is read from the group <oldgroup>
and written to <newgroup>. If you only specify <oldgroup>, the information
is read from as well as written to <oldgroup>. You can use <default> to
specify keys that are not under any group.

<code>
RemoveGroup=<oldgroup>
</code>

Specifies that <oldgroup> is removed entirely. This can be used
to remove obsolete entries or to force a revert to default values.

<code>
Options=<option1>, <option2>,
</code>

With this entry you can specify options that apply to the next "Script",
"Key" or "AllKeys" entry (only to the first!). Possible options are:

*"copy" Copy the configuration item instead of moving it. This means that
the configuration item will not be deleted from <oldfile>/<oldgroup>

*"overwrite" Normally, a configuration item is not moved if an item with the
new name already exists. When this option is specified the old configuration item will overwrite any existing item.

Key=<oldkey>,<newkey>
Key=<oldkey>

Specifies that configuration information is read from the key <oldkey>
and written to <newkey>. If you only specify <oldkey>, the information
is read from as well as written to <oldkey>.

<code>
AllKeys
</code>

Specifies that all configuration information in the selected group should
be moved (All keys).

<code>
AllGroups
</code>

Specifies that all configuration information from all keys in ALL·
groups should be moved.

<code>
RemoveKey=<oldkey>
</code>

Specifies that <oldkey> is removed from the selected group. This can be used
to remove obsolete entries or to force a revert to default values.

Development/Tutorials/Using KConfig XT

2007-12-31T14:42:18Z

Rememberme:

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Using_KConfig_XT}}
{{TutorialBrowser|

series=KConfig|

pre=[[../KConfig|Introduction to KConfig]]|

name=Using KConfig XT|

reading=[http://api.kde.org/4.0-api/kdelibs-apidocs/kdecore/html/kconfig_compiler.html The KDE Configuration Compiler (KDE 4)]<br>[http://api.kde.org/3.5-api/kdelibs-apidocs/kdecore/html/kconfig_compiler.html The KDE Configuration Compiler (KDE 3)]

}}

== Using KConfig XT ==
''Original Author'': Zack Rusin <[mailto:zack@kde.org zack@kde.org]>

This tutorial introduces the main concepts of the KconfigXT
configuration framework and shows how to efficiently use it in applications. It assumes that the reader has already developed a KDE application and is familiar with KConfig. A basic understanding of XML and concepts behind DTDs is also required.

The main idea behind KConfig XT is to make the life of application developers
easier while making the administration of large KDE installations more manageable.
The four basic parts of the new framework are:

* KConfigSkeleton - a class in the libkdecore library which grants a more flexible access to the configuration options,
* XML file containing information about configuration options (the {{path|.kcfg}} file)
* An ini like file which provides the code generation options (the {{path|.kcfgc}} file)
* kconfig_compiler - which generates C++ source code from {{path|.kcfg}} and {{path|.kcfgc}} files. The generated class is based on KConfigSkeleton and provides an API for the application to access its configuration data.

{{note|In this tutorial more advanced and optional features of KConfig XT and their descriptions are marked by ''italic text''. If you decide to skip them during the first reading, be sure to come back to them at some point. }}

== .kcfg DTD Structure ==

The structure of the {{path|.kcfg}} file is described by its DTD (kcfg.xsd - available from
[http://www.kde.org/standards/kcfg/1.0/kcfg.xsd here] (please note that browsers do not display DTDs in a visual form,
download the DTD directly and view it like a text file) or the kdecore
library). Please go through it before you go any further.

Lets create a simple .kcfg file. Please reference the code below as we go through each step.

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kcfg SYSTEM
"http://www.kde.org/standards/kcfg/1.0/kcfg.xsd">
<kcfg>
<kcfgfile name="kjotsrc"/>
<include>kglobalsettings.h</include>
<group name="kjots">
<entry name="SplitterSizes" type="IntList">
<label>How the main window is divided.</label>
</entry>
<entry name="Width" type="Int">
<label>Width of the main window.</label>
<default>600</default>
</entry>
<entry name="Height" type="Int">
<label>Height of the main window.</label>
<default>400</default>
</entry>
<entry name="OpenBooks" type="StringList">
<label>All books that are opened.</label>
</entry>
<entry name="CurrentBook" type="String">
<label>The book currently opened.</label>
</entry>
<entry name="Font" type="Font">
<label>The font used to display the contents of books.</label>
<default code="true">KGlobalSettings::generalFont()</default>
</entry>
</group>
</kcfg>
</code>

* Use your favorite code editor to open a your_application_name{{path|.kcfg}} file (of course replacing your_application_name with the name of the application you want to convert to KConfig XT).
* Start that file by opening the <kcfgfile> tag which controls which KConfig file the data will be stored in. There are three possibilities:
*# If the <kcfgfile> tag has no attributes the generated code will use the application's default KConfig file (normally {{path|$HOME/.kde/config/<appname>rc}}).
*# ''The "name" attribute is used to manually specify a file name. If the value assigned to "name" is not an absolute file path, the file will be created in the default KDE config directory (normally {{path|$HOME/.kde/config}}).''
*# ''If you would like to be able to specify the config file at construction time, use <kcfgfile arg="true">. This causes the constructor of the generated class to take a KSharedConfig::Ptr as an argument, allowing you to construct multiple instances pointing to different files.''
* ''Add the optional <include> tags which may contain C++ header files that are needed to compile the code required to compute the default values.''
* The remaining entries in the XML file are grouped by the tag <group> which describes the corresponding groups in the configuration file.
*#The individual entries must have at least a name or a key. The key is used as the key in the config file. The name is used to create accessor and modifier functions. If <key> is not given, the name is used as the config file key. If <key> is given, but not <name>, the name is constructed by removing all spaces from the <key> contents.
*# Always add a label or a whatsthis tags to your application in which you describe the configuration options. The label tag is used for short descriptions of the entry, while whatsthis contains more verbose documentation. ''It's important for tools like KConfigEditor which can be used by systems administrators to setup machines over on the network.''
*# An entry must also have a type. The allowed types are: String, StringList, Font, Rect, Size, Color, Point, Int, UInt, Bool, Double, DateTime, Int64, UInt64 and Password. '' Besides those basic type the following special types are supported and include:''
*#* Path - This is a string that is specially treated as a file-path. In particular paths in the home directory are prefixed with $HOME when being stored in the configuration file.
*#* Enum - This indicates an enumeration. The possible enum values should be provided via the <choices> tag. Enum values are accessed as integers by the application but stored as string in the configuration file. This makes it possible to add more values at a later date without breaking compatibility.
*#* IntList - This indicates a list of integers. This information is provided to the application as QValueList<int>. Useful for storing QSplitter geometries.
*#* PathList - List of Path elements.
*# The min and max tags can be set to limit the value of the integer-type options.
*#''An entry can optionally have a default value which is used as default when the value isn't specified in any config file. Default values are interpreted as literal constant values. If a default value needs to be computed or if it needs to be obtained from a function call, the <default> tag should contain the code="true" attribute. The contents of the <default> tag is then considered to be a C++ expression. ''
*#''Additional code for computing default values can be provided via the <code> tag. The contents of the <code> tag is inserted as-is. A typical use for this is to compute a common default value which can then be referenced by multiple entries that follow.''
*#''Optionally, the hidden option can also be added to the <entry>. The possible values are true and false.''

== .kcfgc files ==

After creating a {{path|.kcfg}} file create a {{path|.kcfgc}} file which describes the C++ file
generation options. The .kcfgc file is a simple ini file with the typical
"entry=value" format. To create a simple .kcfgc file follow these steps:

# Open a new file in your favorite text editor.
# Start it with the "File=your_application_name.kcfg" entry which specifies where the configuration options for your application are stored.
# Add the "ClassName=YourConfigClassName" entry which specifies the name of the class that will be generated from the .kcfg file. Remember that the generated class will be derived from KConfigSkeleton. PLease make sure that YourConfigClassName is not a class name already used in your application. Save this file under {{path|yourconfigclassname.kcfgc.}} This will ensure the generation of the yourconfigclassname.{h,cpp} files where your configuration class will reside.
# Add any additional entries, which your application might need. Those additional entries include:
#* NameSpace - specifies the namespace in which the generated config class should reside,
#* Inherits - if you need the generated class to inherit your custom class,
#* Singleton - if the configuration class should be a singleton,
#* MemberVariables - specifies the access to the member variables, default is private,
#* ItemAccessors - relates to the above item, if member variables are public then it might make little sense to generate accessors. By default they are generated,
#* Mutators - similar to the above one, but applies to the mutator methods,
#* GlobalEnums - specifies whether enums should be class wide of whether they should be always explicitly prefixed with their type name,
#* UseEnumTypes - specifies whether enum values should be passed as type int or as their enum type in the return value of accessor functions and the arguments of mutator and signal functions.

== Adjusting the CMakeLists.txt file ==

After creating the .kcfg and .kcfgc files the next step is to adjust the
build to let kconfig_compiler generate the required class at compile time. Fortunately doing this is trivial and requires only one step, adding this line to the CMakeLists.txt file example:

kde4_add_kcfg_files(<project name>_SRCS settings.kcfgc)

Alternatively, if a .moc file needs to be generated before compiling the generated source code, use

kde4_add_kcfg_files(<project name>_SRCS GENERATE_MOC settings.kcfgc)

This assures that the configuration class is properly generated and that the .kcfg is installed so it can be used by tools like
the KConfigEditor.

== Use and Dialogs ==

After making all of the above changes you're ready to use KConfig XT. The
kconfig_compiler generated header file will have the name equal to the name of the .kcfg file but with a ".h" extension. Simply include that file wherever you want to access your configuration options.

The use will depend on whether you have added the <tt>Singleton=true</tt> entry to your .kcfgc file.

One the nicest features of the KConfig XT is its seamless integration with the Qt
Designer generated dialogs. You can do that by using {{class|KConfigDialog}}. The
steps to do that are as follows:

# Create the KConfigDialog and pass the instance of your configuration data as one of the arguments. The construct would look like the following example:

<code cppqt>
KConfigDialog* dialog = new KConfigDialog(
this, "settings", YourAppSettings::self() );
</code>

assuming that YourAppSettings is the value of the ClassName variable from the kcfgc file and the settings class is a singelton.
# In Qt Designer create widgets which should be used to configure your options. In order to make those widgets interact with the kcfg you have name each one of them using the following scheme:
## Prefix the Name of the widget which should control one of the options with "kcfg_"
## Append the "name" attribute value from your kcfg file which corresponds to option the given widget should control.
# Add the Qt Designer generated widget to the KConfigDialog.
# Show the dialog when you're done.

== Example ==

Here's an example usage of KConfig XT for the application named Example.
With the following example.kcfg file:

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kcfg SYSTEM
"http://www.kde.org/standards/kcfg/1.0/kcfg.dtd">
<kcfg> <kcfgfile name="examplerc"/>
<group name="network">
<entry name="ServerName" type="String">
<label>Defines the sample server.</label>
</entry>
<entry name="Port" type="Int">
<label>Defines the server port</label>
<default>21</default>
<min>20</min>
<max>990</max>
</entry>
</group>
</kcfg>
</code>

And here's how to actually use the generated class. for the given kcfgc file.

<code ini>
File=example.kcfg
ClassName=ExampleSettings
Singleton=true
Mutators=true
</code>

The header files wouldn't change, but the cpp files must now contain the
following code to access and store the configuration data :

<code cppqt>
...
#include <ExampleSettings.h>
...
void ExampleClass::readConfig() {
m_server = ExampleSettings::serverName();
m_port = ExampleSettings::port();
}
void ExampleClass:saveSettings() {
ExampleSettings::setServerName( m_server );
ExampleSettings::setPort( m_port );
ExampleSettings::writeConfig();
}
</code>

To add a dialog you need to create a Qt Designer widget with the widget names
corresponding to the names of the options they should edit and prefixed with "kcfg_".
It could be something along the lines of:

[[Image:kconfigxt.png|center|256px]]

And you can use the dialog with the following code:

<code cppqt>
//An instance of your dialog could be already created and could be
// cached, in which case you want to display the cached dialog
// instead of creating another one
if ( KConfigDialog::showDialog( "settings" ) )
return;

// KConfigDialog didn't find an instance of this dialog, so lets
// create it :
KConfigDialog* dialog = new KConfigDialog(this, "settings",
ExampleSettings::self());
ExampleDesignerWidget* confWdg =
new ExampleDesignerWidget( 0, "Example" );

dialog->addPage( confWdg, i18n("Example"), "example" );

//User edited the configuration - update your local copies of the
//configuration data
connect( dialog, SIGNAL(settingsChanged()),
this, SLOT(updateConfiguration()) );

dialog->show();
</code>

And that's all it takes. You can have a look at [http://websvn.kde.org/trunk/KDE/kdegames/kreversi KReversi] and [http://websvn.kde.org/trunk/KDE/kdegames/ktron/ KTron] code in the [http://websvn.kde.org/trunk/KDE/kdegames kdegames module] to see a live example of KConfig XT!

== Common Pitfalls and Tips ==

* Do not forget to add the "type" attribute to the "entry" tag in your .kcfg file.
* Always try to add both the <label> and <whatsthis> tags to each entry.
* Putting the MemberVariables=public in your .kcfgc is usually a bad idea - you'll avoid accidental changes to those members by using the aggregation and forcing the use of the mutators.
* If your application doesn't have one central object (created before and destructed after; all others) then always put the Singleton=true entry in your .kcfgs file.
[[Category:C++]]

Development/Tutorials/KConfig

2007-12-31T14:41:21Z

Rememberme:

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KConfig}}
{{TutorialBrowser|

series=KConfig|

name=Introduction to KConfig|

next=[[../Using_KConfig_XT|Using KConfig XT]]

}}

== Abstract ==

This tutorial looks at the KDE configuration data system, starting with an overview of the design fundamentals from an application developer's point of view. It then looks at the classes relevant to application development one by one before moving on to kiosk (user and group profiles) integration.

== Design Essentials ==

KConfig is designed to abstract away the concept of actual storage and retrieval of configuration settings behind an API that allows easy fetching and setting of information. Where and in what format the data is stored is not relevant to an application using KConfig. This keeps all KDE applications consistent in their handling of configurations while alleviating each and every application author to build such a system on their own from scratch, which can be a highly error prone exercise.

A KConfig object represents a single configuration object. Each configuration object is referenced by its unique name and may be actually read from multiple local or remote files or services. Each application has a default configuration object associated with it and there is also a global configuration object.

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|QObject}} object is passed to a config object directly when storing a color value and when retreived a {{qt|QObject}} object is returned. Applications themselves therefore generally do not have to perform serialization and deserialization of objects themselves.

== The KConfig Class ==

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>
// a plain old read/write config object
KConfig config("myapprc");

// a specific file in the filesystem
// currently must be an INI style file
KConfig fullPath("/etc/kderc");

// not merged with global values
KConfig globalFree( "localsrc", KConfig::NoGlobals );

// not merged with globals or the $KDEDIRS hierarchy
KConfig simpleConfig( "simplerc", KConfig::SimpleConfig );

// config specific to a component, in this case a plugin
KConfig pluginConfig( componentData(), "pluginrc" );

// outside the standard config resource
KConfig dataResource( "data", "myapp/somefile" );
</code>

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.

{{tip|For more information on how the merging works, see the [[KDE System Administration/KDE_Filesystem_Hierarchy|KDE Filesystem Hierarchy]] article.}}

On line 6 we open a specific local file, this case {{path|/etc/kderc}}. This performs no merging of values and expects an INI style file.

Line 9 sees the creation of a configuration object that is not merged with the global <tt>kdeglobals</tt> configuration object, while the configuration file on line 12 is additionally not merged with any files in the <tt>$KDEDIRS</tt> hierarchy. This can noticeably improve performance in the case where one is simply reading values out of a simple configuration for which global values are not meaningful.

Line 15 creates a configuration object using the {{class|KComponentData}} object that belongs to a plugin or other component. The plugin may have a different set of directories defined in its {{class|KStandardDirs}} and this is a way of ensuring that {{class|KConfig}} respects this.

Finally on line 18 we see the creation of a configuration object that does not exist in the <tt>config</tt> resource but rather in the application <tt>data</tt> resource. You may use any resource that {{class|KStandardDirs}} is aware of, including ones that are added at runtime.

=== 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:

<code cppqt n>
#include <KComponentData>
#include <KConfig>
#include <KGlobal>

MyClass::MyClass()
{
// note that this is actually a KSharedConfig
// more on that class in a bit!
KConfig* config = KGlobal::config();
}
</code>

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:

<code cppqt n>
#include <KConfig>

MyClass::MyClass()
{
KConfig config;
}
</code>

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>.

Finally there is a global configuration object, <tt>kdeglobals</tt>, that is shared by every application. It holds such information as the default application shortcuts for various actions. It is "blended" into the configuration object if the <tt>KConfig::IncludeGlobals</tt> flag is passed to the {{class|KConfig}} constructor, which is the default.

=== Commonly Useful Methods ===

To save the current state of the configuration object we call the <tt>sync()</tt> method. This method is also called when the object is destroyed. If no changes have been made or the resource reports itself as non-writable (such as in the case of the user not having write permissions to the file) then no disk activity occurs. <tt>sync()</tt> merges changes performed concurrently by other processes - local changes have priority, though.

If we want to make sure that we have the latest values from disk we can call <tt>reparseConfiguration()</tt> which calls <tt>sync()</tt> and then reloads the data from disk.

If we need to prevent the config object from saving already made modifications to disk we need to call <tt>markAsClean()</tt>. A particular use case for this is rolling back the configuration to the on-disk state by calling <tt>markAsClean()</tt> followed by <tt>reparseConfiguration()</tt>.

Listing all groups in a configuration object is as simple as calling <tt>groupList()</tt> as in this code snippet:

<code cppqt n>
KConfig* config = KGlobal::mainComponent().config();

foreach ( const QString& group, config.groupList() ) {
kDebug() << "next group:" << group;
}
</code>

== KSharedConfig ==

The {{class|KSharedConfig}} class is a reference counted version of {{class|KConfig}}. It thus provides a way to reference the same configuration object from multiple places in your application without the extra overhead of separate objects or concerns about syncronizing writes to disk even if the configuration object is updated from multiple code paths.

Accessing a {{class|KSharedConfig}} object is as easy as this:

<code cppqt n>
KSharedConfigPtr config = KSharedConfig::openConfig();
</code>

<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.

{{class|KSharedConfig}} is generally recommended over using {{class|KConfig}} itself, and the object returned from {{class|KComponentData}} is indeed a {{class|KSharedConfig}} object.

== KConfigGroup ==

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>
KConfig config;
KConfigGroup generalGroup( &config, "General" );
KConfigGroup colorsGroup = config.group( "Colors" ); // ... or a bit differently ...
</code>

You can pass {{class|KConfig}} or {{class|KSharedConfig}} objects to {{class|KConfigGroup}}.

Config groups can be nested as well:

<code cppqt n>
KConfigGroup subGroup1( &generalGroup, "LessGeneral" );
KConfigGroup subGroup2 = colorsGroup.group( "Dialogs" );
</code>

== Reading Entries ==

With a {{class|KConfigGroup}} object in hand reading entries is now quite straight forward:

<code cppqt n>
QString accountName = generalGroup.readEntry( "Account",
QString() );
QColor color = colorsGroup.readEntry( "background",
Qt::white );
QStringList list = generalGroup.readEntry( "List",
QStringList() );
QString path = generalGroup.readPathEntry( "SaveTo",
defaultPath );
</code>

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.

There are a couple of special read methods, including <tt>readPathEntry</tt> which returns a file system path. It is vital that one uses <tt>readPathEntry</tt> if it is a path as this enables such features as roaming profiles to work properly.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

== Writing Entries ==

Setting new values is similarly straightforward:

<code cppqt n>
generalGroup.writeEntry( "Account", accountName );
generalGroup.writePathEntry( "SaveTo", savePath );
colorGroup.writeEntry( "background", color );
generalGroup.config()->sync();
</code>

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.

== 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 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.

== Kiosk: Lockdown and User/Group Profiles ==

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as "Kiosk", that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occassion when an application will want to check on the read/write status of a configuration object.

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>
KConfig* config = KGlobal::config();

if ( config->isImmutable() ) {
kDebug() << "configuration object is immutable";
}

KConfigGroup group(config, "General");
if ( group.isImmutable() ) {
kDebug() << "group General is immutable";
}

if ( group.entryIsImmutable("URL") ) {
kDebug() << "URL entry in group General is immutable";
}
</code>

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.

== KConfig XT ==

There is a way to make certain use cases of KConfig easier, faster and more reliable: KConfig XT. In particular, for main application or plugin configuration objects and when syncing configuration dialogs and other interfaces with these values, KConfig XT can help immensely. It also simultaneously documents the configuration options available, which makes every sys admin and system integrator that uses KDE that much more happy.

[[../Using_KConfig_XT|The next tutorial in the KConfig series covers what KConfig XT is and how to use it.]]

KDE TechBase:Contributors

2007-12-31T14:37:06Z

Rememberme: /* German Team */

Welcome to the contributors page.

'''This site contains a list of ''active'' contributors. It should help to build teams which maintain KDE TechBase's content. If you have questions about KDE TechBase you can ask/email the corresponding person.'''

Please add yourself to the list where appropriate. If you are inactive, please remove yourself again.

== Administrators ==

This is a list of KDE TechBase administrators.

* [[User:Danimo|Danimo]]
* [[User:Dhaumann|Dhaumann]], <dhaumann at kde dot org>

== Reviewers and Article Writers ==

If you are continuously reviewing KDE TechBase changes or writing articles add yourself to the list.

* [[User:Dhaumann|Dhaumann]], <dhaumann at kde dot org>
* [[User:Milliams|Milliams]]
* name, <email>

== Translation Teams ==

KDE TechBase is [[Help:Wiki Translation|translated]] into many languages. If you translate pages please add yourself to the right translation team.

=== Chinese(simplified) Team ===
* [[User:Liangqi|Liangqi]], cavendish.qi at gmail dot com
* name, <email>

=== Spanish Team ===
* [[User:Mjp ttc|Mjp ttc]], mjp_ttc at yahoo dot com
* name, <email>

=== German Team ===
* [[User:DrSlowDecay|DrSlowDecay]], kde at metalhorde dot de
* [[User:Rememberme|rememberme]] redict dot info at gmx dot net
* name, <email>

=== Italian Team ===
* [[User:Thunder Teaser|Thunder Teaser]], totokid at gmail dot com
* name, <email>

=== ... Team ===
* name, <email>

User:Rememberme

2007-12-31T14:36:37Z

Rememberme: New page: Translating some Documentation to German.

Translating some Documentation to German.