class KComboBox

An enhanced combo box. More...

Definition#include <kcombobox.h>
InheritsQComboBox (qk)
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 added functionalities : a built-in hook into a KCompletion object which provides automatic & manual completion as well as the ability to change which keyboard key is used for this feature. Furthermore, since it inherits form QComboBox it can 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. 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.

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 the global settings. Simply invoking @see 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.

A small example:

To enable the basic completion feature :


 KComboBox *combo = new KComboBox( true, this, "mywidget" );
 combo->setHandleCompletion(); // enables completion and automatically deletes that object at the end.
 combo->setHandleRotation();
 // Connect to the return pressed signal - optional
 connect( combo, SIGNAL( returnPressed( const QString& ) ), combo->completionObject(), SLOT( addItem( const QString& ) );

To use a customized completion objects derived from KCompletion simply use setCompletionObject to create the completion object instead :


 KComboBox *combo = new KComboBox( this,"mywidget" );
 KURLCompletion *comp = new KURLCompletion();
 combo->setCompletionObject( comp );
 combo->setHandleCompletion();
 combo->setHandleRotation();

Of course setCompletionObject can also be used to assign the base KCompletion class as the comepltion object. This is specailly important when you share a single completion object across multiple widgets.

See setCompletionObject and enableCompletion for detailed information.

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

Constructs a combo box widget with a parent object and a name.

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

Constructs a combo box widget in "select-only" or "read-write" mode with a parent, a name and a context menu.

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

@param autocomplete flag to enable/disable automatic completion mode.

bool autoCompletion ()
[const]

Re-implemented from QComboBox.

Returns true if the current completion mode is set to automatic.

Returns: true when completion mode is automatic.

void setCompletionObject ( KCompletion*, bool autoDelete = false )

Sets the KCompletion object this widget will use.

This method allows you to enable the completion feature by supplying your own KCompletion object. It provides you with control over how the completion object object will be handled by this widget as well.

The object assigned through this method, by default, is not deleted when this widget is destroyed. If you want KComboBox to handle the deletion, make sure you set the flag in the parameter below to true. This is done to allow you to share a single completion object across multiple widgets.

Parameters:
aKCompletion or a derived child object. @param autoDelete if true, delete the completion object on destruction.

KCompletion* completionObject ()
[const]

Returns a pointer to the current completion object.

Returns: a pointer the completion object.

bool deleteCompletion ()
[const]

Returns true if the completion object is deleted upon this widget's destruction.

See setCompeltionObject and enableCompletion for details.

Returns: true if the completion object

void setDeleteCompletion ( bool autoDelete = false )

Sets the completion object for deletion upon this widget's destruction.

If the argument is set to true, the completion object is deleted when this widget's destructor is called.

@param autoDelete if set to true the completion object is deleted on exit.

void setEnableCompletion ( bool autoDelete = true )

Enables or disables basic completion feature for this widget.

This is a convienence method that can automatically create a completion object for you and activate. The completion object is an instance of the base class KCompletion.

If you need to make use of a more specialized completion object, use setCompletionObject. Also unlike setCompletionObject the completion object created by this method will be automatically deleted when the widget is destroyed. To avoid this set the boolean paramter below to false.

@param autoDelete if true, delete the completion object on destruction.

void setEnableCompletionSignal ( bool enable )

Enables/disables this widget's ability to emit completion signals.

Note that if you invoke this function with the argument set to false, no completion signals will be emitted. Thus, this widget will not be able to handle the completion signals even if setHandleCompletion has been or is called. Also note that disabling the emition of the completion signals through this method does NOT delete the comlpetion object if one has already been created. See also setHandleCompletion and setHandleCompletion.

@param emit if true emits completion signal.

void setEnableRotationSignal ( bool enable )

Enables/disables this widget's ability to emit rotation signals.

Note that if you invoke this function with the argument se to false, no rotation signals will be emitted. Thus, this widget will not be able to handle the rotation signals even if setHandleRotation has been or is called. See also @see setHandleRotation.

void setHandleCompletion ( bool complete = true )

Sets this widget to handle the completion signals internally.

When this function is invoked with the default argument or the argument set to "true", KComboBox will automatically handle completion signals. By default, this method enables completion and also creates a base completion object if one is not already present. To stop this widget from handling the completion signal internally simply call it with its argument set to "false".

Note that calling this function does not hinder you from connecting and hence receiving the completion signals externally.

@param complete when true enables this widget to handle completion.

void setHandleRotation ( bool rotate = true )

Sets this widget to handle rotation signals internally.

When this function is invoked with a default argument or the argument set to "true", KComboBox will automatically handle rotation signals. To stop KComboBox from handling the rotation signals internally simply invoke this function with the argument set to "false".

Note that calling this function does not hinder you from connecting and hence receiving the rotation signals externally.

@param autoHandle when true handle rotation signals internally.

bool handlesCompletion ()

Returns true if this widget handles completion signal internally.

Returns: true when this widget handles completion signal.

bool handlesRotation ()

Returns true if this widget handles rotation signal internally.

Returns: true when this widget handles rotation signal.

void setCompletionMode ( KGlobal::Completion mode )
[virtual]

Sets the type of completion to be used.

The completion modes supported are those defined in KGlobal. These completion types are CompletionNone, CompletionAuto, CompletionMan, and CompletionShell.

NOTE: if this widget is not editable i.e. it is constructed as a "select-only" widget, then only two completion modes are allowed: CompletionAuto and ComepltionNone. 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.

Parameters:
modeCompletion type:

KGlobal::Completion completionMode ()
[const]

Retrieves the current completion mode.

The return values are of type KGlobal::Completion. See setCompletionMode for details.

Note that only two completion modes are supported if this widget is not editable : CompletionNone and CompletionAuto.

Returns: the completion mode.

bool setRotateDownKey ( int rDnKey = 0 )

Set the key-binding to be used for rotating through a list to find the next match.

When this key is activated by the user a rotateDown signal will be emitted. If no value is supplied for rDnkey or it is set to 0, then the completion key will be defaulted to the global setting. This method returns false if rDnkey is negative or the supplied key-binding conflicts with either completion or rotateUp keys.

@param rDnkey the key-binding to use for rotating up in a list.

Returns: true if key-binding can successfully be set.

bool setRotateUpKey ( int rUpKey = 0 )

Sets the key-binding to be used for rotating through a list to find the previous match.

When this key is activated by the user a rotateUp signal will be emitted. If no value is supplied for rUpkey or it is set to 0, then the completion key will be defaulted to the global setting. This method returns false if rUpkey is negative or the supplied key-binding conflicts with either completion or rotateDown keys.

@param rUpkey the key-binding to use for rotating down in a list.

Returns: true if key-binding can successfully be set.

bool setCompletionKey ( int ckey = 0 )

Sets the key-binding to be used for the two manual completion types: CompletionMan and CompletionShell.

This function expects the value of the modifier key(s) (Shift, Ctrl, Alt), if present, to be @bf summed up with actual key, ex: Qt::CTRL+Qt::Key_E. If no value is supplied for ckey or it is set to 0, then the completion key will be defaulted to the global setting. This function returns true if the supplied key-binding can be successfully assigned.

NOTE: if ckey is negative or the key-binding conflicts with either completion or rotateDown keys, this function will return false. Also note that this method always returns false if the widget is not editable.

@param ckey Key binding to use for completion. Default is 0.

Returns: true if key-binding can be successfully set.

int completionKey ()
[const]

Returns the key-binding used for completion.

If the key binding contains modifier key(s), the @bf sum of the key and the modifier will be returned. See also @see setCompletionKey. Note that this method is only useful when this widget is editable. Otherwise this method has no meaning.

Returns: the key-binding used for rotating through a list.

int rotateUpKey ()
[const]

Returns the key-binding used for rotating up in a list.

This methods returns the key used to iterate through a list in the "UP" direction. This is opposite to what the rotateDown key does.

If the key binding contains modifier key(s), the SUM of their values is returned. See also setRotateUpKey.

Returns: the key-binding used for rotating up in a list.

int rotateDownKey ()
[const]

Returns the key-binding used for rotating down in a list.

This methods returns the key used to iterate through a list in the "DOWN" direction. This is opposite to what the rotateDown key does.

If the key binding contains modifier key(s), the SUM of their values is returned. See also setRotateDownKey.

Returns: the key-binding used for rotating down in a list.

void useGlobalSettings ()

Sets this widget to use global values for key-bindings.

This method forces this widget to check the global key- bindings for the completion and rotation features each time it processes a key event. Thus, allowing this widget to immediately reflect any changes made to the global settings.

By default this widget uses the global key-bindings. There is no need to call this method unless you have locally modified the key bindings and want to revert back.

void setEnableContextMenu ( bool showMenu = false )

Enables/disables the popup (context) menu for this widget.

This method only works if this widget is editable ( i.e. read-write ). If this widget is not editable, invoking this function accomplishs nothing. Hence, the return value will always be false under those circumstances.

@param showChanger if set to true, the mode changer item is enabled.

void setEnableModeChanger ( bool showMode = false )

Shows the completion mode changer in the context menu.

This function allows to enable/disable the apperance of the mode changer item from the context menu. Note that there is no need to call this function unless you have disabled the mode changer. It is automatically enabled by default.

NOTE : this function is meaningless if this widget is "select-only".

@param showChanger if set to true, the mode changer item is enabled.

void returnPressed ()
[signal]

This signal is emitted when the user presses the return key. It is emitted if and only if the widget is editable (read-write).

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, just like returnPressed(), 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 KGlobal::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 KGlobal::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 KGlobal::CompletionNone.

void multipleCompletions ( const QStringList& )
[virtual slot]

TODO : NOT YET IMPLEMENTED :))

void setEditText ( const QString& )
[virtual slot]

This slot is a re-implemention of @see QComboBox::setEditText. It is re-implemeted to provide a consitent look when items are completed as well as selected from the list box. The argument is the text to set in the line edit box.

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.