UrlbarInput Reference

class UrlbarInput(options)

Implements the text input part of the address bar UI.

Arguments:

  • options (object) – The initial options for UrlbarInput.

  • options.textbox (object) – The container element.

UrlbarInput.UrlbarInput
UrlbarInput._autofillFirstResult(result)

Called by the controller when the first result of a new search is received. If it’s an autofill result, then it may need to be autofilled, subject to a few restrictions.

Arguments:

  • result (UrlbarResult) – The first result.

UrlbarInput._autofillValue(options)

Autofills a value into the input. The value will be autofilled regardless of the input’s current value.

Arguments:

  • options (object) – The options object.

  • options.value (string) – The value to autofill.

  • options.selectionStart (integer) – The new selectionStart.

  • options.selectionEnd (integer) – The new selectionEnd.

  • options.type ("origin"|"url"|"adaptive") – The autofill type, one of: “origin”, “url”, “adaptive”

  • options.adaptiveHistoryInput (string) – If the autofill type is “adaptive”, this is the matching input value from adaptive history.

  • options.untrimmedValue (string) – Untrimmed value including a protocol.

UrlbarInput._loadURL(url, event, openUILinkWhere, params, resultDetails, browser)

Loads the url in the appropriate place.

Arguments:

  • url (string) – The URL to open.

  • event (Event) – The event that triggered to load the url.

  • openUILinkWhere (string) – Where we expect the result to be opened.

  • params (object) – The parameters related to how and where the result will be opened. Further supported paramters are listed in utilityOverlay.js#openUILinkIn.

  • params.triggeringPrincipal (object) – The principal that the action was triggered from.

  • params.postData (nsIInputStream) – The POST data associated with a search submission.

  • params.allowInheritPrincipal (boolean) – Whether the principal can be inherited.

  • params.wasSchemelessInput (boolean) – Whether the search/URL term was without an explicit scheme.

  • resultDetails (object) – Details of the selected result, if any.

  • resultDetails.type (UrlbarUtils.RESULT_TYPE) – Details of the result type, if any.

  • resultDetails.searchTerm (string) – Search term of the result source, if any.

  • resultDetails.source (UrlbarUtils.RESULT_SOURCE) – Details of the result source, if any.

  • browser (object) – [optional] the browser to use for the load.

UrlbarInput._maybeAutofillPlaceholder(value)

Autofills the autofill placeholder string if appropriate, and determines whether autofill should be allowed for the new search started by an input event.

Arguments:

  • value (string) – The new search string.

Returns:

boolean – Whether autofill should be allowed in the new search.

UrlbarInput._maybeCanonizeURL(event, value)

If appropriate, this prefixes a search string with ‘www.’ and suffixes it with browser.fixup.alternate.suffix prior to navigating.

Arguments:

  • event (Event) – The event that triggered this query.

  • value (string) – The search string that should be canonized.

Returns:

string – Returns the canonized URL if available and null otherwise.

UrlbarInput._maybeSelectAll()
Determines if we should select all the text in the Urlbar based on the

Urlbar state, and whether the selection is empty.

UrlbarInput._notifyStartNavigation(result)

This notifies observers that the user has entered or selected something in the URL bar which will cause navigation.

We use the observer service, so that we don’t need to load extra facilities if they aren’t being used, e.g. WebNavigation.

Arguments:

  • result (UrlbarResult) – Details of the result that was selected, if any.

UrlbarInput._recordSearch(engine, event, searchActionDetails)

Records in telemetry that a search is being loaded, updates an incremental total number of searches in a pref, and informs ASRouter that a search has occurred via a trigger send

Arguments:

  • engine (nsISearchEngine) – The engine to generate the query for.

  • event (Event) – The event that triggered this query.

  • searchActionDetails (object) – The details associated with this search query.

  • searchActionDetails.isSuggestion (boolean) – True if this query was initiated from a suggestion from the search engine.

  • searchActionDetails.alias (boolean) – True if this query was initiated via a search alias.

  • searchActionDetails.isFormHistory (boolean) – True if this query was initiated from a form history result.

  • searchActionDetails.url (string) – The url this query was triggered with.

