From af58c42cbb51c3e6f03f365ffe300ad1859f4d26 Mon Sep 17 00:00:00 2001 From: dmahajan980 Date: Thu, 13 Aug 2020 18:07:32 +0530 Subject: [PATCH 1/2] Added documentation for messageListener component --- docs/components/messageListener.md | 168 +++++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 docs/components/messageListener.md diff --git a/docs/components/messageListener.md b/docs/components/messageListener.md new file mode 100644 index 0000000..dce6c25 --- /dev/null +++ b/docs/components/messageListener.md @@ -0,0 +1,168 @@ + + +# `gamepad.messageListener` + +This component listens to the messages and signals sent by the [`inputMapper`](inputMapper.md) component in the content +scripts and then calls the action invokers according to the received message. + +## Using this grade + +The component can be used by creating its instance or by making a custom component using the grade. + +``` javascript +// Either create an instance of the messageListener. +var messageListenerInstanceOne = gamepad.messageListener(); + +// Otherwise create a custom component using the messageListener grade. +fluid.defaults("my.messageListener.grade", { + gradeNames: ["gamepad.messageListener", "my.CustomGrade"] +}); +var messageListenerInstanceTwo = my.messageListener.grade(); +``` + +## Component Options + +This component does not provide any configuration options. + +## Non-navigation Invokers + +### `{messageListener}.addListener()` + +- Returns: Nothing. + +Listens to the messages received from the [`inputMapper`](inputMapper.md) component in the content scripts and triggers +the [actionExecutor](#messagelisteneractionexecutoractiondata) invoker as a callback function. + +### `{messageListener}.actionExecutor(actionData)` + +- `actionData {Object}` The message object received from the [`inputMapper`](inputMapper.md) component in the content + scripts. +- Returns: Nothing. + +Identifies and triggers the **navigation-producing invokers** according to the `actionData`. The navigation-producing +invoker is triggered only if the component provides it. Each of these invokers accepts the following arguments: + +- `tabId`: ID of the currently active tab. +- `invert`: Whether direction of the given action should be in the opposite order (for thumbsticks). +- `active`: Whether a new tab or window should be focused when opened. +- `homepageURL`: URL that a new tab or window should load when opened. +- `left`: Position of the current browser window from the screen's left edge (in pixels). + +The invokers use only those arguments required to perform their specific action. + +## Navigation Invokers + +### `{messageListener}.openNewTab(active, homepageURL)` + +- `active {Boolean}` Whether a new browser tab should be active when opened. +- `homepageURL {String}` URL that a new browser tab should load when opened. +- Returns: Nothing. + +Opens a new tab in the current browser window using the +[`chrome.tabs.create`](https://developer.chrome.com/extensions/tabs#method-create) method. + +### `{messageListener}.closeCurrentTab(tabId)` + +- `tabId {Number}` ID of the currently active tab. +- Returns: Nothing. + +Closes the current tab in the active browser window using the +[`chrome.tabs.remove`](https://developer.chrome.com/extensions/tabs#method-remove) method. + +### `{messageListener}.goToPreviousTab()` + +- Returns: Nothing. + +Switches from the current tab to the previous tab in the active browser window. If the active tab is the first tab in +the list, it will switch to the last tab. + +### `{messageListener}.goToNextTab()` + +- Returns: Nothing. + +Switches from the current tab to the next tab in the active browser window. If the active tab is the last tab in the +list, it will switch to the first tab. + +### `{messageListener}.openNewWindow(active, homepageURL)` + +- `active {Boolean}` Whether a new browser window should be active when opened. +- `homepageURL {String}` URL that a new browser window should load when opened. +- Returns: Nothing. + +Opens a new browser window using the +[`chrome.windows.create`](https://developer.chrome.com/extensions/windows#method-create) method. + +### `{messageListener}.closeCurrentWindow()` + +- Returns: Nothing. + +Closes the currently active browser window using the +[`chrome.windows.getCurrent`](https://developer.chrome.com/extensions/windows#method-getCurrent) and +[`chrome.windows.remove`](https://developer.chrome.com/extensions/windows#method-remove) methods. + +### `{messageListener}.goToPreviousWindow()` + +- Returns: Nothing. + +Switches from the currently active browser window to the previous browser window. If the active window is the first +window in the list, it will switch to the last window. + +### `{messageListener}.goToNextWindow()` + +- Returns: Nothing. + +Switches from the currently active browser window to the next browser window. If the active window is the last window in +the list, it will switch to the first window. + +### `{messageListener}.zoomIn()` + +- Returns: Nothing. + +Zoom in on the current tab in the active browser window using the +[`chrome.tabs.query`](https://developer.chrome.com/extensions/tabs#method-query), +[`chrome.tabs.getZoom`](https://developer.chrome.com/extensions/tabs#method-getZoom), and +[`chrome.tabs.setZoom`](https://developer.chrome.com/extensions/tabs#method-setZoom) methods. + +### `{messageListener}.zoomOut()` + +- Returns: Nothing. + +Zoom out on the current tab in the active browser window using the +[`chrome.tabs.query`](https://developer.chrome.com/extensions/tabs#method-query), +[`chrome.tabs.getZoom`](https://developer.chrome.com/extensions/tabs#method-getZoom), and +[`chrome.tabs.setZoom`](https://developer.chrome.com/extensions/tabs#method-setZoom) methods. + +### `{messageListener}.maximizeWindow(left)` + +- `left {Number}` Position of the current browser window from the screen's left edge (in pixels). +- Returns: Nothing. + +Maximize the current browser window. Saves the browser window's position and dimensions inside the `windowProperties` +member variable before the window is maximized. + +### `{messageListener}.restoreWindowSize(left)` + +- `left {Number}` Position of the current browser window from the screen's left edge (in pixels). +- Returns: Nothing. + +Restores the size of the currently active browser window. The previous dimensions and positions are taken from the +`windowProperties` member variable if stored previously. Otherwise, a set of default values are used for the window's +position and dimensions. + +### `{messageListener}.reopenTabOrWindow()` + +- Returns: Nothing. + +Reopens the last closed browser session using the +[`chrome.sessions.restore`](https://developer.chrome.com/extensions/sessions#method-restore) method. The closed session +could be a tab or a window. From 73f11d2f00ddb2d698fc33ef62c6bb8dc2266460 Mon Sep 17 00:00:00 2001 From: dmahajan980 Date: Fri, 14 Aug 2020 17:40:38 +0530 Subject: [PATCH 2/2] Updated messageListener component documentation --- docs/components/messageListener.md | 39 ++++++++++++------- src/js/background_scripts/message-listener.js | 1 + 2 files changed, 25 insertions(+), 15 deletions(-) diff --git a/docs/components/messageListener.md b/docs/components/messageListener.md index dce6c25..28aa838 100644 --- a/docs/components/messageListener.md +++ b/docs/components/messageListener.md @@ -40,13 +40,14 @@ This component does not provide any configuration options. - Returns: Nothing. -Listens to the messages received from the [`inputMapper`](inputMapper.md) component in the content scripts and triggers +Listens to the messages received from the [`inputMapper`](inputMapper.md) component in the content scripts by using +[`chrome.runtime.onMessage.addListener`](https://developer.chrome.com/extensions/runtime#event-onMessage) and triggers the [actionExecutor](#messagelisteneractionexecutoractiondata) invoker as a callback function. ### `{messageListener}.actionExecutor(actionData)` - `actionData {Object}` The message object received from the [`inputMapper`](inputMapper.md) component in the content - scripts. + scripts. (see below) - Returns: Nothing. Identifies and triggers the **navigation-producing invokers** according to the `actionData`. The navigation-producing @@ -55,17 +56,26 @@ invoker is triggered only if the component provides it. Each of these invokers a - `tabId`: ID of the currently active tab. - `invert`: Whether direction of the given action should be in the opposite order (for thumbsticks). - `active`: Whether a new tab or window should be focused when opened. -- `homepageURL`: URL that a new tab or window should load when opened. +- `homepageURL`: The URL that a new tab or window should load when opened. - `left`: Position of the current browser window from the screen's left edge (in pixels). -The invokers use only those arguments required to perform their specific action. +The invokers use only those arguments required to perform their specific action. Some of these arguments are extracted +from the `actionData` object recieved from the content scripts. Below is an example of the `actionData` object. + +``` snippet +{ + action: "openNewTab", + active: true, + homepageURL: "https://www.google.com/" +} +``` ## Navigation Invokers ### `{messageListener}.openNewTab(active, homepageURL)` -- `active {Boolean}` Whether a new browser tab should be active when opened. -- `homepageURL {String}` URL that a new browser tab should load when opened. +- `active {Boolean}` Whether a new browser tab should be focused when opened. +- `homepageURL {String}` The URL that a new browser tab should load when opened. - Returns: Nothing. Opens a new tab in the current browser window using the @@ -84,19 +94,19 @@ Closes the current tab in the active browser window using the - Returns: Nothing. Switches from the current tab to the previous tab in the active browser window. If the active tab is the first tab in -the list, it will switch to the last tab. +the list, then the focus will move to the last tab. ### `{messageListener}.goToNextTab()` - Returns: Nothing. Switches from the current tab to the next tab in the active browser window. If the active tab is the last tab in the -list, it will switch to the first tab. +list, then the focus will move to the first tab. ### `{messageListener}.openNewWindow(active, homepageURL)` -- `active {Boolean}` Whether a new browser window should be active when opened. -- `homepageURL {String}` URL that a new browser window should load when opened. +- `active {Boolean}` Whether a new browser window should be focused when opened. +- `homepageURL {String}` The URL that a new browser window should load when opened. - Returns: Nothing. Opens a new browser window using the @@ -115,14 +125,14 @@ Closes the currently active browser window using the - Returns: Nothing. Switches from the currently active browser window to the previous browser window. If the active window is the first -window in the list, it will switch to the last window. +window in the list, then the focus will move to the last window. ### `{messageListener}.goToNextWindow()` - Returns: Nothing. Switches from the currently active browser window to the next browser window. If the active window is the last window in -the list, it will switch to the first window. +the list, then the focus will move to the first window. ### `{messageListener}.zoomIn()` @@ -163,6 +173,5 @@ position and dimensions. - Returns: Nothing. -Reopens the last closed browser session using the -[`chrome.sessions.restore`](https://developer.chrome.com/extensions/sessions#method-restore) method. The closed session -could be a tab or a window. +Reopens the last closed browser tab or window using the +[`chrome.sessions.restore`](https://developer.chrome.com/extensions/sessions#method-restore) method. diff --git a/src/js/background_scripts/message-listener.js b/src/js/background_scripts/message-listener.js index 2d46c66..4b7a6d8 100644 --- a/src/js/background_scripts/message-listener.js +++ b/src/js/background_scripts/message-listener.js @@ -27,6 +27,7 @@ https://github.com/fluid-lab/gamepad-navigator/blob/master/LICENSE windowProperties: {} }, invokers: { + // TODO: Rename the addListener invoker and update its documentation. addListener: { "this": "chrome.runtime.onMessage", method: "addListener",