KHistoryCombo class Reference (kdeui Library)

| # kdeui Library API Documentation
Overview | Class Hierarchy | Classes | Classes (annotated) | Members | Source Files

# KHistoryCombo Class Reference

A combobox which implements a history like a unix shell. A combobox for offering a history and completion. More...

`#include <kcombobox.h>`

Inheritance diagram for KHistoryCombo:

[legend]
Collaboration diagram for KHistoryCombo:

[legend]
List of all members.

## Public Slots
void | addToHistory (const QString &item)
| Adds an item to the end of the history list and to the completion list.
void | clearHistory ()
| Clears the history and the completion list.
## Signals
void | cleared ()
| Emitted when the history was cleared by the entry in the popup menu.
## Public Member Functions
| KHistoryCombo (QWidget *parent=0L, const char *name=0L)
| Constructs a "read-write" combobox.
| KHistoryCombo (bool useCompletion, QWidget *parent=0L, const char *name=0L)
| Same as the previous constructor, but additionally has the option to specify whether you want to let KHistoryCombo handle completion or not.
| ~KHistoryCombo ()
| Destructs the combo, the completion-object and the pixmap-provider.
void | setHistoryItems (QStringList items)
| Inserts `items` into the combobox.
void | setHistoryItems (QStringList items, bool setCompletionList)
| Inserts `items` into the combobox.
QStringList | historyItems () const
| Returns the list of history items.
bool | removeFromHistory (const QString &item)
| Removes all items named `item`.
void | setPixmapProvider (KPixmapProvider *prov)
| Sets a pixmap provider, so that items in the combobox can have a pixmap.
KPixmapProvider * | pixmapProvider () const
void | reset ()
| Resets the current position of the up/down history.
## Protected Member Functions
virtual void | keyPressEvent (QKeyEvent *)
| Handling key-events, the shortcuts to rotate the items.
virtual void | wheelEvent (QWheelEvent *ev)
| Handling wheel-events, to rotate the items.
void | insertItems (const QStringList &items)
| Inserts `items` into the combo, honouring pixmapProvider() Does not update the completionObject.
bool | useCompletion () const
virtual void | virtual_hook (int id, void *data)

## Detailed Description

A combobox which implements a history like a unix shell. A combobox for offering a history and completion.

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.

KHistoryCombo obeys the HISTCONTROL environment variable to determine whether duplicates in the history should be tolerated in addToHistory() or not. During construction of KHistoryCombo, duplicates will be disabled when HISTCONTROL is set to "ignoredups" or "ignoreboth". Otherwise, duplicates are enabled by default.

Author:
  Carsten Pfeiffer <pfeiffer@kde.org>

Definition at line 535 of file kcombobox.h.

## Constructor & Destructor Documentation

KHistoryCombo::KHistoryCombo | ( | QWidget * | parent = 0L,
|  | const char * | name = 0L
| ) |

| Constructs a "read-write" combobox. 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. 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
     connect( combo, SIGNAL( activated( const QString& )),
              combo, SLOT( addToHistory( const QString& )));

Use QComboBox::setMaxCount() to limit the history.

`parent` the parent object of this widget. `name` the name of this widget.

Definition at line 356 of file kcombobox.cpp.

References KStdAccel::name().

KHistoryCombo::KHistoryCombo | ( | bool | useCompletion,
|  | QWidget * | parent = 0L,
|  | const char * | name = 0L
| ) |

| Same as the previous constructor, but additionally has the option to specify whether you want to let KHistoryCombo handle completion or not. If set to `true`, KHistoryCombo will sync the completion to the contents of the combobox. Definition at line 363 of file kcombobox.cpp. References KStdAccel::name().

KHistoryCombo::~KHistoryCombo | ( |  | ) |

| Destructs the combo, the completion-object and the pixmap-provider. Definition at line 391 of file kcombobox.cpp.

## Member Function Documentation

void KHistoryCombo::setHistoryItems | ( | QStringList | items | ) | `[inline]`

| Inserts `items` into the combobox. `items` might get truncated if it is longer than maxCount() See also: historyItems Definition at line 583 of file kcombobox.h.

void KHistoryCombo::setHistoryItems | ( | QStringList | items,
|  | bool | setCompletionList
| ) |

| Inserts `items` into the combobox. `items` might get truncated if it is longer than maxCount() Set `setCompletionList` 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
     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 );
Be sure to use different names for saving with KConfig if you have more than one KHistoryCombo. Note: When `setCompletionList` is true, the items are inserted into the KCompletion object with mode KCompletion::Insertion and the mode is set to KCompletion::Weighted afterwards. See also: historyItems KComboBox::completionObject KCompletion::setItems KCompletion::items Definition at line 396 of file kcombobox.cpp. References QComboBox::clear(), QComboBox::clearEdit(), KCompletionBase::completionObject(), KCompletion::Insertion, insertItems(), QComboBox::maxCount(), KCompletion::setItems(), KCompletion::setOrder(), useCompletion(), and KCompletion::Weighted.

QStringList KHistoryCombo::historyItems | ( |  | ) | const

