kdeui Library API Documentation

KLineEdit Class Reference

An enhanced QLineEdit widget for inputting text. More...

#include <klineedit.h>

Inheritance diagram for KLineEdit:

QLineEdit KCompletionBase KIconViewSearchLine KListViewLineEdit KListViewSearchLine KRestrictedLine List of all members.

Public Slots

virtual void setReadOnly (bool)
void rotateText (KCompletionBase::KeyBindingType type)
virtual void setCompletedText (const QString &)
void setCompletedItems (const QStringList &items)
void setCompletedItems (const QStringList &items, bool autoSuggest)
virtual void clear ()
void setSqueezedText (const QString &text)
virtual void setText (const QString &)

Signals

void completionBoxActivated (const QString &)
void returnPressed (const QString &)
void completion (const QString &)
void substringCompletion (const QString &)
void textRotation (KCompletionBase::KeyBindingType)
void completionModeChanged (KGlobalSettings::Completion)
void aboutToShowContextMenu (QPopupMenu *p)

Public Member Functions

 KLineEdit (const QString &string, QWidget *parent, const char *name=0)
 KLineEdit (QWidget *parent=0, const char *name=0)
virtual ~KLineEdit ()
void setURL (const KURL &url)
void cursorAtEnd ()
virtual void setCompletionMode (KGlobalSettings::Completion mode)
virtual void setContextMenuEnabled (bool showMenu)
bool isContextMenuEnabled () const
void setURLDropsEnabled (bool enable)
bool isURLDropsEnabled () const
void setTrapReturnKey (bool trap)
bool trapReturnKey () const
virtual bool eventFilter (QObject *, QEvent *)
KCompletionBoxcompletionBox (bool create=true)
virtual void setCompletionObject (KCompletion *, bool hsig=true)
virtual void copy () const
void setEnableSqueezedText (bool enable)
bool isSqueezedTextEnabled () const
QString originalText () const
void setCompletionBox (KCompletionBox *box)

Protected Slots

virtual void makeCompletion (const QString &)
void slotAboutToShow ()
void slotCancelled ()
void userCancelled (const QString &cancelText)

Protected Member Functions

virtual void resizeEvent (QResizeEvent *)
virtual void keyPressEvent (QKeyEvent *)
virtual void mousePressEvent (QMouseEvent *)
virtual void mouseDoubleClickEvent (QMouseEvent *)
virtual void contextMenuEvent (QContextMenuEvent *)
virtual QPopupMenucreatePopupMenu ()
virtual void dropEvent (QDropEvent *)
virtual void setCompletedText (const QString &, bool)
void setUserSelection (bool userSelection)
virtual void create (WId=0, bool initializeWindow=true, bool destroyOldWindow=true)
virtual void focusInEvent (QFocusEvent *)
bool autoSuggest () const
virtual void virtual_hook (int id, void *data)

Properties

bool contextMenuEnabled
bool urlDropsEnabled
bool trapEnterKeyEvent
bool enableSqueezedText

Friends

class KComboBox

Detailed Description

An enhanced QLineEdit widget for inputting text.

Detail

This widget inherits from QLineEdit and implements the following additional functionalities: a completion object that provides both automatic and manual text completion as well as multiple match iteration 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 KLineEdit also emits a few more additional signals. These are: completion( const QString& ), textRotation( KeyBindingType ), and returnPressed( const QString& ). The completion signal can be connected to a slot that will assist the user in filling out the remaining text. The text rotation signal is intended to be used to iterate through the list of all possible matches whenever there is more than one match for the entered text. The returnPressed( const QString& ) signals are the same as QLineEdit's except it provides the current text in the widget as its argument whenever appropriate.

This widget by default creates a completion object when you invoke the completionObject( bool ) member function for the first time or use setCompletionObject( KCompletion*, bool ) to assign your own completion object. Additionally, to make this widget more functional, KLineEdit will by default handle the text rotation and completion events internally when a completion object is created through either one of the methods mentioned above. If you do not need this functionality, simply use KCompletionBase::setHandleSignals( bool ) or set the boolean parameter in the above functions to false.

The default key-bindings for completion and rotation is determined from the global settings in KStdAccel. These values, however, can be overridden locally by invoking KCompletionBase::setKeyBinding(). The values can easily be reverted back to the default setting, by simply calling useGlobalSettings(). An alternate method would be to default individual key-bindings by using setKeyBinding() with the default second argument.

