← Back to branch summary

~ubuntu-branches/ubuntu/natty/kde4libs/natty-proposed

« back to all changes in this revision

Viewing changes to nepomuk/utils/facetmodel.h

  • Committer: Bazaar Package Importer
  • Author(s): Jonathan Riddell, Scott Kitterman, Jonathan Riddell
  • Date: 2010-11-22 17:59:02 UTC
  • mfrom: (1.6.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20101122175902-yubxubd0pg6hn11z
Tags: 4:4.5.80a-0ubuntu1
[ Scott Kitterman ]
* New upstream beta release
  - Refreshed all patches
  - Updated debian/patches/10_make_libkdeinit4_private.diff to use Qfile
    instead of Qstring in kdecore/kernel/kstandarddirs_unix.cpp
  - Updated debian/patches/kubuntu_01_kubuntu_useragent.diff to provide
    Kubuntu in the Konqueror user agen string with the changes in
    kio/kio/kprotocolmanager.cpp
  - Partially updated debian/patches/kubuntu_05_langpack_desktop_files.diff
    and left the balance in kdecore/localization/klocale.cpp.rej for later
    revision
  - Update debian/patches/kubuntu_06_user_disk_mounting.diff for changes in
    solid/solid/backends/hal/halstorageaccess.cpp
  - Remove debian/patches/kubuntu_71_backport_plasma_webview_changes.diff
    (backported from upstream, so already present now)
  - Add minimum version for libattica-dev of 0.1.90 to build-depends
  - Bump minimum version for libsoprano-dev build-depend to 2.5.60
  - Add minimum version for shared-desktop-ontologies of 0.5 in build-dep

[ Jonathan Riddell ]
* Add build-depends on grantlee, libudev-dev, hupnp (FIXME needs packaging fixes)
* Update kubuntu_04_add_langpack_path.diff 28_find_old_kde4_html_documentation.diff
  22_hack_in_etc_kde4_in_kstandarddirs.diff for QT_NO_CAST_FROM_ASCII
* Update kubuntu_05_langpack_desktop_files.diff for new upstream code
* Add kubuntu_78_solid_trunk.diff to fix solid linking
* Add libnepomukutils4 package for new library
* Don't install kcm_ssl for now, e-mailed upstream to suggest moving to kdebase
* Add kubuntu_79_knewstuff_fix.diff to fix compile broken by non-trunk commit
  http://websvn.kde.org/?view=revision&revision=1199825
* kdelibs5-data replaces old kdebase-runtime-data due to moved file
* Add kubuntu_80_find_hupnp.diff to find hupnp include files, committed upstream

Show diffs side-by-side

added added

removed removed

Lines of Context:
nepomuk/utils/facetmodel.h
 
1
/*
 
2
   This file is part of the Nepomuk KDE project.
 
3
   Copyright (C) 2010 Sebastian Trueg <trueg@kde.org>
 
4
 
 
5
   This library is free software; you can redistribute it and/or
 
6
   modify it under the terms of the GNU Lesser General Public
 
7
   License as published by the Free Software Foundation; either
 
8
   version 2.1 of the License, or (at your option) version 3, or any
 
9
   later version accepted by the membership of KDE e.V. (or its
 
10
   successor approved by the membership of KDE e.V.), which shall
 
11
   act as a proxy defined in Section 6 of version 3 of the license.
 
12
 
 
13
   This library is distributed in the hope that it will be useful,
 
14
   but WITHOUT ANY WARRANTY; without even the implied warranty of
 
15
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 
16
   Lesser General Public License for more details.
 
17
 
 
18
   You should have received a copy of the GNU Lesser General Public
 
19
   License along with this library.  If not, see <http://www.gnu.org/licenses/>.
 
20
*/
 
21
 
 
22
#ifndef _NEPOMUK_QUERY_FACET_MODEL_H_
 
23
#define _NEPOMUK_QUERY_FACET_MODEL_H_
 
24
 
 
25
#include "query.h"
 
26
#include "term.h"
 
27
#include "nepomukutils_export.h"
 
28
 
 
29
#include <QtCore/QAbstractItemModel>
 
30
#include <QtCore/QList>
 
31
 
 
32
namespace Nepomuk {
 
33
    namespace Utils {
 
34
        class Facet;
 
35
 
 
36
        /**
 
37
         * \class FacetModel facetmodel.h Nepomuk/Utils/FacetModel
 
38
         *
 
39
         * \ingroup nepomuk_facets
 
40
         *
 
41
         * \brief A FacetModel contains a list of facets that are provided in a tree structure.
 
42
         *
 
43
         * The FacetModel manages a list of Facet instances that are layed out
 
44
         * in a tree structure in which the leafs are checkable. This allows to
 
45
         * easily configure the facets by clicking the tree.
 
46
         *
 
47
         * Facets are added via setFacets() and addFacet().
 
48
         *
 
49
         * The FacetModel can be used to create and augment queries using the queryTerm()
 
50
         * method and connecting to the queryTermChanged() signal. In addition %FacetModel
 
51
         * provides the extractFacetsFromTerm() method which \em converts a query into
 
52
         * facet selections. This is very convinient if the query comes from another source
 
53
         * like a query bookmark or another application.
 
54
         *
 
55
         * An improved user experience can be created by setting the final query used to
 
56
         * list the results via setClientQuery(). This allows the %FacetModel to filter
 
57
         * the available choices, hiding those that do not make sense with the current
 
58
         * result set or even showing facets that did not make sense before (compare the
 
59
         * ProxyFacet example in \ref nepomuk_facet_examples).
 
60
         *
 
61
         * Typically one would use FacetWidget instead of creating ones own FacetModel.
 
62
         *
 
63
         * \author Sebastian Trueg <trueg@kde.org>
 
64
         *
 
65
         * \since 4.6
 
66
         */
 
67
        class NEPOMUKUTILS_EXPORT FacetModel : public QAbstractItemModel
 
68
        {
 
69
            Q_OBJECT
 
70
 
 
71
        public:
 
72
            /**
 
73
             * Creates an empty facet model
 
74
             */
 
75
            FacetModel( QObject* parent = 0 );
 
76
 
 
77
            /**
 
78
             * Destructor
 
79
             */
 
80
            ~FacetModel();
 
81
 
 
82
            /**
 
83
             * Special roles FacetModel provides through data() in
 
84
             * addition to the standard Qt roles.
 
85
             *
 
86
             * \sa Qt::ItemDataRole
 
87
             */
 
88
            enum CustomRoles {
 
89
                /**
 
90
                 * Provides a pointer to the Facet instance itself.
 
91
                 * Used internally.
 
92
                 */
 
93
                FacetRole = 235265643
 
94
            };
 
95
 
 
96
            /**
 
97
             * Reimplemented to provide facet data to Qt's model/view framework.
 
98
             */
 
99
            int columnCount( const QModelIndex& parent = QModelIndex() ) const;
 
100
 
 
101
            /**
 
102
             * Reimplemented to provide facet data to Qt's model/view framework.
 
103
             */
 
104
            QVariant data( const QModelIndex& index, int role = Qt::DisplayRole ) const;
 
105
 
 
106
            /**
 
107
             * Reimplemented to provide facet data to Qt's model/view framework.
 
108
             */
 
109
            bool setData( const QModelIndex& index, const QVariant& value, int role );
 
110
 
 
111
            /**
 
112
             * Reimplemented to provide facet data to Qt's model/view framework.
 
113
             */
 
114
            bool hasChildren(const QModelIndex &parent) const;
 
115
 
 
116
            /**
 
117
             * Reimplemented to provide facet data to Qt's model/view framework.
 
118
             */
 
119
            QModelIndex parent( const QModelIndex& index ) const;
 
120
 
 
121
            /**
 
122
             * Reimplemented to provide facet data to Qt's model/view framework.
 
123
             */
 
124
            int rowCount( const QModelIndex& parent = QModelIndex() ) const;
 
125
 
 
126
            /**
 
127
             * Reimplemented to provide facet data to Qt's model/view framework.
 
128
             */
 
129
            QModelIndex index( int row, int column, const QModelIndex& parent = QModelIndex() ) const;
 
130
 
 
131
            /**
 
132
             * Reimplemented to provide facet data to Qt's model/view framework.
 
133
             */
 
134
            Qt::ItemFlags flags( const QModelIndex& index ) const;
 
135
 
 
136
            /**
 
137
             * \return All Facet instances added via addFacet() and setFacets().
 
138
             */
 
139
            QList<Facet*> facets() const;
 
140
 
 
141
            /**
 
142
             * Construct a query term from the selected facets in this model.
 
143
             *
 
144
             * \return A new query which combines the facets in this model.
 
145
             */
 
146
            Query::Term queryTerm() const;
 
147
 
 
148
        public Q_SLOTS:
 
149
            /**
 
150
             * Extract as many facets from a query as possible. This method is not able to handle all
 
151
             * kinds of queries but works well on queries created via queryTerm().
 
152
             *
 
153
             * Facets supported by this model will be extracted from \p query and configured
 
154
             * accordingly in the model.
 
155
             *
 
156
             * Be aware that this method is not related to setClientQuery(). It is intended to
 
157
             * split up a query in order to represent it graphically. It will, however change the
 
158
             * client query in order to achieve the best possible term extraction. Thus, one would typically
 
159
             * call setClientQuery after calling this method if \p query does not already contain
 
160
             * the full client query.
 
161
             *
 
162
             * Typically a client would call this method and then try to handle the returned
 
163
             * rest query in another way like converting it into a desktop user query string
 
164
             * that can be shown in a search line edit. Another idea would be to use custom
 
165
             * filters or a simple warning for the user that additional conditions are in place
 
166
             * that could not be "translated" into facets.
 
167
             *
 
168
             * \return The rest query after facets have been extracted.
 
169
             */
 
170
            Nepomuk::Query::Query extractFacetsFromQuery( const Nepomuk::Query::Query& query );
 
171
 
 
172
            /**
 
173
             * Can be used to set the full query the client is using (this includes facets
 
174
             * created through this model). It allows the facet system to disable certain
 
175
             * choices that would not change the result set or do not make sense otherwise.
 
176
             *
 
177
             * Be aware that this method is not related to extractFacetsFromTerm(). It is merely
 
178
             * intended to improve the overall user experienceby filtering the facet choices
 
179
             * depending on the current query.
 
180
             *
 
181
             * Typically a client would call both extractFacetsFromTerm() and setClientQuery()
 
182
             * seperately. However, they will often be called with the same query/term.
 
183
             *
 
184
             * \sa Facet::setClientQuery()
 
185
             */
 
186
            void setClientQuery( const Nepomuk::Query::Query& query );
 
187
 
 
188
            /**
 
189
             * Add \p facet to the model. Used to populate the model with facets.
 
190
             * Ownership of \p facet is transferred to the model.
 
191
             */
 
192
            void addFacet( Nepomuk::Utils::Facet* facet );
 
193
 
 
194
            /**
 
195
             * Set \p facets as the list of facets used in this model. Used to populate the model with facets.
 
196
             * Ownership of the facets is transferred to the model.
 
197
             */
 
198
            void setFacets( const QList<Nepomuk::Utils::Facet*>& facets );
 
199
 
 
200
            /**
 
201
             * Convenience method that clears the selection on all facets.
 
202
             * \sa Facet::clearSelection()
 
203
             */
 
204
            void clearSelection();
 
205
 
 
206
            /**
 
207
             * Remove all facets from the model.
 
208
             */
 
209
            void clear();
 
210
 
 
211
        Q_SIGNALS:
 
212
            /**
 
213
             * Emitted whenever the facets change, i.e. when the user changes the selection
 
214
             * or it is changed programmatically via extractFacetsFromQuery()
 
215
             */
 
216
            void queryTermChanged( const Nepomuk::Query::Term& term );
 
217
 
 
218
        private:
 
219
            class Private;
 
220
            Private* const d;
 
221
 
 
222
            Q_PRIVATE_SLOT( d, void _k_queryTermChanged() )
 
223
            Q_PRIVATE_SLOT( d, void _k_facetSelectionChanged( Nepomuk::Utils::Facet* ) )
 
224
            Q_PRIVATE_SLOT( d, void _k_facetLayoutChanged( Nepomuk::Utils::Facet* ) )
 
225
        };
 
226
    }
 
227
}
 
228
 
 
229
Q_DECLARE_METATYPE( Nepomuk::Utils::Facet* )
 
230
 
 
231
#endif