Expand Minimize Picture-in-picture Power Device Status Voice Recognition Skip Back Skip Forward Minus Plus Play Search
Internet Explorer alert
This browser is not recommended for use with smartdevicelink.com, and may not function properly. Upgrade to a different browser to guarantee support of all features.
close alert
US
JP
US
JP
To Top Created with Sketch. To Top
To Bottom Created with Sketch. To Bottom
HMI Documentation
AddSubMenu

AddSubMenu

Type
Function
Sender
SDL
Purpose
Add a sub menu to the specified application's menu

UI.AddSubMenu represents a request from an application to add a sub-menu to the application's menu. This RPC can be sent to the HMI for an application that is registered and in any state (FULL, BACKGROUND, etc.)

Must
  1. The sub menu sent for the application via AddCommand must be accessible from a Menu.
  2. If the user selects a sub menu item from the application's menu, the HMI must display all commands added via UI.AddCommand which share a menuParams.parentID with the menu's menuID.
  3. Store the data provided in this RPC with the requesting application's appID.
  4. Persist the stored data for the duration of the ignition cycle.
  5. Add the command to the application's menu at the position specified in the menuParams.
  6. Display images on sub menus if provided by the application.
  7. Provide a WARNINGS information to the application that the SubMenu was added but no image was displayed.
  8. Scale the image to ensure it fits properly in the space allocated for the display of the image. If the image does not fit properly even after scaling, the HMI shall not display any image on the submenu.
  9. If a new submenu contains a parentID parameter, the new submenu must be nested inside the submenu specified by the parentID.
  10. When driver distraction state is enabled, submenus that are deeper than the subMenuDepth driver distraction limit must be disabled and inaccessible to the user.
  11. Send BC.OnResetTimeout notification to SDL to reset the timeout in case HMI needs more time to process the request.
Note
  • SDL can request that a submenu be added to another submenu if the parentID parameter is present in the request's menu parameters.
  • A parentID value of 0 indicates the submenu is part of the top level menu.
  • If subMenuDepth is 1, all submenus should be disabled during driver distraction, meaning that only the top level menu should be accessible.
  • HMI does not display any image in case the application does not provide an image for display on the sub menu.
  • HMI does not display any image in case the image referenced by the application for display on the submenu is invalid or is not available.
  • To remove an icon already sent, the app would have to delete the submenu and add it again without the icon.Otherwise, if the submenu is not deleted, another request with the same submenu id will be rejected.

As of Core 7.1, UI.AddSubMenu requests can contain all UI elements that were previously found in a Perform Interaction's Choice.

Request

Parameters

Name Type Mandatory Additional
menuID Integer true minvalue: 1
maxvalue: 2000000000
menuParams Common.MenuParams true
menuIcon Common.Image false
secondaryImage Common.Image false
appID Integer true
menuLayout Common.MenuLayout false

Response

Parameters

This RPC has no additional parameter requirements

Sequence Diagrams

Sequence Diagram

Add Sub Menu for Active App

View Diagram
Sequence Diagram

Add Sub Menu for Inactive App

View Diagram
Sequence Diagram

Add Sub Menu with positions

View Diagram
Sequence Diagram

Add Sub Menu Rejected Limit Reached

View Diagram
Sequence Diagram

Add Sub Menu for WebEngine App

View Diagram

JSON Message Examples

Example Request 

{
  "id" : 112,
  "jsonrpc" : "2.0",
  "method" : "UI.AddSubMenu",
  "params" :
  {
    "menuID" : 345,
    "menuParams" :
    {
         "position" : 2,
         "menuName" : "Settings",
         "secondaryText" : "General",
         "tertiaryText" : "Help"
    },
    "menuIcon" :
    {
         "value" : "tmp/SDL/app/Gis_meteo/1245_28.jpeg",
         "imageType" : "DYNAMIC"
    },
    "secondaryImage" :
    {
         "value" : "tmp/SDL/app/Gis_meteo/5678.jpeg",
         "imageType" : "DYNAMIC"
    },
    "appID" : 65464
  }
}

Example Response 

{
  "id" : 112,
  "jsonrpc" : "2.0",
  "result" :
  {
    "code" : 0,
    "method" : "UI.AddSubMenu"
  }
}

Example Error 

{
  "id" : 112,
  "jsonrpc" : "2.0",
  "error" :
  {
    "code" : 14,
    "message" : "Duplicate name: there was a conflict with an already registered name of SubMenu",
    "data" :
    {
      "method" : "UI.AddSubMenu"
    }
  }
}
View on GitHub.com
Previous Section Next Section