Firefox For Mac Touch Bar

| 15-09-2021
[RAND-1-100] Comments

The Touch Bar is actually a pencil-thin screen above the keyboard of the new MacBook Pro that changes based on what you're doing. Here's what you need to know. Here's what you need to know. When a video is playing, Safari lets you control playback and scrub through the video from the touch bar. When a text field is focused, you get the usual word suggestions. When focus is in the URL bar, you get icons of the URL bar dropdown items. In Firefox, the bar is always empty. Whether it was social media or the tech press it seems like all I'd been hearing about the Touch Bar for years was negativity. Do people mostly like.

Show the function keys

Press and hold the Fn (Function) key on your keyboard to see F1 through F12 in the Touch Bar.

You can also make the function keys appear automatically when you use specific apps:

  1. Choose Apple menu  > System Preferences, then click Keyboard.
  2. Click Shortcuts at the top of the window, then select Function Keys from the list on the left.
  3. Click the add button (+), then select an app and click Add. For each app that you add, the function keys will automatically appear in the Touch Bar whenever you're using that app.

Or use the onscreen keyboard

As an alternative to showing the function keys in the Touch Bar, you can use the function keys in the onscreen keyboard.

  1. Choose Apple menu  > System Preferences, then click Keyboard and complete one of these steps:
    • If you're using macOS Big Sur, select 'Show Input menu in menu bar' in the Input Sources pane.
    • If you're using macOS Catalina or earlier, select ”Show Keyboard and emoji viewers in menu bar” in the Keyboard pane.
  2. Click the viewer icon in the menu bar, then choose Show Keyboard Viewer.
  3. Click the Fn key in the onscreen keyboard to make it show all function keys.
Settings

Show the function keys when using Microsoft Windows

Bar

Press and hold the Fn (Function) key on your keyboard to see F1 through F12 in the Touch Bar.

You can also make the function keys appear continuously in the Touch Bar:

  1. From the notification area on the right side of the Windows taskbar, click the up arrow to show hidden icons.
  2. Click the Boot Camp icon , then choose Boot Camp Control Panel from the menu.
  3. If you're asked whether to allow this app to make changes, click Yes.
  4. Click the Keyboard tab.
  5. Select ”Use all F1, F2, etc. keys as standard function keys”.

Or use the onscreen keyboard

As an alternative to showing the function keys in the Touch Bar, you can use the onscreen keyboard:

  1. From the Windows menu, select Windows Ease of Access.
  2. Click On-Screen Keyboard.
  3. Click the Fn key in the onscreen keyboard to make it show all function keys.

Learn more about the onscreen keyboard in Windows.

The Touch Bar is a hardware component on some MacBook Pros released from 2016.It is a display above the keyboard that allows more flexible types ofinput than is otherwise possible with a normal keyboard. Apple offers Touch BarAPIs so developers can extend the Touch Bar to display inputs specific to theirapplication. Firefox consumes these APIs to offer a customizable row of inputsin the Touch Bar.

In Apple’s documentation, the term “the Touch Bar” refers to the hardware.The term “a Touch Bar” refers not to the hardware but to a collection of inputsshown on the Touch Bar. This means that there can be multiple “Touch Bars” thatswitch out as the user switches contexts. The same naming convention is used inthis document.

In this document and in the code, the word “input” is used to refer toan interactive element in the Touch Bar. It is often interchangeable with“button”, but “input” can also refer to any element displayed in the Touch Bar.

The Touch Bar should never offer functionality unavailable to Firefox userswithout the Touch Bar. Most macOS Firefox users do not have the Touch Bar andsome choose to disable it. Apple’s own Human Interface Guidelines (HIG)forbids this kind of Touch Bar functionality. Please read the HIG for moredesign considerations before you plan on implementing a new Touch Bar feature.

If you have questions about the Touch Bar that are not answered in thisdocument, feel free to reach out to Harry Twyford (:harry on Slack).He wrote this document and Firefox’s initial Touch Bar implementation.

Table of Contents

