/* 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@kde.org>
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 <kcompletion.h>
class KCompletionBox;
class KURL;
/**
* An enhanced QLineEdit widget for inputting text.
*
* @sect Detail
*
* This widget inherits from @ref QLineEdit and implements the following
* additional functionalities: q 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 @ref KLineEdit also emits a few more
* additional signals. These are: @ref completion( const QString& ),
* textRotation( KeyBindingType ), and @ref 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 @ref completionObject( bool ) member function for the first time or
* use @ref setCompletionObject( KCompletion*, bool ) to assign your own
* completion object. Additionally, to make this widget more functional,
* @ref 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 @ref 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 @ref KStdAccel. These values, however,
* can be overriden locally by invoking @ref KCompletionBase::setKeyBinding().
* The values can easily be reverted back to the default setting, by simply
* calling @ref useGlobalSettings(). An alternate method would be to default
* individual key-bindings by usning @ref setKeyBinding() with the default
* second argument.
*
* NOTE that if the @p EchoMode for this widget is set to something other
* than @p QLineEdit::Normal, the completion mode will always be defaulted
* to @ref KGlobal::CompletionNone. This is done purposefully to guard
* against protected entries such as passwords being cached in @ref KCompletion's
* list. Hence, if the @p EchoMode is not @ref QLineEdit::Normal, the completion
* mode is automatically disabled.
*
* @sect Examples
*
* To enable the basic completion feature :
*
* <pre>
* 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&));
* </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>
*
* Note that you have to either delete the allocated completion object
* when you don't need it anymore, or call
* setAutoDeleteCompletionObject( true );
*
* @sect Miscellaneous function calls :
*
* <pre>
* // Tell the widget not to handle completion and
* // iteration internally.
* edit->setHandleSignals( false );
* // Set your own completion key for manual completions.
* edit->setKeyBinding( KCompletionBase::TextCompletion, Qt::End );
* // Hide the context (popup) menu
* edit->setContextMenuEnabled( false );
* // Temporarly disable signal emitions
* // (both completion & iteration signals)
* edit->disableSignals();
* // Default the key-bindings to system settings.
* edit->useGlobalKeyBindings();
* </pre>
*
* @short An enhanced single line input widget.
* @author Dawit Alemayehu <adawit@kde.org>
*/
class KLineEdit : public QLineEdit, public KCompletionBase
{
Q_OBJECT
Q_PROPERTY( bool contextMenuEnabled READ isContextMenuEnabled WRITE setContextMenuEnabled )
Q_PROPERTY( bool urlDropsEnabled READ isURLDropsEnabled WRITE setURLDropsEnabled )
public:
/**
* Construct a @ref 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 );
/**
* Construct a @ref 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.
*/
KLineEdit ( QWidget *parent=0, const char *name=0 );
/**
* Destructor.
*/
virtual ~KLineEdit ();
/**
* Sets @p url into the lineedit. It uses @ref KURL::prettyURL() so
* that the url is properly decoded for displaying.
*/
void setURL( const KURL& url );
/**
* Put 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.
*
* 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 @ref 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 behaviour.
*
* @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.
*
* @return @p true If 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
* behaviour 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
*
* @return @p true if decoded URL drops are enabled
*/
bool isURLDropsEnabled() const;
/**
* By default, @ref KComboBox recognizes @p Key_Return and @p Key_Enter and emits
* the @ref 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 KComboBox stop these
* events. The signals will still be emitted of course.
*
* Only affects read-writable comboboxes.
*
* @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.
*
* @reimplemented
*/
virtual bool eventFilter( QObject *, QEvent * );
/**
* @returns the completion-box, that is used in completion mode
* @ref KGlobalSettings::CompletionPopup.
* This method will create a completion-box by calling
* @ref makeCompletionBox, if none is there, yet.
*/
KCompletionBox * completionBox();
signals:
/**
* 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
* @ref QLineEdit::Password.
*/
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 text rotation key-bindings are pressed.
*
* The argument indicates which key-binding was pressed.
* In @ref KLineEdit's case this can be either one of two values:
* @ref PrevCompletionMatch or @ref NextCompletionMatch. See
* @ref KCompletionBase::setKeyBinding for details.
*
* Note that this signal is @em not emitted if the completion
* mode is set to @p 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 );
public slots:
/**
* Iterate 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 @ref KCompletionBase::setCompletionText.
*/
virtual void setCompletedText( const QString& );
/**
* Sets @p items into the completion-box if @ref completionMode() is
* CompletionPopup. The popup will be shown immediately.
*/
void setCompletedItems( const QStringList& items );
protected slots:
/**
* Complete the remaining text with a matching one from
* a given list.
*/
virtual void makeCompletion( const QString& );
/**
* Stores the current text whenever the completion box is
* displayed for the first time.
*/
void slotAboutToShow();
/**
* Re-stores the current text if the completion box is
* cancelled by the user.
*/
void slotCancelled();
protected:
/**
* 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 * );
/**
* Re-implemented to handle URI drops.
*
* See @ref 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*/ );
private:
void makeCompletionBox(); // creates the completion box
// Constants that represent the ID's of the popup menu.
// TODO: See if we can replace this mess with KActionMenu
// in the future though this is working lovely.
enum MenuID {
Default=0,
Cut,
Copy,
Paste,
Clear,
Unselect,
SelectAll,
NoCompletion,
AutoCompletion,
ShellCompletion,
PopupCompletion,
SemiAutoCompletion
};
/**
* Initializes variables. Called from the constructors.
*/
void init();
// Indicates whether the context
// menu is enabled or disabled
bool m_bEnableMenu;
class KLineEditPrivate;
KLineEditPrivate *d;
};
#endif
| Generated by: faure on ftp.kde.com on Wed Jun 20 13:26:11 2001, using kdoc 2.0a53. |