Custom items on touch bar

Parallels desktop 13 supports the touch bar on latest MacBook Pro. The displayed items are customizable for each single program, but the available functions are predefined, see attached screenshot.

1. It would be useful, if the user could define own keystroke combinations (e.g. Ctrl + Alt + F) for quick access on the touch bar.
2. This includes customizable labels. I would appreciate, if I could read "Refresh" or an icon on the touch bar instead of "F5".

Current limited options:

 

In Parallels Desktop 13 it is possible to define custom touchbar for Windows applications via special XML files. However, this functionality is intended for advanced users.
Which application(s) do you have in mind?

 

Dealing with XML files should not be a insoluble problem. Is there any documentation?

Most interesting for me is integration with ecoDMS client, a document management database. It uses many shortcuts and having some of them directly in the touch bar would really simplify using the program.

 

Where do you find that app in the image?! Tried everything

 

Note: this is a preliminary documentation intended for advanced users. Please backup / snapshot your VM just in case.
Your feedback is appreciated.
Touch Bar advanced customisation
How do I customise touchbar

• To override default touchbar (for non-Windows VM), you must create new XML description and save it as defaultTouchBar.xml file inside of .pvm bundle of your virtual machine
• To override touchbar for specific Windows application, you must create new XML description and save it is under program_executable_name.exe.xml (or program_appid.xml for UWP app) in %LOCALAPPDATA%\Parallels\CustomTouchBars folder. A logoff may be required.

XML schema example
Here is slightly over-the-top example of touchbar for notepad which demoes most available features.

<TouchBar id='notepad' defaultItemIdentifiers='nav,tools,templates,NSTouchBarItemIdentifierCharacterPicker,quit'>
<SegmentedControl id='nav' separated='true' trackingMode='momentary'>
<Segment id='home' keyCode='home' image='NSTouchBarGoBackTemplate'/>
<Segment id='end' keyCode='end' image='NSTouchBarGoForwardTemplate'/>
</SegmentedControl>
<ScrollView id='tools'>
<Button id='open' keyCode='ctrl+o' title='Open' width='70'/>
<Button id='save' keyCode='ctrl+s' title='Save' width='70'/>
<Button id='find' keyCode='ctrl+f' title='Find' width='70'/>
<Button id='replace' keyCode='ctrl+h' title='Replace' width='70'/>
</ScrollView>
<Popover id='templates' title='Templates'>
<PopoverTouchBar id='press' defaultItemIdentifiers='time,NSTouchBarItemIdentifierFlexibleSpace,hello,world,what,is,love'>
<Button id='time' keyCode='F5' backColor='1484d5' title='Insert time' image='NSTouchBarHistoryTemplate' width='120'/>
<Button id='hello' keyCode='h,e,l,l,o' title='Hello' width='80'/>
<Button id='world' keyCode='w,o,r,l,d' title='World' width='80'/>
<Button id='what' keyCode='w,h,a,t' title='What' width='80'/>
<Button id='is' keyCode='i,s' title='is' width='80'/>
<Button id='love' keyCode='l,o,v,e' title='love' width='80'/>
</PopoverTouchBar>
<PressAndHoldTouchBar id='pressandhold' defaultItemIdentifiers='omw,omg,asap'>
<Button id='omg' keyCode='shift+o,m,w,shift+1' title='Omw!'/>
<Button id='omw' keyCode='shift+o,m,g,shift+1' title='Omg!'/>
<Button id='asap' keyCode='shift+a,s,a,p,shift+1' title='Asap!'/>
</PressAndHoldTouchBar>
</Popover>
<Button id='quit' keyCode='alt+f4' title='Quit' image='NSTouchBarStopTemplate'/>
</TouchBar>
General rules

• There must be root TouchBar element
• There must be an "id" attribute defined for each element which must have unique value
• Attribute names are case-sensitive

Touchbar element
Root element of an XML document. Defines elements which are displayed on touch-bar.

• defaultItemIdentifiers - Mandatory. Array of comma-delimited identifiers of buttons included. Identifiers must point to the element of document with the same "id" attribute or special identifiers:

NSTouchBarItemIdentifierCharacterPicker - smiles button
NSTouchBarItemIdentifierFlexibleSpace - flexible space
NSTouchBarItemIdentifierFixedSpaceSmall - small fixed space
NSTouchBarItemIdentifierFixedSpaceLarge - large fixed space​

