Feature/0238 Keyboard Enhancements

docs/BasicCommunication/OnSystemCapabilityUpdated/index.md

@@ -18,11 +18,13 @@ Purpose
     * `menuName` and `templateTitle` should be included, if they are visible on HMI.
     * `mainField1-4`, `statusBar` and `mediaTrack` should not be included if OEM implemented the `WEB_VIEW` template without these text fields.
     * `availabletemplates`, `buttonCapabilities` and `imageTypeSupported` should reflect the general capabilities of the window/system.
+5. HMI sends `KeyboardCapabilities` and max number of customizable keys within OnSystemCapabilityUpdated notification to SDL.
 
 !!! NOTE
 
-Template `WEB_VIEW` is only allowed for the WebEngine applications with `AppHMIType`=`WEB_VIEW`.
+1. Template `WEB_VIEW` is only allowed for the WebEngine applications with `AppHMIType`=`WEB_VIEW`.
 
+2. In case HMI sends `KeyboardCapabilities` without information about `numConfigurableKeys` within OnSystemCapabilityUpdated notification, SDL would provide `KeyboardCapabilities` to app with `numConfigurableKeys` set to zero.
 !!!
 
 #### Parameters

docs/UI/OnKeyboardInput/assets/KeyboardEventInputKeyMask.txt

@@ -2,43 +2,49 @@ participant App
 participant SDL
 participant HMI
 
-note over App,HMI:<align:center> **//Pre-conditions://**\n**1.** appID application is successfully registered and active on HMI\n**2.** By default keyboard input characters are not masked on the screen\n
-note over App:<align:center>PIN authentication\nis required
-App->SDL:PerformInteraction (appID, <KEYBOARD>)
-SDL->HMI:PerformInteraction (appID, <KEYBOARD>)
-note over HMI:<align:center> Displays the keyboard\nin accordance with appID\nSetGlobalProperties presets
-HMI->>SDL:UI.Onsystemcontext (<HMI_OBSCURED>)
-SDL->>App:Onsystemcontext (<HMI_OBSCURED>)
+note over App,HMI:<align:center> **//Pre-conditions://**\n**1.** appID application is successfully registered and active on HMI\n**2.** HMI supports masking input characters
+
+HMI->>SDL: BC.OnSystemCapabilityUpdated(**maskInputCharactersSupported=true**)
+SDL->>App: OnSystemCapabilityUpdated(maskInputCharactersSupported=true)
+opt App sends the request to mask keyboard input characters 
+App->SDL:<align:center>SetGlobalProperties(appID,\n **maskInputCharacters=ENABLE_INPUT_KEY_MASK**)
+SDL->HMI:<align:center>UI.SetGlobalProperties(appID,\n **maskInputCharacters=ENABLE_INPUT_KEY_MASK**)
+note over HMI:<align:center>Stores the request data\nassociating it with appID
+HMI-->SDL:UI.SetGlobalProperties (code:0)
+SDL-->App:SetGlobalProperties (SUCCESS)
 note over HMI:The User presses **"1"** key
 HMI->>SDL:UI.OnkeyboardInput ("1", <KEYPRESS>)
 SDL->>App:OnkeyboardInput ("1", <KEYPRESS>)
-note over HMI:<align:center>Keyboard input characters\nare **not masked**\non the screen
+note over HMI:<align:center>User input is shown **masked**
+end
 
