.TH "KHistoryCombo" kde3 "11 Jun 2005" "Version Version 3.4.1" "kdeui Library" \" -*- nroff -*-
.ad l
.nh
.SH NAME
KHistoryCombo \- A combobox for offering a history and completion.  

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

.in +1c
.ti -1c
.RI "void \fBaddToHistory\fP (const \fBQString\fP &item)"
.br
.ti -1c
.RI "void \fBclearHistory\fP ()"
.br
.in -1c
.SS "Signals"

.in +1c
.ti -1c
.RI "void \fBcleared\fP ()"
.br
.in -1c
.SS "Public Member Functions"

.in +1c
.ti -1c
.RI "\fBKHistoryCombo\fP (\fBQWidget\fP *parent=0L, const char *name=0L)"
.br
.ti -1c
.RI "\fBKHistoryCombo\fP (bool useCompletion, \fBQWidget\fP *parent=0L, const char *name=0L)"
.br
.ti -1c
.RI "\fB~KHistoryCombo\fP ()"
.br
.ti -1c
.RI "void \fBsetHistoryItems\fP (\fBQStringList\fP items)"
.br
.ti -1c
.RI "void \fBsetHistoryItems\fP (\fBQStringList\fP items, bool setCompletionList)"
.br
.ti -1c
.RI "\fBQStringList\fP \fBhistoryItems\fP () const "
.br
.ti -1c
.RI "bool \fBremoveFromHistory\fP (const \fBQString\fP &item)"
.br
.ti -1c
.RI "void \fBsetPixmapProvider\fP (\fBKPixmapProvider\fP *prov)"
.br
.ti -1c
.RI "\fBKPixmapProvider\fP * \fBpixmapProvider\fP () const "
.br
.ti -1c
.RI "void \fBreset\fP ()"
.br
.in -1c
.SS "Protected Member Functions"

.in +1c
.ti -1c
.RI "virtual void \fBkeyPressEvent\fP (\fBQKeyEvent\fP *)"
.br
.ti -1c
.RI "virtual void \fBwheelEvent\fP (\fBQWheelEvent\fP *ev)"
.br
.ti -1c
.RI "void \fBinsertItems\fP (const \fBQStringList\fP &items)"
.br
.ti -1c
.RI "bool \fBuseCompletion\fP () const "
.br
.ti -1c
.RI "virtual void \fBvirtual_hook\fP (int id, void *data)"
.br
.in -1c
.SS "Properties"

.in +1c
.ti -1c
.RI "\fBQStringList\fP \fBhistoryItems\fP"
.br
.in -1c
.SH "Detailed Description"
.PP 
A combobox for offering a history and completion. 

A combobox which implements a history like a unix shell. You can navigate through all the items by using the Up or Down arrows (configurable of course). Additionally, weighted completion is available. So you should load and save the completion list to preserve the weighting between sessions.
.PP
KHistoryCombo obeys the HISTCONTROL environment variable to determine whether duplicates in the history should be tolerated in \fBaddToHistory()\fP or not. During construction of KHistoryCombo, duplicates will be disabled when HISTCONTROL is set to 'ignoredups' or 'ignoreboth'. Otherwise, duplicates are enabled by default.
.PP
\fBAuthor:\fP
.RS 4
Carsten Pfeiffer <pfeiffer@kde.org> 
.RE
.PP

.PP
Definition at line 533 of file kcombobox.h.
.SH "Constructor & Destructor Documentation"
.PP 
.SS "KHistoryCombo::KHistoryCombo (\fBQWidget\fP * parent = \fC0L\fP, const char * name = \fC0L\fP)"
.PP
Constructs a 'read-write' combobox. 
.PP
A read-only history combobox doesn't make much sense, so it is only available as read-write. Completion will be used automatically for the items in the combo.
.PP
The insertion-policy is set to NoInsertion, you have to add the items yourself via the slot addToHistory. If you want every item added, use
.PP
.PP
.nf
 connect( combo, SIGNAL( activated( const QString& )),
          combo, SLOT( addToHistory( const QString& )));