• escapeKeyReplacementItemIdentifier - Optional. Identifier of a button which replaces Escape key.
• principalItemIdentifier - Optional. Identifier of an item which is displayed in center of touch-bar.

Button element
Element which specifies separate button.

• keyCode - Mandatory. Specifies shortcut sequence.
• title - Optional. Specifies text on button.
• image - Optional. Specifies image on button. See "Images".
• backColor - Optional. Specifies background color of button in RRGGBB format.
• textColor - Optional. Specifies text color of button in RRGGBB format.
• width - Optional. Specifies width of a button, in points.

SegmentedControl element
Container element which specifies buttons displayed together. Should contain children Segment subelements.

• trackingMode - Mandatory. Must specify "momentary".
• separated - Optional. Should specify "true" if buttons are displayed separately

Segment subelement

• keyCode - Mandatory. Specifies shortcut sequence.
• title - Optional. Specifies text on button.
• image - Optional. Specifies image on button. See "Images".
• width - Optional. Specifies width of a button, in points.

Popover element
Element which specifies button which expands into separate touch-bar. May show different touch-bar for press-and-hold scenario.
Should contain PopoverTouchBar and may contain PressAndHoldTouchBar subelements which has schema identical to Touchbar elements.

• title - Optional. Specifies text on button.
• image - Optional. Specifies image on button. See "Images".

ScrollView element
Container element which shows buttons in scrollable area. Should contain child Button elements with defined width.

Group element
Container element for other elements. May contain any child elements.

Images
You may use standard images as per Apple documentation: (drop "ImageName" from name)

https://developer.apple.com/library...s.html#//apple_ref/doc/uid/20000957-CH107-SW1

You may define custom images in xml file, but that won't look pretty: specify

image="base64:2x:template:<base64 encoded image data>"
where "2x:" and "template:" are optional, meaning 2x downscale and template image treating accordingly.

Key codes
Characters: a-z
Numbers: 0-9
F keys: f1-f24
Other keys: \/*=[]`.,comma,semicolon,ins,del,home,end,pgup,pgdown,prtSc,break,ctrl,alt,shift,win,fn,scroll_lock,esc,left,right,up,down,space,tab,minus,np_minus,plus,enter,
www_back,www_forward,www_search,www_home,www_stop,www_refresh,www_favorites,app_mail,app_calculator,app_computer,menu.

 

%LOCALAPPDATA%\Parallels\CustomTouchBars folder does not exist? Should i create it manually?

Also i have deleted the windows mail app from my VM, and now parallels just shows a unusable file icon in the touchbar. Can i remove this?
I actually think i saw images of more apps being available, but i see no way to add new apps to the touch bar?

 

You should create it manually.

Touchbar for desktop shows apps pinned to guest Taskbar. You may pin/unpin items there to show them on touchbar.

 

Hello, thank you very much for this documentation, the customisable touchbar is amazing feature!
I've encountered a little problem.
I have this button defined in my XML: <Button id='se80' keyCode='/,n,s,e,8,0,enter' title='SE80' width='50'/>
It works fine with EN keyboard layout (sends sequence "/nse80"), but as I switch to CS (czech) keyboard layout, this button starts to send "-nseáé". I would appreciate if it was possible to define characters using hex codes or better if it's possible not to translate keys according to the keyboard layout selected, but keep exactly what is written in the definition xml.

 

I have customized the touchbar for some of my apps using the XML schema described above. This has really improved my productivity using Windows Apps. Thanks for including this capability!
One thing I have tried but failed to accomplish is a button with "touch and hold" capability as described from Apple (https://developer.apple.com/macos/human-interface-guidelines/touch-bar/touch-bar-architecture/):

"Touch and hold. Initiates a secondary action on a control, such as a button. For example, whereas tapping the Flag button when Mail is active adds a flag to a message, touching and holding the Flag button displays a modal overlay that lets you choose a flag color."​

The closest option available is the Popover element with the PressAndHoldTouchBar subelement. The problem is I do not want the popover feature. It would be nice if a PressAndHoldTouchBar subelement could be associated with a Button element.

Is there a way to do this?

 

There isn't an a way, I guess because button with touch-and-hold is not discoverable. We will consider such functionality in the future.