If EchoMode for this widget is set to something other than QLineEdit::Normal, the completion mode will always be defaulted to KGlobalSettings::CompletionNone. This is done purposefully to guard 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 disabled.

A read-only KLineEdit will have the same background color as a disabled KLineEdit, but its foreground color will be the one used for the read-write mode. This differs from QLineEdit's implementation and is done to give visual distinction between the three different modes: disabled, read-only, and read-write.

Usage

To enable the basic completion feature :

 KLineEdit *edit = new KLineEdit( this, "mywidget" );
 KCompletion *comp = edit->completionObject();
 // Connect to the return pressed signal - optional
 connect(edit,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&)));

To use a customized completion objects or your own completion object :

 KLineEdit *edit = new KLineEdit( this,"mywidget" );
 KURLCompletion *comp = new KURLCompletion();
 edit->setCompletionObject( comp );
 // Connect to the return pressed signal - optional
 connect(edit,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&)));

Note if you specify your own completion object you have to either delete it when you don't need it anymore, or you can tell KLineEdit to delete it for you:

 edit->setAutoDeleteCompletionObject( true );

Miscellaneous function calls :

 // Tell the widget to not handle completion and iteration automatically.
 edit->setHandleSignals( false );

 // Set your own key-bindings for a text completion mode.
 edit->setKeyBinding( KCompletionBase::TextCompletion, Qt::End );

 // Hide the context (popup) menu
 edit->setContextMenuEnabled( false );

 // Temporarily disable signal (both completion & iteration) emitions
 edit->disableSignals();

 // Default the key-bindings back to the default system settings.
 edit->useGlobalKeyBindings();

Author:
Dawit Alemayehu <adawit@kde.org>

Definition at line 145 of file klineedit.h.


Constructor & Destructor Documentation

KLineEdit::KLineEdit const QString string,
QWidget parent,
const char *  name = 0
 

Constructs a KLineEdit object with a default text, a parent, and a name.

Parameters:
string Text to be shown in the edit widget.
parent The parent object of this widget.
name the name of this widget

Definition at line 102 of file klineedit.cpp.

KLineEdit::KLineEdit QWidget parent = 0,
const char *  name = 0
 

Constructs a KLineEdit object with a parent and a name.

Parameters:
parent The parent object of this widget.
name The name of this widget.

Definition at line 108 of file klineedit.cpp.

KLineEdit::~KLineEdit  )  [virtual]
 

Destructor.

Definition at line 114 of file klineedit.cpp.


Member Function Documentation

void KLineEdit::setURL const KURL url  ) 
 

Sets url into the lineedit.

It uses KURL::prettyURL() so that the url is properly decoded for displaying.

Definition at line 1036 of file klineedit.cpp.

References KURL::prettyURL(), and setText().

void KLineEdit::cursorAtEnd  )  [inline]
 

Puts the text cursor at the end of the string.

This method is deprecated. Use QLineEdit::end() instead.

Deprecated:
QLineEdit::end()

Definition at line 195 of file klineedit.h.

void KLineEdit::setCompletionMode KGlobalSettings::Completion  mode  )  [virtual]
 

Re-implemented from KCompletionBase for internal reasons.

This function is re-implemented in order to make sure that the EchoMode is acceptable before we set the completion mode.

See KCompletionBase::setCompletionMode

Reimplemented from KCompletionBase.

Definition at line 144 of file klineedit.cpp.

References KCompletionBase::completionMode(), and KCompletionBase::setCompletionMode().

virtual void KLineEdit::setContextMenuEnabled bool  showMenu  )  [inline, virtual]
 

Enables/disables the popup (context) menu.

Note that when this function is invoked with its argument set to true, then both the context menu and the completion menu item are enabled. If you do not want to the completion item to be visible simply invoke hideModechanger() right after calling this method. Also by default, the context menu is automatically created if this widget is editable. Thus you need to call this function with the argument set to false if you do not want this behavior.

Parameters:
showMenu If true, show the context menu.

Definition at line 221 of file klineedit.h.

bool KLineEdit::isContextMenuEnabled  )  const [inline]
 

Returns true when the context menu is enabled.

Definition at line 226 of file klineedit.h.

void KLineEdit::setURLDropsEnabled bool  enable  ) 
 

Enables/Disables handling of URL drops.

If enabled and the user drops an URL, the decoded URL will be inserted. Otherwise the default behavior of QLineEdit is used, which inserts the encoded URL.

Parameters:
enable If true, insert decoded URLs

