home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / klineedit.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-14  |  20.2 KB  |  657 lines
  1. /*  This file is part of the KDE libraries
  2.  
  3.     This class was originally inspired by Torben Weis'
  4.     fileentry.cpp for KFM II.
  5.  
  6.     Copyright (C) 1997 Sven Radej <sven.radej@iname.com>
  7.     Copyright (c) 1999 Patrick Ward <PAT_WARD@HP-USA-om5.om.hp.com>
  8.     Copyright (c) 1999 Preston Brown <pbrown@kde.org>
  9.  
  10.     Completely re-designed:
  11.     Copyright (c) 2000,2001 Dawit Alemayehu <adawit@kde.org>
  12.  
  13.     This library is free software; you can redistribute it and/or
  14.     modify it under the terms of the GNU Lesser General Public
  15.     License (LGPL) as published by the Free Software Foundation;
  16.     either version 2 of the License, or (at your option) any later
  17.     version.
  18.  
  19.     This library is distributed in the hope that it will be useful,
  20.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  21.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  22.     Lesser General Public License for more details.
  23.  
  24.     You should have received a copy of the GNU Lesser General Public License
  25.     along with this library; see the file COPYING.LIB.  If not, write to
  26.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  27.     Boston, MA 02110-1301, USA.
  28. */
  29.  
  30. #ifndef _KLINEEDIT_H
  31. #define _KLINEEDIT_H
  32.  
  33. #include <qlineedit.h>
  34. #include <kcompletion.h>
  35.  
  36. class QPopupMenu;
  37.  
  38. class KCompletionBox;
  39. class KURL;
  40.  
  41. /**
  42.  * An enhanced QLineEdit widget for inputting text.
  43.  *
  44.  * \b Detail \n
  45.  *
  46.  * This widget inherits from QLineEdit and implements the following
  47.  * additional functionalities: a completion object that provides both
  48.  * automatic and manual text completion as well as multiple match iteration
  49.  * features, configurable key-bindings to activate these features and a
  50.  * popup-menu item that can be used to allow the user to set text completion
  51.  * modes on the fly based on their preference.
  52.  *
  53.  * To support these new features KLineEdit also emits a few more
  54.  * additional signals.  These are: completion( const QString& ),
  55.  * textRotation( KeyBindingType ), and returnPressed( const QString& ).
  56.  * The completion signal can be connected to a slot that will assist the
  57.  * user in filling out the remaining text.  The text rotation signal is
  58.  * intended to be used to iterate through the list of all possible matches
  59.  * whenever there is more than one match for the entered text.  The
  60.  * @p returnPressed( const QString& ) signals are the same as QLineEdit's
  61.  * except it provides the current text in the widget as its argument whenever
  62.  * appropriate.
  63.  *
  64.  * This widget by default creates a completion object when you invoke
  65.  * the completionObject( bool ) member function for the first time or
  66.  * use setCompletionObject( KCompletion*, bool ) to assign your own
  67.  * completion object.  Additionally, to make this widget more functional,
  68.  * KLineEdit will by default handle the text rotation and completion
  69.  * events internally when a completion object is created through either one
  70.  * of the methods mentioned above.  If you do not need this functionality,
  71.  * simply use @p setHandleSignals( bool ) or set the boolean parameter in
  72.  * the above functions to false.
  73.  *
  74.  * The default key-bindings for completion and rotation is determined
  75.  * from the global settings in KStdAccel. These values, however, can
  76.  * be overridden locally by invoking @p setKeyBinding(). You can easily
  77.  * revert these settings back to the default by simply calling
  78.  * @p useGlobalSettings(). An alternate method would be to default
  79.  * individual key-bindings by using setKeyBinding() with the default
  80.  * second argument.
  81.  *
  82.  * If @p EchoMode for this widget is set to something other than @p QLineEdit::Normal,
  83.  * the completion mode will always be defaulted to KGlobalSettings::CompletionNone.
  84.  * This is done purposefully to guard against protected entries such as passwords being
  85.  * cached in KCompletion's list. Hence, if the @p EchoMode is not QLineEdit::Normal, the
  86.  * completion mode is automatically disabled.
  87.  *
  88.  * A read-only KLineEdit will have the same background color as a
  89.  * disabled KLineEdit, but its foreground color will be the one used
  90.  * for the read-write mode. This differs from QLineEdit's implementation
  91.  * and is done to give visual distinction between the three different modes:
  92.  * disabled, read-only, and read-write.
  93.  *
  94.  * \b Usage \n
  95.  *
  96.  * To enable the basic completion feature :
  97.  *
  98.  * \code
  99.  * KLineEdit *edit = new KLineEdit( this, "mywidget" );
  100.  * KCompletion *comp = edit->completionObject();
  101.  * // Connect to the return pressed signal - optional
  102.  * connect(edit,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&)));
  103.  * \endcode
  104.  *
  105.  * To use a customized completion objects or your
  106.  * own completion object :
  107.  *
  108.  * \code
  109.  * KLineEdit *edit = new KLineEdit( this,"mywidget" );
  110.  * KURLCompletion *comp = new KURLCompletion();
  111.  * edit->setCompletionObject( comp );
  112.  * // Connect to the return pressed signal - optional
  113.  * connect(edit,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&)));
  114.  * \endcode
  115.  *
  116.  * Note if you specify your own completion object you have to either delete
  117.  * it when you don't need it anymore, or you can tell KLineEdit to delete it
  118.  * for you:
  119.  * \code
  120.  * edit->setAutoDeleteCompletionObject( true );
  121.  * \endcode
  122.  *
  123.  * <b>Miscellaneous function calls :</b>\n
  124.  *
  125.  * \code
  126.  * // Tell the widget to not handle completion and iteration automatically.
  127.  * edit->setHandleSignals( false );
  128.  *
  129.  * // Set your own key-bindings for a text completion mode.
  130.  * edit->setKeyBinding( KCompletionBase::TextCompletion, Qt::End );
  131.  *
  132.  * // Hide the context (popup) menu
  133.  * edit->setContextMenuEnabled( false );
  134.  *
  135.  * // Temporarily disable signal (both completion & iteration) emitions
  136.  * edit->disableSignals();
  137.  *
  138.  * // Default the key-bindings back to the default system settings.
  139.  * edit->useGlobalKeyBindings();
  140.  * \endcode
  141.  *
  142.  * @author Dawit Alemayehu <adawit@kde.org>
  143.  */
  144.  
  145. class KDEUI_EXPORT KLineEdit : public QLineEdit, public KCompletionBase
  146. {
  147.     friend class KComboBox;
  148.  
  149.     Q_OBJECT
  150.     Q_PROPERTY( bool contextMenuEnabled READ isContextMenuEnabled WRITE setContextMenuEnabled )
  151.     Q_PROPERTY( bool urlDropsEnabled READ isURLDropsEnabled WRITE setURLDropsEnabled )
  152.     Q_PROPERTY( bool trapEnterKeyEvent READ trapReturnKey WRITE setTrapReturnKey )
  153.     Q_PROPERTY( bool enableSqueezedText READ isSqueezedTextEnabled WRITE setEnableSqueezedText )
  154.     // @since 3.5.4
  155.     Q_PROPERTY( QString clickMessage READ clickMessage WRITE setClickMessage )
  156.  
  157. public:
  158.  
  159.     /**
  160.      * Constructs a KLineEdit object with a default text, a parent,
  161.      * and a name.
  162.      *
  163.      * @param string Text to be shown in the edit widget.
  164.      * @param parent The parent object of this widget.
  165.      * @param name the name of this widget
  166.      */
  167.     KLineEdit( const QString &string, QWidget *parent, const char *name = 0 );
  168.  
  169.     /**
  170.      * Constructs a KLineEdit object with a parent and a name.
  171.      *
  172.      * @param parent The parent object of this widget.
  173.      * @param name The name of this widget.
  174.      */
  175.     KLineEdit ( QWidget *parent=0, const char *name=0 );
  176.  
  177.     /**
  178.      *  Destructor.
  179.      */
  180.     virtual ~KLineEdit ();
  181.  
  182.     /**
  183.      * Sets @p url into the lineedit. It uses KURL::prettyURL() so
  184.      * that the url is properly decoded for displaying.
  185.      */
  186.     void setURL( const KURL& url );
  187.  
  188.     /**
  189.      * Puts the text cursor at the end of the string.
  190.      *
  191.      * This method is deprecated.  Use QLineEdit::end()
  192.      * instead.
  193.      *
  194.      * @deprecated
  195.      * QLineEdit::end()
  196.      */
  197.     void cursorAtEnd() { end( false ); }
  198.  
  199.     /**
  200.      * Re-implemented from KCompletionBase for internal reasons.
  201.      *
  202.      * This function is re-implemented in order to make sure that
  203.      * the EchoMode is acceptable before we set the completion mode.
  204.      *
  205.      * See KCompletionBase::setCompletionMode
  206.      */
  207.     virtual void setCompletionMode( KGlobalSettings::Completion mode );
  208.  
  209.    /**
  210.     * Enables/disables the popup (context) menu.
  211.     *
  212.     * Note that when this function is invoked with its argument
  213.     * set to @p true, then both the context menu and the completion
  214.     * menu item are enabled.  If you do not want to the completion
  215.     * item to be visible simply invoke hideModechanger() right
  216.     * after calling this method.  Also by default, the context
  217.     * menu is automatically created if this widget is editable. Thus
  218.     * you need to call this function with the argument set to false
  219.     * if you do not want this behavior.
  220.     *
  221.     * @param showMenu If @p true, show the context menu.
  222.     */
  223.     virtual void setContextMenuEnabled( bool showMenu ) {  m_bEnableMenu = showMenu; }
  224.  
  225.     /**
  226.      * Returns @p true when the context menu is enabled.
  227.      */
  228.     bool isContextMenuEnabled() const { return m_bEnableMenu; }
  229.  
  230.     /**
  231.      * Enables/Disables handling of URL drops. If enabled and the user
  232.      * drops an URL, the decoded URL will be inserted. Otherwise the default
  233.      * behavior of QLineEdit is used, which inserts the encoded URL.
  234.      *
  235.      * @param enable If @p true, insert decoded URLs
  236.      */
  237.     void setURLDropsEnabled( bool enable );
  238.  
  239.     /**
  240.      * Returns @p true when decoded URL drops are enabled
  241.      */
  242.     bool isURLDropsEnabled() const;
  243.  
  244.     /**
  245.      * By default, KLineEdit recognizes @p Key_Return and @p Key_Enter and emits
  246.      * the returnPressed() signals, but it also lets the event pass,
  247.      * for example causing a dialog's default-button to be called.
  248.      *
  249.      * Call this method with @p trap = @p true to make @p KLineEdit stop these
  250.      * events. The signals will still be emitted of course.
  251.      *
  252.      * @see trapReturnKey()
  253.      */
  254.     void setTrapReturnKey( bool trap );
  255.  
  256.     /**
  257.      * @returns @p true if keyevents of @p Key_Return or
  258.      * @p Key_Enter will be stopped or if they will be propagated.
  259.      *
  260.      * @see setTrapReturnKey ()
  261.      */
  262.     bool trapReturnKey() const;
  263.  
  264.     /**
  265.      * Re-implemented for internal reasons.  API not affected.
  266.      *
  267.      */
  268.     virtual bool eventFilter( QObject *, QEvent * );
  269.  
  270.     /**
  271.      * @returns the completion-box, that is used in completion mode
  272.      * KGlobalSettings::CompletionPopup.
  273.      * This method will create a completion-box if none is there, yet.
  274.      *
  275.      * @param create Set this to false if you don't want the box to be created
  276.      *               i.e. to test if it is available.
  277.      */
  278.     KCompletionBox * completionBox( bool create = true );
  279.  
  280.     /**
  281.      * Reimplemented for internal reasons, the API is not affected.
  282.      */
  283.     virtual void setCompletionObject( KCompletion *, bool hsig = true );
  284.  
  285.     /**
  286.      * Reimplemented for internal reasons, the API is not affected.
  287.      */
  288.     virtual void copy() const;
  289.  
  290.     /**
  291.      * Enable text squeezing whenever the supplied text is too long.
  292.      * Only works for "read-only" mode.
  293.      *
  294.      * Note that once text squeezing is enabled, QLineEdit::text()
  295.      * and QLineEdit::displayText() return the squeezed text. If
  296.      * you want the original text, use @ref originalText.
  297.      *
  298.      * @see QLineEdit
  299.      * @since 3.2
  300.      */
  301.     void setEnableSqueezedText( bool enable );
  302.  
  303.     /**
  304.      * Returns true if text squeezing is enabled.
  305.      * This is only valid when the widget is in read-only mode.
  306.      *
  307.      * @since 3.2
  308.      */
  309.     bool isSqueezedTextEnabled() const;
  310.  
  311.     /**
  312.      * Returns the original text if text squeezing is enabled.
  313.      * If the widget is not in "read-only" mode, this function
  314.      * returns the same thing as QLineEdit::text().
  315.      *
  316.      * @see QLineEdit
  317.      * @since 3.2
  318.      */
  319.     QString originalText() const;
  320.  
  321.     /**
  322.      * Set the completion-box to be used in completion mode
  323.      * KGlobalSettings::CompletionPopup.
  324.      * This will do nothing if a completion-box already exists.
  325.      *
  326.      * @param box The KCompletionBox to set
  327.      * @since 3.4
  328.     */
  329.     void setCompletionBox( KCompletionBox *box );
  330.  
  331.     /**
  332.      * This makes the line edit display a grayed-out hinting text as long as
  333.      * the user didn't enter any text. It is often used as indication about
  334.      * the purpose of the line edit.
  335.      * @since 3.5.4
  336.     */
  337.     void setClickMessage( const QString &msg );
  338.  
  339.     /**
  340.      * @return the message set with setClickMessage
  341.      * @since 3.5.4
  342.     */
  343.     QString clickMessage() const;
  344.  
  345. signals:
  346.  
  347.     /**
  348.      * Emitted whenever the completion box is activated.
  349.      * @since 3.1
  350.      */
  351.     void completionBoxActivated (const QString &);
  352.  
  353.     /**
  354.      * Emitted when the user presses the return key.
  355.      *
  356.      *  The argument is the current text.  Note that this
  357.      * signal is @em not emitted if the widget's @p EchoMode is set to
  358.      * QLineEdit::EchoMode.
  359.      */
  360.     void returnPressed( const QString& );
  361.  
  362.     /**
  363.      * Emitted when the completion key is pressed.
  364.      *
  365.      * Please note that this signal is @em not emitted if the
  366.      * completion mode is set to @p CompletionNone or @p EchoMode is
  367.      * @em normal.
  368.      */
  369.     void completion( const QString& );
  370.  
  371.     /**
  372.      * Emitted when the shortcut for substring completion is pressed.
  373.      */
  374.     void substringCompletion( const QString& );
  375.  
  376.     /**
  377.      * Emitted when the text rotation key-bindings are pressed.
  378.      *
  379.      * The argument indicates which key-binding was pressed.
  380.      * In KLineEdit's case this can be either one of two values:
  381.      * PrevCompletionMatch or NextCompletionMatch. See
  382.      * @p setKeyBinding for details.
  383.      *
  384.      * Note that this signal is @em not emitted if the completion
  385.      * mode is set to @p KGlobalSettings::CompletionNone or
  386.      * @p echoMode() is @em not  normal.
  387.      */
  388.     void textRotation( KCompletionBase::KeyBindingType );
  389.  
  390.     /**
  391.      * Emitted when the user changed the completion mode by using the
  392.      * popupmenu.
  393.      */
  394.     void completionModeChanged( KGlobalSettings::Completion );
  395.  
  396.     /**
  397.      * Emitted before the context menu is displayed.
  398.      *
  399.      * The signal allows you to add your own entries into the
  400.      * the context menu that is created on demand.
  401.      *
  402.      * NOTE: Do not store the pointer to the QPopupMenu
  403.      * provided through since it is created and deleted
  404.      * on demand.
  405.      *
  406.      * @param p the context menu about to be displayed
  407.      */
  408.     void aboutToShowContextMenu( QPopupMenu * p );
  409.  
  410. public slots:
  411.  
  412.     /**
  413.      * Re-implemented for internal reasons. API not changed.
  414.      */
  415.     virtual void setReadOnly(bool);
  416.  
  417.     /**
  418.      * Iterates through all possible matches of the completed text or
  419.      * the history list.
  420.      *
  421.      * This function simply iterates over all possible matches in case
  422.      * multimple matches are found as a result of a text completion request.
  423.      * It will have no effect if only a single match is found.
  424.      *
  425.      * @param type The key-binding invoked.
  426.      */
  427.     void rotateText( KCompletionBase::KeyBindingType type );
  428.  
  429.     /**
  430.      * See KCompletionBase::setCompletedText.
  431.      */
  432.     virtual void setCompletedText( const QString& );
  433.  
  434.     /**
  435.      * Sets @p items into the completion-box if completionMode() is
  436.      * CompletionPopup. The popup will be shown immediately.
  437.      *
  438.      * @param items list of completion matches to be shown in the completion box.
  439.      */
  440.     void setCompletedItems( const QStringList& items );
  441.  
  442.     /**
  443.      * Same as the above function except it allows you to temporarily
  444.      * turn off text completion in CompletionPopupAuto mode.
  445.      *
  446.      * TODO: Merge with above function in KDE 4.
  447.      * TODO: Does that make this or the above @deprecated ?
  448.      *
  449.      * @param items list of completion matches to be shown in the completion box.
  450.      * @param autoSuggest true if you want automatic text completion (suggestion) enabled.
  451.      */
  452.     void setCompletedItems( const QStringList& items, bool autoSuggest );
  453.  
  454.     /**
  455.      * Reimplemented to workaround a buggy QLineEdit::clear()
  456.      * (changing the clipboard to the text we just had in the lineedit)
  457.      */
  458.     virtual void clear();
  459.  
  460.     /**
  461.      * Squeezes @p text into the line edit.
  462.      * This can only be used with read-only line-edits.
  463.      * @since 3.1
  464.      */
  465.     void setSqueezedText( const QString &text);
  466.  
  467.     /**
  468.      * Re-implemented to enable text squeezing. API is not affected.
  469.      */
  470.     virtual void setText ( const QString& );
  471.  
  472.  
  473. protected slots:
  474.  
  475.     /**
  476.     * Completes the remaining text with a matching one from
  477.     * a given list.
  478.     */
  479.     virtual void makeCompletion( const QString& );
  480.  
  481.     /**
  482.      * @deprecated.  Will be removed in the next major release!
  483.      */
  484.     void slotAboutToShow() {}
  485.  
  486.     /**
  487.      * @deprecated.  Will be removed in the next major release!
  488.      */
  489.     void slotCancelled() {}
  490.  
  491.     /**
  492.      * Resets the current displayed text.
  493.      * Call this function to revert a text completion if the user
  494.      * cancels the request. Mostly applies to popup completions.
  495.      */
  496.     void userCancelled(const QString & cancelText);
  497.  
  498. protected:
  499.  
  500.     /**
  501.     * Re-implemented for internal reasons.  API not affected.
  502.     *
  503.     * See QLineEdit::resizeEvent().
  504.     */
  505.     virtual void resizeEvent( QResizeEvent * );
  506.  
  507.     /**
  508.     * Re-implemented for internal reasons.  API not affected.
  509.     *
  510.     * See QLineEdit::keyPressEvent().
  511.     */
  512.     virtual void keyPressEvent( QKeyEvent * );
  513.  
  514.     /**
  515.     * Re-implemented for internal reasons.  API not affected.
  516.     *
  517.     * See QLineEdit::mousePressEvent().
  518.     */
  519.     virtual void mousePressEvent( QMouseEvent * );
  520.  
  521.     /**
  522.     * Re-implemented for internal reasons.  API not affected.
  523.     *
  524.     * See QWidget::mouseDoubleClickEvent().
  525.     */
  526.     virtual void mouseDoubleClickEvent( QMouseEvent * );
  527.  
  528.     /**
  529.     * Re-implemented for internal reasons.  API not affected.
  530.     *
  531.     * See QLineEdit::mouseReleaseEvent().
  532.     */
  533.     virtual void mouseReleaseEvent( QMouseEvent * );
  534.  
  535.     /**
  536.     * Re-implemented for internal reasons.  API not affected.
  537.     *
  538.     * See QLineEdit::contextMenuEvent().
  539.     */
  540.     virtual void contextMenuEvent( QContextMenuEvent * );
  541.  
  542.     /**
  543.     * Re-implemented for internal reasons.  API not affected.
  544.     *
  545.     * See QLineEdit::createPopupMenu().
  546.     */
  547.     virtual QPopupMenu *createPopupMenu();
  548.  
  549.     /**
  550.     * Re-implemented for internal reasons.  API not affected.
  551.     *
  552.     * See QFrame::drawContents().
  553.     */
  554.     virtual void drawContents( QPainter *p );
  555.  
  556.     /**
  557.     * Re-implemented to handle URI drops.
  558.     *
  559.     * See QLineEdit::dropEvent().
  560.     */
  561.     virtual void dropEvent( QDropEvent * );
  562.  
  563.     /*
  564.     * This function simply sets the lineedit text and
  565.     * highlights the text appropriately if the boolean
  566.     * value is set to true.
  567.     *
  568.     * @param text
  569.     * @param marked
  570.     */
  571.     virtual void setCompletedText( const QString& /*text*/, bool /*marked*/ );
  572.  
  573.  
  574.     /**
  575.      * Sets the widget in userSelection mode or in automatic completion
  576.      * selection mode. This changes the colors of selections.
  577.      */
  578.     void setUserSelection( bool userSelection );
  579.  
  580.     /**
  581.      * Reimplemented for internal reasons, the API is not affected.
  582.      */
  583.     virtual void create( WId = 0, bool initializeWindow = true,
  584.                          bool destroyOldWindow = true );
  585.  
  586.     /**
  587.     * Re-implemented for internal reasons.  API not affected.
  588.     *
  589.     * See QLineEdit::focusInEvent().
  590.     */
  591.     virtual void focusInEvent( QFocusEvent* );
  592.  
  593.     /**
  594.     * Re-implemented for internal reasons.  API not affected.
  595.     *
  596.     * See QLineEdit::focusOutEvent().
  597.     */
  598.     virtual void focusOutEvent( QFocusEvent* );
  599.  
  600.     /**
  601.      * Whether in current state text should be auto-suggested
  602.      * @since 3.4
  603.     */
  604.     bool autoSuggest() const;
  605.  
  606. private slots:
  607.     void completionMenuActivated( int id );
  608.     void tripleClickTimeout();  // resets possibleTripleClick
  609.     void slotRestoreSelectionColors();
  610.     void setTextWorkaround( const QString& text );
  611.  
  612. private:
  613.  
  614.     // Constants that represent the ID's of the popup menu.
  615.     enum MenuID
  616.     {
  617.         Default = 42,
  618.         NoCompletion,
  619.         AutoCompletion,
  620.         ShellCompletion,
  621.         PopupCompletion,
  622.         ShortAutoCompletion,
  623.         PopupAutoCompletion
  624.     };
  625.  
  626.     /**
  627.      * Initializes variables.  Called from the constructors.
  628.      */
  629.     void init();
  630.  
  631.     bool copySqueezedText( bool clipboard ) const;
  632.  
  633.     /**
  634.      * Checks whether we should/should not consume a key used as
  635.      * an accelerator.
  636.      */
  637.     bool overrideAccel (const QKeyEvent* e);
  638.  
  639.     /**
  640.      * Properly sets the squeezed text whenever the widget is
  641.      * created or resized.
  642.      */
  643.     void setSqueezedText ();
  644.  
  645.     bool m_bEnableMenu;
  646.  
  647.     bool possibleTripleClick;  // set in mousePressEvent, deleted in tripleClickTimeout
  648.  
  649. protected:
  650.     virtual void virtual_hook( int id, void* data );
  651. private:
  652.     class KLineEditPrivate;
  653.     KLineEditPrivate *d;
  654. };
  655.  
  656. #endif
  657.