diff --git a/src/kcombobox.h b/src/kcombobox.h index 89b5e3c..2035412 100644 --- a/src/kcombobox.h +++ b/src/kcombobox.h @@ -1,533 +1,535 @@ /* This file is part of the KDE libraries Copyright (c) 2000,2001 Dawit Alemayehu Copyright (c) 2000,2001 Carsten Pfeiffer This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License (LGPL) as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. 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; see the file COPYING.LIB. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ #ifndef KCOMBOBOX_H #define KCOMBOBOX_H #include #include #include #include class KCompletionBox; class KComboBoxPrivate; class QLineEdit; class QMenu; /** + * @class KComboBox kcombobox.h KComboBox + * * @short A combo box with completion support. * * This widget inherits from QComboBox and implements the following * additional features: * @li a completion object that provides both automatic * and manual text completion as well as text rotation * @li configurable key bindings to activate these features * @li a popup menu item that can be used to allow the user to change * the text completion mode on the fly. * * To support these new features, KComboBox emits a few additional signals * such as completion(const QString&) and textRotation(KeyBindingType). * The completion signal can be connected to a slot that will assist the user in * filling out the remaining text while the rotation signal can be used to traverse * through all possible matches whenever text completion results in multiple matches. * Additionally, the returnPressed() and returnPressed(const QString&) * signals are emitted when the user presses the Enter/Return key. * * KCombobox by default creates a completion object when you invoke the * completionObject(bool) member function for the first time or * explicitly use setCompletionObject(KCompletion*, bool) to assign your * own completion object. Additionally, to make this widget more functional, * KComboBox will by default handle text rotation and completion events * internally whenever a completion object is created through either one of the * methods mentioned above. If you do not need this functionality, simply use * KCompletionBase::setHandleSignals(bool) or alternatively set the boolean * parameter in the @p setCompletionObject call to false. * * Beware: The completion object can be deleted on you, especially if a call * such as setEditable(false) is made. Store the pointer at your own risk, * and consider using QPointer. * * The default key bindings for completion and rotation are determined from the * global settings in KStandardShortcut. These values, however, can be overridden * locally by invoking KCompletionBase::setKeyBinding(). The values can * easily be reverted back to the default settings by calling * useGlobalSettings(). An alternate method would be to default individual * key bindings by using setKeyBinding() with the default second argument. * * A non-editable combo box only has one completion mode, @p CompletionAuto. * Unlike an editable combo box, the CompletionAuto mode works by matching * any typed key with the first letter of entries in the combo box. Please note * that if you call setEditable(false) to change an editable combo box to a * non-editable one, the text completion object associated with the combo box will * no longer exist unless you created the completion object yourself and assigned * it to this widget or you called setAutoDeleteCompletionObject(false). In other * words do not do the following: * * \code * KComboBox* combo = new KComboBox(true, this); * KCompletion* comp = combo->completionObject(); * combo->setEditable(false); * comp->clear(); // CRASH: completion object does not exist anymore. * \endcode * * * A read-only KComboBox will have the same background color as a * disabled KComboBox, but its foreground color will be the one used for * the editable mode. This differs from QComboBox's implementation * and is done to give visual distinction between the three different modes: * disabled, read-only, and editable. * * \b Usage \n * * To enable the basic completion feature: * * \code * KComboBox *combo = new KComboBox(true, this); * KCompletion *comp = combo->completionObject(); * // Connect to the return pressed signal - optional * connect(combo,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&))); * * // Provide the to be completed strings. Note that those are separate from the combo's * // contents. * comp->insertItems(someQStringList); * \endcode * * To use your own completion object: * * \code * KComboBox *combo = new KComboBox(this); * KUrlCompletion *comp = new KUrlCompletion(); * combo->setCompletionObject(comp); * // Connect to the return pressed signal - optional * connect(combo,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&))); * \endcode * * Note that you have to either delete the allocated completion object * when you don't need it anymore, or call * setAutoDeleteCompletionObject(true); * * Miscellaneous function calls: * * \code * // Tell the widget not to handle completion and rotation * combo->setHandleSignals(false); * // Set your own completion key for manual completions. * combo->setKeyBinding(KCompletionBase::TextCompletion, Qt::End); * \endcode * * \image html kcombobox.png "KDE Combo Boxes, one non-editable, one editable with KUrlCompletion" * * @author Dawit Alemayehu */ class KCOMPLETION_EXPORT KComboBox : public QComboBox, public KCompletionBase //krazy:exclude=qclasses { Q_OBJECT Q_PROPERTY(bool autoCompletion READ autoCompletion WRITE setAutoCompletion) #ifndef KCOMPLETION_NO_DEPRECATED Q_PROPERTY(bool urlDropsEnabled READ urlDropsEnabled WRITE setUrlDropsEnabled) #endif Q_PROPERTY(bool trapReturnKey READ trapReturnKey WRITE setTrapReturnKey) Q_DECLARE_PRIVATE(KComboBox) public: /** * Constructs a read-only (or rather select-only) combo box. * * @param parent The parent object of this widget */ explicit KComboBox(QWidget *parent = nullptr); /** * Constructs an editable or read-only combo box. * * @param rw When @p true, widget will be editable. * @param parent The parent object of this widget. */ explicit KComboBox(bool rw, QWidget *parent = nullptr); /** * Destructor. */ virtual ~KComboBox(); /** * Deprecated to reflect Qt api changes * @deprecated since 4.5 */ #ifndef KCOMPLETION_NO_DEPRECATED KCOMPLETION_DEPRECATED void insertURL(const QUrl &url, int index = -1) { insertUrl(index < 0 ? count() : index, url); } KCOMPLETION_DEPRECATED void insertURL(const QPixmap &pixmap, const QUrl &url, int index = -1) { insertUrl(index < 0 ? count() : index, QIcon(pixmap), url); } KCOMPLETION_DEPRECATED void changeURL(const QUrl &url, int index) { changeUrl(index, url); } KCOMPLETION_DEPRECATED void changeURL(const QPixmap &pixmap, const QUrl &url, int index) { changeUrl(index, QIcon(pixmap), url); } #endif /** * Sets @p url into the edit field of the combo box. * * It uses QUrl::toDisplayString() so that the url is properly decoded for * displaying. */ void setEditUrl(const QUrl &url); /** * Appends @p url to the combo box. * * QUrl::toDisplayString() is used so that the url is properly decoded * for displaying. */ void addUrl(const QUrl &url); /** * Appends @p url with the @p icon to the combo box. * * QUrl::toDisplayString() is used so that the url is properly decoded * for displaying. */ void addUrl(const QIcon &icon, const QUrl &url); /** * Inserts @p url at position @p index into the combo box. * * QUrl::toDisplayString() is used so that the url is properly decoded * for displaying. */ void insertUrl(int index, const QUrl &url); /** * Inserts @p url with the @p icon at position @p index into * the combo box. * * QUrl::toDisplayString() is used so that the url is * properly decoded for displaying. */ void insertUrl(int index, const QIcon &icon, const QUrl &url); /** * Replaces the item at position @p index with @p url. * * QUrl::toDisplayString() is used so that the url is properly decoded * for displaying. */ void changeUrl(int index, const QUrl &url); /** * Replaces the item at position @p index with @p url and @p icon. * * QUrl::toDisplayString() is used so that the url is properly decoded * for displaying. */ void changeUrl(int index, const QIcon &icon, const QUrl &url); /** * Returns the current cursor position. * * This method always returns a -1 if the combo box is @em not * editable (read-only). * * @return Current cursor position. */ int cursorPosition() const; /** * Reimplemented from QComboBox. * * If @p true, the completion mode will be set to automatic. * Otherwise, it is defaulted to the global setting. This * method has been replaced by the more comprehensive * setCompletionMode(). * * @param autocomplete Flag to enable/disable automatic completion mode. */ virtual void setAutoCompletion(bool autocomplete); /** * Reimplemented from QComboBox. * * Returns @p true if the current completion mode is set * to automatic. See its more comprehensive replacement * completionMode(). * * @return @p true when completion mode is automatic. */ bool autoCompletion() const; /** * Enables or disables the popup (context) menu. * * This method only works if this widget is editable, and * allows you to enable/disable the context menu. It does nothing if invoked * for a non-editable combo box. * * By default, the context menu is created if this widget is editable. * Call this function with the argument set to false to disable the popup * menu. * * @param showMenu If @p true, show the context menu. * @deprecated since 4.5, use setContextMenuPolicy instead */ #ifndef KCOMPLETION_NO_DEPRECATED virtual KCOMPLETION_DEPRECATED void setContextMenuEnabled(bool showMenu); #endif /** * Enables/Disables handling of URL drops. * * If enabled and the user drops an URL, the decoded URL will * be inserted. Otherwise the default behavior of QComboBox is used, * which inserts the encoded URL. * * @param enable If @p true, insert decoded URLs * @deprecated since 5.0. Use lineEdit()->installEventFilter with a LineEditUrlDropEventFilter */ #ifndef KCOMPLETION_NO_DEPRECATED KCOMPLETION_DEPRECATED void setUrlDropsEnabled(bool enable); #endif /** * Returns @p true when decoded URL drops are enabled */ bool urlDropsEnabled() const; /** * Convenience method which iterates over all items and checks if * any of them is equal to @p text. * * If @p text is an empty string, @p false * is returned. * * @return @p true if an item with the string @p text is in the combo box. */ bool contains(const QString &text) const; /** * By default, KComboBox recognizes Key_Return and Key_Enter * and emits the returnPressed() signals, but it also lets the * event pass, for example causing a dialog's default button to * be called. * * Call this method with @p trap equal to true to make KComboBox * stop these events. The signals will still be emitted of course. * * Only affects editable combo boxes. * * @see setTrapReturnKey() */ void setTrapReturnKey(bool trap); /** * @return @p true if key events of Key_Return or Key_Enter will * be stopped; @p false if they will be propagated. * * @see setTrapReturnKey () */ bool trapReturnKey() const; /** * @returns the completion box that is used in completion mode * CompletionPopup and CompletionPopupAuto. * * This method will create a completion box by calling * KLineEdit::completionBox, if none is there yet. * * @param create Set this to false if you don't want the box to be created * i.e. to test if it is available. */ KCompletionBox *completionBox(bool create = true); /** * Reimplemented for internal reasons. API remains unaffected. * Note that QComboBox::setLineEdit is not virtual in Qt4, do not * use a KComboBox in a QComboBox pointer. * * NOTE: Only editable combo boxes can have a line editor. As such * any attempt to assign a line edit to a non-editable combo box will * simply be ignored. */ virtual void setLineEdit(QLineEdit *); /** * Reimplemented so that setEditable(true) creates a KLineEdit * instead of QLineEdit. * * Note that QComboBox::setEditable is not virtual, so do not * use a KComboBox in a QComboBox pointer. */ void setEditable(bool editable); Q_SIGNALS: /** * Emitted when the user presses the Enter key. * * Note that this signal is only emitted when the widget is editable. */ void returnPressed(); /** * Emitted when the user presses the Enter key. * * The argument is the current text being edited. This signal is just like * returnPressed() except that it contains the current text as its argument. * * Note that this signal is only emitted when the * widget is editable. */ void returnPressed(const QString &); /** * Emitted when the completion key is pressed. * * The argument is the current text being edited. * * Note that this signal is @em not available when the widget is non-editable * or the completion mode is set to @p CompletionNone. */ void completion(const QString &); /** * Emitted when the shortcut for substring completion is pressed. */ void substringCompletion(const QString &); /** * Emitted when the text rotation key bindings are pressed. * * The argument indicates which key binding was pressed. In this case this * can be either one of four values: @p PrevCompletionMatch, * @p NextCompletionMatch, @p RotateUp or @p RotateDown. * * Note that this signal is @em not emitted if the completion * mode is set to CompletionNone. * * @see KCompletionBase::setKeyBinding() for details */ void textRotation(KCompletionBase::KeyBindingType); /** * Emitted whenever the completion mode is changed by the user * through the context menu. */ void completionModeChanged(KCompletion::CompletionMode); /** * Emitted before the context menu is displayed. * * The signal allows you to add your own entries into the context menu. * Note that you must not store the pointer to the QPopupMenu since it is * created and deleted on demand. Otherwise, you can crash your app. * * @param contextMenu the context menu about to be displayed */ void aboutToShowContextMenu(QMenu *contextMenu); public Q_SLOTS: /** * Iterates through all possible matches of the completed text * or the history list. * * Depending on the value of the argument, this function either * iterates through the history list of this widget or all the * possible matches in whenever multiple matches result from a * text completion request. Note that the all-possible-match * iteration will not work if there are no previous matches, i.e. * no text has been completed and the *nix shell history list * rotation is only available if the insertion policy for this * widget is set either @p QComobBox::AtTop or @p QComboBox::AtBottom. * For other insertion modes whatever has been typed by the user * when the rotation event was initiated will be lost. * * @param type The key binding invoked. */ void rotateText(KCompletionBase::KeyBindingType type); /** * Sets the completed text in the line edit appropriately. * * This function is an implementation for * KCompletionBase::setCompletedText. */ void setCompletedText(const QString &) Q_DECL_OVERRIDE; /** * Sets @p items into the completion box if completionMode() is * CompletionPopup. The popup will be shown immediately. */ void setCompletedItems(const QStringList &items, bool autosubject = true) Q_DECL_OVERRIDE; /** * Selects the first item that matches @p item. * * If there is no such item, it is inserted at position @p index * if @p insert is true. Otherwise, no item is selected. */ void setCurrentItem(const QString &item, bool insert = false, int index = -1); protected Q_SLOTS: /** * Completes text according to the completion mode. * * Note: this method is not invoked if the completion mode is * set to @p CompletionNone. Also if the mode is set to @p CompletionShell * and multiple matches are found, this method will complete the * text to the first match with a beep to indicate that there are * more matches. Then any successive completion key event iterates * through the remaining matches. This way the rotation functionality * is left to iterate through the list as usual. */ virtual void makeCompletion(const QString &); protected: /** * This function sets the line edit text and * highlights the text appropriately if the boolean * value is set to true. * * @param text The text to be set in the line edit * @param marked Whether the text inserted should be highlighted */ virtual void setCompletedText(const QString &text, bool marked); QSize minimumSizeHint() const Q_DECL_OVERRIDE; private: const QScopedPointer d_ptr; Q_PRIVATE_SLOT(d_func(), void _k_lineEditDeleted()) }; #endif diff --git a/src/kcompletion.h b/src/kcompletion.h index 4ef86cb..e5757ff 100644 --- a/src/kcompletion.h +++ b/src/kcompletion.h @@ -1,571 +1,573 @@ /* This file is part of the KDE libraries Copyright (C) 1999,2000 Carsten Pfeiffer This library 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 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 Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; see the file COPYING.LIB. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ #ifndef KCOMPLETION_H #define KCOMPLETION_H #include #include #include #include #include class KCompTreeNode; class KCompletionPrivate; class KCompletionMatchesWrapper; class KCompletionMatches; /** + * @class KCompletion kcompletion.h KCompletion + * * @short A generic class for completing QStrings * * This class offers easy use of "auto completion", "manual completion" or * "shell completion" on QString objects. A common use is completing filenames * or URLs (see KUrlCompletion()). * But it is not limited to URL-completion -- everything should be completable! * The user should be able to complete email addresses, telephone numbers, * commands, SQL queries... * Every time your program knows what the user can type into an edit field, you * should offer completion. With KCompletion, this is very easy, and if you are * using a line edit widget (KLineEdit), it is even easier. * Basically, you tell a KCompletion object what strings should be completable * and, whenever completion should be invoked, you call makeCompletion(). * KLineEdit and (an editable) KComboBox even do this automatically for you. * * KCompletion offers the completed string via the signal match() and * all matching strings (when the result is ambiguous) via the method * allMatches(). * * Notice: auto completion, shell completion and manual completion work * slightly differently: * * @li auto completion always returns a complete item as match. * When more than one matching item is available, it will deliver just * the first one (depending on sorting order). Iterating over all matches * is possible via nextMatch() and previousMatch(). * * @li popup completion works in the same way, the only difference being that * the completed items are not put into the edit widget, but into a * separate popup box. * * @li manual completion works the same way as auto completion, except that * it is not invoked automatically while the user is typing, * but only when the user presses a special key. The difference * of manual and auto completion is therefore only visible in UI classes. * KCompletion needs to know whether to deliver partial matches * (shell completion) or whole matches (auto/manual completion), therefore * KCompletion::CompletionMan and KCompletion::CompletionAuto have the exact * same effect in KCompletion. * * @li shell completion works like "tab completion" in a shell: * when multiple matches are available, the longest possible string of all * matches is returned (i.e. only a partial item). * Iterating over all matching items (complete, not partial) is possible * via nextMatch() and previousMatch(). * * As an application programmer, you do not normally have to worry about * the different completion modes; KCompletion handles * that for you, according to the setting setCompletionMode(). * The default setting is globally configured by the user and read * from completionMode(). * * A short example: * \code * KCompletion completion; * completion.setOrder(KCompletion::Sorted); * completion.addItem("pfeiffer@kde.org"); * completion.addItem("coolo@kde.org"); * completion.addItem("carpdjih@sp.zrz.tu-berlin.de"); * completion.addItem("carp@cs.tu-berlin.de"); * * cout << completion.makeCompletion("ca").latin1() << endl; * \endcode * * In shell-completion mode, this will be "carp"; in auto-completion * mode it will be "carp\@cs.tu-berlin.de", as that is alphabetically * smaller. * If setOrder was set to Insertion, "carpdjih\@sp.zrz.tu-berlin.de" * would be completed in auto-completion mode, as that was inserted before * "carp\@cs.tu-berlin.de". * * You can dynamically update the completable items by removing and adding them * whenever you want. * For advanced usage, you could even use multiple KCompletion objects. E.g. * imagine an editor like kwrite with multiple open files. You could store * items of each file in a different KCompletion object, so that you know (and * tell the user) where a completion comes from. * * Note: KCompletion does not work with strings that contain 0x0 characters * (unicode null), as this is used internally as a delimiter. * * You may inherit from KCompletion and override makeCompletion() in * special cases (like reading directories or urls and then supplying the * contents to KCompletion, as KUrlCompletion does), but this is usually * not necessary. * * * @author Carsten Pfeiffer */ class KCOMPLETION_EXPORT KCompletion : public QObject { Q_PROPERTY(CompOrder order READ order WRITE setOrder) Q_PROPERTY(bool ignoreCase READ ignoreCase WRITE setIgnoreCase) Q_PROPERTY(QStringList items READ items WRITE setItems) Q_OBJECT Q_DECLARE_PRIVATE(KCompletion) public: /** * This enum describes the completion mode used for by the KCompletion class. * See * the styleguide. * * @since 5.0 **/ enum CompletionMode { /** * No completion is used. */ CompletionNone = 1, /** * Text is automatically filled in whenever possible. */ CompletionAuto, /** * Same as automatic, but shortest match is used for completion. */ CompletionMan, /** * Completes text much in the same way as a typical *nix shell would. */ CompletionShell, /** * Lists all possible matches in a popup list box to choose from. */ CompletionPopup, /** * Lists all possible matches in a popup list box to choose from, and automatically * fills the result whenever possible. */ CompletionPopupAuto }; /** * Constants that represent the order in which KCompletion performs * completion lookups. */ enum CompOrder { Sorted, ///< Use alphabetically sorted order Insertion, ///< Use order of insertion Weighted ///< Use weighted order }; Q_ENUM(CompOrder) /** * Constructor, nothing special here :) */ KCompletion(); /** * Destructor, nothing special here, either. */ virtual ~KCompletion(); /** * Returns a list of all completion items that contain the given @p string. * @param string the string to complete * @return a list of items which contain @p text as a substring, * i.e. not necessarily at the beginning. * * @see makeCompletion */ QStringList substringCompletion(const QString &string) const; /** * Returns the last match. Might be useful if you need to check whether * a completion is different from the last one. * @return the last match. QString() is returned when there is no * last match. */ virtual const QString &lastMatch() const; /** * Returns a list of all items inserted into KCompletion. This is useful * if you need to save the state of a KCompletion object and restore it * later. * * Important note: when order() == Weighted, then every item in the * stringlist has its weight appended, delimited by a colon. E.g. an item * "www.kde.org" might look like "www.kde.org:4", where 4 is the weight. * * This is necessary so that you can save the items along with its * weighting on disk and load them back with setItems(), restoring its * weight as well. If you really don't want the appended weightings, call * setOrder( KCompletion::Insertion ) before calling items(). * * @return a list of all items * @see setItems */ QStringList items() const; /** * Returns true if the completion object contains no entries. */ bool isEmpty() const; /** * Sets the completion mode. * @param mode the completion mode * @see CompletionMode */ virtual void setCompletionMode(CompletionMode mode); /** * Returns the current completion mode. * * @return the current completion mode, default is CompletionPopup * @see setCompletionMode * @see CompletionMode */ CompletionMode completionMode() const; /** * KCompletion offers three different ways in which it offers its items: * @li in the order of insertion * @li sorted alphabetically * @li weighted * * Choosing weighted makes KCompletion perform an implicit weighting based * on how often an item is inserted. Imagine a web browser with a location * bar, where the user enters URLs. The more often a URL is entered, the * higher priority it gets. * * Note: Setting the order to sorted only affects new inserted items, * already existing items will stay in the current order. So you probably * want to call setOrder(Sorted) before inserting items if you want * everything sorted. * * Default is insertion order. * @param order the new order * @see order */ virtual void setOrder(CompOrder order); /** * Returns the completion order. * @return the current completion order. * @see setOrder */ CompOrder order() const; /** * Setting this to true makes KCompletion behave case insensitively. * E.g. makeCompletion("CA"); might return "carp\@cs.tu-berlin.de". * Default is false (case sensitive). * @param ignoreCase true to ignore the case * @see ignoreCase */ virtual void setIgnoreCase(bool ignoreCase); /** * Returns whether KCompletion acts case insensitively or not. * Default is false (case sensitive). * @return true if the case will be ignored * @see setIgnoreCase */ bool ignoreCase() const; /** * Returns a list of all items matching the last completed string. * It might take some time if you have a @em lot of items. * @return a list of all matches for the last completed string. * @see substringCompletion */ QStringList allMatches(); /** * Returns a list of all items matching @p string. * @param string the string to match * @return the list of all matches */ QStringList allMatches(const QString &string); /** * Returns a list of all items matching the last completed string. * It might take some time if you have a @em lot of items. * The matches are returned as KCompletionMatches, which also * keeps the weight of the matches, allowing * you to modify some matches or merge them with matches * from another call to allWeightedMatches(), and sort the matches * after that in order to have the matches ordered correctly. * * @return a list of all completion matches * @see substringCompletion */ KCompletionMatches allWeightedMatches(); /** * Returns a list of all items matching @p string. * @param string the string to match * @return a list of all matches */ KCompletionMatches allWeightedMatches(const QString &string); /** * Enables/disables emitting a sound when * @li makeCompletion() can't find a match * @li there is a partial completion (= multiple matches in * Shell-completion mode) * @li nextMatch() or previousMatch() hit the last possible * match and the list is rotated * * KNotifyClient() is used to emit the sounds. * * @param enable true to enable sounds * @see soundsEnabled */ virtual void setSoundsEnabled(bool enable); /** * Tells you whether KCompletion will emit sounds on certain occasions. * Default is enabled. * @return true if sounds are enabled * @see setSoundsEnabled */ bool soundsEnabled() const; /** * Returns true when more than one match is found. * @return true if there is more than one match * @see multipleMatches */ bool hasMultipleMatches() const; public Q_SLOTS: /** * Attempts to find an item in the list of available completions * that begins with @p string. Will either return the first matching item * (if there is more than one match) or QString(), if no match is * found. * * In the latter case, a sound will be emitted, depending on * soundsEnabled(). * If a match is found, it will be emitted via the signal * match(). * * If this is called twice or more with the same string while no * items were added or removed in the meantime, all available completions * will be emitted via the signal matches(). * This happens only in shell-completion mode. * * @param string the string to complete * @return the matching item, or QString() if there is no matching * item. * @see substringCompletion */ virtual QString makeCompletion(const QString &string); /** * Returns the next item from the list of matching items. * When reaching the beginning, the list is rotated so it will return the * last match and a sound is emitted (depending on soundsEnabled()). * @return the next item from the list of matching items. * When there is no match, QString() is returned and * a sound is emitted. */ QString previousMatch(); /** * Returns the next item from the list of matching items. * When reaching the last item, the list is rotated, so it will return * the first match and a sound is emitted (depending on * soundsEnabled()). * @return the next item from the list of matching items. When there is no * match, QString() is returned and a sound is emitted. */ QString nextMatch(); /** * Attempts to complete "string" and emits the completion via match(). * Same as makeCompletion(), but in this case as a slot. * @param string the string to complete * @see makeCompletion * @deprecated since 5.0, use makeCompletion() instead */ #ifndef KCOMPLETION_NO_DEPRECATED KCOMPLETION_DEPRECATED void slotMakeCompletion(const QString &string) //inline (redirect) { (void) makeCompletion(string); } /** * Searches the previous matching item and emits it via match(). * Same as previousMatch(), but in this case as a slot. * @see previousMatch * @deprecated since 5.0, use previousMatch() instead */ KCOMPLETION_DEPRECATED void slotPreviousMatch() //inline (redirect) { (void) previousMatch(); } /** * Searches the next matching item and emits it via match(). * Same as nextMatch(), but in this case as a slot. * @see nextMatch * @deprecated since 5.0, use nextMatch() instead */ KCOMPLETION_DEPRECATED void slotNextMatch() //inline (redirect) { (void) nextMatch(); } #endif /** * Inserts @p items into the list of possible completions. * It does the same as setItems(), but without calling clear() before. * @param items the items to insert */ void insertItems(const QStringList &items); /** * Sets the list of items available for completion. Removes all previous * items. * * Notice: when order() == Weighted, then the weighting is looked up for * every item in the stringlist. Every item should have ":number" appended, * where number is an unsigned integer, specifying the weighting. * * If you don't like this, call * setOrder(KCompletion::Insertion) * before calling setItems(). * * @param itemList the list of items that are available for completion * @see items */ virtual void setItems(const QStringList &itemList); /** * Adds an item to the list of available completions. * Resets the current item state (previousMatch() and nextMatch() * won't work the next time they are called). * @param item the item to add */ void addItem(const QString &item); /** * Adds an item to the list of available completions. * Resets the current item state (previousMatch() and nextMatch() * won't work the next time they are called). * * Sets the weight of the item to @p weight or adds it to the current * weight if the item is already available. The weight has to be greater * than 1 to take effect (default weight is 1). * @param item the item to add * @param weight the weight of the item, default is 1 */ void addItem(const QString &item, uint weight); /** * Removes an item from the list of available completions. * Resets the current item state (previousMatch() and nextMatch() * won't work the next time they are called). * @param item the item to remove */ void removeItem(const QString &item); /** * Removes all inserted items. */ virtual void clear(); Q_SIGNALS: /** * This signal is emitted when a match is found. * * In particular, makeCompletion(), previousMatch() and nextMatch() * all emit this signal; makeCompletion() will only emit it when a * match is found, but the other methods will alwasy emit it (and so * may emit it with an empty string). * * @param item the matching item, or QString() if there were no more * matching items. */ void match(const QString &item); /** * This signal is emitted by makeCompletion() in shell-completion mode * when the same string is passed to makeCompletion() multiple times in * a row. * @param matchlist the list of all matching items */ void matches(const QStringList &matchlist); /** * This signal is emitted when calling makeCompletion() and more than * one matching item is found. * @see hasMultipleMatches */ void multipleMatches(); protected: /** * This method is called after a completion is found and before the * matching string is emitted. You can override this method to modify the * string that will be emitted. * This is necessary e.g. in KUrlCompletion(), where files with spaces * in their names are shown escaped ("filename\ with\ spaces"), but stored * unescaped inside KCompletion. * Never delete that pointer! * * Default implementation does nothing. * @param match the match to process * @see postProcessMatches */ virtual void postProcessMatch(QString *match) const; /** * This method is called before a list of all available completions is * emitted via matches(). You can override this method to modify the * found items before match() or matches() are emitted. * Never delete that pointer! * * Default implementation does nothing. * @param matchList the matches to process * @see postProcessMatch */ virtual void postProcessMatches(QStringList *matchList) const; /** * This method is called before a list of all available completions is * emitted via #matches(). You can override this method to modify the * found items before #match() or #matches() are emitted. * Never delete that pointer! * * Default implementation does nothing. * @param matches the matches to process * @see postProcessMatch */ virtual void postProcessMatches(KCompletionMatches *matches) const; private: Q_DISABLE_COPY(KCompletion) const QScopedPointer d_ptr; }; #endif // KCOMPLETION_H diff --git a/src/kcompletionbase.h b/src/kcompletionbase.h index 6379ff1..61a4b48 100644 --- a/src/kcompletionbase.h +++ b/src/kcompletionbase.h @@ -1,376 +1,378 @@ /* This file is part of the KDE libraries Copyright (C) 1999,2000 Carsten Pfeiffer This library 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 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 Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; see the file COPYING.LIB. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ #ifndef KCOMPLETIONBASE_H #define KCOMPLETIONBASE_H #include #include #include class KCompletionBasePrivate; /** + * @class KCompletionBase kcompletionbase.h KCompletionBase + * * An abstract base class for adding a completion feature * into widgets. * * This is a convenience class that provides the basic functions * needed to add text completion support into widgets. All that * is required is an implementation for the pure virtual function * setCompletedText(). Refer to KLineEdit or KComboBox * to see how easily such support can be added using this as a base * class. * * @short An abstract class for adding text completion support to widgets. * @author Dawit Alemayehu */ class KCOMPLETION_EXPORT KCompletionBase { public: Q_DECLARE_PRIVATE(KCompletionBase) /** * Constants that represent the items whose shortcut * key binding is programmable. The default key bindings * for these items are defined in KStandardShortcut. */ enum KeyBindingType { /** * Text completion (by default Ctrl-E). */ TextCompletion, /** * Switch to previous completion (by default Ctrl-Up). */ PrevCompletionMatch, /** * Switch to next completion (by default Ctrl-Down). */ NextCompletionMatch, /** * Substring completion (by default Ctrl-T). */ SubstringCompletion }; // Map for the key binding types mentioned above. typedef QMap > KeyBindingMap; /** * Default constructor. */ KCompletionBase(); /** * Destructor. */ virtual ~KCompletionBase(); /** * Returns a pointer to the current completion object. * * If the completion object does not exist, it is automatically created and * by default handles all the completion signals internally unless @p handleSignals * is set to false. It is also automatically destroyed when the destructor * is called. You can change this default behavior using the * @ref setAutoDeleteCompletionObject and @ref setHandleSignals member * functions. * * See also @ref compObj. * * @param handleSignals if true, handles completion signals internally. * @return a pointer to the completion object. */ KCompletion *completionObject(bool handleSignals = true); /** * Sets up the completion object to be used. * * This method assigns the completion object and sets it up to automatically * handle the completion and rotation signals internally. You should use * this function if you want to share one completion object among your * widgets or need to use a customized completion object. * * The object assigned through this method is not deleted when this object's * destructor is invoked unless you explicitly call @ref setAutoDeleteCompletionObject * after calling this method. Be sure to set the bool argument to false, if * you want to handle the completion signals yourself. * * @param completionObject a KCompletion or a derived child object. * @param handleCompletionSignals if true, handles completion signals internally. */ virtual void setCompletionObject(KCompletion *completionObject, bool handleSignals = true); /** * Enables this object to handle completion and rotation * events internally. * * This function simply assigns a boolean value that * indicates whether it should handle rotation and * completion events or not. Note that this does not * stop the object from emitting signals when these * events occur. * * @param handle if true, it handles completion and rotation internally. */ virtual void setHandleSignals(bool handle); /** * Returns true if the completion object is deleted * upon this widget's destruction. * * See setCompletionObject() and enableCompletion() * for details. * * @return true if the completion object will be deleted * automatically */ bool isCompletionObjectAutoDeleted() const; /** * Sets the completion object when this widget's destructor * is called. * * If the argument is set to true, the completion object * is deleted when this widget's destructor is called. * * @param autoDelete if true, delete completion object on destruction. */ void setAutoDeleteCompletionObject(bool autoDelete); /** * Sets the widget's ability to emit text completion and * rotation signals. * * Invoking this function with @p enable set to @p false will * cause the completion and rotation signals not to be emitted. * However, unlike setting the completion object to @p NULL * using setCompletionObject, disabling the emission of * the signals through this method does not affect the current * completion object. * * There is no need to invoke this function by default. When a * completion object is created through completionObject or * setCompletionObject, these signals are set to emit * automatically. Also note that disabling this signals will not * necessarily interfere with the objects' ability to handle these * events internally. See setHandleSignals. * * @param enable if false, disables the emission of completion and rotation signals. */ void setEnableSignals(bool enable); /** * Returns true if the object handles the signals. * * @return true if this signals are handled internally. */ bool handleSignals() const; /** * Returns true if the object emits the signals. * * @return true if signals are emitted */ bool emitSignals() const; /** * Sets whether the object emits rotation signals. * * @param emitRotationSignals if false, disables the emission of rotation signals. */ void setEmitSignals(bool emitRotationSignals); /** * Sets the type of completion to be used. * * @param mode Completion type * @see CompletionMode */ virtual void setCompletionMode(KCompletion::CompletionMode mode); /** * Returns the current completion mode. * * @return the completion mode. */ KCompletion::CompletionMode completionMode() const; /** * Sets the key binding to be used for manual text * completion, text rotation in a history list as * well as a completion list. * * * When the keys set by this function are pressed, a * signal defined by the inheriting widget will be activated. * If the default value or 0 is specified by the second * parameter, then the key binding as defined in the global * setting should be used. This method returns false * when @p key is negative or the supplied key binding conflicts * with another one set for another feature. * * NOTE: To use a modifier key (Shift, Ctrl, Alt) as part of * the key binding simply @p sum up the values of the * modifier and the actual key. For example, to use CTRL+E, supply * @p "Qt::CtrlButton + Qt::Key_E" as the second argument to this * function. * * @param item the feature whose key binding needs to be set: * @li TextCompletion the manual completion key binding. * @li PrevCompletionMatch the previous match key for multiple completion. * @li NextCompletionMatch the next match key for for multiple completion. * @li SubstringCompletion the key for substring completion * @param key key binding used to rotate down in a list. * @return true if key binding is successfully set. * @see keyBinding */ bool setKeyBinding(KeyBindingType item, const QList &key); /** * Returns the key binding used for the specified item. * * This method returns the key binding used to activate * the feature given by @p item. If the binding * contains modifier key(s), the sum of the modifier key * and the actual key code is returned. * * @param item the item to check * @return the key binding used for the feature given by @p item. * @since 5.0 * @see setKeyBinding */ QList keyBinding(KeyBindingType item) const; /** * @deprecated since 5.0, use keyBinding instead */ #ifndef KCOMPLETION_NO_DEPRECATED KCOMPLETION_DEPRECATED QList getKeyBinding(KeyBindingType item) const { return keyBinding(item); } #endif /** * Sets this object to use global values for key bindings. * * This method changes the values of the key bindings for * rotation and completion features to the default values * provided in KGlobalSettings. * * NOTE: By default, inheriting widgets should use the * global key bindings so that there is no need to * call this method. */ void useGlobalKeyBindings(); /** * A pure virtual function that must be implemented by * all inheriting classes. * * This function is intended to allow external completion * implementations to set completed text appropriately. It * is mostly relevant when the completion mode is set to * CompletionAuto and CompletionManual modes. See * KCompletionBase::setCompletedText. * Does nothing in CompletionPopup mode, as all available * matches will be shown in the popup. * * @param text the completed text to be set in the widget. */ virtual void setCompletedText(const QString &text) = 0; /** * A pure virtual function that must be implemented by * all inheriting classes. * @param items the list of completed items * @param autoSuggest if @c true, the first element of @p items * is automatically completed (i.e. preselected). */ virtual void setCompletedItems(const QStringList &items, bool autoSuggest = true) = 0; /** * Returns a pointer to the completion object. * * This method is only different from completionObject() * in that it does not create a new KCompletion object even if * the internal pointer is @c NULL. Use this method to get the * pointer to a completion object when inheriting so that you * will not inadvertently create it. * * @return the completion object or @c NULL if one does not exist. */ KCompletion *compObj() const; protected: /** * Returns a key binding map. * * This method is the same as getKeyBinding(), except that it * returns the whole keymap containing the key bindings. * * @return the key binding used for the feature given by @p item. * @since 5.0 */ KeyBindingMap keyBindingMap() const; /** * @deprecated since 5.0, use keyBindingMap instead */ #ifndef KCOMPLETION_NO_DEPRECATED KCOMPLETION_DEPRECATED KeyBindingMap getKeyBindings() const { return keyBindingMap(); } #endif /** * Sets the keymap. * * @param keyBindingMap */ void setKeyBindingMap(KeyBindingMap keyBindingMap); /** * Sets or removes the delegation object. If a delegation object is * set, all function calls will be forwarded to the delegation object. * @param delegate the delegation object, or 0 to remove it */ void setDelegate(KCompletionBase *delegate); /** * Returns the delegation object. * @return the delegation object, or 0 if there is none * @see setDelegate() */ KCompletionBase *delegate() const; /** Virtual hook, used to add new "virtual" functions while maintaining binary compatibility. Unused in this class. */ virtual void virtual_hook(int id, void *data); private: Q_DISABLE_COPY(KCompletionBase) const QScopedPointer d_ptr; }; #endif // KCOMPLETIONBASE_H diff --git a/src/kcompletionbox.h b/src/kcompletionbox.h index 140c6fb..74565c2 100644 --- a/src/kcompletionbox.h +++ b/src/kcompletionbox.h @@ -1,251 +1,253 @@ /* This file is part of the KDE libraries Copyright (c) 2000 Carsten Pfeiffer 2000 Stefan Schimanski <1Stein@gmx.de> 2000,2001,2002,2003,2004 Dawit Alemayehu This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License (LGPL) as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. 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 Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; see the file COPYING.LIB. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ #ifndef KCOMPLETIONBOX_H #define KCOMPLETIONBOX_H #include #include "kcompletion_export.h" class KCompletionBoxPrivate; class QEvent; /** + * @class KCompletionBox kcompletionbox.h KCompletionBox + * * @short A helper widget for "completion-widgets" (KLineEdit, KComboBox)) * * A little utility class for "completion-widgets", like KLineEdit or * KComboBox. KCompletionBox is a listbox, displayed as a rectangle without * any window decoration, usually directly under the lineedit or combobox. * It is filled with all possible matches for a completion, so the user * can select the one he wants. * * It is used when KCompletion::CompletionMode == CompletionPopup or CompletionPopupAuto. * * @author Carsten Pfeiffer */ class KCOMPLETION_EXPORT KCompletionBox : public QListWidget { Q_OBJECT Q_DECLARE_PRIVATE(KCompletionBox) Q_PROPERTY(bool isTabHandling READ isTabHandling WRITE setTabHandling) Q_PROPERTY(QString cancelledText READ cancelledText WRITE setCancelledText) Q_PROPERTY(bool activateOnSelect READ activateOnSelect WRITE setActivateOnSelect) public: /** * Constructs a KCompletionBox. * * The parent widget is used to give the focus back when pressing the * up-button on the very first item. */ explicit KCompletionBox(QWidget *parent = nullptr); /** * Destroys the box */ ~KCompletionBox(); QSize sizeHint() const Q_DECL_OVERRIDE; /** * @returns true if selecting an item results in the emission of the selected() signal. */ bool activateOnSelect() const; /** * Returns a list of all items currently in the box. */ QStringList items() const; /** * @returns true if this widget is handling Tab-key events to traverse the * items in the dropdown list, otherwise false. * * Default is true. * * @see setTabHandling */ bool isTabHandling() const; /** * @returns the text set via setCancelledText() or QString(). */ QString cancelledText() const; public Q_SLOTS: /** * Inserts @p items into the box. Does not clear the items before. * @p index determines at which position @p items will be inserted. * (defaults to appending them at the end) */ void insertItems(const QStringList &items, int index = -1); /** * Clears the box and inserts @p items. */ void setItems(const QStringList &items); /** * Adjusts the size of the box to fit the width of the parent given in the * constructor and pops it up at the most appropriate place, relative to * the parent. * * Depending on the screensize and the position of the parent, this may * be a different place, however the default is to pop it up and the * lower left corner of the parent. * * Make sure to hide() the box when appropriate. */ virtual void popup(); /** * Makes this widget (when visible) capture Tab-key events to traverse the * items in the dropdown list (Tab goes down, Shift+Tab goes up). * * On by default, but should be turned off when used in combination with KUrlCompletion. * When off, KLineEdit handles Tab itself, making it select the current item from the completion box, * which is particularly useful when using KUrlCompletion. * * @see isTabHandling */ void setTabHandling(bool enable); /** * Sets the text to be emitted if the user chooses not to * pick from the available matches. * * If the cancelled text is not set through this function, the * userCancelled signal will not be emitted. * * @see userCancelled( const QString& ) * @param text the text to be emitted if the user cancels this box */ void setCancelledText(const QString &text); /** * Set whether or not the selected signal should be emitted when an * item is selected. By default the selected() signal is emitted. * * @param doEmit false if the signal should not be emitted. */ void setActivateOnSelect(bool doEmit); /** * Moves the selection one line down or select the first item if nothing is selected yet. */ void down(); /** * Moves the selection one line up or select the first item if nothing is selected yet. */ void up(); /** * Moves the selection one page down. */ void pageDown(); /** * Moves the selection one page up. */ void pageUp(); /** * Moves the selection up to the first item. */ void home(); /** * Moves the selection down to the last item. */ void end(); /** * Reimplemented for internal reasons. API is unaffected. * Call it only if you really need it (i.e. the widget was hidden before) to have better performance. */ void setVisible(bool visible) Q_DECL_OVERRIDE; Q_SIGNALS: /** * Emitted when an item was selected, contains the text of * the selected item. */ void activated(const QString &); /** * Emitted whenever the user chooses to ignore the available * selections and closes this box. */ void userCancelled(const QString &); protected: /** * This calculates the size of the dropdown and the relative position of the top * left corner with respect to the parent widget. This matches the geometry and position * normally used by K/QComboBox when used with one. */ QRect calculateGeometry() const; /** * @deprecated since 5.0, use resizeAndReposition instead. */ #ifndef KCOMPLETION_NO_DEPRECATED KCOMPLETION_DEPRECATED void sizeAndPosition() { resizeAndReposition(); } #endif /** * This properly resizes and repositions the listbox. * * @since 5.0 */ void resizeAndReposition(); /** * Reimplemented from QListWidget to get events from the viewport (to hide * this widget on mouse-click, Escape-presses, etc. */ bool eventFilter(QObject *, QEvent *) Q_DECL_OVERRIDE; /** * The preferred global coordinate at which the completion box's top left corner * should be positioned. */ virtual QPoint globalPositionHint() const; protected Q_SLOTS: /** * Called when an item was activated. Emits * activated() with the item. */ virtual void slotActivated(QListWidgetItem *); private: const QScopedPointer d_ptr; Q_PRIVATE_SLOT(d_func(), void _k_itemClicked(QListWidgetItem *)) }; #endif // KCOMPLETIONBOX_H diff --git a/src/kcompletionmatches.h b/src/kcompletionmatches.h index 517f111..a4bc94e 100644 --- a/src/kcompletionmatches.h +++ b/src/kcompletionmatches.h @@ -1,105 +1,107 @@ /* This file is part of the KDE libraries Copyright (C) 1999,2000 Carsten Pfeiffer This library 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 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 Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; see the file COPYING.LIB. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ #ifndef KCOMPLETIONMATCHES_H #define KCOMPLETIONMATCHES_H #include #include #include #include class KCompletionMatchesWrapper; class KCompletionMatchesPrivate; typedef KSortableList KCompletionMatchesList; /** + * @class KCompletionMatches kcompletionmatches.h KCompletionMatches + * * This structure is returned by KCompletion::allWeightedMatches(). * It also keeps the weight of the matches, allowing * you to modify some matches or merge them with matches * from another call to allWeightedMatches(), and sort the matches * after that in order to have the matches ordered correctly. * * Example (a simplified example of what Konqueror's completion does): * \code * KCompletionMatches matches = completion->allWeightedMatches(location); * if(!location.startsWith("www.")) matches += completion->allWeightedmatches("www." + location"); * matches.removeDuplicates(); * QStringList list = matches.list(); * \endcode * * @short List for keeping matches returned from KCompletion */ class KCOMPLETION_EXPORT KCompletionMatches : public KCompletionMatchesList { public: Q_DECLARE_PRIVATE(KCompletionMatches) /** * Default constructor. * @param sort if false, the matches won't be sorted before the conversion, * use only if you're sure the sorting is not needed */ KCompletionMatches(bool sort); /** * copy constructor. */ KCompletionMatches(const KCompletionMatches &); /** * assignment operator. */ KCompletionMatches &operator=(const KCompletionMatches &); /** * @internal */ KCompletionMatches(const KCompletionMatchesWrapper &matches); /** * default destructor. */ ~KCompletionMatches(); /** * Removes duplicate matches. Needed only when you merged several matches * results and there's a possibility of duplicates. */ void removeDuplicates(); /** * Returns the matches as a QStringList. * @param sort if false, the matches won't be sorted before the conversion, * use only if you're sure the sorting is not needed * @return the list of matches */ QStringList list(bool sort = true) const; /** * If sorting() returns false, the matches aren't sorted by their weight, * even if true is passed to list(). * @return true if the matches won't be sorted */ bool sorting() const; private: const QScopedPointer d_ptr; }; #endif // KCOMPLETIONMATCHES_H diff --git a/src/khistorycombobox.h b/src/khistorycombobox.h index 5e3372b..3f16012 100644 --- a/src/khistorycombobox.h +++ b/src/khistorycombobox.h @@ -1,260 +1,262 @@ /* This file is part of the KDE libraries Copyright (c) 2000,2001 Dawit Alemayehu Copyright (c) 2000,2001 Carsten Pfeiffer This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License (LGPL) as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. 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; see the file COPYING.LIB. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ #ifndef KHistoryComboBoxBOX_H #define KHistoryComboBoxBOX_H #include #include class KPixmapProvider; class KHistoryComboBoxPrivate; /** + * @class KHistoryComboBox khistorycombobox.h KHistoryComboBox + * * @short A combobox for offering a history and completion * * A combobox which implements a history like a unix shell. You can navigate * through all the items by using the Up or Down arrows (configurable of * course). Additionally, weighted completion is available. So you should * load and save the completion list to preserve the weighting between * sessions. * * KHistoryComboBox obeys the HISTCONTROL environment variable to determine * whether duplicates in the history should be tolerated in * addToHistory() or not. During construction of KHistoryComboBox, * duplicates will be disabled when HISTCONTROL is set to "ignoredups" or * "ignoreboth". Otherwise, duplicates are enabled by default. * * \image html khistorycombobox.png "KDE History Combo Box" * * @author Carsten Pfeiffer */ class KCOMPLETION_EXPORT KHistoryComboBox : public KComboBox { Q_OBJECT Q_DECLARE_PRIVATE(KHistoryComboBox) Q_PROPERTY(QStringList historyItems READ historyItems WRITE setHistoryItems) public: /** * Constructs a "read-write" combobox. A read-only history combobox * doesn't make much sense, so it is only available as read-write. * Completion will be used automatically for the items in the combo. * * The insertion-policy is set to NoInsert, you have to add the items * yourself via the slot addToHistory. If you want every item added, * use * * \code * connect( combo, SIGNAL( activated( const QString& )), * combo, SLOT( addToHistory( const QString& ))); * \endcode * * Use QComboBox::setMaxCount() to limit the history. * * @p parent the parent object of this widget. */ explicit KHistoryComboBox(QWidget *parent = nullptr); /** * Same as the previous constructor, but additionally has the option * to specify whether you want to let KHistoryComboBox handle completion * or not. If set to @p true, KHistoryComboBox will sync the completion to the * contents of the combobox. */ explicit KHistoryComboBox(bool useCompletion, QWidget *parent = nullptr); /** * Destructs the combo, the completion-object and the pixmap-provider */ ~KHistoryComboBox(); /** * Inserts @p items into the combobox. @p items might get * truncated if it is longer than maxCount() * * @see historyItems */ void setHistoryItems(const QStringList &items); /** * Inserts @p items into the combobox. @p items might get * truncated if it is longer than maxCount() * * Set @p setCompletionList to true, if you don't have a list of * completions. This tells KHistoryComboBox to use all the items for the * completion object as well. * You won't have the benefit of weighted completion though, so normally * you should do something like * \code * KConfigGroup config(KSharedConfig::openConfig(), "somegroup"); * * // load the history and completion list after creating the history combo * QStringList list; * list = config.readEntry("Completion list", QStringList()); * combo->completionObject()->setItems(list); * list = config.readEntry("History list", QStringList()); * combo->setHistoryItems(list); * * [...] * * // save the history and completion list when the history combo is * // destroyed * QStringList list; * KConfigGroup config(KSharedConfig::openConfig(), "somegroup"); * list = combo->completionObject()->items(); * config.writeEntry("Completion list", list); * list = combo->historyItems(); * config.writeEntry("History list", list); * \endcode * * Be sure to use different names for saving with KConfig if you have more * than one KHistoryComboBox. * * Note: When @p setCompletionList is true, the items are inserted into the * KCompletion object with mode KCompletion::Insertion and the mode is set * to KCompletion::Weighted afterwards. * * @see historyItems * @see KComboBox::completionObject * @see KCompletion::setItems * @see KCompletion::items */ void setHistoryItems(const QStringList &items, bool setCompletionList); /** * Returns the list of history items. Empty, when this is not a read-write * combobox. * * @see setHistoryItems */ QStringList historyItems() const; /** * Removes all items named @p item. * * @return @p true if at least one item was removed. * * @see addToHistory */ bool removeFromHistory(const QString &item); /** * Sets a pixmap provider, so that items in the combobox can have a pixmap. * KPixmapProvider is just an abstract class with the one pure virtual * method KPixmapProvider::pixmapFor(). This method is called whenever * an item is added to the KHistoryComboBoxBox. Implement it to return your * own custom pixmaps, or use the KUrlPixmapProvider from KIO, * which uses KMimeType::pixmapForUrl to resolve icons. * * Set @p provider to nullptr if you want to disable pixmaps. Default no pixmaps. * * @see pixmapProvider */ void setPixmapProvider(KPixmapProvider *provider); /** * @returns the current pixmap provider. * @see setPixmapProvider * @see KPixmapProvider */ KPixmapProvider *pixmapProvider() const; using QComboBox::insertItems; public Q_SLOTS: /** * Adds an item to the end of the history list and to the completion list. * If maxCount() is reached, the first item of the list will be * removed. * * If the last inserted item is the same as @p item, it will not be * inserted again. * * If duplicatesEnabled() is false, any equal existing item will be * removed before @p item is added. * * Note: By using this method and not the Q and KComboBox insertItem() * methods, you make sure that the combobox stays in sync with the * completion. It would be annoying if completion would give an item * not in the combobox, and vice versa. * * @see removeFromHistory * @see QComboBox::setDuplicatesEnabled */ void addToHistory(const QString &item); /** * Clears the history and the completion list. */ void clearHistory(); /** * Resets the current position of the up/down history. Call this * when you manually call setCurrentItem() or clearEdit(). */ void reset(); Q_SIGNALS: /** * Emitted when the history was cleared by the entry in the popup menu. */ void cleared(); protected: /** * Handling key-events, the shortcuts to rotate the items. */ void keyPressEvent(QKeyEvent *) Q_DECL_OVERRIDE; /** * Handling wheel-events, to rotate the items. */ void wheelEvent(QWheelEvent *ev) Q_DECL_OVERRIDE; /** * Inserts @p items into the combo, honoring pixmapProvider() * Does not update the completionObject. * * Note: duplicatesEnabled() is not honored here. * * Called from setHistoryItems() and setPixmapProvider() */ void insertItems(const QStringList &items); /** * @returns if we can modify the completion object or not. */ bool useCompletion() const; private: const QScopedPointer d_ptr; Q_PRIVATE_SLOT(d_func(), void _k_clear()) Q_PRIVATE_SLOT(d_func(), void _k_addContextMenuItems(QMenu *)) Q_PRIVATE_SLOT(d_func(), void _k_simulateActivated(const QString &)) Q_DISABLE_COPY(KHistoryComboBox) }; #endif diff --git a/src/klineedit.h b/src/klineedit.h index c7116a4..165a4fb 100644 --- a/src/klineedit.h +++ b/src/klineedit.h @@ -1,635 +1,637 @@ /* This file is part of the KDE libraries This class was originally inspired by Torben Weis' fileentry.cpp for KFM II. Copyright (C) 1997 Sven Radej Copyright (c) 1999 Patrick Ward Copyright (c) 1999 Preston Brown Completely re-designed: Copyright (c) 2000,2001 Dawit Alemayehu This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License (LGPL) as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. 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; see the file COPYING.LIB. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ #ifndef KLINEEDIT_H #define KLINEEDIT_H #include #include #include #include class QAction; class QMenu; class KCompletionBox; class QUrl; class KLineEditPrivate; /** + * @class KLineEdit klineedit.h KLineEdit + * * An enhanced QLineEdit widget for inputting text. * * \b Detail \n * * This widget inherits from QLineEdit and implements the following * additional functionalities: a completion object that provides both * automatic and manual text completion as well as multiple match iteration * features, configurable key-bindings to activate these features and a * popup-menu item that can be used to allow the user to set text completion * modes on the fly based on their preference. * * To support these new features KLineEdit also emits a few more * additional signals. These are: completion( const QString& ), * textRotation( KeyBindingType ), and returnPressed( const QString& ). * The completion signal can be connected to a slot that will assist the * user in filling out the remaining text. The text rotation signal is * intended to be used to iterate through the list of all possible matches * whenever there is more than one match for the entered text. The * @p returnPressed( const QString& ) signals are the same as QLineEdit's * except it provides the current text in the widget as its argument whenever * appropriate. * * This widget by default creates a completion object when you invoke * the completionObject( bool ) member function for the first time or * use setCompletionObject( KCompletion*, bool ) to assign your own * completion object. Additionally, to make this widget more functional, * KLineEdit will by default handle the text rotation and completion * events internally when a completion object is created through either one * of the methods mentioned above. If you do not need this functionality, * simply use KCompletionBase::setHandleSignals( bool ) or set the * boolean parameter in the above functions to false. * * The default key-bindings for completion and rotation is determined * from the global settings in KStandardShortcut. These values, however, * can be overridden locally by invoking KCompletionBase::setKeyBinding(). * The values can easily be reverted back to the default setting, by simply * calling useGlobalSettings(). An alternate method would be to default * individual key-bindings by using setKeyBinding() with the default * second argument. * * If @p EchoMode for this widget is set to something other than @p QLineEdit::Normal, * the completion mode will always be defaulted to CompletionNone. * This is done purposefully to guard against protected entries such as passwords being * cached in KCompletion's list. Hence, if the @p EchoMode is not QLineEdit::Normal, the * completion mode is automatically disabled. * * A read-only KLineEdit will have the same background color as a * disabled KLineEdit, but its foreground color will be the one used * for the read-write mode. This differs from QLineEdit's implementation * and is done to give visual distinction between the three different modes: * disabled, read-only, and read-write. * * KLineEdit has also a password mode which depends of globals KDE settings. Use * KLineEdit::setPasswordMode instead of QLineEdit::echoMode property to have a password field. * * \b Usage \n * * To enable the basic completion feature: * * \code * KLineEdit *edit = new KLineEdit( this ); * KCompletion *comp = edit->completionObject(); * // Connect to the return pressed signal - optional * connect(edit,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&))); * \endcode * * To use a customized completion objects or your * own completion object: * * \code * KLineEdit *edit = new KLineEdit( this ); * KUrlCompletion *comp = new KUrlCompletion(); * edit->setCompletionObject( comp ); * // Connect to the return pressed signal - optional * connect(edit,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&))); * \endcode * * Note if you specify your own completion object you have to either delete * it when you don't need it anymore, or you can tell KLineEdit to delete it * for you: * \code * edit->setAutoDeleteCompletionObject( true ); * \endcode * * Miscellaneous function calls :\n * * \code * // Tell the widget to not handle completion and iteration automatically. * edit->setHandleSignals( false ); * * // Set your own key-bindings for a text completion mode. * edit->setKeyBinding( KCompletionBase::TextCompletion, Qt::End ); * * // Hide the context (popup) menu * edit->setContextMenuPolicy( Qt::NoContextMenu ); * * // Default the key-bindings back to the default system settings. * edit->useGlobalKeyBindings(); * \endcode * * \image html klineedit.png "KDE Line Edit Widgets with clear-button" * * @author Dawit Alemayehu */ class KCOMPLETION_EXPORT KLineEdit : public QLineEdit, public KCompletionBase //krazy:exclude=qclasses { friend class KComboBox; friend class KLineEditStyle; Q_OBJECT Q_DECLARE_PRIVATE(KLineEdit) #ifndef KCOMPLETION_NO_DEPRECATED Q_PROPERTY(bool contextMenuEnabled READ isContextMenuEnabled WRITE setContextMenuEnabled) #endif #ifndef KCOMPLETION_NO_DEPRECATED Q_PROPERTY(bool urlDropsEnabled READ urlDropsEnabled WRITE setUrlDropsEnabled) #endif Q_PROPERTY(bool trapEnterKeyEvent READ trapReturnKey WRITE setTrapReturnKey) Q_PROPERTY(bool squeezedTextEnabled READ isSqueezedTextEnabled WRITE setSqueezedTextEnabled) #ifndef KCOMPLETION_NO_DEPRECATED Q_PROPERTY(QString clickMessage READ clickMessage WRITE setClickMessage) #endif Q_PROPERTY(bool showClearButton READ isClearButtonShown WRITE setClearButtonShown) Q_PROPERTY(bool passwordMode READ passwordMode WRITE setPasswordMode) public: /** * Constructs a KLineEdit object with a default text, a parent, * and a name. * * @param string Text to be shown in the edit widget. * @param parent The parent widget of the line edit. */ explicit KLineEdit(const QString &string, QWidget *parent = nullptr); /** * Constructs a line edit * @param parent The parent widget of the line edit. */ explicit KLineEdit(QWidget *parent = nullptr); /** * Destructor. */ virtual ~KLineEdit(); /** * Sets @p url into the lineedit. It uses QUrl::toDisplayString() so * that the url is properly decoded for displaying. */ void setUrl(const QUrl &url); /** * Reimplemented from KCompletionBase for internal reasons. * * This function is re-implemented in order to make sure that * the EchoMode is acceptable before we set the completion mode. * * See KCompletionBase::setCompletionMode */ void setCompletionMode(KCompletion::CompletionMode mode) Q_DECL_OVERRIDE; /** * Disables completion modes by makeing them non-checkable. * * The context menu allows to change the completion mode. * This method allows to disable some modes. */ void setCompletionModeDisabled(KCompletion::CompletionMode mode, bool disable = true); /** * Enables/disables the popup (context) menu. * * This method only works if this widget is editable, i.e. read-write and * allows you to enable/disable the context menu. It does nothing if invoked * for a none-editable combo-box. * * By default, the context menu is created if this widget is editable. * Call this function with the argument set to false to disable the popup * menu. * * @param showMenu If @p true, show the context menu. * @deprecated since 4.5, use setContextMenuPolicy instead */ #ifndef KCOMPLETION_NO_DEPRECATED virtual KCOMPLETION_DEPRECATED void setContextMenuEnabled(bool showMenu); #endif /** * Returns @p true when the context menu is enabled. * @deprecated since 4.5, use contextMenuPolicy instead */ #ifndef KCOMPLETION_NO_DEPRECATED KCOMPLETION_DEPRECATED bool isContextMenuEnabled() const; #endif /** * Enables/Disables handling of URL drops. If enabled and the user * drops an URL, the decoded URL will be inserted. Otherwise the default * behavior of QLineEdit is used, which inserts the encoded URL. * Call setUrlDropsEnabled(false) if you need dropEvent to be called in a KLineEdit subclass. * * @param enable If @p true, insert decoded URLs */ void setUrlDropsEnabled(bool enable); // KF6: remove it and don't create LineEditUrlDropEventFilter by default. /** * Returns @p true when decoded URL drops are enabled */ bool urlDropsEnabled() const; /** * By default, KLineEdit recognizes @p Key_Return and @p Key_Enter and emits * the returnPressed() signals, but it also lets the event pass, * for example causing a dialog's default-button to be called. * * Call this method with @p trap = @p true to make @p KLineEdit stop these * events. The signals will still be emitted of course. * * @see trapReturnKey() */ void setTrapReturnKey(bool trap); /** * @returns @p true if keyevents of @p Key_Return or * @p Key_Enter will be stopped or if they will be propagated. * * @see setTrapReturnKey () */ bool trapReturnKey() const; /** * @returns the completion-box, that is used in completion mode * CompletionPopup. * This method will create a completion-box if none is there, yet. * * @param create Set this to false if you don't want the box to be created * i.e. to test if it is available. */ virtual KCompletionBox *completionBox(bool create = true); /** * Reimplemented for internal reasons, the API is not affected. */ void setCompletionObject(KCompletion *, bool handle = true) Q_DECL_OVERRIDE; /** * Reimplemented for internal reasons, the API is not affected. */ virtual void copy() const; /** * Enable text squeezing whenever the supplied text is too long. * Only works for "read-only" mode. * * Note that once text squeezing is enabled, QLineEdit::text() * and QLineEdit::displayText() return the squeezed text. If * you want the original text, use @ref originalText. * * @see QLineEdit */ void setSqueezedTextEnabled(bool enable); /** * Returns true if text squeezing is enabled. * This is only valid when the widget is in read-only mode. */ bool isSqueezedTextEnabled() const; /** * Returns the original text if text squeezing is enabled. * If the widget is not in "read-only" mode, this function * returns the same thing as QLineEdit::text(). * * @see QLineEdit */ QString originalText() const; /** * Returns the text as given by the user (i.e. not autocompleted) * if the widget has autocompletion disabled, this function * returns the same as QLineEdit::text(). * @since 4.2.2 */ QString userText() const; /** * Set the completion-box to be used in completion mode * CompletionPopup. * This will do nothing if a completion-box already exists. * * @param box The KCompletionBox to set */ void setCompletionBox(KCompletionBox *box); /** * This makes the line edit display a grayed-out hinting text as long as * the user didn't enter any text. It is often used as indication about * the purpose of the line edit. * @deprecated since 5.0, use QLineEdit::setPlaceholderText instead. */ #ifndef KCOMPLETION_NO_DEPRECATED KCOMPLETION_DEPRECATED void setClickMessage(const QString &msg); #endif /** * @return the message set with setClickMessage * @deprecated since 5.0, use QLineEdit::placeholderText instead. */ #ifndef KCOMPLETION_NO_DEPRECATED KCOMPLETION_DEPRECATED QString clickMessage() const; #endif /** * This makes the line edit display an icon on one side of the line edit * which, when clicked, clears the contents of the line edit. * This is useful for such things as location or search bars. **/ void setClearButtonShown(bool show); /** * @return whether or not the clear button is shown **/ bool isClearButtonShown() const; /** * @return the size used by the clear button * @since 4.1 **/ QSize clearButtonUsedSize() const; /** * Do completion now. This is called automatically when typing a key for instance. * Emits completion() and/or calls makeCompletion(), depending on * emitSignals and handleSignals. * * @since 4.2.1 */ void doCompletion(const QString &text); Q_SIGNALS: /** * Emitted whenever the completion box is activated. */ void completionBoxActivated(const QString &); /** * Emitted when the user presses the return key. * * The argument is the current text. Note that this * signal is @em not emitted if the widget's @p EchoMode is set to * QLineEdit::EchoMode. */ void returnPressed(const QString &); /** * Emitted when the completion key is pressed. * * Please note that this signal is @em not emitted if the * completion mode is set to @p CompletionNone or @p EchoMode is * @em normal. */ void completion(const QString &); /** * Emitted when the shortcut for substring completion is pressed. */ void substringCompletion(const QString &); /** * Emitted when the text is changed NOT by the suggested autocompletion: * either when the user is physically typing keys, or when the text is changed programmatically, * for example, by calling setText(). * But not when automatic completion changes the text temporarily. * * @since 4.2.2 * @deprecated since 4.5. You probably want to connect to textEdited() instead, * which is emitted whenever the text is actually changed by the user * (by typing or accepting autocompletion), without side effects from * suggested autocompletion either. userTextChanged isn't needed anymore. */ #ifndef KCOMPLETION_NO_DEPRECATED QT_MOC_COMPAT void userTextChanged(const QString &); #endif /** * Emitted when the text rotation key-bindings are pressed. * * The argument indicates which key-binding was pressed. * In KLineEdit's case this can be either one of two values: * PrevCompletionMatch or NextCompletionMatch. See * KCompletionBase::setKeyBinding for details. * * Note that this signal is @em not emitted if the completion * mode is set to @p CompletionNone or @p echoMode() is @em not normal. */ void textRotation(KCompletionBase::KeyBindingType); /** * Emitted when the user changed the completion mode by using the * popupmenu. */ void completionModeChanged(KCompletion::CompletionMode); /** * Emitted before the context menu is displayed. * * The signal allows you to add your own entries into the * the context menu that is created on demand. * * NOTE: Do not store the pointer to the QMenu * provided through since it is created and deleted * on demand. * * @param contextMenu the context menu about to be displayed */ void aboutToShowContextMenu(QMenu *contextMenu); /** * Emitted when the user clicked on the clear button */ void clearButtonClicked(); public Q_SLOTS: /** * Sets the lineedit to read-only. Similar to QLineEdit::setReadOnly * but also takes care of the background color, and the clear button. */ virtual void setReadOnly(bool); /** * Iterates through all possible matches of the completed text or * the history list. * * This function simply iterates over all possible matches in case * multiple matches are found as a result of a text completion request. * It will have no effect if only a single match is found. * * @param type The key-binding invoked. */ void rotateText(KCompletionBase::KeyBindingType type); /** * See KCompletionBase::setCompletedText. */ void setCompletedText(const QString &) Q_DECL_OVERRIDE; /** * Same as the above function except it allows you to temporarily * turn off text completion in CompletionPopupAuto mode. * * * @param items list of completion matches to be shown in the completion box. * @param autoSuggest true if you want automatic text completion (suggestion) enabled. */ void setCompletedItems(const QStringList &items, bool autoSuggest = true) Q_DECL_OVERRIDE; /** * Squeezes @p text into the line edit. * This can only be used with read-only line-edits. */ void setSqueezedText(const QString &text); /** * Reimplemented to enable text squeezing. API is not affected. */ virtual void setText(const QString &); /** * @brief set the line edit in password mode. * this change the EchoMode according to KDE preferences. * @param passwordMode true to set in password mode */ void setPasswordMode(bool passwordMode = true); /** * @return returns true if the lineedit is set to password mode echoing */ bool passwordMode() const; protected Q_SLOTS: /** * Completes the remaining text with a matching one from * a given list. */ virtual void makeCompletion(const QString &); /** * Resets the current displayed text. * Call this function to revert a text completion if the user * cancels the request. Mostly applies to popup completions. */ void userCancelled(const QString &cancelText); protected: /** * Reimplemented for internal reasons. API not affected. */ bool event(QEvent *) Q_DECL_OVERRIDE; /** * Reimplemented for internal reasons. API not affected. * * See QLineEdit::resizeEvent(). */ void resizeEvent(QResizeEvent *) Q_DECL_OVERRIDE; /** * Reimplemented for internal reasons. API not affected. * * See QLineEdit::keyPressEvent(). */ void keyPressEvent(QKeyEvent *) Q_DECL_OVERRIDE; /** * Reimplemented for internal reasons. API not affected. * * See QLineEdit::mousePressEvent(). */ void mousePressEvent(QMouseEvent *) Q_DECL_OVERRIDE; /** * Reimplemented for internal reasons. API not affected. * * See QLineEdit::mouseReleaseEvent(). */ void mouseReleaseEvent(QMouseEvent *) Q_DECL_OVERRIDE; /** * Reimplemented for internal reasons. API not affected. * * See QWidget::mouseDoubleClickEvent(). */ void mouseDoubleClickEvent(QMouseEvent *) Q_DECL_OVERRIDE; /** * Reimplemented for internal reasons. API not affected. * * See QLineEdit::contextMenuEvent(). */ void contextMenuEvent(QContextMenuEvent *) Q_DECL_OVERRIDE; /** * Reimplemented for internal reasons. API not affected. * * See QLineEdit::createStandardContextMenu(). */ QMenu *createStandardContextMenu(); /** * This function simply sets the lineedit text and * highlights the text appropriately if the boolean * value is set to true. * * @param text * @param marked */ virtual void setCompletedText(const QString & /*text*/, bool /*marked*/); /** * Sets the widget in userSelection mode or in automatic completion * selection mode. This changes the colors of selections. */ void setUserSelection(bool userSelection); /** * Whether in current state text should be auto-suggested */ bool autoSuggest() const; void paintEvent(QPaintEvent *ev) Q_DECL_OVERRIDE; private: const QScopedPointer d_ptr; Q_PRIVATE_SLOT(d_func(), void _k_textChanged(const QString &)) Q_PRIVATE_SLOT(d_func(), void _k_completionMenuActivated(QAction *)) Q_PRIVATE_SLOT(d_func(), void _k_tripleClickTimeout()) Q_PRIVATE_SLOT(d_func(), void _k_restoreSelectionColors()) Q_PRIVATE_SLOT(d_func(), void _k_completionBoxTextChanged(const QString &)) Q_PRIVATE_SLOT(d_func(), void _k_updateClearButtonIcon(const QString &)) }; #endif diff --git a/src/kpixmapprovider.h b/src/kpixmapprovider.h index 67917f2..a627b22 100644 --- a/src/kpixmapprovider.h +++ b/src/kpixmapprovider.h @@ -1,57 +1,59 @@ /* This file is part of the KDE libraries Copyright (c) 2000 Carsten Pfeiffer This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License (LGPL) as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. 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 Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; see the file COPYING.LIB. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ #ifndef KPIXMAPPROVIDER_H #define KPIXMAPPROVIDER_H #include #include /** + * @class KPixmapProvider kpixmapprovider.h KPixmapProvider + * * A tiny abstract class with just one method: * pixmapFor() * * It will be called whenever an icon is searched for @p text. * * Used e.g. by KHistoryComboBox * * @author Carsten Pfeiffer * @short an abstract interface for looking up icons */ class KCOMPLETION_EXPORT KPixmapProvider { public: virtual ~KPixmapProvider(); /** * You may subclass this and return a pixmap of size @p size for @p text. * @param text the text that is associated with the pixmap * @param size the size of the icon in pixels, 0 for defaylt size. * See KIconLoader::StdSize. * @return the pixmap for the arguments, or null if there is none */ virtual QPixmap pixmapFor(const QString &text, int size = 0) = 0; protected: /** Virtual hook, used to add new "virtual" functions while maintaining binary compatibility. Unused in this class. */ virtual void virtual_hook(int id, void *data); }; #endif // KPIXMAPPROVIDER_H