Firefox’s Touch Bar implementation is equal parts JavaScript and Cocoa(Objective-C++). The JavaScript code lives in browser/components/touchbarand the Cocoa code lives in widget/cocoa, mostly in nsTouchBar.mm. TheCocoa code is a consumer of Apple’s Touch Bar APIs and defines what types ofTouch Bar inputs are available to its own consumers. The JS code inbrowser/components/touchbar provides services to nsTouchBar.mm anddefines what inputs the user actually sees in the Touch Bar. There is two-waycommunication between the JS and the Cocoa: the Cocoa code asks the JS whatinputs it should display, and the JS asks the Cocoa code to update those inputswhen needed.

browser/components/touchbar/MacTouchBar.js defines what specific inputs areavailable to the user, what icon they will have, what action they will perform,and so on. Inputs are defined in the gBuiltInInputs object in that file.When creating a new object in gBuiltInInputs, the available properties aredocumented in the JSDoc for TouchBarInput:

Clarification on some of these properties is warranted.

  • title is the key to a Fluent translation defined in browser/locales/<LOCALE>/browser/touchbar/touchbar.ftl.

  • type must be a value from the kInputTypes enum in MacTouchBar.js.For example, kInputTypes.BUTTON. More information on input types followsbelow.

  • callback points to a JavaScript function. Any chrome-level JavaScript canbe executed. execCommand is a convenience method in MacTouchBar.jsthat takes a XUL command as a string and executes that command. For instance,one input sets callback to execCommand('Browser:Back').

  • children is an array of objects with the same properties as members ofgBuiltInInputs. When used with an input of typekInputTypes.SCROLLVIEW, children can only contain inputs of typekInputTypes.BUTTON. When used with an input of typekInputTypes.POPOVER, any input type except another kInputTypes.POPOVERcan be used.

Button

A simple button. If image is not specified, the buttons displays the textlabel from title. If both image and title are specified, only theimage is shown. The action specified in callback is executed when thebutton is pressed.

Caution

Even if the title will not be shown in the Touch Bar, you must stilldefine a title property.

Main Button

Similar to a button, but displayed at double the width. A main buttondisplays both the string in title and the icon in image. Only onemain button should be shown in the Touch Bar at any time, although this isnot enforced.

Label

A non-interactive text label. This input takes only the attributes titleand type.

Popover

Initially represented in the Touch Bar as a button, a popover will display anentirely different set of inputs when pressed. These different inputs shouldbe defined in the children property of the parent. Popovers can also beshown and hidden programmatically, by calling

where the second argument is a reference to a popover TouchBarInput andthe third argument is whether the popover should be shown or hidden.

Scroll View

A Scroll View is a scrolling list of buttons. The buttons should be definedin the Scroll View’s children array.

Note

In Firefox, a list of search shortcuts appears in the Touch Bar when theaddress bar is focused. This is an example of a ScrollView contained withina popover. The popover is opened programmatically withgTouchBarUpdater.showPopover when the address bar is focused and it ishidden when the address bar is blurred.

Some examples of gBuiltInInputs objects follow.

A simple button

A button is defined with a title, icon, type, and a callback. The callbacksimply calls the XUL command to go back.

The search popover

This is the input that occupies the Touch Bar when the address bar is focused.

At the top level, a Popover is defined. This allows a collection of childrento be shown in a separate Touch Bar. The Popover has two children: a Label,and a Scroll View. The Scroll View displays five similar buttons that call ahelper method to insert search shortcut symbols into the address bar.

Adding a new input is easy: just add a new object to gBuiltInInputs. Thiswill make the input available in the Touch Bar customization window (accessiblefrom the Firefox menu bar item).

If you want to to add your new input to the default set, add its identifierhere, where type is a value from kAllowedInputTypes in thatfile and key is the value you set for title in gBuiltInInputs.You should request approval from UX before changing the default set of inputs.

If you are interested in adding new features to Firefox’s implementation of theTouch Bar API, read on!

Firefox implements Apple’s Touch Bar API in its Widget: Cocoa code with annsTouchBar class. nsTouchBar interfaces between Apple’s Touch Bar APIand the TouchBarHelper JavaScript API.

