|
|
/* 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 Dawit Alemayehu <adawit@earthlink.net> This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License 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 Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; see the file COPYING.LIB. If not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ #ifndef _KLINEEDIT_H #define _KLINEEDIT_H #include <qlineedit.h> #include <qpopupmenu.h> #include <kcompletion.h> /** * 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 @ref 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. * Additionally, 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: @ref completion, @ref rotateUp and @ref 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. * * By default, when you create a completion object through * either @ref completionObject() or @ref setCompletionObject * this widget will be automatically enabled to handle the * signals. If you do not need this feature, simply use the * appropriate accessor methods to turn it off. * * The default key-bindings for completion and rotation * are determined from the global settings in @ref KStdAccel. * However, these values can be set locally overriding the * global settings. Simply invoking @ref 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 @ref 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. * NOTE: if the EchoMode for this widget is set to something * other than @ref QLineEdit::Normal, the completion mode will * always be defaulted to KGlobal::CompletionNone. 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 disabled. * * @sect Examples: * * To enable the basic completion feature : * * <pre> * KLineEdit *edit = new KLineEdit( true, this, "mywidget" ); * KCompletion *comp = edit->completionObject(); * // Connect to the return pressed signal - optional * connect(edit,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&)); * </pre> * * To use a customized completion objects or your * own completion object : * * <pre> * 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&)); * </pre> * * Other miscelanous function call examples : * * <pre> * // Tell the widget not to handle completion and * // rotation internally. * edit->setHandleSignals( false ); * // Set your own completion key for manual completions. * edit->setCompletionKey( Qt::End ); * // Shows the context (popup) menu * edit->setEnableContextMenu(); * // Temporarly disable signal emition * edit->disableSignals(); * // Default the key-bindings to system settings. * edit->useGlobalSettings(); * </pre> * * @short An enhanced single line input widget. * @author Dawit Alemayehu <adawit@earthlink.net> */ class KLineEdit : public QLineEdit, public KCompletionBase { Q_OBJECT 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 * @param hsig determines if this widget automatically handles both signals internally. */ KLineEdit( const QString &string, QWidget *parent, const char *name = 0 ); /** * Constructs a KLineEdit object with 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 * @param hsig determines if this widget automatically handles both signals internally. */ KLineEdit ( QWidget *parent=0, const char *name=0 ); /** * Destructor. */ virtual ~KLineEdit (); /** * Puts cursor at the end of the string. * * This method is deprecated. Use @ref QLineEdit::end * instead. * * @deprecated * @ref QLineEdit::end */ void cursorAtEnd() { end( false ); } /** * Re-implemented from @ref 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 @ref KCompletionBase::setCompletionMode */ virtual void setCompletionMode( KGlobalSettings::Completion mode ); /** * 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 enabled. By default the mode changer * is visible when context menu is enabled. Use either the * second boolean parameter or @ref hideModechanger() if you * do not want this item to be visible. 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. * * @param showMenu if true, show the context menu. * @param showMode if true, show the mode changer item. */ virtual void setEnableContextMenu( bool showMenu ); /** * Returns true when the context menu is enabled. * * @return @p true if context menu is enabled. */ bool isContextMenuEnabled() const { return m_bEnableMenu; } signals: /** * 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 returnPressed( 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 completion( const QString& ); /** * Signal emitted when the rotate up key is pressed. * See @ref KCompletionBase::setRotateUpKey. * * 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 down key is pressed. * See @ref KCompletionBase::setRotateDownKey. * * Note that this signal is NOT emitted if the completion * mode is set to CompletionNone or EchoMode is NOT normal. */ void rotateDown(); public slots: /* * 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. */ virtual void iterateUpInList() { rotateText( completionObject()->previousMatch() ); } /* * 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. */ virtual void iterateDownInList() { rotateText( completionObject()->nextMatch() ); } protected slots: /** * Accepts the "aboutToShow" signal from the completion * sub-menu inserted by @ref showCompletionMenu. * * This method sets the completion mode to the one * requested by the end user. */ virtual void selectedItem( int itemID ) { setCompletionMode( (KGlobalSettings::Completion)itemID ); } /** * 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 */ virtual void showCompletionMenu() { insertCompletionItems( this, SLOT( selectedItem( int ) ) ); } /** * 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, * @ref KCompletionBase::insetCompeltionMenu, is * defined by the KCompletionBase. */ virtual void aboutToShowMenu() { insertCompletionMenu( this, SLOT( showCompletionMenu() ), m_pContextMenu, m_pContextMenu->count()-1 ); } /** * Completes the remaining text with a matching one from * a given list. */ virtual void makeCompletion( const QString& ); protected: /** * Initializes variables. Called from the constructors. */ virtual void init(); /** * Rotates the text on rotation events. * * @param string the text to replace the current one with. */ void rotateText( const QString& ); /** * Implementation of @ref KCompletionBase::connectSignals(). * * This function simply connects the signals to appropriate * slots when they are handled internally. * * @param handle if true, handle completion & roation internally. */ virtual void connectSignals( bool handle ) const; /** * Re-implemented for internal reasons. API not affected. * * See @ref QLineEdit::keyPressEvent. */ virtual void keyPressEvent( QKeyEvent * ); /** * Re-implemented for internal reasons. API not affected. * * See @ref QLineEdit::mousePressEvent. */ virtual void mousePressEvent( QMouseEvent * ); private : // Pointers to the context & sub menus. QPopupMenu *m_pContextMenu; // Indicates whether the context menu is enabled // or disabled bool m_bEnableMenu; }; #endif
Generated by: dfaure@faure on Sun Mar 26 14:24:24 2000, using kdoc 2.0a35. |