UrlbarChildController Reference

class UrlbarChildController(options)

The in-process face of the address bar controller. Lives next to the <moz-urlbar> custom element and forwards work that has to happen in the parent process to a paired UrlbarParentController via the UrlbarChild/UrlbarParent JSWindowActor pair. The actor owns the per-instance bookkeeping (instance id, lifetime); this wrapper just holds the controller it hands back.

The wrapper abstracts the transport: on the direct path (chrome <moz-urlbar>) the actor pair hands back the real UrlbarParentController and calls happen synchronously, while on the message path (a content-process <moz-urlbar>, or chrome with the pref) it gets a proxy implementing the same surface. Callers (UrlbarInput, UrlbarView) don’t distinguish them.

Arguments:
UrlbarChildController.UrlbarChildController
UrlbarChildController.input

type: unknown

UrlbarChildController.parentController

type: UrlbarParentController

The paired parent controller – the real UrlbarParentController on the direct path, or the UrlbarParentControllerProxy on the message path.

UrlbarChildController.userSelectionBehavior

type: “arrow”|”tab”|”none”

The selection behavior that the user has used to select a result. The setter ignores a change to “arrow” once “tab” has been recorded, since we want to know that tab was used first.

UrlbarChildController.discardResults(queryContext)

Takes the running query away from the listeners, reporting it to them as cancelled: nothing more of it reaches them, results or end. The input calls this when it takes the query over after the first result – entering search mode and restarting it – since the results are about to be replaced. The query keeps running until the restart cancels it, which over the message path takes a round trip.

Arguments:

  • queryContext (UrlbarQueryContext) – The context of the query being discarded.

UrlbarChildController.focusBrowser(browserId)
Arguments:

  • browserId (number) – The browser the load resolved to, as returned by loadURL.

Returns:

Promise.<{focused: boolean}>|Object – Whether the browser was focused.

UrlbarChildController.getEngineIconURL(engineId)
UrlbarChildController.handleKeyNavigation(event, executeAction=true)

Receives keyboard events from the input and handles those that should navigate within the view or pick the currently selected item.

Arguments:

  • event (KeyboardEvent) – The DOM KeyboardEvent.

  • executeAction (boolean) – Whether the event should actually execute the associated action, or just be managed (at a preventDefault() level). This is used when the event will be deferred by the event bufferer, but preventDefault() and friends should still happen synchronously.

UrlbarChildController.initEngineStore()
UrlbarChildController.isCanonizeKeyboardEvent(event)

Returns whether the passed-in event represents a canonization request.

Arguments:

  • event (Event) – An Event to examine.

Returns:

boolean – Whether the event is a KeyboardEvent that triggers canonization.

UrlbarChildController.keyEventMovesCaret(event)

Checks whether a keyboard event that would normally open the view should instead be handled natively by the input field. On certain platforms, the up and down keys can be used to move the caret, in which case we only want to open the view if the caret is at the start or end of the input.

Arguments:

  • event (KeyboardEvent) – The DOM KeyboardEvent.

Returns:

boolean – Returns true if the event should move the caret instead of opening the view.

UrlbarChildController.markEngineAsUsed(engineId)
UrlbarChildController.maybeInitEngineStore()
UrlbarChildController.notify(notification, ...params)

Hands a notification to the listeners, dropping the results and the end of a query they have moved on from.

Arguments:

  • notification (string) – The notification, one of UrlbarShared.NOTIFICATIONS.

  • params (any) – The notification’s arguments. The query lifecycle ones take the query context.

UrlbarChildController.notifyFromWire(notification, ...params)

Takes a notification off the wire, building the query context in this realm before anything reads it.

Arguments:

  • notification (string) – The notification, one of UrlbarShared.NOTIFICATIONS.

  • params (any) – The notification’s arguments, the query context in its wire form.

UrlbarChildController.openSERP(engineId, searchTerms, where, inBackground, browserId)
UrlbarChildController.openSearchForm(engineId, where, inBackground, browserId)
UrlbarChildController.startQuery(queryContext)

Starts a query and returns the parent controller’s promise so callers (the input’s lastQueryContextPromise, which tests await) can track completion.

A query that would run before the engine store is populated is held back until it is. Results are produced by the providers in the parent, which use the search service directly, so a query dispatched before the store is ready can deliver results to a UI that has no engines to look up. Holding the query back is what keeps every result-handling path downstream of a populated store.

Arguments:

  • queryContext (UrlbarQueryContext)

Returns:

Promise.<UrlbarQueryContext> – Resolves with the finished context, or with the untouched one if the query was cancelled or superseded while waiting for the engine store.

UrlbarChildController.updateEngineStore(args)
UrlbarChildController.whereToOpen(event)

Determines where a URL/page picked in <moz-urlbar> should be opened. Only the call to BrowserUtils.whereToOpenLink (a system module the content-web scope can’t import) goes through UrlbarContentUtils; everything else, including the guarded empty-tab read, is content-safe and stays here.

Arguments:

  • event (KeyboardEvent|MouseEvent) – The event that triggered the opening.

Returns:

"current"|"tabshifted"|"tab"|"save"|"window" –