quickopendataprovider.h 7.68 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
/*
 * This file is part of KDevelop
 *
 * Copyright 2007 David Nolden <david.nolden.kdevelop@art-master.de>
 *
 * 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 of the
 * License, 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 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.
 */
21 22
#ifndef KDEVPLATFORM_QUICKOPENDATAPROVIDER_H
#define KDEVPLATFORM_QUICKOPENDATAPROVIDER_H
23

24 25 26
#include <QList>
#include <QObject>
#include <QSet>
Kevin Funk's avatar
Kevin Funk committed
27
#include <QExplicitlySharedDataPointer>
28

Kevin Funk's avatar
Kevin Funk committed
29
#include <language/languageexport.h>
30

31 32
class QString;
class QStringList;
33
class QIcon;
34 35

namespace KDevelop {
36
class IndexedString;
37

38 39 40 41 42 43 44 45 46 47 48 49
/**
 * Hint: When implementing a data-provider, do not forget to export it! Else it won't work.
 * */

/**
 * If your plugin manages a list of files, you can use this to return that list.
 * The file-list can be queried by other data-providers(for example functions/methods) so they
 * can manipulate their content based on those file-lists. The file-list should not be filtered at all,
 * it should only depend on the enabled models/items
 *
 * Example: A list of files in the include-path, a list of files in the project, etc.
 * */
50 51 52
class KDEVPLATFORMLANGUAGE_EXPORT QuickOpenFileSetInterface
{
public:
53
    virtual QSet<IndexedString> files() const = 0;
54 55
    virtual ~QuickOpenFileSetInterface();
};
56 57 58
/**
 * You can use this as additional base-class for your embedded widgets to get additional interaction
 * */
59 60 61
class KDEVPLATFORMLANGUAGE_EXPORT QuickOpenEmbeddedWidgetInterface
{
public:
David Nolden's avatar
David Nolden committed
62
    virtual ~QuickOpenEmbeddedWidgetInterface();
63
    ///Is called when the keyboard-shortcut "next" is triggered on the widget, which currently is ALT+Right
64
    virtual bool next() = 0;
65
    ///Is called when the keyboard-shortcut "previous" is triggered on the widget, which currently is ALT+Left
66
    virtual bool previous() = 0;
67
    ///Is called when the keyboard-shortcut "scroll up" is triggered on the widget, which currently is ALT+Up
68
    virtual bool up() = 0;
69
    ///Is called when the keyboard-shortcut "scroll down" is triggered on the widget, which currently is ALT+Down
70
    virtual bool down() = 0;
71 72
    ///Is called when the keyboard-shortcut "back" is triggered on the widget, which currently is ALT+Backspace
    virtual void back() = 0;
73 74 75 76
    ///Is called when the keyboard-shortcut "accept" is triggered on the widget, which currently is ALT+Return
    virtual void accept() = 0;
    ///Reset the navigation state to the state before keyboard interaction
    virtual void resetNavigationState() = 0;
77 78
};

79
/**
David Faure's avatar
David Faure committed
80
 * Reimplement this to represent single entries within the quickopen list.
81
 * */
82 83 84 85
class KDEVPLATFORMLANGUAGE_EXPORT QuickOpenDataBase
    : public QSharedData
{
public:
86
    virtual ~QuickOpenDataBase();
87 88 89 90 91

    ///Return the text to be shown in the list for this item
    virtual QString text() const = 0;

    virtual QString htmlDescription() const = 0;
92

93 94 95 96 97 98
    /**Can return Custom highlighting triplets as explained in
     * the kde header ktexteditor/codecompletionmodel.h
     * The default-implementation returns an empty list, which means no
     * special highlighting will be applied.
     * */
    virtual QList<QVariant> highlighting() const;
99 100 101 102 103 104 105

    /**
     * May return an icon to mark the item in the quickopen-list.
     * The standard-implementation returns an invalid item, which means that
     * no icon will be shown.
     * */
    virtual QIcon icon() const;
106 107 108 109 110 111 112 113 114

    /**
     * Is called when the item should be executed.
     *
     * @param filterText Current content of the quickopen-dialogs filter line-edit.
     *                   If this is changed, and false is returned, the content of the
     *                   line-edit will be changed according to the new text.
     * @return Whether the dialog should be closed.
     * */
115
    virtual bool execute(QString& filterText) = 0;
116 117 118 119 120 121 122 123 124 125 126 127 128

    /**
     * Return true here if this data-item should be expandable with
     * an own embedded widget.
     * The default-implementation returns false.
     * */
    virtual bool isExpandable() const;

    /**
     * This will be called if isExpandable() returns true.
     *
     * A widget should be returned that will be embedded into the quickopen-list.
     * The widget will be owned by the quickopen-list and will be deleted at will.
129 130 131
     *
     * If the widget can be dynamic_cast'ed to QuickOpenEmbeddedWidgetInterface,
     * the additional interaction defined there will be possible.
132
     *
133 134 135
     * The default-implementation returns 0, which means no widget will be shown.
     * */
    virtual QWidget* expandingWidget() const;
136 137
};

138
using QuickOpenDataPointer = QExplicitlySharedDataPointer<QuickOpenDataBase>;
139 140 141 142

/**
 * Use this interface to provide custom quickopen-data to the quickopen-widget.
 *
143 144
 * If possible, you should use KDevelop::Filter (@file quickopenfilter.h )
 * to implement the actual filtering, so it is consistent.
145 146
 * */

147 148 149 150 151 152
class KDEVPLATFORMLANGUAGE_EXPORT QuickOpenDataProviderBase
    : public QObject
{
    Q_OBJECT

public:
153
    ~QuickOpenDataProviderBase() override;
154 155 156 157

    /**
     * For efficiency, all changes to the filter-text are provided by the following 3 difference-operations.
     * */
158

David Nolden's avatar
David Nolden committed
159 160 161 162 163
    /**
     * Search-text was changed.
     * This is called whenever the search-text was changed, and the UI should be updated.
     * Store the text to track the exact difference.
     * */
164
    virtual void setFilterText(const QString& text) = 0;
165

166 167 168
    /**
     * Filter-text should be completely reset and the context re-computed.
     * */
David Nolden's avatar
David Nolden committed
169
    virtual void reset() = 0;
170

171 172 173
    /**
     * Returns the count of items this provider currently represents
     * */
174 175
    virtual uint itemCount() const = 0;

176 177 178 179 180
    /**
     * Returns the count of *unfiltered* items this provider currently represents
     */
    virtual uint unfilteredItemCount() const = 0;

181
    /**
182 183
     * Returns the data-item for a given row.
     *
184 185 186 187 188
     * Generally, the items must addressed alphabetically,
     * they will be displayed in the same order in the
     * quickopen list.
     *
     * For performance-reasons the underlying models should
189
     * create the QuickOpenDataBase items on demand, because only
190
     * those that will really be shown will be requested.
191
     *
192
     * @param row Index of item to be returned.
193
     * */
194
    virtual QuickOpenDataPointer data(uint row) const  = 0;
195 196

    /**
197 198 199 200
     * If the data-provider supports multiple different scopes/items, this will be called
     * with the enabled scopes/items.
     * If the data-provider supports only one scope/item, this can be ignored.
     * The lists contains all scopes/items, even those that are not supported by this provider.
201
     * */
202
    virtual void enableData(const QStringList& items, const QStringList& scopes);
203 204
};

205 206 207
/**
 * Try parsing string according to "path_to_file":"line number" template. "line number" may be empty.
 * @param from Source string
208 209 210
 * @param path Set to parsed path to file, or left unchanged if @p from doesn't match the template. May refer to the same object as @p from
 * @param lineNumber Set to parsed line number, zero if "line number" is empty or left unchanged if @p from doesn't match the template.
 * @return Whether @p from did match the expected template.
211 212
 * */
bool KDEVPLATFORMLANGUAGE_EXPORT extractLineNumber(const QString& from, QString& path, uint& lineNumber);
213 214 215
}

#endif