KDE API Reference

Contents

KCompletionBox Class

A helper widget for "completion-widgets" (KLineEdit, KComboBox)). More...

Header: #include <KCompletionBox>
CMake: find_package(KF6 REQUIRED COMPONENTS Completion)
target_link_libraries(mytarget PRIVATE KF6::Completion)
Inherits: QListWidget

Properties

Public Functions

KCompletionBox(QWidget *parent = nullptr)
bool activateOnSelect() const
QString cancelledText() const
bool isTabHandling() const
QStringList items() const

Public Slots

void down()
void end()
void home()
void insertItems(const QStringList &items, int index = -1)
void pageDown()
void pageUp()
virtual void popup()
void setActivateOnSelect(bool doEmit)
void setCancelledText(const QString &text)
void setItems(const QStringList &items)
void setTabHandling(bool enable)
virtual void setVisible(bool visible) override
void up()

Signals

(since 5.81) void textActivated(const QString &text)
void userCancelled(const QString &)

Protected Functions

QRect calculateGeometry() const
virtual QPoint globalPositionHint() const
(since 5.0) void resizeAndReposition()

Protected Slots

virtual void slotActivated(QListWidgetItem *)

Detailed Description

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.

Property Documentation

activateOnSelect : bool

Access functions:

bool activateOnSelect() const
void setActivateOnSelect(bool doEmit)

cancelledText : QString

Access functions:

QString cancelledText() const
void setCancelledText(const QString &text)

isTabHandling : bool

Access functions:

bool isTabHandling() const
void setTabHandling(bool enable)

Member Function Documentation

[explicit] KCompletionBox::KCompletionBox(QWidget *parent = nullptr)

Constructs a KCompletionBox.

The parent widget is used to give the focus back when pressing the up-button on the very first item.

bool KCompletionBox::activateOnSelect() const

Returns true if selecting an item results in the emission of the selected() signal.

Note: Getter function for property activateOnSelect.

See also setActivateOnSelect().

[protected] QRect KCompletionBox::calculateGeometry() const

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.

QString KCompletionBox::cancelledText() const

Returns the text set via setCancelledText() or QString().

Note: Getter function for property cancelledText.

See also setCancelledText().

[slot] void KCompletionBox::down()

Moves the selection one line down or select the first item if nothing is selected yet.

[slot] void KCompletionBox::end()

Moves the selection down to the last item.

[virtual protected] QPoint KCompletionBox::globalPositionHint() const

The preferred global coordinate at which the completion box's top left corner should be positioned.

[slot] void KCompletionBox::home()

Moves the selection up to the first item.

[slot] void KCompletionBox::insertItems(const QStringList &items, int index = -1)

Inserts items into the box. Does not clear the items before. index determines at which position items will be inserted. (defaults to appending them at the end)

bool KCompletionBox::isTabHandling() const

Returns true if this widget is handling Tab-key events to traverse the items in the dropdown list, otherwise false.

Default is true.

Note: Getter function for property isTabHandling.

See also setTabHandling.

QStringList KCompletionBox::items() const

Returns a list of all items currently in the box.

See also setItems().

[slot] void KCompletionBox::pageDown()

Moves the selection one page down.

[slot] void KCompletionBox::pageUp()

Moves the selection one page up.

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.

[protected, since 5.0] void KCompletionBox::resizeAndReposition()

This properly resizes and repositions the listbox.

This function was introduced in 5.0.

[slot] void KCompletionBox::setActivateOnSelect(bool doEmit)

Set whether or not the selected signal should be emitted when an item is selected. By default the selected() signal is emitted.

doEmit false if the signal should not be emitted.

Note: Setter function for property activateOnSelect.

See also activateOnSelect().

[slot] void KCompletionBox::setCancelledText(const QString &text)

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.

text the text to be emitted if the user cancels this box

Note: Setter function for property cancelledText.

See also cancelledText() and userCancelled( const QString& ).

[slot] void KCompletionBox::setItems(const QStringList &items)

Clears the box and inserts items.

See also items().

[slot] void KCompletionBox::setTabHandling(bool enable)

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.

Note: Setter function for property isTabHandling.

See also isTabHandling.

[override virtual slot] void KCompletionBox::setVisible(bool visible)

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.

[virtual protected slot] void KCompletionBox::slotActivated(QListWidgetItem *)

Called when an item is activated. Emits KCompletionBox::textActivated(const QString &) with the item text.

Note: For releases <= 5.81, this slot emitted KCompletionBox::activated(const QString &) with the item text.

[signal, since 5.81] void KCompletionBox::textActivated(const QString &text)

Emitted when an item is selected, text is the text of the selected item.

This function was introduced in 5.81.

[slot] void KCompletionBox::up()

Moves the selection one line up or select the first item if nothing is selected yet.

[signal] void KCompletionBox::userCancelled(const QString &)

Emitted whenever the user chooses to ignore the available selections and closes this box.