KDE 4.7 PyKDE API Reference

- KDE's Python API

# KCompletionBox Class Reference

`from PyKDE4.kdeui import *`

Inherits: KListWidget → QListWidget → QListView → QAbstractItemView → QAbstractScrollArea → QFrame → QWidget → QObject

## Detailed Description

A helper widget for "completion-widgets" (KLineEdit, KComboBox))

A little utility class for "completion-widgets", like KLineEdit or 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>

## Signals
| activated (QString a0)
| userCancelled (QString a0)
## Methods
| __init__ (self, QWidget parent=0)
bool | activateOnSelect (self)
QRect | calculateGeometry (self)
QString | cancelledText (self)
| down (self)
| end (self)
bool | eventFilter (self, QObject a0, QEvent a1)
QPoint | globalPositionHint (self)
| home (self)
| insertItems (self, QStringList items, int index=-1)
bool | isTabHandling (self)
QStringList | items (self)
| pageDown (self)
| pageUp (self)
| popup (self)
| setActivateOnSelect (self, bool state)
| setCancelledText (self, QString txt)
| setItems (self, QStringList items)
| setTabHandling (self, bool enable)
| setVisible (self, bool visible)
| sizeAndPosition (self)
QSize | sizeHint (self)
| slotActivated (self, QListWidgetItem a0)
| up (self)

## Signal Documentation

activated | ( | QString | a0
| ) |  |  |

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

Signal syntax:
  `QObject.connect(source, SIGNAL("activated(const QString&)"), target_slot)`

userCancelled | ( | QString | a0
| ) |  |  |

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

Signal syntax:
  `QObject.connect(source, SIGNAL("userCancelled(const QString&)"), target_slot)`

## Method Documentation

__init__ | ( | self, |
|  | QWidget | parent=0
| ) |  |  |

Constructs a KCompletionBox.

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

bool activateOnSelect | ( |  | self ) |

Returns:
  true if selecting an item results in the emition of the selected() signal.

QRect calculateGeometry | ( |  | self ) |

This calculates the size of the dropdown and the relative position of the top left corner with respect to the parent widget. This matches the geometry and position normally used by K/QComboBox when used with one.

QString cancelledText | ( |  | self ) |

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

down | ( |  | self ) |

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

end | ( |  | self ) |

Moves the selection down to the last item.

bool eventFilter | ( | self, |
|  | QObject | a0,
|  | QEvent | a1
| ) |  |  |

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

QPoint globalPositionHint | ( |  | self ) |

The preferred global coordinate at which the completion box's top left corner should be positioned.

home | ( |  | self ) |

Moves the selection up to the first item.

insertItems | ( | self, |
|  | QStringList | items,
|  | int | index=-1
| ) |  |  |

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)

bool isTabHandling | ( |  | self ) |

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

Default is true.

See also:
  setTabHandling

QStringList items | ( |  | self ) |

Returns a list of all items currently in the box.

pageDown | ( |  | self ) |

Moves the selection one page down.

pageUp | ( |  | self ) |

Moves the selection one page up.

popup | ( |  | self ) |

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.

setActivateOnSelect | ( | self, |
|  | bool | state
| ) |  |  |

Set whether or not the selected signal should be emitted when an item is selected. By default the selected() signal is emitted.

Parameters:

  | state | false if the signal should not be emitted.

setCancelledText | ( | self, |
|  | QString | txt
| ) |  |  |

Sets the text to be emitted if the user chooses not to pick from the available matches.

If the canceled 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

setItems | ( | self, |
|  | QStringList | items
| ) |  |  |

Clears the box and inserts items.

setTabHandling | ( | self, |
|  | bool | enable
| ) |  |  |

Makes this widget (when visible) capture Tab-key events to traverse the items in the dropdown list (Tab goes down, Shift+Tab goes up).

On by default, but should be turned off when used in combination with KUrlCompletion. When off, KLineEdit handles Tab itself, making it select the current item from the completion box, which is particularly useful when using KUrlCompletion.

See also:
  isTabHandling

setVisible | ( | self, |
|  | bool | visible
| ) |  |  |

Re-implemented for internal reasons. API is unaffected. Call it only if you really need it (i.e. the widget was hidden before) to have better performance.

sizeAndPosition | ( |  | self ) |

This properly sizes and positions the listbox.

QSize sizeHint | ( |  | self ) |

slotActivated | ( | self, |
|  | QListWidgetItem | a0
| ) |  |  |

Called when an item was activated. Emits activated() with the item.

up | ( |  | self ) |

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