Source: klineedit.h


Annotated List
Files
Globals
Hierarchy
Index
/*  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>

    Re-designed with addional functionality:
    Copyright (c) 1999-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.  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 @ref 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.
 *
 *
 * 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 @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.
 *
 * @sect A small example:
 *
 * To enable the basic completion & rotation features :
 *
 * <pre>
 * 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& ) ) );
 * </pre>
 *
 * To use a customized completion object such as KURLCompletion
 * use setCompletionObject(...) instead :
 *
 * <pre>
 * 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& ) ) );
 * </pre>
 *
 * 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.
 *
 *
 * @short An enhanced single line input widget.
 * @author Dawit Alemayehu <adawit@earthlink.net>
 */
class KLineEdit : public QLineEdit
{
  Q_OBJECT

public:

    /**
    * Constructs a KLineEdit object with a default text, a parent,
    * a name and a context menu.
    *
    * @param @p string text to be shown in the edit widget
    * @param @p parent the parent object of this widget
    * @param @p name the name of this widget
    */
    KLineEdit( const QString &string, QWidget *parent, const char *name = 0 );

    /**
    * Constructs a KLineEdit object with a parent, a name and a
    * a context menu.
    *
    * @param @p string text to be shown in the edit widget
    * @param @p parent the parent object of this widget
    * @param @p name the name of this widget
    */
    KLineEdit ( QWidget *parent=0, const char *name=0 );

    /**
    *  Destructor.
    */
    virtual ~KLineEdit ();

    /**
    * Puts cursor at the end of the string.
    * 
    * This method is deprecated.  Use @see QLineEdit::end instead.
    *
    * @deprecated
    * @see QLineEdit::end
    */
    void cursorAtEnd() { end( false ); }

    /**
    * Sets the @ref 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
    * @ref setDeleteCompletionOnExit and @ref 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.
    *
    * @param a @ref KCompletion or a derived child object.
    * @param @p autoDelete if true, the completion object is deleted in the destructor.
    */
    void setCompletionObject( KCompletion*,  bool autoDelete = false );

    /**
    * Returns true if the completion object is deleted upon this widget's
    * destruction.
    *
    * See @ref setCompeltionObject, @ref setHandleCompletion,
    * @ref deleteCompletionOnExit and @ref setDeleteCompletionOnExit
    * for more details.
    *
    * @return true if the completion object is deleted
    */
    bool deleteCompletion() const { return m_bAutoDelCompObj; }

    /**
    * 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 @p autoDelete if set to true the completion object is deleted on exit.
    */
    void setDeleteCompletion( bool autoDelete = false ) { m_bAutoDelCompObj = autoDelete; }

    /**
    * Returns a pointer to the current completion object.
    *
    * @return the completion object or null if one does not exist.
    */
    KCompletion* completionObject() const { return m_pCompObj; }

