Home · All Classes · Main Classes · Deprecated
Public Slots | Signals | Public Member Functions | Properties

MCompleter Class Reference

MCompleter provides completion in MWidget. More...

Inherits MSceneWindow.

List of all members.

Public Slots

void hideCompleter ()
void complete ()
void confirm ()
void queryAll ()

Signals

void startCompleting (const QString &prefix)
void startCompleting (const QString &prefix, const QModelIndex &index)
void confirmed (const QString &candidate)
void confirmed (const QString &candidate, const QModelIndex &index)
void shown ()
void hidden ()

Public Member Functions

 MCompleter ()
 MCompleter (const QStringList &completionCandidates)
 MCompleter (QAbstractItemModel *completionCandidates)
virtual ~MCompleter ()
MWidgetwidget ()
void setWidget (MWidget *)
void setValueColumnIndex (int)
int valueColumnIndex () const
QString completionPrefix () const
void setCandidateSourceModel (QAbstractItemModel *)
QAbstractItemModelcandidateSourceModel () const
QAbstractItemModelmatchedCandidateModel () const
bool acceptMultipleEntries () const
void setAcceptMultipleEntries (bool)
bool isActive () const
QString charactersToTrim () const
void setCharactersToTrim (const QString &str)
QString charactersToTrimForCompletionPrefix () const
void setCharactersToTrimForCompletionPrefix (const QString &str)
void setCompletionTitle (const QString &title)
QString completionTitle () const
QString fetchInProgressLabel () const
void setFetchInProgressLabel (const QString &text)

Properties

bool acceptMultipleEntries
QString charactersToTrimForCompletionPrefix
QString completionTitle
QString fetchInProgressLabel

Detailed Description

MCompleter provides completion in MWidget.

The MCompleter interacts with MWidgets that have input method support, e.g. MTextEdit. Such widgets need to reimplement inputMethodQuery() for Qt::ImCursorPosition and Qt::ImSurroundingText.

See also:
flags(), QGraphicsItem::ItemAcceptsInputMethod

Once a completion candidate has been confirmed(), the widget is supposed to insert the received candidate so that the completer can filter candidates according to the completion prefix.

When the user starts typing a word, MCompleter suggests completion candidates, based on the contents of its candidateSourceModel(). For simple use cases, a QStringList can be sufficient. Candidates are confirmed (and inserted into the text edit) by pressing return or touching the completion item.

MCompleter also supports asynchronous model for completion candidates. Although the base class QAbstractItemModel does not directly provide state information for asynchronous fetches, MCompleter uses its canFetchMore() method to query whether fetch is in progress. Because nothing signales the state changes completer has to resort to polling.

   QStringList list;
   list << "apple" << "appreciate" << "orange" << "offset";
   QStringListModel testModel(list)
   MCompleter* completer = new MCompleter(testModel);
   MTextEdit * edit = new MTextEdit(MTextEditModel::MultiLine, "", 0);
   edit->setCompleter(completer);

The MCompleter supports customized matching, through the startCompleting() signal:

   MCompleter* completer = new MCompleter();
   MTextEdit * edit = new MTextEdit(MTextEditModel::MultiLine, "", 0);
   edit->setCompleter(completer);
   connect(completer, SIGNAL(startCompleting(QString, QModelIndex)), this, SLOT(customizedComplete(QString, QModelIndex)));

The application can update the model according to the prefix in the slot, and MCompleter will then show completion candidates according to the updated model:

   void ExampleClass::customizedComplete(const QString &prefix, const QModelIndex &index)
   {
      //do customized match according prefix,
      completer->setCandidateSourceModel(model);
   }

MCompleter supports more than one-dimensional models, in which case the last column is queried for values. All columns are used to match and display a candidate, but only the item in that column will be inserted to the text upon confirmation. The value column can be set via setValueColumnIndex().

See also:
QAbstractItemModel, QAbstractTableModel Example:
   class TestModel : public  QAbstractTableModel
   {
      public :
          TestModel(const QStringList&, const QStringList&, QObject * parent = 0);
          //...
   };

   QStringList modelColumn1;
   modelColumn1.append("Tom While");
   modelColumn1.append("John Frank");
   QStringList modelColumn2;
   modelColumn2.append("<tom.w@example.com>");
   modelColumn2.append("<john.f@example.com>");
   TestModel* testModel = new TestModel(modelColumn1, modelColumn2, this);
   MCompleter* completer = new MCompleter(testModel);
   MTextEdit * edit = new MTextEdit(MTextEditModel::MultiLine, "", 0);
   edit->setCompleter(completer);

To trim special characters before confirming an item to the text entry, call setCharactersToTrim(). For example, when the user confirms an item such as "<tom.w@example.com>", but the angle brackets need to be removed before insertion:

   completer->setCharactersToTrim(QString("<>"));

Constructor & Destructor Documentation

MCompleter::MCompleter (  ) 

Creates an instance without any completion candidates.

MCompleter::MCompleter ( const QStringList completionCandidates  )  [explicit]

Creates an instance with the specified list of possible completion candidates.

Parameters:
[in] completionCandidates list of completion candidates.
MCompleter::MCompleter ( QAbstractItemModel completionCandidates  )  [explicit]

Creates an instance with the specified model of possible completion candidates. If completionCandidates has only one column, then this column is the completion candidate list. If completionCandidates has more than one column, all columns are used as possible completion candidates, but only the items of the default value column will be inserted into the text edit upon candidate confirmation. The default value column is the last column. It can be changed through setValueColumnIndex().

Parameters:
[in] completionCandidates model of completion candidates, MCompleter does not take ownership.
MCompleter::~MCompleter (  )  [virtual]

Destructor.


Member Function Documentation

bool MCompleter::acceptMultipleEntries (  )  const

