File: ch07lev1sec2.html

package info (click to toggle)
ebook-dev-kde20 200010-3
links: PTS
area: non-free
in suites: etch, etch-m68k, sarge
size: 11,428 kB
ctags: 2,726
sloc: sh: 96; makefile: 35
file content (519 lines) | stat: -rw-r--r-- 11,675 bytes
parent folder | download | duplicates (2)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>Application Configuration Information</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.54"/><LINK
REL="HOME"
TITLE="KDE 2.0 Development"
HREF="index.html"/><LINK
REL="UP"
TITLE="Further KDE Compliance"
HREF="ch07.html"/><LINK
REL="PREVIOUS"
TITLE="Further KDE Compliance"
HREF="ch07.html"/><LINK
REL="NEXT"
TITLE="Session Management"
HREF="ch07lev1sec3.html"/><META
HTTP-EQUIV="Content-Style-Type"
CONTENT="text/css"/><LINK
REL="stylesheet"
HREF="kde-common.css"
TYPE="text/css"/><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=iso-8859-1"/><META
HTTP-EQUIV="Content-Language"
CONTENT="en"/><LINK
REL="stylesheet"
HREF="kde-localised.css"
TYPE="text/css"
TITLE="KDE-English"/><LINK
REL="stylesheet"
HREF="kde-default.css"
TYPE="text/css"
TITLE="KDE-Default"/></HEAD
><BODY
CLASS="section"
LINK="#336699"
VLINK="#336699"
ALINK="#336699"
BGCOLOR="#FFFFFF"
><DIV
ALIGN="RIGHT"
CLASS="NAVBAR"
><P
><A
HREF="ch07.html"
>Prev</A
> <A
HREF="ch07lev1sec3.html"
>Next</A
> <A
HREF="index.html"
>Table of Contents</A
></P
></DIV
><DIV
CLASS="section"
><TABLE
WIDTH="100%"
CELLPADDING="0"
CELLSPACING="0"
BORDER="0"
ALIGN="CENTER"
><TR
><TD
WIDTH="90%"
><H1
CLASS="section"
><A
NAME="ch07lev1sec2"
>7.2. Application Configuration Information</A
></H1
><P
>Configuration information for KDE applications is stored in human-readable text files in a standard format. An example is shown in <A
HREF="ch07lev1sec2.html#ch07list07"
>Listing 7.7</A
>. Applications generally store user settings, such as the name of a mail server or the number of times to try connecting to a site before giving up and user preferences for things such as UI layout and colors. The files are stored as human-readable text so that users and administrators can read and modify these files with any text editor. These files offer advantages over the binary-format configuration files used on some other systems:</P
><UL
COMPACT="COMPACT"
><LI
STYLE="list-style-type: disc"
><P
>You can automate configuration and reconfiguration (from scripts, for example).</P
></LI
><LI
STYLE="list-style-type: disc"
><P
>The files are safer from corruption. Having a few small errors in a file such as the one in <A
HREF="ch07lev1sec2.html#ch07list07"
>Listing 7.7</A
> is unlikely to make it unreadable to a human. The human can correct these errors so that the application can read the file. Small errors in a compact, binary format may destroy information and make the file unusable by the application.</P
></LI
></UL
><P
>KDE configuration files store information as Key, Value pairs as shown in <A
HREF="ch07lev1sec2.html#ch07list07"
>Listing 7.7</A
> One pair appears per line.</P
><DIV
CLASS="example"
><HR/><A
NAME="ch07list07"
></A
><P
><B
>Example 7.7. A Sample KDE Application Configuration File</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="programlisting"
>   1&nbsp;
   2&nbsp;1: #KDE Config File
   3&nbsp;2: DefaultHeight=300
   4&nbsp;3: [Options]
   5&nbsp;4: BackgroundColor=255,255,255
   6&nbsp;5: ForegroundColor=100,100,255
   7&nbsp;</PRE
