Custom items on touch bar

Discussion in 'Parallels Desktop for Mac Feature Suggestions' started by PascalO2, Aug 22, 2017.

  1. PascalO2

    PascalO2 Bit Poster

    Messages:
    2
    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:
    Touch-bar-items.png
     
    BelalS likes this.
  2. StanislavZ

    StanislavZ Parallels Developers

    Messages:
    96
    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?
     
  3. PascalO2

    PascalO2 Bit Poster

    Messages:
    2
    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. Shortcuts ecoDMS.png
     
  4. MortenL

    MortenL Bit Poster

    Messages:
    7
    Where do you find that app in the image?! Tried everything
     
  5. StanislavZ

    StanislavZ Parallels Developers

    Messages:
    96
    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.
     
  6. MortenL

    MortenL Bit Poster

    Messages:
    7
    %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?
     
  7. StanislavZ

    StanislavZ Parallels Developers

    Messages:
    96
    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.
     
  8. TomasH3

    TomasH3 Bit Poster

    Messages:
    1
    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.
     
  9. DerrickP2

    DerrickP2 Bit Poster

    Messages:
    1
    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?
     
  10. StanislavZ

    StanislavZ Parallels Developers

    Messages:
    96
    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.
     

Share This Page