The best resource to understand the Touch Bar API is Apple’sofficial documentation. This documentation will cover how Firefox implementsthese APIs and how one might extend nsTouchBar to enable new Touch Barfeatures.

Every new Firefox window initializes nsTouchBar (link). The functionmakeTouchBar is looked for automatically on every new instance of anNSWindow*. If makeTouchBar is defined, that window will own a newinstance of nsTouchBar.

Firefox For Mac Touch Bars

At the time of this writing, every window initializes nsTouchBar with adefault set of inputs. In the future, Firefox windows other than the mainbrowser window (such as the Library window or DevTools) may initializensTouchBar with a different set of inputs.

nsTouchBar has two different initialization methods: init andinitWithInputs. The former is a convenience method for the latter, callinginitWithInputs with a nil argument. When that happens, a Touch Bar iscreated containing a default set of inputs. initWithInputs can also take anNSArray<TouchBarInput*>*. In that case, a non-customizable Touch Bar will beinitialized with only those inputs available.

The architecture of the Touch Bar is based largely around an NSString*wrapper class called NSTouchBarItemIdentifier. Every input in the Touch Barhas a unique NSTouchBarItemIdentifier. They are structured in reverse-URIformat like so:

com.mozilla.firefox.touchbar.[TYPE].[KEY]

[TYPE] is a string indicating the type of the input, e.g. “button”. If aninput is a child of another input, the parent’s type is prepended to the child’stype, e.g. “scrubber.button” indicates a button contained in a scrubber.

[KEY] is the title attribute defined for that input on the JS side.

If you need to generate an identifier, use the convenience method[TouchBarInputnativeIdentifierWithType:withKey:].

Caution

Do not create a new input that would have the same identifier as any otherinput. All identifiers must be unique.

Warning

NSTouchBarItemIdentifieris used in one other place: settingcustomizationIdentifier. Do not ever change this string. If it is changed,any customizations users have made to the layout of their Touch Bar in Firefoxwill be erased.

Each identifier is tied to a TouchBarInput. TouchBarInput is a classthat holds the properties specified for each input in gBuiltInInputs.nsTouchBar uses them to create instances of NSTouchBarItemwhich are the actual objects used by Apple’s Touch Bar API and displayed in theTouch Bar. It is important to understand the difference betweenTouchBarInput and NSTouchBarItem!

Firefox For Mac Touch Bar

Creating a Touch Bar and its TouchBarInputs flows as follows:

Firefox Mac Touch Bar

  1. [nsTouchBarinit] is called from [NSWindowmakeTouchBar].

  2. init populates two NSArrays: customizationAllowedItemIdentifiers anddefaultItemIdentifiers. It also initializes a TouchBarInput objectfor every element in the union of the two arrays and stores them inNSMutableDictionary<NSTouchBarItemIdentifier,TouchBarInput*>*mappedLayoutItems.

  3. touchBar:makeItemForIdentifier: is called for every element in the unionof the two arrays of identifiers. This method retrieves the TouchBarInputfor the given identifier and uses it to initialize a NSTouchBarItem.touchBar:makeItemForIdentifier: reads the type attribute from theTouchBarInput to determine what NSTouchBarItem subclass should beinitialized. Our Touch Bar code currently supports NSCustomTouchBarItem(buttons, main buttons); NSPopoverTouchBarItem (popovers);NSTextField (labels); and NSScrollView (ScrollViews).

  4. Once the NSTouchBarItem is initialized, its properties are populated withan assortment of “update” methods. These include updateButton,updateMainButton, updateLabel, updatePopover, andupdateScrollView.

  5. Since the localization of TouchBarInput titles happens asynchronously inJavaScript code, the l10n callback executes[nsTouchBarUpdaterupdateTouchBarInputs:]. This method reads theidentifier of the input(s) that need to be updated and calls their respective“update” methods. This method is most often used to update title afterl10n is complete. It can also be used to update any property of aTouchBarInput; for instance, one might wish to change colorwhen a specific event occurs in the browser.