class KComboBox

An enhanced combo box. More...

Definition#include <kcombobox.h>
InheritsKCompletionBase (kdecore), QComboBox
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

Public Methods

Public Slots

Signals

Protected Methods

Protected Slots


Detailed Description

A combined button, line-edit and a popup list widget.

This widget inherits from QComboBox and implements the following additional functionalities: a completion object that provides both automatic and manual text completion as well as text rotation features, configurable key-bindings to activate these features and a popup-menu item that can be used to allow the user to set text completion modes on the fly based on their preference.

To support these new features KComboBox also emits a few more additional signals as well. The main ones being the completion and rotation signals. The completion signal is intended to be connected to a slot that will assist the user in filling out the remaining text while the rotation signals, both rotateUp and rotateDown, are intended to be used to transverse through some kind of list in opposing directions. The previousMatch and nextMatch signals are used to iterate through all possible matches whenever there are more than one possible text completion matches. And the returnPressed signals are emitted when the user presses the return key.

This widget by default creates a completion object whenever you invoke the member function completionObject for the first time. You can also assign your own completion object through setCompletionObject function if you want to control the kind of completion object that needs to be used. Additionally, to make this widget more functional, KComboBox will automatically handle the iteration and completion signals internally when a completion object is created through either one of the previously defined methods. If you do not need this feature, simply use KCompletionBase::setHandleSignals or the boolean paramter when calling setCompletionObject, to turn it off.

The default key-binding for completion and rotation is determined from the global settings in KStdAccel. However, these values can be set locally to override these global settings. Simply invoking useGlobalSettings then allows you to immediately default the bindings back to the global settings again. You can also default the key-bindings by simply invoking the setXXXKey method without any argumet. Note that if this widget is not editable, i.e. it is constructed as a "select-only" widget, then only one completion mode, CompletionAuto, is allowed. All the other modes are simply ignored. The CompletionAuto mode in this case allows you to automatically select an item from the list that matches the key-code of the first key pressed.

Example:

To enable the basic completion feature :


 KComboBox *combo = new KComboBox( true, this, "mywidget" );
 KCompletion *comp = combo->completionObject();
 // Connect to the return pressed signal - optional
 connect(combo,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&));

To use a customized completion objects or your own completion object :


 KComboBox *combo = new KComboBox( this,"mywidget" );
 KURLCompletion *comp = new KURLCompletion();
 combo->setCompletionObject( comp );
 // Connect to the return pressed signal - optional
 connect(combo,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&));

Other miscelanous functions :


 // Tell the widget not to handle completion and rotation
 combo->setHandleSignals( false );
 // set your own completion key for manual completions.
 combo->setKeyBinding( KCompletionBase::TextCompletion, Qt::End );
 // Shows the context (popup) menu
 combo->setEnableContextMenu( false );
 // Temporarly disable signal emition
 combo->disableSignals();
 // Default the key-bindings to system settings.
 combo->useGlobalKeyBindings();

 KComboBox ( QWidget *parent=0, const char *name=0 )

Constructs a read-only or rather select-only combo box with a parent object and a name.

Parameters:
parentthe parent object of this widget
namethe name of this widget

 KComboBox ( bool rw, QWidget *parent=0, const char *name=0 )

Constructs a "read-write" or "read-only" combo box depending on the value of the first argument( bool rw ) with a parent, a name.

Parameters:
rwwhen true widget will be editable.
parentthe parent object of this widget.
namethe name of this widget.

KComboBox ()

[virtual]

Destructor.

int  cursorPosition ()

[const]

Returns the current cursor position.

This method always returns a -1 if the combo-box is NOT editable (read-write).

Returns: current cursor position.

void  setAutoCompletion ( bool autocomplete )

[virtual]

Re-implemented from QComboBox.

If true, the completion mode will be set to automatic. Otherwise, it is defaulted to the gloabl setting. This methods has been replaced by the more comprehensive setCompletionMode.

Parameters:
autocompleteflag to enable/disable automatic completion mode.

bool  autoCompletion ()

[const]

Re-implemented from QComboBox.

Returns true if the current completion mode is set to automatic. See its more comprehensive replacement completionMode.

Returns: true when completion mode is automatic.

void  setEnableContextMenu ( bool showMenu )

[virtual]

Enables or disables the popup (context) menu.

