/* This file Copyright (C) 2003 Michael 'Mickey' Lauer is part of the Copyright (C) 2000 Carsten Pfeiffer Opie Project Copyright (C) 2000 Dawit Alemayehu =. Originally part of the KDE projects .=l.            .>+-=  _;:,     .>    :=|. This program is free software; you can .> <`_,   >  .   <= redistribute it and/or modify it under :`=1 )Y*s>-.--   : the terms of the GNU Library General Public .="- .-=="i,     .._ License as published by the Free Software  - .   .-<_>     .<> Foundation; either version 2 of the License,      ._= =}       : or (at your option) any later version.     .%`+i>       _;_.     .i_,=:_.      -`: 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 OCOMBOBOX_H #define OCOMBOBOX_H /* QT */ #include /* OPIE */ #include #include #include /* FORWARDS */ class QListBoxItem; class QPopupMenu; class OCompletionBox; typedef QString OURL; /** * 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 OComboBox also emits a few * more additional signals as well. The main ones are the * @ref completion( const QString& ) and @ref textRotation( KeyBindingType ) * 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 traverse 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( OCompletion*, bool ) to assign your * own completion object. Additionally, to make this widget more functional, * OComboBox 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 OCompletionBase::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 OStdAccel. These values, however, * can be overriden locally by invoking @ref OCompletionBase::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 Useage * * To enable the basic completion feature: * * 
 * OComboBox *combo = new OComboBox( true, this, "mywidget" );
 * OCompletion *comp = combo->completionObject();
 * // Connect to the return pressed signal - optional
 * connect(combo,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&));
 *
* * To use your own completion object: * * 
 * OComboBox *combo = new OComboBox( this,"mywidget" );
 * OURLCompletion *comp = new OURLCompletion();
 * combo->setCompletionObject( comp );
 * // Connect to the return pressed signal - optional
 * connect(combo,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&));
 *
