125 lines
4.2 KiB
C++
125 lines
4.2 KiB
C++
/*
|
|
* Copyright 2009 Aaron Seigo <aseigo@kde.org>
|
|
*
|
|
* This program is free software; you can redistribute it and/or modify
|
|
* it under the terms of the GNU Library General Public License as
|
|
* published by the Free Software Foundation; either version 2, or
|
|
* (at your option) any later version.
|
|
*
|
|
* This program 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 General Public License for more details
|
|
*
|
|
* You should have received a copy of the GNU Library General Public
|
|
* License along with this program; if not, write to the
|
|
* Free Software Foundation, Inc.,
|
|
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
|
|
*/
|
|
|
|
#ifndef PLASMA_RUNNERSYNTAX_H
|
|
#define PLASMA_RUNNERSYNTAX_H
|
|
|
|
#include <QString>
|
|
#include <QStringList>
|
|
|
|
#include <plasma/plasma.h>
|
|
|
|
namespace Plasma
|
|
{
|
|
|
|
class RunnerSyntaxPrivate;
|
|
/**
|
|
* @class RunnerSyntax
|
|
* @since 4.3
|
|
*
|
|
* Represents a query prototype that the runner accepts. These can be
|
|
* created and registered with AbstractRunner::addSyntax(Syntax &) to
|
|
* allow applications to show to the user what the runner is currently
|
|
* capable of doing
|
|
*/
|
|
class PLASMA_EXPORT RunnerSyntax
|
|
{
|
|
public:
|
|
/**
|
|
* Constructs a simple syntax object
|
|
*
|
|
* @arg exampleQuery an example of the query, with :q: placed wherever
|
|
* search term text might appear. e.g. if the runner
|
|
* accepts "keyword some random text" then the value
|
|
* of this parameter should be "keyword :q:"
|
|
* @arg descrition A description of what the described syntax does from
|
|
* the user's point of view.
|
|
*/
|
|
RunnerSyntax(const QString &exampleQuery, const QString &description);
|
|
|
|
/**
|
|
* Copy constructor
|
|
*/
|
|
RunnerSyntax(const RunnerSyntax &other);
|
|
|
|
/**
|
|
* Assignment operator
|
|
*/
|
|
RunnerSyntax &operator=(const RunnerSyntax &rhs);
|
|
|
|
/**
|
|
* Adds a synonymous example query to this Syntax. Some runners may
|
|
* accept multiple formulations of keywords to trigger the same behaviour.
|
|
* This allows the runner to show these relationships by grouping the
|
|
* example queries into one Syntax object
|
|
*
|
|
* @arg exampleQuery an example of the query, with :q: placed wherever
|
|
* search term text might appear. e.g. if the runner
|
|
* accepts "keyword some random text" then the value
|
|
* of this parameter should be "keyword :q:"
|
|
*/
|
|
void addExampleQuery(const QString &exampleQuery);
|
|
|
|
/**
|
|
* @return the example queries associated with this Syntax object
|
|
*/
|
|
QStringList exampleQueries() const;
|
|
|
|
/**
|
|
* @return the example queries associated with this Syntax object, with
|
|
* the searchTermDescription replacing instances of :q:. Used for showing
|
|
* the queries in the user interface.
|
|
*/
|
|
QStringList exampleQueriesWithTermDescription() const;
|
|
|
|
/**
|
|
* Sets the description for the syntax, describing what it does from
|
|
* the user's point of view.
|
|
*/
|
|
void setDescription(const QString &description);
|
|
|
|
/**
|
|
* @return the description of what the syntax does from the user's
|
|
* point of view
|
|
*/
|
|
QString description() const;
|
|
|
|
/**
|
|
* Sets the text that should be used to replace instances of :q:
|
|
* in the text. By default this is the generic phrase "search term".
|
|
* If the syntax expects a specific kind of input, it may be defined
|
|
* here. A syntax used by a runner that changes the brightness of the display
|
|
* may set this to "brightness" for instance.
|
|
*/
|
|
void setSearchTermDescription(const QString &description);
|
|
|
|
/**
|
|
* @return a description of the search term for this syntax
|
|
*/
|
|
QString searchTermDescription() const;
|
|
|
|
private:
|
|
RunnerSyntaxPrivate *const d;
|
|
};
|
|
|
|
} // namespace Plasma
|
|
|
|
#endif // multiple inclusion guard
|
|
|