|
|
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.
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();
|
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. |
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.
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]
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 |
[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 |
[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]
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 |
[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:
type | the key-binding invoked. |
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.
Parameters:
itemID | the completion mode type |
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]
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 |
[protected virtual]
Initializes the variables upon construction.
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.
See QComboBox::keyPressEvent.
bool |
[protected virtual]
Re-implemented for internal reasons. API is not affected.
See QComboBox::mousePressEvent.