Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages

OLineEdit Class Reference

An enhanced single line input widget. More...

#include </home/clem/local/src/opie/libopie2/qt3/opieui/olineedit.h>

Inheritance diagram for OLineEdit:

Inheritance graph
[legend]
Collaboration diagram for OLineEdit:

Collaboration graph
[legend]
List of all members.

Public Slots

virtual void setReadOnly (bool)
void rotateText (OCompletionBase::KeyBindingType)
virtual void setCompletedText (const QString &)
void setCompletedItems (const QStringList &items)
virtual void clear ()

Signals

void returnPressed (const QString &)
void completion (const QString &)
void substringCompletion (const QString &)
void textRotation (OCompletionBase::KeyBindingType)
void completionModeChanged (OGlobalSettings::Completion)
void aboutToShowContextMenu (QPopupMenu *)

Public Member Functions

 OLineEdit (const QString &string, QWidget *parent, const char *name=0)
 OLineEdit (QWidget *parent=0, const char *name=0)
virtual ~OLineEdit ()
void setURL (const KURL &url)
void cursorAtEnd ()
virtual void setCompletionMode (OGlobalSettings::Completion mode)
virtual void setContextMenuEnabled (bool showMenu)
bool isContextMenuEnabled () const
void setURLDropsEnabled (bool enable)
bool isURLDropsEnabled () const
void setTrapReturnKey (bool trap)
bool trapReturnKey () const
virtual bool eventFilter (QObject *, QEvent *)
OCompletionBox * completionBox (bool create=true)
virtual void setCompletionObject (OCompletion *, bool hsig=true)

Protected Slots

virtual void makeCompletion (const QString &)
void slotAboutToShow ()
void slotCancelled ()

Protected Member Functions

virtual void keyPressEvent (QKeyEvent *)
virtual void mousePressEvent (QMouseEvent *)
virtual void mouseDoubleClickEvent (QMouseEvent *)
virtual QPopupMenu * createPopupMenu ()
virtual void setCompletedText (const QString &, bool)
virtual void create (WId=0, bool initializeWindow=true, bool destroyOldWindow=true)

Properties

bool contextMenuEnabled
bool urlDropsEnabled

Private Types

enum  MenuID {
  Default = 42, NoCompletion, AutoCompletion, ShellCompletion,
  PopupCompletion, SemiAutoCompletion
}

Private Slots

void completionMenuActivated (int id)
void tripleClickTimeout ()

Private Member Functions

void init ()
void makeCompletionBox ()

Private Attributes

bool m_bEnableMenu
bool possibleTripleClick
OLineEditPrivate * d

Friends

class OComboBox

Classes

class  OLineEditPrivate

Detailed Description

An enhanced single line input widget.

An enhanced QLineEdit widget for inputting text.

Detail
This widget inherits from QLineEdit and implements the following additional functionalities: q completion object that provides both automatic and manual text completion as well as multiple match iteration 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 OLineEdit also emits a few more additional signals. These are: completion( const QString& ), textRotation( KeyBindingType ), and returnPressed( const QString& ). The completion signal can be connected to a slot that will assist the user in filling out the remaining text. The text rotation signal is intended to be used to iterate through the list of all possible matches whenever there is more than one match for the entered text. The returnPressed( const QString& ) signals are the same as QLineEdit's except it provides the current text in the widget as its argument whenever appropriate.

This widget by default creates a completion object when you invoke the completionObject( bool ) member function for the first time or use setCompletionObject( OCompletion*, bool ) to assign your own completion object. Additionally, to make this widget more functional, OLineEdit will by default handle the text rotation and completion events internally when a completion object is created through either one of the methods mentioned above. If you do not need this functionality, simply use OCompletionBase::setHandleSignals( bool ) or set the boolean parameter in the above functions to FALSE.

The default key-bindings for completion and rotation is determined from the global settings in OStdAccel. These values, however, can be overriden locally by invoking OCompletionBase::setKeyBinding(). The values can easily be reverted back to the default setting, by simply calling useGlobalSettings(). An alternate method would be to default individual key-bindings by usning setKeyBinding() with the default second argument.

