Expand Minimize Picture-in-picture Power Device Status Voice Recognition Skip Back Skip Forward Minus Plus Play Search
Documentation
Sidebar

SDLPerformInteraction Class Reference

Section Contents

Overview

Performs an application-initiated interaction in which the user can select a choice from the passed choice set.

There are several ways to present a choice set: as visual pop-up menu (with an optional keyboard that allows for searches), as voice-recognition (VR) only menu, or as both a VR and visual menu. It is also possible to present only the keyboard for doing searches.

A choice set can have up to 100 items, however if you are presenting a visual only menu please be aware that the OEM may choose to limit the number of presented choices when the driver is distracted (i.e. the car is moving).

A VR-only menu could be used to ask a user to say the name of a song to play. The user’s response would only be valid if it appears in the specified choice set. A visual popup-menu could be used to present a list of albums to the user. The user would select the album they want to play from the list of presented choices. A keyboard can be used for searches. For example, the user could be asked to enter the name of a restaurant. The name can be used to search for local restaurants with the same name. When the search is completed another menu can be presented with a list of potential addresses for the destination.

If connecting to SDL Core v.6.0+, the perform interaction can be canceled programmatically using the cancelID. On older versions of SDL Core, the perform interaction will persist until the user has interacted with the perform interaction or the specified timeout has elapsed.

See

SDLCreateInteractionChoiceSet, SDLDeleteInteractionChoiceSet

@since SDL 1.0

-initWithInitialText:interactionMode:interactionChoiceSetIDList:cancelID:

Convenience init for creating a basic display or voice-recognition menu.

Objective-C

- (nonnull instancetype)
           initWithInitialText:(nonnull NSString *)initialText
               interactionMode:(nonnull SDLInteractionMode)interactionMode
    interactionChoiceSetIDList:
        (nonnull NSArray<NSNumber<SDLUInt> *> *)interactionChoiceSetIDList
                      cancelID:(UInt32)cancelID;

Swift

init(initialText: String, interactionMode: SDLInteractionMode, interactionChoiceSetIDList: [NSNumber & SDLUInt], cancelID: UInt32)

Parameters

initialText

Text to be displayed first

interactionMode

Indicates the method in which the user is notified and uses the interaction

interactionChoiceSetIDList

List of interaction choice set IDs to use with an interaction

cancelID

An ID for this specific perform interaction to allow cancellation through the CancelInteraction RPC

Return Value

An SDLPerformInteraction object

-initWithInitialText:initialPrompt:interactionMode:interactionChoiceSetIDList:helpPrompt:timeoutPrompt:timeout:vrHelp:interactionLayout:cancelID:

Convenience init for setting all parameters of a display or voice-recognition menu.

Objective-C

- (nonnull instancetype)
           initWithInitialText:(nonnull NSString *)initialText
                 initialPrompt:(nullable NSArray<SDLTTSChunk *> *)initialPrompt
               interactionMode:(nonnull SDLInteractionMode)interactionMode
    interactionChoiceSetIDList:
        (nonnull NSArray<NSNumber<SDLUInt> *> *)interactionChoiceSetIDList
                    helpPrompt:(nullable NSArray<SDLTTSChunk *> *)helpPrompt
                 timeoutPrompt:(nullable NSArray<SDLTTSChunk *> *)timeoutPrompt
                       timeout:(UInt16)timeout
                        vrHelp:(nullable NSArray<SDLVRHelpItem *> *)vrHelp
             interactionLayout:(nullable SDLLayoutMode)interactionLayout
                      cancelID:(UInt32)cancelID;

Swift

init(initialText: String, initialPrompt: [SDLTTSChunk]?, interactionMode: SDLInteractionMode, interactionChoiceSetIDList: [NSNumber & SDLUInt], helpPrompt: [SDLTTSChunk]?, timeoutPrompt: [SDLTTSChunk]?, timeout: UInt16, vrHelp: [SDLVRHelpItem]?, interactionLayout: SDLLayoutMode?, cancelID: UInt32)

Parameters

initialText

Text to be displayed first

initialPrompt

The initial prompt spoken to the user at the start of an interaction

interactionMode

The method in which the user is notified and uses the interaction (voice, visual or both)

interactionChoiceSetIDList

List of interaction choice set IDs to use with an interaction

helpPrompt

The spoken text when a user speaks help when the interaction is occurring

timeoutPrompt

The text spoken when a VR interaction times out

timeout

Timeout in milliseconds

vrHelp

Suggested voice recognition help items to display on-screen during a perform interaction

interactionLayout

For touchscreen interactions, the mode of how the choices are presented

cancelID

