Qtopia1-6 merge

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

1 files changed, 447 insertions, 135 deletions

diff --git a/library/applnk.cpp b/library/applnk.cpp
index 9498f84..298581a 100644
--- a/library/applnk.cpp
+++ b/library/applnk.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.
 **
@@ -21,2 +21,4 @@
 #define QTOPIA_INTERNAL_MIMEEXT
+#define QTOPIA_INTERNAL_PRELOADACCESS
+#define QTOPIA_INTERNAL_APPLNKASSIGN
 
@@ -27,3 +29,5 @@
 #include <qpe/categoryselect.h>
+#ifdef QWS
 #include <qpe/qcopenvelope_qws.h>
+#endif
 #include <qpe/global.h>
@@ -52,3 +56,3 @@ static QString safeFileName(const QString& n)
     QString safename=n;
-    safename.replace(QRegExp("[^0-9A-Za-z.]"),"_"); // Njaard says this is broken
+    safename.replace(QRegExp("[^0-9A-Za-z.]"),"_");
     safename.replace(QRegExp("^[^A-Za-z]*"),"");
@@ -73,3 +77,48 @@ class AppLnkPrivate
 public:
-    QArray<int> mCat;
+    /* the size of the Pixmap */
+    enum Size {Normal = 0, Big };
+    AppLnkPrivate() {
+        /* we want one normal and one big item */
+        mPixmaps = QArray<QPixmap>(2);
+    }
+
+    QStringList mCatList; // always correct
+    QArray<int> mCat; // cached value; correct if not empty
+    QArray<QPixmap> mPixmaps;
+
+    void updateCatListFromArray()
+    {
+	Categories cat( 0 );
+	cat.load( categoryFileName() );
+	mCatList = cat.labels("Document View",mCat);
+    }
+
+    void setCatArrayDirty()
+    {
+	mCat.resize(0);
+    }
+
+    void ensureCatArray()
+    {
+	if ( mCat.count() > 0 || mCatList.count()==0 )
+	    return;
+
+	Categories cat( 0 );
+	cat.load( categoryFileName() );
+	mCat.resize( mCatList.count() );
+	int i;
+	QStringList::ConstIterator it;
+	for ( i = 0, it = mCatList.begin(); it != mCatList.end();
+	      ++it, i++ ) {
+
+	    bool number;
+	    int id = (*it).toInt( &number );
+	    if ( !number ) {
+		id = cat.id( "Document View", *it );
+		if ( id == 0 )
+		    id = cat.addCategory( "Document View", *it );
+	    }
+	    mCat[i] = id;
+	}
+    }
 };
@@ -80,4 +129,90 @@ public:
 
