AutoCompleteTextView (Beta): Getting Started

This quick start tutorial demonstrates how to create a simple iOS application with TKAutoCompleteTextView.

Prerequisites

This article assumes that you have followed the Downloading UI for iOS, Installing UI for iOS and Setting Up the project steps from the common Getting Started article.

Setting up TKAutoCompleteTextView

Now that our project is created and the TelerikUI.framework is added, we can start referencing and using the TelerikUI types:

Open your ViewController.m file and add a reference to Telerik UI header file:

#import <TelerikUI/TelerikUI.h>

Note that starting with Xcode 6 Apple doesn't generate the precompiled headers file automatically. That is why you should add import the UIKit framework before importing TelerikUI:

#import <UIKit/UIKit.h>

If you are writing Swift, add the same line in your bridging header.

In the viewDidLoad method of your view controller prepare a small array of sample data to be presented as suggestions in TKAutoCompleteTextField.

NSArray *sampleArrayOfStrings =@[@"Kristina Wolfe",@"Freda Curtis",@"Jeffery Francis",@"Eva Lawson", @"Theresa    Bryan", @"Jenny Fuller", @"Terrell Norris", @"Eric Wheeler", @"Julius Clayton", @"Alfredo Thornton", @"Roberto Romero",@"Orlando Mathis",@"Eduardo Thomas",@"Harry Douglas"];
let sampleArrayOfStrings = ["Kristina Wolfe","Freda Curtis","Jeffery Francis","Eva Lawson","Emmett Santos", "Theresa Bryan", "Jenny Fuller", "Terrell Norris", "Eric Wheeler", "Julius Clayton", "Alfredo Thornton", "Roberto Romero","Orlando Mathis","Eduardo Thomas","Harry Douglas"]
NSString[] sampleArrayOfStrings = new NSString[] { new NSString("Kristina Wolfe"),
    new NSString("Freda Curtis"),
    new NSString("Jeffery Francis"),
    new NSString("Eva Lawson"),
    new NSString("Emmett Santos"), 
    new NSString("Theresa Bryan"), 
    new NSString("Jenny Fuller"), 
    new NSString("Terrell Norris"),
    new NSString("Eric Wheeler"), 
    new NSString("Julius Clayton"), 
    new NSString("Alfredo Thornton"), 
    new NSString("Roberto Romero"),
    new NSString("Orlando Mathis"),
    new NSString("Eduardo Thomas"),
    new NSString("Harry Douglas")
};

Next, create an instance of TKDataSource. This component is used to feed TKAutoCompleteTextView with our data. Now we need to go through the items of the source array and create TKAutoCompleteToken objects with which the TKAutoCompleteTextView component operates.

_dataSource = [[TKDataSource alloc] initWithArray:sampleArrayOfStrings];
[_dataSource.settings.autocomplete createToken:^TKAutoCompleteToken *(NSUInteger dataIndex, id item) {
    TKAutoCompleteToken *token = [[TKAutoCompleteToken alloc] initWithText:item];
    return token;
}];
let datasource = TKDataSource()
this.dataSource = new TKDataSource(sampleArrayOfStrings);
this.dataSource.Settings.AutoComplete.CreateToken (delegate(nuint index, NSObject item) {
TKAutoCompleteToken token = new TKAutoCompleteToken((NSString)item);
    return token;
});

Then create a new instace of TKAutoCompleteTextView and add it as a subview of the ViewController's main view. The autoresizingMask property is set in order to allow correct resizing of the list view when the device is rotated in landscape mode.

self.automaticallyAdjustsScrollViewInsets = NO;
TKAutoCompleteTextView *autocomplete = [[TKAutoCompleteTextView alloc] initWithFrame: CGRectMake(10, 80, self.view.bounds.size.width - 20, 40)];
autocomplete.autoresizingMask = UIViewAutoresizingFlexibleWidth;
autocomplete.dataSource = _dataSource;
[self.view addSubview:autocomplete];
self.automaticallyAdjustsScrollViewInsets = false
autocomplete = TKAutoCompleteTextView(frame: CGRect(x: 10, y: self.view.bounds.origin.y + 25, width: self.view.bounds.size.width - 20, height: 44))
autocomplete.autoresizingMask = UIViewAutoresizing.flexibleWidth
self.view.backgroundColor = UIColor(red: 0.937, green: 0.937, blue: 0.957, alpha: 1.0)
self.view.addSubview(autocomplete)
this.AutomaticallyAdjustsScrollViewInsets = false;
TKAutoCompleteTextView autocomplete = new TKAutoCompleteTextView(new CGRect(10, 80, this.View.Bounds.Width - 20, 30));
autocomplete.AutoresizingMask = UIViewAutoresizing.FlexibleWidth;
autocomplete.WeakDataSource = this.dataSource;
this.View.AddSubview(autocomplete);

Set up the minimumCharactersToSearch property which defines after what number of entered symbols the autocomplete should start suggesting Set also the suggestionViewHeight property which sets the height of the suggestions presenting view.

autocomplete.minimumCharactersToSearch = 1;
autocomplete.suggestionViewHeight = self.view.bounds.size.height/4;
autocomplete.minimumCharactersToSearch = 1
autocomplete.suggestionViewHeight = self.view.bounds.size.height/4
autocomplete.MinimumCharactersToSearch = 1;    
autocomplete.SuggestionViewHeight = this.View.Bounds.Size.Height/2;

So far we have got the following view:

You can change the suggestion logic in order to control which suggestions to be shown. You can show suggestions which contain the typed phrase or suggestions that start with that phrase. The completionMode property is used to control the suggesting logic. The default behaviour is showing suggestions which start with the typed in phrase.

_dataSource.settings.autocomplete.completionMode = TKAutoCompleteCompletionModeStartsWith;
datasource.settings.autocomplete.completionMode = TKAutoCompleteCompletionMode.startsWith
this.dataSource.Settings.AutoComplete.CompletionMode = TKAutoCompleteCompletionMode.StartsWith;

This will result in:

For more information about the completion modes, please refer to the Completion Modes article

Finally, right now we get suggestions in a drop-down and we have to tap one of them to perform selection. What will make the auto completion process even easier is if, in addition to the drop-down with suggestions, we get a single suggestion that is shown in the text view part of TKAutoCompleteTextView which we can easily select with a single keyboard stroke. This behavior is defined by the so called SuggestMode, and in order to get the described functionality, let's set the SuggestMode to SuggestAppend:

autocomplete.suggestMode = TKAutoCompleteSuggestModeSuggestAppend;
autocomplete.suggestMode = TKAutoCompleteSuggestMode.suggestAppend
autocomplete.SuggestMode = TKAutoCompleteSuggestMode.SuggestAppend;

The result will be:

For more information about the suggest modes, please refer to the Suggest Modes article