An ID for this specific perform interaction to allow cancellation through the CancelInteraction RPC.

Return Value

An SDLPerformInteraction object

-initWithInteractionChoiceSetId:

Convenience init for setting the a single visual or voice-recognition menu choice.

Objective-C

- (nonnull instancetype)initWithInteractionChoiceSetId:
    (UInt16)interactionChoiceSetId;

Swift

init(interactionChoiceSetId: UInt16)

Parameters

interactionChoiceSetId

Single interaction choice set ID to use with an interaction

Return Value

An SDLPerformInteraction object

-initWithInteractionChoiceSetIdList:

Convenience init for setting the a visual or voice-recognition menu choices.

Objective-C

- (nonnull instancetype)initWithInteractionChoiceSetIdList:
    (nonnull NSArray<NSNumber<SDLUInt> *> *)interactionChoiceSetIdList;

Swift

init(interactionChoiceSetIdList: [NSNumber & SDLUInt])

Parameters

interactionChoiceSetIdList

List of interaction choice set IDs to use with an interaction

Return Value

An SDLPerformInteraction object

-initWithInitialPrompt:initialText:interactionChoiceSetID:

Convenience init for creating a visual or voice-recognition menu with one choice.

Objective-C

- (nonnull instancetype)initWithInitialPrompt:(nullable NSString *)initialPrompt
                                  initialText:(nonnull NSString *)initialText
                       interactionChoiceSetID:(UInt16)interactionChoiceSetID;

Swift

init(initialPrompt: String?, initialText: String, interactionChoiceSetID: UInt16)

Parameters

initialPrompt

The initial prompt spoken to the user at the start of an interaction

initialText

Text to be displayed first

interactionChoiceSetID

Single interaction choice set ID to use with an interaction

Return Value

An SDLPerformInteraction object

-initWithInitialPrompt:initialText:interactionChoiceSetID:vrHelp:

Convenience init for creating a visual or voice-recognition menu with one choice and VR help items.

Objective-C

- (nonnull instancetype)
     initWithInitialPrompt:(nullable NSString *)initialPrompt
               initialText:(nonnull NSString *)initialText
    interactionChoiceSetID:(UInt16)interactionChoiceSetID
                    vrHelp:(nullable NSArray<SDLVRHelpItem *> *)vrHelp;

Swift

init(initialPrompt: String?, initialText: String, interactionChoiceSetID: UInt16, vrHelp: [SDLVRHelpItem]?)

Parameters

initialPrompt

The initial prompt spoken to the user at the start of an interaction

initialText

Text to be displayed first

interactionChoiceSetID

Single interaction choice set ID to use with an interaction

vrHelp

Suggested voice recognition help items to display on-screen during a perform interaction

Return Value

An SDLPerformInteraction object

-initWithInitialPrompt:initialText:interactionChoiceSetIDList:helpPrompt:timeoutPrompt:interactionMode:timeout:

Convenience init for creating a visual or voice-recognition menu using the default display layout and VR help items. Prompts are created from the passed strings.

Objective-C

- (nonnull instancetype)
         initWithInitialPrompt:(nullable NSString *)initialPrompt
                   initialText:(nonnull NSString *)initialText
    interactionChoiceSetIDList:
        (nonnull NSArray<NSNumber<SDLUInt> *> *)interactionChoiceSetIDList
                    helpPrompt:(nullable NSString *)helpPrompt
                 timeoutPrompt:(nullable NSString *)timeoutPrompt
               interactionMode:(nonnull SDLInteractionMode)interactionMode
                       timeout:(UInt32)timeout;

Swift

init(initialPrompt: String?, initialText: String, interactionChoiceSetIDList: [NSNumber & SDLUInt], helpPrompt: String?, timeoutPrompt: String?, interactionMode: SDLInteractionMode, timeout: UInt32)

Parameters

initialText

Text to be displayed first

initialPrompt

The initial prompt spoken to the user at the start of an interaction

interactionMode

The method in which the user is notified and uses the interaction (voice, visual or both)

interactionChoiceSetIDList

List of interaction choice set IDs to use with an interaction

helpPrompt

The spoken text when a user speaks help when the interaction is occurring

timeoutPrompt

The text spoken when a VR interaction times out

timeout

Timeout in milliseconds

Return Value

An SDLPerformInteraction object

-initWithInitialPrompt:initialText:interactionChoiceSetIDList:helpPrompt:timeoutPrompt:interactionMode:timeout:vrHelp:

Convenience init for creating a visual or voice-recognition menu using the default display layout. Prompts are created from the passed strings.

Objective-C

