Presenting a keyboard or a popup menu with a search field requires you to implement the SDLKeyboardDelegate
. Note that the initialText
in the keyboard case often acts as "placeholder text" and not as true initial text.
You should present a keyboard to users when your app contains a "search" field. For example, in a music player app, you may want to give the user a way to search for a song or album. A keyboard could also be useful in an app that displays nearby points of interest, or in other situations.
Keyboards are unavailable for use in many countries when the driver is distracted. This is often when the vehicle is moving above a certain speed, such as 5 miles per hour. This will be automatically managed by the system. Your keyboard may be disabled or an error returned if the driver is distracted.
// Returns a cancelID and presents the keyboard NSNumber<SDLInt> *cancelID = [self.sdlManager.screenManager presentKeyboardWithInitialText:<#(nonnull NSString *)#> delegate:<#(nonnull id<SDLKeyboardDelegate>)#>];
// Returns a cancelID and presents the keyboard let cancelID = sdlManager.screenManager.presentKeyboard(withInitialText: <#String#>, delegate: <#SDLKeyboardDelegate#>)
Using the SDLKeyboardDelegate
is required for popup keyboards and popup menus with search. It involves two required methods (for handling the user's input and the keyboard's unexpected abort), as well as several optional methods for additional functionality.
#pragma mark - SDLKeyboardDelegate /// Required Methods - (void)keyboardDidAbortWithReason:(SDLKeyboardEvent)event { if ([event isEqualToEnum:SDLKeyboardEventCancelled]) { <#The user cancelled the keyboard interaction#> } else if ([event isEqualToEnum:SDLKeyboardEventAborted]) { <#The system aborted the keyboard interaction#> } } - (void)userDidSubmitInput:(NSString *)inputText withEvent:(SDLKeyboardEvent)source { if ([source isEqualToEnum:SDLKeyboardEventSubmitted]) { <#The user submitted some text with the keyboard#> } else if ([source isEqualToEnum:SDLKeyboardEventVoice]) { <#The user decided to start voice input, you should start an AudioPassThru session if supported#> } } /// Optional Methods - (void)updateAutocompleteWithInput:(NSString *)currentInputText autoCompleteResultsHandler:(SDLKeyboardAutoCompleteResultsHandler)resultsHandler { <#Check the input text and return an array of autocomplete results#> resultsHandler(@[<#String results to be displayed#>]); } - (void)updateCharacterSetWithInput:(NSString *)currentInputText completionHandler:(SDLKeyboardCharacterSetCompletionHandler)completionHandler { <#Check the input text and return a set of characters to allow the user to enter#> } - (void)keyboardDidSendEvent:(SDLKeyboardEvent)event text:(NSString *)currentInputText { <#This is sent upon every event, such as keypresses, cancellations, and aborting#> } - (SDLKeyboardProperties *)customKeyboardConfiguration { <#Use an alternate keyboard configuration. The keypressMode, limitedCharacterSet, and autoCompleteText will be overridden by the screen manager#> }
extension <#Class Name#>: SDLKeyboardDelegate { /// Required Methods func keyboardDidAbort(withReason event: SDLKeyboardEvent) { switch event { case .cancelled: <#The user cancelled the keyboard interaction#> case .aborted: <#The system aborted the keyboard interaction#> default: break } } func userDidSubmitInput(_ inputText: String, withEvent source: SDLKeyboardEvent) { switch source { case .voice: <#The user decided to start voice input, you should start an AudioPassThru session if supported#> case .submitted: <#The user submitted some text with the keyboard#> default: break } } /// Optional Methods func updateAutocomplete(withInput currentInputText: String, autoCompleteResultsHandler resultsHandler: @escaping SDLKeyboardAutoCompleteResultsHandler) { <#Check the input text and return an array of autocomplete results#> resultsHandler([<#String results to be displayed#>]); } func updateCharacterSet(withInput currentInputText: String, completionHandler: @escaping SDLKeyboardCharacterSetCompletionHandler) { <#Check the input text and return a set of characters to allow the user to enter#> } func keyboardDidSendEvent(_ event: SDLKeyboardEvent, text currentInputText: String) { <#This is sent upon every event, such as keypresses, cancellations, and aborting#> } func customKeyboardConfiguration() -> SDLKeyboardProperties { <#Use an alternate keyboard configuration. The keypressMode, limitedCharacterSet, and autoCompleteText will be overridden by the screen manager#> } }
You can dismiss a displayed keyboard before the timeout has elapsed by sending a CancelInteraction
request. If you presented the keyboard using the screen manager, you can dismiss the choice set by calling dismissKeyboard
with the cancelID
that was returned (if one was returned) when presenting.
If connected to older head units that do not support this feature, the cancel request will be ignored, and the keyboard will persist on the screen until the timeout has elapsed or the user dismisses it by making a selection.
// Use the saved cancelID from above to dismiss the keyboard [self.sdlManager.screenManager dismissKeyboardWithCancelID:cancelID];
// Use the saved cancelID from above to dismiss the keyboard sdlManager.screenManager.dismissKeyboard(withCancelID: cancelID)
If you don't want to use the SDLScreenManager
, you can do this manually using the PerformInteraction
RPC request. As this is no longer a recommended course of action, we will leave it to you to figure out how to manually do it.