# class KHistoryComboBox

###

Module | kdeui
Namespace |
Class | KHistoryComboBox
Inherits | KComboBox

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.

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

Author Carsten Pfeiffer <pfeiffer@kde.org>

### methods

- KHistoryComboBox (parent)

  returns ctor
  KDE 4.1.0 and later only

  Argument | Type | Default
  --- | --- | ---
  parent | QWidget | 0

  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 NoInsert, 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.

- KHistoryComboBox (useCompletion, parent)

  returns ctor
  KDE 4.1.0 and later only

  Argument | Type | Default
  --- | --- | ---
  useCompletion | bool |
  parent | QWidget | 0

  Same as the previous constructor, but additionally has the option to specify whether you want to let KHistoryComboBox handle completion or not. If set to true, KHistoryComboBox will sync the completion to the contents of the combobox.

- KHistoryComboBox (a0)

  returns ctor
  Not implemented

  Argument | Type | Default
  --- | --- | ---
  a0 | KHistoryComboBox |

- KHistoryComboBox (a0)

  returns ctor
  before KDE 4.1.0 only

  Argument | Type | Default
  --- | --- | ---
  a0 | QWidget | 0

- KHistoryComboBox (a0, a1)

  returns ctor
  before KDE 4.1.0 only

  Argument | Type | Default
  --- | --- | ---
  a0 | bool |
  a1 | QWidget | 0

- addToHistory (item)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  item | QString |

  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

  See also QComboBox.setDuplicatesEnabled

- clearHistory ( )

  returns Nothing

  Clears the history and the completion list.

- cleared ( )

  returns Nothing
  SIGNAL ("cleared ()")

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

- historyItems ( )

  returns QStringList

  Returns the list of history items. Empty, when this is not a read-write combobox.

  See also setHistoryItems

- insertItems (items)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  items | QStringList |

  Inserts items into the combo, honoring pixmapProvider() Does not update the completionObject.

  Note: duplicatesEnabled() is not honored here.

  Called from setHistoryItems() and setPixmapProvider()

- keyPressEvent (a0)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  a0 | QKeyEvent |

  Handling key-events, the shortcuts to rotate the items.

- pixmapProvider ( )

  returns KPixmapProvider

  Returns the current pixmap provider.

  See also setPixmapProvider

  See also KPixmapProvider

- removeFromHistory (item)

  returns bool

  Argument | Type | Default
  --- | --- | ---
  item | QString |

  Removes all items named item.

  Returns true if at least one item was removed.

  See also addToHistory

- reset ( )

  returns Nothing

  Resets the current position of the up/down history. Call this when you manually call setCurrentItem() or clearEdit().

- setHistoryItems (items)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  items | QStringList |

  Inserts items into the combobox. items might get truncated if it is longer than maxCount()

  See also historyItems

- setHistoryItems (items, setCompletionList)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  items | QStringList |
  setCompletionList | bool |

  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 KHistoryComboBox 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

      KConfigGroup config(KGlobal.config(), "somegroup");

      // load the history and completion list after creating the history combo
      QStringList list;
      list = config.readEntry("Completion list", QStringList());
      combo->completionObject()->setItems(list);
      list = config.readEntry("History list", QStringList());
      combo->setHistoryItems(list);

      [...]

      // save the history and completion list when the history combo is
      // destroyed
      QStringList list;
      KConfigGroup config(KGlobal.config(), "somegroup");
      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 KHistoryComboBox.

  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

  See also KComboBox.completionObject

  See also KCompletion.setItems

  See also KCompletion.items

- setPixmapProvider (prov)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  prov | KPixmapProvider |

  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 KHistoryComboBoxBox. Implement it to return your own custom pixmaps, or use the KUrlPixmapProvider from libkio, which uses KMimeType.pixmapForUrl to resolve icons.

  Set prov to 0 if you want to disable pixmaps. Default no pixmaps.

  See also pixmapProvider

- useCompletion ( )

  returns bool

  Returns if we can modify the completion object or not.

- wheelEvent (ev)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  ev | QWheelEvent |

  Handling wheel-events, to rotate the items.