Template Images

You can easily display text, images, and buttons using the SDLScreenManager. To update the UI, simply give the manager your new data and (optionally) sandwich the update between the manager's beginUpdates and endUpdatesWithCompletionHandler methods.

Image Fields

Showing Images

Creating an SDLArtwork

Create an SDLArtwork object which can be manually uploaded or set into the SDLScreenManager and automatically uploaded. An SDLArtwork includes information about whether the image should be persisted between vehicle startups, whether the image is a template image and should be re-colored, and more.

UIImage *image = [UIImage imageNamed:@"<#ArtworkName#>"]
SDLArtwork *artwork = [SDLArtwork artworkWithImage:image asImageFormat:SDLArtworkImageFormatPNG /* or SDLArtworkImageFormatJPG */];

let image = UIImage(named: <#ArtworkName#>)!  
let artwork = SDLArtwork(image: UIImage(named: image, persistent: true, as: .PNG /* or .JPG */)

Setting Primary Graphic

[self.sdlManager.screenManager beginUpdates];
self.sdlManager.screenManager.primaryGraphic = <#SDLArtwork#>;
[self.sdlManager.screenManager endUpdatesWithCompletionHandler:^(NSError * _Nullable error) {
    if (error != nil) {
        <#Error Updating UI#>
    } else {
        <#Update to UI was Successful#>
    }
}];

sdlManager.screenManager.beginUpdates()
sdlManager.screenManager.primaryGraphic = <#SDLArtwork#>
sdlManager.screenManager.endUpdates { (error) in
    if error != nil {
        <#Error Updating UI#>
    } else {
        <#Update to UI was Successful#>
    }
}

Removing Images

To remove an image from the screen you just need to set the screen manager property to nil.

self.sdlManager.screenManager.primaryGraphic = nil;

sdlManager.screenManager.primaryGraphic = nil

Overwriting Images

When a file is to be uploaded to the module, the library checks if a file with the same name has already been uploaded to module and skips the upload if it can. For cases where an image by the same name needs to be re-uploaded, the SDLArtwork / SDLFile's overwrite property should be used. Setting overwrite to true before passing the image to a SDLScreenManager method such as primaryGraphic and secondaryGraphic will force the image to be re-uploaded. This includes methods such as preloadChoices:withCompletionHandler: where the arguments passed in contain images.

Note

Please note that many production modules on the road do not refresh the HMI with the new image if the file name has not changed. If you want the image to refresh on the screen immediately, we suggest using two image names and toggling back and forth between the names each time you update the image.

This issue may also extend to menus, alerts, and other UI features even if they're not on-screen at the time. Because of these issues, we do not recommend that you try to overwrite an image. Instead, you can delete an image file using the SDLFileManager and re-upload it once the deletion completes, or you may use a different file name.

Templating Images (RPC v5.0+)

Templated images are tinted by Core so the image is visible regardless of whether your user has set the head unit to day or night mode. For example, if a head unit is in night mode with a dark theme (see Customizing the Template section for more details on how to customize theme colors), then your templated images will be displayed as white. In the day theme, the image will automatically change to black.

Soft buttons, menu icons, and primary / secondary graphics can all be templated. A template image works very much like it does on iOS and in fact, it uses the same API as iOS. Any SDLArtwork created with a UIImage that has a renderingMode of alwaysTemplate will be templated via SDL as well. Images that you wish to template must be PNGs with a transparent background and only one color for the icon. Therefore, templating is only useful for things like icons and not for images that must be rendered in a specific color.

Templated Images Example

In the screenshots below, the shuffle and repeat icons have been templated. In night mode, the icons are tinted white and in day mode the icons are tinted black.

Night Mode

Day Mode

UIImage *image = [[UIImage imageNamed:@"<#ArtworkName#>"] imageWithRenderingMode:UIImageRenderingModeAlwaysTemplate];
SDLArtwork *artwork = [SDLArtwork artworkWithImage:image asImageFormat:SDLArtworkImageFormatPNG];

let image = UIImage(named: "<#ArtworkName#>")?.withRenderingMode(.alwaysTemplate)
let artwork = SDLArtwork(image: image, persistent: true, as: .PNG)

Static Icons

Static icons are pre-existing images on the remote system that you may reference and use in your own application. Each OEM will design their own custom static icons but you can get an overview of the available icons from the icons designed for the open source Generic HMI. Static icons are fully supported by the screen manager via an SDLArtwork initializer. Static icons can be used in primary and secondary graphic fields, soft button image fields, and menu icon fields.

SDLArtwork *staticIconArt = [[SDLArtwork alloc] initWithStaticIcon:SDLStaticIconNameAlbum];

let staticIconArt = SDLArtwork(staticIcon: .album)