|
|
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.
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();
|
Constructs a read-only or rather select-only combo box with a parent object and a name.
Parameters:
parent | the parent object of this widget |
name | the name of this widget |
|
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:
rw | when true widget will be editable.
|
parent | the parent object of this widget. |
name | the name of this widget. |
~ |
[virtual]
Destructor.
int |
[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 |
[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:
autocomplete | flag to enable/disable automatic completion mode. |
Reimplemented from QComboBox
bool |
[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 |
[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:
showMenu | if true, show the context menu. |
showMode | if true, show the mode changer. |
bool |
[const]
Returns true when the context menu is enabled.
Returns: true if context menu is enabled.
bool |
[const]
Returns true if the combo-box is editable.
Returns: true if combo is editable.
void |
[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 |
[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 |
[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 |
[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 |
[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 |
[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 |
[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 |
[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 |
[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 |
[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 |
[protected virtual slot]
Deals with highlighting the seleted item when return is pressed in the list box (editable-mode only).
void |
[protected virtual slot]
Deals with text changes in auto completion mode.
void |
[protected virtual]
Initializes the variables upon construction.
void |
[protected]
Rotates the text on rotation events.
Parameters:
string | the text to replace the current one with. |
void |
[protected const virtual]
Implementation of KCompletionBase::connectSignals().
This function simply connects the signals to appropriate slots when they are handled internally.
Parameters:
handle | if true, handle completion & roation internally. |
Reimplemented from KCompletionBase
void |
[protected virtual]
Re-implemented for internal reasons. API is not affected.
Reimplemented from QComboBox
bool |
[protected virtual]
Re-implemented for internal reasons. API is not affected.
See QComboBox::mousePressEvent.
Reimplemented from QComboBox