/usr/include/nepomuk/facet.h is in kdelibs5-dev 4:4.13.0-0ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 | /*
This file is part of the Nepomuk KDE project.
Copyright (C) 2010 Sebastian Trueg <trueg@kde.org>
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) version 3, or any
later version accepted by the membership of KDE e.V. (or its
successor approved by the membership of KDE e.V.), which shall
act as a proxy defined in Section 6 of version 3 of the license.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library. If not, see <http://www.gnu.org/licenses/>.
*/
#ifndef _NEPOMUK_QUERY_FACET_H_
#define _NEPOMUK_QUERY_FACET_H_
#include <QtCore/QObject>
#include "nepomukutils_export.h"
class KGuiItem;
namespace Nepomuk {
namespace Query {
class Term;
class Query;
}
namespace Utils {
/**
* \class Facet facet.h Nepomuk/Utils/Facet
*
* \ingroup nepomuk_facets
*
* \brief The base class for all facets used to create query filters.
*
* A Facet represents one aspect of a query like the resource type or
* the modification date. By providing a list of facets to the user they
* can interactively construct a query by restricting the result set step
* by step.
*
* A Facet can be seen as a list of choices presented to the user. Depending
* on the selection (which is typically triggered by user interaction) the
* Facet produces a resulting term() which is then used in the final query.
*
* Each facet needs to implement a set of methods describing the choices:
* count(), guiItem(), isSelected(), setSelected(), and clearSelection().
* In addition the term() method constructs the term this facet represents
* with its current selection.
*
* Methods selectFromTerm() and setClientQuery() are optional but allow for a
* more advanced usage and a better user experience. See the method documentation
* for details.
*
* Before implementing your own Facet subclass make sure that SimpleFacet or
* DynamicResourceFacet do not suit your needs.
*
* Facet also provides a set of static factory methods like createTagFacet() or
* createFileTypeFacet() to create standard facets that are useful in most
* query UI situations.
*
* \author Sebastian Trueg <trueg@kde.org>
*
* \since 4.6
*/
class NEPOMUKUTILS_EXPORT Facet : public QObject
{
Q_OBJECT
public:
/**
* Constructor
*/
Facet( QObject* parent = 0 );
/**
* Destructor
*/
virtual ~Facet();
/**
* A Facet can have one of three selection modes which is provided
* by selectionMode().
*/
enum SelectionMode {
/**
* All of the choices need to be matched. This typically
* means that all choices' terms are combined using an
* AndTerm.
*/
MatchAll,
/**
* At least one of the choices needs to be matched. This typically
* means that all choices' terms are combined using an
* OrTerm.
*/
MatchAny,
/**
* Exactly one of the choices needs to match. This means
* that the Facet is exclusive, ie. only one choice
* can be selected at all times.
*/
MatchOne
};
/**
* The selection mode used by this facet. The GUI client
* can make use of this value to adjust the GUI accordingly.
* A typical example would be using radio buttons for
* MatchOne facets.
*/
virtual SelectionMode selectionMode() const = 0;
/**
* The term currently produced by this facet. This is dependant
* on the subclass implementation and the selectionMode(). The SimpleFacet for example
* uses an AndTerm or an OrTerm to combine all its terms in MatchAll or MatchAny
* mode while it returns the one selected term in MatchOne mode.
*/
virtual Query::Term queryTerm() const = 0;
/**
* The number of choices this facet provides.
*/
virtual int count() const = 0;
/**
* The text to be displayed at \p index. The default implementation makes
* use of guiItem(). Normally subclasses would implement guItem() instead
* of this method.
*/
virtual QString text( int index ) const;
/**
* The parameters used to render the choice at \p index.
*/
virtual KGuiItem guiItem( int index ) const;
/**
* \return \p true if the choice at \p index is selected, \p false otherwise.
*/
virtual bool isSelected( int index ) const = 0;
/**
* The client query set via setClientQuery(). See the documentation of setClientQuery()
* for details.
*/
Query::Query clientQuery() const;
/**
* Creates a new Facet that allows to filter on the file type. Normally
* this facet would be used in combination with a FileQuery.
* \sa createTypeFacet()
*/
static Facet* createFileTypeFacet( QObject* parent = 0 );
/**
* Creates a new Facet that allows to filter on the resource type without
* a restriction to files.
* \sa createFileTypeFacet()
*/
static Facet* createTypeFacet( QObject* parent = 0 );
/**
* Creates a new Facet that allows to filter on the date. This includes
* the modification, creation, and access dates.
* \sa Query::dateRangeQuery()
*/
static Facet* createDateFacet( QObject* parent = 0 );
/**
* Creates a new Facet that allows to filter on tags, i.e. search for
* resources that are tagged with the selected tags. The list of tags
* is dynamic. This means it has a default selection of the most often
* used ones and provides a means to access all tags through a dialog.
*/
static Facet* createTagFacet( QObject* parent = 0 );
/**
* Creates a new Facet that allows to sort the results by one of several
* criteria like last modification date or a score calculated by the
* %Nepomuk system.
* Using this facet does only make sense when displaying sorted results
* or when using a limit on the number of results.
*/
static Facet* createPriorityFacet( QObject* parent = 0 );
/**
* Creates a new Facet that allows to filter on the rating of resources.
*/
static Facet* createRatingFacet( QObject* parent = 0 );
public Q_SLOTS:
/**
* Clear the selection. If selectionMode() is MatchOne the first
* choice should be selected.
*/
virtual void clearSelection() = 0;
/**
* Called by client code to change the selection.
*
* \param index The index of the choice for which the selection should
* be changed.
* \param selected If \p true the item should be selected, otherwise
* it should be deselected.
*/
virtual void setSelected( int index, bool selected = true ) = 0;
/**
* If a client application provides several ways to construct a query
* (one could think of a query editor which allows to insert certain
* constraints or simply another application providing a base query)
* the user expects to be able to modify that query using the available
* facets. Thus, a Facet should be able to extract parts from a query.
*
* Implement this method to create a selection based on the contents of
* \p term. The selection of the facet must only change if all of \p term
* can be used. This means that if \p term is for example an OrTerm and
* the Facet can only handle one of the sub terms it needs to ignore the
* whole term. FacetModel::setQuery() internally calls selectFromTerm()
* on all its facets.
*
* A simple example is SimpleFacet which compares all its terms which have been
* added via SimpleFacet::addTerm() to \p term. Depending on the selectionMode()
* it also checks for AndTerm or OrTerm.
*
* \warning Implementations of this method should \em never reset the selection
* before handling \p term. Instead the method should work similar to setSelected(),
* ie. in MatchAll or MatchAny facets calling it multiple times should select
* multiple choices.
*
* \return \p true if all of \p term could be used to select choices in
* this term, \p false otherwise.
*/
virtual bool selectFromTerm( const Nepomuk::Query::Term& queryTerm ) = 0;
/**
* The FacetModel will set this to the final query that has been constructed
* from the facets and any other query part set by the client via FacetModel::setClientQuery().
* The facet may use this information to filter the presented choices. A typical example
* is to only show terms that would actually change the result set. The latter is what
* DynamicResourceFacet does.
*/
void setClientQuery( const Nepomuk::Query::Query& query );
Q_SIGNALS:
/**
* Emitted when the term of the facet changed, ie. when the value returned by term()
* has changed.
*
* Subclasses should call setTermChanged() instead of emitting this signal manually.
*
* Be aware that in most situations queryTermChanged() and selectionChanged() will
* have to be emitted at the same time.
*/
void queryTermChanged( Nepomuk::Utils::Facet* facet, const Nepomuk::Query::Term& queryTerm );
/**
* Emitted when the layout of the facet changed, ie. one of count(), guitItem(), or
* text() return different values.
*
* Subclasses should call setLayoutChanged() instead of emitting this signal manually.
*/
void layoutChanged( Nepomuk::Utils::Facet* facet );
/**
* Emitted when the selection changed - normally triggered by a call to setSelected().
*
* Subclasses should call setSelectionChanged() instead of emitting this signal manually.
*
* Be aware that in most situations queryTermChanged() and selectionChanged() will
* have to be emitted at the same time.
*/
void selectionChanged( Nepomuk::Utils::Facet* facet );
protected Q_SLOTS:
/**
* Subclasses should call this method instead of emitting termChanged() manually.
*/
void setQueryTermChanged();
/**
* Subclasses should call this method instead of emitting layoutChanged() manually.
*/
void setLayoutChanged();
/**
* Subclasses should call this method instead of emitting selectionChanged() manually.
*/
void setSelectionChanged();
protected:
/**
* This method is called from setClientQuery() and can be reimplemented by subclasses.
*
* The default implementation does nothing.
*/
virtual void handleClientQueryChange();
private:
class FacetPrivate;
FacetPrivate* const d;
};
}
}
#endif
|