Documentation

6 files changed, 181 insertions, 37 deletions

diff --git a/src/imports/mimetypes/qdeclarativemimedatabase.cpp b/src/imports/mimetypes/qdeclarativemimedatabase.cpp
index c3c2081..f54e9e1 100644
--- a/src/imports/mimetypes/qdeclarativemimedatabase.cpp
+++ b/src/imports/mimetypes/qdeclarativemimedatabase.cpp
@@ -39,7 +39,7 @@
 **
 ****************************************************************************/
 
-#include "qdeclarativemimedatabase_p.h"
+#include "qdeclarativemimedatabase_p.h"   // Basis
 
 #include "qdeclarativemimetype_p.h"
 
@@ -47,16 +47,35 @@
 
 // ------------------------------------------------------------------------------------------------
 
+extern bool isQMimeDatabaseDebuggingActivated;
+
+#ifndef QT_NO_DEBUG_OUTPUT
+#define DBG() if (isQMimeDatabaseDebuggingActivated) qDebug() << Q_FUNC_INFO
+#else
+#define DBG() if (0) qDebug() << Q_FUNC_INFO
+#endif
+
+// ------------------------------------------------------------------------------------------------
+
+/*!
+    \qmlclass MimeDatabase QDeclarativeMimeDatabase
+    \brief The QML MimeDatabase element maintains a database of MIME types.
+ */
+
+// ------------------------------------------------------------------------------------------------
+
 QDeclarativeMimeDatabase::QDeclarativeMimeDatabase(QObject *theParent) :
         QObject(theParent),
         m_MimeDatabase()
-{}
+{
+    DBG() << "mimeTypeNames():" << mimeTypeNames();
+}
 
 // ------------------------------------------------------------------------------------------------
 
 QDeclarativeMimeDatabase::~QDeclarativeMimeDatabase()
 {
-    //qDebug() << Q_FUNC_INFO;
+    DBG() << "mimeTypeNames():" << mimeTypeNames();
 }
 
 // ------------------------------------------------------------------------------------------------
@@ -68,6 +87,13 @@ QMimeDatabase &QDeclarativeMimeDatabase::mimeDatabase()
 
 // ------------------------------------------------------------------------------------------------
 
