Since: token

#include <bb/extensions/cascades/tokenentry/AbstractTokenHandler>

Token handler for TokenEntry control.

Token handler defines the rules for token creation, displaying token completions, suggestions, and look-up results.

A user has to override the AbstractTokenHandler class and provide it to an instance of the TokenEntry. AbstractTokenHandler has an "empty" default implementation for all its methods, so it allows to be partially overridden.

The communication between token handler and TokenEntry is done via TokenEntryEvent, which is passed as a parameter to handler's methods. The user reads the query from the TokenEntryEvent, and then generates and sets a collection of TokenData objects on the TokenEntryEvent. If these TokenData objects have no parent, the TokenEntry takes ownership of them and sets itself as their parent, which means that TokenEntry deletes such TokenData when it does not need it for UI interactions. Note: always set a parent on TokenData if you plan to cache it outside of TokenEntry.


Public Functions Index

AbstractTokenHandler ()
virtual ~AbstractTokenHandler ()
virtual voidpickerTapped ()
virtual bb::cascades::ActionSet *provideActionSet (TokenData *token)
virtual voidprovideCompletions (TokenEntryEvent *completionEvent)
virtual voidprovideLookup (TokenEntryEvent *lookupEvent)
virtual voidprovideSuggestions (TokenEntryEvent *suggestionEvent)
virtual voidtokenLongPressed (TokenData *token)
virtual voidtokenSelected (TokenData *token, TokenEntryEvent *tokenSelectedEvent)
virtual TokenData *validateAndProvideToken (const QString &textEntry)

Public Functions

AbstractTokenHandler ()

virtual~AbstractTokenHandler ()


virtual void pickerTapped ()

Allows an application to define how to respond when the picker is selected.

When the user taps on the picker image, this method will be called to allow for application defined functionality.

By default, the method does nothing.

virtualbb::cascades::ActionSet * provideActionSet (

Allows an application to provide a custom ActionSet for menus.

When the user performs a long-press on a token; or when the contextual menu is invoked while a token is selected. This allows an application to construct an ActionSet to be added to the ContextMenuHandler.

If an application does not wish to provide an ActionSet, return NULL.

virtual void provideCompletions (

Generates a collection of completions for the entry being typed in the TokenEntry.

As user types in the TokenEntry field the provideCompletions method is called to get the list of possible completions for the typed entry. TokenEntryEvent facilitates data handling between TokenEntry.

Typical implementation of this method:
  • acquire entry string by calling completionEvent->query();

  • generate completions in form of QList<TokenData*> completionsExample;

  • attach the completions to the event: completionEvent->setReplyTokens(completionsExample);


virtual void provideLookup (

Generates and updates lookup results for TokenEntry's lookup requests.

While typing in the TokenEntry field the user is prompted with the option of starting [remote] lookup for the matches to the entered string, which calls this method.

Override this method to implement [remote] lookup. Use the TokenEntryEvent parameter to get the lookup query, then generate and set the lookup results on the same TokenEntryEvent. It is expected that the lookup process takes relatively long time while the set of the lookup results is growing. Under such scenario the TokenEntry's lookup results display needs to be updated at shorter periods of time, so, store the reference to the TokenEntryEvent to update lookup parameter at later time

Typical implementation of this method:
  • acquire entry string by calling lookupEvent->query();

  • start a separate lookup thread

  • while the lookup results set is growing: -- generate intermediate lookup results in form of QList<TokenData*> lookupResults; -- update the event: lookupEvent->setReplyTokens(lookupResults, bool finished = false);

  • when the lookup is complete: -- finish updating the event: lookupEvent->setReplyTokens(lookupResults, bool finished = true);

  void remoteLookup(TokenEntryEvent *lookupEvent) {
      QList<bb::cascades::extensions::TokenData*> resultTokens;
      QString searchStr(lookupEvent->query());

      // run lookup and populate resultTokens
      // use lookupEvent->setReplyTokens(resultTokens, false); for intermediate results

        lookupEvent->setReplyTokens(resultTokens, true);

    void YourTokenHandler::provideLookup(TokenEntryEvent *lookupEvent) {
        QtConcurrent::run(remoteLookup, lookupEvent);

virtual void provideSuggestions (

Generates a collection of suggestions based on the current set of TokenData.

After a user enters a new TokenData into the TokenEntry field provideSuggestions method is called to get a list of suggesteds to add. TokenEntryEvent facilitates data handling between TokenEntry.

Typical implementation of this method:
  • acquire current set of tokens by calling TokenEntry.tokens

  • generate suggestions in form of QList<TokenData*> suggestionsExample;

  • attach the completions to the event: suggestionEvent->setReplyTokens(suggestionsExample);


the TokenEntryEvent to perform responses on.

virtual void tokenLongPressed (

Notifies when the token has been long pressed.

This method allows for the application to perform extra operations when a user long presses on a token, such as displaying a crosscut when the token is tied to a contact.

TokenData::setMiscellaneous can be used when creating the token to set such key information (such as contact id).

By default, this method does nothing.

virtual void tokenSelected (

Generates an alternative set of entries for the selected token.

When the user interacts in such a way that the token becomes selected (through tapping, or some other mechanism) this method will be called in order to generate alternative entries for the selected token's value. A list will be displayed that allows the user to select one of the alternative entries to replace the current token with. When this entry is selected, the entire TokenData will be replaced in-place.

By default, this method does nothing.

Using whatever data deemed necessary in the app, a QList containing the alternative entries will need to be generated. When tokenSelectedEvent->setReplyTokens is called, this list will be displayed under the selected token when this method returns. It is possible to set any value of the TokenData and yet use the setXXXXXDisplayOnList methods to not display it in the drop down list. This is useful for email selection, where the email would be in the description value, but the title needs to remain for friendly name of the actual token being displayed.

Setting the reply tokens to nothing, or doing nothing, will result in no list being displayed.

If the user selects a different TokenData then the value in the selected token, the selected token will be replaced and the tokenChanged signal will be emitted.

NOTE: This function will NOT be called for group token types. When a group token is selected, it displays the list of group members specified in the group list attached to the token data, so no alternatives are requested through this function.

virtualTokenData * validateAndProvideToken (

Defines how a token is generated from a string.


the string typed in the TokenEntry



Last modified: 2015-07-24

Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus