iOS Guides

Alerts

An alert is a pop-up window showing a short message with optional buttons. When an alert is activated, it will abort any SDL operation that is in-progress, except the already-in-progress alert. If an alert is issued while another alert is still in progress, the newest alert will simply be ignored.

Depending the platform, an alert can have up to three lines of text, a progress indicator (e.g. a spinning wheel or hourglass), and up to four soft buttons.

Alert Layouts

Alert With No Soft Buttons

Generic - Alert

Note

If no soft buttons are added to an alert some OEMs may add a default "cancel" or "close" button.

Alert With Soft Buttons

Generic - Alert

Creating the Alert

Text

Objective-C

SDLAlert *alert = [[SDLAlert alloc] initWithAlertText:<#NSString#> softButtons:<#[SDLSoftButton]#> playTone:<#BOOL#> ttsChunks:<#[SDLTTSChunk]#> alertIcon:<#SDLImage#> cancelID:<#UInt32#>];

Swift

let alert = SDLAlert(alertText: <#String?#>, softButtons: <#[SDLSoftButton]?#>, playTone: <#Bool#>, ttsChunks: <#[SDLTTSChunk]?#>, alertIcon: <#SDLImage?#>, cancelID: <#UInt32#>)

Buttons

Objective-C

SDLSoftButton *button1 = [[SDLSoftButton alloc] initWithType:SDLSoftButtonTypeText text:@"<#Button Text#>" image:nil highlighted:false buttonId:<#Soft Button Id#> systemAction:SDLSystemActionDefaultAction handler:^(SDLOnButtonPress *_Nullable buttonPress, SDLOnButtonEvent *_Nullable buttonEvent) {
    if (buttonPress == nil) {
        return;
    }
    <#Button has been pressed#>
}];

SDLSoftButton *button2 = [[SDLSoftButton alloc] initWithType:SDLSoftButtonTypeText text:<#Button Text#> image:nil highlighted:false buttonId:<#Soft Button Id#> systemAction:SDLSystemActionDefaultAction handler:^(SDLOnButtonPress *_Nullable buttonPress, SDLOnButtonEvent *_Nullable buttonEvent) {
    if (buttonPress == nil) {
        return;
    }
    <#Button has been pressed#>
}];

alert.softButtons = @[button1, button2];

Swift

let button1 = SDLSoftButton(type: .text, text: <#Button Text#>, image: nil, highlighted: false, buttonId: <#Soft Button Id#>, systemAction: .defaultAction, handler: { buttonPress, buttonEvent in
    guard buttonPress != nil else { return }
    <#Button has been pressed#>
})

let button2 = SDLSoftButton(type: .text, text: <#Button Text#>, image: nil, highlighted: false, buttonId: <#Soft Button Id#>, systemAction: .defaultAction, handler: { buttonPress, buttonEvent in
    guard buttonPress != nil else { return }
    <#Button has been pressed#>
})

alert.softButtons = [button1, button2]

Alert Icon

An alert can include a custom or static (built-in) image that will be displayed within the alert. Before you add the image to the alert make sure the image is uploaded to the head unit using the SDLFileManager. If the image is already uploaded, you can set the alertIcon property.

Generic - Alert

Objective-C

alert.alertIcon = [[SDLImage alloc] initWithName:<#artworkName#> isTemplate:YES];

Swift

alert.alertIcon = SDLImage(name: <#artworkName#>, isTemplate: true)

Timeouts

An optional timeout can be added that will dismiss the alert when the duration is over. Typical timeouts are between 3 and 10 seconds. If omitted a default of 5 seconds is used.

Objective-C

// Duration timeout is in milliseconds
alert.duration = @(4000);

Swift

// Duration timeout is in milliseconds
alert.duration = NSNumber(4000)

Progress Indicator

Not all OEMs support a progress indicator. If supported, the alert will show an animation that indicates that the user must wait (e.g. a spinning wheel or hourglass, etc). If omitted, no progress indicator will be shown.

Objective-C

alert.progressIndicator = @YES;

Swift

alert.progressIndicator = NSNumber(true)

Text-To-Speech

An alert can also speak a prompt or play a sound file when the alert appears on the screen. This is done by setting the ttsChunks parameter.

Text

Objective-C

alert.ttsChunks = [SDLTTSChunk textChunksFromString:@"<#Text to speak#>"];

Swift

alert.ttsChunks = SDLTTSChunk.textChunks(from: "<#Text to speak#>")

Sound File

The ttsChunks parameter can also take a file to play/speak. For more information on how to upload the file please refer to the Playing Audio Indications guide.

Objective-C

 alert.ttsChunks = [SDLTTSChunk fileChunksWithName:@"<#Name#>"];

Swift

 alert.ttsChunks = SDLTTSChunk.fileChunks(withName: "<#Name#>")

Play Tone

To play the alert tone when the alert appears and before the text-to-speech is spoken, set playTone to true.

Objective-C

alert.playTone = @YES;

Swift

alert.playTone = NSNumber(true)

Showing the Alert

Objective-C

[self.sdlManager sendRequest:alert withResponseHandler:^(SDLRPCRequest *request, SDLRPCResponse *response, NSError *error) {
    if (!response.success.boolValue) { 
        // Print out the error if there is one and return early
        return;
    }
    <#Alert was shown successfully#>
}];

Swift

sdlManager.send(request: alert) { (request, response, error) in
    guard response?.success.boolValue == true else { return }
    <#Alert was shown successfully#>
}

Dismissing the Current Alert

Objective-C

SDLCancelInteraction *cancelInteraction = [SDLCancelInteraction alert];
[self.sdlManager sendRequest:cancelInteraction withResponseHandler:^(__kindof SDLRPCRequest * _Nullable request, __kindof SDLRPCResponse * _Nullable response, NSError * _Nullable error) {
    if (!response.success.boolValue) { 
        // Print out the error if there is one and return early
        return;
    }
    <#The alert was canceled successfully#>
}];

Swift

let cancelInteraction = SDLCancelInteraction.alert()
sdlManager.send(request: cancelInteraction) { (request, response, error) in
    guard response?.success.boolValue == true else { return }
    <#The alert was canceled successfully#>
}

View on GitHub.com

Previous Section Next Section