Qtopia1-6 merge

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

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,10 +1,10 @@
 /**********************************************************************
-** 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
 ** Foundation and appearing in the file LICENSE.GPL included in the
 ** packaging of this file.
 **
@@ -42,24 +42,26 @@
 #include <sys/stat.h>
 #include <sys/wait.h>
 #include <sys/types.h>
 #include <fcntl.h>
 #include <unistd.h>
 
+#ifdef QWS
 #include <qwindowsystem_qws.h> // for qwsServer
+#endif
 #include <qdatetime.h>
 
 #include <qfile.h>
 
 namespace {
   // checks if the storage should be searched
   bool checkStorage(const QString &path ){ // this is a small Config replacement cause config is too limited -zecke
     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 ){
       if( (*it).startsWith("autocheck = 0" ) ){
 	return false;
       }else if( (*it).startsWith("autocheck = 1" ) ){
@@ -105,17 +107,19 @@ private:
 
 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 )
 {
 #if QT_VERSION >= 232  && !defined(QT_NO_COP)
     if ( !appl )
@@ -166,13 +170,61 @@ static QString dictDir()
 {
     return qpeDir() + "/etc/dict";
 }
 
 /*!
   \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
 */
 
 /*!
   \internal
 */
 Global::Global()
@@ -249,38 +301,48 @@ const QDawg& Global::dawg(const QString& name)
     if ( !named_dawg )
 	named_dawg = new QDict<QDawg>;
     QDawg* r = named_dawg->find(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);
     }
     return *r;
 }
 
 /*!
+  \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)
 {
     addWords("local",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)
 {
     QDawg& d = (QDawg&)dawg(dictname);
     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);
 	dawgfile.close();
     }
 
@@ -288,17 +350,17 @@ void Global::addWords(const QString& dictname, const QStringList& wordlist)
 
     // #### Signal other processes to re-read.
 }
 
 
 /*!
-  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)
 {
     QDir d;
     QString r = getenv("HOME");
     r += "/Applications/";
@@ -323,14 +385,14 @@ void Global::createDocDir()
 	mkdir( QPEApplication::documentDir().latin1(), 0755 );
     }
 }
 
 
 /*!
-  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)
 {
 #if defined(Q_WS_QWS) && !defined(QT_NO_COP)
     QCopEnvelope e( "QPE/TaskBar", "message(QString)" );
     e << message;
@@ -370,22 +432,34 @@ QWidget *Global::restart( bool )
 #endif
     return 0;
 }
 
 /*!
   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()
 {
 #if defined(Q_WS_QWS) && !defined(QT_NO_COP)
     QCopChannel::send( "QPE/TaskBar", "showInputMethod()" );
 #endif
 }
 
 /*!
   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()
 {
 #if defined(Q_WS_QWS) && !defined(QT_NO_COP)
     QCopChannel::send( "QPE/TaskBar", "hideInputMethod()" );
 #endif
@@ -462,36 +536,42 @@ bool Global::terminateBuiltin( const QString& n )
   \internal
 */
 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);
 
 #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)" );
 	e << ap;
 	return;
     }
@@ -521,13 +601,13 @@ void Global::invoke(const QString &c)
 #ifdef HAVE_QUICKEXEC
     QString libexe = qpeDir()+"/binlib/lib"+args[0] + ".so";
     qDebug("libfile = %s", libexe.latin1() );
     if ( QFile::exists( libexe ) ) {
 	qDebug("calling quickexec %s", libexe.latin1() );
 	quickexecv( libexe.utf8().data(), (const char **)args );
-    } else 
+    } else
 #endif
     {
 	if ( !::vfork() ) {
 	    for ( int fd = 3; fd < 100; fd++ )
 		::close( fd );
 	    ::setpgid( ::getpid(), ::getppid() );
@@ -538,17 +618,19 @@ void Global::invoke(const QString &c)
 	}
     }
     StartingAppList::add( list[0] );
 #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 )
 {
     if ( qApp->type() != QApplication::GuiServer ) {
 	// ask the server to do the work
 #if defined(Q_WS_QWS) && !defined(QT_NO_COP)
@@ -574,14 +656,16 @@ void Global::execute( const QString &c, const QString& document )
 		    running[i]->raise();
 		    running[i]->show();
 		    running[i]->setActiveWindow();
 		} 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;
 	    }
 	}
     }
 
     //Global::invoke(c, document);
@@ -591,29 +675,32 @@ void Global::execute( const QString &c, const QString& document )
 
 #if defined(Q_WS_QWS) && !defined(QT_NO_COP)
     QString ap=list[0];
 
     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;
     }
 #endif
 }
 
 /*!
-  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)
 {
     QString r="\"";
     for (int i=0; i<(int)s.length(); i++) {
 	char c = s[i].latin1();
@@ -625,14 +712,16 @@ QString Global::shellQuote(const QString& s)
     }
     r += "\"";
     return r;
 }
 
 /*!
-  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)
 {
     QString r="\"";
     for (int i=0; i<(int)s.length(); i++) {
 	char c = s[i].latin1();
@@ -658,27 +747,27 @@ void Global::findDocuments(DocLnkSet* folder, const QString &mimefilter)
     folder->appendFrom(d);
     /** let's do intellegint way of searching these files
      *  a) the user don't want to check mediums global
      *  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
      *
      *  b) mimefilter is set to an application we need to find out if the
      *     mimetypes are included in the mime mask of the medium
      */
     StorageInfo storage;
     const QList<FileSystem> &fs = storage.fileSystems();
     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;
 	DocLnkSet ide( path, mimefilter );
 	folder->appendFrom(ide);
       } else if ( (*it)->disk() == "/dev/mtdblock6" || (*it)->disk() == "tmpfs" ) {
@@ -710,21 +799,15 @@ QStringList Global::helpPath()
     for (QStringList::ConstIterator it = langs.fromLast(); it!=langs.end(); --it) {
 	QString lang = *it;
 	if ( !lang.isEmpty() )
 	    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;
 }
 
 
 #include "global.moc"