+/*!
+    \qmlproperty QVariantList MimeDatabase::mimeTypeNames
+    list of registered MIME types
+ */
+
+// ------------------------------------------------------------------------------------------------
+
 QVariantList QDeclarativeMimeDatabase::mimeTypeNames() const
 {
     QVariantList result;
@@ -81,6 +107,10 @@ QVariantList QDeclarativeMimeDatabase::mimeTypeNames() const
 
 // ------------------------------------------------------------------------------------------------
 
+/*!
+    \qmlmethod MimeDatabase::mimeTypeForName()
+    \brief Returns a MIME type for \a nameOrAlias or an invalid one if none found.
+ */
 QDeclarativeMimeType *QDeclarativeMimeDatabase::mimeTypeForName (
                                                     const QString &mimeTypeName
                                                 )
@@ -94,6 +124,18 @@ QDeclarativeMimeType *QDeclarativeMimeDatabase::mimeTypeForName (
 
 // ------------------------------------------------------------------------------------------------
 
+/*!
+    \qmlmethod MimeDatabase::findByName()
+    \brief Returns a MIME type for the file \a fileName.
+
+    A valid MIME type is always returned. If the file name doesn't match any
+    known pattern, the default MIME type (application/octet-stream)
+    is returned.
+
+    This function does not try to open the file. To also use the content
+    when determining the MIME type, use QMimeDatabase::findByFile or
+    QMimeDatabase::findByNameAndData instead.
+*/
 QDeclarativeMimeType *QDeclarativeMimeDatabase::findByName (
                                                     const QString &fileName
                                                 )
@@ -107,6 +149,21 @@ QDeclarativeMimeType *QDeclarativeMimeDatabase::findByName (
 
 // ------------------------------------------------------------------------------------------------
 
+/*!
+    \qmlmethod MimeDatabase::findByFile()
+    \brief Returns a MIME type for \a fileName.
+
+    This method looks at both the file name and the file contents,
+    if necessary. The file extension has priority over the contents,
+    but the contents will be used if the file extension is unknown, or
+    matches multiple MIME types.
+
+    A valid MIME type is always returned. If the file doesn't match any
+    known pattern or data, the default MIME type (application/octet-stream)
+    is returned.
+
+    The \a fileName can also include an absolute or relative path.
+*/
 QDeclarativeMimeType *QDeclarativeMimeDatabase::findByFile (
                                                     const QString &fileName
                                                 )
@@ -117,3 +174,7 @@ QDeclarativeMimeType *QDeclarativeMimeDatabase::findByFile (
                           //    when this registry is released.
                );
 }
+
+// ------------------------------------------------------------------------------------------------
+
+#undef DBG
diff --git a/src/imports/mimetypes/qdeclarativemimedatabase_p.h b/src/imports/mimetypes/qdeclarativemimedatabase_p.h
index e494f73..22d329a 100644
--- a/src/imports/mimetypes/qdeclarativemimedatabase_p.h
+++ b/src/imports/mimetypes/qdeclarativemimedatabase_p.h
@@ -39,10 +39,10 @@
 **
 ****************************************************************************/
 
-#ifndef QT_DECLARATIVE_MIME_TYPE_REGISTRY_P_H_INCLUDED
-#define QT_DECLARATIVE_MIME_TYPE_REGISTRY_P_H_INCLUDED
+#ifndef QDECLARATIVEMIMEDATABASE_P_H_INCLUDED
+#define QDECLARATIVEMIMEDATABASE_P_H_INCLUDED
 
-#include "qmimedatabase.h"
+#include <qmimedatabase.h>
 
 #include <QtDeclarative/qdeclarative.h>
 
@@ -61,8 +61,8 @@ class QDeclarativeMimeDatabase : public QObject
                STORED false)
 
 protected:
-    // We keep this destructor with its default value of 0 protected since only
-    // QDeclarativePrivate::QDeclarativeElement<T> needs it:
+    // We keep this destructor with its default value of 0 protected since
+    // only QDeclarativePrivate::QDeclarativeElement<T> needs it:
     QDeclarativeMimeDatabase(QObject *theParent = 0);
 
 public:
@@ -98,4 +98,4 @@ private:
 
 QML_DECLARE_TYPE(QDeclarativeMimeDatabase)
 
-#endif   // QT_DECLARATIVE_MIME_TYPE_REGISTRY_P_H_INCLUDED
+#endif   // QDECLARATIVEMIMEDATABASE_P_H_INCLUDED
diff --git a/src/imports/mimetypes/qdeclarativemimetype.cpp b/src/imports/mimetypes/qdeclarativemimetype.cpp
index bc2819e..5c4b402 100644
--- a/src/imports/mimetypes/qdeclarativemimetype.cpp
+++ b/src/imports/mimetypes/qdeclarativemimetype.cpp
@@ -59,9 +59,8 @@ extern bool isQMimeTypeDebuggingActivated;
 // ------------------------------------------------------------------------------------------------
 
 /*!
-    \qmlclass MimeType
+    \qmlclass MimeType QDeclarativeMimeType
     \brief The QML MimeType element describes types of file or data, represented by a MIME type string.
-    \inherits QObject
  */
 
 // ------------------------------------------------------------------------------------------------
diff --git a/src/mimetypes/qmimedatabase.cpp b/src/mimetypes/qmimedatabase.cpp
index 7a31224..5431a56 100644
--- a/src/mimetypes/qmimedatabase.cpp
+++ b/src/mimetypes/qmimedatabase.cpp
@@ -1,4 +1,4 @@
-/**************************************************************************
+/****************************************************************************
 **
 ** This file is part of QMime
 **
@@ -16,9 +16,10 @@
 ** Public License version 2.1 requirements will be met:
 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
 **
-**************************************************************************/
+****************************************************************************/
+
+#include "qmimedatabase.h"   // Basis
 
-#include "qmimedatabase.h"
 #include "qmimedatabase_p.h"
 
 #include <QtCore/QFile>
@@ -38,24 +39,44 @@
 
 QT_BEGIN_NAMESPACE
 
-Q_GLOBAL_STATIC(QMimeDatabasePrivate, staticMimeDataBase)
+// ------------------------------------------------------------------------------------------------
+
+bool isQMimeDatabaseDebuggingActivated (false);
+
+#ifndef QT_NO_DEBUG_OUTPUT
+#define DBG() if (isQMimeDatabaseDebuggingActivated) qDebug() << Q_FUNC_INFO
+#else
+#define DBG() if (0) qDebug() << Q_FUNC_INFO
+#endif
+
+// ------------------------------------------------------------------------------------------------
+
+Q_GLOBAL_STATIC(QMimeDatabasePrivate, staticQMimeDatabase)
+
+// ------------------------------------------------------------------------------------------------
 
 QMimeDatabasePrivate *QMimeDatabasePrivate::instance()
 {
-    return staticMimeDataBase();
+    return staticQMimeDatabase();
 }
 
+// ------------------------------------------------------------------------------------------------
+
 QMimeDatabasePrivate::QMimeDatabasePrivate()
     : m_provider(0), m_defaultMimeType(QLatin1String("application/octet-stream"))
 {
 }
 
+// ------------------------------------------------------------------------------------------------
+
 QMimeDatabasePrivate::~QMimeDatabasePrivate()
 {
     delete m_provider;
     m_provider = 0;
 }
 
+// ------------------------------------------------------------------------------------------------
+
 QMimeProviderBase *QMimeDatabasePrivate::provider()
 {
     if (!m_provider) {
@@ -70,12 +91,16 @@ QMimeProviderBase *QMimeDatabasePrivate::provider()
     return m_provider;
 }
 
+// ------------------------------------------------------------------------------------------------
+
 void QMimeDatabasePrivate::setProvider(QMimeProviderBase *theProvider)
 {
     delete m_provider;
     m_provider = theProvider;
 }
 
+// ------------------------------------------------------------------------------------------------
+
 // Returns a MIME type or an invalid one if none found
 QMimeType QMimeDatabasePrivate::mimeTypeForName(const QString &nameOrAlias)
 {
@@ -91,6 +116,8 @@ QStringList QMimeDatabasePrivate::findByName(const QString &fileName, QString *f
     return matchingMimeTypes;
 }
 
+// ------------------------------------------------------------------------------------------------
+
 static inline bool isTextFile(const QByteArray &data)
 {
     // UTF16 byte order marks
@@ -110,6 +137,8 @@ static inline bool isTextFile(const QByteArray &data)
     return true;
 }
 
+// ------------------------------------------------------------------------------------------------
+
 QMimeType QMimeDatabasePrivate::findByData(const QByteArray &data, int *accuracyPtr)
 {
     if (data.isEmpty()) {
@@ -131,6 +160,8 @@ QMimeType QMimeDatabasePrivate::findByData(const QByteArray &data, int *accuracy
     return mimeTypeForName(defaultMimeType());
 }
 
+// ------------------------------------------------------------------------------------------------
+
 QMimeType QMimeDatabasePrivate::findByNameAndData(const QString &fileName, QIODevice *device, int *accuracyPtr)
 {
     // First, glob patterns are evaluated. If there is a match with max weight,
@@ -189,6 +220,8 @@ QMimeType QMimeDatabasePrivate::findByNameAndData(const QString &fileName, QIODe
     return mimeTypeForName(defaultMimeType());
 }
 
+// ------------------------------------------------------------------------------------------------
+
 #if 0
 QStringList QMimeDatabasePrivate::filterStrings() const
 {
@@ -204,11 +237,14 @@ QStringList QMimeDatabasePrivate::filterStrings() const
 }
 #endif
 
+// ------------------------------------------------------------------------------------------------
+
 QList<QMimeType> QMimeDatabasePrivate::allMimeTypes()
 {
     return provider()->allMimeTypes();
 }
 
+// ------------------------------------------------------------------------------------------------
 
 bool QMimeDatabasePrivate::inherits(const QString &mime, const QString &parent)
 {
@@ -227,6 +263,8 @@ bool QMimeDatabasePrivate::inherits(const QString &mime, const QString &parent)
     return false;
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     \class QMimeDatabase
     \brief The QMimeDatabase class maintains a database of MIME types.
@@ -269,21 +307,36 @@ bool QMimeDatabasePrivate::inherits(const QString &mime, const QString &parent)
     The class is protected by a QMutex and can therefore be accessed by threads.
 
     \sa QMimeType
-*/
+ */
 
+// ------------------------------------------------------------------------------------------------
+
+/*!
+    \fn QMimeDatabase::QMimeDatabase();
+    \brief Initializes the MIME database.
+ */
 QMimeDatabase::QMimeDatabase() :
-    d(staticMimeDataBase())
+        d(staticQMimeDatabase())
 {
 }
 
+// ------------------------------------------------------------------------------------------------
+
+/*!
+    \fn QMimeDatabase::~QMimeDatabase();
+    \brief Resets the d pointer.
+ */
 QMimeDatabase::~QMimeDatabase()
 {
     d = 0;
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
-    Returns a MIME type for \a nameOrAlias or an invalid one if none found.
-*/
+    \fn QMimeType QMimeDatabase::mimeTypeForName(const QString& nameOrAlias) const;
+    \brief Returns a MIME type for \a nameOrAlias or an invalid one if none found.
+ */
 QMimeType QMimeDatabase::mimeTypeForName(const QString& nameOrAlias) const
 {
     QMutexLocker locker(&d->mutex);
@@ -291,8 +344,11 @@ QMimeType QMimeDatabase::mimeTypeForName(const QString& nameOrAlias) const
     return d->mimeTypeForName(nameOrAlias);
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
-    Returns a MIME type for \a fileInfo.
+    \fn QMimeType QMimeDatabase::findByFile(const QFileInfo &fileInfo) const;
+    \brief Returns a MIME type for \a fileInfo.
 
     This method looks at both the file name and the file contents,
     if necessary. The file extension has priority over the contents,
@@ -310,7 +366,7 @@ QMimeType QMimeDatabase::mimeTypeForName(const QString& nameOrAlias) const
 */
 QMimeType QMimeDatabase::findByFile(const QFileInfo &fileInfo) const
 {
-    //qDebug() << Q_FUNC_INFO << "fileInfo" << fileInfo.absoluteFilePath();
+    DBG() << "fileInfo" << fileInfo.absoluteFilePath();
 
     QMutexLocker locker(&d->mutex);
 
@@ -339,8 +395,11 @@ QMimeType QMimeDatabase::findByFile(const QFileInfo &fileInfo) const
     return d->findByNameAndData(fileInfo.absoluteFilePath(), &file, &priority);
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
-    Returns a MIME type for \a fileName.
+    \fn QMimeType QMimeDatabase::findByFile(const QString &fileName) const;
+    \brief Returns a MIME type for \a fileName.
 
     This method looks at both the file name and the file contents,
     if necessary. The file extension has priority over the contents,
@@ -360,8 +419,11 @@ QMimeType QMimeDatabase::findByFile(const QString &fileName) const
     return findByFile(fileInfo);
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
-    Returns a MIME type for the file \a fileName.
+    \fn QMimeType QMimeDatabase::findByName(const QString &fileName) const;
+    \brief Returns a MIME type for the file \a fileName.
 
     A valid MIME type is always returned. If the file name doesn't match any
     known pattern, the default MIME type (application/octet-stream)
@@ -388,6 +450,8 @@ QMimeType QMimeDatabase::findByName(const QString &fileName) const
     }
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     Returns the suffix for the file \a fileName, as known by the MIME database.
 
@@ -402,6 +466,8 @@ QString QMimeDatabase::suffixForFileName(const QString &fileName) const
     return foundSuffix;
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     Returns a MIME type for \a data.
 
@@ -417,6 +483,8 @@ QMimeType QMimeDatabase::findByData(const QByteArray &data) const
     return d->findByData(data, &accuracy);
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     Returns a MIME type for \a url.
 
@@ -446,6 +514,8 @@ QMimeType QMimeDatabase::findByUrl(const QUrl &url) const
     return findByName(url.path());
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     Returns a MIME type for the given \a fileName and \a device data.
 
@@ -464,12 +534,14 @@ QMimeType QMimeDatabase::findByUrl(const QUrl &url) const
 */
 QMimeType QMimeDatabase::findByNameAndData(const QString &fileName, QIODevice *device) const
 {
-    //qDebug() << Q_FUNC_INFO << "fileName" << fileName;
+    DBG() << "fileName" << fileName;
 
     int accuracy = 0;
     return d->findByNameAndData(fileName, device, &accuracy);
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     Returns a MIME type for the given \a fileName and device \a data.
 
@@ -488,13 +560,15 @@ QMimeType QMimeDatabase::findByNameAndData(const QString &fileName, QIODevice *d
 */
 QMimeType QMimeDatabase::findByNameAndData(const QString &fileName, const QByteArray &data) const
 {
-    //qDebug() << Q_FUNC_INFO << "fileName" << fileName;
+    DBG() << "fileName" << fileName;
 
     QBuffer buffer(const_cast<QByteArray *>(&data));
     int accuracy = 0;
     return d->findByNameAndData(fileName, &buffer, &accuracy);
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     Returns the list of all available MIME types.
 
@@ -509,6 +583,8 @@ QList<QMimeType> QMimeDatabase::allMimeTypes() const
     return d->allMimeTypes();
 }
 
+// ------------------------------------------------------------------------------------------------
+
 // TODO: needed?
 #if 0
 QStringList QMimeDatabase::filterStrings() const
@@ -518,6 +594,8 @@ QStringList QMimeDatabase::filterStrings() const
     return d->filterStrings();
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     Returns a string with all the possible file filters, for use with file dialogs
 */
@@ -545,4 +623,10 @@ QString QMimeDatabase::allFiltersString(QString *allFilesFilter) const
 }
 #endif
 
+// ------------------------------------------------------------------------------------------------
+
+#undef DBG
+
+// ------------------------------------------------------------------------------------------------
+
 QT_END_NAMESPACE
diff --git a/src/mimetypes/qmimedatabase.h b/src/mimetypes/qmimedatabase.h
index d16cc3e..25845c8 100644
--- a/src/mimetypes/qmimedatabase.h
+++ b/src/mimetypes/qmimedatabase.h
@@ -1,4 +1,4 @@
-/**************************************************************************
+/****************************************************************************
 **
 ** This file is part of QMime
 **
@@ -16,10 +16,10 @@
 ** Public License version 2.1 requirements will be met:
 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
 **
-**************************************************************************/
+****************************************************************************/
 
-#ifndef QMIMEDATABASE_H
-#define QMIMEDATABASE_H
+#ifndef QMIMEDATABASE_H_INCLUDED
+#define QMIMEDATABASE_H_INCLUDED
 
 #include "qmime_global.h"
 
@@ -71,5 +71,5 @@ private:
 };
 
 QT_END_NAMESPACE
-
-#endif // QMIMEDATABASE_H
+  
+#endif   // QMIMEDATABASE_H_INCLUDED
diff --git a/src/mimetypes/qmimedatabase_p.h b/src/mimetypes/qmimedatabase_p.h
index 2886b63..9d8ef3b 100644
--- a/src/mimetypes/qmimedatabase_p.h
+++ b/src/mimetypes/qmimedatabase_p.h
@@ -1,4 +1,4 @@
-/**************************************************************************
+/****************************************************************************
 **
 ** This file is part of QMime
 **
@@ -16,10 +16,10 @@
 ** Public License version 2.1 requirements will be met:
 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
 **
-**************************************************************************/
+****************************************************************************/
 
-#ifndef QMIMEDATABASE_P_H
-#define QMIMEDATABASE_P_H
+#ifndef QMIMEDATABASE_P_H_INCLUDED
+#define QMIMEDATABASE_P_H_INCLUDED
 
 #include <QtCore/QMultiHash>
 #include <QtCore/QMutex>
@@ -68,4 +68,4 @@ struct QMimeDatabasePrivate
 
 QT_END_NAMESPACE
 
-#endif // QMIMEDATABASE_P_H
+#endif   // QMIMEDATABASE_P_H_INCLUDED