class KComboBox

An enhanced combo box. More...

Definition#include <kcombobox.h>
InheritsKCompletionBase (kdecore), QComboBox (qt)
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 enhances it with the following functionalities : a built-in KCompletion object which provides automatic & manual completion, the ability to change which keyboard key is used to activate this feature and rotation signals that can be used to iterate through some type of list. They key-bindings for the rotation feature are also configurable and can be interchanged between system and local settings easily. Moreover, since this widget inherits form QComboBox it can easily be used as a drop-in replacement where the above functionalities are needed and/or useful.

KComboBox emits a few more additional signals than QComboBox, the main ones being the comepltion and the rotation signal metioned above. 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 returnPressed signals are emitted when the user presses the return key.

By default, when you create a completion object through either completionObject() or setCompletionObject this widget will be automatically enabled to handle the signals. If you do not need this feature, simply use the appropriate accessor methods or the boolean paramters on the above function to shut them 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 in the list that matches the pressed key-codes. For example, if you have a list of countries, typing the first few letters of the name attempts to find a match and if one is found it will be selected as the current item.

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->setCompletionKey( Qt::End );
 // Shows the context (popup) menu
 combo->setEnableContextMenu();
 // Temporarly disable signal emition
 combo->disableSignals();
 // Default the key-bindings to system settings.
 combo->useGlobalSettings();

 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.

Reimplemented from QComboBox

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.

Reimplemented from QComboBox

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  rotateUp ()

[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 ()

[signal]

This signal is 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  iterateUpInList ()

[virtual slot]

Iterates in the up (previous match) direction through the completion list if it is available.

This slot is intended to make it easy to connect the rotate up signal in order to make the widget itself handle rotation events internally. Note that no action is taken if there is no completion object or the completion object does not contain a next match.

void  iterateDownInList ()

[virtual slot]

Iterates in the down (next match) direction through the completion list if it is available.

This slot is intended to make it easy to connect the rotate down signal in order to make the widget itself handle rotation events internally. Note that no action is taken if there is no completion object or the completion object does not contain a next match.

void  selectedItem ( int itemID )

[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.

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]

Deals with text changes in auto completion mode.

void  init ()

[protected virtual]

Initializes the variables upon construction.

void  rotateText ( const QString& )

[protected]

Rotates the text on rotation events.

Parameters:
stringthe text to replace the current one with.

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.

Reimplemented from QComboBox

bool  eventFilter ( QObject *, QEvent * )

[protected virtual]

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

See QComboBox::mousePressEvent.

Reimplemented from QComboBox