src/panels/information/metadatawidget.h

   1 /***************************************************************************
   2  *   Copyright (C) 2008 by Sebastian Trueg <trueg@kde.org>                 *
   3  *   Copyright (C) 2009 by Peter Penz <peter.penz@gmx.at>                  *
   4  *                                                                         *
   5  *   This program is free software; you can redistribute it and/or modify  *
   6  *   it under the terms of the GNU General Public License as published by  *
   7  *   the Free Software Foundation; either version 2 of the License, or     *
   8  *   (at your option) any later version.                                   *
   9  *                                                                         *
  10  *   This program is distributed in the hope that it will be useful,       *
  11  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  12  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  13  *   GNU General Public License for more details.                          *
  14  *                                                                         *
  15  *   You should have received a copy of the GNU General Public License     *
  16  *   along with this program; if not, write to the                         *
  17  *   Free Software Foundation, Inc.,                                       *
  18  *   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA            *
  19  ***************************************************************************/
  20
  21 #ifndef METADATAWIDGET_H
  22 #define METADATAWIDGET_H
  23
  24 #include <config-nepomuk.h>
  25 #ifdef HAVE_NEPOMUK
  26     #include <Nepomuk/Tag>
  27 #else
  28     // The HAVE_NEPOMUK macro cannot be used in combination with
  29     // Q_PRIVATE_SLOT, hence a workaround is used for environments
  30     // where Nepomuk is not available:
  31     namespace Nepomuk {
  32         typedef int Tag;
  33     }
  34 #endif
  35
  36 #include <kfileitem.h>
  37
  38 #include <QList>
  39 #include <QWidget>
  40
  41 class KUrl;
  42
  43 /**
  44  * @brief Shows the meta data of one or more file items.
  45  *
  46  * Meta data like name, size, rating, comment, ... are
  47  * shown as several rows containing a description and
  48  * the meta data value. It is possible for the user
  49  * to change specific meta data like rating, tags and
  50  * comment. The changes are stored automatically by the
  51  * meta data widget.
  52  */
  53 class MetaDataWidget : public QWidget
  54 {
  55     Q_OBJECT
  56
  57 public:
  58     /**
  59      * Allows to specify which general data should be hidden
  60      * by the meta data widget.
  61      * @see MetaDataWidget::setHiddenData()
  62      * @see MetaDataWidget::hiddenData()
  63      */
  64     enum MetaDataType
  65     {
  66         None = 0,
  67         TypeData = 1,
  68         SizeData= 2,
  69         ModifiedData = 4,
  70         OwnerData =  8,
  71         PermissionsData = 16,
  72         RatingData = 32,
  73         TagsData = 64,
  74         CommentData = 128
  75     };
  76     Q_DECLARE_FLAGS( MetaDataTypes, MetaDataType )
  77
  78     explicit MetaDataWidget(QWidget* parent = 0);
  79     virtual ~MetaDataWidget();
  80
  81     /**
  82      * Triggers the asynchronous loading of the meta data
  83      * for the file item \p item. Connect to the signal
  84      * loadingFinished() to be able to read the meta
  85      * data.
  86      */
  87     void setItem(const KFileItem& item);
  88
  89     /**
  90      * Triggers the asynchronous loading of the meta data
  91      * for the file items \p items. Connect to the signal
  92      * loadingFinished() to be able to read the meta
  93      * data.
  94      */
  95     void setItems(const KFileItemList& items);
  96
  97     /**
  98      * Convenience method for MetaDataWidget::setItem(const KFileItem&),
  99      * if the application has only an URL and no file item.
 100      * For performance reason it is recommended to use this convenience
 101      * method only if the application does not have a file item already.
 102      */
 103     void setItem(const KUrl& url);
 104
 105     /**
 106      * Convenience method for MetaDataWidget::setItems(const KFileItemList&),
 107      * if the application has only URLs and no file items.
 108      * For performance reason it is recommended to use this convenience
 109      * method only if the application does not have a file items already.
 110      */
 111     void setItems(const QList<KUrl>& urls);
 112
 113     KFileItemList items() const;
 114
 115     /**
 116      * Specifies which kind of data should be hidden (@see MetaDataWidget::Data).
 117      * Example: metaDataWidget->setHiddenData(MetaDataWidget::TypeData | ModifiedData);
 118      * Per default no data is hidden.
 119      */
 120     void setHiddenData(MetaDataTypes data);
 121
 122     /**
 123      * Returns which kind of data is hidden (@see MetaDataWidget::Data).
 124      * Example: if (metaDataWidget->hiddenData() & MetaDataWidget::TypeData) ...
 125      */
 126     MetaDataTypes hiddenData() const;
 127
 128     /**
 129      * Returns the rating for the currently set item(s). It is required
 130      * to wait for the signal loadingFinished() or ratingChanged()
 131      * to get a valid result.
 132      */
 133     unsigned int rating() const;
 134
 135     /**
 136      * Returns the tags for the currently set item(s). It is required
 137      * to wait for the signal loadingFinished() or tagsChanged()
 138      * to get a valid result.
 139      */
 140     QList<Nepomuk::Tag> tags() const;
 141
 142     /**
 143      * Returns the comment for the currently set item(s). It is required
 144      * to wait for the signal loadingFinished() or commentChanged()
 145      * to get a valid result.
 146      */
 147     QString comment() const;
 148
 149 signals:
 150     /**
 151      * Is emitted if the loading of the meta data has been finished
 152      * after invoking MetaDataWidget::setItem() or MetaDataWidget::setItems().
 153      */
 154     void loadingFinished();
 155
 156     /**
 157      * Is emitted after the user has changed the rating.
 158      * The changed rating is automatically stored already by
 159      * the meta data widget.
 160      * Note that the signal is not emitted if the rating has
 161      * indirectly been changed by MetaDataWidget::setItem() or
 162      * MetaDataWidget::setItems(). In this case connect to
 163      * the signal loadingFinished() instead.
 164      */
 165     void ratingChanged(const int rating);
 166
 167     /**
 168      * Is emitted after the user has changed the tags.
 169      * The changed tags are automatically stored already by
 170      * the meta data widget.
 171      * Note that the signal is not emitted if the tags have
 172      * indirectly been changed by MetaDataWidget::setItem() or
 173      * MetaDataWidget::setItems(). In this case connect to
 174      * the signal loadingFinished() instead.
 175      */
 176     void tagsChanged(const QList<Nepomuk::Tag>& tags);
 177
 178     /**
 179      * Is emitted after the user has changed the comment.
 180      * The changed comment is automatically stored already by
 181      * the meta data widget.
 182      * Note that the signal is not emitted if the comment has
 183      * indirectly been changed by MetaDataWidget::setItem() or
 184      * MetaDataWidget::setItems(). In this case connect to
 185      * the signal loadingFinished() instead.
 186      */
 187     void commentChanged(const QString& comment);
 188
 189 private:
 190     class Private;
 191     Private* d;
 192
 193     Q_PRIVATE_SLOT(d, void slotLoadingFinished())
 194     Q_PRIVATE_SLOT(d, void slotRatingChanged(unsigned int rating))
 195     Q_PRIVATE_SLOT(d, void slotTagsChanged(const QList<Nepomuk::Tag>& tags))
 196     Q_PRIVATE_SLOT(d, void slotCommentChanged(const QString& comment))
 197     Q_PRIVATE_SLOT(d, void slotMetaDataUpdateDone())
 198 };
 199
 200 Q_DECLARE_OPERATORS_FOR_FLAGS(MetaDataWidget::MetaDataTypes)
 201
 202 #endif