SDLScreenManager Class Reference

textField1

The top text field within a template layout. Pass an empty string \@"" to clear the text field.

If the system does not support a full 4 fields, this will automatically be concatenated and properly send the field available.

If 3 lines are available: [field1, field2, field3 - field 4]

If 2 lines are available: [field1 - field2, field3 - field4]

If 1 line is available: [field1 - field2 - field3 - field4]

Objective-C

@property (nonatomic, copy, nullable) NSString *textField1;

Swift

var textField1: String? { get set }

textField2

The second text field within a template layout. Pass an empty string \@"" to clear the text field.

If the system does not support a full 4 fields, this will automatically be concatenated and properly send the field available.

If 3 lines are available: [field1, field2, field3 - field 4]

If 2 lines are available: [field1 - field2, field3 - field4]

If 1 line is available: [field1 - field2 - field3 - field4]

Objective-C

@property (nonatomic, copy, nullable) NSString *textField2;

Swift

var textField2: String? { get set }

textField3

The third text field within a template layout. Pass an empty string \@"" to clear the text field.

If the system does not support a full 4 fields, this will automatically be concatenated and properly send the field available.

If 3 lines are available: [field1, field2, field3 - field 4]

If 2 lines are available: [field1 - field2, field3 - field4]

If 1 line is available: [field1 - field2 - field3 - field4]

Objective-C

@property (nonatomic, copy, nullable) NSString *textField3;

Swift

var textField3: String? { get set }

textField4

The fourth text field within a template layout. Pass an empty string \@"" to clear the text field.

If the system does not support a full 4 fields, this will automatically be concatenated and properly send the field available.

If 3 lines are available: [field1, field2, field3 - field 4]

If 2 lines are available: [field1 - field2, field3 - field4]

If 1 line is available: [field1 - field2 - field3 - field4]

Objective-C

@property (nonatomic, copy, nullable) NSString *textField4;

Swift

var textField4: String? { get set }

mediaTrackTextField

The media text field available within the media layout. Often less emphasized than textField(1-4)

Objective-C

@property (nonatomic, copy, nullable) NSString *mediaTrackTextField;

Swift

var mediaTrackTextField: String? { get set }

primaryGraphic

The primary graphic within a template layout

Objective-C

@property (nonatomic, strong, nullable) SDLArtwork *primaryGraphic;

Swift

var primaryGraphic: SDLArtwork? { get set }

secondaryGraphic

A secondary graphic used in some template layouts

Objective-C

@property (nonatomic, strong, nullable) SDLArtwork *secondaryGraphic;

Swift

var secondaryGraphic: SDLArtwork? { get set }

textAlignment

What alignment textField(1-4) should use

Objective-C

@property (nonatomic, copy) SDLTextAlignment _Nonnull textAlignment;

Swift

var textAlignment: SDLTextAlignment { get set }

textField1Type

The type of data textField1 describes

Objective-C

@property (nonatomic, copy, nullable) SDLMetadataType textField1Type;

Swift

var textField1Type: SDLMetadataType? { get set }

textField2Type

The type of data textField2 describes

Objective-C

@property (nonatomic, copy, nullable) SDLMetadataType textField2Type;

Swift

var textField2Type: SDLMetadataType? { get set }

textField3Type

The type of data textField3 describes

Objective-C

@property (nonatomic, copy, nullable) SDLMetadataType textField3Type;

Swift

var textField3Type: SDLMetadataType? { get set }

textField4Type

The type of data textField4 describes

Objective-C

@property (nonatomic, copy, nullable) SDLMetadataType textField4Type;

Swift

var textField4Type: SDLMetadataType? { get set }

title

The title of the current template layout.

Objective-C

@property (nonatomic, copy, nullable) NSString *title;

Swift

var title: String? { get set }

softButtonObjects

The current list of soft buttons within a template layout. Set this array to change the displayed soft buttons.

Objective-C