Returns single/multiple entry property. If false, only single entry (e.g. single email address) is relevant, if true, then multiple entries can be confirmed in the same text field. Default delimiters between multiple entries are comma and semicolon. This means if there is already a confirmed completion in the text entry, then completer wouldn't give the next suggestion.

QAbstractItemModel * MCompleter::candidateSourceModel (  )  const

Returns the completion candidates' source model.

QString MCompleter::charactersToTrim (  )  const

Returns the characters which will be trimmed when confirm().

See also:
setCharactersToTrim()
QString MCompleter::charactersToTrimForCompletionPrefix (  )  const

Returns the characters which will be trimmed from the start and the end of completionPrefix(). Default charactersToTrimForCompletionPrefix() is space.

See also:
setCharactersToTrimForCompletionPrefix().
void MCompleter::complete (  )  [slot]

Matches completion candidates, and display the completer if there are some matched completion candidates. If there is no customized match rule slot connected, completer searches the completion candidate source model, and continues until reach the end or the hints number equal default maximum hits: 10. If you want to get all matched items, use queryAll(). /sa queryAll()

QString MCompleter::completionPrefix (  )  const

Returns current completion prefix. The prefix is the text which contains the cursor, and betweens two delimiters. Default delimiters are comma and semicolon.

QString MCompleter::completionTitle (  )  const

Returns title for completions.

void MCompleter::confirm (  )  [slot]

Confirms current selected completion item, will insert the item's (belongs to the value column) display string to the text entry.

void MCompleter::confirmed ( const QString candidate  )  [signal]

This signal is emitted when an item in the completion candidates is confirmed by the user. The widget() using the completer is supposed to insert the confirmed completion by itself.

void MCompleter::confirmed ( const QString candidate,
const QModelIndex index 
) [signal]

This is an overloaded version of confirmed().

QString MCompleter::fetchInProgressLabel (  )  const

Label text to show during asynchronous model update.

The text is visible in completer only when fetch is in progress, there are no matches, and there is a completion prefix.

See also:
setFetchInProgressLabel
void MCompleter::hidden (  )  [signal]

This signal is emitted just after hiding the completer.

void MCompleter::hideCompleter (  )  [slot]

hides the completer. This function should be called when the MWidget wants to hide completer when losing focus. The application can not call show() or appear() to show completer, but can call complete() to start to match, and the completer will be visible automatically if there are some matched completion candidates.

bool MCompleter::isActive (  )  const

Returns if current completer is active (there are some completions shown).

Reimplemented from MWidgetController.

QAbstractItemModel * MCompleter::matchedCandidateModel (  )  const

Returns the matched completion candidates' model.

void MCompleter::queryAll (  )  [slot]

Queries the completion candidate source model, to get all matched items. It is always called after complete(), but it does nothing if there is a customized match rule slot connected. /sa complete()

void MCompleter::setAcceptMultipleEntries ( bool  enable  ) 

Sets single/multiple entry property.

See also:
acceptMultipleEntries().
void MCompleter::setCandidateSourceModel ( QAbstractItemModel model  ) 

Sets the completion candidate source list with specified model.

void MCompleter::setCharactersToTrim ( const QString str  ) 

Sets the characters to be trimmed when confirm(). When confirming, the completion will remove the characters(belong to charactersToTrim()) from the start and the end. For example, to remove '<' and '>' from "<tom@example.com>", only insert "tom@example.com" to text entry.

   completer->setCharactersToTrim(QString("<>"));
void MCompleter::setCharactersToTrimForCompletionPrefix ( const QString str  ) 

Sets the characters to be trimmed from the start and the end of completionPrefix(). All characters in str will be removed from the start and the end of completionPrefix(). Example:

   // if the text which contains cursor and betweens two delimiters is "  text to be trimmed\t\r ".
   completer->setCharactersToTrimForCompletionPrefix(QString(" \t\r"));
   // completionPrefix() == "to be trimmed";
See also:
charactersToTrimForCompletionPrefix().
void MCompleter::setCompletionTitle ( const QString title  ) 

Set title for completions.

void MCompleter::setFetchInProgressLabel ( const QString text  ) 

Set the label to show during asynchronous model update.

Parameters:
text Temporary completion label to show when there are no candidates. "Waiting...", or the like.
See also:
fetchInProgressLabel
void MCompleter::setValueColumnIndex ( int  column  ) 

Changes the completer's default value column.

See also:
valueColumnIndex().
void MCompleter::setWidget ( MWidget widget  ) 

Sets the completer's widget which receives the completions. This method is implicitely called when the MCompleter is bound to a MWidget, e.g., MTextEdit::setCompleter(). For custom widgets, this method needs to be called explicitly.

void MCompleter::shown (  )  [signal]

This signal is emitted just after showing the completer.

void MCompleter::startCompleting ( const QString prefix  )  [signal]

This signal is emitted before starting matching the completion candidates. Application can customize its own completion rule, by connecting its customized match rule slot to this signal, and calling setCompletions, setMatchedCompletions inside the slot's implementation.

void MCompleter::startCompleting ( const QString prefix,
const QModelIndex index 
) [signal]

This is an overloaded version of startCompleting().

int MCompleter::valueColumnIndex (  )  const

Returns the value column index of the completer's model. The value column contains the text which will be inserted to the text edit upon candidate confirmation. Default value column is the last column of the model.

MWidget * MCompleter::widget (  ) 

Returns the completer's widget which receives the completions.


Property Documentation

bool MCompleter::acceptMultipleEntries [read, write]
QString MCompleter::charactersToTrimForCompletionPrefix [read, write]
QString MCompleter::completionTitle [read, write]
QString MCompleter::fetchInProgressLabel [read, write]

Copyright © 2010 Nokia Corporation
MeeGo Touch