1 files changed, 124 insertions, 41 deletions

diff --git a/library/global.cpp b/library/global.cpp
index ab27b3f..7438891 100644
--- a/library/global.cpp
+++ b/library/global.cpp
@@ -1,7 +1,7 @@
 /**********************************************************************
-** Copyright (C) 2000 Trolltech AS.  All rights reserved.
+** Copyright (C) 2000-2002 Trolltech AS.  All rights reserved.
 **
-** This file is part of Qtopia Environment.
+** This file is part of the Qtopia Environment.
 **
 ** This file may be distributed and/or modified under the terms of the
 ** GNU General Public License version 2 as published by the Free Software
@@ -45,7 +45,9 @@
 #include <fcntl.h>
 #include <unistd.h>
 
+#ifdef QWS
 #include <qwindowsystem_qws.h> // for qwsServer
+#endif
 #include <qdatetime.h>
 
 #include <qfile.h>
@@ -56,7 +58,7 @@ namespace {
     QFile file(path );
     if(!file.open(IO_ReadOnly ) )
        return true;
-    
+
     QByteArray array = file.readAll();
     QStringList list = QStringList::split('\n', QString( array ) );
     for(QStringList::Iterator it = list.begin(); it != list.end(); ++it ){
@@ -108,11 +110,13 @@ StartingAppList* StartingAppList::appl = 0;
 StartingAppList::StartingAppList( QObject *parent, const char* name )
     :QObject( parent, name )
 {
+#ifdef QWS
 #if QT_VERSION >= 232 && !defined(QT_NO_COP)
     connect( qwsServer, SIGNAL( newChannel(const QString&)),
              this, SLOT( handleNewChannel(const QString&)) );
     dict.setAutoDelete( TRUE );
 #endif
+#endif
 }
 
 void StartingAppList::add( const QString& name )
@@ -169,7 +173,55 @@ static QString dictDir()
 
 /*!
   \class Global global.h
-  \brief The Global class collects application-wide global functions.
+  \brief The Global class provides application-wide global functions.
+
+  The Global functions are grouped as follows:
+  \tableofcontents
+
+  \section1 User Interface
+
+  The statusMessage() function provides short-duration messages to the
+  user. The showInputMethod() function shows the current input method,
+  and hideInputMethod() hides the input method.
+
+  \section1 Document related
+
+  The findDocuments() function creates a set of \link doclnk.html
+  DocLnk\endlink objects in a particular folder.
+
+  \section1 Filesystem related
+
+  Global provides an applicationFileName() function that returns the
+  full path of an application-specific file.
+
+  The execute() function runs an application.
+
+  \section1 Word list related
+
+  A list of words relevant to the current locale is maintained by the
+  system. The list is held in a \link qdawg.html DAWG\endlink
+  (implemented by the QDawg class). This list is used, for example, by
+  the pickboard input method.
+
+  The global QDawg is returned by fixedDawg(); this cannot be updated.
+  An updatable copy of the global QDawg is returned by addedDawg().
+  Applications may have their own word lists stored in \l{QDawg}s
+  which are returned by dawg(). Use addWords() to add words to the
+  updateable copy of the global QDawg or to named application
+  \l{QDawg}s.
+
+  \section1 Quoting
+
+  The shellQuote() function quotes a string suitable for passing to a
+  shell. The stringQuote() function backslash escapes '\' and '"'
+  characters.
+
+  \section1 Hardware
+
+  The writeHWClock() function sets the hardware clock to the system
+  clock's date and time.
+
+  \ingroup qtopiaemb
 */
 
 /*!
@@ -252,7 +304,7 @@ const QDawg& Global::dawg(const QString& name)
     if ( !r ) {
         r = new QDawg;
         named_dawg->insert(name,r);
-        QString dawgfilename = dictDir() + "/" + name + ".dawg";
+        QString dawgfilename = applicationFileName("Dictionary", name ) + ".dawg";
         QFile dawgfile(dawgfilename);
         if ( dawgfile.open(IO_ReadOnly) )
             r->readFile(dawgfilename);
@@ -261,7 +313,12 @@ const QDawg& Global::dawg(const QString& name)
 }
 
 /*!
+  \overload
   Adds \a wordlist to the addedDawg().
+
+  Note that the addition of words persists between program executions
+  (they are saved in the dictionary files), so you should confirm the
+  words with the user before adding them.
 */
 void Global::addWords(const QStringList& wordlist)
 {
@@ -269,7 +326,12 @@ void Global::addWords(const QStringList& wordlist)
 }
 
 /*!
-  Adds \a wordlist to the dawg() named \a dictname.
+  \overload
+  Adds \a wordlist to the addedDawg().
+
+  Note that the addition of words persists between program executions
+  (they are saved in the dictionary files), so you should confirm the
+  words with the user before adding them.
 */
 void Global::addWords(const QString& dictname, const QStringList& wordlist)
 {
@@ -277,7 +339,7 @@ void Global::addWords(const QString& dictname, const QStringList& wordlist)
     QStringList all = d.allWords() + wordlist;
     d.createFromWords(all);
 
-    QString dawgfilename = dictDir() + "/" + dictname + ".dawg";
+    QString dawgfilename = applicationFileName("Dictionary", dictname) + ".dawg";
     QFile dawgfile(dawgfilename);
     if ( dawgfile.open(IO_WriteOnly) ) {
         d.write(&dawgfile);
@@ -291,11 +353,11 @@ void Global::addWords(const QString& dictname, const QStringList& wordlist)
 
 
 /*!
-  Returns a full path for the application named \a appname, with the
-  given \a filename or QString::null if there was a problem creating
-  the directory tree for \a appname.  
-  If \a filename contains "/", it is the caller's responsibility to 
-  ensure those directories exist.
+  Returns the full path for the application called \a appname, with the
+  given \a filename. Returns QString::null if there was a problem creating
+  the directory tree for \a appname.
+  If \a filename contains "/", it is the caller's responsibility to
+  ensure that those directories exist.
 */
 QString Global::applicationFileName(const QString& appname, const QString& filename)
 {
@@ -326,8 +388,8 @@ void Global::createDocDir()
 
 
 /*!
-  Displays a status \a message to the user. This generally appears
-  in the taskbar for some amount of time, then disappears.
+  Displays a status \a message to the user. This usually appears
+  in the taskbar for a short amount of time, then disappears.
 */
 void Global::statusMessage(const QString& message)
 {
@@ -373,6 +435,13 @@ QWidget *Global::restart( bool )
 
 /*!
   Explicitly show the current input method.
+
+  Input methods are indicated in the taskbar by a small icon. If the
+  input method is activated (shown) then it takes up some proportion
+  of the bottom of the screen, to allow the user to interact (input
+  characters) with it.
+
+  \sa hideInputMethod()
 */
 void Global::showInputMethod()
 {
@@ -383,6 +452,11 @@ void Global::showInputMethod()
 
 /*!
   Explicitly hide the current input method.
+
+  The current input method is still indicated in the taskbar, but no
+  longer takes up screen space, and can no longer be interacted with.
+
+  \sa showInputMethod()
 */
 void Global::hideInputMethod()
 {
@@ -465,16 +539,22 @@ void Global::terminate( const AppLnk* app )
 {
     //if ( terminateBuiltin(app->exec()) ) return; // maybe? haven't tried this
 
+#ifndef QT_NO_COP
     QCString channel = "QPE/Application/" + app->exec().utf8();
     if ( QCopChannel::isRegistered(channel) ) {
         QCopEnvelope e(channel, "quit()");
     }
+#endif
 }
 
 /*!
-  Low-level function to run command \a c. Not recommended.
+  Low-level function to run command \a c.
+
+  \warning Do not use this function. Use execute instead.
+
+  \sa execute()
 */
-void Global::invoke(const QString &c) 
+void Global::invoke(const QString &c)
 {
     // Convert the command line in to a list of arguments
     QStringList list = QStringList::split(QRegExp("  *"),c);
@@ -482,13 +562,13 @@ void Global::invoke(const QString &c)
 #if defined(Q_WS_QWS) && !defined(QT_NO_COP)
     QString ap=list[0];
     // see if the application is already running
-    // XXX should lock file /tmp/qcop-msg-ap 
+    // XXX should lock file /tmp/qcop-msg-ap
     if ( QCopChannel::isRegistered( ("QPE/Application/" + ap).latin1() ) ) {
         QCopEnvelope e("QPE/System", "notBusy(QString)" );
         e << ap;
         return;
     }
-    // XXX should unlock file /tmp/qcop-msg-ap 
+    // XXX should unlock file /tmp/qcop-msg-ap
     //see if it is being started
     if ( StartingAppList::isStarting( ap ) ) {
         QCopEnvelope e("QPE/System", "notBusy(QString)" );
@@ -524,7 +604,7 @@ void Global::invoke(const QString &c)
     if ( QFile::exists( libexe ) ) {
         qDebug("calling quickexec %s", libexe.latin1() );
         quickexecv( libexe.utf8().data(), (const char **)args );
-    } else 
+    } else
 #endif
     {
         if ( !::vfork() ) {
@@ -541,11 +621,13 @@ void Global::invoke(const QString &c)
 #endif //QT_NO_QWS_MULTIPROCESS
 }
 
+
 /*!
-  Executes application identfied by \a c, passing \a document.
+  Executes the application identfied by \a c, passing \a
+  document if it isn't null.
 
-  Note that you might be better off sending a QCop message to
-  the application's QPE/Application/<i>appname</i> channel.
+  Note that a better approach might be to send a QCop message to the
+  application's QPE/Application/\e{appname} channel.
 */
 void Global::execute( const QString &c, const QString& document )
 {
@@ -577,8 +659,10 @@ void Global::execute( const QString &c, const QString& document )
                 } else {
                     running[i] = builtin[i].func( builtin[i].maximized );
                 }
+#ifndef QT_NO_COP
                 QCopEnvelope e("QPE/System", "notBusy(QString)" );
                 e << c; // that was quick ;-)
+#endif
                 return;
             }
         }
@@ -594,13 +678,14 @@ void Global::execute( const QString &c, const QString& document )
 
     qDebug("executing %s", ap.latin1() );
     if ( ap == "suspend" ) {
-                QWSServer::sendKeyEvent( 0xffff, Qt::Key_F34, FALSE, TRUE, FALSE );
+        QWSServer::sendKeyEvent( 0xffff, Qt::Key_F34, FALSE, TRUE, FALSE );
         return;
     }
 
-    /* if need be, sending a qcop message will result in an invoke, see 
+    /* if need be, sending a qcop message will result in an invoke, see
        preceeding function */
-    { QCopEnvelope env( ("QPE/Application/" + ap).latin1(), "raise()" ); }
+    invoke( ap );
+    //{ QCopEnvelope env( ("QPE/Application/" + ap).latin1(), "raise()" ); }
     if ( !document.isEmpty() ) {
         QCopEnvelope env( ("QPE/Application/" + ap).latin1(), "setDocument(QString)" );
         env << document;
@@ -609,8 +694,10 @@ void Global::execute( const QString &c, const QString& document )
 }
 
 /*!
-  Returns the string \a s with the characters backslash, ", and $
-  quoted by a preceeding backslash.
+  Returns the string \a s with the characters '\', '"', and '$' quoted
+  by a preceeding '\'.
+
+  \sa stringQuote()
 */
 QString Global::shellQuote(const QString& s)
 {
@@ -628,8 +715,10 @@ QString Global::shellQuote(const QString& s)
 }
 
 /*!
-  Returns the string \a s with the characters backslash and "
-  quoted by a preceeding backslash.
+  Returns the string \a s with the characters '\' and '"' quoted by a
+  preceeding '\'.
+
+  \sa shellQuote()
 */
 QString Global::stringQuote(const QString& s)
 {
@@ -661,8 +750,8 @@ void Global::findDocuments(DocLnkSet* folder, const QString &mimefilter)
      *  b) the user wants to check but use the global options for it
      *  c) the user wants to check it but not this medium
      *  d) the user wants to check and this medium as well
-     * 
-     *  In all cases we need to apply a different mimefilter to 
+     *
+     *  In all cases we need to apply a different mimefilter to
      *  the medium.
      *  a) mimefilter.isEmpty() we need to apply the responding filter
      *     either the global or the one on the medium
@@ -675,7 +764,7 @@ void Global::findDocuments(DocLnkSet* folder, const QString &mimefilter)
     QListIterator<FileSystem> it ( fs );
     for ( ; it.current(); ++it ) {
       if ( (*it)->isRemovable() ) { // let's find out  if we should search on it
-        // this is a candidate look at the cf and see if we should search on it 
+        // this is a candidate look at the cf and see if we should search on it
         QString path = (*it)->path();
         if( !checkStorage((*it)->path() + "/.opiestorage.cf" ) )
           continue;
@@ -713,16 +802,10 @@ QStringList Global::helpPath()
             path += QPEApplication::qpeDir() + "/help/" + lang + "/html";
     }
     path += QPEApplication::qpeDir() + "/pics";
-    path += QPEApplication::qpeDir() + "/help/en/html";
+    path += QPEApplication::qpeDir() + "/help/html";
     path += QPEApplication::qpeDir() + "/docs";
-    QString dir = QDir::current().canonicalPath();
-    if ( dir == "/" )
-        dir += "/docs";
-    else {
-        path += dir + "/../pics";
-        dir += "/../docs";
-        path += dir;
-    }
+
+
     return path;
 }