Merge branch 'dev' into release/5.3.0

Author: uguraslan

docs/_sidebar.md

@@ -2,6 +2,7 @@
 
 - Plugins
   - [Accessibility](/plugins/accessibility.md)
+  - [App](/plugins/app.md)
   - [Utils](/plugins/utils.md)
   - [Storage](/plugins/storage.md)
   - [Settings](/plugins/settings.md)

docs/plugins/app.md

@@ -0,0 +1,33 @@
+# App
+
+SDK provides various methods that can be used within the application.
+
+## Available Methods
+
+### overRideKeyMap
+
+This method can be used to merge and override the existing keymap (coming from `settings.json`) by using a custom keymap in runtime. The method will merge all key mappings by overriding the existing key mappings with the new ones when a key is defined in both keymaps.
+
+`keepDuplicates` flag is set to `false` by default, which means duplicated values (like two different keys trigger the `Back` action) will be removed from the final keymap. If `keepDuplicates` is set to `true`, duplicated **values** will be kept in the final keymap.
+
+#### Usage
+
+```js
+const customKeyMap = {
+    13: "Enter",
+    83: "Search"
+}
+
+this.application.overRideKeyMap(customKeyMap) // keepDuplicates = false
+```
+
+or
+
+```js
+this.application.overRideKeyMap(customKeyMap, true) // keepDuplicates = true
+```
+
+#### Parameters
+
+- `customKeyMap` : keymap object
+- `keepDuplicates`: flag to keep duplicated values in the final keymap or not. The default value is `false`.

docs/plugins/subtitles.md

@@ -0,0 +1,144 @@
+# Subtitles
+
+You can use the *Subtitles* plugin to easily display Subtitles (or Closed Captions) in your App.
+
+The plugin comes with some basic styling of Subtitles and offers the option to customize them, such as font size, colors, and positioning.
+
+> The Subtitles plugins in the Lightning-SDK only offers an API for displaying Subtitles.
+
+> Retrieving subtitles from a video stream or a remote API is not part of the Plugin's functionality as it's very App and / or Platform specific.
+
+## Usage
+
+If you want to display Subtitles in your App, first import the Subtitles plugin from the Lightning SDK:
+
+```js
+import { Subtitles } from '@lightningjs/sdk'
+```
+
+## Available Methods
+
+### show
+
+Sets the visibility of Subtitles to `true`, to display Subtitles.
+
+```js
+Subtitles.show()
+```
+
+### hide
+
+Sets the visibility of Subtitles to `false`, to hide Subtitles.
+
+```js
+Subtitles.hide()
+```
+
+### text
+
+Sets the text of the Subtitles text.
+
+```js
+Subtitles.text('Subtitle Text')
+```
+
+### clear
+
+Clears the text of the Subtitles text.
+
+```js
+Subtitles.clear()
+```
+
+### styles
+
+Sets the styles of the Subtitles text. This is a short hand method for setting the following styles: `fontFamily`, `fontSize`, `fontColor`, `backgroundColor`, `textAlign`. If any of these styles are not set, the default values will be used.
+
+```js
+Subtitles.styles({
+  fontFamily: 'sans-serif',
+  fontSize: 45,
+  fontColor: 0xffffffff,
+  backgroundColor: 0x90000000,
+  textAlign: 'center',
+})
+```
+### fontFamily
+
+Sets the `fontFamily` style of the Subtitles text.
+
+```js
+Subtitles.fontFamily('sans-serif')
+```
+
+### fontSize
+
+Sets the `fontSize` style of the Subtitles text.
+
+```js
+Subtitles.fontSize(50)
+```
+
+### fontColor
+
+Sets the `fontColor` style of the Subtitles text
+
+```js
+Subtitles.fontColor(0xffffffff)
+```
+
+### backgroundColor
+
+Sets the `backgroundColor` style of the Subtitles text
+
+```js
+Subtitles.backgroundColor(0x90000000)
+```
+
+### textAlign
+
+Sets the `textAlign` style of the Subtitles text
+
+```js
+Subtitles.textAlign('center')
+```
+
+### position
+
+Sets the x and y positions of the Subtitles text.
+
+`x` value must be either a number or one of the following options: `'left'`, `'center'`, `'right'`. The default value for `x` is `'center'`.
+
+`y` value must be either a number or one of the following options: `'top'`, `'center'`, `'bottom'`. The default value for `y` is 'bottom'.
+
+```js
+Subtitles.position('center', 'top')
+Subtitles.position(100, 100)
+```
+
+### viewport
+
+Sets the width and height for the viewport of the Subtitles text. The viewport is the area in which the Subtitles text will be displayed. By default, Subtitles assumes the viewport is the same size as the App. If your video player is smaller, you can set the viewport to match the size of the video player to correctly position the Subtitles text.
+
+The first argument is the width of the viewport, the second argument is the height of the viewport.
+
+
+```js
+Subtitles.viewport(854, 480)
+```
+
+### maxWidth
+
+Sets the maximum width of the Subtitles text.
+
+```js
+Subtitles.maxWidth(1200)
+```
+
+### maxLines
+
+Sets the maximum number of lines for the Subtitles text.
+
+```js
+Subtitles.maxLines(2)
+```

index.js

@@ -43,3 +43,4 @@ export { default as TV } from './src/TV'
 export { default as Utils } from './src/Utils'
 export { default as VideoPlayer } from './src/VideoPlayer'
 export { default as Metadata } from './src/Metadata'
+export { default as Subtitles } from './src/Subtitles'

src/Application/index.js

@@ -119,6 +119,32 @@ export default function(App, appData, platformSettings) {
       Accessibility.colorshift(this, type, config)
     }
 
+    get keymapping() {
+      return this.stage.application.config.keys
+    }
+
+    /**
+     * This function overides the default keymap with the latest keymap.
+     * @param customKeymap
+     * @param keepDuplicates
+     */
+    overRideKeyMap(customKeymap, keepDuplicates = false) {
+      const baseKeymap = this.stage.application.config.keys
+      Object.keys(customKeymap).reduce((keymapping, key) => {
+        // prevent duplicate values to exist in final keymapping (i.e. 2 keys triggering 'Back')
+        if (!keepDuplicates) {
+          Object.keys(baseKeymap).forEach(baseKey => {
+            if (baseKey != key && baseKeymap[baseKey] == customKeymap[key]) {
+              delete keymapping[baseKey]
+            }
+          })
+        }
+        keymapping[key] = customKeymap[key]
+        return keymapping
+      }, baseKeymap)
+      return baseKeymap
+    }
+
     _setup() {
       Promise.all([
         this.loadFonts((App.config && App.config.fonts) || (App.getFonts && App.getFonts()) || []),