2063545 - Document gBrowser's progress listener infrastructure

Status: RESOLVED FIXED

(Firefox :: Tabbed Browser, task)

Description

[Dão Gottwald [:dao]]

browser/components/tabbrowser/docs/ covers what gBrowser is and how the async tab switcher works, but nothing covers the progress listener infrastructure. addProgressListener, addTabsProgressListener and their remove counterparts have no JSDoc either, and there is no general web progress documentation in-tree to defer to. Little of the behavior is guessable from the signatures.

Proposed, a new page under browser/components/tabbrowser/docs/ covering:

• The two listener flavors. Global listeners (addProgressListener) only receive notifications for the selected browser; tabs listeners (addTabsProgressListener) receive them for every tab, with the browser as an extra leading argument. Both take plain objects — dispatch is if (aMethod in p), each call is try/caught so one throwing listener doesn't inhibit the rest, and partial implementations are normal. Global listeners run before tabs listeners.
• TabProgressListener as the per-tab translator: it turns raw web progress into tab state (the busy attribute, progress, gBrowser._isBusy) and records the tab's last stateFlags, status, message and totalProgress.
• What a tab switch replays. updateCurrentBrowser re-emits onLocationChange, onSecurityChange and onContentBlockingEvent, then onUpdateCurrentBrowser with the recorded values, only when the recorded stateFlags is non-zero, plus a synthetic STATE_START | STATE_IS_NETWORK or its STATE_STOP mirror depending on the new tab's busy attribute and _isBusy.
• The sharp edges. The STATE_START/STATE_STOP that onUpdateCurrentBrowser synthesizes carries no STATE_IS_NETWORK, so consumers gated on that flag react to the separate synthetic notification instead; the recorded message is cleared at STATE_START and STATE_STOP, so a status delivered before a load's STATE_START is shown but not replayed on a tab switch; the record is written after the listeners run, so a listener reading it sees the previous value; and the initial about:blank is suppressed via _isForInitialAboutBlank, which substitutes onUpdateCurrentBrowser for onStateChange.
• How to wait for progress on a specific tab in a test.

Also add JSDoc to addProgressListener, removeProgressListener, addTabsProgressListener and removeTabsProgressListener, which feeds the eventual js:autoclass API reference.

Comment 1

[Dão Gottwald [:dao]]

Attachment: Bug 2063545 - Tidy the tabbrowser docs. r?sthompson!

The page told the <xul:tabbrowser> story four times over; it now says once that
the name survives in older code, and describes what gBrowser is today.

Comment 2

[Dão Gottwald [:dao]]

Attachment: Bug 2063545 - Document gBrowser's progress listener infrastructure. r?sthompson!

The replay on a tab switch reaches global listeners only, and a listener that
implements onRefreshAttempted without returning true cancels the refresh --
neither is guessable, and both are in the page.

Comment 3

[Pulsebot]

Pushed by [e-mail]:
https://github.com/mozilla-firefox/firefox/commit/dbdf04183a63
https://hg.mozilla.org/integration/autoland/rev/59ca3cf789cb
Tidy the tabbrowser docs. r=sthompson,tabbrowser-reviewers
https://github.com/mozilla-firefox/firefox/commit/d156ac96af44
https://hg.mozilla.org/integration/autoland/rev/473b8a090d9b
Document gBrowser's progress listener infrastructure. r=sthompson,tabbrowser-reviewers

Comment 4

[Cosmin Sabou [:CosminS]]

https://hg.mozilla.org/mozilla-central/rev/59ca3cf789cb
https://hg.mozilla.org/mozilla-central/rev/473b8a090d9b