File indexing completed on 2024-04-28 03:53:08
0001 /* 0002 This file is part of the KDE libraries 0003 0004 SPDX-FileCopyrightText: 2000 Carsten Pfeiffer <pfeiffer@kde.org> 0005 SPDX-FileCopyrightText: 2000 Stefan Schimanski <1Stein@gmx.de> 0006 SPDX-FileCopyrightText: 2000, 2001, 2002, 2003, 2004 Dawit Alemayehu <adawit@kde.org> 0007 0008 SPDX-License-Identifier: LGPL-2.0-or-later 0009 */ 0010 0011 #ifndef KCOMPLETIONBOX_H 0012 #define KCOMPLETIONBOX_H 0013 0014 #include "kcompletion_export.h" 0015 #include <QListWidget> 0016 #include <memory> 0017 0018 class KCompletionBoxPrivate; 0019 class QEvent; 0020 0021 /** 0022 * @class KCompletionBox kcompletionbox.h KCompletionBox 0023 * 0024 * @short A helper widget for "completion-widgets" (KLineEdit, KComboBox)) 0025 * 0026 * A little utility class for "completion-widgets", like KLineEdit or 0027 * KComboBox. KCompletionBox is a listbox, displayed as a rectangle without 0028 * any window decoration, usually directly under the lineedit or combobox. 0029 * It is filled with all possible matches for a completion, so the user 0030 * can select the one he wants. 0031 * 0032 * It is used when KCompletion::CompletionMode == CompletionPopup or CompletionPopupAuto. 0033 * 0034 * @author Carsten Pfeiffer <pfeiffer@kde.org> 0035 */ 0036 class KCOMPLETION_EXPORT KCompletionBox : public QListWidget 0037 { 0038 Q_OBJECT 0039 Q_PROPERTY(bool isTabHandling READ isTabHandling WRITE setTabHandling) 0040 Q_PROPERTY(QString cancelledText READ cancelledText WRITE setCancelledText) 0041 Q_PROPERTY(bool activateOnSelect READ activateOnSelect WRITE setActivateOnSelect) 0042 0043 public: 0044 /** 0045 * Constructs a KCompletionBox. 0046 * 0047 * The parent widget is used to give the focus back when pressing the 0048 * up-button on the very first item. 0049 */ 0050 explicit KCompletionBox(QWidget *parent = nullptr); 0051 0052 /** 0053 * Destroys the box 0054 */ 0055 ~KCompletionBox() override; 0056 0057 QSize sizeHint() const override; 0058 0059 /** 0060 * @returns true if selecting an item results in the emission of the selected() signal. 0061 */ 0062 bool activateOnSelect() const; 0063 0064 /** 0065 * Returns a list of all items currently in the box. 0066 */ 0067 QStringList items() const; 0068 0069 /** 0070 * @returns true if this widget is handling Tab-key events to traverse the 0071 * items in the dropdown list, otherwise false. 0072 * 0073 * Default is true. 0074 * 0075 * @see setTabHandling 0076 */ 0077 bool isTabHandling() const; 0078 0079 /** 0080 * @returns the text set via setCancelledText() or QString(). 0081 */ 0082 QString cancelledText() const; 0083 0084 public Q_SLOTS: 0085 /** 0086 * Inserts @p items into the box. Does not clear the items before. 0087 * @p index determines at which position @p items will be inserted. 0088 * (defaults to appending them at the end) 0089 */ 0090 void insertItems(const QStringList &items, int index = -1); 0091 0092 /** 0093 * Clears the box and inserts @p items. 0094 */ 0095 void setItems(const QStringList &items); 0096 0097 /** 0098 * Adjusts the size of the box to fit the width of the parent given in the 0099 * constructor and pops it up at the most appropriate place, relative to 0100 * the parent. 0101 * 0102 * Depending on the screensize and the position of the parent, this may 0103 * be a different place, however the default is to pop it up and the 0104 * lower left corner of the parent. 0105 * 0106 * Make sure to hide() the box when appropriate. 0107 */ 0108 virtual void popup(); 0109 0110 /** 0111 * Makes this widget (when visible) capture Tab-key events to traverse the 0112 * items in the dropdown list (Tab goes down, Shift+Tab goes up). 0113 * 0114 * On by default, but should be turned off when used in combination with KUrlCompletion. 0115 * When off, KLineEdit handles Tab itself, making it select the current item from the completion box, 0116 * which is particularly useful when using KUrlCompletion. 0117 * 0118 * @see isTabHandling 0119 */ 0120 void setTabHandling(bool enable); 0121 0122 /** 0123 * Sets the text to be emitted if the user chooses not to 0124 * pick from the available matches. 0125 * 0126 * If the cancelled text is not set through this function, the 0127 * userCancelled signal will not be emitted. 0128 * 0129 * @see userCancelled( const QString& ) 0130 * @param text the text to be emitted if the user cancels this box 0131 */ 0132 void setCancelledText(const QString &text); 0133 0134 /** 0135 * Set whether or not the selected signal should be emitted when an 0136 * item is selected. By default the selected() signal is emitted. 0137 * 0138 * @param doEmit false if the signal should not be emitted. 0139 */ 0140 void setActivateOnSelect(bool doEmit); 0141 0142 /** 0143 * Moves the selection one line down or select the first item if nothing is selected yet. 0144 */ 0145 void down(); 0146 0147 /** 0148 * Moves the selection one line up or select the first item if nothing is selected yet. 0149 */ 0150 void up(); 0151 0152 /** 0153 * Moves the selection one page down. 0154 */ 0155 void pageDown(); 0156 0157 /** 0158 * Moves the selection one page up. 0159 */ 0160 void pageUp(); 0161 0162 /** 0163 * Moves the selection up to the first item. 0164 */ 0165 void home(); 0166 0167 /** 0168 * Moves the selection down to the last item. 0169 */ 0170 void end(); 0171 0172 /** 0173 * Reimplemented for internal reasons. API is unaffected. 0174 * Call it only if you really need it (i.e. the widget was hidden before) to have better performance. 0175 */ 0176 void setVisible(bool visible) override; 0177 0178 Q_SIGNALS: 0179 /** 0180 * Emitted when an item is selected, @p text is the text of the selected item. 0181 * 0182 * @since 5.81 0183 */ 0184 void textActivated(const QString &text); 0185 0186 /** 0187 * Emitted whenever the user chooses to ignore the available 0188 * selections and closes this box. 0189 */ 0190 void userCancelled(const QString &); 0191 0192 protected: 0193 /** 0194 * This calculates the size of the dropdown and the relative position of the top 0195 * left corner with respect to the parent widget. This matches the geometry and position 0196 * normally used by K/QComboBox when used with one. 0197 */ 0198 QRect calculateGeometry() const; 0199 0200 /** 0201 * This properly resizes and repositions the listbox. 0202 * 0203 * @since 5.0 0204 */ 0205 void resizeAndReposition(); 0206 0207 /** 0208 * Reimplemented from QListWidget to get events from the viewport (to hide 0209 * this widget on mouse-click, Escape-presses, etc. 0210 */ 0211 bool eventFilter(QObject *, QEvent *) override; 0212 0213 /** 0214 * The preferred global coordinate at which the completion box's top left corner 0215 * should be positioned. 0216 */ 0217 virtual QPoint globalPositionHint() const; 0218 0219 protected Q_SLOTS: 0220 /** 0221 * Called when an item is activated. Emits KCompletionBox::textActivated(const QString &) with the item text. 0222 * 0223 * @note For releases <= 5.81, this slot emitted KCompletionBox::activated(const QString &) with the item text. 0224 */ 0225 virtual void slotActivated(QListWidgetItem *); 0226 0227 private: 0228 std::unique_ptr<KCompletionBoxPrivate> const d; 0229 }; 0230 0231 #endif // KCOMPLETIONBOX_H