-  Information about applications are stored in Qtopia as ".desktop" files.
-  When read, these files are stored as AppLnk objects.
+    Every Qtopia application \e app has a corresponding \e app.desktop
+    file. When one of these files is read its data is stored as an
+    AppLnk object.
+
+    The AppLnk class introduces some Qtopia-specific concepts, and
+    provides a variety of functions, as described in the following
+    sections.
+    \tableofcontents
+
+    \target Types
+    \section1 Types
+
+    Every AppLnk object has a \e type. For applications, games and
+    settings the type is \c Application; for documents the
+    type is the document's MIME type.
+
+    \target files-and-links
+    \section1 Files and Links
+
+    When you create an AppLnk (or more likely, a \link doclnk.html
+    DocLnk\endlink), you don't deal directly with filenames in the
+    filesystem. Instead you do this:
+    \code
+    DocLnk d;
+    d.setType("text/plain");
+    d.setName("My Nicely Named Document / Whatever"); // Yes, "/" is legal.
+    \endcode
+    At this point, the file() and linkFile() are unknown. Normally
+    this is uninteresting, and the names become automatically known,
+    and more importantly, becomes reserved, when you ask what they are:
+
+    \code
+    QString fn = d.file();
+    \endcode
+    This invents a filename, and creates the file on disk (an empty
+    reservation file) to prevent the name being used by another
+    application.
+
+    In some circumstances, you don't want to create the file if it
+    doesn't already exist (e.g. in the Document tab, some of the \link
+    doclnk.html DocLnk\endlink objects represented by icons are
+    DocLnk's created just for that view - they don't have
+    corresponding \c .desktop files. To avoid littering empty
+    reservation files around, we check in a few places to see whether
+    the file really needs to exist).
+
+    \section1 Functionality
+
+    AppLnk objects are created by calling the constructor with the
+    name of a \e .desktop file. The object can be checked for validity
+    using isValid().
+
+    The following functions are used to set or retrieve information
+    about the application:
+    \table
+    \header \i Get Function \i Set Function \i Short Description
+    \row \i \l name()	    \i \l setName()    \i application's name
+    \row \i \l pixmap()     \i \e none	    \i application's icon
+    \row \i \l bigPixmap()  \i \e none	    \i application's large icon
+    \row \i \e none	    \i setIcon()    \i sets the icon's filename
+    \row \i \l type() 	    \i \l setType()    \i see \link #Types Types\endlink above
+    \row \i \l rotation()   \i \e none	    \i 0, 90, 180 or 270 degrees
+    \row \i \l comment()    \i \l setComment() \i text for the Details dialog
+    \row \i \l exec()	    \i \l setExec()    \i executable's filename
+    \row \i \l file()	    \i \e none	    \i document's filename
+    \row \i \l linkFile()   \i \l setLinkFile()	\i \e .desktop filename
+    \row \i \l mimeTypes()  \i \e none	    \i the mime types the application can view or edit
+    \row \i \l categories() \i \l setCategories()	\i \e{see the function descriptions}
+    \row \i \l fileKnown()  \i \e none	    \i see \link
+#files-and-links Files and Links\endlink above
+    \row \i \l linkFileKnown() \i \e none	    \i see \link
+#files-and-links Files and Links\endlink above
+    \row \i \l property()   \i \l setProperty()	\i any AppLnk property
+    can be retrieved or set (if writeable) using these
+    \endtable
+
+    To save an AppLnk to disk use writeLink(). To execute the
+    application that the AppLnk object refers to, use execute().
+
+    AppLnk's can be deleted from disk using removeLinkFile(). To
+    remove both the link and the application's executable use
+    removeFiles().
+
+    Icon sizes can be globally changed (but only for AppLnk objects
+    created after the calls) with setSmallIconSize() and
+    setBigIconSize().
+
+    \ingroup qtopiaemb
 */
@@ -87,2 +222,4 @@ public:
   Only affects AppLnk objects created after the call.
+
+  \sa smallIconSize() setIcon()
 */
@@ -95,2 +232,4 @@ void AppLnk::setSmallIconSize(int small)
   Returns the size used for small icons.
+
+  \sa setSmallIconSize() setIcon()
 */
@@ -105,2 +244,4 @@ int AppLnk::smallIconSize()
   Only affects AppLnk objects created after the call.
+
+  \sa bigIconSize() setIcon()
 */
@@ -113,2 +254,4 @@ void AppLnk::setBigIconSize(int big)
   Returns the size used for large icons.
+
+  \sa setBigIconSize() setIcon()
 */
@@ -123,3 +266,8 @@ int AppLnk::bigIconSize()
 
-  Returns the Name property.
+  Returns the Name property. This is the user-visible name for the
+  document or application, not the filename.
+
+    See \link #files-and-links Files and Links\endlink.
+
+  \sa setName()
 */
@@ -128,4 +276,6 @@ int AppLnk::bigIconSize()
 
-  Returns the Exec property. This is the executable program associated
-  with the AppLnk.
+  Returns the Exec property. This is the name of the executable
+  program associated with the AppLnk.
+
+  \sa setExec()
 */
@@ -134,3 +284,4 @@ int AppLnk::bigIconSize()
 
-  Returns the Rotation property.
+  Returns the Rotation property. The value is 0, 90, 180 or 270
+  degrees.
 */
@@ -140,2 +291,4 @@ int AppLnk::bigIconSize()
   Returns the Comment property.
+
+  \sa setComment()
 */
@@ -151,2 +304,6 @@ int AppLnk::bigIconSize()
   Returns the Categories property.
+
+  See the CategoryWidget for more details.
+
+  \sa setCategories()
 */