-opt App sends the request to mask keyboard input characters
-App->SDL:SetGlobalProperties (appID, <ENABLE_INPUT_KEY_MASK>)
-SDL->HMI:UI.SetGlobalProperties (appID, <ENABLE_INPUT_KEY_MASK>)
+opt App sends the request to UNmask keyboard input characters
+App->SDL:<align:center>SetGlobalProperties(appID,\n **maskInputCharacters=DISABLE_INPUT_KEY_MASK**
+SDL->HMI:<align:center>UI.SetGlobalProperties(appID,\n**maskInputCharacters=DISABLE_INPUT_KEY_MASK**
 note over HMI:<align:center>Stores the request data\nassociating it with appID
 HMI-->SDL:UI.SetGlobalProperties (code:0)
-SDL-->App:SetGlobalProperties (code:0)
+SDL-->App:SetGlobalProperties (SUCCESS)
 note over HMI:The User presses **"1"** key
-HMI->>SDL:UI.OnkeyboardInput ("1", <INPUT_KEY_MASK_ENABLED>)
-SDL->>App:OnkeyboardInput ("1", <INPUT_KEY_MASK_ENABLED>)
-note over HMI:<align:center>Keyboard input characters\nare **masked**\non the screen
+HMI->>SDL:UI.OnkeyboardInput ("1", <KEYPRESS>)
+SDL->>App:OnkeyboardInput ("1", <KEYPRESS>)
+note over HMI:<align:center>User input is shown **NOT masked**
 end
 
 opt App sends the request to unmask keyboard input characters per User choice
-App->SDL:SetGlobalProperties (appID, <USER_CHOICE_INPUT_KEY_MASK>)
-SDL->HMI:UI.SetGlobalProperties (appID, <USER_CHOICE_INPUT_KEY_MASK>)
+App->SDL:<align:center> SetGlobalProperties (appID,\n **maskInputCharacters=USER_CHOICE_INPUT_KEY_MASK**)
+SDL->HMI:<align:center> UI.SetGlobalProperties (appID,\n **maskInputCharacters=USER_CHOICE_INPUT_KEY_MASK**)
 note over HMI:<align:center>Stores the request data\nassociating it with appID
 HMI-->SDL:UI.SetGlobalProperties (code:0)
-SDL-->App:SetGlobalProperties (code:0)
+SDL-->App:SetGlobalProperties (SUCCESS)
+HMI->>SDL:UI.OnkeyboardInput (<INPUT_KEY_MASK_DISABLED>)
+SDL->>App:OnkeyboardInput (<INPUT_KEY_MASK_DISABLED>)
+note over HMI:<align:center>A key to mask/unmask\ninput characters is shown
 note over HMI:The User presses **"1"** key
-HMI->>SDL:UI.OnkeyboardInput ("1", <INPUT_KEY_MASK_ENABLED>)
-SDL->>App:OnkeyboardInput ("1", <INPUT_KEY_MASK_ENABLED>)
-note over HMI:<align:center>Keyboard input characters\nare **masked**\non the screen
-note over HMI:<align:center> **Postcondition**:\nProvides a key to unmask\ninput characters
-note over HMI:<align:center>The User presses the key\nto unmask input characters
-note over HMI:<align:center>Keyboard input characters\nare **not masked**\non the screen
-HMI->>SDL:UI.OnKeyboardInput (<INPUT_KEY_MASK_DISABLED>)
-SDL->>App:OnKeyboardInput (<INPUT_KEY_MASK_DISABLED>)
+HMI->>SDL:UI.OnkeyboardInput ("1", <KEYPRESS>)
+SDL->>App:OnkeyboardInput ("1", <KEYPRESS>)
+note over HMI:The User presses the key\n to mask input characters
+HMI->>SDL:UI.OnkeyboardInput (<INPUT_KEY_MASK_ENABLED>)
+SDL->>App:OnkeyboardInput (<INPUT_KEY_MASK_ENABLED>)
+note over HMI:<align:center>Keyboard input characters\nare ** masked**\non the screen
+
 end

docs/UI/SetGlobalProperties/assets/SetGlobalPropertiesCustomizeKeys.txt

@@ -6,12 +6,12 @@ note over App,HMI:<align:center> **//Pre-conditions://**\n**1.** appID applicati
 
 opt App sends a request to change customizable keys special characters - Happy Path
 note over HMI:<align:center>Keyboard layout\ncustomizable keys are:\n**" # "** - default value\n**" - "** - default value
-App->SDL:SetGlobalProperties (appID, <customizeKeys: **" # ", " $ "**>)
-SDL->HMI:UI.SetGlobalProperties (appID, <customizeKeys: **" # ", " $ "**>)     
+App->SDL:SetGlobalProperties (appID, <customizeKeys: **" ¥ ", " $ "**>)
+SDL->HMI:UI.SetGlobalProperties (appID, <customizeKeys: **" ¥ ", " $ "**>)     
 HMI->HMI:Update\ncustomizable\nkeys
 HMI-->SDL:UI.SetGlobalProperties (SUCCESS)
 SDL-->App:SetGlobalProperties (SUCCESS)
-note over HMI:<align:center>Keyboard layout\ncustomizable keys are:\n**" # "** - customized value\n** " $ "** - customized value
+note over HMI:<align:center>Keyboard layout\ncustomizable keys are:\n**" ¥ "** - customized value\n** " $ "** - customized value
 end
 
 opt App sends a request with a special character already available on keyboard

docs/UI/SetGlobalProperties/assets/SetGlobalPropertiesResumptionKeyboardProperties.txt

@@ -0,0 +1,28 @@
+participant App
+participant SDL
+participant HMI
+
+note over App,HMI:<align:center>**//Pre-conditions://**\n**1.** appID application is successfuly registered, activated\n**2.** App set non-default values for 'KeyboardProperties' via SetGlobalProperties request\n keyboardLayout=AZERTY; maskInputCharacters=USER_CHOICE_INPUT_KEY_MASK; customizeKeys = "#", "$"
+
+note over App,HMI: Unexpected disconnect and reconnect are performed
+
+App->SDL: RegisterAppInterface(hashID, params)
+
+
+note over SDL:<align:center> <hashID> is valid\nStart data resumption for the App
+
+SDL->HMI:<align:center>UI.SetGlobalProperties\n (**keyboardLayout=AZERTY;\nmaskInputCharacters=USER_CHOICE_INPUT_KEY_MASK;\ncustomizeKeys = #, $**)
+
+HMI-->SDL: UI.SetGlobalProperties (code:0)
+
+
+SDL-->App: RegisterAppInterface (SUCCESS)
+
+SDL->>HMI: BC.OnAppRegistered(appName; appID)
+SDL->>App: OnHMIStatus()
+
+SDL->HMI: BC.ActivateApp()
+HMI-->SDL: BC.ActivateApp (code:0)
+
+HMI->>SDL: UI.OnKeyboardInput(INPUT_KEY_MASK_DISABLED)
+SDL->>App:OnKeyboardInput(INPUT_KEY_MASK_DISABLED)

docs/UI/SetGlobalProperties/index.md

@@ -42,6 +42,7 @@ _**Notes for HMI expected behavior:**_
 6. When the User selects one of the displayed matching `autoCompleteList` strings, the system shall submit that entry and not require further User input for submission.
 7. HMI allows to customize special characters depending on the keyboard layout restrictions:
     * `QWERTY` - 3 customizable keys
+    * `QWERTZ` - 3 customizable keys
     * `AZERTY` - 4 customizable keys
     * `NUMERIC` - 2 customizable keys
 
@@ -75,9 +76,7 @@ _**Important Note:**_ If HMI-defined VR commands are accessible together with th
   * display the complete list of available VR commands (SDL-defined and HMI-defined ones) when the User activates VR.
 
 4. HMI displays the in-application menu for every active application upon the User's request. It must contain SDL-requested commands (UI.AddCommand) and sub-menus (UI.AddSubMenu). SDL provides the values for the name (`menuTitle` parameter) and for the icon (`menuIcon` parameter) of this in-application menu. The values for in-application menu and touchscreen keyboard are allowed by SDL Core for navigation type of application only.
-5. HMI must display the onscreen keyboard upon the User's request within the following condition: all `keyboardProperties` supported by HMI must be embodied in `HMI_capabilities.json file`. In this case SDL Core is able to compare `keyboardProperties` requested by the mobile device with actually supported `keyboardProperties` and send to HMI only those that are supported.
-6. HMI must use default `keyboardProperties` parameters, in case SDL Core transfers UI.SetGlobalProperties request with omitted or empty `keyboardProperties` parameters.
-7. In case SDL sends request with some values in `customizeKeys` array, HMI must:
+5. In case SDL sends request with some values in `customizeKeys` array, HMI must:
     * use these values to change the special characters shown in customizable keys
     * keep default values in the remaining keys, if the array is less than or equal to customizable keys amount
 
@@ -107,6 +106,11 @@ SetGlobalProperties Customize Keys
 ![SetGlobalProperties](./assets/SetGlobalPropertiesCustomizeKeys.png)
 |||
 
+|||
+SetGlobalProperties Resumption of non-default KeyboardProperties
+![SetGlobalProperties](./assets/SetGlobalPropertiesResumptionKeyboardProperties.png)
+|||
+
 ### JSON Message Examples
 
 #### Example Request