></TD
></TR
></TABLE
><HR/></DIV
><P
>The pairs can be grouped to help organize the information for the application or to make the file more readable. Group names appear in brackets alone on a line preceding the group they label (line 3). </P
><P
>The files can also include comments. Comments appear on lines starting with a <TT
CLASS="literal"
># (line 1)</TT
>.</P
><P
>KDE  configuration files are stored in .kde/share/config in the user's home directory. Each application creates a configuration file called <I
CLASS="emphasis"
>kappnamerc</I
>, where <I
CLASS="emphasis"
>kappname</I
> is the name of the application. For example, knotes creates knotesrc.</P
><DIV
CLASS="section"
><TABLE
WIDTH="100%"
CELLPADDING="0"
CELLSPACING="0"
BORDER="0"
ALIGN="CENTER"
><TR
><TD
WIDTH="90%"
><H2
CLASS="section"
><A
NAME="ch07lev2sec3"
>7.2.1. Accessing Configuration Files</A
></H2
><P
>Configuration files are read and written with the <TT
CLASS="literal"
>KConfig</TT
> class. The default configuration file, <I
CLASS="emphasis"
>kappnamerc</I
>, can be accessed with the <TT
CLASS="literal"
>KConfig</TT
> object returned by the method <TT
CLASS="literal"
>KApplication::config()</TT
>. You typically access this object with <TT
CLASS="literal"
>kapp-&gt;config()</TT
>. (<TT
CLASS="literal"
>kapp</TT
> is a macro defined in kapp.h that returns a pointer to the current <TT
CLASS="literal"
>KApplication</TT
> object. A KDE application uses only one <TT
CLASS="literal"
>KApplication</TT
> object; therefore, <TT
CLASS="literal"
>kapp</TT
> can reliably be used from any source-code file that is part of your application.)</P
><P
><A
HREF="ch07lev1sec2.html#ch07list08"
>Listings 7.8</A
> and <A
HREF="ch07lev1sec2.html#ch07list09"
>7.9</A
> show the code for <TT
CLASS="literal"
>KConfigDemo</TT
>, a widget that demonstrates the use of <TT
CLASS="literal"
>KConfig</TT
>.</P
><DIV
CLASS="example"
><HR/><A
NAME="ch07list08"
></A
><P
><B
>Example 7.8. kconfigdemo.h: Class Declaration for <TT
CLASS="literal"
>KConfigDemo</TT
>, a widget that demonstrates <TT
CLASS="literal"
>KConfig</TT
></B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="programlisting"
>   1&nbsp;
   2&nbsp; 1: #ifndef __KCONFIGDEMO_H__
   3&nbsp; 2: #define __KCONFIGDEMO_H__
   4&nbsp; 3:
   5&nbsp; 4: #include &lt;qlineedit.h&gt;
   6&nbsp; 5:
   7&nbsp; 6: /**
   8&nbsp; 7:  * KConfigDemo
   9&nbsp; 8:  * Show how to access KDE configuration files with KConfig.
  10&nbsp; 9:  **/
  11&nbsp;10: class KConfigDemo : public QLineEdit
  12&nbsp;11: {
  13&nbsp;12:  public:
  14&nbsp;13:   KConfigDemo ();
  15&nbsp;14:
  16&nbsp;15:  protected:
  17&nbsp;16:   void closeEvent (QCloseEvent *qcloseevent);
  18&nbsp;17:
  19&nbsp;18: };
  20&nbsp;19:
  21&nbsp;20: #endif
  22&nbsp;</PRE
></TD
></TR
></TABLE
><HR/></DIV
><P
><TT
CLASS="literal"
>KConfigDemo</TT
> is a line editor widget that saves its text in a configuration file when the user closes the window, and it reloads it the next time the program is run.</P
><P
><TT
CLASS="literal"
>KConfigDemo</TT
> is subclassed from <TT
CLASS="literal"
>QLineEdit</TT
>, which does most of the work for you. You just need to add the configuration file access.</P
><DIV
CLASS="example"
><HR/><A
NAME="ch07list09"
></A
><P
><B
>Example 7.9. kconfigdemo.cpp: Class Definition for <TT
CLASS="literal"
>KConfigDemo</TT
></B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="programlisting"
>   1&nbsp;
   2&nbsp; 1: #include &lt;kapp.h&gt;
   3&nbsp; 2: #include &lt;kconfig.h&gt;
   4&nbsp; 3:
   5&nbsp; 4: #include "kconfigdemo.h"
   6&nbsp; 5:
   7&nbsp; 6: KConfigDemo::KConfigDemo () : QLineEdit (0)
   8&nbsp; 7: {
   9&nbsp; 8:   kapp-&gt;config()-&gt;setGroup ("LineEditor");
  10&nbsp; 9:   setText (kapp-&gt;config()-&gt;readEntry ("Text", "Hello"));
  11&nbsp;10: }
  12&nbsp;11:
  13&nbsp;12: void
  14&nbsp;13: KConfigDemo::closeEvent (QCloseEvent *qcloseevent)
  15&nbsp;14: {
  16&nbsp;15:   kapp-&gt;config()-&gt;setGroup ("LineEditor");
  17&nbsp;16:   kapp-&gt;config()-&gt;writeEntry ("Text", text());
  18&nbsp;17:   kapp-&gt;config()-&gt;sync();
  19&nbsp;18:
  20&nbsp;19:   qcloseevent-&gt;accept();
  21&nbsp;20: }</PRE