@@ -155,2 +312,3 @@ const QArray<int>& AppLnk::categories() const
 {
+    d->ensureCatArray();
     return d->mCat;
@@ -164,2 +322,4 @@ const QArray<int>& AppLnk::categories() const
   duration of the current process.
+
+  \sa AppLnkSet::find()
 */
@@ -169,3 +329,3 @@ const QArray<int>& AppLnk::categories() const
 
-  Returns whether this AppLnk is valid.
+  Returns TRUE if this AppLnk is valid; otherwise returns FALSE.
 */
@@ -184,3 +344,5 @@ AppLnk::AppLnk()
 /*!
-  Loads \a file as an AppLnk.
+  Loads \a file (e.g. \e app.desktop) as an AppLnk.
+
+  \sa writeLink()
 */
@@ -202,3 +364,6 @@ AppLnk::AppLnk( const QString &file )
 	    mComment = config.readEntry( "Comment", QString::null );
+	    // MIME types are case-insensitive.
 	    mMimeTypes = config.readListEntry( "MimeType", ';' );
+	    for (QStringList::Iterator it=mMimeTypes.begin(); it!=mMimeTypes.end(); ++it)
+		*it = (*it).lower();
 	    mMimeTypeIcons = config.readListEntry( "MimeTypeIcons", ';' );
@@ -206,23 +371,31 @@ AppLnk::AppLnk( const QString &file )
 	    mFile = config.readEntry("File", QString::null);
-	    sl = config.readListEntry("Categories", ';');
-	}
-    }
-    // let's try our darndest to create categories...
-    Categories cat( 0 );
-    cat.load( categoryFileName() );
-    d->mCat.resize( sl.count() );
-    int i;
-    QStringList::Iterator it;
-    for ( i = 0, it = sl.begin(); it != sl.end();
-	  ++it, i++ ) {
-
-	bool number;
-	int id = (*it).toInt( &number );
-	if ( !number ) {
-	    // convert from old school...
-	    id = cat.id( "Document Viewer", *it );
-	    if ( id == 0 )
-		id = cat.addCategory( "Document Viewer", *it );
+	    if ( mFile[0] != '/' ) {
+		int slash = file.findRev('/');
+		if ( slash >= 0 ) {
+		    mFile = file.left(slash) + '/' + mFile;
+		}
+	    }
+	    d->mCatList = config.readListEntry("Categories", ';');
+	    if ( d->mCatList[0].toInt() < -1 ) {
+		// numeric cats in file! convert to text
+		Categories cat( 0 );
+		cat.load( categoryFileName() );
+		d->mCat.resize( d->mCatList.count() );
+		int i;
+		QStringList::ConstIterator it;
+		for ( i = 0, it = d->mCatList.begin(); it != d->mCatList.end();
+		      ++it, i++ ) {
+		    bool number;
+		    int id = (*it).toInt( &number );
+		    if ( !number ) {
+			// convert from text
+			id = cat.id( "Document View", *it );
+			if ( id == 0 )
+			    id = cat.addCategory( "Document View", *it );
+		    }
+		    d->mCat[i] = id;
+		}
+		d->updateCatListFromArray();
+	    }
 	}
-	d->mCat[i] = id;
     }
@@ -231,8 +404,40 @@ AppLnk::AppLnk( const QString &file )
 
+AppLnk& AppLnk::operator=(const AppLnk &copy)
+{
+    if ( mId )
+	qWarning("Deleting AppLnk that is in an AppLnkSet");
+    if ( d )
+	delete d;
+
+
+    mName = copy.mName;
+
+    /* remove for Qtopia 3.0 -zecke */
+    mPixmap = copy.mPixmap;
+    mBigPixmap = copy.mBigPixmap;
+
+    mExec = copy.mExec;
+    mType = copy.mType;
+    mRotation = copy.mRotation;
+    mComment = copy.mComment;
+    mFile = copy.mFile;
+    mLinkFile = copy.mLinkFile;
+    mIconFile = copy.mIconFile;
+    mMimeTypes = copy.mMimeTypes;
+    mMimeTypeIcons = copy.mMimeTypeIcons;
+    mId = 0;
+    d = new AppLnkPrivate();
+    d->mCat = copy.d->mCat;
+    d->mCatList = copy.d->mCatList;
+    d->mPixmaps = copy.d->mPixmaps;
+
+    return *this;
+}
 /*!
-  Returns a small pixmap associated with the application.
+  protected internally to share code
+  should I document that at all?
+  I don't know the TT style for that
 */