.fi
.PP
.PP
Use \fBQComboBox::setMaxCount()\fP to limit the history.
.PP
\fCparent\fP the parent object of this widget. \fCname\fP the name of this widget. 
.PP
Definition at line 348 of file kcombobox.cpp.
.SS "KHistoryCombo::KHistoryCombo (bool useCompletion, \fBQWidget\fP * parent = \fC0L\fP, const char * name = \fC0L\fP)"
.PP
Same as the previous constructor, but additionally has the option to specify whether you want to let KHistoryCombo handle completion or not. 
.PP
If set to \fCtrue\fP, KHistoryCombo will sync the completion to the contents of the combobox. 
.PP
Definition at line 355 of file kcombobox.cpp.
.SS "KHistoryCombo::~\fBKHistoryCombo\fP ()"
.PP
Destructs the combo, the completion-object and the pixmap-provider. 
.PP
Definition at line 383 of file kcombobox.cpp.
.SH "Member Function Documentation"
.PP 
.SS "void KHistoryCombo::setHistoryItems (\fBQStringList\fP items)\fC [inline]\fP"
.PP
Inserts \fCitems\fP into the combobox. 
.PP
\fCitems\fP might get truncated if it is longer than \fBmaxCount()\fP
.PP
\fBSee also:\fP
.RS 4
\fBhistoryItems\fP 
.RE
.PP

.PP
Definition at line 581 of file kcombobox.h.
.SS "void KHistoryCombo::setHistoryItems (\fBQStringList\fP items, bool setCompletionList)"
.PP
Inserts \fCitems\fP into the combobox. 
.PP
\fCitems\fP might get truncated if it is longer than \fBmaxCount()\fP
.PP
Set \fCsetCompletionList\fP to true, if you don't have a list of completions. This tells KHistoryCombo to use all the items for the completion object as well. You won't have the benefit of weighted completion though, so normally you should do something like 
.PP
.nf
 KConfig *config = kapp->config();
 QStringList list;

 // load the history and completion list after creating the history combo
 list = config->readListEntry( 'Completion list' );
 combo->completionObject()->setItems( list );
 list = config->readListEntry( 'History list' );
 combo->setHistoryItems( list );

 [...]

 // save the history and completion list when the history combo is
 // destroyed
 list = combo->completionObject()->items()
 config->writeEntry( 'Completion list', list );
 list = combo->historyItems();
 config->writeEntry( 'History list', list );

.fi
.PP
.PP
Be sure to use different names for saving with \fBKConfig\fP if you have more than one KHistoryCombo.
.PP
Note: When \fCsetCompletionList\fP is true, the items are inserted into the \fBKCompletion\fP object with mode \fBKCompletion::Insertion\fP and the mode is set to \fBKCompletion::Weighted\fP afterwards.
.PP
\fBSee also:\fP
.RS 4
\fBhistoryItems\fP 
.PP
\fBKComboBox::completionObject\fP 
.PP
\fBKCompletion::setItems\fP 
.PP
\fBKCompletion::items\fP 
.RE
.PP

.PP
Definition at line 388 of file kcombobox.cpp.
.PP
References QComboBox::clear(), QComboBox::clearEdit(), KCompletionBase::completionObject(), insertItems(), QComboBox::maxCount(), KCompletion::setItems(), KCompletion::setOrder(), and useCompletion().
.SS "\fBQStringList\fP KHistoryCombo::historyItems () const"
.PP
Returns the list of history items. 
.PP
Empty, when this is not a read-write combobox.
.PP
\fBSee also:\fP
.RS 4
\fBsetHistoryItems\fP 
.RE
.PP

.PP
Referenced by setPixmapProvider().
.SS "bool KHistoryCombo::removeFromHistory (const \fBQString\fP & item)"
.PP
Removes all items named \fCitem\fP. 
.PP
\fBReturns:\fP
.RS 4
\fCtrue\fP if at least one item was removed.
.RE
.PP
\fBSee also:\fP
.RS 4
\fBaddToHistory\fP 
.RE
.PP

.PP
Definition at line 499 of file kcombobox.cpp.
.PP
References KCompletionBase::completionObject(), QComboBox::count(), QComboBox::currentText(), KCompletion::removeItem(), QComboBox::removeItem(), QComboBox::setEditText(), QComboBox::text(), and useCompletion().
.SS "void KHistoryCombo::setPixmapProvider (\fBKPixmapProvider\fP * prov)"
.PP
Sets a pixmap provider, so that items in the combobox can have a pixmap. 
.PP
\fBKPixmapProvider\fP is just an abstract class with the one pure virtual method \fBKPixmapProvider::pixmapFor()\fP. This method is called whenever an item is added to the KHistoryComboBox. Implement it to return your own custom pixmaps, or use the \fBKURLPixmapProvider\fP from libkio, which uses \fBKMimeType::pixmapForURL\fP to resolve icons.
.PP
Set \fCprov\fP to 0L if you want to disable pixmaps. Default no pixmaps.
.PP
\fBSee also:\fP
.RS 4
\fBpixmapProvider\fP 
.RE
.PP