NOTE that if the EchoMode for this widget is set to something other than QLineEdit::Normal, the completion mode will always be defaulted to PGlobalSettings::CompletionNone. This is done purposefully to guard against protected entries such as passwords being cached in OCompletion's list. Hence, if the EchoMode is not QLineEdit::Normal, the completion mode is automatically disabled.

Usage
To enable the basic completion feature :

 OLineEdit *edit = new OLineEdit( this, "mywidget" );
 OCompletion *comp = edit->completionObject();
 // Fill the completion object with a list of possible matches
 QStringList list;
 list << "mickeyl@handhelds.org" << "mickey@tm.informatik.uni-frankfurt.de>" << "mickey@Vanille.de";
 comp->setItems( list );
 // Connect to the return pressed signal (optional)
 connect(edit,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&));

To use a customized completion objects or your own completion object :

 OLineEdit *edit = new OLineEdit( this,"mywidget" );
 KURLCompletion *comp = new KURLCompletion();
 edit->setCompletionObject( comp );
 // Connect to the return pressed signal - optional
 connect(edit,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
 // iteration internally.
 edit->setHandleSignals( false );
 // Set your own completion key for manual completions.
 edit->setKeyBinding( OCompletionBase::TextCompletion, Qt::End );
 // Hide the context (popup) menu
 edit->setContextMenuEnabled( false );
 // Temporarly disable signal emitions
 // (both completion & iteration signals)
 edit->disableSignals();
 // Default the key-bindings to system settings.
 edit->useGlobalKeyBindings();

Author:
Dawit Alemayehu <adawit@kde.org>

Opie adaption by Michael Lauer <mickey@tm.informatik.uni-frankfurt.de>

Definition at line 150 of file olineedit.h.

Member Enumeration Documentation

enum OLineEdit::MenuID [private]
 

Enumeration values:
Default 
NoCompletion 
AutoCompletion 
ShellCompletion 
PopupCompletion 
SemiAutoCompletion 

Definition at line 462 of file olineedit.h.

Constructor & Destructor Documentation

OLineEdit::OLineEdit (  const QString &  string,
QWidget *  parent,
const char *  name = 0
) 
 

Constructs a OLineEdit object with a default text, a parent, and a name.

Parameters:
string Text to be shown in the edit widget.
parent The parent object of this widget.
name the name of this widget

Definition at line 76 of file olineedit.cpp.

References init().

OLineEdit::OLineEdit (  QWidget *  parent = 0,
const char *  name = 0
) 
 

Constructs a OLineEdit object with a parent and a name.

Parameters:
string Text to be shown in the edit widget.
parent The parent object of this widget.
name The name of this widget.

Definition at line 82 of file olineedit.cpp.

References init().

OLineEdit::~OLineEdit (   )  [virtual]
 

Destructor.

Definition at line 88 of file olineedit.cpp.

References d.

Member Function Documentation

void OLineEdit::aboutToShowContextMenu (  QPopupMenu *   )  [signal]
 

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.

Parameters:
the context menu about to be displayed

Referenced by createPopupMenu().

void OLineEdit::clear (   )  [virtual, slot]
 

Reimplemented to workaround a buggy QLineEdit::clear() (changing the clipboard to the text we just had in the lineedit)

Definition at line 726 of file olineedit.cpp.

References QString::null.

Referenced by OEditListBox::addItem(), and OEditListBox::clear().

void OLineEdit::completion (  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 normal.

Referenced by keyPressEvent().

OCompletionBox * OLineEdit::completionBox (  bool  create = true  ) 
 

Returns:
the completion-box, that is used in completion mode KGlobalSettings::CompletionPopup. This method will create a completion-box if none is there, yet.
Parameters:
create Set this to false if you don't want the box to be created i.e. to test if it is available.

Definition at line 697 of file olineedit.cpp.

References OLineEdit::OLineEditPrivate::completionBox, d, and makeCompletionBox().

Referenced by OComboBox::completionBox(), and OComboBox::eventFilter().

void OLineEdit::completionMenuActivated (  int  id  )  [private, slot]
 

Definition at line 493 of file olineedit.cpp.

References AutoCompletion, OLineEdit::OLineEditPrivate::completionBox, OCompletionBase::completionMode(), completionModeChanged(), d, OCompletionBox::hide(), NoCompletion, PopupCompletion, SemiAutoCompletion, setCompletionMode(), and ShellCompletion.

Referenced by createPopupMenu().

void OLineEdit::completionModeChanged (  OGlobalSettings::Completion   )  [signal]
 

Emitted when the user changed the completion mode by using the popupmenu.

Referenced by completionMenuActivated().

void OLineEdit::create (  WId  = 0,
bool  initializeWindow = true,
bool  destroyOldWindow = true
)  [protected, virtual]
 

Reimplemented for internal reasons, the API is not affected.

Definition at line 720 of file olineedit.cpp.

QPopupMenu * OLineEdit::createPopupMenu (   )  [protected, virtual]
 

Re-implemented for internal reasons. API not affected.

See QLineEdit::createPopupMenu().

Definition at line 433 of file olineedit.cpp.

References aboutToShowContextMenu(), AutoCompletion, completionMenuActivated(), OCompletionBase::completionMode(), OCompletionBase::compObj(), m_bEnableMenu, NoCompletion, PopupCompletion, SemiAutoCompletion, ShellCompletion, and tr.

void OLineEdit::cursorAtEnd (   )  [inline]
 

Puts the text cursor at the end of the string.

This method is deprecated. Use QLineEdit::end() instead.

Deprecated:
QLineEdit::end()

Definition at line 199 of file olineedit.h.

References end.

bool OLineEdit::eventFilter (  QObject *  ,
QEvent * 
)  [virtual]
 

Re-implemented for internal reasons. API not affected.

Definition at line 546 of file olineedit.cpp.

References OLineEdit::OLineEditPrivate::completionBox, d, OLineEdit::OLineEditPrivate::grabReturnKeyEvents, OCompletionBox::hide(), Qt::Key_Enter, Qt::Key_Return, KeyPress, and returnPressed().

void OLineEdit::init (   )  [private]
 

Initializes variables. Called from the constructors.

Definition at line 93 of file olineedit.cpp.

References d, possibleTripleClick, and setContextMenuEnabled().

Referenced by OLineEdit().

bool OLineEdit::isContextMenuEnabled (   )  const [inline]
 

Returns true when the context menu is enabled.

Definition at line 230 of file olineedit.h.

References m_bEnableMenu.

bool OLineEdit::isURLDropsEnabled (   )  const
 

Returns true when decoded URL drops are enabled

Definition at line 591 of file olineedit.cpp.

References d, and OLineEdit::OLineEditPrivate::handleURLDrops.

void OLineEdit::keyPressEvent (  QKeyEvent *   )  [protected, virtual]
 

Re-implemented for internal reasons. API not affected.

See QLineEdit::keyPressEvent().

Definition at line 207 of file olineedit.cpp.

References completion(), OLineEdit::OLineEditPrivate::completionBox, OCompletionBase::completionMode(), d, OCompletionBase::emitSignals(), OCompletionBase::getKeyBindings(), OCompletionBase::handleSignals(), hasSelectedText(), OCompletionBox::hide(), QString::isNull(), keycode, len, QString::length(), makeCompletion(), Dasher::Opts::Normal, qDebug(), text, and QString::unicode().

void OLineEdit::makeCompletion (  const QString &   )  [protected, virtual, slot]
 

Completes the remaining text with a matching one from a given list.

Definition at line 156 of file olineedit.cpp.

References OCompletion::allMatches(), OLineEdit::OLineEditPrivate::completionBox, OCompletionBase::completionMode(), OCompletionBase::compObj(), d, OCompletionBox::hide(), QString::isNull(), OCompletion::makeCompletion(), match(), setCompletedItems(), and setCompletedText().

Referenced by keyPressEvent(), and OComboBox::makeCompletion().

void OLineEdit::makeCompletionBox (   )  [private]
 

Creates the completion box

Definition at line 611 of file olineedit.cpp.

References OLineEdit::OLineEditPrivate::completionBox, d, and OCompletionBase::handleSignals().

Referenced by completionBox(), and setCompletedItems().

void OLineEdit::mouseDoubleClickEvent (  QMouseEvent *   )  [protected, virtual]
 

Re-implemented for internal reasons. API not affected.

See QWidget::mouseDoubleClickEvent().

Definition at line 407 of file olineedit.cpp.

References Qt::LeftButton, possibleTripleClick, and tripleClickTimeout().

void OLineEdit::mousePressEvent (  QMouseEvent *   )  [protected, virtual]
 

Re-implemented for internal reasons. API not affected.

See QLineEdit::mousePressEvent().

Definition at line 418 of file olineedit.cpp.

References Qt::LeftButton, and possibleTripleClick.

void OLineEdit::returnPressed (  const QString &   )  [signal]
 

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::EchoMode.

Referenced by eventFilter().

void OLineEdit::rotateText (  OCompletionBase::KeyBindingType   )  [slot]
 

Iterates through all possible matches of the completed text or the history list.

This function simply iterates over all possible matches in case multimple matches are found as a result of a text completion request. It will have no effect if only a single match is found.

Parameters:
type The key-binding invoked.

Definition at line 137 of file olineedit.cpp.

References OCompletionBase::compObj(), hasSelectedText(), input, QString::isNull(), OCompletionBase::NextCompletionMatch, OCompletion::nextMatch(), OCompletionBase::PrevCompletionMatch, OCompletion::previousMatch(), and setCompletedText().

Referenced by OComboBox::rotateText().

void OLineEdit::setCompletedItems (  const QStringList &  items  )  [virtual, slot]
 

Sets items into the completion-box if completionMode() is CompletionPopup. The popup will be shown immediately.

Implements OCompletionBase.

Definition at line 676 of file olineedit.cpp.

References OLineEdit::OLineEditPrivate::completionBox, QValueList< T >::count(), d, QValueList< T >::first(), OCompletionBox::hide(), QString::isEmpty(), QValueList< T >::isEmpty(), makeCompletionBox(), OCompletionBox::popup(), OCompletionBox::setCancelledText(), OCompletionBox::setItems(), and text.

Referenced by makeCompletion(), OComboBox::setCompletedItems(), and setCompletionObject().

void OLineEdit::setCompletedText (  const QString &  ,
bool 
)  [protected, virtual]
 

Re-implemented to handle URI drops.

See QLineEdit::dropEvent().

Definition at line 118 of file olineedit.cpp.

References QString::length(), and text.

void OLineEdit::setCompletedText (  const QString &   )  [virtual, slot]
 

See OCompletionBase::setCompletedText.

Implements OCompletionBase.

Definition at line 128 of file olineedit.cpp.

References OCompletionBase::completionMode().

Referenced by makeCompletion(), rotateText(), and OComboBox::setCompletedText().

void OLineEdit::setCompletionMode (  OGlobalSettings::Completion  mode  )  [virtual]
 

Re-implemented from OCompletionBase for internal reasons.

This function is re-implemented in order to make sure that the EchoMode is acceptable before we set the completion mode.

See OCompletionBase::setCompletionMode

Reimplemented from OCompletionBase.

Definition at line 103 of file olineedit.cpp.

References OLineEdit::OLineEditPrivate::completionBox, OCompletionBase::completionMode(), d, OCompletionBox::hide(), Dasher::Opts::Normal, and OCompletionBase::setCompletionMode().

Referenced by completionMenuActivated(), OpieUIDemo::demoOLineEdit(), and OComboBox::setAutoCompletion().

void OLineEdit::setCompletionObject (  OCompletion *  ,
bool  hsig = true
)  [virtual]
 

Reimplemented for internal reasons, the API is not affected.

Reimplemented from OCompletionBase.

Definition at line 705 of file olineedit.cpp.

References OCompletionBase::compObj(), OCompletionBase::handleSignals(), setCompletedItems(), and OCompletionBase::setCompletionObject().

virtual void OLineEdit::setContextMenuEnabled (  bool  showMenu  )  [inline, virtual]
 

Enables/disables the popup (context) menu.

Note that when this function is invoked with its argument set to true, then both the context menu and the completion menu item are enabled. If you do not want to the completion item to be visible simply invoke hideModechanger() right after calling this method. Also by default, the context menu is automatically created if this widget is editable. Thus you need to call this function with the argument set to false if you do not want this behaviour.

Parameters:
showMenu If true, show the context menu.

Definition at line 225 of file olineedit.h.

References m_bEnableMenu.

Referenced by init(), and OComboBox::setContextMenuEnabled().

void OLineEdit::setReadOnly (  bool   )  [virtual, slot]
 

Re-implemented for internal reasons. API not changed.

Definition at line 187 of file olineedit.cpp.

References Disabled, Dasher::Opts::Normal, and p.

void OLineEdit::setTrapReturnKey (  bool  trap  ) 
 

By default, OLineEdit recognizes Key_Return and Key_Enter and emits the returnPressed() signals, but it also lets the event pass, for example causing a dialog's default-button to be called.

Call this method with trap = true to make OLineEdit stop these events. The signals will still be emitted of course.

See also:
trapReturnKey()

Definition at line 596 of file olineedit.cpp.

References d, and OLineEdit::OLineEditPrivate::grabReturnKeyEvents.

Referenced by OEditListBox::init().

void OLineEdit::setURL (  const KURL &  url  ) 
 

Sets url into the lineedit. It uses KURL::prettyURL() so that the url is properly decoded for displaying.

void OLineEdit::setURLDropsEnabled (  bool  enable  ) 
 

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 QLineEdit is used, which inserts the encoded URL.

Parameters:
enable If true, insert decoded URLs

Definition at line 586 of file olineedit.cpp.

References d, and OLineEdit::OLineEditPrivate::handleURLDrops.

void OLineEdit::slotAboutToShow (   )  [inline, protected, slot]
 

Deprecated:
. Will be removed in the next major release!

Definition at line 394 of file olineedit.h.

void OLineEdit::slotCancelled (   )  [inline, protected, slot]
 

Deprecated:
. Will be removed in the next major release!

Definition at line 399 of file olineedit.h.

void OLineEdit::substringCompletion (  const QString &   )  [signal]
 

Emitted when the shortcut for substring completion is pressed.

void OLineEdit::textRotation (  OCompletionBase::KeyBindingType   )  [signal]
 

Emitted when the text rotation key-bindings are pressed.

The argument indicates which key-binding was pressed. In OLineEdit's case this can be either one of two values: PrevCompletionMatch or NextCompletionMatch. See OCompletionBase::setKeyBinding for details.

Note that this signal is not emitted if the completion mode is set to KGlobalSettings::CompletionNone or echoMode() is not normal.

bool OLineEdit::trapReturnKey (   )  const
 

Returns:
true if keyevents of Key_Return or Key_Enter will be stopped or if they will be propagated.
See also:
setTrapReturnKey ()

Definition at line 601 of file olineedit.cpp.

References d, and OLineEdit::OLineEditPrivate::grabReturnKeyEvents.

void OLineEdit::tripleClickTimeout (   )  [private, slot]
 

Definition at line 428 of file olineedit.cpp.

References possibleTripleClick.

Referenced by mouseDoubleClickEvent().

Friends And Related Function Documentation

friend class OComboBox [friend]
 

Definition at line 152 of file olineedit.h.

Member Data Documentation

OLineEditPrivate* OLineEdit::d [private]
 

Reimplemented from OCompletionBase.

Definition at line 494 of file olineedit.h.

Referenced by completionBox(), completionMenuActivated(), eventFilter(), init(), isURLDropsEnabled(), keyPressEvent(), makeCompletion(), makeCompletionBox(), setCompletedItems(), setCompletionMode(), setTrapReturnKey(), setURLDropsEnabled(), trapReturnKey(), and ~OLineEdit().

bool OLineEdit::m_bEnableMenu [private]
 

Checks whether we should/should not consume a key used as an accelerator.

Definition at line 487 of file olineedit.h.

Referenced by createPopupMenu(), isContextMenuEnabled(), and setContextMenuEnabled().

bool OLineEdit::possibleTripleClick [private]
 

Definition at line 489 of file olineedit.h.

Referenced by init(), mouseDoubleClickEvent(), mousePressEvent(), and tripleClickTimeout().

Property Documentation

bool OLineEdit::contextMenuEnabled [read, write]
 

Definition at line 154 of file olineedit.h.

bool OLineEdit::urlDropsEnabled [read, write]
 

Definition at line 156 of file olineedit.h.

The documentation for this class was generated from the following files:
Generated on Sat Nov 5 17:42:51 2005 for OPIE by  doxygen 1.4.2