    /**
    * 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 @ref setHandleCompletion
    * and @ref setHandleCompletion.
    *
    * @param @p emit if true emits completion signal.
    */
    void setEnableCompletionSignal( bool enable ) { m_bEmitCompletion = 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 @ref setHandleRotation has
    * been or is called.  See also @see setHandleRotation.
    */
    void setEnableRotationSignal( bool enable ) { m_bEmitRotation = enable; }

    /**
    * 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 @p complete when true enables this widget to handle completion.
    */
    void setHandleCompletion( bool complete = 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 @p autoHandle when true handle rotation signals internally.
    */
    void setHandleRotation( bool rotate = true );

    /**
    * Returns true if this widget handles completion signal internally.
    *
    * @return true when this widget handles completion signal.
    */
    bool handlesCompletion() { return m_bEmitCompletion; }

    /**
    * Returns true if this widget handles rotation signal internally.
    *
    * @return true when this widget handles rotation signal.
    */
    bool handlesRotation() { return m_bEmitRotation; }

    /**
    * Set the type of completion to be used.
    *
    * The completion modes supported are those defined in @ref KGlobal.
    * These completion types are CompletionNone, CompletionAuto,
    * CompletionMan, and CompletionShell.
    *
    * @param mode Completion type:
    *        @li CompletionNone  - Disables all completion features.
    *        @li CompletionAuto  - Attempts to find a match and fill-in
    *                              the remaining text.
    *        @li CompletionMan   - Acts the same way as "CompletionAuto"
    *                              except the action has to be triggered
    *                              using the pre-defined completion key.
    *        @li CompletionShell - Attempts to mimic the completion feature
    *                              found in typcial *nix shell enviornments.
    *
    * Please note that if the EchoMode for this widget is set to something
    * other than @ref 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.
    */
    virtual void setCompletionMode( KGlobal::Completion mode );

    /**
    * Retrieve the current completion mode.
    *
    * The return values are of type @ref KGlobal::Completion.  See
    * @ref setCompletionMode for details.
    *
    * @return the completion mode.
    */
    KGlobal::Completion completionMode() const { return m_iCompletionMode; }

    /**
    * 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 @p 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 @p ckey is negative or the key-binding conflicts with either
    * @ref completion or @ref rotateDown keys, this function will return false.
    *
    * @param @p ckey Key binding to use for completion.  Default is 0.
    * @return @p true if key-binding can be successfully set.
    */
    bool setCompletionKey( int ckey = 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 @ref rotateDown signal will be
    * emitted.  If no value is supplied for @p rDnkey or it is set to 0, then
    * the completion key will be defaulted to the global setting.  This method
    * returns false if @p rDnkey is negative or the supplied key-binding
    * conflicts with either @ref completion or @ref rotateUp keys.
    *
    * @param @p rDnkey the key-binding to use for rotating up in a list.
    * @return @p true if key-binding can successfully be set.
    */
    bool setRotateDownKey( int rDnKey = 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 @ref rotateUp signal will be
    * emitted.  If no value is supplied for @p rUpkey or it is set to 0, then
    * the completion key will be defaulted to the global setting.  This method
    * returns false if @p rUpkey is negative or the supplied key-binding
    * conflicts with either @ref completion or @ref rotateDown keys.
    *
    * @param @p rUpkey the key-binding to use for rotating down in a list.
    * @return @p true if key-binding can successfully be set.
    */
    bool setRotateUpKey( int rUpKey = 0 );

    /**
    * 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.
    *
    * @return the key-binding used for rotating through a list.
    */
    int completionKey() const { return m_iCompletionKey; }

    /**
    * 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 @ref rotateDown key
    * does.
    *
    * If the key binding contains modifier key(s), the SUM of their values
    * is returned.  See also @ref setRotateUpKey.
    *
    * @return the key-binding used for rotating up in a list.
    */
    int rotateUpKey() const { return m_iRotateUpKey; }

    /**
    * 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 @ref rotateDown key
    * does.
    *
    * If the key binding contains modifier key(s), the SUM of their values
    * is returned.  See also @ref setRotateDownKey.
    *
    * @return the key-binding used for rotating down in a list.
    */
    int rotateDownKey() const { return m_iRotateDnKey; }

    /**
    * 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 useGlobalSettings();

    /**
    * 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 @p showMenu if true, shows the context menu.
    */
    virtual void setEnableContextMenu( bool showMenu = 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 @p showChanger if set to true, the mode changer item is enabled.
    */
    virtual void setEnableModeChanger( bool showChanger = false );

    /**
    * Returns true when the context menu is enabled.
    *
    * @return @p true if context menu is enabled.
    */
    bool isContextMenuEnabled() const { return m_bShowContextMenu; }

    /**
    * Returns true if the mode changer item is visible in
    * the context menu.
    *
    * @return @p true if the mode changer is visible in context menu.
    */
    bool isModeChangerEnabled() const { return m_bShowModeChanger; }

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.
    *
    * 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 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 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();

    /*
    * 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();


protected slots:

    /**
    * Copies the marked text to the clipboard, if there is any,
    * and if echoMode() is Normal.  See also @ref QLineEdit::copy.
    */
    virtual void slotCopy()       { copy(); }

    /**
    * Copies the marked text to the clipboard and deletes it
    * if there is any.  See also @ref QLineEdit::cut.
    */
    virtual void slotCut()        { cut(); }

    /**
    * Inserts the text in the clipboard at the current cursor position,
    * deleting any previously marked text. See also @ref QLineEdit::paste.
    */
    virtual void slotPaste()      { paste(); }

    /**
    * Sets the comepltion mode to KGlobal::CompletionNone
    */
    virtual void modeNone()   { setCompletionMode( KGlobal::CompletionNone ); }

    /**
    * Sets the comepltion mode to KGlobal::CompletionManual
    */
    virtual void modeManual() { setCompletionMode( KGlobal::CompletionMan );  }

    /**
    * Sets the comepltion mode to KGlobal::CompletionAuto
    */
    virtual void modeAuto()   { setCompletionMode( KGlobal::CompletionAuto ); }

    /**
    * Sets the comepltion mode to KGlobal::CompletionShell
    */
    virtual void modeShell()  { setCompletionMode( KGlobal::CompletionShell );}

    /**
    * Populates the context menu before it is displayed.
    */
    virtual void aboutToShowMenu();

    /**
    * Populates the sub menu before it is displayed.
    */
    virtual void aboutToShowSubMenu( int );

    /**
    * Deals with text changes and auto completion in this
    * widget.
    */
    virtual void entryChanged( const QString& );

    /**
    * Fills in the remaining text.
    */
    virtual void makeCompletion( const QString& );

    /*
    * Resets the completion object if it is deleted externally.
    */
    void completionDestroyed() { m_pCompObj = 0; }

    /*
    * Re-emitts the returnPressed signal with the current
    * text as its argument.
    */
    void slotReturnPressed();

protected:

    /**
    * Initializes variables.  Called from the constructors.
    */
    virtual void initialize();

    /*
    * Re-implemented from QLineEdit to filter key-events.
    */
    virtual void keyPressEvent( QKeyEvent * );

    /*
    * Re-implemented from QLineEdit to filter key-events.
    */
    virtual void mousePressEvent( QMouseEvent * );

    /*
    * Rotates the text on rotation events
    */
    void rotateText( const QString& );

    // Pointers to the context & sub menus.
    QPopupMenu *m_pContextMenu, *m_pSubMenu;
    // Pointer to the Completion object.
    KCompletion *m_pCompObj;

private :
    // Stores the completion key locally
    int m_iCompletionKey;
    // Stores the Rotate up key locally
    int m_iRotateUpKey;
    // stores the Rotate down key locally
    int m_iRotateDnKey;
    // Holds the location where the Mode
    // switcher item was inserted.
    int m_iSubMenuId;
    // Holds the length of the entry.
    int m_iPrevlen;
    // Holds the current cursor position.
    int m_iPrevpos;

    // Indicates whether the context menu is enabled
    // or disabled
    bool m_bShowContextMenu;
    // Indicates whether the mode switcher item will be
    // available in the context (popup) menu.
    bool m_bShowModeChanger;
    // Determines whether the completion object should be
    // deleted when this widget is destroyed.
    bool m_bAutoDelCompObj;
    // Determines whether this widget handles rotation signals
    // internally or not
    bool m_bHandleRotationSignal;
    // Determines whether this widget handles completion signals
    // internally or not
    bool m_bHandleCompletionSignal;
    // Determines whether this widget fires rotation signals
    bool m_bEmitRotation;
    // Determines whether this widget fires completion signals
    bool m_bEmitCompletion;

    // Stores the completion mode locally.
    KGlobal::Completion m_iCompletionMode;
};

#endif

Generated by: root@tantive.terraplex.com on Sun Feb 27 17:39:25 2000, using kdoc 2.0a33.