.PP
Definition at line 635 of file kcombobox.cpp.
.PP
References QComboBox::clear(), QComboBox::count(), historyItems(), and insertItems().
.SS "\fBKPixmapProvider\fP* KHistoryCombo::pixmapProvider () const\fC [inline]\fP"
.PP
\fBReturns:\fP
.RS 4
the current pixmap provider. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBsetPixmapProvider\fP 
.PP
\fBKPixmapProvider\fP 
.RE
.PP

.PP
Definition at line 664 of file kcombobox.h.
.SS "void KHistoryCombo::reset ()\fC [inline]\fP"
.PP
Resets the current position of the up/down history. 
.PP
Call this when you manually call \fBsetCurrentItem()\fP or \fBclearEdit()\fP. 
.PP
Definition at line 670 of file kcombobox.h.
.SS "void KHistoryCombo::addToHistory (const \fBQString\fP & item)\fC [slot]\fP"
.PP
Adds an item to the end of the history list and to the completion list. 
.PP
If \fBmaxCount()\fP is reached, the first item of the list will be removed.
.PP
If the last inserted item is the same as \fCitem\fP, it will not be inserted again.
.PP
If \fBduplicatesEnabled()\fP is false, any equal existing item will be removed before \fCitem\fP is added.
.PP
Note: By using this method and not the Q and \fBKComboBox\fP \fBinsertItem()\fP methods, you make sure that the combobox stays in sync with the completion. It would be annoying if completion would give an item not in the combobox, and vice versa.
.PP
\fBSee also:\fP
.RS 4
\fBremoveFromHistory\fP 
.PP
\fBQComboBox::setDuplicatesEnabled\fP 
.RE
.PP

.PP
Definition at line 447 of file kcombobox.cpp.
.PP
References KCompletion::addItem(), KCompletionBase::completionObject(), KComboBox::contains(), QComboBox::count(), QComboBox::currentItem(), QComboBox::duplicatesEnabled(), QComboBox::insertItem(), QComboBox::maxCount(), KPixmapProvider::pixmapFor(), KCompletion::removeItem(), QComboBox::removeItem(), KComboBox::setCurrentItem(), QComboBox::text(), and useCompletion().
.SS "void KHistoryCombo::clearHistory ()\fC [slot]\fP"
.PP
Clears the history and the completion list. 
.PP
Definition at line 427 of file kcombobox.cpp.
.PP
References KCompletion::clear(), QComboBox::clear(), KCompletionBase::completionObject(), QComboBox::currentText(), QComboBox::setEditText(), and useCompletion().
.SS "void KHistoryCombo::cleared ()\fC [signal]\fP"
.PP
Emitted when the history was cleared by the entry in the popup menu. 
.PP
.SS "void KHistoryCombo::keyPressEvent (\fBQKeyEvent\fP *)\fC [protected, virtual]\fP"
.PP
Handling key-events, the shortcuts to rotate the items. 
.PP
Definition at line 594 of file kcombobox.cpp.
.PP
References KComboBox::contains().
.SS "void KHistoryCombo::wheelEvent (\fBQWheelEvent\fP * ev)\fC [protected, virtual]\fP"
.PP
Handling wheel-events, to rotate the items. 
.PP
Reimplemented from \fBKComboBox\fP.
.PP
Definition at line 610 of file kcombobox.cpp.
.PP
References QComboBox::listBox(), and QApplication::sendEvent().
.SS "void KHistoryCombo::insertItems (const \fBQStringList\fP & items)\fC [protected]\fP"
.PP
Inserts \fCitems\fP into the combo, honoring \fBpixmapProvider()\fP Does not update the completionObject. 
.PP
Note: \fBduplicatesEnabled()\fP is not honored here.
.PP
Called from \fBsetHistoryItems()\fP and \fBsetPixmapProvider()\fP 
.PP
Definition at line 653 of file kcombobox.cpp.
.PP
References QComboBox::insertItem(), QString::isEmpty(), and KPixmapProvider::pixmapFor().
.PP
Referenced by setHistoryItems(), and setPixmapProvider().
.SS "bool KHistoryCombo::useCompletion () const\fC [inline, protected]\fP"
.PP
\fBReturns:\fP
.RS 4
if we can modify the completion object or not. 
.RE
.PP

.PP
Definition at line 729 of file kcombobox.h.
.PP
References KCompletionBase::compObj().
.PP
Referenced by addToHistory(), clearHistory(), removeFromHistory(), and setHistoryItems().

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