corysanin/tubestation
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Bug 1674152 - Building documentation for Picture-in-Picture using SphinxJS r=mtigley

Browse Source 
Changed formatting to support parsing, adding config files to target for parsing by SphinxJS via mach docs command.

Differential Revision: https://phabricator.services.mozilla.com/D105061
This commit is contained in:
Tony Froman
2021-03-26 21:55:19 +00:00
parent f4a4fdd9f1
commit e006ae203d
6 changed files with 112 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/conf.py
View File

@@ -63,6 +63,8 @@ js_source_path = [
"../toolkit/components/featuregates",
"../toolkit/mozapps/extensions",
"../toolkit/components/prompts/src",
"../toolkit/components/pictureinpicture",
"../toolkit/components/pictureinpicture/content",
]
root_for_relative_js_paths = ".."
jsdoc_config_path = "jsdoc.json"

63
toolkit/components/pictureinpicture/PictureInPicture.jsm
View File

@@ -140,7 +140,6 @@ class PictureInPictureParent extends JSWindowActorParent {
* This module is responsible for creating a Picture in Picture window to host
* a clone of a video element running in web content.
*/
var PictureInPicture = {
// Maps PictureInPictureParent actors to their corresponding PiP player windows
weakPipToWin: new WeakMap(),
@@ -151,7 +150,7 @@ var PictureInPicture = {
/**
* Returns the player window if one exists and if it hasn't yet been closed.
*
* @param pipActorRef (PictureInPictureParent)
* @param {PictureInPictureParent} pipActorRef
* Reference to the calling PictureInPictureParent actor
*
* @return {DOM Window} the player window if it exists and is not in the
@@ -188,6 +187,8 @@ var PictureInPicture = {
/**
* Called when the browser UI handles the View:PictureInPicture command via
* the keyboard.
*
* @param {Event} event
*/
onCommand(event) {
if (!Services.prefs.getBoolPref(PIP_ENABLED_PREF, false)) {
@@ -218,7 +219,7 @@ var PictureInPicture = {
/**
* Remove attribute which enables pip icon in tab
*
* @param window {Window}
* @param {Window} window
* A PictureInPicture player's window, used to resolve the player's
* associated originating content browser
*/
@@ -249,7 +250,7 @@ var PictureInPicture = {
/**
* Closes and waits for passed PiP player window to finish closing.
*
* @param pipWin {Window}
* @param {Window} pipWin
* Player window to close
*/
async closePipWindow(pipWin) {
@@ -317,11 +318,11 @@ var PictureInPicture = {
* A request has come up from content to open a Picture in Picture
* window.
*
* @param wgp (WindowGlobalParent)
* @param {WindowGlobalParent} wgps
* The WindowGlobalParent that is requesting the Picture in Picture
* window.
*
* @param videoData (object)
* @param {object} videoData
* An object containing the following properties:
*
* videoHeight (int):
@@ -330,7 +331,7 @@ var PictureInPicture = {
* videoWidth (int):
* The preferred width of the video.
*
* @returns Promise
* @returns {Promise}
* Resolves once the Picture in Picture window has been created, and
* the player component inside it has finished loading.
*/
@@ -380,6 +381,8 @@ var PictureInPicture = {
/**
* unload event has been called in player.js, cleanup our preserved
* browser object.
*
* @param {Window} window
*/
unload(window) {
TelemetryStopwatch.finish(
@@ -403,11 +406,11 @@ var PictureInPicture = {
* Open a Picture in Picture window on the same screen as parentWin,
* sized based on the information in videoData.
*
* @param parentWin (chrome window)
* @param {ChromeWindow} parentWin
* The window hosting the browser that requested the Picture in
* Picture window.
*
* @param videoData (object)
* @param {object} videoData
* An object containing the following properties:
*
* videoHeight (int):
@@ -416,10 +419,10 @@ var PictureInPicture = {
* videoWidth (int):
* The preferred width of the video.
*
* @param actorReference (PictureInPictureParent)
* @param {PictureInPictureParent} actorReference
* Reference to the calling PictureInPictureParent
*
* @returns Promise
* @returns {Promise}
* Resolves once the window has opened and loaded the player component.
*/
async openPipWindow(parentWin, videoData) {
@@ -461,13 +464,13 @@ var PictureInPicture = {
* and size. If those values are unknown or offscreen, then a default
* location and size is used.
*
* @param requestingWin (chrome window|player window)
* @param {ChromeWindow|PlayerWindow} requestingWin
* The window hosting the browser that requested the Picture in
* Picture window. If this is an existing player window then the returned
* player size and position will be determined based on the existing
* player window's size and position.
*
* @param videoData (object)
* @param {object} videoData
* An object containing the following properties:
*
* videoHeight (int):
@@ -476,7 +479,7 @@ var PictureInPicture = {
* videoWidth (int):
* The preferred width of the video.
*
* @returns (object)
* @returns {object}
* The size and position for the player window.
*
* top (int):
@@ -654,6 +657,14 @@ var PictureInPicture = {
return { top, left, width, height };
},
/**
* Resizes the the PictureInPicture player window.
*
* @param {object} videoData
* The source video's data.
* @param {PictureInPictureParent} actorRef
* Reference to the PictureInPicture parent actor.
*/
resizePictureInPictureWindow(videoData, actorRef) {
let win = this.getWeakPipPlayer(actorRef);
@@ -666,6 +677,13 @@ var PictureInPicture = {
win.moveTo(left, top);
},
/**
* Opens the context menu for toggling PictureInPicture.
*
* @param {Window} window
* @param {object} data
* Message data from the PictureInPictureToggleParent
*/
openToggleContextMenu(window, data) {
let document = window.document;
let popup = document.getElementById("pictureInPictureToggleContextMenu");
@@ -702,10 +720,10 @@ var PictureInPicture = {
/**
* This function takes a screen and will return the left, top, width and
* height of the screen
* @param screen
* @param {Screen} screen
* The screen we need to get the sizec and coordinates of
*
* @returns array
* @returns {array}
* Size and location of screen
*
* screenLeft.value (int):
@@ -759,14 +777,17 @@ var PictureInPicture = {
/**
* This function takes in a left and top value and returns the screen they
* are located on.
*
* If the left and top are not on any screen, it will return the
* default screen
* @param left
*
* @param {int} left
* left or x coordinate
* @param top
*
* @param {int} top
* top or y coordinate
*
* @returns screen
* @returns {Screen} screen
* the screen the left and top are on otherwise, default screen
*/
getWorkingScreen(left, top, width = 1, height = 1) {
@@ -784,7 +805,7 @@ var PictureInPicture = {
/**
* Saves position and size of Picture-in-Picture window
* @param win The Picture-in-Picture window
* @param {Window} win The Picture-in-Picture window
*/
savePosition(win) {
let xulStore = Services.xulStore;
@@ -802,7 +823,7 @@ var PictureInPicture = {
/**
* Load last Picture in Picture location and size
* @returns object
* @returns {object}
* The size and position of the last Picture in Picture window.
*
* top (int):

74
toolkit/components/pictureinpicture/content/player.js
View File

@@ -36,11 +36,11 @@ const BOTTOM_RIGHT_QUADRANT = 4;
* Public function to be called from PictureInPicture.jsm. This is the main
* entrypoint for initializing the player window.
*
* @param id (Number)
* @param {Number} id
* A unique numeric ID for the window, used for Telemetry Events.
* @param wgp (WindowGlobalParent)
* @param {WindowGlobalParent} wgp
* The WindowGlobalParent that is hosting the originating video.
* @param videoRef {ContentDOMReference}
* @param {ContentDOMReference} videoRef
* A reference to the video element that a Picture-in-Picture window
* is being created for
*/
@@ -52,7 +52,7 @@ function setupPlayer(id, wgp, videoRef) {
* Public function to be called from PictureInPicture.jsm. This update the
* controls based on whether or not the video is playing.
*
* @param isPlaying (Boolean)
* @param {Boolean} isPlaying
* True if the Picture-in-Picture video is playing.
*/
function setIsPlayingState(isPlaying) {
@@ -63,7 +63,7 @@ function setIsPlayingState(isPlaying) {
* Public function to be called from PictureInPicture.jsm. This update the
* controls based on whether or not the video is muted.
*
* @param isMuted (Boolean)
* @param {Boolean} isMuted
* True if the Picture-in-Picture video is muted.
*/
function setIsMutedState(isMuted) {
@@ -117,11 +117,11 @@ let Player = {
/**
* Initializes the player browser, and sets up the initial state.
*
* @param id (Number)
* @param {Number} id
* A unique numeric ID for the window, used for Telemetry Events.
* @param wgp (WindowGlobalParent)
* @param {WindowGlobalParent} wgp
* The WindowGlobalParent that is hosting the originating video.
* @param videoRef {ContentDOMReference}
* @param {ContentDOMReference} videoRef
* A reference to the video element that a Picture-in-Picture window
* is being created for
*/
@@ -427,6 +427,10 @@ let Player = {
);
},
/**
* Uses the PiP window's change in position to determine which direction
* the window has been moved in.
*/
determineDirectionDragged() {
// Determine change in window location.
let deltaX = this.oldMouseUpWindowX - window.screenX;
@@ -445,6 +449,12 @@ let Player = {
return dragDirection;
},
/**
* Event handler for "mouseup" events on the PiP window.
*
* @param {Event} event
* Event context details
*/
onMouseUp(event) {
if (
window.screenX != this.lastScreenX ||
@@ -536,11 +546,23 @@ let Player = {
this.oldMouseUpWindowY = window.screenY;
},
/**
* Event handler for resizing the PiP Window
*
* @param {Event} event
* Event context data object
*/
onResize(event) {
this.resizeDebouncer.disarm();
this.resizeDebouncer.arm();
},
/**
* Event handler for user issued commands
*
* @param {Event} event
* Event context data object
*/
onCommand(event) {
this.closePipWindow({ reason: "player-shortcut" });
},
@@ -552,18 +574,17 @@ let Player = {
_isPlaying: false,
/**
* isPlaying returns true if the video is currently playing.
* GET isPlaying returns true if the video is currently playing.
*
* @return Boolean
* SET isPlaying to true if the video is playing, false otherwise. This will
* update the internal state and displayed controls.
*
* @type {Boolean}
*/
get isPlaying() {
return this._isPlaying;
},
/**
* Set isPlaying to true if the video is playing, false otherwise. This will
* update the internal state and displayed controls.
*/
set isPlaying(isPlaying) {
this._isPlaying = isPlaying;
this.controls.classList.toggle("playing", isPlaying);
@@ -574,18 +595,17 @@ let Player = {
_isMuted: false,
/**
* isMuted returns true if the video is currently muted.
* GET isMuted returns true if the video is currently muted.
*
* @return Boolean
* SET isMuted to true if the video is muted, false otherwise. This will
* update the internal state and displayed controls.
*
* @type {Boolean}
*/
get isMuted() {
return this._isMuted;
},
/**
* Set isMuted to true if the video is muted, false otherwise. This will
* update the internal state and displayed controls.
*/
set isMuted(isMuted) {
this._isMuted = isMuted;
this.controls.classList.toggle("muted", isMuted);
@@ -594,6 +614,14 @@ let Player = {
document.l10n.setAttributes(audioButton, strId);
},
/**
* Used for recording telemetry in Picture-in-Picture.
*
* @param {string} type
* The type of PiP event being recorded.
* @param {object} args
* The data to pass to telemetry when the event is recorded.
*/
recordEvent(type, args) {
Services.telemetry.recordEvent(
"pictureinpicture",
@@ -607,7 +635,7 @@ let Player = {
/**
* Makes the player controls visible.
*
* @param revealIndefinitely (Boolean)
* @param {Boolean} revealIndefinitely
* If false, this will hide the controls again after
* CONTROLS_FADE_TIMEOUT_MS milliseconds has passed. If true, the controls
* will remain visible until revealControls is called again with
@@ -633,9 +661,9 @@ let Player = {
* impose a minimum window size. For other platforms, this function is a
* no-op.
*
* @param width (Number)
* @param {Number} width
* The width of the video being played.
* @param height (Number)
* @param {Number} height
* The height of the video being played.
*/
computeAndSetMinimumSize(width, height) {

9
toolkit/components/pictureinpicture/docs/index.rst
View File

@@ -188,3 +188,12 @@ If ``video`` is being cloned visually to another element, calling this method wi
boolean video.isCloningElementVisually;
A read-only value that returns ``true`` if ``video`` is being cloned visually.
API References
====================================
.. toctree::
:maxdepth: 1
picture-in-picture-api
player-api

4
toolkit/components/pictureinpicture/docs/picture-in-picture-api.rst Normal file
View File

@@ -0,0 +1,4 @@
PictureInPicture Reference
===========================
.. js:autoclass:: PictureInPicture
:members:

4
toolkit/components/pictureinpicture/docs/player-api.rst Normal file
View File

@@ -0,0 +1,4 @@
Player Reference
======================
.. js:autoclass:: Player
:members: