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

SDLAddCommand Class Reference

Section Contents

Overview

This class will add a command to the application’s Command Menu

A command will be added to the end of the list of elements in the Command Menu under the following conditions:

  1. When a SDLAddCommand is added with no SDLMenuParams value provided.
  2. When a SDLMenuParams value is provided with a SDLMenuParam.position value greater than or equal to the number of menu items currently defined in the menu specified by the SDLMenuParam.parentID value.

The set of choices which the application builds using SDLAddCommand can be a mixture of:

  1. Choices having only VR synonym definitions, but no SDLMenuParams definitions
  2. Choices having only SDLMenuParams definitions, but no VR synonym definitions
  3. Choices having both SDLMenuParams and VR synonym definitions

HMILevel needs to be FULL, LIMITED or BACKGROUD @since SDL 1.0

See

SDLDeleteCommand, SDLAddSubMenu, SDLDeleteSubMenu

-initWithHandler:

Constructs a SDLAddCommand with a handler callback when an event occurs.

Objective-C

- (nonnull instancetype)initWithHandler:
    (nullable SDLRPCCommandNotificationHandler)handler;

Swift

init(handler: SDLRPCCommandNotificationHandler? = nil)

Parameters

handler

A callback that is called when a button event occurs for the command.

Return Value

A SDLAddCommand object

-initWithId:vrCommands:handler:

Convenience init for creating a voice command menu item.

@discussion This menu item can only be triggered by the VR system and does not show up in the HMI application menu.

Objective-C

- (nonnull instancetype)initWithId:(UInt32)commandId
                        vrCommands:(nullable NSArray<NSString *> *)vrCommands
                           handler:(nullable SDLRPCCommandNotificationHandler)
                                       handler;

Swift

init(id commandId: UInt32, vrCommands: [String]?, handler: SDLRPCCommandNotificationHandler? = nil)

Parameters

commandId

A unique id for the menu item.

vrCommands

One or more voice recognition phrases. If recognized by the VR system, the handler will be called.

handler

Called when the VR system recognizes a phrase in vrCommands

Return Value

A SDLAddCommand object

-initWithId:vrCommands:menuName:handler:

Convenience init for creating a menu item with text.

Objective-C

- (nonnull instancetype)initWithId:(UInt32)commandId
                        vrCommands:(nullable NSArray<NSString *> *)vrCommands
                          menuName:(nonnull NSString *)menuName
                           handler:(nullable SDLRPCCommandNotificationHandler)
                                       handler;

Swift

init(id commandId: UInt32, vrCommands: [String]?, menuName: String, handler: SDLRPCCommandNotificationHandler? = nil)

Parameters

commandId

A unique id for the menu item.

vrCommands

One or more voice recognition phrases. If recognized by the VR system, the handler will be called.

menuName

The text that will appear in the menu.

handler

Called when the menu item is selected and/or when the VR system recognizes a phrase in vrCommands

Return Value

A SDLAddCommand object

-initWithId:vrCommands:menuName:parentId:position:iconValue:iconType:handler:

Convenience init for creating a menu item with text and a custom icon.

Warning

The icon must be uploaded to Core before being displayed in the menu.

Objective-C

- (nonnull instancetype)initWithId:(UInt32)commandId
                        vrCommands:(nullable NSArray<NSString *> *)vrCommands
                          menuName:(nonnull NSString *)menuName
                          parentId:(UInt32)parentId
                          position:(UInt16)position
                         iconValue:(nullable NSString *)iconValue
                          iconType:(nullable SDLImageType)iconType
                           handler:(nullable SDLRPCCommandNotificationHandler)
                                       handler;

Swift

init(id commandId: UInt32, vrCommands: [String]?, menuName: String, parentId: UInt32, position: UInt16, iconValue: String?, iconType: SDLImageType?, handler: SDLRPCCommandNotificationHandler? = nil)

Parameters

commandId

A unique id for the menu item.

vrCommands

One or more voice recognition phrases. If recognized by the VR system, the handler will be called.

menuName

The text that will appear in the menu.

parentId

The command id of the parent menu if menu item is in a submenu. If not in a submenu, the parentId is 0.

position

The menu item’s row number in the menu.

iconValue

The unique name used to upload the image to Core.

iconType

Whether the image is static or dynamic.

handler

Called when the menu item is selected and/or when the VR system recognizes a phrase in vrCommands

Return Value

A SDLAddCommand object

-initWithId:vrCommands:menuName:parentId:position:iconValue:iconType:iconIsTemplate:handler:

Convenience init for creating a menu item with text and a custom icon.

Warning

The icon must be uploaded to Core before being displayed in the menu.