@property (nonatomic, copy) NSArray<SDLSoftButtonObject *> *_Nonnull softButtonObjects;

Swift

var softButtonObjects: [SDLSoftButtonObject] { get set }

menuConfiguration

Configures the layout of the menu and sub-menus. If set after a menu already exists, the existing main menu layout will be updated.

If set menu layouts don’t match available menu layouts in WindowCapability, an error log will be emitted and the layout will not be set.

Setting this parameter will send a message to the remote system. This value will be set immediately, but if that message is rejected, the original value will be re-set and an error log will be emitted.

This only works on head units supporting RPC spec version 6.0 and newer. If the connected head unit does not support this feature, a warning log will be emitted and nothing will be set.

Objective-C

@property (nonatomic, strong) SDLMenuConfiguration *_Nonnull menuConfiguration;

Swift

var menuConfiguration: SDLMenuConfiguration { get set }

menu

The current list of menu cells displayed in the app’s menu.

WARNING: If two or more cells in this array are duplicates – they contain all of the same data – the menu will not be set. Each list of subCells and the main menu are compared separately, which means you can have duplicate cells between the main menu and a sub cell list without a conflict occurring.

WARNING: If two or more cells contain the same title but are otherwise distinctive, unique identifiers will be appended in the style (2), (3), (4), etc. to those cells’ title. The same rules apply to duplicate titles as apply to complete duplicates above: the titles can be duplicates between different array lists without a conflict.

WARNING: If any two cells contain the same voice command string in their voiceCommands list, the menu will not be set. Note that unlike the two warnings above, these lists are not checked separately. If you have the same voice command in a cell of the main menu and a sub cell, it will not be set.

Objective-C

@property (nonatomic, copy) NSArray<SDLMenuCell *> *_Nonnull menu;

Swift

var menu: [SDLMenuCell] { get set }

dynamicMenuUpdatesMode

Change the mode of the dynamic menu updater to be enabled, disabled, or enabled on known compatible head units.

The current status for dynamic menu updates. A dynamic menu update allows for smarter building of menu changes. If this status is set to SDLDynamicMenuUpdatesModeForceOn, menu updates will only create add commands for new items and delete commands for items no longer appearing in the menu. This helps reduce possible RPCs failures as there will be significantly less commands sent to the HMI.

If set to SDLDynamicMenuUpdatesModeForceOff, menu updates will work the legacy way. This means when a new menu is set the entire old menu is deleted and add commands are created for every item regardless if the item appears in both the old and new menu. This method is RPCs heavy and may cause some failures when creating and updating large menus.

We recommend using either SDLDynamicMenuUpdatesModeOnWithCompatibility or SDLDynamicMenuUpdatesModeForceOn. SDLDynamicMenuUpdatesModeOnWithCompatibility turns dynamic updates off for head units that we know have poor compatibility with dynamic updates (e.g. they have bugs that cause menu items to not be placed correctly).

Objective-C

@property (nonatomic) SDLDynamicMenuUpdatesMode dynamicMenuUpdatesMode;

Swift

var dynamicMenuUpdatesMode: SDLDynamicMenuUpdatesMode { get set }

voiceCommands

The current list of voice commands available for the user to speak and be recognized by the IVI’s voice recognition engine.

Objective-C

@property (nonatomic, copy) NSArray<SDLVoiceCommand *> *_Nonnull voiceCommands;

Swift

var voiceCommands: [SDLVoiceCommand] { get set }

keyboardConfiguration

The default keyboard configuration, this can be additionally customized by each SDLKeyboardDelegate.

Objective-C

@property (nonatomic, strong, null_resettable) SDLKeyboardProperties *keyboardConfiguration;

Swift

var keyboardConfiguration: SDLKeyboardProperties! { get set }

preloadedChoices

Cells will be hashed by their text, image names, and VR command text. When assembling an SDLChoiceSet, you can pull objects from here, or recreate them. The preloaded versions will be used so long as their text, image names, and VR commands are the same.