* * 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: * * 
 * // Tell the widget not to handle completion and rotation
 * combo->setHandleSignals( false );
 * // Set your own completion key for manual completions.
 * combo->setKeyBinding( OCompletionBase::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();
 *
* * @short An enhanced combo box. * @author Dawit Alemayehu */ class OComboBox : public QComboBox, public OCompletionBase { Q_OBJECT //Q_PROPERTY( bool autoCompletion READ autoCompletion WRITE setAutoCompletion ) //Q_PROPERTY( bool contextMenuEnabled READ isContextMenuEnabled WRITE setContextMenuEnabled ) //Q_PROPERTY( bool urlDropsEnabled READ isURLDropsEnabled WRITE setURLDropsEnabled ) 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 */ OComboBox( QWidget *parent=0, const char *name=0 ); /** * Constructs 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. */ OComboBox( bool rw, QWidget *parent=0, const char *name=0 ); /** * Destructor. */ virtual ~OComboBox(); /** * Sets @p url into the edit field of the combobox. It uses * @ref OURL::prettyURL() so that the url is properly decoded for * displaying. */ //void setEditURL( const OURL& url ); /** * Inserts @p url at position @p index into the combobox. The item will * be appended if @p index is negative. @ref OURL::prettyURL() is used * so that the url is properly decoded for displaying. */ //void insertURL( const OURL& 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 OURL::prettyURL() is used so that the url is properly decoded * for displaying. */ //void insertURL( const QPixmap& pixmap, const OURL& url, int index = -1 ); /** * Replaces the item at position @p index with @p url. * @ref OURL::prettyURL() is used so that the url is properly decoded * for displaying. */ //void changeURL( const OURL& url, int index ); /** * Replaces the item at position @p index with @p url and pixmap @p pixmap. * @ref OURL::prettyURL() is used so that the url is properly decoded * for displaying. */ //void changeURL( const QPixmap& pixmap, const OURL& url, int index ); /** * Returns 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 ( lineEdit() ) ? lineEdit()->cursorPosition() : -1; } /** * Re-implemented from @ref QComboBox. * * If @p true, the completion mode will be set to automatic. * Otherwise, it is defaulted to the global setting. This * method 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() == OGlobalSettings::CompletionAuto; } /** * Enables 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. */ 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 QComboBox 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 */ //bool isURLDropsEnabled() const; /** * 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, OComboBox 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 true to make OComboBox * 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 * ); /** * @returns the completion-box, that is used in completion mode * @ref OGlobalSettings::CompletionPopup and @ref OGlobalSettings::CompletionPopupAuto. * This method will create a completion-box by calling * @ref OLineEdit::completionBox, if none is there, yet. * * @param create Set this to false if you don't want the box to be created * i.e. to test if it is available. */ OCompletionBox * completionBox( bool create = true ); virtual void setLineEdit( OLineEdit * ); 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 OGlobalSettings::CompletionNone. */ void completion( const QString& ); /** * Emitted when the shortcut for substring completion is pressed. */ void substringCompletion( const QString& ); /** * Emitted when the text rotation key-bindings are pressed. * * The argument indicates which key-binding was pressed. * In this case this can be either one of four values: * @p PrevCompletionMatch, @p NextCompletionMatch, @p RotateUp or * @p RotateDown. See @ref OCompletionBase::setKeyBinding() for * details. * * Note that this signal is @em NOT emitted if the completion * mode is set to CompletionNone. */ void textRotation( OCompletionBase::KeyBindingType ); /** * Emitted when the user changed the completion mode by using the * popupmenu. */ void completionModeChanged( OGlobalSettings::Completion ); /** * Emitted before the context menu is displayed. * * The signal allows you to add your own entries into the * the context menu that is created on demand. * * NOTE: Do not store the pointer to the QPopupMenu * provided through since it is created and deleted * on demand. * * @param the context menu about to be displayed */ void aboutToShowContextMenu( QPopupMenu * ); public slots: /** * Iterates through all possible matches of the completed text * or the history list. * * Depending on the value of 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. Note that the all-possible-match * iteration will not work if there are no previous matches, i.e. * no text has been completed and the *nix shell history list * rotation is only available if the insertion policy for this * widget is set either @p QComobBox::AtTop or @p QComboBox::AtBottom. * For other insertion modes whatever has been typed by the user * when the rotation event was initiated will be lost. * * @param type The key-binding invoked. */ void rotateText( OCompletionBase::KeyBindingType /* type */ ); /** * Sets the completed text in the line-edit appropriately. * * This function is an implementation for * @ref OCompletionBase::setCompletedText. */ 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 ); public: /** * Selects the first item that matches @p item. If there is no such item, * it is inserted at position @p index if @p insert is true. Otherwise, * no item is selected. */ void setCurrentItem( const QString& item, bool insert = false, int index = -1 ); void setCurrentItem(int index); protected slots: /** * @deprecated. */ 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: /* * This function simply sets the lineedit text and * highlights the text appropriately if the boolean * value is set to true. * * @param * @param */ virtual void setCompletedText( const QString& /* */, bool /*marked*/ ); /** * Reimplemented for internal reasons, the API is not affected. */ virtual void create( WId = 0, bool initializeWindow = true, bool destroyOldWindow = true ); private: // Constants that represent the ID's of the popup menu. // TODO: See if we can replace this mess with OActionMenu // in the future though this is working lovely. enum MenuID { Default=0, Cut, Copy, Paste, Clear, Unselect, SelectAll, NoCompletion, AutoCompletion, ShellCompletion, PopupCompletion, SemiAutoCompletion }; /** * Initializes the variables upon construction. */ void init(); /** * Temporary functions to delete words back and foward until * alternatives are available in QT3 (Seth Chaiklin, 21 may 2001) */ void deleteWordBack(); void deleteWordForward(); bool m_bEnableMenu; // indicating if we should stop return-key events from propagating bool m_trapReturnKey; //protected: // virtual void virtual_hook( int id, void* data ); private: class OComboBoxPrivate; OComboBoxPrivate *d; }; class OPixmapProvider; /** * A combobox which implements a history like a unix shell. You can navigate * through all the items by using the Up or Down arrows (configurable of * course). Additionally, weighted completion is available. So you should * load and save the completion list to preserve the weighting between * sessions. * * @author Carsten Pfeiffer * @short A combobox for offering a history and completion */ class OHistoryCombo : public OComboBox { Q_OBJECT Q_PROPERTY( QStringList historyItems READ historyItems WRITE setHistoryItems ) public: /** * Constructs a "read-write" combobox. A read-only history combobox * doesn't make much sense, so it is only available as read-write. * Completion will be used automatically for the items in the combo. * * The insertion-policy is set to NoInsertion, you have to add the items * yourself via the slot @ref addToHistory. If you want every item added, * use * * 
     * connect( combo, SIGNAL( activated( const QString& )),
     *          combo, SLOT( addToHistory( const QString& )));
     *
* * Use @ref QComboBox::setMaxCount() to limit the history. * * @p parent the parent object of this widget. * @p name the name of this widget. */ OHistoryCombo( QWidget *parent = 0L, const char *name = 0L ); // ### merge these two constructors /** * Same as the previous constructor, but additionally has the option * to specify whether you want to let OHistoryCombo handle completion * or not. If set to @p true, OHistoryCombo will sync the completion to the * contents of the combobox. */ OHistoryCombo( bool useCompletion, QWidget *parent = 0L, const char *name = 0L ); /** * Destructs the combo, the completion-object and the pixmap-provider */ ~OHistoryCombo(); /** * Inserts @p items into the combobox. @p items might get * truncated if it is longer than @ref maxCount() * * @see #historyItems */ inline void setHistoryItems( QStringList items ) { setHistoryItems(items, false); } /** * Inserts @p items into the combobox. @p items might get * truncated if it is longer than @ref maxCount() * * Set @p setCompletionList to true, if you don't have a list of * completions. This tells OHistoryCombo to use all the items for the * completion object as well. * You won't have the benefit of weighted completion though, so normally * you should do something like * 
     * OConfig *config = kapp->config();
     * QStringList list;
     *
     * // load the history and completion list after creating the history combo
     * list = config->readListEntry( "Completion list" );
     * combo->completionObject()->setItems( list );
     * list = config->readListEntry( "History list" );
     * combo->setHistoryItems( list );
     *
     * [...]
     *
     * // save the history and completion list when the history combo is
     * // destroyed
     * list = combo->completionObject()->items()
     * config->writeEntry( "Completion list", list );
     * list = combo->historyItems();
     * config->writeEntry( "History list", list );
     *
* * Be sure to use different names for saving with OConfig if you have more * than one OHistoryCombo. * * Note: When @p setCompletionList is true, the items are inserted into the * OCompletion object with mode OCompletion::Insertion and the mode is set * to OCompletion::Weighted afterwards. * * @see #historyItems * @see OComboBox::completionObject * @see OCompletion::setItems * @see OCompletion::items */ void setHistoryItems( QStringList items, bool setCompletionList ); /** * Returns the list of history items. Empty, when this is not a read-write * combobox. * * @see #setHistoryItems */ QStringList historyItems() const; /** * Removes all items named @p item. * * @return @p true if at least one item was removed. * * @see #addToHistory */ bool removeFromHistory( const QString& item ); /** * Sets a pixmap provider, so that items in the combobox can have a pixmap. * @ref OPixmapProvider is just an abstract class with the one pure virtual * method @ref OPixmapProvider::pixmapFor(). This method is called whenever * an item is added to the OHistoryComboBox. Implement it to return your * own custom pixmaps, or use the @ref OURLPixmapProvider from libkio, * which uses @ref OMimeType::pixmapForURL to resolve icons. * * Set @p prov to 0L if you want to disable pixmaps. Default no pixmaps. * * @see #pixmapProvider */ void setPixmapProvider( OPixmapProvider *prov ); /** * @returns the current pixmap provider. * @see #setPixmapProvider * @see OPixmapProvider */ OPixmapProvider * pixmapProvider() const { return myPixProvider; } /** * Resets the current position of the up/down history. Call this * when you manually call @ref setCurrentItem() or @ref clearEdit(). */ void reset() { slotReset(); } public slots: /** * Adds an item to the end of the history list and to the completion list. * If @ref maxCount() is reached, the first item of the list will be * removed. * * If the last inserted item is the same as @p item, it will not be * inserted again. * * If @ref duplicatesEnabled() is false, any equal existing item will be * removed before @p item is added. * * Note: By using this method and not the Q and OComboBox insertItem() * methods, you make sure that the combobox stays in sync with the * completion. It would be annoying if completion would give an item * not in the combobox, and vice versa. * * @see #removeFromHistory * @see QComboBox::setDuplicatesEnabled */ void addToHistory( const QString& item ); /** * Clears the history and the completion list. */ void clearHistory(); signals: /** * Emitted when the history was cleared by the entry in the popup menu. */ void cleared(); protected: /** * Handling key-events, the shortcuts to rotate the items. */ virtual void keyPressEvent( QKeyEvent * ); /** * Inserts @p items into the combo, honouring @ref pixmapProvider() * Does not update the completionObject. * * Note: @ref duplicatesEnabled() is not honored here. * * Called from @ref setHistoryItems() and @ref setPixmapProvider() */ void insertItems( const QStringList& items ); /** * @returns if we can modify the completion object or not. */ bool useCompletion() const { return compObj() != 0L; } private slots: /** * Resets the iterate index to -1 */ void slotReset(); /** * Called from the popupmenu, * calls clearHistory() and emits cleared() */ void slotClear(); /** * Appends our own context menu entry. */ void addContextMenuItems( QPopupMenu* ); private: void init( bool useCompletion ); /** * The current position (index) in the combobox, used for Up and Down */ int myIterateIndex; /** * The text typed before Up or Down was pressed. */ QString myText; /** * Indicates that the user at least once rotated Up through the entire list * Needed to allow going back after rotation. */ bool myRotated; OPixmapProvider *myPixProvider; private: class OHistoryComboPrivate; OHistoryComboPrivate *d; }; #endif