Source: kcombobox.h


Annotated List
Files
Globals
Hierarchy
Index
/* This file is part of the KDE libraries

   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 (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
   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 _KCOMBOBOX_H
#define _KCOMBOBOX_H

#include <qcombobox.h>
#include <qlineedit.h>
#include <qpopupmenu.h>
#include <qlistbox.h>

#include <kcompletion.h>


/**
 * A combined button, line-edit and a popup list widget.
 *
 * This widget inherits from QComboBox and implements
 * the following additional functionalities:  a completion
 * object that provides both automatic and manual text
 * completion as well as text rotation 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 KComboBox also emits a few
 * more additional signals as well.  The main ones being the
 * @p completion and @p rotation signals.  The completion signal
 * is intended to be connected to a slot that will assist the user
 * in filling out the remaining text while the rotation signals, both
 * @ref rotateUp and @ref rotateDown, are intended to be used to
 * transverse through some kind of list in opposing directions.
 * The @ref previousMatch and @ref nextMatch signals are used to
 * iterate through all possible matches whenever there are more than
 * one possible text completion matches.  And the @ref returnPressed
 * signals are emitted when the user presses the return key.
 *
 * This widget by default creates a completion object whenever you
 * invoke the member function @ref completionObject for the first
 * time.  You can also assign your own completion object through
 * @ref setCompletionObject function if you want to control the kind
 * of completion object that needs to be used.  Additionally, to make
 * this widget more functional, KComboBox will automatically handle the
 * iteration and completion signals internally when a completion object
 * is created through either one of the previously defined methods.  If
 * you do not need this feature, simply use @ref KCompletionBase::setHandleSignals
 * or the boolean paramter when calling @p setCompletionObject, to turn
 * it off.
 *
 * The default key-binding for completion and rotation is determined
 * from the global settings in @ref KStdAccel.  However, these values
 * can be set locally to override these global settings.  Simply invoking
 * @ref useGlobalSettings then allows you to immediately default the
 * bindings back to the global settings again.  You can also default
 * the key-bindings by simply invoking the @ref setXXXKey method without
 * any argumet.  Note that if this widget is not editable, i.e. it is
 * constructed as a "select-only" widget, then only one completion mode,
 * CompletionAuto, is allowed.  All the other modes are simply ignored.
 * The CompletionAuto mode in this case allows you to automatically select
 * an item from the list that matches the key-code of the first key pressed.
 *
 * @sect Example:
 *
 * To enable the basic completion feature :
 *
 * <pre>
 * KComboBox *combo = new KComboBox( true, this, "mywidget" );
 * KCompletion *comp = combo->completionObject();
 * // Connect to the return pressed signal - optional
 * connect(combo,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&));
 * </pre>
 *
 * To use a customized completion objects or your
 * own completion object :
 *
 * <pre>
 * KComboBox *combo = new KComboBox( this,"mywidget" );
 * KURLCompletion *comp = new KURLCompletion();
 * combo->setCompletionObject( comp );
 * // Connect to the return pressed signal - optional
 * connect(combo,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&));
 * </pre>
 *
 * Other miscelanous functions :
 *
 * <pre>
 * // Tell the widget not to handle completion and rotation
 * combo->setHandleSignals( false );
 * // set your own completion key for manual completions.
 * combo->setKeyBinding( KCompletionBase::TextCompletion, Qt::End );
 * // Shows the context (popup) menu
 * combo->setEnableContextMenu( false );
 * // Temporarly disable signal emition
 * combo->disableSignals();
 * // Default the key-bindings to system settings.
 * combo->useGlobalKeyBindings();
 * </pre>
 *
 * @short An enhanced combo box.
 * @author Dawit Alemayehu <adawit@kde.org>
 */
class KComboBox : public QComboBox, public KCompletionBase
{
  Q_OBJECT

public:
	
    /**
    * Constructs a read-only or rather select-only combo box with a parent object
    * and a name.
    *
    * @param parent the parent object of this widget
    * @param name the name of this widget
    */
    KComboBox( QWidget *parent=0, const char *name=0 );

    /**
    * Constructs a "read-write" or "read-only" combo box depending on the value of
    * the first argument( bool rw ) with a parent, a name.
    *
    * @param rw when @p true widget will be editable.
    * @param parent the parent object of this widget.
    * @param name the name of this widget.
    */
    KComboBox( bool rw, QWidget *parent=0, const char *name=0 );

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

    /**
    * Returns the current cursor position.
    *
    * This method always returns a -1 if the combo-box is NOT
    * editable (read-write).
    *
    * @return current cursor position.
    */
    int cursorPosition() const { return ( m_pEdit ) ? m_pEdit->cursorPosition() : -1; }

    /**
    * Re-implemented from QComboBox.
    *
    * If true, the completion mode will be set to automatic.
    * Otherwise, it is defaulted to the gloabl setting.  This
    * methods has been replaced by the more comprehensive @ref
    * setCompletionMode.
    *
    * @param autocomplete flag to enable/disable automatic completion mode.
    */
    virtual void setAutoCompletion( bool autocomplete );

    /**
    * Re-implemented from QComboBox.
    *
    * Returns true if the current completion mode is set
    * to automatic.  See its more comprehensive replacement
    * @ref completionMode.
    *
    * @return true when completion mode is automatic.
    */
    bool autoCompletion() const { return completionMode() == KGlobalSettings::CompletionAuto; }