| Returns the list of history items. Empty, when this is not a read-write combobox. See also: setHistoryItems Definition at line 418 of file kcombobox.cpp. References QComboBox::count(), and QComboBox::text(). Referenced by setPixmapProvider().

bool KHistoryCombo::removeFromHistory | ( | const QString & | item | ) |

| Removes all items named `item`. Returns: `true` if at least one item was removed. See also: addToHistory Definition at line 489 of file kcombobox.cpp. References KCompletionBase::completionObject(), QComboBox::count(), QComboBox::currentText(), QString::isEmpty(), KCompletion::removeItem(), QComboBox::removeItem(), QComboBox::setEditText(), QComboBox::text(), and useCompletion().

void KHistoryCombo::setPixmapProvider | ( | KPixmapProvider * | prov | ) |

| Sets a pixmap provider, so that items in the combobox can have a pixmap. KPixmapProvider is just an abstract class with the one pure virtual method KPixmapProvider::pixmapFor(). This method is called whenever an item is added to the KHistoryComboBox. Implement it to return your own custom pixmaps, or use the KURLPixmapProvider from libkio, which uses KMimeType::pixmapForURL to resolve icons. Set `prov` to 0L if you want to disable pixmaps. Default no pixmaps. See also: pixmapProvider Definition at line 615 of file kcombobox.cpp. References QComboBox::clear(), QComboBox::count(), historyItems(), and insertItems().

KPixmapProvider* KHistoryCombo::pixmapProvider | ( |  | ) | const`[inline]`

| Returns: the current pixmap provider. See also: setPixmapProvider KPixmapProvider Definition at line 666 of file kcombobox.h.

void KHistoryCombo::reset | ( |  | ) | `[inline]`

| Resets the current position of the up/down history. Call this when you manually call setCurrentItem() or clearEdit(). Definition at line 672 of file kcombobox.h.

void KHistoryCombo::addToHistory | ( | const QString & | item | ) | `[slot]`

| Adds an item to the end of the history list and to the completion list. If maxCount() is reached, the first item of the list will be removed. If the last inserted item is the same as `item`, it will not be inserted again. If duplicatesEnabled() is false, any equal existing item will be removed before `item` is added. Note: By using this method and not the Q and KComboBox insertItem() 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. See also: removeFromHistory QComboBox::setDuplicatesEnabled Definition at line 443 of file kcombobox.cpp. References KCompletion::addItem(), KCompletionBase::completionObject(), KComboBox::contains(), QComboBox::count(), QComboBox::currentItem(), QComboBox::duplicatesEnabled(), QComboBox::insertItem(), QString::isEmpty(), QComboBox::maxCount(), KPixmapProvider::pixmapFor(), KCompletion::removeItem(), QComboBox::removeItem(), KComboBox::setCurrentItem(), KIcon::SizeSmall, QComboBox::text(), and useCompletion().

void KHistoryCombo::clearHistory | ( |  | ) | `[slot]`

| Clears the history and the completion list. Definition at line 427 of file kcombobox.cpp. References KCompletion::clear(), QComboBox::clear(), KCompletionBase::completionObject(), and useCompletion().

void KHistoryCombo::cleared | ( |  | ) | `[signal]`

| Emitted when the history was cleared by the entry in the popup menu.

void KHistoryCombo::keyPressEvent | ( | QKeyEvent * |  | ) | `[protected, virtual]`

| Handling key-events, the shortcuts to rotate the items. Definition at line 575 of file kcombobox.cpp. References KStdAccel::isEqual().

void KHistoryCombo::wheelEvent | ( | QWheelEvent * | ev | ) | `[protected, virtual]`

| Handling wheel-events, to rotate the items. Reimplemented from KComboBox. Definition at line 590 of file kcombobox.cpp. References QWheelEvent::accept(), QWheelEvent::delta(), QComboBox::listBox(), and QApplication::sendEvent().

void KHistoryCombo::insertItems | ( | const QStringList & | items | ) | `[protected]`

| Inserts `items` into the combo, honouring pixmapProvider() Does not update the completionObject. Note: duplicatesEnabled() is not honored here. Called from setHistoryItems() and setPixmapProvider() Definition at line 633 of file kcombobox.cpp. References QComboBox::insertItem(), QString::isEmpty(), KPixmapProvider::pixmapFor(), and KIcon::SizeSmall. Referenced by setHistoryItems(), and setPixmapProvider().

bool KHistoryCombo::useCompletion | ( |  | ) | const`[inline, protected]`

| Returns: if we can modify the completion object or not. Definition at line 731 of file kcombobox.h. References KCompletionBase::compObj(). Referenced by addToHistory(), clearHistory(), removeFromHistory(), and setHistoryItems().

The documentation for this class was generated from the following files:

- kcombobox.h
- kcombobox.cpp

This file is part of the documentation for kdelibs Version 3.1.5.
Documentation copyright © 1996-2002 the KDE developers.
Generated on Wed Jan 28 13:01:06 2004 by doxygen 1.3.4 written by Dimitri van Heesch, © 1997-2001