|
|
An enhanced QLineEdit widget for inputting text.
This widget has the same behaviour as QLineEdit with the following added functionalities : a popup menu that provides basic features such as copy/cut/paste to manipulate content through the mouse, a built-in hook into KCompletion which provides automatic & manual completion as well as iteration through a given list, and the ability to change which keyboard keys to use for these features. Since this widget inherits form QLineEdit, it can be used as a drop-in replacement where the above extra functionalities are needed and/or useful.
KLineEdit emits a few more additional signals than QLineEdit: completion, rotateUp and rotateDown and @returnPressed. The completion signal can be connected to a slot that will assist the user in filling out the remaining text. The two rotation signals are intended to be used to iterate through a list of predefined text entries.
The default key-bindings for completion and rotation are determined from the global settings in KStdAccel. However, these values can be set locally overriding the global settings. Simply invoking @see useGlobalSettings allows you to immediately default the bindings back to the global settings again. Also if you are interested in only defaulting the key-bindings individually for each action, simply call the setXXXKey methods without any argumet. For example, after locally customizing the key-binding that invokes manual completion, simply invoking @see setCompletionKey(), without any argument, will result in the completion key being set to 0. This will then force the key-event filter to use the global value.
To enable the basic completion & rotation features :
KLineEdit* myEdit = new KLineEdit( this,"mywidget" ); myEdit->setHandleCompletion(); myEdit->setHandleRotation(); // Insert the enteries on RETURN pressed into the completion object's list connect( edit, SIGNAL( returnPressed(const QString& ) ), edit->completionObject(), SLOT( addItem( const QString& ) ) );
To use a customized completion object such as KURLCompletion use setCompletionObject(...) instead :
KLineEdit* myEdit = new KLineEdit( this,"mywidget" ); KURLCompletion *comp = new KURLCompletion(); myEdit->setCompletionObject( comp, false ); // KLineEdit will delete the completion object. myEdit->setHandleCompletion(); myEdit->setHandleRotation(); // Insert the enteries on RETURN pressed into the completion object's list connect( edit, SIGNAL( returnPressed( const QString& ) ), edit->completionObject(), SLOT( addItem( const QString& ) ) );
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.
KLineEdit ( const QString &string, QWidget *parent, const char *name = 0 ) |
Constructs a KLineEdit object with a default text, a parent, a name and a context menu.
@param string
text to be shown in the edit widget
@param parent
the parent object of this widget
@param name
the name of this widget
KLineEdit ( QWidget *parent=0, const char *name=0 ) |
Constructs a KLineEdit object with a parent, a name and a a context menu.
@param string
text to be shown in the edit widget
@param parent
the parent object of this widget
@param name
the name of this widget
~KLineEdit () |
Destructor.
void cursorAtEnd () |
Puts cursor at the end of the string.
This method is deprecated. Use @see QLineEdit::end instead.
void setCompletionObject ( KCompletion*, bool autoDelete = false ) |
Sets the KCompletion object this widget will use.
This function allows you to enable the completion feature by supplying your own KCompletion object. It also enables you to control how this completion object will be handled by this widget (see below).
The completion object assigned using method is by default NOT deleted when this widget is destroyed. If you want KLineEdit to delete this object in its destructor, be sure to set the boolean parameter, autoDelete, to "true". This is especially usefully if you want to share the same completion object across mulitple widgets. You can also use the member functions setDeleteCompletionOnExit and deleteCompletionOnExit to change the status of whether the completion object gets deleted in KLineEdit's destructor. You can also reset this widget's reference to a completion object by either deleting the object manually yourself or calling this function with the first argument set to null - setCompletionObject( 0 ). Be aware however that doing so will stop this widget from handling completion and rotation signals internally even if you have explicitly called the setHandleXXXX methods.
Parameters:
a | KCompletion or a derived child object.
@param autoDelete if true, the completion object is deleted in the destructor.
|
bool deleteCompletion () |
Returns true if the completion object is deleted upon this widget's destruction.
See setCompeltionObject, setHandleCompletion, deleteCompletionOnExit and setDeleteCompletionOnExit for more details.
Returns: true if the completion object is deleted
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.
KCompletion* completionObject () |
Returns a pointer to the current completion object.
Returns: the completion object or null if one does not exist.
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", KLineEdit 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", KLineEdit will automatically handle rotation signals. To stop KLineEdit 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 ) |
Set 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.
Please note that if the EchoMode for this widget is set to something other than QLineEdit::Normal, this method refuses to accept the new completion mode. This is done purposefully to protect against protected entries such as passwords being cached in KCompletion's list. Hence, if the EchoMode is not QLineEdit::Normal, the completion mode is automatically "soft" (the completion object is not deleted) disabled.
Parameters:
mode | Completion type: |
KGlobal::Completion completionMode () |
Retrieve the current completion mode.
The return values are of type KGlobal::Completion. See setCompletionMode for details.
Returns: the completion mode.
bool setCompletionKey ( int ckey = 0 ) |
Set 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.
@param ckey
Key binding to use for completion. Default is 0.
Returns: true
if key-binding can be successfully set.
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.
int completionKey () |
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.
Returns: the key-binding used for rotating through a list.
int rotateUpKey () |
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 () |
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.
This method also allows you to enable/disable the context menu. If this method is invoked without an argument, the context menu will be disabled.
@param showMenu
if true, shows the context menu.
void setEnableModeChanger ( bool showChanger = false ) |
Enables/disables the completion mode changer item in the context menu.
This function allows you to enable or disable the completion mode changer as needed without having to disable the popup menu. If enabled the user can change the comepltion mode on the fly.
@param showChanger
if set to true, the mode changer item is enabled.
bool isContextMenuEnabled () |
Returns true when the context menu is enabled.
Returns: true
if context menu is enabled.
bool isModeChangerEnabled () |
Returns true if the mode changer item is visible in the context menu.
Returns: true
if the mode changer is visible in context menu.
void returnPressed ( const QString& ) |
This signal is emitted when the user presses the return key. The argument is the current text. Note that this signal is NOT emitted if the widget's EchoMode is set to QLineEdit::Password.
void completion ( const QString& ) |
Signal emitted when the completion key is pressed.
Please note that this signal is NOT emitted if the completion mode is set to CompletionNone or EchoMode is NOT normal.
void rotateUp () |
Signal emitted when the rotate up key is pressed.
Please note that this signal is NOT emitted if the completion mode is set to CompletionNone or EchoMode is NOT normal.
void rotateDown () |
Signal emitted when the rotate down key is pressed.
Please note that this signal is NOT emitted if the completion mode is set to CompletionNone or EchoMode is NOT normal.
void slotCopy () |
Copies the marked text to the clipboard, if there is any, and if echoMode() is Normal. See also QLineEdit::copy.
void slotCut () |
Copies the marked text to the clipboard and deletes it if there is any. See also QLineEdit::cut.
void slotPaste () |
Inserts the text in the clipboard at the current cursor position, deleting any previously marked text. See also QLineEdit::paste.
void modeNone () |
Sets the comepltion mode to KGlobal::CompletionNone
void modeManual () |
Sets the comepltion mode to KGlobal::CompletionManual
void modeAuto () |
Sets the comepltion mode to KGlobal::CompletionAuto
void modeShell () |
Sets the comepltion mode to KGlobal::CompletionShell
void aboutToShowMenu () |
Populates the context menu before it is displayed.
void aboutToShowSubMenu ( int ) |
Populates the sub menu before it is displayed.
void entryChanged ( const QString& ) |
Deals with text changes and auto completion in this widget.
void makeCompletion ( const QString& ) |
Fills in the remaining text.
void initialize () |
Initializes variables. Called from the constructors.