Inherits from UIView
Conforms to UIInputViewAudioFeedback
Declared in JACKeyboard.h

Overview

The JACKeyboard class is a JSON defined, custom-drawn keyboard. It is a nearly pixel-perfect replacement for Apple’s UIKeyboard.

JACKeyboard UIKeyboard
JACKeyboard JACKeyboard

The apperance and behavior of JACKeyboard is entirely customizable and is controlled by JSON configuration files. The JSON files are parsed and displayed at runtime, allowing JACKeyboard to provide several benefits, including:

  • support for languages not supported by iOS, e.g. Native American Languages or the International Phonetic Alphabet (IPA);
  • context-aware keyboards for more than Apple’s 9 chosen UIKeyboardType; and
  • in-app support for a language other than the user’s primary language, without having to enable a system wide keyboard.

Keyboard Structure

In JACKeyboard, individual keyboard keys are defined by JSON dictionaries. These dictionaries are grouped in JSON arrays, with each array representing a single row of keys. Thus, the top row of a simple English keyboard would appear as follows:

Figure 1 Sample Row

 [ {"text":"Q"} , {"text":"W"} , {"text":"E"} , {"text":"R"} , {"text":"T"} , {"text": "Y"} , …]

Each of these rows (JSON arrays) are grouped in an array, with the first element corresponding to the topmost row. So the JSON configuration file for a very simple English keyboard would be:

Figure 2 Sample Keyboard

 [
   [ {"text":"Q"} , {"text":"W"} , {"text":"E"} , {"text":"R"} , {"text":"T"} , {"text":"Y"} , …],
   [ {"text":"A"} , {"text":"S"} , {"text":"D"} , {"text":"F"} , {"text":"G"} , {"text":"H"} , …],
   [ {"text":"Z"} , {"text":"X"} , {"text":"C"} , {"text":"V"} , {"text":"B"} , {"text":"N"} , …],
   [ {"text":" "} ]
  ]

By default, JACKeyboard will automatically determine the width of each key, making every key in a row equally sized and spaced.

Defining Custom Keyboard Keys

Of course, JACKeyboard can handle more complex key configurations and key types. Below is a listing of the parameters configurable for each key. If a value is not specified, the default value is assumed.

Figure 3 JSON Key Parameters