Objective-C

@property (nonatomic, copy, readonly) NSSet<SDLChoiceCell *> *_Nonnull preloadedChoices;

Swift

var preloadedChoices: Set<AnyHashable> { get }

-initWithConnectionManager:fileManager:systemCapabilityManager:

Initialize a screen manager

Objective-C

- (nonnull instancetype)
    initWithConnectionManager:
        (nonnull id<SDLConnectionManagerType>)connectionManager
                  fileManager:(nonnull SDLFileManager *)fileManager
      systemCapabilityManager:
          (nonnull SDLSystemCapabilityManager *)systemCapabilityManager;

Parameters

connectionManager

The connection manager used to send RPCs

fileManager

The file manager used to upload files

systemCapabilityManager

The system capability manager object for reading window capabilities

-initWithConnectionManager:fileManager:systemCapabilityManager:permissionManager:

Initialize a screen manager

Objective-C

- (nonnull instancetype)
    initWithConnectionManager:
        (nonnull id<SDLConnectionManagerType>)connectionManager
                  fileManager:(nonnull SDLFileManager *)fileManager
      systemCapabilityManager:
          (nonnull SDLSystemCapabilityManager *)systemCapabilityManager
            permissionManager:(nonnull SDLPermissionManager *)permissionManager;

Parameters

connectionManager

The connection manager used to send RPCs

fileManager

The file manager used to upload files

systemCapabilityManager

The system capability manager object for reading window capabilities

permissionManager

The permission manager object for checking RPC permissions

-startWithCompletionHandler:

Starts the manager and all sub-managers

Objective-C

- (void)startWithCompletionHandler:
    (nonnull void (^)(NSError *_Nullable))handler;

Swift

func start() async throws

Parameters

handler

The handler called when setup is complete

-stop

Stops the manager.

Objective-C

- (void)stop;

Swift

func stop()

-beginUpdates

Delays all screen updates until endUpdatesWithCompletionHandler: is called.

Objective-C

- (void)beginUpdates;

Swift

func beginUpdates()

-endUpdates

Pairs with beginUpdates: to batch text, graphic, and layout changes into a single update with a callback when the update is complete.

Update text fields with new text set into the text field properties, updates the primary and secondary images with new image(s) if new one(s) been set, and updates the template if one was changed using changeLayout:withCompletionHandler:.

NOTE: The handler in changeLayout:withCompletionHandler: will not be called if the update is batched into this update.

Objective-C

- (void)endUpdates;

Swift

func endUpdates()

-endUpdatesWithCompletionHandler:

Pairs with beginUpdates: to batch text, graphic, and layout changes into a single update with a callback when the update is complete.

Update text fields with new text set into the text field properties, updates the primary and secondary images with new image(s) if new one(s) been set, and updates the template if one was changed using changeLayout:withCompletionHandler:.

NOTE: The handler in changeLayout:withCompletionHandler: will not be called if the update is batched into this update.

NOTE: If this update returns an error, it may have been superseded by another update. This means that it was cancelled while in-progress because another update was requested, whether batched or not. Check for error domain SDLErrorDomainTextAndGraphicManager and code SDLTextAndGraphicManagerErrorPendingUpdateSuperseded to determine if your update was superseded. Any other error should represent a rejection of your data to be presented by the head unit. Note that if your update is superseded, it’s possible that the update will succeed or fail later. If you have set a handler for your update which superseded this update, the error or success will be represented there.

Objective-C

- (void)endUpdatesWithCompletionHandler:
    (nullable SDLScreenManagerUpdateCompletionHandler)handler;

Swift

func endUpdates() async throws

Parameters

handler

A handler run when the fields have finished updating, with an error if the update failed. This handler may be called multiple times when the text update is sent and the image update is sent.

-changeLayout:withCompletionHandler:

Change the current layout to a new layout and optionally update the layout’s night and day color schemes. The values set for the text, graphics, buttons and template title persist between layout changes. To update the text, graphics, buttons and template title at the same time as the template, batch all the updates between beginUpdates and endUpdates. If the layout update fails while batching, then the updated text, graphics, buttons or template title will also not be updated.

If you are connected on a < v6.0 connection and batching the update, the layout will be updated, then the text and graphics will be updated. If you are connected on a >= v6.0 connection, the layout will be updated at the same time that the text and graphics are updated.

If this update is batched between beginUpdates and endUpdatesWithCompletionHandler:, the completion handler here will not be called. Use the completion handler on endUpdatesWithCompletionHandler:

NOTE: If this update returns an error, it may have been superseded by another update. This means that it was cancelled while in-progress because another update was requested, whether batched or not. Check for error domain SDLErrorDomainTextAndGraphicManager and code SDLTextAndGraphicManagerErrorPendingUpdateSuperseded to determine if your update was superseded. Any other error should represent a rejection of your data to be presented by the head unit. Note that if your update is superseded, it’s possible that the update will succeed or fail later. If you have set a handler for your update which superseded this update, the error or success will be represented there.

Objective-C

- (void)changeLayout:(nonnull SDLTemplateConfiguration *)templateConfiguration
    withCompletionHandler:
        (nullable SDLScreenManagerUpdateCompletionHandler)handler;

Swift

func changeLayout(_ templateConfiguration: SDLTemplateConfiguration) async throws

Parameters

templateConfiguration

The new configuration of the template, including the layout and color scheme.

handler

A handler that will be called when the layout change finished.

-softButtonObjectNamed:

Retrieve a SoftButtonObject based on its name.

Objective-C

- (nullable SDLSoftButtonObject *)softButtonObjectNamed:
    (nonnull NSString *)name;

Swift

func softButtonObjectNamed(_ name: String) -> SDLSoftButtonObject?

Parameters

name

The name of the button

-subscribeButton:withUpdateHandler:

Subscribes to a subscribe button. The update handler will be called when the button has been selected. If there is an error subscribing to the subscribe button it will be returned in the error parameter of the updateHandler.

Objective-C

- (nonnull id<NSObject>)subscribeButton:(nonnull SDLButtonName)buttonName
                      withUpdateHandler:
                          (nonnull SDLSubscribeButtonHandler)updateHandler;

Swift

func subscribeButton(_ buttonName: SDLButtonName, withUpdateHandler updateHandler: @escaping SDLSubscribeButtonHandler) -> NSObjectProtocol

Parameters

buttonName

The name of the hard button to subscribe to

updateHandler

The block run when the subscribe button is selected

-subscribeButton:withObserver:selector:

Subscribes to a subscribe button. The selector will be called when the button has been selected. If there is an error subscribing to the subscribe button it will be returned in the error parameter of the selector.

The selector supports the following parameters:

1. A selector with no parameters. The observer will be notified when a button press occurs (it will not know if a short or long press has occurred).

2. A selector with one parameter: (SDLButtonName). The observer will be notified when a button press occurs (both a short and long press will trigger the selector, but it will not be able to distinguish between them). It will not be notified of button events.

3. A selector with two parameters: (SDLButtonName, NSError). The observer will be notified when a button press occurs (both a short and long press will trigger the selector, but it will not be able to distinguish between them). It will not be notified of button events.

4. A selector with three parameters: (SDLButtonName, NSError, SDLOnButtonPress). The observer will be notified when a long or short button press occurs (and can distinguish between a short or long press), but will not be notified of individual button events.

5. A selector with four parameters: (SDLButtonName, NSError, SDLOnButtonPress, SDLOnButtonEvent). The observer will be notified when any button press or any button event occurs (and can distinguish between them).

To unsubscribe from the hard button, call unsubscribeButton:withObserver:withCompletionHandler:.

Objective-C

- (void)subscribeButton:(nonnull SDLButtonName)buttonName
           withObserver:(nonnull id<NSObject>)observer
               selector:(nonnull SEL)selector;