Definition at line 1016 of file klineedit.cpp.

bool KLineEdit::isURLDropsEnabled  )  const
 

Returns true when decoded URL drops are enabled.

Definition at line 1021 of file klineedit.cpp.

void KLineEdit::setTrapReturnKey bool  trap  ) 
 

By default, KLineEdit recognizes Key_Return and Key_Enter and emits the returnPressed() signals, but it also lets the event pass, for example causing a dialog's default-button to be called.

Call this method with trap = true to make KLineEdit stop these events. The signals will still be emitted of course.

See also:
trapReturnKey()

Definition at line 1026 of file klineedit.cpp.

bool KLineEdit::trapReturnKey  )  const
 

Returns:
true if keyevents of Key_Return or Key_Enter will be stopped or if they will be propagated.
See also:
setTrapReturnKey ()

Definition at line 1031 of file klineedit.cpp.

bool KLineEdit::eventFilter QObject ,
QEvent
[virtual]
 

Re-implemented for internal reasons.

API not affected.

Definition at line 965 of file klineedit.cpp.

References KCursor::autoHideEventFilter(), and returnPressed().

KCompletionBox * KLineEdit::completionBox bool  create = true  ) 
 

Returns:
the completion-box, that is used in completion mode KGlobalSettings::CompletionPopup. This method will create a completion-box if none is there, yet.
Parameters:
create Set this to false if you don't want the box to be created i.e. to test if it is available.

Definition at line 1218 of file klineedit.cpp.

References setCompletionBox().

Referenced by setCompletedItems().

void KLineEdit::setCompletionObject KCompletion ,
bool  hsig = true
[virtual]
 

Reimplemented for internal reasons, the API is not affected.

Reimplemented from KCompletionBase.

Definition at line 1228 of file klineedit.cpp.

References KCompletionBase::compObj(), KCompletionBase::handleSignals(), setCompletedItems(), and KCompletionBase::setCompletionObject().

void KLineEdit::copy  )  const [virtual]
 

Reimplemented for internal reasons, the API is not affected.

Definition at line 388 of file klineedit.cpp.

Referenced by keyPressEvent().

void KLineEdit::setEnableSqueezedText bool  enable  ) 
 

Enable text squeezing whenever the supplied text is too long.

Only works for "read-only" mode.

Note that once text squeezing is enabled, QLineEdit::text() and QLineEdit::displayText() return the squeezed text. If you want the original text, use originalText.

See also:
QLineEdit
Since:
3.2

Definition at line 294 of file klineedit.cpp.

Referenced by setSqueezedText().

bool KLineEdit::isSqueezedTextEnabled  )  const
 

Returns true if text squeezing is enabled.

This is only valid when the widget is in read-only mode.

Since:
3.2

Definition at line 299 of file klineedit.cpp.

QString KLineEdit::originalText  )  const
 

Returns the original text if text squeezing is enabled.

If the widget is not in "read-only" mode, this function returns the same thing as QLineEdit::text().

See also:
QLineEdit
Since:
3.2

Definition at line 1289 of file klineedit.cpp.

void KLineEdit::setCompletionBox KCompletionBox box  ) 
 

Set the completion-box to be used in completion mode KGlobalSettings::CompletionPopup.

This will do nothing if a completion-box already exists.

Parameters:
box The KCompletionBox to set
Since:
3.4

Definition at line 1041 of file klineedit.cpp.

References completionBoxActivated(), KCompletionBase::handleSignals(), and userCancelled().

Referenced by completionBox().

void KLineEdit::completionBoxActivated const QString  )  [signal]
 

Emitted whenever the completion box is activated.

Since:
3.1

Referenced by setCompletionBox().

void KLineEdit::returnPressed const QString  )  [signal]
 

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::EchoMode.

Referenced by eventFilter().

void KLineEdit::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 normal.

Referenced by keyPressEvent().

void KLineEdit::substringCompletion const QString  )  [signal]
 

Emitted when the shortcut for substring completion is pressed.

Referenced by keyPressEvent().

void KLineEdit::textRotation KCompletionBase::KeyBindingType   )  [signal]
 

Emitted when the text rotation key-bindings are pressed.

The argument indicates which key-binding was pressed. In KLineEdit's case this can be either one of two values: PrevCompletionMatch or NextCompletionMatch. See KCompletionBase::setKeyBinding for details.

Note that this signal is not emitted if the completion mode is set to KGlobalSettings::CompletionNone or echoMode() is not normal.