This method only works if this widget is editable, i.e. read-write and allows you to enable/disable the context menu. It does nothing if invoked for a none-editable combo-box. Note that by default the mode changer item is made visiable whenever the context menu is enabled. Use * hideModechanger() if you want to hide this item. Also by default, the context menu is created if this widget is editable. Call this function with the argument set to false to disable the popup menu.

Parameters:
showMenuif true, show the context menu.
showModeif true, show the mode changer.

bool  isContextMenuEnabled ()

[const]

Returns true when the context menu is enabled.

Returns: true if context menu is enabled.

bool  isEditable ()

[const]

Returns true if the combo-box is editable.

Returns: true if combo is editable.

void  returnPressed ()

[signal]

This signal is emitted when the user presses the return key. Note that this signal is only emitted if this widget is editable.

void  returnPressed ( const QString& )

[signal]

This signal is emitted when the user presses the return key. The argument is the current text being edited. This signal is just like returnPressed() except it contains the current text as its argument.

Note that this signal is only emitted if this widget is editable.

void  completion ( const QString& )

[signal]

This signal is emitted when the completion key is pressed. The argument is the current text being edited.

Note that this signal is NOT available if this widget is non-editable or the completion mode is set to KGlobalSettings::CompletionNone.

void  previousMatch ( KeyBindingType )

[signal]

Signal emitted when the key-binding set for the next text match is pressed.

This signal is emitted when the key-binding used for iterating through all possible matches is invoked. It is usually used in the manual completion modes to iterate through the multiple matches

Note that this signal is NOT emitted if the completion mode is set to CompletionNone or EchoMode is NOT normal.

void  nextMatch ( KeyBindingType )

[signal]

Signal emitted when the key-binding set for the previous text match is pressed.

See KCompletionBase::setKeyBinding.

Note that this signal is NOT emitted if the completion mode is set to CompletionNone or EchoMode is NOT normal.

void  rotateUp ( KeyBindingType )

[signal]

This signal is emitted when the rotate up key is pressed.

Note that this signal is NOT available if this widget is non-editable or the completion mode is set to KGlobalSettings::CompletionNone.

void  rotateDown ( KeyBindingType )

[signal]

Signal emitted when the rotate down key is pressed.

Note that this signal is NOT available if this widget is non-editable or the completion mode is set to KGlobalSettings::CompletionNone.

void  rotateText ( KeyBindingType )

[slot]

Iterates through all possible matches of the completed text or the history list.

Depending on the argument this function either iterates through the history list of this widget or the all possible matches in whenever multiple matches result from a text completion request. This function will have no effect if the previous completion resulted in a single match.

Parameters:
typethe key-binding invoked.

void  selectedItem ( int )

[protected virtual slot]

changes the completion mode.

This slot sets the completion mode to the one requested by the end user through the popup menu.

Parameters:
itemIDthe completion mode type

void  showCompletionMenu ()

[protected virtual slot]

Populates the sub menu before it is displayed.

All the items are inserted by the completion base class. See @KCompletionBase::insertCompletionItems. The items then invoke the slot giiven by the

void  aboutToShowMenu ()

[protected virtual slot]

Inserts the completion menu item as needed.

Since this widget comes with its own pop-up menu this slot is needed to invoke the method need to insert the completion menu. This method, KCompletionBase::insetCompeltionMenu, is defined by the KCompletionBase.

void  itemSelected ( QListBoxItem* )

[protected virtual slot]

Deals with highlighting the seleted item when return is pressed in the list box (editable-mode only).

void  makeCompletion ( const QString& )

[protected virtual slot]

Completes text according to the completion mode.

Note: this method is not invoked if the completion mode is set to CompletionNone. Also if the mode is set to CompletionShell and multiple matches are found, this method will complete the text to the first match with a beep to inidicate that there are more matches. Then any successive completion key event iterates through the remaining matches. This way the rotation functionality is left to iterate through the list as usual.

void  init ()

[protected virtual]

Initializes the variables upon construction.

void  connectSignals ( bool handle )

[protected const virtual]

Implementation of KCompletionBase::connectSignals().

This function simply connects the signals to appropriate slots when they are handled internally.

Parameters:
handleif true, handle completion & roation internally.

Reimplemented from KCompletionBase

void  keyPressEvent ( QKeyEvent* )

[protected virtual]

Re-implemented for internal reasons. API is not affected.

See QComboBox::keyPressEvent.

bool  eventFilter ( QObject *, QEvent * )

[protected virtual]

Re-implemented for internal reasons. API is not affected.

See QComboBox::mousePressEvent.