    /**
    * Enables or disables the popup (context) menu.
    *
    * This method only works if this widget is editable, i.e.
    * read-write and allows you to enable/disable the context
    * menu.  It does nothing if invoked for a none-editable
    * combo-box.  Note that by default the mode changer item
    * is made visiable whenever the context menu is enabled.
    * Use * @ref hideModechanger() if you want to hide this
    * item.    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.
    */
    virtual void setEnableContextMenu( bool showMenu );

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

    /**
    * Returns true if the combo-box is editable.
    *
    * @return true if combo is editable.
    */
    bool isEditable() const { return (m_pEdit!= 0); }

signals:
    /**
    * This signal is emitted when the user presses
    * the return key.  Note that this signal is only
    * emitted if this widget is editable.
    */
    void returnPressed();

    /**
    * This signal is emitted when the user presses
    * the return key.  The argument is the current
    * text being edited.  This signal is just like
    * @ref returnPressed() except it contains the
    * current text as its argument.
    *
    * Note that this signal is only emitted if this
    * widget is editable.
    */
    void returnPressed( const QString& );

    /**
    * This signal is emitted when the completion key
    * is pressed.  The argument is the current text
    * being edited.
    *
    * Note that this signal is NOT available if this
    * widget is non-editable or the completion mode is
    * set to KGlobalSettings::CompletionNone.
    */
    void completion( const QString& );

    /**
    * Signal emitted when the key-binding set for
    * the next text match is pressed.
    *
    * This signal is emitted when the key-binding used for
    * iterating through all possible matches is invoked.
    * It is usually used in the manual completion modes to
    * iterate through the multiple matches
    *
    * Note that this signal is NOT emitted if the completion
    * mode is set to CompletionNone or EchoMode is NOT normal.
    */
    void previousMatch( KeyBindingType /* type */ );

    /**
    * Signal emitted when the key-binding set for
    * the previous text match is pressed.
    *
    * See @ref KCompletionBase::setKeyBinding.
    *
    * Note that this signal is NOT emitted if the completion
    * mode is set to CompletionNone or EchoMode is NOT normal.
    */
    void nextMatch( KeyBindingType /* type */ );

    /**
    * This signal is emitted when the rotate up key is pressed.
    *
    * Note that this signal is NOT available if this widget is non-editable
    * or the completion mode is set to KGlobalSettings::CompletionNone.
    */
    void rotateUp( KeyBindingType /* type */ );

    /**
    * Signal emitted when the rotate down key is pressed.
    *
    * Note that this signal is NOT available if this widget is non-editable
    * or the completion mode is set to KGlobalSettings::CompletionNone.
    */
    void rotateDown( KeyBindingType /* type */ );

public slots:

    /**
    * Iterates through all possible matches of the completed text or
    * the history list.
    *
    * Depending on the argument this function either iterates through
    * the history list of this widget or the all possible matches in
    * whenever multiple matches result from a text completion request.
    * This function will have no effect if the previous completion
    * resulted in a single match.
    *
    * @param type the key-binding invoked.
    */
    void rotateText( KeyBindingType /* type */ );


protected slots:

    /**
    *  changes the completion mode.
    *
    * This slot sets the completion mode to the one
    * requested by the end user through the popup
    * menu.
    *
    * @param itemID the completion mode type
    */
    virtual void selectedItem( int );

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

    /**
    * Deals with highlighting the seleted item when
    * return is pressed in the list box (editable-mode only).
    */
    virtual void itemSelected( QListBoxItem* );

    /**
    * Completes text according to the completion mode.
    *
    * Note: this method is @p not invoked if the completion mode is
    * set to CompletionNone.  Also if the mode is set to @p CompletionShell
    * and multiple matches are found, this method will complete the
    * text to the first match with a beep to inidicate that there are
    * more matches.  Then any successive completion key event iterates
    * through the remaining matches.  This way the rotation functionality
    * is left to iterate through the list as usual.
    */
    virtual void makeCompletion( const QString& );

protected:

    /**
    * Initializes the variables upon construction.
    */
    virtual void init();

    /**
    * 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 is not affected.
    *
    * See @ref QComboBox::keyPressEvent.
    */
    virtual void keyPressEvent ( QKeyEvent* );

    /**
    * Re-implemented for internal reasons.  API is not affected.
    *
    * See @ref QComboBox::mousePressEvent.
    */
    virtual bool eventFilter( QObject *, QEvent * );

private :
    // Flag that indicates whether we enable/disable
    // the context (popup) menu.
    bool m_bEnableMenu;
    // Pointer to the line editor.
    QLineEdit* m_pEdit;
    // Context Menu items.
    QPopupMenu *m_pContextMenu;
    // Holds the current text on rotation.  Allows us
    // to emulate *nix shell like rotation where you
    // would not loose what you typed even if you rotate
    // before finishing it :)
    QString m_strCurrentText;
	
    class KComboBoxPrivate;
    KComboBoxPrivate *d;
};
#endif

Generated by: root@porky.devel.redhat.com on Wed May 10 08:56:43 2000, using kdoc 2.0a35.