Objective-C

- (nonnull instancetype)initWithId:(UInt32)commandId
                        vrCommands:(nullable NSArray<NSString *> *)vrCommands
                          menuName:(nonnull NSString *)menuName
                          parentId:(UInt32)parentId
                          position:(UInt16)position
                         iconValue:(nullable NSString *)iconValue
                          iconType:(nullable SDLImageType)iconType
                    iconIsTemplate:(BOOL)iconIsTemplate
                           handler:(nullable SDLRPCCommandNotificationHandler)
                                       handler;

Swift

init(id commandId: UInt32, vrCommands: [String]?, menuName: String, parentId: UInt32, position: UInt16, iconValue: String?, iconType: SDLImageType?, iconIsTemplate: Bool, handler: SDLRPCCommandNotificationHandler? = nil)

Parameters

commandId

A unique id for the menu item.

vrCommands

One or more voice recognition phrases. If recognized by the VR system, the handler will be called.

menuName

The text that will appear in the menu.

parentId

The command id of the parent menu if menu item is in a submenu. If not in a submenu, the parentId is 0.

position

The menu item’s row number in the menu.

iconValue

The unique name used to upload the image to Core.

iconType

Whether the image is static or dynamic.

iconIsTemplate

Whether or not the image is a template that can be (re)colored by the SDL HMI

handler

Called when the menu item is selected and/or when the VR system recognizes a phrase in vrCommands

Return Value

A SDLAddCommand object

-initWithId:vrCommands:menuName:parentId:position:icon:handler:

Convenience init for creating a menu item with text and a custom icon.

Warning

The icon must be uploaded to Core before being displayed in the menu.

Objective-C

- (nonnull instancetype)initWithId:(UInt32)commandId
                        vrCommands:(nullable NSArray<NSString *> *)vrCommands
                          menuName:(nonnull NSString *)menuName
                          parentId:(UInt32)parentId
                          position:(UInt16)position
                              icon:(nullable SDLImage *)icon
                           handler:(nullable SDLRPCCommandNotificationHandler)
                                       handler;

Swift

init(id commandId: UInt32, vrCommands: [String]?, menuName: String, parentId: UInt32, position: UInt16, icon: SDLImage?, handler: SDLRPCCommandNotificationHandler? = nil)

Parameters

commandId

A unique id for the menu item.

vrCommands

One or more voice recognition phrases. If recognized by the VR system, the handler will be called.

menuName

The text that will appear in the menu.

parentId

The command id of the parent menu if menu item is in a submenu. If not in a submenu, the parentId is 0.

position

The menu item’s row number in the menu.

icon

A image that appears next to the menuName text.

handler

Called when the menu item is selected and/or when the VR system recognizes a phrase in vrCommands

Return Value

A SDLAddCommand object

handler

A handler that will let you know when the button you created is subscribed.

Warning

This will only work if you use SDLManager.

Objective-C

@property (readwrite, copy, nonatomic, nullable)
    SDLRPCCommandNotificationHandler handler;

Swift

var handler: SDLRPCCommandNotificationHandler? { get set }

cmdID

A unique id that identifies the command.

@discussion Is returned in an SDLOnCommand notification to identify the command selected by the user

Required, Integer, 0 - 2,000,000,000

Objective-C

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

Swift

var cmdID: NSNumber & SDLInt { get set }

menuParams

A SDLMenuParams pointer which defines the command and how it is added to the command menu.

@discussion If provided, this will define the command and how it is added to the command menu. If null, commands will not be accessible through the HMI application menu.

Optional

Objective-C

@property (readwrite, strong, nonatomic, nullable) SDLMenuParams *menuParams;

Swift

var menuParams: SDLMenuParams? { get set }

vrCommands

An array of strings to be used as VR synonyms for this command.

@discussion If provided, defines one or more VR phrases the recognition of any of which triggers the SDLOnCommand notification with this cmdID. If null, commands will not be accessible by voice commands (when the user hits push-to-talk).

Optional, Array of Strings, Max String length 99 chars, Array size 1 - 100

Objective-C

@property (readwrite, strong, nonatomic, nullable)
    NSArray<NSString *> *vrCommands;

Swift

var vrCommands: [String]? { get set }

cmdIcon

Image struct containing a static or dynamic icon.

@discussion If provided, defines the image to be be shown along with a command. If omitted on supported displays, no (or the default if applicable) icon will be displayed

Optional

Objective-C

@property (readwrite, strong, nonatomic, nullable) SDLImage *cmdIcon;

Swift

var cmdIcon: SDLImage? { get set }
View on GitHub.com
Previous Section Next Section