UrlbarInput._resetSearchState()

Resets some state so that searches from the user’s previous interaction with the input don’t interfere with searches from a new interaction.

UrlbarInput._searchModeForResult(result, entry="null")

Returns a search mode object if a result should enter search mode when selected.

Arguments:

  • result (UrlbarResult) – The result to check.

  • entry (string) – If provided, this will be recorded as the entry point into search mode. See setSearchMode() documentation for details.

Returns:

object – A search mode object. Null if search mode should not be entered. See setSearchMode documentation for details.

UrlbarInput._setValue(val, options)

Sets the input field value.

Arguments:

  • val (string) – The new value to set.

  • options (object) – Options for setting.

  • options.allowTrim (boolean) – Whether the value can be trimmed.

  • options.untrimmedValue (string) – Override for this._untrimmedValue.

  • options.valueIsTyped (boolean) – Override for this.valueIsTypede.

  • options.actionType (string) – Value for the actiontype attribute.

Returns:

string – The set value.

UrlbarInput._trimValue(val)

Shortens the given value, usually by removing http:// and trailing slashes.

Arguments:

  • val (string) – The string to be trimmed if it appears to be URI

Returns:

string – The trimmed string

UrlbarInput._updateSearchModeUI(searchMode)

Updates the UI so that search mode is either entered or exited.

Arguments:

  • searchMode (object) – See setSearchMode documentation. If null, then search mode is exited.

UrlbarInput._whereToOpen(event)

Determines where a URL/page should be opened.

Arguments:

  • event (Event) – the event triggering the opening.

Returns:

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

UrlbarInput.afterTabSwitchFocusChange()

When switching tabs quickly, TabSelect sometimes happens before _adjustFocusAfterTabSwitch and due to the focus still being on the old tab, we end up flickering the results pane briefly.

UrlbarInput.confirmSearchMode()

Confirms the current search mode.

UrlbarInput.formatValue()

Applies styling to the text in the urlbar input, depending on the text.

UrlbarInput.getSearchMode(browser, confirmedOnly=false)

Gets the search mode for a specific browser instance.

Arguments:

  • browser (Browser) – The search mode for this browser will be returned.

  • confirmedOnly (boolean) – Normally, if the browser has both preview and confirmed modes, preview mode will be returned since it takes precedence. If this argument is true, then only confirmed search mode will be returned, or null if search mode hasn’t been confirmed.

Returns:

object – A search mode object. See setSearchMode documentation. If the browser is not in search mode, then null is returned.

UrlbarInput.getSearchSource(event)

Get search source.

Arguments:

  • event (Event) – The event that triggered this query.

Returns:

string – The source name.

UrlbarInput.handleCommand(event=null)

Handles an event which might open text or a URL. If the event requires doing so, handleCommand forwards it to handleNavigation.

Arguments:

  • event (Event) – The event triggering the open.

UrlbarInput.handleEvent(event)

Passes DOM events to the _on_<event type> methods.

Arguments:

  • event (Event) – The event to handle.

UrlbarInput.handleNavigation(options)

Handles an event which would cause a URL or text to be opened.

Arguments:

  • options (object) – Options for the navigation.

  • options.event (Event) – The event triggering the open.

  • options.oneOffParams (HandleNavigationOneOffParams) – Optional. Pass if this navigation was triggered by a one-off. Practically speaking, UrlbarSearchOneOffs passes this when the user holds certain key modifiers while picking a one-off. In those cases, we do an immediate search using the one-off’s engine instead of entering search mode.

  • options.triggeringPrincipal (object) – The principal that the action was triggered from.

UrlbarInput.handoff(searchString, searchEngine, newtabSessionId)

Called by inputs that resemble search boxes, but actually hand input off to the Urlbar. We use these fake inputs on the new tab page and about:privatebrowsing.