- (nonnull instancetype)
         initWithInitialPrompt:(nullable NSString *)initialPrompt
                   initialText:(nonnull NSString *)initialText
    interactionChoiceSetIDList:
        (nonnull NSArray<NSNumber<SDLUInt> *> *)interactionChoiceSetIDList
                    helpPrompt:(nullable NSString *)helpPrompt
                 timeoutPrompt:(nullable NSString *)timeoutPrompt
               interactionMode:(nonnull SDLInteractionMode)interactionMode
                       timeout:(UInt32)timeout
                        vrHelp:(nullable NSArray<SDLVRHelpItem *> *)vrHelp;

Swift

init(initialPrompt: String?, initialText: String, interactionChoiceSetIDList: [NSNumber & SDLUInt], helpPrompt: String?, timeoutPrompt: String?, interactionMode: SDLInteractionMode, timeout: UInt32, vrHelp: [SDLVRHelpItem]?)

Parameters

initialText

Text to be displayed first

initialPrompt

The initial prompt spoken to the user at the start of an interaction

interactionMode

The method in which the user is notified and uses the interaction (voice, visual or both)

interactionChoiceSetIDList

List of interaction choice set IDs to use with an interaction

helpPrompt

The spoken text when a user speaks help when the interaction is occurring

timeoutPrompt

The text spoken when a VR interaction times out

timeout

Timeout in milliseconds

vrHelp

Suggested voice recognition help items to display on-screen during a perform interaction

Return Value

An SDLPerformInteraction object

-initWithInitialChunks:initialText:interactionChoiceSetIDList:helpChunks:timeoutChunks:interactionMode:timeout:vrHelp:

Convenience init for creating a visual or voice-recognition menu using the default display layout.

Objective-C

- (nonnull instancetype)
         initWithInitialChunks:(nullable NSArray<SDLTTSChunk *> *)initialChunks
                   initialText:(nonnull NSString *)initialText
    interactionChoiceSetIDList:
        (nonnull NSArray<NSNumber<SDLUInt> *> *)interactionChoiceSetIDList
                    helpChunks:(nullable NSArray<SDLTTSChunk *> *)helpChunks
                 timeoutChunks:(nullable NSArray<SDLTTSChunk *> *)timeoutChunks
               interactionMode:(nonnull SDLInteractionMode)interactionMode
                       timeout:(UInt32)timeout
                        vrHelp:(nullable NSArray<SDLVRHelpItem *> *)vrHelp;

Swift

init(initialChunks: [SDLTTSChunk]?, initialText: String, interactionChoiceSetIDList: [NSNumber & SDLUInt], help helpChunks: [SDLTTSChunk]?, timeoutChunks: [SDLTTSChunk]?, interactionMode: SDLInteractionMode, timeout: UInt32, vrHelp: [SDLVRHelpItem]?)

Parameters

initialText

Text to be displayed first

initialChunks

The initial prompt spoken to the user at the start of an interaction

interactionMode

The method in which the user is notified and uses the interaction (voice, visual or both)

interactionChoiceSetIDList

List of interaction choice set IDs to use with an interaction

helpChunks

The spoken text when a user speaks help when the interaction is occurring

timeoutChunks

The text spoken when a VR interaction times out

timeout

Timeout in milliseconds

vrHelp

Suggested voice recognition help items to display on-screen during a perform interaction

Return Value

An SDLPerformInteraction object

-initWithInitialChunks:initialText:interactionChoiceSetIDList:helpChunks:timeoutChunks:interactionMode:timeout:vrHelp:interactionLayout:

Convenience init for setting all parameters of a visual or voice-recognition menu.

Objective-C

- (nonnull instancetype)
         initWithInitialChunks:(nullable NSArray<SDLTTSChunk *> *)initialChunks
                   initialText:(nonnull NSString *)initialText
    interactionChoiceSetIDList:
        (nonnull NSArray<NSNumber<SDLUInt> *> *)interactionChoiceSetIDList
                    helpChunks:(nullable NSArray<SDLTTSChunk *> *)helpChunks
                 timeoutChunks:(nullable NSArray<SDLTTSChunk *> *)timeoutChunks
               interactionMode:(nonnull SDLInteractionMode)interactionMode
                       timeout:(UInt32)timeout
                        vrHelp:(nullable NSArray<SDLVRHelpItem *> *)vrHelp
             interactionLayout:(nullable SDLLayoutMode)layout;

Swift

init(initialChunks: [SDLTTSChunk]?, initialText: String, interactionChoiceSetIDList: [NSNumber & SDLUInt], help helpChunks: [SDLTTSChunk]?, timeoutChunks: [SDLTTSChunk]?, interactionMode: SDLInteractionMode, timeout: UInt32, vrHelp: [SDLVRHelpItem]?, interactionLayout layout: SDLLayoutMode?)

