File: ch07lev1sec3.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 (503 lines) | stat: -rw-r--r-- 12,506 bytes
parent folder | download | duplicates (2)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>Session Management</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="Application Configuration Information"
HREF="ch07lev1sec2.html"/><LINK
REL="NEXT"
TITLE="Application Resources"
HREF="ch07lev1sec4.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="ch07lev1sec2.html"
>Prev</A
> <A
HREF="ch07lev1sec4.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="ch07lev1sec3"
>7.3. Session Management</A
></H1
><P
>We  touched on session management in <A
HREF="ch02.html"
>Chapter 2 <SPAN
CLASS="QUOTE"
>"A Simple KDE Application."</SPAN
></A
> You created <TT
CLASS="literal"
>KSimpleApp</TT
> and endowed it with the capability to be restarted and maintain its position and size across sessions. (<I
CLASS="emphasis"
>Session</I
> refers to the time between logging in and logging out.) Actually, this functionality was provided by <TT
CLASS="literal"
>KTMainWindow</TT
> from which the class <TT
CLASS="literal"
>KSimpleApp</TT
> was derived.</P
><P
>In general, you'll want to save more information across sessions than just the window position and size. <TT
CLASS="literal"
>KTMainWindow</TT
> offers the virtual methods <TT
CLASS="literal"
>saveProperties()</TT
> and <TT
CLASS="literal"
>readProperties()</TT
> for this purpose. Also, you will want to save the user's data (or at least offer this option) before a session exits. You reimplement the virtual method <TT
CLASS="literal"
>queryClose()</TT
> to do this. Listings 7.11&#8211;7.13 show the source code for KSaveAcross, an application that demonstrates these features.</P
><DIV
CLASS="example"
><HR/><A
NAME="ch07list11"
></A
><P
><B
>Example 7.11. ksaveacross.h: Class Declaration for <TT
CLASS="literal"
>KSaveAcross</TT
>, a Widget That Demonstrates Session Management Features of <TT
CLASS="literal"
>KTMainWindow</TT
></B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="programlisting"
>   1&nbsp;
   2&nbsp; 1: #ifndef __KSAVEACROSS_H__
   3&nbsp; 2: #define __KSAVEACROSS_H__
   4&nbsp; 3:
   5&nbsp; 4: #include &lt;ktmainwindow.h&gt;
   6&nbsp; 5:
   7&nbsp; 6: /**
   8&nbsp; 7:  * KSaveAcross
   9&nbsp; 8:  * This application saves its data across sessions. Its data is
  10&nbsp; 9:  *  the contents of a QLineEdit.
  11&nbsp;10:  **/ 
  12&nbsp;11: class KSaveAcross : public KTMainWindow
  13&nbsp;12: {
  14&nbsp;13:  Q_OBJECT
  15&nbsp;14:  public:
  16&nbsp;15:   KSaveAcross (const char *name=0);
  17&nbsp;16:
  18&nbsp;17:  public slots:
  19&nbsp;18:    /**
  20&nbsp;19:     * Change the font used by qlineedit.
  21&nbsp;20:     **/
  22&nbsp;21:   void slotChangeFont();
  23&nbsp;22:
  24&nbsp;23:  protected:
  25&nbsp;24:   QLineEdit *qlineedit;
  26&nbsp;25:
  27&nbsp;26:   /**
  28&nbsp;27:    * Ask the user if he/she wants to save the document.
  29&nbsp;28:    **/
  30&nbsp;29:   bool queryClose();
  31&nbsp;30:
  32&nbsp;31:   /**
  33&nbsp;32:    * Save the chosen font.
  34&nbsp;33:    **/
  35&nbsp;34:   void saveProperties (KConfig *kconfig);
  36&nbsp;35:   /**
  37&nbsp;36:    * Read the chosen font.
  38&nbsp;37:    **/
  39&nbsp;38:   void readProperties (KConfig *kconfig);
  40&nbsp;39:
  41&nbsp;40: };
  42&nbsp;41:
  43&nbsp;42: #endif</PRE
