/* This file is part of the KDE libraries
Copyright (c) 2000 Dawit Alemayehu <adawit@kde.org>
2000 Carsten Pfeiffer <pfeiffer@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 <qlineedit.h>
#include <qcombobox.h>
#include <kcompletion.h>
class QListBoxItem;
class QLineEdit;
class KURL;
/**
* A combined button, line-edit and a popup list widget.
*
* @sect Detail
*
* This widget inherits from @ref 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 @ref KComboBox also emits a few
* more additional signals as well. The main ones are the
* @ref completion( const QString& ) and @ref textRotation( KeyBindgingType )
* 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 is intended to be used to trasverse through all
* possible matches whenever text completion results in multiple matches.
* The @ref returnPressed() and @ref returnPressed( const QString& )
* signal is emitted when the user presses the Enter/Return key.
*
* 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 KComboBox will by default handle the text rotation and completion
* events internally whenever 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 alternatively
* set the boolean parameter in the above methods 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 this widget is not editable ( i.e. select-only ), then only
* one completion mode, @p CompletionAuto, will work. All the other modes are
* simply ignored. The @p CompletionAuto mode in this case allows you to
* automatically select an item from the list by trying to match the pressed
* keycode with the first letter of the enteries in the combo box.
*
* @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 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>
*
* Note that you have to either delete the allocated completion object
* when you don't need it anymore, or call
* setAutoDeleteCompletionObject( true );
*
* Miscellaneous function calls:
*
* <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 );
* // Hide the context (popup) menu
* combo->setContextMenuEnabled( false );
* // Temporarly disable signal emition
* combo->disableSignals();
* // Default the all key-bindings to their system-wide settings.
* combo->useGlobalKeyBindings();
* </pre>
*
* @short An enhanced combo box.
* @author Dawit Alemayehu <adawit@kde.org>
*/
class KComboBox : public QComboBox, public KCompletionBase
{
Q_OBJECT
Q_PROPERTY( bool autoCompletion READ autoCompletion WRITE setAutoCompletion )
Q_PROPERTY( bool contextMenuEnabled READ isContextMenuEnabled WRITE setContextMenuEnabled )
public:
/**
* Construct 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 );
/**
* Construct a "read-write" or "read-only" combo box depending on
* the value of the first argument( @p 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();
/**
* Sets @p url into the edit field of the combobox. It uses
* @ref KURL::prettyURL() so that the url is properly decoded for
* displaying.
*/
void setEditURL( const KURL& url );
/**
* Inserts @p url at position @p index into the combobox. The item will
* be appended if @p index is negative. @ref KURL::prettyURL() is used
* so that the url is properly decoded for displaying.
*/
void insertURL( const KURL& url, int index = -1 );
/**
* Inserts @p url with the pixmap &p pixmap at position @p index into
* the combobox. The item will be appended if @p index is negative.
* @ref KURL::prettyURL() is used so that the url is properly decoded
* for displaying.
*/
void insertURL( const QPixmap& pixmap, const KURL& url, int index = -1 );
/**
* Replaces the item at position @p index with @p url.
* @ref KURL::prettyURL() is used so that the url is properly decoded
* for displaying.
*/
void changeURL( const KURL& url, int index );
/**
* Replaces the item at position @p index with @p url and pixmap @p pixmap.
* @ref KURL::prettyURL() is used so that the url is properly decoded
* for displaying.
*/
void changeURL( const QPixmap& pixmap, const KURL& url, int index );
/**
* Retreive the current cursor position.
*
* This method always returns a -1 if the combo-box is @em not
* editable (read-write).
*
* @return Current cursor position.
*/
int cursorPosition() const { return ( m_pEdit ) ? m_pEdit->cursorPosition() : -1; }
/**
* Re-implemented from @ref QComboBox.
*
* If @p 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 @p true if the current completion mode is set
* to automatic. See its more comprehensive replacement
* @ref completionMode().
*
* @return @p true when completion mode is automatic.
*/
bool autoCompletion() const { return completionMode() == KGlobalSettings::CompletionAuto; }
/**
* Enable or disable 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 @p true, show the context menu.
* @param showMode If @p true, show the mode changer.
*/
virtual void setContextMenuEnabled( bool showMenu );
/**
* Returns @p true when the context menu is enabled.
*
* @return @p true if context menu is enabled.
*/
bool isContextMenuEnabled() const { return m_bEnableMenu; }
/**
* Returns @p true if the combo-box is editable.
*
* @return @p true if combo is editable.
*/
bool isEditable() const { return editable(); }
/**
* Convenience method which iterates over all items and checks if
* any of them is equal to @p text.
*
* If @p text is an empty string, @p false
* is returned.
*
* @return @p true if an item with the string @p text is in the combobox.
*/
bool contains( const QString& text ) const;
/**
* By default, @ref KComboBox recognizes Key_Return and 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 equal to @p true to make @ref KComboBox
* stop these
* events. The signals will still be emitted of course.
*
* Only affects read-writable comboboxes.
*
* @see setTrapReturnKey()
*/
void setTrapReturnKey( bool trap );
/**
* @return @p true if keyevents of Key_Return or 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 * );
signals:
/**
* Emitted when the user presses the Enter key.
*
* Note that this signal is only
* emitted if this widget is editable.
*/
void returnPressed();
/**
* Emitted when the user presses
* the Enter 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 @em not available if this
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* Emitted when the text rotation key-bindings are pressed.
*
* The argument indic
* widget is non-editable or the completion mode is
* set to @p KGlobalSettings::CompletionNone.
*/
void completion( const QString& );
/**
* E