.TH "KCompletionBox" kde3 "11 Jun 2005" "Version Version 3.4.1" "kdeui Library" \" -*- nroff -*-
.ad l
.nh
.SH NAME
KCompletionBox \- A helper widget for 'completion-widgets' (\fBKLineEdit\fP, \fBKComboBox\fP)).  

.PP
.SH SYNOPSIS
.br
.PP
\fC#include <kcompletionbox.h>\fP
.PP
Inherits \fBKListBox\fP.
.PP
.SS "Public Slots"

.in +1c
.ti -1c
.RI "\fBQStringList\fP \fBitems\fP () const "
.br
.ti -1c
.RI "void \fBinsertItems\fP (const \fBQStringList\fP &items, int \fBindex\fP=-1)"
.br
.ti -1c
.RI "void \fBsetItems\fP (const \fBQStringList\fP &items)"
.br
.ti -1c
.RI "virtual void \fBpopup\fP ()"
.br
.ti -1c
.RI "void \fBsetTabHandling\fP (bool enable)"
.br
.ti -1c
.RI "bool \fBisTabHandling\fP () const "
.br
.ti -1c
.RI "void \fBsetCancelledText\fP (const \fBQString\fP &txt)"
.br
.ti -1c
.RI "\fBQString\fP \fBcancelledText\fP () const "
.br
.ti -1c
.RI "void \fBsetActivateOnSelect\fP (bool state)"
.br
.ti -1c
.RI "void \fBdown\fP ()"
.br
.ti -1c
.RI "void \fBup\fP ()"
.br
.ti -1c
.RI "void \fBpageDown\fP ()"
.br
.ti -1c
.RI "void \fBpageUp\fP ()"
.br
.ti -1c
.RI "void \fBhome\fP ()"
.br
.ti -1c
.RI "void \fBend\fP ()"
.br
.ti -1c
.RI "virtual void \fBshow\fP ()"
.br
.ti -1c
.RI "virtual void \fBhide\fP ()"
.br
.in -1c
.SS "Signals"

.in +1c
.ti -1c
.RI "void \fBactivated\fP (const \fBQString\fP &)"
.br
.ti -1c
.RI "void \fBuserCancelled\fP (const \fBQString\fP &)"
.br
.in -1c
.SS "Public Member Functions"

.in +1c
.ti -1c
.RI "\fBKCompletionBox\fP (\fBQWidget\fP *parent, const char *name=0)"
.br
.ti -1c
.RI "\fB~KCompletionBox\fP ()"
.br
.ti -1c
.RI "virtual \fBQSize\fP \fBsizeHint\fP () const "
.br
.ti -1c
.RI "bool \fBactivateOnSelect\fP () const "
.br
.in -1c
.SS "Protected Slots"

.in +1c
.ti -1c
.RI "virtual void \fBslotActivated\fP (\fBQListBoxItem\fP *)"
.br
.in -1c
.SS "Protected Member Functions"

.in +1c
.ti -1c
.RI "\fBQRect\fP \fBcalculateGeometry\fP () const "
.br
.ti -1c
.RI "void \fBsizeAndPosition\fP ()"
.br
.ti -1c
.RI "virtual bool \fBeventFilter\fP (\fBQObject\fP *, \fBQEvent\fP *)"
.br
.ti -1c
.RI "virtual void \fBvirtual_hook\fP (int id, void *data)"
.br
.in -1c
.SS "Properties"

.in +1c
.ti -1c
.RI "bool \fBisTabHandling\fP"
.br
.ti -1c
.RI "\fBQString\fP \fBcancelledText\fP"
.br
.ti -1c
.RI "bool \fBactivateOnSelect\fP"
.br
.in -1c
.SH "Detailed Description"
.PP 
A helper widget for 'completion-widgets' (\fBKLineEdit\fP, \fBKComboBox\fP)). 

A little utility class for 'completion-widgets', like \fBKLineEdit\fP or \fBKComboBox\fP. 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.
.PP
It is used when \fBKGlobalSettings::Completion\fP == CompletionPopup or CompletionPopupAuto.
.PP
\fBAuthor:\fP
.RS 4
Carsten Pfeiffer <pfeiffer@kde.org> 
.RE
.PP

.PP
Definition at line 43 of file kcompletionbox.h.
.SH "Constructor & Destructor Documentation"
.PP 
.SS "KCompletionBox::KCompletionBox (\fBQWidget\fP * parent, const char * name = \fC0\fP)"
.PP
Constructs a KCompletionBox. 
.PP
The parent widget is used to give the focus back when pressing the up-button on the very first item. 
.PP
Definition at line 47 of file kcompletionbox.cpp.
.PP
References QListBox::clicked(), QListBox::currentChanged(), KListBox::doubleClicked(), QListBox::setColumnMode(), and slotActivated().
.SS "KCompletionBox::~\fBKCompletionBox\fP ()"
.PP
Destroys the box. 
.PP
Definition at line 79 of file kcompletionbox.cpp.
.SH "Member Function Documentation"
.PP 
.SS "bool KCompletionBox::activateOnSelect () const"
.PP
\fBReturns:\fP
.RS 4
true if selecting an item results in the emition of the \fBselected\fP signal.
.RE
.PP
\fBSince:\fP
.RS 4
3.4.1 
.RE
.PP

