File indexing completed on 2024-04-28 03:53:08

 /*
     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