How do I retrieve keystrokes from a custom keyboard on an iOS app?
I need to build a custom keyboard for my iPhone app. Previous questions and answers on the topic have focused on the visual elements of a custom keyboard, but I'm trying to understand how to retrieve the keystrokes from this keyboard.
Apple provides the inputView mechanism which makes it easy to associate a custom keyboard with an UITextField or UITextView, but they do not provide the functions to send generated keystrokes back to the associated object. Based on the typical delegation for these objects, we'd expect three functions : one of normal characters, one for backspace and one for enter. Yet, no one seems to clearly define these functions or how to use them.
How do I build a custom keyboard for my iOS app and retrieve keystrokes from it?
Solution 1:
Greg's approach should work but I have an approach that doesn't require the keyboard to be told about the text field or text view. In fact, you can create a single instance of the keyboard and assign it to multiple text fields and/or text views. The keyboard handles knowing which one is the first responder.
Here is my approach. I'm not going to show any code for creating the keyboard layout. That's the easy part. This code shows all of the plumbing.
Edit: This has been updated to properly handle UITextFieldDelegate textField:shouldChangeCharactersInRange:replacementString: and UITextViewDelegate textView:shouldChangeTextInRange:replacementText:.
The header file:
@interface SomeKeyboard : UIView <UIInputViewAudioFeedback>
@end
The implementation file:
@implmentation SomeKeyboard {
id<UITextInput> _input;
BOOL _tfShouldChange;
BOOL _tvShouldChange;
}
- (id)init {
self = [super init];
if (self) {
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(checkInput:) name:UITextFieldTextDidBeginEditingNotification object:nil];
}
return self;
}
// This is used to obtain the current text field/view that is now the first responder
- (void)checkInput:(NSNotification *)notification {
UITextField *field = notification.object;
if (field.inputView && self == field.inputView) {
_input = field;
_tvShouldChange = NO;
_tfShouldChange = NO;
if ([_input isKindOfClass:[UITextField class]]) {
id<UITextFieldDelegate> del = [(UITextField *)_input delegate];
if ([del respondsToSelector:@selector(textField:shouldChangeCharactersInRange:replacementString:)]) {
_tfShouldChange = YES;
}
} else if ([_input isKindOfClass:[UITextView class]]) {
id<UITextViewDelegate> del = [(UITextView *)_input delegate];
if ([del respondsToSelector:@selector(textView:shouldChangeTextInRange:replacementText:)]) {
_tvShouldChange = YES;
}
}
}
}
// Call this for each button press
- (void)click {
[[UIDevice currentDevice] playInputClick];
}
// Call this when a button on the keyboard is tapped (other than return or backspace)
- (void)keyTapped:(UIButton *)button {
NSString *text = ???; // determine text for the button that was tapped
if ([_input respondsToSelector:@selector(shouldChangeTextInRange:replacementText:)]) {
if ([_input shouldChangeTextInRange:[_input selectedTextRange] replacementText:text]) {
[_input insertText:text];
}
} else if (_tfShouldChange) {
NSRange range = [(UITextField *)_input selectedRange];
if ([[(UITextField *)_input delegate] textField:(UITextField *)_input shouldChangeCharactersInRange:range replacementString:text]) {
[_input insertText:text];
}
} else if (_tvShouldChange) {
NSRange range = [(UITextView *)_input selectedRange];
if ([[(UITextView *)_input delegate] textView:(UITextView *)_input shouldChangeTextInRange:range replacementText:text]) {
[_input insertText:text];
}
} else {
[_input insertText:text];
}
}
// Used for a UITextField to handle the return key button
- (void)returnTapped:(UIButton *)button {
if ([_input isKindOfClass:[UITextField class]]) {
id<UITextFieldDelegate> del = [(UITextField *)_input delegate];
if ([del respondsToSelector:@selector(textFieldShouldReturn:)]) {
[del textFieldShouldReturn:(UITextField *)_input];
}
} else if ([_input isKindOfClass:[UITextView class]]) {
[_input insertText:@"\n"];
}
}
// Call this to dismiss the keyboard
- (void)dismissTapped:(UIButton *)button {
[(UIResponder *)_input resignFirstResponder];
}
// Call this for a delete/backspace key
- (void)backspaceTapped:(UIButton *)button {
if ([_input respondsToSelector:@selector(shouldChangeTextInRange:replacementText:)]) {
UITextRange *range = [_input selectedTextRange];
if ([range.start isEqual:range.end]) {
UITextPosition *newStart = [_input positionFromPosition:range.start inDirection:UITextLayoutDirectionLeft offset:1];
range = [_input textRangeFromPosition:newStart toPosition:range.end];
}
if ([_input shouldChangeTextInRange:range replacementText:@""]) {
[_input deleteBackward];
}
} else if (_tfShouldChange) {
NSRange range = [(UITextField *)_input selectedRange];
if (range.length == 0) {
if (range.location > 0) {
range.location--;
range.length = 1;
}
}
if ([[(UITextField *)_input delegate] textField:(UITextField *)_input shouldChangeCharactersInRange:range replacementString:@""]) {
[_input deleteBackward];
}
} else if (_tvShouldChange) {
NSRange range = [(UITextView *)_input selectedRange];
if (range.length == 0) {
if (range.location > 0) {
range.location--;
range.length = 1;
}
}
if ([[(UITextView *)_input delegate] textView:(UITextView *)_input shouldChangeTextInRange:range replacementText:@""]) {
[_input deleteBackward];
}
} else {
[_input deleteBackward];
}
[self updateShift];
}
@end
This class requires a category method for UITextField:
@interface UITextField (CustomKeyboard)
- (NSRange)selectedRange;
@end
@implementation UITextField (CustomKeyboard)
- (NSRange)selectedRange {
UITextRange *tr = [self selectedTextRange];
NSInteger spos = [self offsetFromPosition:self.beginningOfDocument toPosition:tr.start];
NSInteger epos = [self offsetFromPosition:self.beginningOfDocument toPosition:tr.end];
return NSMakeRange(spos, epos - spos);
}
@end
Solution 2:
I have created a full working example of a keyboard for the iPad, available on Github here:
https://github.com/lnafziger/Numberpad
Numberpad is a custom numeric keyboard for the iPad which works with both
UITextField's andUITextView's requiring no changes other than adding an instance of the Numberpad class as the inputView of the text field/view.
Features:
- It is covered under the MIT licence, so may be freely copied and used per its' terms.
- It works with UITextFields and UITextViews
- It does not require a delegate to be set.
- It automatically keeps track of which view is the first responder (so you don't have to)
- You do not have to set the size of the keyboard, or keep track of it.
- There is a shared instance that you can use for as many input views as you like, without using extra memory for each one.
Usage is as simple as including Numberpad.h and then:
theTextField.inputView = [Numberpad defaultNumberpad];
Everything else is taken care of automatically!
Either grab the two class files and the xib from Github (link above), or create the buttons (in code or in a storyboard/xib) with their actions set to the appropriate methods in the class (numberpadNumberPressed, numberpadDeletePressed, numberpadClearPressed, or numberpadDonePressed).
The following code is out of date. See the Github project for the latest code.
Numberpad.h:
#import <UIKit/UIKit.h>
@interface Numberpad : UIViewController
// The one and only Numberpad instance you should ever need:
+ (Numberpad *)defaultNumberpad;
@end
Numberpad.m:
#import "Numberpad.h"
#pragma mark - Private methods
@interface Numberpad ()
@property (nonatomic, weak) id<UITextInput> targetTextInput;
@end
#pragma mark - Numberpad Implementation
@implementation Numberpad
@synthesize targetTextInput;
#pragma mark - Shared Numberpad method
+ (Numberpad *)defaultNumberpad {
static Numberpad *defaultNumberpad = nil;
static dispatch_once_t onceToken;
dispatch_once(&onceToken, ^{
defaultNumberpad = [[Numberpad alloc] init];
});
return defaultNumberpad;
}
#pragma mark - view lifecycle
- (void)viewDidLoad {
[super viewDidLoad];
// Keep track of the textView/Field that we are editing
[[NSNotificationCenter defaultCenter] addObserver:self
selector:@selector(editingDidBegin:)
name:UITextFieldTextDidBeginEditingNotification
object:nil];
[[NSNotificationCenter defaultCenter] addObserver:self
selector:@selector(editingDidBegin:)
name:UITextViewTextDidBeginEditingNotification
object:nil];
[[NSNotificationCenter defaultCenter] addObserver:self
selector:@selector(editingDidEnd:)
name:UITextFieldTextDidEndEditingNotification
object:nil];
[[NSNotificationCenter defaultCenter] addObserver:self
selector:@selector(editingDidEnd:)
name:UITextViewTextDidEndEditingNotification
object:nil];
}
- (void)viewDidUnload {
[[NSNotificationCenter defaultCenter] removeObserver:self
name:UITextFieldTextDidBeginEditingNotification
object:nil];
[[NSNotificationCenter defaultCenter] removeObserver:self
name:UITextViewTextDidBeginEditingNotification
object:nil];
[[NSNotificationCenter defaultCenter] removeObserver:self
name:UITextFieldTextDidEndEditingNotification
object:nil];
[[NSNotificationCenter defaultCenter] removeObserver:self
name:UITextViewTextDidEndEditingNotification
object:nil];
self.targetTextInput = nil;
[super viewDidUnload];
}
#pragma mark - editingDidBegin/End
// Editing just began, store a reference to the object that just became the firstResponder
- (void)editingDidBegin:(NSNotification *)notification {
if (![notification.object conformsToProtocol:@protocol(UITextInput)]) {
self.targetTextInput = nil;
return;
}
self.targetTextInput = notification.object;
}
// Editing just ended.
- (void)editingDidEnd:(NSNotification *)notification {
self.targetTextInput = nil;
}
#pragma mark - Keypad IBActions
// A number (0-9) was just pressed on the number pad
// Note that this would work just as well with letters or any other character and is not limited to numbers.
- (IBAction)numberpadNumberPressed:(UIButton *)sender {
if (!self.targetTextInput) {
return;
}
NSString *numberPressed = sender.titleLabel.text;
if ([numberPressed length] == 0) {
return;
}
UITextRange *selectedTextRange = self.targetTextInput.selectedTextRange;
if (!selectedTextRange) {
return;
}
[self textInput:self.targetTextInput replaceTextAtTextRange:selectedTextRange withString:numberPressed];
}
// The delete button was just pressed on the number pad
- (IBAction)numberpadDeletePressed:(UIButton *)sender {
if (!self.targetTextInput) {
return;
}
UITextRange *selectedTextRange = self.targetTextInput.selectedTextRange;
if (!selectedTextRange) {
return;
}
// Calculate the selected text to delete
UITextPosition *startPosition = [self.targetTextInput positionFromPosition:selectedTextRange.start offset:-1];
if (!startPosition) {
return;
}
UITextPosition *endPosition = selectedTextRange.end;
if (!endPosition) {
return;
}
UITextRange *rangeToDelete = [self.targetTextInput textRangeFromPosition:startPosition
toPosition:endPosition];
[self textInput:self.targetTextInput replaceTextAtTextRange:rangeToDelete withString:@""];
}
// The clear button was just pressed on the number pad
- (IBAction)numberpadClearPressed:(UIButton *)sender {
if (!self.targetTextInput) {
return;
}
UITextRange *allTextRange = [self.targetTextInput textRangeFromPosition:self.targetTextInput.beginningOfDocument
toPosition:self.targetTextInput.endOfDocument];
[self textInput:self.targetTextInput replaceTextAtTextRange:allTextRange withString:@""];
}
// The done button was just pressed on the number pad
- (IBAction)numberpadDonePressed:(UIButton *)sender {
if (!self.targetTextInput) {
return;
}
// Call the delegate methods and resign the first responder if appropriate
if ([self.targetTextInput isKindOfClass:[UITextView class]]) {
UITextView *textView = (UITextView *)self.targetTextInput;
if ([textView.delegate respondsToSelector:@selector(textViewShouldEndEditing:)]) {
if ([textView.delegate textViewShouldEndEditing:textView]) {
[textView resignFirstResponder];
}
}
} else if ([self.targetTextInput isKindOfClass:[UITextField class]]) {
UITextField *textField = (UITextField *)self.targetTextInput;
if ([textField.delegate respondsToSelector:@selector(textFieldShouldEndEditing:)]) {
if ([textField.delegate textFieldShouldEndEditing:textField]) {
[textField resignFirstResponder];
}
}
}
}
#pragma mark - text replacement routines
// Check delegate methods to see if we should change the characters in range
- (BOOL)textInput:(id <UITextInput>)textInput shouldChangeCharactersInRange:(NSRange)range withString:(NSString *)string
{
if (!textInput) {
return NO;
}
if ([textInput isKindOfClass:[UITextField class]]) {
UITextField *textField = (UITextField *)textInput;
if ([textField.delegate respondsToSelector:@selector(textField:shouldChangeCharactersInRange:replacementString:)]) {
if (![textField.delegate textField:textField
shouldChangeCharactersInRange:range
replacementString:string]) {
return NO;
}
}
} else if ([textInput isKindOfClass:[UITextView class]]) {
UITextView *textView = (UITextView *)textInput;
if ([textView.delegate respondsToSelector:@selector(textView:shouldChangeTextInRange:replacementText:)]) {
if (![textView.delegate textView:textView
shouldChangeTextInRange:range
replacementText:string]) {
return NO;
}
}
}
return YES;
}
// Replace the text of the textInput in textRange with string if the delegate approves
- (void)textInput:(id <UITextInput>)textInput replaceTextAtTextRange:(UITextRange *)textRange withString:(NSString *)string {
if (!textInput) {
return;
}
if (!textRange) {
return;
}
// Calculate the NSRange for the textInput text in the UITextRange textRange:
int startPos = [textInput offsetFromPosition:textInput.beginningOfDocument
toPosition:textRange.start];
int length = [textInput offsetFromPosition:textRange.start
toPosition:textRange.end];
NSRange selectedRange = NSMakeRange(startPos, length);
if ([self textInput:textInput shouldChangeCharactersInRange:selectedRange withString:string]) {
// Make the replacement:
[textInput replaceRange:textRange withText:string];
}
}
@end