.SS "\fBQStringList\fP KCompletionBox::items () const\fC [slot]\fP"
.PP
Returns a list of all items currently in the box. 
.PP
Definition at line 85 of file kcompletionbox.cpp.
.PP
References QListBox::firstItem(), QListBoxItem::next(), and QListBoxItem::text().
.PP
Referenced by setItems().
.SS "void KCompletionBox::insertItems (const \fBQStringList\fP & items, int index = \fC-1\fP)\fC [slot]\fP"
.PP
Inserts \fCitems\fP into the box. 
.PP
Does not clear the items before. \fCindex\fP determines at which position \fCitems\fP will be inserted. (defaults to appending them at the end) 
.PP
Definition at line 468 of file kcompletionbox.cpp.
.PP
References QListBox::insertStringList().
.SS "void KCompletionBox::setItems (const \fBQStringList\fP & items)\fC [slot]\fP"
.PP
Clears the box and inserts \fCitems\fP. 
.PP
Definition at line 477 of file kcompletionbox.cpp.
.PP
References QListBox::firstItem(), QListBox::insertItem(), QListBox::insertStringList(), items(), QListBoxItem::next(), sizeAndPosition(), and QListBox::triggerUpdate().
.PP
Referenced by KLineEdit::setCompletedItems().
.SS "void KCompletionBox::popup ()\fC [virtual, slot]\fP"
.PP
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. 
.PP
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.
.PP
Make sure to \fBhide()\fP the box when appropriate. 
.PP
Definition at line 250 of file kcompletionbox.cpp.
.PP
References QListBox::clearSelection(), QListBox::count(), QListBox::ensureCurrentVisible(), hide(), QListBox::setCurrentItem(), show(), and sizeAndPosition().
.SS "void KCompletionBox::setTabHandling (bool enable)\fC [slot]\fP"
.PP
Makes this widget (when visible) capture Tab-key events to traverse the items in the dropdown list. 
.PP
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.
.PP
\fBSee also:\fP
.RS 4
\fBisTabHandling\fP 
.RE
.PP

.PP
Definition at line 426 of file kcompletionbox.cpp.
.SS "bool KCompletionBox::isTabHandling () const\fC [slot]\fP"
.PP
\fBReturns:\fP
.RS 4
true if this widget is handling Tab-key events to traverse the items in the dropdown list, otherwise false.
.RE
.PP
Default is false.
.PP
\fBSee also:\fP
.RS 4
\fBsetTabHandling\fP 
.RE
.PP

.SS "void KCompletionBox::setCancelledText (const \fBQString\fP & txt)\fC [slot]\fP"
.PP
Sets the text to be emitted if the user chooses not to pick from the available matches. 
.PP
If the canceled text is not set through this function, the userCancelled signal will not be emitted.
.PP
\fBSee also:\fP
.RS 4
\fBuserCancelled( const QString& )\fP 
.RE
.PP
\fBParameters:\fP
.RS 4
\fItxt\fP the text to be emitted if the user cancels this box 
.RE
.PP

.PP
Definition at line 436 of file kcompletionbox.cpp.
.SS "\fBQString\fP KCompletionBox::cancelledText () const\fC [slot]\fP"
.PP
\fBReturns:\fP
.RS 4
the text set via \fBsetCancelledText()\fP or QString::null. 
.RE
.PP

.SS "void KCompletionBox::setActivateOnSelect (bool state)\fC [slot]\fP"
.PP
Set whether or not the selected signal should be emitted when an item is selected. 
.PP
By default the \fBselevted\fP signal is emitted.
.PP
\fBParameters:\fP
.RS 4
\fIstate\fP false if the signal should not be emitted. 
.RE
.PP
\fBSince:\fP
.RS 4
3.4.1 
.RE
.PP