Arguments:

  • searchString (string) – The search string to use.

  • searchEngine (nsISearchEngine) – Optional. If included and the right prefs are set, we will enter search mode when handing searchString from the fake input to the Urlbar.

  • newtabSessionId (string) – Optional. The id of the newtab session that handed off this search.

UrlbarInput.makeURIReadable(uri)

Converts an internal URI (e.g. a URI with a username or password) into one which we can expose to the user.

Arguments:

  • uri (nsIURI) – The URI to be converted

Returns:

nsIURI – The converted, exposable URI

UrlbarInput.maybeConfirmSearchModeFromResult(options)

Confirms search mode and starts a new search if appropriate for the given result. See also _searchModeForResult.

Arguments:

  • options (object) – Options object.

  • options.entry (string) – The search mode entry point. See setSearchMode documentation for details.

  • options.result (UrlbarResult) – The result to confirm. Defaults to the currently selected result.

  • options.checkValue (boolean) – If true, the trimmed input value must equal the result’s keyword in order to enter search mode.

  • options.startQuery (boolean) – If true, start a query after entering search mode. Defaults to true.

Returns:

boolean – True if we entered search mode and false if not.

UrlbarInput.onFirstResult(firstResult)

Invoked by the controller when the first result is received.

Arguments:

  • firstResult (UrlbarResult) – The first result received.

Returns:

boolean – True if this method canceled the query and started a new one. False otherwise.

UrlbarInput.pickElement(element, event)

Called when an element of the view is picked.

Arguments:

  • element (Element) – The element that was picked.

  • event (Event) – The event that picked the element.

UrlbarInput.pickResult(result, event, element=null, browser)

Called when a result is picked.

Arguments:

  • result (UrlbarResult) – The result that was picked.

  • event (Event) – The event that picked the result.

  • element (DOMElement) – the picked view element, if available.

  • browser (object) – The browser to use for the load.

UrlbarInput.removeHiddenFocus(forceSuppressFocusBorder=false)

Restore focus styles. This is used by Activity Stream and about:privatebrowsing for search hand-off.

Arguments:

  • forceSuppressFocusBorder (Browser) – Set true to suppress-focus-border attribute if this flag is true.

UrlbarInput.restoreSearchModeState()

Restores the current browser search mode from a previously stored state.

UrlbarInput.sanitizeTextFromClipboard(clipboardData)

Sanitize and process data retrieved from the clipboard

Arguments:

  • clipboardData (string) – The original data retrieved from the clipboard.

Returns:

string – The sanitized paste data, ready to use.

UrlbarInput.search(value, options)

Sets the input’s value, starts a search, and opens the view.

Arguments:

  • value (string) – The input’s value will be set to this value, and the search will use it as its query.

  • options (object) – Object options

  • options.searchEngine (nsISearchEngine) – Search engine to use when the search is using a known alias.

  • options.searchModeEntry (UrlbarUtils.SEARCH_MODE_ENTRY) – If provided, we will record this parameter as the search mode entry point in Telemetry. Consumers should provide this if they expect their call to enter search mode.

  • options.focus (boolean) – If true, the urlbar will be focused. If false, the focus will remain unchanged.

  • options.startQuery (boolean) – If true, start query to show urlbar result by fireing input event. If false, not fire the event.

UrlbarInput.searchModeShortcut()

Enters search mode with the default engine.

UrlbarInput.setHiddenFocus()

Focus without the focus styles. This is used by Activity Stream and about:privatebrowsing for search hand-off.

UrlbarInput.setPageProxyState(state, updatePopupNotifications)

Updates the user interface to indicate whether the URI in the address bar is different than the loaded page, because it’s being edited or because a search result is currently selected and is displayed in the location bar.

