Qtopia1-6 merge

still to test
bic changes to be resolved
more changes to be made?

1 files changed, 112 insertions, 29 deletions

diff --git a/library/global.cpp b/library/global.cpp
index ab27b3f..7438891 100644
--- a/library/global.cpp
+++ b/library/global.cpp
@@ -1,5 +1,5 @@
 /**********************************************************************
-** 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.
 **
@@ -47,3 +47,5 @@
 
+#ifdef QWS
 #include <qwindowsystem_qws.h> // for qwsServer
+#endif
 #include <qdatetime.h>
@@ -110,2 +112,3 @@ StartingAppList::StartingAppList( QObject *parent, const char* name )
 {
+#ifdef QWS
 #if QT_VERSION >= 232 && !defined(QT_NO_COP)
@@ -115,2 +118,3 @@ StartingAppList::StartingAppList( QObject *parent, const char* name )
 #endif
+#endif
 }
@@ -171,3 +175,51 @@ 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
 */
@@ -254,3 +306,3 @@ const QDawg& Global::dawg(const QString& name)
 	named_dawg->insert(name,r);
-	QString dawgfilename = dictDir() + "/" + name + ".dawg";
+	QString dawgfilename = applicationFileName("Dictionary", name ) + ".dawg";
 	QFile dawgfile(dawgfilename);
@@ -263,3 +315,8 @@ 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.
 */
@@ -271,3 +328,8 @@ 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.
 */
@@ -279,3 +341,3 @@ void Global::addWords(const QString& dictname, const QStringList& wordlist)
 
-    QString dawgfilename = dictDir() + "/" + dictname + ".dawg";
+    QString dawgfilename = applicationFileName("Dictionary", dictname) + ".dawg";
     QFile dawgfile(dawgfilename);
@@ -293,7 +355,7 @@ 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
+  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 those directories exist.
+  ensure that those directories exist.
 */
@@ -328,4 +390,4 @@ 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.
 */
@@ -375,2 +437,9 @@ 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()
 */
@@ -385,2 +454,7 @@ 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()
 */
@@ -467,2 +541,3 @@ void Global::terminate( const AppLnk* app )
 
+#ifndef QT_NO_COP
     QCString channel = "QPE/Application/" + app->exec().utf8();
@@ -471,2 +546,3 @@ void Global::terminate( const AppLnk* app )
     }
+#endif
 }
@@ -474,3 +550,7 @@ void Global::terminate( const AppLnk* app )
 /*!
-  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()
 */
@@ -543,7 +623,9 @@ void Global::invoke(const QString &c)
 
+
 /*!
-  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.
 */
@@ -579,4 +661,6 @@ void Global::execute( const QString &c, const QString& document )
 		}
+#ifndef QT_NO_COP
 		QCopEnvelope e("QPE/System", "notBusy(QString)" );
 		e << c; // that was quick ;-)
+#endif
 		return;
@@ -602,3 +686,4 @@ void Global::execute( const QString &c, const QString& document )
        preceeding function */
-    { QCopEnvelope env( ("QPE/Application/" + ap).latin1(), "raise()" ); }
+    invoke( ap );
+    //{ QCopEnvelope env( ("QPE/Application/" + ap).latin1(), "raise()" ); }
     if ( !document.isEmpty() ) {
@@ -611,4 +696,6 @@ 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()
 */
@@ -630,4 +717,6 @@ 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()
 */
@@ -715,12 +804,6 @@ QStringList Global::helpPath()
     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;