Parameters

initialText

Text to be displayed first

initialChunks

The initial prompt spoken to the user at the start of an interaction

interactionMode

The method in which the user is notified and uses the interaction (voice, visual or both)

interactionChoiceSetIDList

List of interaction choice set IDs to use with an interaction

helpChunks

The spoken text when a user speaks help when the interaction is occurring

timeoutChunks

The text spoken when a VR interaction times out

timeout

Timeout in milliseconds

vrHelp

Suggested voice recognition help items to display on-screen during a perform interaction

layout

For touchscreen interactions, the mode of how the choices are presented

Return Value

An SDLPerformInteraction object

initialText

Text to be displayed first.

String, Required

@since SDL 1.0

Objective-C

@property (readwrite, strong, nonatomic) NSString *_Nonnull initialText;

Swift

var initialText: String { get set }

initialPrompt

This is the TTS prompt spoken to the user at the start of an interaction.

Array of SDLTTSChunk, Optional, Array size: 1-100

@since SDL 1.0

Objective-C

@property (readwrite, strong, nonatomic, nullable)
    NSArray<SDLTTSChunk *> *initialPrompt;

Swift

var initialPrompt: [SDLTTSChunk]? { get set }

interactionMode

For application-requested interactions, this mode indicates the method in which the user is notified and uses the interaction. Users can choose either only by voice (VR_ONLY), by tactile selection from the menu (MANUAL_ONLY), or by either mode (BOTH).

SDLInteractionMode, Required

@since SDL 1.0

Objective-C

@property (readwrite, strong, nonatomic)
    SDLInteractionMode _Nonnull interactionMode;

Swift

var interactionMode: SDLInteractionMode { get set }

interactionChoiceSetIDList

List of interaction choice set IDs to use with an interaction.

Array of Integers, Required, Array size: 0-100, Min value: 0, Max value: 2000000000

@since SDL 1.0

Objective-C

@property (readwrite, strong, nonatomic)
    NSArray<NSNumber<SDLInt> *> *_Nonnull interactionChoiceSetIDList;

Swift

var interactionChoiceSetIDList: [NSNumber & SDLInt] { get set }

helpPrompt

Help text. This is the spoken text when a user speaks help while the interaction is occurring.

SDLTTSChunk, Optional

@since SDL 1.0

Objective-C

@property (readwrite, strong, nonatomic, nullable)
    NSArray<SDLTTSChunk *> *helpPrompt;

Swift

var helpPrompt: [SDLTTSChunk]? { get set }

timeoutPrompt

Timeout text. This text is spoken when a VR interaction times out.

Array of SDLTTSChunk, Optional, Array size: 1-100

@since SDL 1.0

Objective-C

@property (readwrite, strong, nonatomic, nullable)
    NSArray<SDLTTSChunk *> *timeoutPrompt;

Swift

var timeoutPrompt: [SDLTTSChunk]? { get set }

timeout

Timeout in milliseconds. Applies only to the menu portion of the interaction. The VR timeout will be handled by the platform. If omitted a standard value of 10 seconds is used.

Integer, Optional, Min value: 5000, Max value: 100,000

@since SDL 1.0

Objective-C

@property (readwrite, strong, nonatomic, nullable) NSNumber<SDLInt> *timeout;

Swift

var timeout: (NSNumber & SDLInt)? { get set }

vrHelp

Suggested voice recognition help items to display on-screen during a perform interaction. If omitted on supported displays, the default generated list of suggested choices shall be displayed.

SDLVRHelpItem, Optional

@since SDL 2.0

Objective-C

@property (readwrite, strong, nonatomic, nullable)
    NSArray<SDLVRHelpItem *> *vrHelp;

Swift

var vrHelp: [SDLVRHelpItem]? { get set }

interactionLayout

For tactile interaction modes (MANUAL_ONLY, or BOTH), the layout mode of how the choices are presented.

SDLLayoutMode, Optional

@since SDL 3.0

Objective-C

@property (readwrite, strong, nonatomic, nullable)
    SDLLayoutMode interactionLayout;

Swift

var interactionLayout: SDLLayoutMode? { get set }

cancelID

An ID for this specific perform interaction to allow cancellation through the CancelInteraction RPC.

Integer, Optional

See

SDLCancelInteraction @since SDL 6.0

Objective-C

@property (readwrite, strong, nonatomic, nullable) NSNumber<SDLInt> *cancelID;

Swift

var cancelID: (NSNumber & SDLInt)? { get set }
View on GitHub.com
Previous Section Next Section