User customization
A new feature of PyTouchBar is allowing the user to customize the TouchBar thanks to the customization palette. It will allow the user to add, remove and reorganize the TouchBar with the items you provide.
Since the customized TouchBar will be saved and loaded, this is a bit tricky to implement.
Giving the TouchBar a customization identifier will allow it to be saved and loaded on the next run.
The identifier is a string, formatted as "reverse-DNS style" according to the official Apple documentation (https://developer.apple.com/documentation/appkit/nstouchbar/2544730-customizationidentifier)
Example: com.madrau.PyTouchBar.anythingiwant
To do so, use the set_customization_identifier command:
PyTouchBar.set_customization_identifier("com.madrau.PyTouchBar.touchbar")
When you initialize a TouchBarItem, you provide some parameters ("text" for a Label, "action" for a Button, ...). For an item to be customizable, there are a few more parameters to specify.
- id (string) : Identifier for the item: same as for the TouchBar Identifier, the id is a string that will be used to save the position of the item. By default, they are generated randomly at each run, but if the item position should be saved, it should be a fixed value.
- customization_label (string) : The title of the item in the customization palette (not for Space items!).
- customization_mode (PyTouchBar.CustomizationMode) : How the item should be customizable by the user.
Items used in the example image were inited like this:
button = ptb.TouchBarItems.Button(title = "Button", action = action, id = "button", customization_label = "A button", customization_mode = ptb.CustomizationMode.allowed)
space = ptb.TouchBarItems.Space.Flexible(customization_mode = ptb.CustomizationMode.allowed)
slider = ptb.TouchBarItems.Slider(id = "slider", customization_label = "The slider", customization_mode = ptb.CustomizationMode.allowed)
stepper = ptb.TouchBarItems.Stepper(min = 0, max = 100, id = "stepper", customization_label = "The stepper", customization_mode = ptb.CustomizationMode.allowed)
There are two ways of calling the customization palette.
The first way is by calling the PyTouchBar.customize function.
PyTouchBar.customize()
The second way is to use the "Customize TouchBar" menu. This menu is not shown by default. To show it, when you set the TouchBar identifier, set the "menu" parameter to True.
PyTouchBar.set_customization_identifier("com.madrau.PyTouchBar.touchbar", menu = True)
By default, when you add items to the TouchBar with the set_touchbar function, the items will be placed in the "Default Set". If you want to create a TouchBar item that is not in the Default Set, but could be placed by the user, add them to the "define" parameter
ptb.set_touchbar([button, space, slider], define = [stepper])
With this code, the TouchBar will by default show the button, the space and the slider. But if the user opens the Customization Palette, he will also see the stepper, that he could add to the TouchBar.
The example image was done with the following code:
ptb.set_customization_identifier("com.madrau.PyTouchBar.anotherTest", menu = True)
button = ptb.TouchBarItems.Button(title = "Button", action = action, id = "button", customization_label = "A button", customization_mode = ptb.CustomizationMode.allowed)
space = ptb.TouchBarItems.Space.Flexible(customization_mode = ptb.CustomizationMode.allowed)
slider = ptb.TouchBarItems.Slider(id = "slider", customization_label = "The slider", customization_mode = ptb.CustomizationMode.allowed)
stepper = ptb.TouchBarItems.Stepper(min = 0, max = 100, id = "stepper", customization_label = "The stepper", customization_mode = ptb.CustomizationMode.allowed)
ptb.set_touchbar([button, space, slider], define = [stepper])