Advance Wayland and KDE package bring-up
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
This commit is contained in:
@@ -0,0 +1,559 @@
|
||||
/*
|
||||
This file is part of the KDE libraries
|
||||
SPDX-FileCopyrightText: 1999, 2000 Carsten Pfeiffer <pfeiffer@kde.org>
|
||||
|
||||
SPDX-License-Identifier: LGPL-2.0-or-later
|
||||
*/
|
||||
|
||||
#ifndef KCOMPLETION_H
|
||||
#define KCOMPLETION_H
|
||||
|
||||
#include <kcompletion_export.h>
|
||||
|
||||
#include <QKeySequence>
|
||||
#include <QObject>
|
||||
#include <QPointer>
|
||||
#include <QStringList>
|
||||
#include <functional>
|
||||
#include <memory>
|
||||
|
||||
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 <pfeiffer@kde.org>
|
||||
*/
|
||||
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.
|
||||
*
|
||||
* @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 or custom sorter logic
|
||||
Insertion, ///< Use order of insertion
|
||||
Weighted, ///< Use weighted order
|
||||
};
|
||||
Q_ENUM(CompOrder)
|
||||
|
||||
/**
|
||||
* The sorter function signature. Deriving classes may provide
|
||||
* custom sorting logic via the setSorterFunction method.
|
||||
*
|
||||
* @since 5.88
|
||||
*/
|
||||
using SorterFunction = std::function<void(QStringList &)>;
|
||||
|
||||
/**
|
||||
* Constructor, nothing special here :)
|
||||
*/
|
||||
KCompletion();
|
||||
|
||||
/**
|
||||
* Destructor, nothing special here, either.
|
||||
*/
|
||||
~KCompletion() override;
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*
|
||||
* @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;
|
||||
|
||||
/**
|
||||
* Informs the caller if they should display the auto-suggestion for the last completion operation performed.
|
||||
* Applies for CompletionPopupAuto and CompletionAuto modes.
|
||||
* Defaults to true, but deriving classes may set it to false in special cases via "setShouldAutoSuggest".
|
||||
* @return true if auto-suggestion should be displayed for the last completion operation performed.
|
||||
* @since 5.87
|
||||
*/
|
||||
bool shouldAutoSuggest() 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();
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*
|
||||
* @note 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 always 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;
|
||||
|
||||
/**
|
||||
* Deriving classes may set this property and control whether the auto-suggestion should be displayed
|
||||
* for the last completion operation performed.
|
||||
*
|
||||
* Applies for CompletionPopupAuto and CompletionAuto modes.
|
||||
* @since 5.87
|
||||
*/
|
||||
void setShouldAutoSuggest(bool shouldAutosuggest);
|
||||
|
||||
/**
|
||||
* Sets a custom function to be used to sort the matches.
|
||||
* Can be set to nullptr to use the default sorting logic.
|
||||
*
|
||||
* Applies for CompOrder::Sorted mode.
|
||||
* @since 5.88
|
||||
*/
|
||||
void setSorterFunction(SorterFunction sortFunc);
|
||||
|
||||
private:
|
||||
Q_DISABLE_COPY(KCompletion)
|
||||
std::unique_ptr<KCompletionPrivate> const d_ptr;
|
||||
};
|
||||
|
||||
#endif // KCOMPLETION_H
|
||||
Reference in New Issue
Block a user