></TD
></TR
></TABLE
><HR/></DIV
><P
>The content area of the <TT
CLASS="literal"
>KSaveAcross</TT
> widget is a <TT
CLASS="literal"
>QLineEdit</TT
> widget. The menubar offers two choices: change the font used by the <TT
CLASS="literal"
>QLineEdit</TT
> widget or quit the application. The font chosen by the user is saved across sessions.</P
><DIV
CLASS="example"
><HR/><A
NAME="ch07list12"
></A
><P
><B
>Example 7.12. ksaveacross.cpp: Class Definition for <TT
CLASS="literal"
>KSaveAcross</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;kfontdialog.h&gt;
   4&nbsp; 3: #include &lt;kstdaction.h&gt;
   5&nbsp; 4: #include &lt;kaction.h&gt;
   6&nbsp; 5: #include &lt;kmessagebox.h&gt;
   7&nbsp; 6: #include &lt;kconfig.h&gt;
   8&nbsp; 7:
   9&nbsp; 8: #include "ksaveacross.moc"
  10&nbsp; 9:
  11&nbsp;10:
  12&nbsp;11: KSaveAcross::KSaveAcross (const char *name)
  13&nbsp;12: {
  14&nbsp;13:   KStdAction::quit (kapp, SLOT (closeAllWindows()),
  15&nbsp;14:                actionCollection());
  16&nbsp;15:
  17&nbsp;16:   new KAction ("Change Font&#8230;", 0, this, SLOT(slotChangeFont()),
  18&nbsp;17:           actionCollection(), "change_font");
  19&nbsp;18:   createGUI();
  20&nbsp;19:
  21&nbsp;20:   qlineedit = new QLineEdit (this);
  22&nbsp;21:
  23&nbsp;22:   setView (qlineedit);
  24&nbsp;23: }
  25&nbsp;24:
  26&nbsp;25: void
  27&nbsp;26: KSaveAcross::slotChangeFont()
  28&nbsp;27: {
  29&nbsp;28:   QFont qfont = qlineedit-&gt;font();
  30&nbsp;29:
  31&nbsp;30:   if (KFontDialog::getFont (qfont))
  32&nbsp;31:     qlineedit-&gt;setFont(qfont);
  33&nbsp;32: }
  34&nbsp;33:
  35&nbsp;34: bool
  36&nbsp;35: KSaveAcross::queryClose()
  37&nbsp;36: {
  38&nbsp;37:  
  39&nbsp;38:
  40&nbsp;39:   const int yes=0, no=1, cancel=2;
  41&nbsp;40:   int yesnocancel;
  42&nbsp;41:
  43&nbsp;42:   yesnocancel =
  44&nbsp;43:     KMessageBox::
  45&nbsp;44:     questionYesNo (this, "Save changes to document?", "ksaveacross");
  46&nbsp;45:
  47&nbsp;46:   switch (yesnocancel)
  48&nbsp;47:     {
  49&nbsp;48:     case (yes):
  50&nbsp;49:       //You would save the document here and let the application exit.
  51&nbsp;50:       return true;
  52&nbsp;51:     case (no):
  53&nbsp;52:       //Let the application exit without saving the document.
  54&nbsp;53:       return true;
  55&nbsp;54:     case (cancel):
  56&nbsp;55:       //Don't save, but don't let the application exit.
  57&nbsp;56:       return false;
  58&nbsp;57:     }
  59&nbsp;58: }
  60&nbsp;59:
  61&nbsp;60:
  62&nbsp;61: void
  63&nbsp;62: KSaveAcross::saveProperties (KConfig *kconfig)
  64&nbsp;63: {
  65&nbsp;64:   kconfig-&gt;writeEntry ("LineEditorFont", qlineedit-&gt;font());
  66&nbsp;65:   kconfig-&gt;sync();
  67&nbsp;66: }
  68&nbsp;67:
  69&nbsp;68: void
  70&nbsp;69: KSaveAcross::readProperties (KConfig *kconfig)
  71&nbsp;70: {
  72&nbsp;71:   qlineedit-&gt;setFont (kconfig-&gt;readFontEntry ("LineEditorFont"));
  73&nbsp;72: }</PRE
