diff options
Diffstat (limited to 'kdeui/klineedit.h')
| -rw-r--r-- | kdeui/klineedit.h | 656 |
1 files changed, 656 insertions, 0 deletions
diff --git a/kdeui/klineedit.h b/kdeui/klineedit.h new file mode 100644 index 000000000..bd3cb6faf --- /dev/null +++ b/kdeui/klineedit.h @@ -0,0 +1,656 @@ +/* This file is part of the KDE libraries + + This class was originally inspired by Torben Weis' + fileentry.cpp for KFM II. + + Copyright (C) 1997 Sven Radej <sven.radej@iname.com> + Copyright (c) 1999 Patrick Ward <PAT_WARD@HP-USA-om5.om.hp.com> + Copyright (c) 1999 Preston Brown <pbrown@kde.org> + + Completely re-designed: + Copyright (c) 2000,2001 Dawit Alemayehu <adawit@kde.org> + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License (LGPL) as published by the Free Software Foundation; + either version 2 of the License, or (at your option) any later + version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with this library; see the file COPYING.LIB. If not, write to + the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. +*/ + +#ifndef _KLINEEDIT_H +#define _KLINEEDIT_H + +#include <qlineedit.h> +#include <kcompletion.h> + +class QPopupMenu; + +class KCompletionBox; +class KURL; + +/** + * An enhanced QLineEdit widget for inputting text. + * + * \b Detail \n + * + * 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 + * @p 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 @p 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 @p setKeyBinding(). You can easily + * revert these settings back to the default by simply calling + * @p useGlobalSettings(). An alternate method would be to default + * individual key-bindings by using setKeyBinding() with the default + * second argument. + * + * If @p EchoMode for this widget is set to something other than @p 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 @p 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. + * + * \b Usage \n + * + * To enable the basic completion feature : + * + * \code + * 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&))); + * \endcode + * + * To use a customized completion objects or your + * own completion object : + * + * \code + * 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&))); + * \endcode + * + * 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: + * \code + * edit->setAutoDeleteCompletionObject( true ); + * \endcode + * + * <b>Miscellaneous function calls :</b>\n + * + * \code + * // 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(); + * \endcode + * + * @author Dawit Alemayehu <adawit@kde.org> + */ + +class KDEUI_EXPORT KLineEdit : public QLineEdit, public KCompletionBase +{ + friend class KComboBox; + + Q_OBJECT + Q_PROPERTY( bool contextMenuEnabled READ isContextMenuEnabled WRITE setContextMenuEnabled ) + Q_PROPERTY( bool urlDropsEnabled READ isURLDropsEnabled WRITE setURLDropsEnabled ) + Q_PROPERTY( bool trapEnterKeyEvent READ trapReturnKey WRITE setTrapReturnKey ) + Q_PROPERTY( bool enableSqueezedText READ isSqueezedTextEnabled WRITE setEnableSqueezedText ) + // @since 3.5.4 + Q_PROPERTY( QString clickMessage READ clickMessage WRITE setClickMessage ) + +public: + + /** + * Constructs a KLineEdit object with a default text, a parent, + * and a name. + * + * @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( const QString &string, QWidget *parent, const char *name = 0 ); + + /** + * Constructs a KLineEdit object with a parent and a name. + * + * @param parent The parent object of this widget. + * @param name The name of this widget. + */ + KLineEdit ( QWidget *parent=0, const char *name=0 ); + + /** + * Destructor. + */ + virtual ~KLineEdit (); + + /** + * Sets @p url into the lineedit. It uses KURL::prettyURL() so + * that the url is properly decoded for displaying. + */ + void setURL( const KURL& url ); + + /** + * Puts the text cursor at the end of the string. + * + * This method is deprecated. Use QLineEdit::end() + * instead. + * + * @deprecated + * QLineEdit::end() + */ + void cursorAtEnd() { end( false ); } + + /** + * 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 + */ + virtual void setCompletionMode( KGlobalSettings::Completion mode ); + + /** + * Enables/disables the popup (context) menu. + * + * Note that when this function is invoked with its argument + * set to @p 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. + * + * @param showMenu If @p true, show the context menu. + */ + virtual void setContextMenuEnabled( bool showMenu ) { m_bEnableMenu = showMenu; } + + /** + * Returns @p true when the context menu is enabled. + */ + bool isContextMenuEnabled() const { return m_bEnableMenu; } + + /** + * 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. + * + * @param enable If @p true, insert decoded URLs + */ + void setURLDropsEnabled( bool enable ); + + /** + * Returns @p true when decoded URL drops are enabled + */ + bool isURLDropsEnabled() const; + + /** + * By default, KLineEdit recognizes @p Key_Return and @p 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 @p trap = @p true to make @p KLineEdit stop these + * events. The signals will still be emitted of course. + * + * @see trapReturnKey() + */ + void setTrapReturnKey( bool trap ); + + /** + * @returns @p true if keyevents of @p Key_Return or + * @p Key_Enter will be stopped or if they will be propagated. + * + * @see setTrapReturnKey () + */ + bool trapReturnKey() const; + + /** + * Re-implemented for internal reasons. API not affected. + * + */ + virtual bool eventFilter( QObject *, QEvent * ); + + /** + * @returns the completion-box, that is used in completion mode + * KGlobalSettings::CompletionPopup. + * This method will create a completion-box if none is there, yet. + * + * @param create Set this to false if you don't want the box to be created + * i.e. to test if it is available. + */ + KCompletionBox * completionBox( bool create = true ); + + /** + * Reimplemented for internal reasons, the API is not affected. + */ + virtual void setCompletionObject( KCompletion *, bool hsig = true ); + + /** + * Reimplemented for internal reasons, the API is not affected. + */ + virtual void copy() const; + + /** + * 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 @ref originalText. + * + * @see QLineEdit + * @since 3.2 + */ + void setEnableSqueezedText( bool enable ); + + /** + * Returns true if text squeezing is enabled. + * This is only valid when the widget is in read-only mode. + * + * @since 3.2 + */ + bool isSqueezedTextEnabled() 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 QLineEdit + * @since 3.2 + */ + QString originalText() const; + + /** + * Set the completion-box to be used in completion mode + * KGlobalSettings::CompletionPopup. + * This will do nothing if a completion-box already exists. + * + * @param box The KCompletionBox to set + * @since 3.4 + */ + void setCompletionBox( KCompletionBox *box ); + + /** + * This makes the line edit display a grayed-out hinting text as long as + * the user didn't enter any text. It is often used as indication about + * the purpose of the line edit. + * @since 3.5.4 + */ + void setClickMessage( const QString &msg ); + + /** + * @return the message set with setClickMessage + * @since 3.5.4 + */ + QString clickMessage() const; + +signals: + + /** + * Emitted whenever the completion box is activated. + * @since 3.1 + */ + void completionBoxActivated (const QString &); + + /** + * Emitted when the user presses the return key. + * + * The argument is the current text. Note that this + * signal is @em not emitted if the widget's @p EchoMode is set to + * QLineEdit::EchoMode. + */ + void returnPressed( const QString& ); + + /** + * Emitted when the completion key is pressed. + * + * Please note that this signal is @em not emitted if the + * completion mode is set to @p CompletionNone or @p EchoMode is + * @em normal. + */ + void completion( const QString& ); + + /** + * Emitted when the shortcut for substring completion is pressed. + */ + void substringCompletion( const QString& ); + + /** + * 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 + * @p setKeyBinding for details. + * + * Note that this signal is @em not emitted if the completion + * mode is set to @p KGlobalSettings::CompletionNone or + * @p echoMode() is @em not normal. + */ + void textRotation( KCompletionBase::KeyBindingType ); + + /** + * Emitted when the user changed the completion mode by using the + * popupmenu. + */ + void completionModeChanged( KGlobalSettings::Completion ); + + /** + * 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. + * + * @param p the context menu about to be displayed + */ + void aboutToShowContextMenu( QPopupMenu * p ); + +public slots: + + /** + * Re-implemented for internal reasons. API not changed. + */ + virtual void setReadOnly(bool); + + /** + * 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. + * + * @param type The key-binding invoked. + */ + void rotateText( KCompletionBase::KeyBindingType type ); + + /** + * See KCompletionBase::setCompletedText. + */ + virtual void setCompletedText( const QString& ); + + /** + * Sets @p items into the completion-box if completionMode() is + * CompletionPopup. The popup will be shown immediately. + * + * @param items list of completion matches to be shown in the completion box. + */ + void setCompletedItems( const QStringList& items ); + + /** + * 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 ? + * + * @param items list of completion matches to be shown in the completion box. + * @param autoSuggest true if you want automatic text completion (suggestion) enabled. + */ + void setCompletedItems( const QStringList& items, bool autoSuggest ); + + /** + * Reimplemented to workaround a buggy QLineEdit::clear() + * (changing the clipboard to the text we just had in the lineedit) + */ + virtual void clear(); + + /** + * Squeezes @p text into the line edit. + * This can only be used with read-only line-edits. + * @since 3.1 + */ + void setSqueezedText( const QString &text); + + /** + * Re-implemented to enable text squeezing. API is not affected. + */ + virtual void setText ( const QString& ); + + +protected slots: + + /** + * Completes the remaining text with a matching one from + * a given list. + */ + virtual void makeCompletion( const QString& ); + + /** + * @deprecated. Will be removed in the next major release! + */ + void slotAboutToShow() {} + + /** + * @deprecated. Will be removed in the next major release! + */ + void slotCancelled() {} + + /** + * Resets the current displayed text. + * Call this function to revert a text completion if the user + * cancels the request. Mostly applies to popup completions. + */ + void userCancelled(const QString & cancelText); + +protected: + + /** + * Re-implemented for internal reasons. API not affected. + * + * See QLineEdit::resizeEvent(). + */ + virtual void resizeEvent( QResizeEvent * ); + + /** + * Re-implemented for internal reasons. API not affected. + * + * See QLineEdit::keyPressEvent(). + */ + virtual void keyPressEvent( QKeyEvent * ); + + /** + * Re-implemented for internal reasons. API not affected. + * + * See QLineEdit::mousePressEvent(). + */ + virtual void mousePressEvent( QMouseEvent * ); + + /** + * Re-implemented for internal reasons. API not affected. + * + * See QWidget::mouseDoubleClickEvent(). + */ + virtual void mouseDoubleClickEvent( QMouseEvent * ); + + /** + * Re-implemented for internal reasons. API not affected. + * + * See QLineEdit::mouseReleaseEvent(). + */ + virtual void mouseReleaseEvent( QMouseEvent * ); + + /** + * Re-implemented for internal reasons. API not affected. + * + * See QLineEdit::contextMenuEvent(). + */ + virtual void contextMenuEvent( QContextMenuEvent * ); + + /** + * Re-implemented for internal reasons. API not affected. + * + * See QLineEdit::createPopupMenu(). + */ + virtual QPopupMenu *createPopupMenu(); + + /** + * Re-implemented for internal reasons. API not affected. + * + * See QFrame::drawContents(). + */ + virtual void drawContents( QPainter *p ); + + /** + * Re-implemented to handle URI drops. + * + * See QLineEdit::dropEvent(). + */ + virtual void dropEvent( QDropEvent * ); + + /* + * This function simply sets the lineedit text and + * highlights the text appropriately if the boolean + * value is set to true. + * + * @param text + * @param marked + */ + virtual void setCompletedText( const QString& /*text*/, bool /*marked*/ ); + + + /** + * Sets the widget in userSelection mode or in automatic completion + * selection mode. This changes the colors of selections. + */ + void setUserSelection( bool userSelection ); + + /** + * Reimplemented for internal reasons, the API is not affected. + */ + virtual void create( WId = 0, bool initializeWindow = true, + bool destroyOldWindow = true ); + + /** + * Re-implemented for internal reasons. API not affected. + * + * See QLineEdit::focusInEvent(). + */ + virtual void focusInEvent( QFocusEvent* ); + + /** + * Re-implemented for internal reasons. API not affected. + * + * See QLineEdit::focusOutEvent(). + */ + virtual void focusOutEvent( QFocusEvent* ); + + /** + * Whether in current state text should be auto-suggested + * @since 3.4 + */ + bool autoSuggest() const; + +private slots: + void completionMenuActivated( int id ); + void tripleClickTimeout(); // resets possibleTripleClick + void slotRestoreSelectionColors(); + void setTextWorkaround( const QString& text ); + +private: + + // Constants that represent the ID's of the popup menu. + enum MenuID + { + Default = 42, + NoCompletion, + AutoCompletion, + ShellCompletion, + PopupCompletion, + ShortAutoCompletion, + PopupAutoCompletion + }; + + /** + * Initializes variables. Called from the constructors. + */ + void init(); + + bool copySqueezedText( bool clipboard ) const; + + /** + * Checks whether we should/should not consume a key used as + * an accelerator. + */ + bool overrideAccel (const QKeyEvent* e); + + /** + * Properly sets the squeezed text whenever the widget is + * created or resized. + */ + void setSqueezedText (); + + bool m_bEnableMenu; + + bool possibleTripleClick; // set in mousePressEvent, deleted in tripleClickTimeout + +protected: + virtual void virtual_hook( int id, void* data ); +private: + class KLineEditPrivate; + KLineEditPrivate *d; +}; + +#endif |