1# Overview
2
3The RDM tool uses several forms of tab and browser swapping to integrate the
4tool UI cleanly into the browser UI.  The high level steps of this process are
5documented at `/devtools/docs/responsive-design-mode.md`.
6
7This document contains a random assortment of low level notes about the steps
8the browser goes through when swapping browsers between tabs.
9
10# Connections between Browsers and Tabs
11
12Link between tab and browser (`gBrowser._linkBrowserToTab`):
13
14```
15aTab.linkedBrowser = browser;
16gBrowser._tabForBrowser.set(browser, aTab);
17```
18
19# Swapping Browsers between Tabs
20
21## Legend
22
23* (R): remote browsers only
24* (!R): non-remote browsers only
25
26## Functions Called
27
28When you call `gBrowser.swapBrowsersAndCloseOther` to move tab content from a
29browser in one tab to a browser in another tab, here are all the code paths
30involved:
31
32* `gBrowser.swapBrowsersAndCloseOther`
33  * `gBrowser._beginRemoveTab`
34    * `gBrowser.tabContainer.updateVisibility`
35    * Emit `TabClose`
36    * `browser.webProgress.removeProgressListener`
37    * `filter.removeProgressListener`
38    * `listener.destroy`
39  * `gBrowser._swapBrowserDocShells`
40    * `ourBrowser.webProgress.removeProgressListener`
41    * `filter.removeProgressListener`
42    * `gBrowser._swapRegisteredOpenURIs`
43    * `ourBrowser.swapDocShells(aOtherBrowser)`
44      * Emit `SwapDocShells`
45      * `PopupNotifications._swapBrowserNotifications`
46      * `browser.detachFormFill` (!R)
47      * `browser.swapFrameLoaders`
48      * `browser.attachFormFill` (!R)
49      * `browser._remoteWebNavigationImpl.swapBrowser(browser)` (R)
50      * `browser._remoteWebProgressManager.swapBrowser(browser)` (R)
51      * `browser._remoteFinder.swapBrowser(browser)` (R)
52      * Emit `EndSwapDocShells`
53    * `gBrowser.mTabProgressListener`
54    * `filter.addProgressListener`
55    * `ourBrowser.webProgress.addProgressListener`
56  * `gBrowser._endRemoveTab`
57    * `gBrowser.tabContainer._fillTrailingGap`
58    * `gBrowser._blurTab`
59    * `gBrowser._tabFilters.delete`
60    * `gBrowser._tabListeners.delete`
61    * `gBrowser._outerWindowIDBrowserMap.delete`
62    * `browser.destroy`
63    * `gBrowser.tabContainer.removeChild`
64    * `gBrowser.tabContainer.adjustTabstrip`
65    * `gBrowser.tabContainer._setPositionalAttributes`
66    * `browser.parentNode.removeChild(browser)`
67    * `gBrowser._tabForBrowser.delete`
68    * `gBrowser.mPanelContainer.removeChild`
69  * `gBrowser.setTabTitle` / `gBrowser.setTabTitleLoading`
70    * `browser.currentURI.spec`
71    * `gBrowser._tabAttrModified`
72    * `gBrowser.updateTitlebar`
73  * `gBrowser.updateCurrentBrowser`
74    * `browser.docShellIsActive` (!R)
75    * `gBrowser.showTab`
76    * `gBrowser._appendStatusPanel`
77    * `gBrowser._callProgressListeners` with `onLocationChange`
78    * `gBrowser._callProgressListeners` with `onSecurityChange`
79    * `gBrowser._callProgressListeners` with `onUpdateCurrentBrowser`
80    * `gBrowser._recordTabAccess`
81    * `gBrowser.updateTitlebar`
82    * `gBrowser._callProgressListeners` with `onStateChange`
83    * `gBrowser._setCloseKeyState`
84    * Emit `TabSelect`
85    * `gBrowser._tabAttrModified`
86    * `browser.getInPermitUnload`
87    * `gBrowser.tabContainer._setPositionalAttributes`
88  * `gBrowser._tabAttrModified`
89
90## Browser State
91
92When calling `gBrowser.swapBrowsersAndCloseOther`, the browser is not actually
93moved from one tab to the other.  Instead, various properties _on_ each of the
94browsers are swapped.
95
96Browser attributes `gBrowser.swapBrowsersAndCloseOther` transfers between
97browsers:
98
99* `usercontextid`
100
101Tab attributes `gBrowser.swapBrowsersAndCloseOther` transfers between tabs:
102
103* `usercontextid`
104* `muted`
105* `soundplaying`
106* `busy`
107
108Browser properties `gBrowser.swapBrowsersAndCloseOther` transfers between
109browsers:
110
111* `mIconURL`
112* `getFindBar(aOurTab)._findField.value`
113
114Browser properties `gBrowser._swapBrowserDocShells` transfers between browsers:
115
116* `outerWindowID` in `gBrowser._outerWindowIDBrowserMap`
117* `_outerWindowID` on the browser (R)
118* `docShellIsActive`
119* `permanentKey`
120* `registeredOpenURI`
121
122Browser properties `browser.swapDocShells` transfers between browsers:
123
124* `_docShell`
125* `_webBrowserFind`
126* `_contentWindow`
127* `_webNavigation`
128* `_remoteWebNavigation` (R)
129* `_remoteWebNavigationImpl` (R)
130* `_remoteWebProgressManager` (R)
131* `_remoteWebProgress` (R)
132* `_remoteFinder` (R)
133* `_securityUI` (R)
134* `_documentURI` (R)
135* `_documentContentType` (R)
136* `_contentTitle` (R)
137* `_characterSet` (R)
138* `_contentPrincipal` (R)
139* `_imageDocument` (R)
140* `_fullZoom` (R)
141* `_textZoom` (R)
142* `_isSyntheticDocument` (R)
143* `_innerWindowID` (R)
144* `_manifestURI` (R)
145
146`browser.swapFrameLoaders` swaps the actual page content.
147