.PP
Definition at line 549 of file kcompletionbox.cpp.
.SS "void KCompletionBox::down ()\fC [slot]\fP"
.PP
Moves the selection one line down or select the first item if nothing is selected yet. 
.PP
Definition at line 381 of file kcompletionbox.cpp.
.PP
References QListBox::count(), QListBox::currentItem(), QListBox::currentText(), QListBox::highlighted(), QListBox::setCurrentItem(), and QListBox::setSelected().
.PP
Referenced by eventFilter().
.SS "void KCompletionBox::up ()\fC [slot]\fP"
.PP
Moves the selection one line up or select the first item if nothing is selected yet. 
.PP
Definition at line 396 of file kcompletionbox.cpp.
.PP
References QListBox::currentItem(), and QListBox::setCurrentItem().
.PP
Referenced by eventFilter().
.SS "void KCompletionBox::pageDown ()\fC [slot]\fP"
.PP
Moves the selection one page down. 
.PP
Definition at line 402 of file kcompletionbox.cpp.
.PP
References QListBox::count(), QListBox::currentItem(), QListBox::numItemsVisible(), and QListBox::setCurrentItem().
.PP
Referenced by eventFilter().
.SS "void KCompletionBox::pageUp ()\fC [slot]\fP"
.PP
Moves the selection one page up. 
.PP
Definition at line 409 of file kcompletionbox.cpp.
.PP
References QListBox::currentItem(), QListBox::numItemsVisible(), and QListBox::setCurrentItem().
.PP
Referenced by eventFilter().
.SS "void KCompletionBox::home ()\fC [slot]\fP"
.PP
Moves the selection up to the first item. 
.PP
Definition at line 416 of file kcompletionbox.cpp.
.PP
References QListBox::setCurrentItem().
.PP
Referenced by eventFilter().
.SS "void KCompletionBox::end ()\fC [slot]\fP"
.PP
Moves the selection down to the last item. 
.PP
Definition at line 421 of file kcompletionbox.cpp.
.PP
References QListBox::count(), and QListBox::setCurrentItem().
.PP
Referenced by eventFilter().
.SS "void KCompletionBox::show ()\fC [virtual, slot]\fP"
.PP
Re-implemented for internal reasons. 
.PP
API is unaffected. 
.PP
Definition at line 300 of file kcompletionbox.cpp.
.PP
References sizeAndPosition().
.PP
Referenced by popup().
.SS "void KCompletionBox::hide ()\fC [virtual, slot]\fP"
.PP
Re-implemented for internal reasons. 
.PP
API is unaffected. 
.PP
Definition at line 324 of file kcompletionbox.cpp.
.PP
Referenced by eventFilter(), popup(), and slotActivated().
.SS "void KCompletionBox::activated (const \fBQString\fP &)\fC [signal]\fP"
.PP
Emitted when an item was selected, contains the text of the selected item. 
.PP
Referenced by slotActivated().
.SS "void KCompletionBox::userCancelled (const \fBQString\fP &)\fC [signal]\fP"
.PP
Emitted whenever the user chooses to ignore the available selections and close the this box. 
.PP
.SS "\fBQRect\fP KCompletionBox::calculateGeometry () const\fC [protected]\fP"
.PP
This calculates the size of the dropdown and the relative position of the top left corner with respect to the parent widget. 
.PP
This matches the geometry and position normally used by K/QComboBox when used with one. 
.PP
Definition at line 332 of file kcompletionbox.cpp.
.PP
References QListBox::count(), QObject::inherits(), QRect::isNull(), QListBox::itemHeight(), QObject::parent(), QRect::width(), QPoint::x(), and QPoint::y().
.PP
Referenced by sizeAndPosition().
.SS "void KCompletionBox::sizeAndPosition ()\fC [protected]\fP"
.PP
This properly sizes and positions the listbox. 
.PP
Definition at line 268 of file kcompletionbox.cpp.
.PP
References QRect::bottom(), calculateGeometry(), KGlobalSettings::desktopGeometry(), QRect::height(), QRect::right(), QRect::size(), QRect::x(), QPoint::x(), QRect::y(), and QPoint::y().
.PP
Referenced by popup(), setItems(), and show().
.SS "bool KCompletionBox::eventFilter (\fBQObject\fP *, \fBQEvent\fP *)\fC [protected, virtual]\fP"
.PP
Reimplemented from \fBKListBox\fP to get events from the viewport (to hide this widget on mouse-click, Escape-presses, etc. 
.PP
Definition at line 108 of file kcompletionbox.cpp.
.PP
References QMouseEvent::accept(), QKeyEvent::accept(), QListBox::currentText(), down(), end(), hide(), QListBox::highlighted(), home(), QKeyEvent::key(), pageDown(), pageUp(), QMouseEvent::pos(), QListBox::selectedItem(), QKeyEvent::state(), and up().
.SS "void KCompletionBox::slotActivated (\fBQListBoxItem\fP *)\fC [protected, virtual, slot]\fP"
.PP
Called when an item was activated. 
.PP
Emits \fBactivated()\fP with the item. 
.PP
Definition at line 99 of file kcompletionbox.cpp.
.PP
References activated(), and hide().
.PP
Referenced by KCompletionBox().

.SH "Author"
.PP 
Generated automatically by Doxygen for kdeui Library from the source code.
