Skip to content

GitLab

T
tangled
Commit d5de6d0d authored by Henrique Nakashima's avatar Henrique Nakashima Committed by Commit Bot
Browse files
Options

Homogenize order of tags in chrome/browser/resources/pdf jsdoc. 

The format should be:

/**
 * Description.
 *
 * @param {Foo} foo The foo
 * @return {Bar}
 * @private
 */

Cq-Include-Trybots: master.tryserver.chromium.linux:closure_compilation
Change-Id: I48fbf027e16a07a37c5688cac41084bf500e7f93
Reviewed-on: https://chromium-review.googlesource.com/1005908
Commit-Queue: Henrique Nakashima <hnakashima@chromium.org>
Reviewed-by: default avatarDemetrios Papadopoulos <dpapad@chromium.org>
Cr-Commit-Position: refs/heads/master@{#550682}
parent 5713ca49
Hide whitespace changes
Inline Side-by-side
Showing with 204 additions and 83 deletions
chrome/browser/resources/pdf/browser_api.js
View file @ d5de6d0d
......@@ -5,7 +5,6 @@
'use strict';
/**
* Returns a promise that will resolve to the default zoom factor.
* @param {!Object} streamInfo The stream object pointing to the data contained
* in the PDF.
* @return {Promise<number>} A promise that will resolve to the default zoom
......@@ -28,6 +27,7 @@ function lookupDefaultZoom(streamInfo) {
* Returns a promise that will resolve to the initial zoom factor
* upon starting the plugin. This may differ from the default zoom
* if, for example, the page is zoomed before the plugin is run.
*
* @param {!Object} streamInfo The stream object pointing to the data contained
* in the PDF.
* @return {Promise<number>} A promise that will resolve to the initial zoom
......@@ -64,10 +64,10 @@ class BrowserApi {
}
/**
* Returns a promise to a BrowserApi.
* @param {!Object} streamInfo The stream object pointing to the data
* contained in the PDF.
* @param {BrowserApi.ZoomBehavior} zoomBehavior How to manage zoom.
* @return {Promise<BrowserApi>} A promise to a BrowserApi.
*/
static create(streamInfo, zoomBehavior) {
return Promise
......@@ -79,8 +79,8 @@ class BrowserApi {
}
/**
* Returns the stream info pointing to the data contained in the PDF.
* @return {Object} The stream info object.
* @return {Object} The stream info object pointing to the data contained in
* the PDF.
*/
getStreamInfo() {
return this.streamInfo_;
......@@ -96,6 +96,7 @@ class BrowserApi {
/**
* Sets the browser zoom.
*
* @param {number} zoom The zoom factor to send to the browser.
* @return {Promise} A promise that will be resolved when the browser zoom
* has been updated.
......@@ -109,7 +110,6 @@ class BrowserApi {
}
/**
* Returns the default browser zoom factor.
* @return {number} The default browser zoom factor.
*/
getDefaultZoom() {
......@@ -117,7 +117,6 @@ class BrowserApi {
}
/**
* Returns the initial browser zoom factor.
* @return {number} The initial browser zoom factor.
*/
getInitialZoom() {
......@@ -125,7 +124,6 @@ class BrowserApi {
}
/**
* Returns how to manage the zoom.
* @return {BrowserApi.ZoomBehavior} How to manage zoom.
*/
getZoomBehavior() {
......@@ -134,6 +132,7 @@ class BrowserApi {
/**
* Adds an event listener to be notified when the browser zoom changes.
*
* @param {!Function} listener The listener to be called with the new zoom
* factor.
*/
......@@ -164,6 +163,7 @@ BrowserApi.ZoomBehavior = {
/**
* Creates a BrowserApi for an extension running as a mime handler.
*
* @return {Promise<BrowserApi>} A promise to a BrowserApi instance constructed
* using the mimeHandlerPrivate API.
*/
......@@ -199,6 +199,7 @@ function createBrowserApiForMimeHandlerView() {
/**
* Creates a BrowserApi instance for an extension not running as a mime handler.
*
* @return {Promise<BrowserApi>} A promise to a BrowserApi instance constructed
* from the URL.
*/
......@@ -228,7 +229,6 @@ function createBrowserApiForPrintPreview() {
}
/**
* Returns a promise that will resolve to a BrowserApi instance.
* @return {Promise<BrowserApi>} A promise to a BrowserApi instance for the
* current environment.
*/
......
chrome/browser/resources/pdf/coords_transformer.js
View file @ d5de6d0d
......@@ -42,6 +42,7 @@ window.PDFCoordsTransformer = class {
/**
* Send a 'transformPagePoint' message to the plugin.
*
* @param {function(Object, Object):void} callback Function to call when the
* response is received.
* @param {Object} params User parameters to be used in |callback|.
......@@ -59,6 +60,7 @@ window.PDFCoordsTransformer = class {
/**
* Call when 'transformPagePointReply' is received from the plugin.
*
* @param {Object} message The message received from the plugin.
*/
onReplyReceived(message) {
......
chrome/browser/resources/pdf/gesture_detector.js
View file @ d5de6d0d
......@@ -10,7 +10,6 @@
*/
class GestureDetector {
/**
* Constructs a GestureDetector.
* @param {!Element} element The element to monitor for touch gestures.
*/
constructor(element) {
......@@ -37,18 +36,20 @@ class GestureDetector {
this.pinchStartEvent_ = null;
this.lastTouchTouchesCount_ = 0;
/** @private {?TouchEvent} */
/** @private {TouchEvent} */
this.lastEvent_ = null;
/**
* The scale relative to the start of the pinch when handling ctrl-wheels.
* null when there is no ongoing pinch.
*
* @private {?number}
*/
this.accumulatedWheelScale_ = null;
/**
* A timeout ID from setTimeout used for sending the pinchend event when
* handling ctrl-wheels.
*
* @private {?number}
*/
this.wheelEndTimeout_ = null;
......@@ -60,6 +61,7 @@ class GestureDetector {
/**
* Add a |listener| to be notified of |type| events.
*
* @param {string} type The event type to be notified for.
* @param {!Function} listener The callback.
*/
......@@ -70,7 +72,6 @@ class GestureDetector {
}
/**
* Returns true if the last touch start was a two finger touch.
* @return {boolean} True if the last touch start was a two finger touch.
*/
wasTwoFingerTouch() {
......@@ -79,8 +80,9 @@ class GestureDetector {
/**
* Call the relevant listeners with the given |pinchEvent|.
* @private
*
* @param {!Object} pinchEvent The event to notify the listeners of.
* @private
*/
notify_(pinchEvent) {
let listeners = this.listeners_.get(pinchEvent.type);
......@@ -91,8 +93,9 @@ class GestureDetector {
/**
* The callback for touchstart events on the element.
* @private
*
* @param {!TouchEvent} event Touch event on the element.
* @private
*/
onTouchStart_(event) {
this.lastTouchTouchesCount_ = event.touches.length;
......@@ -106,8 +109,9 @@ class GestureDetector {
/**
* The callback for touch move, end, and cancel events on the element.
* @private
*
* @param {!TouchEvent} event Touch event on the element.
* @private
*/
onTouch_(event) {
if (!this.pinchStartEvent_)
......@@ -153,8 +157,9 @@ class GestureDetector {
/**
* The callback for wheel events on the element.
* @private
*
* @param {!WheelEvent} event Wheel event on the element.
* @private
*/
onWheel_(event) {
// We handle ctrl-wheels to invoke our own pinch zoom. On Mac, synthetic
......@@ -211,11 +216,12 @@ class GestureDetector {
/**
* Computes the change in scale between this touch event
* and a previous one.
* @private
*
* @param {!TouchEvent} event Latest touch event on the element.
* @param {!TouchEvent} prevEvent A previous touch event on the element.
* @return {?number} The ratio of the scale of this event and the
* scale of the previous one.
* @private
*/
static pinchScaleRatio_(event, prevEvent) {
let distance1 = GestureDetector.distance_(prevEvent);
......@@ -225,9 +231,10 @@ class GestureDetector {
/**
* Computes the distance between fingers.
* @private
*
* @param {!TouchEvent} event Touch event with at least 2 touch points.
* @return {number} Distance between touch[0] and touch[1].
* @private
*/
static distance_(event) {
let touch1 = event.touches[0];
......@@ -239,9 +246,10 @@ class GestureDetector {
/**
* Computes the midpoint between fingers.
* @private
*
* @param {!TouchEvent} event Touch event with at least 2 touch points.
* @return {!Object} Midpoint between touch[0] and touch[1].
* @private
*/
static center_(event) {
let touch1 = event.touches[0];
......
chrome/browser/resources/pdf/main.js
View file @ d5de6d0d
......@@ -6,6 +6,7 @@
/**
* Global PDFViewer object, accessible for testing.
*
* @type Object
*/
var viewer;
......@@ -15,12 +16,14 @@ var viewer;
/**
* Stores any pending messages received which should be passed to the
* PDFViewer when it is created.
*
* @type Array
*/
var pendingMessages = [];
/**
* Handles events that are received prior to the PDFViewer being created.
*
* @param {Object} message A message event received.
*/
function handleScriptingMessage(message) {
......@@ -29,6 +32,7 @@ function handleScriptingMessage(message) {
/**
* Initialize the global PDFViewer and pass any outstanding messages to it.
*
* @param {Object} browserApi An object providing an API to the browser.
*/
function initViewer(browserApi) {
......
chrome/browser/resources/pdf/metrics.js
View file @ d5de6d0d
......@@ -48,6 +48,7 @@ window.PDFMetrics = class {
/**
* Call when the zoom mode is changed to fit a FittingType.
*
* @param {FittingType} fittingType the new FittingType.
*/
onFitTo(fittingType) {}
......@@ -73,6 +74,7 @@ window.PDFMetrics = class {
* This is used in print preview mode to avoid bundling the actions in the PDF
* viewer and the print preview in the same histogram. Also, metricsPrivate is
* not available in print preview.
*
* @implements {PDFMetrics}
*/
window.PDFMetricsDummy = class {
......@@ -100,6 +102,7 @@ window.PDFMetricsDummy = class {
/**
* Implementation of PDFMetrics that logs the corresponding metrics to UMA
* through chrome.metricsPrivate.
*
* @implements {PDFMetrics}
*/
window.PDFMetricsImpl = class {
......@@ -164,14 +167,15 @@ window.PDFMetricsImpl = class {
}
/**
* @private
* Logs the "first" event code if it hasn't been logged by this instance yet
* and also log the "total" event code. This distinction allows analyzing
* both:
* - in what percentage of documents each action was taken;
* - how many times, on average, each action is taken on a document;
*
* @param {number} firstEventCode event code for the "first" metric.
* @return {number} totalEventCode event code for the "total" metric.
* @private
*/
logFirstAndTotal_(firstEventCode, totalEventCode) {
this.log_(totalEventCode);
......@@ -179,19 +183,21 @@ window.PDFMetricsImpl = class {
}
/**
* @private
* Logs the given event code to chrome.metricsPrivate.
*
* @param {number} eventCode event code to log.
* @private
*/
log_(eventCode) {
chrome.metricsPrivate.recordValue(this.actionsMetric_, eventCode);
}
/**
* @private
* Logs the given event code. Subsequent calls of this method with the same
* event code have no effect on the this PDFMetrics instance.
*
* @param {number} eventCode event code to log.
* @private
*/
logOnlyFirstTime_(eventCode) {
if (!this.firstEventLogged_.has(eventCode)) {
......
chrome/browser/resources/pdf/navigator.js
View file @ d5de6d0d
......@@ -7,6 +7,7 @@
/**
* Creates a new NavigatorDelegate for calling browser-specific functions to
* do the actual navigating.
*
* @param {number} tabId The tab ID of the PDF viewer or -1 if the viewer is
* not displayed in a tab.
* @constructor
......@@ -17,6 +18,7 @@ function NavigatorDelegate(tabId) {
/**
* Creates a new Navigator for navigating to links inside or outside the PDF.
*
* @param {string} originalUrl The original page URL.
* @param {Object} viewport The viewport info of the page.
* @param {Object} paramsParser The object for URL parsing.
......@@ -34,8 +36,8 @@ function Navigator(originalUrl, viewport, paramsParser, navigatorDelegate) {
NavigatorDelegate.prototype = {
/**
* @public
* Called when navigation should happen in the current tab.
*
* @param {string} url The url to be opened in the current tab.
*/
navigateInCurrentTab: function(url) {
......@@ -48,8 +50,8 @@ NavigatorDelegate.prototype = {
},
/**
* @public
* Called when navigation should happen in the new tab.
*
* @param {string} url The url to be opened in the new tab.
* @param {boolean} active Indicates if the new tab should be the active tab.
*/
......@@ -63,8 +65,8 @@ NavigatorDelegate.prototype = {
},
/**
* @public
* Called when navigation should happen in the new window.
*
* @param {string} url The url to be opened in the new window.
*/
navigateInNewWindow: function(url) {
......@@ -95,6 +97,7 @@ Navigator.prototype = {
/**
* Function to navigate to the given URL. This might involve navigating
* within the PDF page or opening a new url (in the same tab or a new tab).
*
* @param {string} url The URL to navigate to.
* @param {number} disposition The window open disposition when
* navigating to the new URL.
......@@ -148,10 +151,11 @@ Navigator.prototype = {
},
/**
* @private
* Called when the viewport position is received.
*
* @param {Object} viewportPosition Dictionary containing the viewport
* position.
* @private
*/
onViewportReceived_: function(viewportPosition) {
var originalUrl = this.originalUrl_;
......@@ -172,10 +176,11 @@ Navigator.prototype = {
},
/**
* @private
* Checks if the URL starts with a scheme and is not just a scheme.
*
* @param {string} url The input URL
* @return {boolean} Whether the url is valid.
* @private
*/
isValidUrl_: function(url) {
// Make sure |url| starts with a valid scheme.
......@@ -200,11 +205,12 @@ Navigator.prototype = {
},
/**
* @private
* Attempt to figure out what a URL is when there is no scheme.
*
* @param {string} url The input URL
* @return {string} The URL with a scheme or the original URL if it is not
* possible to determine the scheme.
* @private
*/
guessUrlWithoutScheme_: function(url) {
// If the original URL is mailto:, that does not make sense to start with,
......
chrome/browser/resources/pdf/open_pdf_params_parser.js
View file @ d5de6d0d
......@@ -12,7 +12,6 @@
*/
window.OpenPDFParamsParser = class {
/**
* Constructor.
* @param {function(Object)} postMessageCallback
* Function called to fetch information for a named destination.
*/
......@@ -25,11 +24,12 @@ window.OpenPDFParamsParser = class {
}
/**
* @private
* Parse zoom parameter of open PDF parameters. The PDF should be opened at
* the specified zoom level.
*
* @param {string} paramValue zoom value.
* @return {Object} Map with zoom parameters (zoom and position).
* @private
*/
parseZoomParam_(paramValue) {
const paramValueSplit = paramValue.split(',');
......@@ -55,11 +55,12 @@ window.OpenPDFParamsParser = class {
}
/**
* @private
* Parse view parameter of open PDF parameters. The PDF should be opened at
* the specified fitting type mode and position.
*
* @param {string} paramValue view value.
* @return {Object} Map with view parameters (view and viewPosition).
* @private
*/
parseViewParam_(paramValue) {
const viewModeComponents = paramValue.toLowerCase().split(',');
......@@ -92,9 +93,10 @@ window.OpenPDFParamsParser = class {
/**
* Parse the parameters encoded in the fragment of a URL into a dictionary.
* @private
*
* @param {string} url to parse
* @return {Object} Key-value pairs of URL parameters
* @private
*/
parseUrlParams_(url) {
const params = {};
......@@ -126,6 +128,7 @@ window.OpenPDFParamsParser = class {
* Parse PDF url parameters used for controlling the state of UI. These need
* to be available when the UI is being initialized, rather than when the PDF
* is finished loading.
*
* @param {string} url that needs to be parsed.
* @return {Object} parsed url parameters.
*/
......@@ -144,6 +147,7 @@ window.OpenPDFParamsParser = class {
* and specify actions to be performed when opening pdf files.
* See http://www.adobe.com/content/dam/Adobe/en/devnet/acrobat/
* pdfs/pdf_open_parameters.pdf for details.
*
* @param {string} url that needs to be parsed.
* @param {Function} callback function to be called with viewport info.
*/
......@@ -180,6 +184,7 @@ window.OpenPDFParamsParser = class {
/**
* This is called when a named destination is received and the page number
* corresponding to the request for which a named destination is passed.
*
* @param {number} pageNumber The page corresponding to the named destination
* requested.
*/
......
chrome/browser/resources/pdf/pdf.js
View file @ d5de6d0d
......@@ -22,6 +22,7 @@ function getScrollbarWidth() {
/**
* Return the filename component of a URL, percent decoded if possible.
*
* @param {string} url The URL to get the filename from.
* @return {string} The filename component.
*/
......@@ -42,6 +43,7 @@ function getFilenameFromURL(url) {
/**
* Whether keydown events should currently be ignored. Events are ignored when
* an editable element has focus, to allow for proper editing controls.
*
* @param {HTMLElement} activeElement The currently selected DOM node.
* @return {boolean} True if keydown events should be ignored.
*/
......@@ -88,8 +90,9 @@ PDFViewer.DARK_BACKGROUND_COLOR = '0xFF525659';
/**
* Creates a new PDFViewer. There should only be one of these objects per
* document.
* @constructor
*
* @param {!BrowserApi} browserApi An object providing an API to the browser.
* @constructor
*/
function PDFViewer(browserApi) {
this.browserApi_ = browserApi;
......@@ -289,10 +292,11 @@ function PDFViewer(browserApi) {
PDFViewer.prototype = {
/**
* @private
* Handle key events. These may come from the user directly or via the
* scripting API.
*
* @param {KeyboardEvent} e the event to handle.
* @private
*/
handleKeyEvent_: function(e) {
var position = this.viewport_.position;
......@@ -448,8 +452,9 @@ PDFViewer.prototype = {
},
/**
* @private
* Rotate the plugin clockwise.
*
* @private
*/
rotateClockwise_: function() {
this.metrics.onRotation();
......@@ -457,8 +462,9 @@ PDFViewer.prototype = {
},
/**
* @private
* Rotate the plugin counter-clockwise.
*
* @private
*/
rotateCounterClockwise_: function() {
this.metrics.onRotation();
......@@ -466,9 +472,10 @@ PDFViewer.prototype = {
},
/**
* @private
* Request to change the viewport fitting type.
*
* @param {CustomEvent} e Event received with the new FittingType as detail.
* @private
*/
fitToChanged_: function(e) {
if (e.detail.fittingType == FittingType.FIT_TO_PAGE) {
......@@ -486,25 +493,28 @@ PDFViewer.prototype = {
},
/**
* @private
* Notify the plugin to print.
*
* @private
*/
print_: function() {
this.postMessage_({type: 'print'});
},
/**
* @private
* Notify the plugin to save.
*
* @private
*/
save_: function() {
this.postMessage_({type: 'save'});
},
/**
* @private
* Sends a 'documentLoaded' message to the PDFScriptingAPI if the document has
* finished loading.
*
* @private
*/
sendDocumentLoadedMessage_: function() {
if (this.loadState_ == LoadState.LOADING)
......@@ -516,11 +526,12 @@ PDFViewer.prototype = {
},
/**
* @private
* Handle open pdf parameters. This function updates the viewport as per
* the parameters mentioned in the url while opening pdf. The order is
* important as later actions can override the effects of previous actions.
*
* @param {Object} params The open params passed in the URL.
* @private
*/
handleURLParams_: function(params) {
if (params.zoom)
......@@ -550,13 +561,14 @@ PDFViewer.prototype = {
},
/**
* @private
* Moves the viewport to a point in a page. Called back after a
* 'transformPagePointReply' is returned from the plugin.
*
* @param {string} origin Identifier for the caller for logging purposes.
* @param {number} page The index of the page to go to. zero-based.
* @param {Object} message Message received from the plugin containing the
* x and y to navigate to in screen coordinates.
* @private
*/
goToPageAndXY_: function(origin, page, message) {
this.viewport_.goToPageAndXY(page, message.x, message.y);
......@@ -565,10 +577,11 @@ PDFViewer.prototype = {
},
/**
* @private
* Update the loading progress of the document in response to a progress
* message being received from the plugin.
*
* @param {number} progress the progress as a percentage.
* @private
*/
updateProgress_: function(progress) {
if (this.toolbar_)
......@@ -600,10 +613,11 @@ PDFViewer.prototype = {
},
/**
* @private
* Load a dictionary of translated strings into the UI. Used as a callback for
* chrome.resourcesPrivate.
*
* @param {Object} strings Dictionary of translated strings
* @private
*/
handleStrings_: function(strings) {
document.documentElement.dir = strings.textdirection;
......@@ -616,10 +630,11 @@ PDFViewer.prototype = {
},
/**
* @private
* An event handler for handling password-submitted events. These are fired
* when an event is entered into the password screen.
*
* @param {Object} event a password-submitted event.
* @private
*/
onPasswordSubmitted_: function(event) {
this.postMessage_(
......@@ -627,19 +642,21 @@ PDFViewer.prototype = {
},
/**
* @private
* Post a message to the PPAPI plugin. Some messages will cause an async reply
* to be received through handlePluginMessage_().
*
* @param {Object} message Message to post.
* @private
*/
postMessage_: function(message) {
this.plugin_.postMessage(message);
},
/**
* @private
* An event handler for handling message events received from the plugin.
*
* @param {MessageObject} message a message event.
* @private
*/
handlePluginMessage_: function(message) {
switch (message.data.type.toString()) {
......@@ -742,9 +759,10 @@ PDFViewer.prototype = {
},
/**
* @private
* A callback that's called before the zoom changes. Notify the plugin to stop
* reacting to scroll events while zoom is taking place to avoid flickering.
*
* @private
*/
beforeZoom_: function() {
this.postMessage_({type: 'stopScrolling'});
......@@ -765,9 +783,10 @@ PDFViewer.prototype = {
},
/**
* @private
* A callback that's called after the zoom changes. Notify the plugin of the
* zoom change and to continue reacting to scroll events.
*
* @private
*/
afterZoom_: function() {
var position = this.viewport_.position;
......@@ -792,10 +811,10 @@ PDFViewer.prototype = {
},
/**
* @param {boolean} userInitiated The value to set |isUserInitiatedEvent_|
* to.
* @private
* A callback that sets |isUserInitiatedEvent_| to |userInitiated|.
*
* @param {boolean} userInitiated The value to set |isUserInitiatedEvent_| to.
* @private
*/
setUserInitiated_: function(userInitiated) {
if (this.isUserInitiatedEvent_ == userInitiated) {
......@@ -805,9 +824,10 @@ PDFViewer.prototype = {
},
/**
* @private
* A callback that's called when an update to a pinch zoom is detected.
*
* @param {!Object} e the pinch event.
* @private
*/
onPinchUpdate_: function(e) {
// Throttle number of pinch events to one per frame.
......@@ -821,9 +841,10 @@ PDFViewer.prototype = {
},
/**
* @private
* A callback that's called when the end of a pinch zoom is detected.
*
* @param {!Object} e the pinch event.
* @private
*/
onPinchEnd_: function(e) {
// Using rAF for pinch end prevents pinch updates scheduled by rAF getting
......@@ -834,9 +855,10 @@ PDFViewer.prototype = {
},
/**
* @private
* A callback that's called when the start of a pinch zoom is detected.
*
* @param {!Object} e the pinch event.
* @private
*/
onPinchStart_: function(e) {
// We also use rAF for pinch start, so that if there is a pinch end event
......@@ -847,8 +869,9 @@ PDFViewer.prototype = {
},
/**
* @private
* A callback that's called after the viewport changes.
*
* @private
*/
viewportChanged_: function() {
if (!this.documentDimensions_)
......@@ -910,6 +933,7 @@ PDFViewer.prototype = {
* Handle a scripting message from outside the extension (typically sent by
* PDFScriptingAPI in a page containing the extension) to interact with the
* plugin.
*
* @param {MessageObject} message the message to handle.
*/
handleScriptingMessage: function(message) {
......@@ -941,10 +965,11 @@ PDFViewer.prototype = {
},
/**
* @private
* Handle scripting messages specific to print preview.
*
* @param {MessageObject} message the message to handle.
* @return {boolean} true if the message was handled, false otherwise.
* @private
*/
handlePrintPreviewScriptingMessage_: function(message) {
if (!this.isPrintPreview_)
......@@ -996,10 +1021,11 @@ PDFViewer.prototype = {
},
/**
* @private
* Send a scripting message outside the extension (typically to
* PDFScriptingAPI in a page containing the extension).
*
* @param {Object} message the message to send.
* @private
*/
sendScriptingMessage_: function(message) {
if (this.parentWindow_ && this.parentOrigin_) {
......@@ -1030,6 +1056,7 @@ PDFViewer.prototype = {
* - title
* - page (optional)
* - array of children (themselves bookmarks)
*
* @type {Array} the top-level bookmarks of the PDF.
*/
get bookmarks() {
......
chrome/browser/resources/pdf/pdf_scripting_api.js
View file @ d5de6d0d
......@@ -4,6 +4,7 @@
/**
* Turn a dictionary received from postMessage into a key event.
*
* @param {Object} dict A dictionary representing the key event.
* @return {Event} A key event.
*/
......@@ -21,6 +22,7 @@ function DeserializeKeyEvent(dict) {
/**
* Turn a key event into a dictionary which can be sent over postMessage.
*
* @param {Event} event A key event.
* @return {Object} A dictionary representing the key event.
*/
......@@ -44,6 +46,7 @@ var LoadState = {LOADING: 'loading', SUCCESS: 'success', FAILED: 'failed'};
/**
* Create a new PDFScriptingAPI. This provides a scripting interface to
* the PDF viewer so that it can be customized by things like print preview.
*
* @param {Window} window the window of the page containing the pdf viewer.
* @param {Object} plugin the plugin element containing the pdf viewer.
* @constructor
......@@ -100,11 +103,12 @@ function PDFScriptingAPI(window, plugin) {
PDFScriptingAPI.prototype = {
/**
* @private
* Send a message to the extension. If messages try to get sent before there
* is a plugin element set, then we queue them up and send them later (this
* can happen in print preview).
*
* @param {Object} message The message to send.
* @private
*/
sendMessage_: function(message) {
if (this.plugin_)
......@@ -116,6 +120,7 @@ PDFScriptingAPI.prototype = {
/**
* Sets the plugin element containing the PDF viewer. The element will usually
* be passed into the PDFScriptingAPI constructor but may also be set later.
*
* @param {Object} plugin the plugin element containing the PDF viewer.
*/
setPlugin: function(plugin) {
......@@ -133,6 +138,7 @@ PDFScriptingAPI.prototype = {
/**
* Sets the callback which will be run when the PDF viewport changes.
*
* @param {Function} callback the callback to be called.
*/
setViewportChangedCallback: function(callback) {
......@@ -142,6 +148,7 @@ PDFScriptingAPI.prototype = {
/**
* Sets the callback which will be run when the PDF document has finished
* loading. If the document is already loaded, it will be run immediately.
*
* @param {Function} callback the callback to be called.
*/
setLoadCallback: function(callback) {
......@@ -160,6 +167,7 @@ PDFScriptingAPI.prototype = {
/**
* Resets the PDF viewer into print preview mode.
*
* @param {string} url the url of the PDF to load.
* @param {boolean} grayscale whether or not to display the PDF in grayscale.
* @param {Array<number>} pageNumbers an array of the page numbers.
......@@ -178,6 +186,7 @@ PDFScriptingAPI.prototype = {
/**
* Load a page into the document while in print preview mode.
*
* @param {string} url the url of the pdf page to load.
* @param {number} index the index of the page to load.
*/
......@@ -196,6 +205,7 @@ PDFScriptingAPI.prototype = {
/**
* Get the selected text in the document. The callback will be called with the
* text that is selected. May only be called after document load.
*
* @param {Function} callback a callback to be called with the selected text.
* @return {boolean} true if the function is successful, false if there is an
* outstanding request for selected text that has not been answered.
......@@ -217,6 +227,7 @@ PDFScriptingAPI.prototype = {
/**
* Send a key event to the extension.
*
* @param {Event} keyEvent the key event to send to the extension.
*/
sendKeyEvent: function(keyEvent) {
......@@ -230,6 +241,7 @@ PDFScriptingAPI.prototype = {
* iframe which is navigated to the PDF viewer extension and 2) a scripting
* interface which provides access to various features of the viewer for use
* by print preview and accessibility.
*
* @param {string} src the source URL of the PDF to load initially.
* @param {string} baseUrl the base URL of the PDF viewer
* @return {HTMLIFrameElement} the iframe element containing the PDF viewer.
......
chrome/browser/resources/pdf/toolbar_manager.js
View file @ d5de6d0d
......@@ -47,10 +47,11 @@ function isMouseNearSideToolbar(e, window) {
/**
* Constructs a Toolbar Manager, responsible for co-ordinating between multiple
* toolbar elements.
* @constructor
*
* @param {Object} window The window containing the UI.
* @param {Object} toolbar The top toolbar element.
* @param {Object} zoomToolbar The zoom toolbar element.
* @constructor
*/
function ToolbarManager(window, toolbar, zoomToolbar) {
this.window_ = window;
......@@ -111,6 +112,7 @@ ToolbarManager.prototype = {
/**
* Whether a mousemove event is high enough velocity to reveal the toolbars.
*
* @param {MouseEvent} e Event to test.
* @return {boolean} true if the event is a high velocity mousemove, false
* otherwise.
......@@ -136,6 +138,7 @@ ToolbarManager.prototype = {
/**
* Wrapper around Date.now() to make it easily replaceable for testing.
*
* @return {number}
* @private
*/
......@@ -241,6 +244,7 @@ ToolbarManager.prototype = {
/**
* Updates the size of toolbar dropdowns based on the positions of the rest of
* the UI.
*
* @private
*/
resizeDropdowns_: function() {
......
chrome/browser/resources/pdf/viewport.js
View file @ d5de6d0d
......@@ -20,6 +20,7 @@ let PartialPoint;
/**
* Returns the height of the intersection of two rectangles.
*
* @param {Object} rect1 the first rect
* @param {Object} rect2 the second rect
* @return {number} the height of the intersection of the rects
......@@ -33,6 +34,7 @@ function getIntersectionHeight(rect1, rect2) {
/**
* Computes vector between two points.
*
* @param {!Object} p1 The first point.
* @param {!Object} p2 The second point.
* @return {!Object} The vector.
......@@ -51,7 +53,7 @@ function frameToPluginCoordinate(coordinateInFrame) {
/**
* Create a new viewport.
* @constructor
*
* @param {Window} window the window
* @param {Object} sizer is the element which represents the size of the
* document in the viewport
......@@ -64,6 +66,7 @@ function frameToPluginCoordinate(coordinateInFrame) {
* @param {number} defaultZoom The default zoom level.
* @param {number} topToolbarHeight The number of pixels that should initially
* be left blank above the document for the toolbar.
* @constructor
*/
function Viewport(
window, sizer, viewportChangedCallback, beforeZoomCallback,
......@@ -136,6 +139,7 @@ Viewport.ZOOM_FACTOR_RANGE = {
/**
* Clamps the zoom factor (or page scale factor) to be within the limits.
*
* @param {number} factor The zoom/scale factor.
* @return {number} The factor clamped within the limits.
*/
......@@ -161,6 +165,7 @@ Viewport.prototype = {
* Rounding is necessary when interacting with the renderer which tends to
* operate in integral values (for example for determining if scrollbars
* should be shown).
*
* @param {number} zoom The zoom to use to compute the scaled dimensions.
* @return {Object} A dictionary with scaled 'width'/'height' of the document.
* @private
......@@ -175,12 +180,13 @@ Viewport.prototype = {
},
/**
* @private
* Returns true if the document needs scrollbars at the given zoom level.
*
* @param {number} zoom compute whether scrollbars are needed at this zoom
* @return {Object} with 'horizontal' and 'vertical' keys which map to bool
* values indicating if the horizontal and vertical scrollbars are needed
* respectively.
* @private
*/
documentNeedsScrollbars_: function(zoom) {
var zoomedDimensions = this.getZoomedDocumentDimensions_(zoom);
......@@ -204,6 +210,7 @@ Viewport.prototype = {
/**
* Returns true if the document needs scrollbars at the current zoom level.
*
* @return {Object} with 'x' and 'y' keys which map to bool values
* indicating if the horizontal and vertical scrollbars are needed
* respectively.
......@@ -213,8 +220,9 @@ Viewport.prototype = {
},
/**
* @private
* Helper function called when the zoomed document size changes.
*
* @private
*/
contentSizeChanged_: function() {
var zoomedDimensions = this.getZoomedDocumentDimensions_(this.zoom);
......@@ -226,16 +234,18 @@ Viewport.prototype = {
},
/**
* @private
* Called when the viewport should be updated.
*
* @private
*/
updateViewport_: function() {
this.viewportChangedCallback_();
},
/**
* @private
* Called when the browser window size changes.
*
* @private
*/
resizeWrapper_: function() {
this.setUserInitiatedCallback_(false);
......@@ -244,8 +254,9 @@ Viewport.prototype = {
},
/**
* @private
* Called when the viewport size changes.
*
* @private
*/
resize_: function() {
if (this.fittingType_ == FittingType.FIT_TO_PAGE)
......@@ -270,6 +281,7 @@ Viewport.prototype = {
/**
* Scroll the viewport to the specified position.
*
* @type {Object} position The position to scroll to.
*/
set position(position) {
......@@ -298,6 +310,7 @@ Viewport.prototype = {
/**
* Set the zoom manager.
*
* @type {ZoomManager} manager the zoom manager to set.
*/
set zoomManager(manager) {
......@@ -328,12 +341,13 @@ Viewport.prototype = {
},
/**
* @private
* @param {function} f Function to wrap
* Used to wrap a function that might perform zooming on the viewport. This is
* required so that we can notify the plugin that zooming is in progress
* so that while zooming is taking place it can stop reacting to scroll events
* from the viewport. This is to avoid flickering.
*
* @param {function} f Function to wrap
* @private
*/
mightZoom_: function(f) {
this.beforeZoomCallback_();
......@@ -344,9 +358,10 @@ Viewport.prototype = {
},
/**
* @private
* Sets the zoom of the viewport.
*
* @param {number} newZoom the zoom level to zoom to.
* @private
*/
setZoomInternal_: function(newZoom) {
if (!this.allowedToChangeZoom_) {
......@@ -368,11 +383,12 @@ Viewport.prototype = {
},
/**
* @private
* Sets the zoom of the viewport.
* Same as setZoomInternal_ but for pinch zoom we have some more operations.
*
* @param {number} scaleDelta The zoom delta.
* @param {!Object} center The pinch center in content coordinates.
* @private
*/
setPinchZoomInternal_: function(scaleDelta, center) {
assert(
......@@ -399,10 +415,11 @@ Viewport.prototype = {
},
/**
* @private
* Converts a point from frame to content coordinates.
*
* @param {!Object} framePoint The frame coordinates.
* @return {!Object} The content coordinates.
* @private
*/
frameToContent: function(framePoint) {
// TODO(mcnee) Add a helper Point class to avoid duplicating operations
......@@ -415,6 +432,7 @@ Viewport.prototype = {
/**
* Sets the zoom to the given zoom level.
*
* @param {number} newZoom the zoom level to zoom to.
*/
setZoom: function(newZoom) {
......@@ -428,6 +446,7 @@ Viewport.prototype = {
/**
* Gets notified of the browser zoom changing seperately from the
* internal zoom.
*
* @param {number} oldBrowserZoom the previous value of the browser zoom.
*/
updateZoomFromBrowserChange: function(oldBrowserZoom) {
......@@ -463,9 +482,11 @@ Viewport.prototype = {
},
/**
* @private
* Get the which page is at a given y position.
*
* @param {number} y the y-coordinate to get the page at.
* @return {number} the index of a page overlapping the given y-coordinate.
* @private
*/
getPageAtY_: function(y) {
var min = 0;
......@@ -496,6 +517,7 @@ Viewport.prototype = {
/**
* Returns the page with the greatest proportion of its height in the current
* viewport.
*
* @return {number} the index of the most visible page.
*/
getMostVisiblePage: function() {
......@@ -523,7 +545,6 @@ Viewport.prototype = {
},
/**
* @private
* Compute the zoom level for fit-to-page, fit-to-width or fit-to-height.
*
* At least one of {fitWidth, fitHeight} must be true.
......@@ -534,6 +555,7 @@ Viewport.prototype = {
* @param {boolean} fitHeight a bool indicating whether the whole height of
* the page needs to be in the viewport.
* @return {number} the internal zoom to set
* @private
*/
computeFittingZoom_: function(pageDimensions, fitWidth, fitHeight) {
assert(
......@@ -586,7 +608,6 @@ Viewport.prototype = {
},
/**
* @private
* Compute a zoom level given the dimensions to fit and the actual numbers
* in those dimensions.
*
......@@ -599,6 +620,7 @@ Viewport.prototype = {
* @param {number} pageWidth the width of the page in px.
* @param {number} pageHeight the height of the page in px.
* @return {number} the internal zoom to set
* @private
*/
computeFittingZoomGivenDimensions_: function(
fitWidth, fitHeight, windowWidth, windowHeight, pageWidth, pageHeight) {
......@@ -638,11 +660,12 @@ Viewport.prototype = {
},
/**
* @private
* Zoom the viewport so that the page height consumes the entire viewport.
*
* @param {boolean} scrollToTopOfPage Set to true if the viewport should be
* scrolled to the top of the current page. Set to false if the viewport
* should remain at the current scroll position.
* @private
*/
fitToHeightInternal_: function(scrollToTopOfPage) {
this.mightZoom_(() => {
......@@ -672,11 +695,12 @@ Viewport.prototype = {
},
/**
* @private
* Zoom the viewport so that a page consumes as much as possible of the it.
*
* @param {boolean} scrollToTopOfPage Set to true if the viewport should be
* scrolled to the top of the current page. Set to false if the viewport
* should remain at the current scroll position.
* @private
*/
fitToPageInternal_: function(scrollToTopOfPage) {
this.mightZoom_(() => {
......@@ -739,6 +763,7 @@ Viewport.prototype = {
/**
* Pinch zoom event handler.
*
* @param {!Object} e The pinch event.
*/
pinchZoom: function(e) {
......@@ -811,6 +836,7 @@ Viewport.prototype = {
/**
* Go to the given page index.
*
* @param {number} page the index of the page to go to. zero-based.
*/
goToPage: function(page) {
......@@ -819,6 +845,7 @@ Viewport.prototype = {
/**
* Go to the given y position in the given page index.
*
* @param {number} page the index of the page to go to. zero-based.
* @param {number} x the x position in the page to go to.
* @param {number} y the y position in the page to go to.
......@@ -848,6 +875,7 @@ Viewport.prototype = {
/**
* Set the dimensions of the document.
*
* @param {Object} documentDimensions the dimensions of the document
*/
setDocumentDimensions: function(documentDimensions) {
......@@ -869,6 +897,7 @@ Viewport.prototype = {
/**
* Get the coordinates of the page contents (excluding the page shadow)
* relative to the screen.
*
* @param {number} page the index of the page to get the rect for.
* @return {Object} a rect representing the page in screen coordinates.
*/
......
chrome/browser/resources/pdf/viewport_scroller.js
View file @ d5de6d0d
......@@ -5,15 +5,17 @@
'use strict';
/**
* @private
* The period of time in milliseconds to wait between updating the viewport
* position by the scroll velocity.
*
* @private
*/
ViewportScroller.DRAG_TIMER_INTERVAL_MS_ = 100;
/**
* @private
* The maximum drag scroll distance per DRAG_TIMER_INTERVAL in pixels.
*
* @private
*/
ViewportScroller.MAX_DRAG_SCROLL_DISTANCE_ = 100;
......@@ -21,6 +23,7 @@ ViewportScroller.MAX_DRAG_SCROLL_DISTANCE_ = 100;
* Creates a new ViewportScroller.
* A ViewportScroller scrolls the page in response to drag selection with the
* mouse.
*
* @param {Object} viewport The viewport info of the page.
* @param {Object} plugin The PDF plugin element.
* @param {Object} window The window containing the viewer.
......@@ -38,9 +41,10 @@ function ViewportScroller(viewport, plugin, window) {
ViewportScroller.prototype = {
/**
* @private
* Start scrolling the page by |scrollVelocity_| every
* |DRAG_TIMER_INTERVAL_MS_|.
*
* @private
*/
startDragScrollTimer_: function() {
if (this.timerId_ === null) {
......@@ -52,8 +56,9 @@ ViewportScroller.prototype = {
},
/**
* @private
* Stops the drag scroll timer if it is active.
*
* @private
*/
stopDragScrollTimer_: function() {
if (this.timerId_ !== null) {
......@@ -64,8 +69,9 @@ ViewportScroller.prototype = {
},
/**
* @private
* Scrolls the viewport by the current scroll velocity.
*
* @private
*/
dragScrollPage_: function() {
var position = this.viewport_.position;
......@@ -79,11 +85,12 @@ ViewportScroller.prototype = {
},
/**
* @private
* Calculate the velocity to scroll while dragging using the distance of the
* cursor outside the viewport.
*
* @param {Object} event The mousemove event.
* @return {Object} Object with x and y direction scroll velocity.
* @private
*/
calculateVelocity_: function(event) {
var x =
......@@ -102,10 +109,11 @@ ViewportScroller.prototype = {
},
/**
* @private
* Handles mousemove events. It updates the scroll velocity and starts and
* stops timer based on scroll velocity.
*
* @param {Object} event The mousemove event.
* @private
*/
onMousemove_: function(event) {
this.scrollVelocity_ = this.calculateVelocity_(event);
......@@ -118,6 +126,7 @@ ViewportScroller.prototype = {
/**
* Sets whether to scroll the viewport when the mouse is outside the
* viewport.
*
* @param {boolean} isSelecting Represents selection status.
*/
setEnableScrolling: function(isSelecting) {
......
chrome/browser/resources/pdf/zoom_manager.js
View file @ d5de6d0d
......@@ -11,7 +11,6 @@
*/
class ZoomManager {
/**
* Constructs a ZoomManager.
* @param {!Viewport} viewport A Viewport for which to manage zoom.
* @param {number} initialZoom The initial browser zoom level.
*/
......@@ -25,6 +24,7 @@ class ZoomManager {
/**
* Creates the appropriate kind of zoom manager given the zoom behavior.
*
* @param {BrowserApi.ZoomBehavior} zoomBehavior How to manage zoom.
* @param {!Viewport} viewport A Viewport for which to manage zoom.
* @param {Function} setBrowserZoomFunction A function that sets the browser
......@@ -45,6 +45,7 @@ class ZoomManager {
/**
* Invoked when a browser-initiated zoom-level change occurs.
*
* @param {number} newZoom the zoom level to zoom to.
*/
onBrowserZoomChange(newZoom) {}
......@@ -57,6 +58,7 @@ class ZoomManager {
/**
* Combines the internal pdf zoom and the browser zoom to
* produce the total zoom level for the viewer.
*
* @param {number} internalZoom the zoom level internal to the viewer.
* @return {number} the total zoom level.
*/
......@@ -67,6 +69,7 @@ class ZoomManager {
/**
* Given a zoom level, return the internal zoom level needed to
* produce that zoom level.
*
* @param {number} totalZoom the total zoom level.
* @return {number} the zoom level internal to the viewer.
*/
......@@ -76,6 +79,7 @@ class ZoomManager {
/**
* Returns whether two numbers are approximately equal.
*
* @param {number} a The first number.
* @param {number} b The second number.
*/
......@@ -100,6 +104,7 @@ class InactiveZoomManager extends ZoomManager {}
class ActiveZoomManager extends ZoomManager {
/**
* Constructs a ActiveZoomManager.
*
* @param {!Viewport} viewport A Viewport for which to manage zoom.
* @param {Function} setBrowserZoomFunction A function that sets the browser
* zoom to the provided value.
......@@ -113,6 +118,7 @@ class ActiveZoomManager extends ZoomManager {
/**
* Invoked when a browser-initiated zoom-level change occurs.
*
* @param {number} newZoom the zoom level to zoom to.
*/
onBrowserZoomChange(newZoom) {
......@@ -159,6 +165,7 @@ class ActiveZoomManager extends ZoomManager {
/**
* Combines the internal pdf zoom and the browser zoom to
* produce the total zoom level for the viewer.
*
* @param {number} internalZoom the zoom level internal to the viewer.
* @return {number} the total zoom level.
*/
......@@ -171,6 +178,7 @@ class ActiveZoomManager extends ZoomManager {
/**
* Given a zoom level, return the internal zoom level needed to
* produce that zoom level.
*
* @param {number} totalZoom the total zoom level.
* @return {number} the zoom level internal to the viewer.
*/
......@@ -188,6 +196,7 @@ class ActiveZoomManager extends ZoomManager {
class EmbeddedZoomManager extends ZoomManager {
/**
* Invoked when a browser-initiated zoom-level change occurs.
*
* @param {number} newZoom the new browser zoom level.
*/
onBrowserZoomChange(newZoom) {
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment