Home · All Classes · Main Classes · Deprecated |
MCompleter provides completion in MWidget. More...
Inherits MSceneWindow.
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.
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().
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("<>"));
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.
[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().
[in] | completionCandidates | model of completion candidates, MCompleter does not take ownership. |
MCompleter::~MCompleter | ( | ) | [virtual] |
Destructor.
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().
QString MCompleter::charactersToTrimForCompletionPrefix | ( | ) | const |
Returns the characters which will be trimmed from the start and the end of completionPrefix(). Default charactersToTrimForCompletionPrefix() is space.
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.
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.
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";
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.
text | Temporary completion label to show when there are no candidates. "Waiting...", or the like. |
void MCompleter::setValueColumnIndex | ( | int | column | ) |
Changes the completer's default value column.
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.
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 |