kdeui Library API Documentation

KCompletionBox Class Reference

A little utility class for "completion-widgets", like KLineEdit or KComboBox. A helper widget for "completion-widgets" (KLineEdit, KComboBox)). More...

#include <kcompletionbox.h>

Inheritance diagram for KCompletionBox:

KListBox QListBox List of all members.

Public Slots

QStringList items () const
 Returns a list of all items currently in the box.

void insertItems (const QStringList &items, int index=-1)
 Inserts items into the box.

void setItems (const QStringList &items)
 Clears the box and inserts items.

virtual void popup ()
 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.

void setTabHandling (bool enable)
 Makes this widget (when visible) capture Tab-key events to traverse the items in the dropdown list.

bool isTabHandling () const
void setCancelledText (const QString &)
 Sets the text to be emitted if the user chooses not to pick from the available matches.

QString cancelledText () const
void down ()
 Moves the selection one line down or select the first item if nothing is selected yet.

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

void pageDown ()
 Moves the selection one page down.

void pageUp ()
 Moves the selection one page up.

void home ()
 Moves the selection up to the first item.

void end ()
 Moves the selection down to the last item.

virtual void show ()
 Re-implemented for internal reasons.

virtual void hide ()
 Re-implemented for internal reasons.


Signals

void activated (const QString &)
 Emitted when an item was selected, contains the text of the selected item.

void userCancelled (const QString &)
 Emitted whenever the user chooses to ignore the available selections and close the this box.


Public Methods

 KCompletionBox (QWidget *parent, const char *name=0)
 Constructs a KCompletionBox.

 ~KCompletionBox ()
 Destroys the box.


Protected Slots

virtual void slotActivated (QListBoxItem *)
 Called when an item was activated.


Protected Methods

