* documentation updates

* don't trigger an assertion if no icon size is spezified by the view, just don't generate a preview in this case

svn path=/trunk/KDE/kdebase/apps/; revision=863328

2 files changed, 30 insertions, 10 deletions

diff --git a/src/kfilepreviewgenerator.cpp b/src/kfilepreviewgenerator.cpp
index e81f66980..b55f60516 100644
--- a/src/kfilepreviewgenerator.cpp
+++ b/src/kfilepreviewgenerator.cpp
@@ -82,7 +82,7 @@ private:
 
 KFilePreviewGenerator::KFilePreviewGenerator(QAbstractItemView* parent, KDirSortFilterProxyModel* model) :
     QObject(parent),
-    m_showPreview(false),
+    m_showPreview(true),
     m_clearItemQueues(true),
     m_hasCutSelection(false),
     m_pendingVisiblePreviews(0),
@@ -98,7 +98,9 @@ KFilePreviewGenerator::KFilePreviewGenerator(QAbstractItemView* parent, KDirSort
     m_pendingItems(),
     m_dispatchedItems()
 {
-    Q_ASSERT(m_view->iconSize().isValid());  // each view must provide its current icon size
+    if (!m_view->iconSize().isValid()) {
+        m_showPreview = false;
+    }
 
     m_dirModel = static_cast<KDirModel*>(m_proxyModel->sourceModel());
     connect(m_dirModel->dirLister(), SIGNAL(newItems(const KFileItemList&)),
@@ -140,6 +142,12 @@ KFilePreviewGenerator::~KFilePreviewGenerator()
 
 void KFilePreviewGenerator::setShowPreview(bool show)
 {
+    if (show && !m_view->iconSize().isValid()) {
+        // the view must provide an icon size, otherwise the showing
+        // off previews will get ignored
+        return;
+    }
+    
     if (m_showPreview != show) {
         m_showPreview = show;
         m_cutItemsCache.clear();
diff --git a/src/kfilepreviewgenerator.h b/src/kfilepreviewgenerator.h
index 47aff66a7..6d720fefc 100644
--- a/src/kfilepreviewgenerator.h
+++ b/src/kfilepreviewgenerator.h
@@ -34,7 +34,7 @@ class KMimeTypeResolver;
 class QAbstractItemView;
 
 /**
- * @brief Manages the icon state of a directory model.
+ * @brief Generates previews for files of an item view.
  *
  * Per default a preview is generated for each item.
  * Additionally the clipboard is checked for cut items.
@@ -54,22 +54,34 @@ class KFilePreviewGenerator : public QObject
     Q_OBJECT
 
 public:
+    /**
+     * @param parent  Item view containing the file items where previews should
+     *                be generated. It is mandatory that the item view specifies
+     *                an icon size by QAbstractItemView::setIconSize(), otherwise
+     *                no previews will be generated.
+     * @param model   Model of the item view.
+     */
     KFilePreviewGenerator(QAbstractItemView* parent, KDirSortFilterProxyModel* model);
     virtual ~KFilePreviewGenerator();
+    
+    /**
+     * If \a show is set to true, a preview is generated for each item. If \a show
+     * is false, the MIME type icon of the item is shown instead. Per default showing
+     * of the preview is turned on. Note that it is mandatory that the item view
+     * specifies an icon size by QAbstractItemView::setIconSize(), otherwise
+     * KFilePreviewGenerator::showPreview() will always return false.
+     */
     void setShowPreview(bool show);
     bool showPreview() const;
 
     /**
-     * Updates the previews for all already available items. It is only necessary
-     * to invoke this method when the icon size of the abstract item view has
-     * been changed.
+     * Updates the previews for all already available items. Usually It is only
+     * necessary to invoke this method when the icon size of the abstract item view
+     * has been changed by QAbstractItemView::setIconSize().
      */
     void updatePreviews();
 
-    /**
-     * Cancels all pending previews. Should be invoked when the URL of the item
-     * view has been changed.
-     */
+    /** Cancels all pending previews. */
     void cancelPreviews();
 
 private slots: