Mini Window API Reference

class MiniWindowManagerClass()

Cross-window manager for Mini Windows. Owns the registry of open mini windows, the per-origin lifecycle observers, and SessionStore integration.

MiniWindowManagerClass._miniwindows

type: Set.<object>

Live MiniWindow instances.

MiniWindowManagerClass._miniWindowForBrowser(browser)

Arguments:

• browser (XULBrowserElement)

Returns:

object|undefined – the mini window hosting browser, if any. Keyed on the mini window’s <browser> element.

MiniWindowManagerClass.maybeMoveOldestMiniWindow(originWin)

Moves the oldest popped tab back to the origin window.

Arguments:

• originWin (Window)

Returns:

boolean – true if a popped tab was moved home.

MiniWindowManagerClass.popRegion(tab, cropInfo, entryPoint)

Pop a cropped region of tab into a new mini window.

Arguments:

• tab (MozTabbrowserTab) – the tab to move.

• cropInfo (object) – see MiniWindow.

• entryPoint (string) – where the pop was initiated.

Returns:

Promise.<(object|null)> – the MiniWindow, or null.

MiniWindowManagerClass.popTab(tab, entryPoint)

Pop the whole tab into a new always-on-top window.

Arguments:

• tab (MozTabbrowserTab) – the tab to move.

• entryPoint (string) – where the pop was initiated.

Returns:

Promise.<(object|null)> – the MiniWindow, or null.

MiniWindowManagerClass.popTabs(tabs, entryPoint)

Pop each of tabs, into their own full-tab mini window. Splitview tabs are moved into their own mini windows.

Arguments:

• tabs (Array.<MozTabbrowserTab>)

• entryPoint (string) – where the pop was initiated.

MiniWindowManagerClass.tabsToPop(tabs)

The tabs popTabs would move. If tabs are in a splitview state, separates them in the results.

Arguments:

• tabs (Array.<MozTabbrowserTab>)

Returns:

Array.<MozTabbrowserTab>

MiniWindowManagerClass.windowsToAvoid(win)

The always-on-top windows win should try not to cover.

Arguments:

• win (Window) – the window doing the avoiding; never included.

Returns:

Array.<Window>

class MiniWindow(manager, originWin, sourceTab, cropInfo=null)

One always-on-top popup hosting a live moved tab. The tab keeps its browsing context across the move, so the page is never reloaded, and teardown adopts it back into its origin window rather than discarding it.

Arguments:

• manager (object) – The MiniWindowManager singleton.

• originWin (ChromeWindow) – The tab’s source window.

• sourceTab (MozTabbrowserTab) – The tab to move.

• cropInfo (object|null) – The page region to frame, in content CSS px. Carries left/top/width/height plus the viewport size and fullZoom it was captured against; see MiniWindowUtils. Null makes a full-tab mini window.

MiniWindow.MiniWindow

MiniWindow.browser

The browser for the current Mini Window, or undefined before the popup window exists.

MiniWindow.isCropped

Whether this Mini Window frames a cropped region rather than the whole tab.

MiniWindow.state

The current state of the Mini Window, one of MiniWindowState.

MiniWindow.tab

The tab that this Mini Window holds, or undefined before the popup window exists.

MiniWindow.close(method="close_button")

Close the popup and discard the tab. We need to return the tab to its originWin so that sessionStore can remember it in the originWin’s history.

This must only be invoked when the popped window is still alive - the unload path should use #onUnload instead. Use returnToOriginWin to return the tab instead of closing it.

Returns as soon as the state is CLOSING, without waiting: the tab state flush, the adopt back into originWin and the teardown all happen afterwards, so the popup is still open when this returns.

Arguments:

• method (string) – how this was reached; see metrics.yaml.

MiniWindow.handleEvent(event)

Arguments:

• event (Event) – A WINDOW_EVENTS event from the popup window.

MiniWindow.hideToolbarOnScrollDown()

Scrolling down dismisses the toolbar at once.

MiniWindow.open()

Moves the source tab out into a new always-on-top popup and frames the crop in it.

Returns:

Promise.<(DOMWindow|null)> – Resolves once the popup has finished delayed startup, been framed and reached state ACTIVE. Resolves with null without waiting if the tab could not be moved out, in which case the Mini Window is left CLOSED.

MiniWindow.returnToOriginWin(focus, method="put_tab_back")

Put the tab back into its original window and tear the mini window down.

Arguments:

• focus (boolean) – whether to focus the tab in originWin.

• method (string) – how this was reached; see metrics.yaml.

MiniWindow.revealToolbar(hideDelay)

Show the toolbar and (re)start the countdown that hides it again.

Arguments:

• hideDelay (number) – how long the toolbar stays up.

MiniWindow.uninit()

Remove any event listeners and close the window (if it already hasn’t), then unregister from the manager. Safe to call more than once.

class MiniWindowUtils()

Static sizing/framing helpers for a Mini Window.

static MiniWindowUtils.computeWindowRect(originWin, cropInfo)

Where and how large to open the mini window for cropInfo. Reads the screen originWin is on; computeWindowRectForScreen does the math.

Arguments:

• originWin (Window) – the window the tab is popped out of.

• cropInfo (object) – region to frame; uses width/height, content CSS px.

Returns:

Object

static MiniWindowUtils.computeWindowRectForScreen(cropInfo, screenInfo)

Size the miniwindow to the crop’s own dimensions (so the region shows at native size, scale 1), clamped down to the available screen when the crop is larger, preserving aspect ratio, then corner it in the available rect.

Three pixel spaces meet here::

desktop px availRect screen CSS px cropInfo, returned width/height originWin CSS returned left/top (what openWindow features take)

A scale is desktopPx per cssPx, i.e. defaultCSSScaleFactor over contentsScaleFactor: 2/2 = 1 on a Retina Mac, 1.5/1 at 150% on Windows. originWin may be on a different monitor than the mini window, so its scale is tracked separately from the target screen’s.

Arguments:

• cropInfo (object) – region to frame; uses width/height, content CSS px.

• screenInfo (object)

• screenInfo.availRect (object) – the target screen’s available rect, {left, top, width, height} in desktop px.

• screenInfo.screenCssToDesktopScale (number) – the target screen’s scale.

• screenInfo.originCssToDesktopScale (number) – originWin’s scale.

• screenInfo.isRTL (boolean) – whether the app locale is RTL.

Returns:

Object

static MiniWindowUtils.fullTabSize()

Size for a full-tab mini window, which frames no crop and so has no natural size of its own.

Returns:

Object – in CSS px.

static MiniWindowUtils.repositionToAvoid(win, avoidWins)

Where to move an already-open mini window so it clears avoidWins.

Arguments:

• win (Window) – the mini window to place, already open.

• avoidWins (Array.<Window>) – windows it should not cover (excluding win).

Returns:

Object|null – the new top-left in win’s CSS px for moveTo, or null if it already clears everything.

static MiniWindowUtils.resolveOverlapConflicts(rect, obstacles, screenRect)

Move rect off anything in obstacles it would cover. Every rect is in desktop px.

First tries the screen’s own four corners, preferring the one nearest to where the window wanted to sit. If they’re all taken, falls back to sitting flush against an obstacle’s edge:

   +---+
   | 2 |          1  left:   flush to the obstacle's left
+---+---+---+     2  top:    flush above it
| 1 | X | 3 |     3  right:  flush to its right
+---+---+---+     4  bottom: flush below it
   | 4 |          X  the obstacle
   +---+

Candidates off screenRect or onto another obstacle are dropped.

Arguments:

• rect (object) – {left, top, width, height} the window wants.

• obstacles (Array.<object>) – rects to avoid, same shape as rect.

• screenRect (object) – candidates have to fit inside this.

Returns:

Object – where to put it.

static MiniWindowUtils.windowRectDesktopPx(win)

A window’s outer rect in desktop px.

Arguments:

• win (Window)

Returns:

Object

class MiniWindowParent()

Parent actor for Mini Window.

class MiniWindowChild()

Content-side actor for Mini Window.