></TD
></TR
></TABLE
><HR/></DIV
><P
>The method <TT
CLASS="literal"
>saveProperties()</TT
> (lines 61&#8211;66) is called just before the application is terminated by the session manager. If the user quits the application normally, the method is not called. When the session manager restarts the application at the beginning of the next session, the method <TT
CLASS="literal"
>readProperties()</TT
> is called. In these methods, you should save and read in properties that describe the current state of the application but that may not be saved in or specified in the configuration file. A Web browser, for example, might save the URL of the current page in the method <TT
CLASS="literal"
>saveProperties()</TT
>, although it wouldn't want to store this in the configuration file.</P
><P
><TT
CLASS="literal"
>saveProperties()</TT
> and <TT
CLASS="literal"
>readProperties()</TT
> work with <TT
CLASS="literal"
>KConfig</TT
> objects. These <TT
CLASS="literal"
>KConfig</TT
> objects do not operate on the default application configuration file. Instead, they operate on instance-specific configuration files created solely for the purpose of saving this session. The reading and writing methods were described in the previous section. Don't forget to call <TT
CLASS="literal"
>kconfig-&gt;sync()</TT
> (line 65) at the end of <TT
CLASS="literal"
>saveProperties()</TT
> to write the information to disk.</P
><P
>Before the application exits, it should ask the user whether he or she wishes to save the current document. If the application does this in the method <TT
CLASS="literal"
>queryClose()</TT
> (a virtual method of the class <TT
CLASS="literal"
>KTMainWindow</TT
>), the question is asked whether the application is closed by the user or by the session manager.</P
><P
>If <TT
CLASS="literal"
>queryClose()</TT
> returns <TT
CLASS="literal"
>3false</TT
>, the application does not exit. The reimplementation of <TT
CLASS="literal"
>queryClose()</TT
> in <TT
CLASS="literal"
>KSaveAcross</TT
> (line 34&#8211;58) presents the user with the choices Yes, No, and Cancel as answers to the question, <SPAN
CLASS="QUOTE"
>"Save changes to document?"</SPAN
> If the user answers Yes or No, <TT
CLASS="literal"
>queryClose()</TT
> returns <TT
CLASS="literal"
>true</TT
>, letting the application exit. If the user chooses Cancel, <TT
CLASS="literal"
>queryClose()</TT
> returns <TT
CLASS="literal"
>false</TT
> and the user can continue working.</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
>You'll need to create a file called ksaveacrossui.rc and place it in the directory $KDEDIR/share/apps/ksaveacross as explained in <A
HREF="ch05.html"
>Chapter 5, <SPAN
CLASS="QUOTE"
>"KDE User Interface Compliance"</SPAN
></A
>. A usable version of ksaveacrossui.rc is included with the code on this book's Web site.</P
></TD
></TR
></TABLE
></DIV
><P
><A
HREF="ch07lev1sec3.html#ch07list13"
>Listing 7.13</A
> provides the <TT
CLASS="literal"
>main()</TT
> function needed to create and start this application. Notice that I have included the session management code (lines 9&#8211;15), which was discussed in <A
HREF="ch02.html"
>Chapter 2</A
>. <A
HREF="ch07lev1sec3.html#ch07fig04"
>Figure 7.4</A
> shows running KSaveAcross.</P
><P
>To create an executable, you'll need the code in <A
HREF="ch07lev1sec3.html#ch07list13"
>Listing 7.13</A
>, and you'll need to place the GUI file, ksaveacrossui.rc (found on this book's web site), in  the directory $KDEDIR/share/ kstatusbardemo.</P
><DIV
CLASS="example"
><HR/><A
NAME="ch07list13"
></A
><P
><B
>Example 7.13. main.cpp: A <TT
CLASS="literal"
>main()</TT
> Function Suitable for Testing <TT
CLASS="literal"
>KSaveAcross</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 "ksaveacross.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, "ksaveacross");
  10&nbsp; 9:
  11&nbsp;10:   if (kapplication.isRestored())
  12&nbsp;11:       RESTORE(KSaveAcross)
  13&nbsp;12:   else
  14&nbsp;13:   {
  15&nbsp;14:     KSaveAcross *ksaveacross = new KSaveAcross;
  16&nbsp;15:     ksaveacross-&gt;show();
  17&nbsp;16:   }
  18&nbsp;17:
  19&nbsp;18:   return kapplication.exec();
  20&nbsp;19: }</PRE
></TD
></TR
></TABLE
><HR/></DIV
><DIV
CLASS="figure"
><HR/><A
NAME="ch07fig04"
></A
><P
><B
>Figure 7.4. KSaveAcross saves its options across sessions and offers to save the user's data before it is closed.</B
></P
><DIV
CLASS="mediaobject"
><P
><IMG
SRC="graphics/07fig04.gif"
></IMG
></P
></DIV
><HR/></DIV
></TD
><TD
WIDTH="10%"
VALIGN="BOTTOM"
ALIGN="CENTER"
><ANNMARK
NAME="ch07lev1sec3"/></TD
></TR
><ANNOTATION
NAME="ch07lev1sec3"
TITLE="Session Management"/></TABLE
></DIV
><DIV
ALIGN="RIGHT"
CLASS="NAVBAR"
><P
><A
HREF="ch07lev1sec2.html"
>Prev</A
> <A
HREF="ch07lev1sec4.html"
>Next</A
> <A
HREF="index.html"
>Table of Contents</A
></P
></DIV
><HR
WIDTH="100%"
SIZE="2"
ALIGN="CENTER"
NOSHADE="NOSHADE"/></BODY
></HTML
>