Arguments:

  • state (string) – The string “valid” indicates that the security indicators and other related user interface elments should be shown because the URI in the location bar matches the loaded page. The string “invalid” indicates that the URI in the location bar is different than the loaded page.

  • updatePopupNotifications (boolean) – Indicates whether we should update the PopupNotifications visibility due to this change, otherwise avoid doing so as it is being handled somewhere else.

UrlbarInput.setResultForCurrentValue(result)

The input keeps track of the result associated with the current input value. This result can be set by calling either setValueFromResult or this method. Use this method when you need to set the result without also setting the input value. This can be the case when either the selection is cleared and no other result becomes selected, or when the result is the heuristic and we don’t want to modify the value the user is typing.

Arguments:

  • result (UrlbarResult) – The result to associate with the current input value.

UrlbarInput.setSearchMode(searchMode, browser)

Sets search mode for a specific browser instance. If the given browser is selected, then this will also enter search mode.

Arguments:

  • searchMode (object) – A search mode object.

  • searchMode.engineName (string) – The name of the search engine to restrict to.

  • searchMode.source (UrlbarUtils.RESULT_SOURCE) – A result source to restrict to.

  • searchMode.entry (string) – How search mode was entered. This is recorded in event telemetry. One of the values in UrlbarUtils.SEARCH_MODE_ENTRY.

  • searchMode.isPreview (boolean) – If true, we will preview search mode. Search mode preview does not record telemetry and has slighly different UI behavior. The preview is exited in favor of full search mode when a query is executed. False should be passed if the caller needs to enter search mode but expects it will not be interacted with right away. Defaults to true.

  • browser (Browser) – The browser for which to set search mode.

UrlbarInput.setURI(uri=null, dueToTabSwitch=false, dueToSessionRestore=false, hideSearchTerms=false, isSameDocument=false)

Sets the URI to display in the location bar.

Arguments:

  • uri (nsIURI) – If this is unspecified, the current URI will be used.

  • dueToTabSwitch (boolean) – True if this is being called due to switching tabs and false otherwise.

  • dueToSessionRestore (boolean) – True if this is being called due to session restore and false otherwise.

  • hideSearchTerms (boolean) – True if userTypedValue should not be overidden by search terms and false otherwise.

  • isSameDocument (boolean) – True if the caller of setURI loaded a new document and false otherwise (e.g. the location change was from an anchor scroll or a pushState event).

UrlbarInput.setValueFromResult(options)

Called by the view when moving through results with the keyboard, and when picking a result. This sets the input value to the value of the result and invalidates the pageproxystate. It also sets the result that is associated with the current input value. If you need to set this result but don’t want to also set the input value, then use setResultForCurrentValue.

Arguments:

  • options (object) – Options.

  • options.result (UrlbarResult) – The result that was selected or picked, null if no result was selected.

  • options.event (Event) – The event that picked the result.

  • options.urlOverride (string) – Normally the URL is taken from result.payload.url, but if urlOverride is specified, it’s used instead.

Returns:

boolean – Whether the value has been canonized

UrlbarInput.startQuery(options)

Starts a query based on the current input value.

Arguments:

  • options (object) – Object options

  • options.allowAutofill (boolean) – Whether or not to allow providers to include autofill results.

  • options.autofillIgnoresSelection (boolean) – Normally we autofill only if the cursor is at the end of the string, if this is set we’ll autofill regardless of selection.

  • options.searchString (string) – The search string. If not given, the current input value is used. Otherwise, the current input value must start with this value.

  • options.resetSearchState (boolean) – If this is the first search of a user interaction with the input, set this to true (the default) so that search-related state from the previous interaction doesn’t interfere with the new interaction. Otherwise set it to false so that state is maintained during a single interaction. The intended use for this parameter is that it should be set to false when this method is called due to input events.

  • options.event (event) – The user-generated event that triggered the query, if any. If given, we will record engagement event telemetry for the query.

UrlbarInput.updateTextOverflow()

Invoked on overflow/underflow/scrollend events to update attributes related to the input text directionality. Overflow fade masks use these attributes to appear at the proper side of the urlbar.