Swift

func subscribeButton(_ buttonName: SDLButtonName, withObserver observer: NSObjectProtocol, selector: Selector)

Parameters

buttonName

The name of the hard button to subscribe to

observer

The object that will have selector called whenever the button has been selected

selector

The selector on observer that will be called whenever the button has been selected

-unsubscribeButton:withObserver:withCompletionHandler:

Unsubscribes to a subscribe button. Please note that if a subscribe button has multiple subscribers the observer will no longer get notifications, however, the app will still be subscribed to the hard button until the last subscriber is removed.

Objective-C

- (void)unsubscribeButton:(nonnull SDLButtonName)buttonName
             withObserver:(nonnull id<NSObject>)observer
    withCompletionHandler:
        (nonnull SDLScreenManagerUpdateCompletionHandler)completionHandler;

Swift

func unsubscribeButton(_ buttonName: SDLButtonName, withObserver observer: NSObjectProtocol) async throws

Parameters

buttonName

The name of the hard button to subscribe to

observer

The object that will be unsubscribed. If a block was subscribed, the return value should be passed. If a selector was subscribed, the observer object should be passed

completionHandler

A handler called when the observer has been unsubscribed to the hard button

-preloadChoices:withCompletionHandler:

Preload cells to the head unit. This will greatly reduce the time taken to present a choice set. Any already matching a choice already on the head unit will be ignored. You do not need to wait until the completion handler is called to present a choice set containing choices being loaded. The choice set will wait until the preload completes and then immediately present.

Objective-C

- (void)preloadChoices:(nonnull NSArray<SDLChoiceCell *> *)choices
    withCompletionHandler:(nullable SDLPreloadChoiceCompletionHandler)handler;

Swift

func preloadChoices(_ choices: [SDLChoiceCell]) async throws

Parameters

choices

The choices to be preloaded.

handler

The handler to be called when complete.

-deleteChoices:

Delete loaded cells from the head unit. If the cells don’t exist on the head unit they will be ignored.

Objective-C

- (void)deleteChoices:(nonnull NSArray<SDLChoiceCell *> *)choices;

Swift

func deleteChoices(_ choices: [SDLChoiceCell])

Parameters

choices

The choices to be deleted. These will be matched via a hash of the text, image name(s), and VR commands.

-presentChoiceSet:mode:

Present a choice set on the head unit with a certain interaction mode. You should present in VR only if the user reached this choice set by using their voice, in Manual only if the user used touch to reach this choice set. Use Both if you’re lazy…for real though, it’s kind of confusing to the user and isn’t recommended.

If the cells in the set are not already preloaded, they will be preloaded before the presentation occurs; this could take a while depending on the contents of the cells.

If the cells have voice commands and images attached, this could take upwards of 10 seconds. If there are no cells on the set, this will fail, calling choiceSet:didReceiveError: on the choice set delegate.

Objective-C

- (void)presentChoiceSet:(nonnull SDLChoiceSet *)choiceSet
                    mode:(nonnull SDLInteractionMode)mode;

Swift

func present(_ choiceSet: SDLChoiceSet, mode: SDLInteractionMode)

Parameters

choiceSet

The set to be displayed

mode

If the set should be presented for the user to interact via voice, touch, or both

-presentSearchableChoiceSet:mode:withKeyboardDelegate:

Present a choice set on the head unit with a certain interaction mode. You should present in VR only if the user reached this choice set by using their voice, in Manual only if the user used touch to reach this choice set. Use Both if you’re lazy…for real though, it’s kind of confusing to the user and isn’t recommended.

This presents the choice set as searchable when in a touch interaction. The user, when not in a distracted state, will have a keyboard available for searching this set. The user’s input in the keyboard will be available in the SDLKeyboardDelegate.

If the cells in the set are not already preloaded, they will be preloaded before the presentation occurs; this could take a while depending on the contents of the cells.