-const QPixmap& AppLnk::pixmap() const
-{
-    if ( mPixmap.isNull() ) {
+const QPixmap& AppLnk::pixmap( int pos, int size ) const {
+    if ( d->mPixmaps[pos].isNull() ) {
 	AppLnk* that = (AppLnk*)this;
@@ -240,11 +445,20 @@ const QPixmap& AppLnk::pixmap() const
 	    MimeType mt(type());
-	    that->mPixmap = mt.pixmap();
-	    if ( that->mPixmap.isNull() )
-		that->mPixmap = Resource::loadPixmap("UnknownDocument-14");
-	    return that->mPixmap;
+	    that->d->mPixmaps[pos] = mt.pixmap();
+	    if ( that->d->mPixmaps[pos].isNull() )
+		that->d->mPixmaps[pos].convertFromImage(
+		    Resource::loadImage("UnknownDocument")
+			.smoothScale( size, size ) );
+	    return that->d->mPixmaps[pos];
 	}
 	QImage unscaledIcon = Resource::loadImage( that->mIconFile );
-	that->mPixmap.convertFromImage( unscaledIcon.smoothScale( smallSize, smallSize ) );
-	that->mBigPixmap.convertFromImage( unscaledIcon.smoothScale( bigSize, bigSize ) );
-	return that->mPixmap;
+	if ( unscaledIcon.isNull() ) {
+	    qDebug( "Cannot find icon: %s", that->mIconFile.latin1() );
+	    that->d->mPixmaps[pos].convertFromImage(
+		    Resource::loadImage("UnknownDocument")
+			.smoothScale( size, size ) );
+	} else {
+	    that->d->mPixmaps[0].convertFromImage( unscaledIcon.smoothScale( smallSize, smallSize ) );
+	    that->d->mPixmaps[1].convertFromImage( unscaledIcon.smoothScale( bigSize, bigSize ) );
+	}
+	return that->d->mPixmaps[0];
     }
@@ -254,3 +468,18 @@ const QPixmap& AppLnk::pixmap() const
 /*!
+  Returns a small pixmap associated with the application.
+
+  \sa bigPixmap() setIcon()
+*/
+const QPixmap& AppLnk::pixmap() const
+{
+    if ( d->mPixmaps[0].isNull() ) {
+        return pixmap(AppLnkPrivate::Normal, smallSize );
+    }
+    return d->mPixmaps[0];
+}
+
+/*!
   Returns a large pixmap associated with the application.
+
+  \sa pixmap() setIcon()
 */
@@ -258,15 +487,4 @@ const QPixmap& AppLnk::bigPixmap() const
 {
-    if ( mBigPixmap.isNull() ) {
-	AppLnk* that = (AppLnk*)this;
-	if ( mIconFile.isEmpty() ) {
-	    MimeType mt(type());
-	    that->mBigPixmap = mt.bigPixmap();
-	    if ( that->mBigPixmap.isNull() )
-		that->mBigPixmap = Resource::loadPixmap("UnknownDocument");
-	    return that->mBigPixmap;
-	}
-	QImage unscaledIcon = Resource::loadImage( that->mIconFile );
-	that->mPixmap.convertFromImage( unscaledIcon.smoothScale( smallSize, smallSize ) );
-	that->mBigPixmap.convertFromImage( unscaledIcon.smoothScale( bigSize, bigSize ) );
-	return that->mBigPixmap;
+    if ( d->mPixmaps[1].isNull() ) {
+        return pixmap( AppLnkPrivate::Big, bigSize );
     }
@@ -276,3 +494,5 @@ const QPixmap& AppLnk::bigPixmap() const
 /*!
-  Returns the type of the application.
+  Returns the type of the AppLnk. For applications, games and
+  settings the type is \c Application; for documents the type is the
+  document's MIME type.
 */
@@ -282,5 +502,8 @@ QString AppLnk::type() const
 	AppLnk* that = (AppLnk*)this;
-	MimeType mt(file());
-	that->mType = mt.id();
-	return that->mType;
+	QString f = file();
+	if ( !f.isNull() ) {
+	    MimeType mt(f);
+	    that->mType = mt.id();
+	    return that->mType;
+	}
     }
@@ -292,3 +515,3 @@ QString AppLnk::type() const
 
-  \sa exec()
+  \sa exec() name()
 */
@@ -297,3 +520,3 @@ QString AppLnk::file() const
     if ( mFile.isNull() ) {
-	AppLnk* that = (AppLnk*)this; // copy?
+	AppLnk* that = (AppLnk*)this;
 	QString ext = MimeType(mType).extension();
@@ -308,5 +531,7 @@ QString AppLnk::file() const
 		QString(getenv("HOME"))+"/Documents/"+mType+"/"+safeFileName(that->mName);
-	    if ( QFile::exists(that->mFile+ext) || QFile::exists(that->mFile+".desktop") ) { // a .desktop with the same name exists
+            /*
+             * A file with the same name or a .desktop file already exists
+             */
+	    if ( QFile::exists(that->mFile+ext) || QFile::exists(that->mFile+".desktop") ) {
 		int n=1;
-		qWarning("AppLnk::file() n=1 %s", that->mFile.latin1() );
 		QString nn;
@@ -316,3 +541,2 @@ QString AppLnk::file() const
 		that->mFile = nn;
-		qWarning("AppLnl::file() now mFile is %s", that->mFile.latin1() );
 	    }
@@ -322,6 +546,8 @@ QString AppLnk::file() const
 	prepareDirectories(that->mFile);
-	QFile f(that->mFile);
-	if ( !f.open(IO_WriteOnly) )
-	    that->mFile = QString::null;
-	return that->mFile;
+	if ( !that->mFile.isEmpty() ) {
+	    QFile f(that->mFile);
+	    if ( !f.open(IO_WriteOnly) )
+		that->mFile = QString::null;
+	    return that->mFile;
+	}
     }
@@ -331,5 +557,5 @@ QString AppLnk::file() const
 /*!
-  Returns the desktop file coresponding to this AppLnk.
+  Returns the desktop file corresponding to this AppLnk.
 
-  \sa file(), exec()
+  \sa file() exec() name()
 */
@@ -342,3 +568,6 @@ QString AppLnk::linkFile() const
 	    const FileSystem *fs = storage.fileSystemOf( that->mFile );
-	    if ( fs && ( fs->isRemovable() || fs->disk() == "/dev/mtdblock6" || fs->disk() == "tmpfs" ) ) {
+            /* tmpfs + and ramfs are available too but not removable
+             * either we fix storage or add this
+             */
+	    if ( fs && ( fs->isRemovable() || fs->disk() == "/dev/mtdblock6" || fs->disk() == "tmpfs") ) {
 		that->mLinkFile = fs->path();
@@ -347,20 +576,22 @@ QString AppLnk::linkFile() const
 	    that->mLinkFile += "/Documents/"+type()+"/"+safeFileName(that->mName);
-	    if ( QFile::exists(that->mLinkFile+".desktop") ) { // ok the file exists lets check if we point to the same file
-		int n=1;
-		QString nn;
-		AppLnk lnk( that->mLinkFile+".desktop" );
-		if(that->file() != lnk.file() ){
-		  qWarning("AppLnk::linkFile exists %s", that->mLinkFile.latin1() );
-		  while (QFile::exists((nn=that->mLinkFile+"_"+QString::number(n))+".desktop")){
-		    n++;
-		    AppLnk lnk(nn ); // just to be sure
-		    if(lnk.file() ==that->file() ){
-		      break;
-		    }
-		  }
-		  that->mLinkFile = nn;
-		}
+
+            /* the desktop file exists make sure we don't point to the same file */
+	    if ( QFile::exists(that->mLinkFile+".desktop") ) {
+                AppLnk lnk( that->mLinkFile + ".desktop" );
+
+                /* the linked is different */
+                if(that->file() != lnk.file() ) {
+                    int n = 1;
+                    QString nn;
+                    while (QFile::exists((nn=that->mLinkFile+"_"+QString::number(n))+".desktop")) {
+                        n++;
+                        /* just to be sure */
+                        AppLnk lnk(nn );
+                        if (lnk.file() == that->file() )
+                            break;
+                    }
+                    that->mLinkFile = nn;
+                }
 	    }
 	    that->mLinkFile += ".desktop";
-	    qWarning("AppLnk::linkFile is %s", that->mLinkFile.latin1() );
 	    storeLink();
@@ -392,2 +623,4 @@ AppLnk::AppLnk( const AppLnk &copy )
     d->mCat = copy.d->mCat;
+    d->mCatList = copy.d->mCatList;
+    d->mPixmaps = copy.d->mPixmaps;
 }
@@ -395,6 +628,6 @@ AppLnk::AppLnk( const AppLnk &copy )
 /*!
-  Destroys the AppLnk. Note that if the AppLnk is current a member of
-  an AppLnkSet, this will produce a run-time warning.
+  Destroys the AppLnk. Note that if the AppLnk is currently a member
+  of an AppLnkSet, this will produce a run-time warning.
 
-  \sa AppLnkSet::add(), AppLnkSet::remove()
+  \sa AppLnkSet::add() AppLnkSet::remove()
 */
@@ -409,3 +642,6 @@ AppLnk::~AppLnk()
 /*!
+  \overload
   Executes the application associated with this AppLnk.
+
+  \sa exec()
 */
@@ -419,2 +655,4 @@ void AppLnk::execute() const
   \a args as arguments.
+
+  \sa exec()
 */
@@ -439,3 +677,3 @@ void AppLnk::execute(const QStringList& args) const
   \a args as arguments. Rotation is not taken into account by
-  this function, you should not call it directly.
+  this function, so you should not call it directly.
 
@@ -451,3 +689,3 @@ void AppLnk::invoke(const QStringList& args) const
 
-  \sa exec()
+  \sa exec() name()
 */
@@ -471,3 +709,3 @@ void AppLnk::setName( const QString& docname )
 
-  \sa file()
+  \sa file() name()
 */
@@ -491,2 +729,5 @@ void AppLnk::setLinkFile( const QString& filename )
 
+  This text is displayed in the 'Details Dialog', for example if the
+  user uses the 'press-and-hold' gesture.
+
   \sa comment()
@@ -501,2 +742,6 @@ void AppLnk::setComment( const QString& comment )
 
+  For applications, games and settings the type should be \c
+  Application; for documents the type should be the document's MIME
+  type.
+
   \sa type()
@@ -509,5 +754,14 @@ void AppLnk::setType( const QString& type )
 /*!
-  Sets the Icon property to \a iconname.
+  \fn QString AppLnk::icon() const
+
+  Returns the Icon property.
+
+  \sa setIcon()
+*/
+
+/*!
+  Sets the Icon property to \a iconname. This is the filename from
+  which the pixmap() and bigPixmap() are obtained.
 
-  \sa pixmap(), bigPixmap()
+  \sa icon() setSmallIconSize() setBigIconSize()
 */
@@ -517,4 +771,4 @@ void AppLnk::setIcon( const QString& iconname )
     QImage unscaledIcon = Resource::loadImage( mIconFile );
-    mPixmap.convertFromImage( unscaledIcon.smoothScale( smallSize, smallSize ) );
-    mBigPixmap.convertFromImage( unscaledIcon.smoothScale( bigSize, bigSize ) );
+    d->mPixmaps[0].convertFromImage( unscaledIcon.smoothScale( smallSize, smallSize ) );
+    d->mPixmaps[1].convertFromImage( unscaledIcon.smoothScale( bigSize, bigSize ) );
 }
@@ -524,2 +778,4 @@ void AppLnk::setIcon( const QString& iconname )
 
+  See the CategoryWidget for more details.
+
   \sa categories()
@@ -529,2 +785,3 @@ void AppLnk::setCategories( const QArray<int>& c )
     d->mCat = c;
+    d->updateCatListFromArray();
 }
@@ -538,4 +795,7 @@ void AppLnk::setCategories( const QArray<int>& c )
 /*!
-  Attempts to ensure that the link file for this AppLnk exists, including
-  creating any required directories. Returns TRUE if successful.
+  Attempts to ensure that the link file for this AppLnk exists,
+  including creating any required directories. Returns TRUE if
+  successful; otherwise returns FALSE.
+
+  You should not need to use this function.
 */
@@ -548,6 +808,7 @@ bool AppLnk::ensureLinkExists() const
 /*!
-  Commits the AppLnk to disk. Returns whether the operation succeeded.
+  Commits the AppLnk to disk. Returns TRUE if the operation succeeded;
+  otherwise returns FALSE.
 
-  The "linkChanged(QString)" message is sent to the
-  "QPE/System" QCop channel as a result.
+  In addition, the "linkChanged(QString)" message is sent to the
+  "QPE/System" \link qcop.html QCop\endlink channel.
 */
@@ -563,2 +824,5 @@ bool AppLnk::writeLink() const
 
+/*!
+  \internal
+*/
 void AppLnk::storeLink() const
@@ -571,13 +835,19 @@ void AppLnk::storeLink() const
     if ( !mComment.isNull() ) config.writeEntry("Comment",mComment);
-    config.writeEntry("File",file());
-    // write out the id...
-    int i;
-    QStringList sl;
-    for ( i = 0; i < int(d->mCat.count()); i++ ) {
-	sl.append( QString::number( d->mCat[i] ) );
-    }
-    config.writeEntry( "Categories", sl, ';' );
-
+    QString f = file();
+    int i = 0;
+    while ( i < (int)f.length() && i < (int)mLinkFile.length() && f[i] == mLinkFile[i] )
+	i++;
+    while ( i && f[i] != '/' )
+	i--;
+    // simple case where in the same directory
+    if ( mLinkFile.find( '/', i + 1 ) < 0 )
+	f = f.mid(i+1);
+    // ### could do relative ie ../../otherDocs/file.doc
+    config.writeEntry("File",f);
+    config.writeEntry( "Categories", d->mCatList, ';' );
+
+#ifndef QT_NO_COP
     QCopEnvelope e("QPE/System", "linkChanged(QString)");
     e << mLinkFile;
+#endif
 }
@@ -586,2 +856,4 @@ void AppLnk::storeLink() const
   Sets the property named \a key to \a value.
+
+  \sa property()
 */
@@ -597,2 +869,4 @@ void AppLnk::setProperty(const QString& key, const QString& value)
   Returns the property named \a key.
+
+  \sa setProperty()
 */
@@ -607,3 +881,2 @@ QString AppLnk::property(const QString& key) const
 
-
 bool AppLnk::isPreloaded() const {
@@ -632,3 +905,5 @@ void AppLnk::setPreloaded(bool yesNo) {
 /*!
-  Deletes both the linkFile() and file() associated with this AppLnk.
+  Deletes both the linkFile() and the file() associated with this AppLnk.
+
+  \sa removeLinkFile()
 */
@@ -639,2 +914,3 @@ void AppLnk::removeFiles()
 	if ( QFile::remove(file()) ) {
+#ifndef QT_NO_COP
 	    QCopEnvelope e("QPE/System", "linkChanged(QString)");
@@ -644,2 +920,3 @@ void AppLnk::removeFiles()
 		e << file();
+#endif
 	} else if ( valid ) {
@@ -652,3 +929,5 @@ void AppLnk::removeFiles()
 /*!
-  Delete the linkFile(), leaving any file() untouched.
+  Deletes the linkFile(), leaving any file() untouched.
+
+    \sa removeFiles()
 */
@@ -657,4 +936,6 @@ void AppLnk::removeLinkFile()
     if ( isValid() && linkFileKnown() && QFile::remove(linkFile()) ) {
+#ifndef QT_NO_COP
 	QCopEnvelope e("QPE/System", "linkChanged(QString)");
 	e << linkFile();
+#endif
     }
@@ -684,3 +965,6 @@ public:
 
-  Returns the list of types in the set.
+  Returns the list of \link applnk.html#Types types\endlink in the set.
+
+    For applications, games and settings the type is \c Application;
+    for documents the type is the document's MIME type.
 
@@ -705,7 +989,10 @@ AppLnkSet::AppLnkSet() :
   Constructs an AppLnkSet that contains AppLnk objects representing
-  all the files in a \a directory (recursively).
+  all the files in the given \a directory (and any subdirectories
+  recursively).
 
-  The directories may contain ".directory" files which overrides
-  any AppLnk::type() value of AppLnk objects found in the directory.
+  \omit
+  The directories may contain ".directory" files which override
+  any AppLnk::type() values for AppLnk objects found in the directory.
   This allows simple localization of application types.
+  \endomit
 */
@@ -720,4 +1007,4 @@ AppLnkSet::AppLnkSet( const QString &directory ) :
 /*!
-  Detaches all AppLnk objects from the set. The set become empty
-  and the call becomes responsible for deleting the AppLnk objects.
+  Detaches all AppLnk objects from the set. The set become empty and
+  the caller becomes responsible for deleting the AppLnk objects.
 */
@@ -735,3 +1022,3 @@ void AppLnkSet::detachChildren()
 /*!
-  Destroys the set, deleting all AppLnk objects it contains.
+  Destroys the set, deleting all the AppLnk objects it contains.
 
@@ -813,3 +1100,4 @@ void AppLnkSet::findChildren(const QString &dr, const QString& typ, const QStrin
 /*!
-  Adds \a f to the set. The set takes over responsibility for deleting \a f.
+  Adds AppLnk \a f to the set. The set takes responsibility for
+  deleting \a f.
 
@@ -829,4 +1117,5 @@ void AppLnkSet::add( AppLnk *f )
 /*!
-  Removes \a f to the set, returning whether \a f was in the set.
-  The caller becomes responsible for deleting \a f.
+  Removes AppLnk \a f to the set. The caller becomes responsible for
+  deleting \a f. Returns TRUE if \a f was in the set; otherwise
+  returns FALSE.
 
@@ -843,4 +1132,8 @@ bool AppLnkSet::remove( AppLnk *f )
 
+
 /*!
   Returns the localized name for type \a t.
+
+    For applications, games and settings the type is \c Application;
+    for documents the type is the document's MIME type.
 */
@@ -854,2 +1147,5 @@ QString AppLnkSet::typeName( const QString& t ) const
   Returns the small pixmap associated with type \a t.
+
+    For applications, games and settings the type is \c Application;
+    for documents the type is the document's MIME type.
 */
@@ -863,2 +1159,5 @@ QPixmap AppLnkSet::typePixmap( const QString& t ) const
   Returns the large pixmap associated with type \a t.
+
+    For applications, games and settings the type is \c Application;
+    for documents the type is the document's MIME type.
 */
@@ -923,4 +1222,4 @@ DocLnkSet::DocLnkSet()
 /*!
-  Constructs an DocLnkSet that contains DocLnk objects representing
-  all the files in a \a directory (recursively).
+  Constructs a DocLnkSet that contains DocLnk objects representing all
+  the files in the \a directory (and any subdirectories, recursively).
 
@@ -929,3 +1228,6 @@ DocLnkSet::DocLnkSet()
   The value may contain multiple wild-card patterns separated by ";",
-  such as "*o/mpeg;audio/x-wav".
+  such as \c{*o/mpeg;audio/x-wav}.
+
+  See also \link applnk.html#files-and-links Files and Links\endlink.
+
 */
@@ -998,2 +1300,9 @@ void DocLnkSet::findChildren(const QString &dr, const QValueList<QRegExp> &mimeF
 
+    /* Opie got a different approach
+     * I guess it's geek vs. consumer
+     * in this case to be discussed
+     */
+    if ( dir.exists( ".Qtopia-ignore" ) )
+	return;
+
     const QFileInfoList *list = dir.entryInfoList();
@@ -1003,5 +1312,6 @@ void DocLnkSet::findChildren(const QString &dr, const QValueList<QRegExp> &mimeF
 	    QString bn = fi->fileName();
-	    if ( bn[0] != '.' && bn != "CVS" ) {
-		if ( fi->isDir() ) {
-		    findChildren(fi->filePath(), mimeFilters, reference, depth);
+	    if ( bn[0] != '.' ) {
+		if ( fi->isDir()  ) {
+		    if ( bn != "CVS" && bn != "Qtopia" && bn != "QtPalmtop" )
+			findChildren(fi->filePath(), mimeFilters, reference, depth);
 		} else {
@@ -1060,4 +1370,5 @@ DocLnk::DocLnk( const QString &file ) :
   Constructs a DocLnk from a valid .desktop \a file or a new .desktop
-  \a file for other files. If \a may_be_desktopfile is TRUE, then \a file
-  is first attempted to be read as a .desktop file.
+  \a file for other files. If \a may_be_desktopfile is TRUE, then an
+  attempt is made to read \a file as a .desktop file; if that fails it
+  is read as a normal file.
 */
@@ -1090,4 +1401,4 @@ void DocLnk::init(const QString &file)
 	QString n = file;
-	n.replace(QRegExp("\\..*"),"");
 	n.replace(QRegExp(".*/"),"");
+	n.replace(QRegExp("\\..*"),"");
 	setName( n );
@@ -1108,3 +1419,3 @@ DocLnk::DocLnk()
 /*!
-  Destroys the DocLnk. As with AppLnk objects, a run-time error
+  Destroys the DocLnk. Just like AppLnk objects, a run-time error
   occurs if the DocLnk is a member of a DocLnkSet (or AppLnkSet).
@@ -1145 +1456,2 @@ void DocLnk::invoke(const QStringList& args) const
 
+