Referenced by keyPressEvent().

void KLineEdit::completionModeChanged KGlobalSettings::Completion   )  [signal]
 

Emitted when the user changed the completion mode by using the popupmenu.

void KLineEdit::aboutToShowContextMenu QPopupMenu p  )  [signal]
 

Emitted before the context menu is displayed.

The signal allows you to add your own entries into the the context menu that is created on demand.

NOTE: Do not store the pointer to the QPopupMenu provided through since it is created and deleted on demand.

Parameters:
p the context menu about to be displayed

Referenced by createPopupMenu().

void KLineEdit::setReadOnly bool   )  [virtual, slot]
 

Re-implemented for internal reasons.

API not changed.

Definition at line 259 of file klineedit.cpp.

References setSqueezedText(), and setText().

void KLineEdit::rotateText KCompletionBase::KeyBindingType  type  )  [slot]
 

Iterates through all possible matches of the completed text or the history list.

This function simply iterates over all possible matches in case multimple matches are found as a result of a text completion request. It will have no effect if only a single match is found.

Parameters:
type The key-binding invoked.

Definition at line 199 of file klineedit.cpp.

References KCompletionBase::compObj(), KCompletion::nextMatch(), KCompletion::previousMatch(), and setCompletedText().

Referenced by keyPressEvent().

void KLineEdit::setCompletedText const QString  )  [virtual, slot]
 

See KCompletionBase::setCompletedText.

Implements KCompletionBase.

Definition at line 189 of file klineedit.cpp.

References KCompletionBase::completionMode().

Referenced by makeCompletion(), rotateText(), and setCompletedItems().

void KLineEdit::setCompletedItems const QStringList items  )  [virtual, slot]
 

Sets items into the completion-box if completionMode() is CompletionPopup.

The popup will be shown immediately.

Parameters:
items list of completion matches to be shown in the completion box.

Implements KCompletionBase.

Definition at line 1151 of file klineedit.cpp.

Referenced by keyPressEvent(), makeCompletion(), and setCompletionObject().

void KLineEdit::setCompletedItems const QStringList items,
bool  autoSuggest
[slot]
 

Same as the above function except it allows you to temporarily turn off text completion in CompletionPopupAuto mode.

TODO: Merge with above function in KDE 4. TODO: Does that make this or the above

Deprecated:
?
Parameters:
items list of completion matches to be shown in the completion box.
autoSuggest true if you want automatic text completion (suggestion) enabled.

Definition at line 1156 of file klineedit.cpp.

References KCompletionBox::cancelledText, completionBox(), setCompletedText(), KCompletionBox::setItems(), and setUserSelection().

void KLineEdit::clear  )  [virtual, slot]
 

Reimplemented to workaround a buggy QLineEdit::clear() (changing the clipboard to the text we just had in the lineedit).

Reimplemented in KIconViewSearchLine.

Definition at line 1278 of file klineedit.cpp.

References setText().

Referenced by KIconViewSearchLine::clear(), and KEditListBox::clear().

void KLineEdit::setSqueezedText const QString text  )  [slot]
 

Squeezes text into the line edit.

This can only be used with read-only line-edits.

Since:
3.1

Definition at line 288 of file klineedit.cpp.

References setEnableSqueezedText(), and setText().

Referenced by resizeEvent(), setReadOnly(), and setText().

void KLineEdit::setText const QString  )  [virtual, slot]
 

Re-implemented to enable text squeezing.

API is not affected.

Definition at line 304 of file klineedit.cpp.

References setSqueezedText().

Referenced by clear(), KToolBar::insertLined(), KLineEditDlg::KLineEditDlg(), KToolBar::setLinedText(), setReadOnly(), setSqueezedText(), setURL(), KLineEditDlg::slotClear(), and userCancelled().

void KLineEdit::makeCompletion const QString  )  [protected, virtual, slot]
 

Completes the remaining text with a matching one from a given list.

Definition at line 220 of file klineedit.cpp.

References KCompletion::allMatches(), KCompletionBase::completionMode(), KCompletionBase::compObj(), KCompletion::makeCompletion(), setCompletedItems(), setCompletedText(), and setUserSelection().

Referenced by keyPressEvent().

void KLineEdit::slotAboutToShow  )  [inline, protected, slot]
 

Deprecated:
. Will be removed in the next major release!

Definition at line 467 of file klineedit.h.

void KLineEdit::slotCancelled  )  [inline, protected, slot]
 