If the cells have voice commands and images attached, this could take upwards of 10 seconds. If there are no cells on the set, this will fail, calling choiceSet:didReceiveError: on the choice set delegate.

Objective-C

- (void)presentSearchableChoiceSet:(nonnull SDLChoiceSet *)choiceSet
                              mode:(nonnull SDLInteractionMode)mode
              withKeyboardDelegate:(nonnull id<SDLKeyboardDelegate>)delegate;

Parameters

choiceSet

The set to be displayed

mode

If the set should be presented for the user to interact via voice, touch, or both

delegate

The keyboard delegate called when the user interacts with the search field of the choice set

-presentKeyboardWithInitialText:delegate:

Present a keyboard-only interface to the user and receive input. The user will be able to input text in the keyboard when in a non-driver distraction situation.

Objective-C

- (nullable NSNumber<SDLInt> *)
    presentKeyboardWithInitialText:(nonnull NSString *)initialText
                          delegate:(nonnull id<SDLKeyboardDelegate>)delegate;

Parameters

initialText

The initial text within the keyboard input field. It will disappear once the user selects the field in order to enter text

delegate

The keyboard delegate called when the user interacts with the keyboard

-dismissKeyboardWithCancelID:

Cancels the keyboard-only interface if it is currently showing. If the keyboard has not yet been sent to Core, it will not be sent.

This will only dismiss an already presented keyboard if connected to head units running SDL 6.0+.

Objective-C

- (void)dismissKeyboardWithCancelID:(nonnull NSNumber<SDLInt> *)cancelID;

Swift

func dismissKeyboard(withCancelID cancelID: NSNumber & SDLInt)

Parameters

cancelID

The unique ID assigned to the keyboard, passed as the return value from presentKeyboardWithInitialText:keyboardDelegate:

-openMenu

Present the top-level of your application menu. This method should be called if the menu needs to be opened programmatically because the built in menu button is hidden.

Objective-C

- (BOOL)openMenu;

Swift

func openMenu() -> Bool

-openSubmenu:

Present the application menu. This method should be called if the menu needs to be opened programmatically because the built in menu button is hidden. You must update the menu with the proper cells before calling this method. This RPC will fail if the cell does not contain a sub menu, or is not in the menu array.

Objective-C

- (BOOL)openSubmenu:(nonnull SDLMenuCell *)cell;

Swift

func openSubmenu(_ cell: SDLMenuCell) -> Bool

Parameters

cell

The submenu cell that should be opened as a sub menu, with its sub cells as the options.

-presentAlert:withCompletionHandler:

Present the alert on the screen. To replace a currently presenting alert with a new alert, you must first call cancel on the currently presenting alert before sending the new alert. Otherwise the newest alert will only be presented when the module dismisses the currently presented alert (either due to the timeout or the user selecting a button on the alert). Please note that cancelling a currently presented alert will only work on modules supporting RPC Spec v.5.0+.

If the alert contains an audio indication with a file that needs to be uploaded, it will be uploaded before presenting the alert. If the alert contains soft buttons with images, they will be uploaded before presenting the alert. If the alert contains an icon, that will be uploaded before presenting the alert.

The handler will be called when the alert either dismisses from the screen or it has failed to present. If the error value in the handler is present, then the alert failed to appear or was aborted, if not, then the alert dismissed without error. The userInfo object on the error contains an error key with more information about the error. If the alert failed to present, the userInfo object will contain a tryAgainTime key with information on how long to wait before trying to send another alert. The value for tryAgainTime may be nil if the module did not return a value in its response.

Objective-C

- (void)presentAlert:(nonnull SDLAlertView *)alert
    withCompletionHandler:
        (nullable SDLScreenManagerUpdateCompletionHandler)handler;

Swift

func presentAlert(_ alert: SDLAlertView) async throws

Parameters

alert

Alert to be presented

handler

The handler to be called when the alert either dismisses from the screen or it has failed to present.