></TD
></TR
></TABLE
><HR/></DIV
><P
>In the constructor, you look in the group <TT
CLASS="literal"
>LineEditor</TT
> (line 8) for the key <TT
CLASS="literal"
>Text</TT
> (line 9). (Note: If you had not specified a group with <TT
CLASS="literal"
>setGroup()</TT
>, the Key, Value pair would have been written to the default, unnamed group.) <TT
CLASS="literal"
>readEntry()</TT
> returns the value found to the right of <TT
CLASS="literal"
>Text=</TT
> in the configuration file as a <TT
CLASS="literal"
>QString</TT
>. In the event that the key <TT
CLASS="literal"
>Text</TT
> does not appear at all&#8212;as is the case when the program is run for the first time&#8212;<TT
CLASS="literal"
>readEntry()</TT
> returns <TT
CLASS="literal"
>Hello</TT
>, the value specified as the default (line 9).</P
><P
>You want to save the text when the user closes the window. To do this, reimplement the virtual method <TT
CLASS="literal"
>closeEvent()</TT
>. This method is called when a close request is made, but before the window is actually closed. In this method, place the text of the widget (returned by <TT
CLASS="literal"
>text()</TT
>) to the configuration file into the group <TT
CLASS="literal"
>LineEditor</TT
>. The call on line 17 is very important. This call actually writes the new configuration information to disk.</P
><DIV
CLASS="note"
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="note.png"
HSPACE="5"
ALT="Note"/></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
><TT
CLASS="literal"
>KConfig</TT
> caches the information in memory until the method <TT
CLASS="literal"
>KConfig::sync()</TT
> is called, so be sure to call it before your application exits or else your settings will be lost.</P
></TD
></TR
></TABLE
></DIV
><P
>Finally, call <TT
CLASS="literal"
>qcloseevent-&gt;accept()</TT
>, which lets Qt know that the widget is willing to grant the user's request and be closed.</P
><P
><A
HREF="ch07lev1sec2.html#ch07list10"
>Listing 7.10</A
> is for a <TT
CLASS="literal"
>main()</TT
> function that you can use to test <TT
CLASS="literal"
>KConfigDemo</TT
>. <A
HREF="ch07lev1sec2.html#ch07fig03"
>Figure 7.3</A
> shows the program that is created&#8212;kconfigdemotest&#8212;running.</P
><DIV
CLASS="example"
><HR/><A
NAME="ch07list10"
></A
><P
><B
>Example 7.10. main.cpp: A <TT
CLASS="literal"
>main()</TT
> Function Suitable for Testing <TT
CLASS="literal"
>KConfigDemo</TT
></B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="programlisting"
>   1&nbsp;
   2&nbsp; 1: #include &lt;kapp.h&gt;
   3&nbsp; 2:
   4&nbsp; 3: #include "kconfigdemo.h"
   5&nbsp; 4:
   6&nbsp; 5: int
   7&nbsp; 6: main (int argc, char *argv[])
   8&nbsp; 7: {
   9&nbsp; 8:   KApplication kapplication (argc, argv, "kconfigdemotest");
  10&nbsp; 9:
  11&nbsp;10:   KConfigDemo *kconfigdemo = new KConfigDemo;
  12&nbsp;11:
  13&nbsp;12:   kapplication.setMainWidget (kconfigdemo);
  14&nbsp;13:
  15&nbsp;14:   kconfigdemo-&gt;show();
  16&nbsp;15:   return kapplication.exec();
  17&nbsp;16: } </PRE
></TD
></TR
></TABLE
><HR/></DIV
><P
><TT
CLASS="literal"
>KConfig</TT
> can read and write many types of data, not just strings. For example, in the next section you read and write a <TT
CLASS="literal"
>QFont</TT
>. The supported types are listed in the documentation (and header file) for <TT
CLASS="literal"
>KConfigBase</TT
>.</P
><DIV
CLASS="figure"
><HR/><A
NAME="ch07fig03"
></A
><P
><B
>Figure 7.3. KConfigDemo saves the text you enter in its configuration file.</B
></P
><DIV
CLASS="mediaobject"
><P
><IMG
SRC="graphics/07fig03.gif"
></IMG
></P
></DIV
><HR/></DIV
></TD
><TD
WIDTH="10%"
VALIGN="BOTTOM"
ALIGN="CENTER"
><ANNMARK
NAME="ch07lev2sec3"/></TD
></TR
><ANNOTATION
NAME="ch07lev2sec3"
TITLE="Accessing Configuration Files"/></TABLE
></DIV
></TD
><TD
WIDTH="10%"
VALIGN="BOTTOM"
ALIGN="CENTER"
><ANNMARK
NAME="ch07lev1sec2"/></TD
></TR
><ANNOTATION
NAME="ch07lev1sec2"
TITLE="Application Configuration Information"/></TABLE
></DIV
><DIV
ALIGN="RIGHT"
CLASS="NAVBAR"
><P
><A
HREF="ch07.html"
>Prev</A
> <A
HREF="ch07lev1sec3.html"
>Next</A
> <A
HREF="index.html"
>Table of Contents</A
></P
></DIV
><HR
WIDTH="100%"
SIZE="2"
ALIGN="CENTER"
NOSHADE="NOSHADE"/></BODY
></HTML
>