virtual bool eventFilter (QObject *, QEvent *)
 Reimplemented from KListBox to get events from the viewport (to hide this widget on mouse-click, Escape-presses, etc.

virtual void virtual_hook (int id, void *data)

Detailed Description

A little utility class for "completion-widgets", like KLineEdit or KComboBox. A helper widget for "completion-widgets" (KLineEdit, 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 KGlobalSettings::Completion == CompletionPopup or CompletionPopupAuto.

Author:
Carsten Pfeiffer <pfeiffer@kde.org>

Definition at line 41 of file kcompletionbox.h.


Constructor & Destructor Documentation

KCompletionBox::KCompletionBox QWidget   parent,
const char *    name = 0
 

Constructs a KCompletionBox.

Notice: the parent needs to be always 0L, so you can't specify it in the constructor. Because of that, Qt's auto-deletion does not take place, so you have to explicitly delete this widget when you don't need it anymore.

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

Definition at line 41 of file kcompletionbox.cpp.

References QListBox::clicked(), QListBox::currentChanged(), KListBox::doubleClicked(), QListBox::setColumnMode(), and slotActivated().

KCompletionBox::~KCompletionBox  
 

Destroys the box.

Definition at line 71 of file kcompletionbox.cpp.


Member Function Documentation

QStringList KCompletionBox::items   [slot]
 

Returns a list of all items currently in the box.

Definition at line 77 of file kcompletionbox.cpp.

References QListBox::count(), and QListBox::text().

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

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)

Definition at line 366 of file kcompletionbox.cpp.

References QListBox::index(), and QListBox::insertStringList().

void KCompletionBox::setItems const QStringList   items [slot]
 

Clears the box and inserts items.

Definition at line 375 of file kcompletionbox.cpp.

References QListBox::firstItem(), QListBox::insertItem(), QListBox::insertStringList(), QListBox::item(), QListBoxItem::next(), and QListBox::triggerUpdate().

void KCompletionBox::popup   [virtual, slot]
 

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.

Definition at line 219 of file kcompletionbox.cpp.

References QListBox::clearSelection(), QListBox::count(), QListBox::ensureCurrentVisible(), QSize::height(), hide(), QListBox::setCurrentItem(), and show().

void KCompletionBox::setTabHandling bool    enable [slot]
 

Makes this widget (when visible) capture Tab-key events to traverse the items in the dropdown list.

Default off, as it conflicts with the usual behavior of Tab to traverse widgets. It is useful for cases like Konqueror's Location Bar, though.

See also:
isTabHandling

Definition at line 331 of file kcompletionbox.cpp.

bool KCompletionBox::isTabHandling   [slot]
 

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

See also:
setTabHandling

Definition at line 336 of file kcompletionbox.cpp.

void KCompletionBox::setCancelledText const QString   [slot]
 

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 also:
userCancelled( const QString& )
Parameters:
txt  the text to be emitted if the user cancels this box

Definition at line 341 of file kcompletionbox.cpp.

QString KCompletionBox::cancelledText   [slot]
 

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

Definition at line 346 of file kcompletionbox.cpp.

void KCompletionBox::down   [slot]
 

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

Definition at line 286 of file kcompletionbox.cpp.

References QListBox::count(), QListBox::currentItem(), QListBox::currentText(), QListBox::highlighted(), QListBox::setCurrentItem(), and QListBox::setSelected().

Referenced by eventFilter().

void KCompletionBox::up   [slot]
 

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

Definition at line 301 of file kcompletionbox.cpp.

References QListBox::currentItem(), and QListBox::setCurrentItem().

Referenced by eventFilter().

void KCompletionBox::pageDown   [slot]
 

Moves the selection one page down.

Definition at line 307 of file kcompletionbox.cpp.

References QListBox::count(), QListBox::currentItem(), QListBox::numItemsVisible(), and QListBox::setCurrentItem().

Referenced by eventFilter().

void KCompletionBox::pageUp   [slot]
 

Moves the selection one page up.

Definition at line 314 of file kcompletionbox.cpp.

References QListBox::currentItem(), QListBox::numItemsVisible(), and QListBox::setCurrentItem().

Referenced by eventFilter().

void KCompletionBox::home   [slot]
 

Moves the selection up to the first item.

Definition at line 321 of file kcompletionbox.cpp.

References QListBox::setCurrentItem().

Referenced by eventFilter().

void KCompletionBox::end   [slot]
 

Moves the selection down to the last item.

Definition at line 326 of file kcompletionbox.cpp.

References QListBox::count(), and QListBox::setCurrentItem().

Referenced by eventFilter().

void KCompletionBox::show   [virtual, slot]
 

Re-implemented for internal reasons.

API is unaffected.

Definition at line 237 of file kcompletionbox.cpp.

References QRect::bottom(), QApplication::desktop(), QRect::right(), QPoint::x(), and QPoint::y().

Referenced by popup().

void KCompletionBox::hide   [virtual, slot]
 

Re-implemented for internal reasons.

API is unaffected.

Definition at line 267 of file kcompletionbox.cpp.

Referenced by eventFilter(), popup(), and slotActivated().

void KCompletionBox::activated const QString   [signal]
 

Emitted when an item was selected, contains the text of the selected item.

Referenced by slotActivated().

void KCompletionBox::userCancelled const QString   [signal]
 

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

bool KCompletionBox::eventFilter QObject  ,
QEvent  
[protected, virtual]
 

Reimplemented from KListBox to get events from the viewport (to hide this widget on mouse-click, Escape-presses, etc.

Definition at line 95 of file kcompletionbox.cpp.

References QKeyEvent::accept(), down(), end(), hide(), home(), QKeyEvent::key(), pageDown(), pageUp(), QMouseEvent::pos(), QKeyEvent::state(), QEvent::type(), and up().

void KCompletionBox::slotActivated QListBoxItem   [protected, virtual, slot]
 

Called when an item was activated.

Emits activated() with the item.

Definition at line 86 of file kcompletionbox.cpp.

References activated(), hide(), and QListBoxItem::text().

Referenced by KCompletionBox().


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kdelibs Version 3.1.0.
Documentation copyright © 1996-2002 the KDE developers.
Generated on Wed Oct 8 12:21:03 2003 by doxygen 1.2.18 written by Dimitri van Heesch, © 1997-2001