Deprecated:
. Will be removed in the next major release!

Definition at line 472 of file klineedit.h.

void KLineEdit::userCancelled const QString cancelText  )  [protected, slot]
 

Resets the current displayed text.

Call this function to revert a text completion if the user cancels the request. Mostly applies to popup completions.

Definition at line 1059 of file klineedit.cpp.

References KCompletionBase::completionMode(), and setText().

Referenced by setCompletionBox().

void KLineEdit::resizeEvent QResizeEvent  )  [protected, virtual]
 

Re-implemented for internal reasons.

API not affected.

See QLineEdit::resizeEvent().

Definition at line 418 of file klineedit.cpp.

References setSqueezedText().

void KLineEdit::keyPressEvent QKeyEvent  )  [protected, virtual]
 

Re-implemented for internal reasons.

API not affected.

See QLineEdit::keyPressEvent().

Reimplemented in KListViewLineEdit, and KRestrictedLine.

Definition at line 426 of file klineedit.cpp.

References KStdAccel::backwardWord(), KStdAccel::beginningOfLine(), completion(), KCompletionBase::completionMode(), KCompletionBase::compObj(), KShortcut::contains(), copy(), KStdAccel::copy(), KStdAccel::cut(), KStdAccel::deleteWordBack(), KStdAccel::deleteWordForward(), KCompletionBase::emitSignals(), KStdAccel::endOfLine(), KStdAccel::forwardWord(), KCompletionBase::getKeyBindings(), KCompletionBase::handleSignals(), makeCompletion(), KStdAccel::paste(), KStdAccel::pasteSelection(), KStdAccel::redo(), rotateText(), setCompletedItems(), setUserSelection(), KStdAccel::shortcut(), substringCompletion(), textRotation(), and KStdAccel::undo().

Referenced by KListViewLineEdit::keyPressEvent().

void KLineEdit::mousePressEvent QMouseEvent  )  [protected, virtual]
 

Re-implemented for internal reasons.

API not affected.

See QLineEdit::mousePressEvent().

Definition at line 815 of file klineedit.cpp.

void KLineEdit::mouseDoubleClickEvent QMouseEvent  )  [protected, virtual]
 

Re-implemented for internal reasons.

API not affected.

See QWidget::mouseDoubleClickEvent().

Definition at line 804 of file klineedit.cpp.

void KLineEdit::contextMenuEvent QContextMenuEvent  )  [protected, virtual]
 

Re-implemented for internal reasons.

API not affected.

See QLineEdit::contextMenuEvent().

Definition at line 831 of file klineedit.cpp.

QPopupMenu * KLineEdit::createPopupMenu  )  [protected, virtual]
 

Re-implemented for internal reasons.

API not affected.

See QLineEdit::createPopupMenu().

Reimplemented in KListViewSearchLine.

Definition at line 837 of file klineedit.cpp.

References aboutToShowContextMenu(), KGlobalSettings::completionMode(), KCompletionBase::completionMode(), and KCompletionBase::compObj().

Referenced by KListViewSearchLine::createPopupMenu().

void KLineEdit::dropEvent QDropEvent  )  [protected, virtual]
 

Re-implemented to handle URI drops.

See QLineEdit::dropEvent().

Definition at line 942 of file klineedit.cpp.

References KURLDrag::decode().

void KLineEdit::setUserSelection bool  userSelection  )  [protected]
 

Sets the widget in userSelection mode or in automatic completion selection mode.

This changes the colors of selections.

Definition at line 1249 of file klineedit.cpp.

Referenced by keyPressEvent(), makeCompletion(), and setCompletedItems().

void KLineEdit::create WId  = 0,
bool  initializeWindow = true,
bool  destroyOldWindow = true
[protected, virtual]
 

Reimplemented for internal reasons, the API is not affected.

Definition at line 1243 of file klineedit.cpp.

References KCursor::setAutoHideCursor().

void KLineEdit::focusInEvent QFocusEvent  )  [protected, virtual]
 

Re-implemented for internal reasons.

API not affected.

See QLineEdit::focusInEvent().

Definition at line 1297 of file klineedit.cpp.

bool KLineEdit::autoSuggest  )  const [protected]
 

Whether in current state text should be auto-suggested

Since:
3.4.

Definition at line 1306 of file klineedit.cpp.


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kdeui Library Version 3.4.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Tue Aug 2 12:23:30 2005 by doxygen 1.3.9.1 written by Dimitri van Heesch, © 1997-2003