JSON Key Accepted Values Default Value Example Example Image
text Any string. (Usually a string with a single character.) {“text”:“Ω”}
style light
dark
blue
spacebar
blankSpace 		light {“style”:“dark”,…}
type textEntry
spacebar
return
shift
delete
switchKeyboard
dismissKeyboard 		textEntry {“type”:“textEntry”,…}
modifiers Any array of strings. {“text”: “N”,
“modifiers”:[“N”,“Ñ”,“Ń”]}
width Any floating point number. 1 {“style”: “blue”,
“width”: 2.5,…}
image The name of an PNG image located in the applications default bundle.
This name should exclude the file extension (.png) and pixel density (@2x).
The image will be drawn as an alpha mask using a color corresponding to the key style. 		{“style”:“dark”,
“image”:“Globe”,…}
selectedImage See image. The value of image. {“style”:“dark”,
“image”:“UnShifted”,
“selectedImage”:“Shifted"…}
keyboardDisplayName Any string. {“type”:“spacebar”,
“style”:“spacebar”,
“keyboardDisplayName”:“Greek”}
keyboardName The name of a JSON configuration file, excluding the .json file extension. {“type”:“switchKeyboard”,
“style”:“dark”,
“keyboardName”:“QWERTY”}
font A string with the name of any iOS system font. HelveticaNeue-Bold on iPhone.
HelveticaNeue on iPad. 		{“text”:“ABC”,
“font”:“HelveticaNeue-CondensedBold”}
hasHomerowIndicator 1 or 0 on iPad.
Not supported on iPhone.		 0 {“text”:“F”,
“hasHomerowIndicator”:1}

The configuration file provided must be a valid JSON file capable of being parsed by NSJSONSerialization. If a keyboard configuration file is not loading, verify the JSON using JSONLint. If you would like to encode additional data in a JSON file, JACKeyboard will gracefully ignore non-standard key-value pairs.

Warning: JACKeyboard does not support auto-correct. Because auto-correct is implemented at a very low level in the system keyboard and is language specific, it is unlikely that JACKeyboard will gain this feature.

Tasks

Designated Initializer

Setup or Change Keyboard Layout

Responding to User Initiated Keyboard Change

Keyboard-Wide Configuration

Custom Return Key Behavior

  •   returnKeyHandler

    A block to be called when the user selects the return key

         property
  •   textField

    A weakly retained instance of the text field being typed into.

         property

Properties

capitalization

An enumerated data type that sets the state of the keyboard’s shift key.

@property (nonatomic) JACKeyboardCapitalization capitalization

Discussion

You can both write to this property to change the current capitalization state, or read from it, to respond to user input.

The capitalization should be one of the following:

 typedef enum{
   JACKeyboardCapitalizationNone,
   JACKeyboardCapitalizationShift,
   JACKeyboardCapitalizationCapsLock
 }JACKeyboardCapitalization;

Declared In

JACKeyboard.h

caseSensitiveKeyDisplay

A boolean value to indicate whether the keys should change appearance when the shift key is selected.

@property (nonatomic) BOOL caseSensitiveKeyDisplay

Discussion

The default value is NO. Enabling this feature incurs a non-trivial performance penalty, because the keyboard has to be redrawn after every shift key state change.

Declared In

JACKeyboard.h

currentKeyboardChangeHandler

A block to be called when the keyboard being displayed to the user changes.

@property (nonatomic, strong) JACKeyboardCurrentKeyboardChangeHandler currentKeyboardChangeHandler

Discussion

The block should have the following format:

typedef void (^JACKeyboardCurrentKeyboardChangeHandler)(JACKeyboard keyboard, NSString newKeyboardFileName);

Declared In

JACKeyboard.h

currentKeyboardFileName

The name of the keyboard that is currently being displayed to the user.

@property (nonatomic, readonly) NSString *currentKeyboardFileName

Declared In

JACKeyboard.h

returnKeyHandler

A block to be called when the user selects the return key

@property (nonatomic, strong) JACKeyboardReturnKeyHandler returnKeyHandler

Discussion

When the user taps the return key on the keyboard, this block is invoked on the main thread with the following signature:

typedef void (^JACKeyboardReturnKeyHandler)(JACKeyboard *keyboard, NSDictionary *returnKeyJSONDictionary);

Some suggested implementations of behaviors to implement:

//Insert a new line
_keyboard.returnKeyHandler = ^(JACKeyboard *keyboard, NSDictionary *returnKeyDictionary){  
    [keyboard.textField insertText:@"\n"];  
};

//Update the UI with input text
_keyboard.returnKeyHandler = ^(JACKeyboard *keyboard, NSDictionary *returnKeyDictionary){  
    NSString *searchTerm = keyboard.textField.text;
    //do something with the search term
};

//Copy the input text to the pasteboard
_keyboard.returnKeyHandler = ^(JACKeyboard *keyboard, NSDictionary *returnKeyDictionary){  
    [UIPasteboard generalPasteboard].string = keyboard.textField.text;
};

Warning: This block should never retain the input text field (including calls to self.text from within a UITextField subclass). This would cause a retain cycle. Instead, rely on JACKeyboard’s weakly retained textField property.

Declared In

JACKeyboard.h

textField

A weakly retained instance of the text field being typed into.

@property (nonatomic, weak) id<UIKeyInput> textField

Discussion

Utilize this property in the returnKeyHandler to prevent a retain cycle.

Warning: Because JACKeyboard programatically changes the contents of the textField, a UITextFieldDelegate will not receive notification of changes to the textField. If you would like to respond to changes in textField, it is reccomended that your subclass of UITextField override -(void)insertText: and -(void)deleteBackward. Note that UIKit is not KVO compliant, so you cannot observe changes to the textField’s text property.

Declared In

JACKeyboard.h

Instance Methods

configureKeyboardWithFile:

Specifies the keyboard configuration file to be displayed.

- (void)configureKeyboardWithFile:(NSString *)fileName

Parameters

fileName

The name of a file, without the .json file extension, located in the application’s main bundle.

Discussion

This may be called at any time to change the default keyboard.

Declared In

JACKeyboard.h

configureKeyboardWithFiles:

Specifies a set of keyboard configuration files to be displayed.

- (void)configureKeyboardWithFiles:(NSArray *)keyboardFileNames

Parameters

keyboardFileNames

An NSArray of NSStrings corresponding to keyboard configuration file names.

Discussion

When the user taps the change keyboard button, (normally ), JACKeyboard will cycle through these keyboards, displaying the name of each one momentarily on the spacebar key.

Declared In

JACKeyboard.h

initWithTextField:

This is the designated initializer for JACKeyboard.

- (id)initWithTextField:(id<UIKeyInput>)textField

Parameters

textField

The text field that the keyboard will type into. Normally a UITextField.

Return Value

The initialized keyboard.

Discussion

Normally this method will be invoked in the -inputView method of a UITextView subclass. An example implementation is shown below.

- (UIView *)inputView {
    JACKeyboard *keyboard = [[JACMessageBarKeyboard alloc] initWithTextField:self];
    [keyboard configureKeyboardWithFile:@"QWERTY"];   //QWERTY.json in the main bundle
    keyboard.returnKeyHandler = ^(JACKeyboard *aKeyboard, NSDictionary *returnKeyDictionary){  [aKeyboard.textField insertText:@"\n"];  };
    return keyboard;
}

Declared In

JACKeyboard.h