UrlbarController Reference

class UrlbarController(options)

The address bar controller handles queries from the address bar, obtains results and returns them to the UI for display.

Listeners may be added to listen for the results. They may support the following methods which may be called when a query is run:

  • onQueryStarted(queryContext)

  • onQueryResults(queryContext)

  • onQueryCancelled(queryContext)

  • onQueryFinished(queryContext)

  • onQueryResultRemoved(index)

  • onViewOpen()

  • onViewClose()

Initialises the class. The manager may be overridden here, this is for test purposes.

Arguments
  • options (object()) – The initial options for UrlbarController.

  • options.input (UrlbarInput()) – The input this controller is operating with.

  • options.manager (object()) – Optional fake providers manager to override the built-in providers manager. Intended for use in unit tests only.

UrlbarController.addQueryListener(listener)

Adds a listener for query actions and results.

Arguments
  • listener (object()) – The listener to add.

Throws

TypeError() – Throws if the listener is not an object.

UrlbarController.cancelQuery()

Cancels an in-progress query. Note, queries may continue running if they can’t be cancelled.

UrlbarController.handleDeleteEntry(result)

Handles deletion of results from the last query context and the view. There are two kinds of results that can be deleted:

  • Results for which provider.blockResult() returns true

  • Results whose source is HISTORY are handled specially by this method and can always be removed

No other results can be deleted and this method will ignore them.

Arguments
  • result (UrlbarResult()) – The result to delete. If given, it must be present in the controller’s most recent query context. If not given, the currently selected result in the view is used.

Returns

boolean – Returns true if the result was deleted and false if not.

UrlbarController.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.

UrlbarController.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.

UrlbarController.notify(name, ...params)

Notifies listeners of results.

Arguments
  • name (string()) – Name of the notification.

  • params (object()) – Parameters to pass with the notification.

UrlbarController.receiveResults(queryContext)

Receives results from a query.

Arguments
  • queryContext (UrlbarQueryContext()) – The query details.

UrlbarController.recordSelectedResult(event, result)

Records details of the selected result in telemetry. We only record the selection behavior, type and index.

Arguments
  • event (Event()) – The event which triggered the result to be selected.

  • result (UrlbarResult()) – The selected result.

UrlbarController.removeQueryListener(listener)

Removes a query listener.

Arguments
  • listener (object()) – The listener to add.

UrlbarController.setView(view)

Hooks up the controller with a view.

Arguments
  • view (UrlbarView()) – The UrlbarView instance associated with this controller.

UrlbarController.speculativeConnect(result, context, reason)

Tries to initialize a speculative connection on a result. Speculative connections are only supported for a subset of all the results.

Arguments
  • result (UrlbarResult()) – Tthe result to speculative connect to.

  • context (UrlbarQueryContext()) – The queryContext

  • reason (string()) – Reason for the speculative connect request.

UrlbarController.startQuery(queryContext)

Takes a query context and starts the query based on the user input.

Arguments
  • queryContext (UrlbarQueryContext()) – The query details.

UrlbarController.userSelectionBehavior

Stores the selection behavior that the user has used to select a result.