Theme meta issue

[mikebeaton]

There are some already approved and designed (with feedback from theme designers) changes coming up to how themes work. Details below, along with some additional suggestions for changes which may or may not be approved - input and discussion welcome have now been approved, in somewhat changed and cleaner form.

TL/DR:

Approved:

• Change theme directory structure
• Modern (aka Acidanthera/GoldenGate) to become new default theme
• Allow per-OS and per-theme icons for OS other than macOS and Windows (currently, you can set a per-OS icon, but not in a way which changes per theme)
• Allow per-theme per-Tool and per-Entry icons (at the moment: you can set a one-off icon for a given tool binary, but not in a way which changes per-theme; you cannot set different icons if you use the binary more than once with different arguments; it also only works when volume icons are enabled, whereas you might normally want volume icons off when using a theme)
• Update auto-detection of shell and nvram icons to not be dependent on the entry names
• Output failed searches for other icon images to debug log, to make it easier for users to see where they could have put icons
• Swap OC Shutdown and Restart buttons to match Big Sur order

Undecided

• There is no concept of defining the properties of the theme. While the user can set the attributes, attributes are rather his preferences, and for the theme we would like to define its properties to define its visual style. I suggest to introduce an optional manifest.plist file that will contain:
  • Text colour in RGB or RGBA format independent from UITheme proto. This might want multiple colours.
  • Background colour independent from UITheme proto.
  • Font name (currently Font, but can become anything).
• Font size is currently fixed, but now that we support text scrolling we can honestly be less restrictive and allow bigger sizes to an extent.
• Basic movement animation when moving the selector left and right, particularly when reaching user-invisible area (hidden by the arrows).
• CD/DVD/BD icons.

---

Exhaustive detail:

1) Change theme directory structure (was approved and designed prior to this issue)

Currently themes are identified by file prefixes in a flat directory structure, e.g. Selector.icns, OldSelector.icns, ModernSelector.icns.

This is to be replaced by a [vendor]/[theme] directory structure, with the existing Acidanthera themes directories named for corresponding macOS codenames:

Acidanthera/Chardonnay/Selector.icns, etc.  [was Old]
Acidanthera/Syrah/Selector.icns, etc.       [was Default]
Acidanthera/GoldenGate/Selector.icns, etc.  [was Modern]

PickerVariant = Auto, Default, Old and Modern will be still be supported as special cases, so users will just have to update OcBinaryData as normal when this change is made.

In future, all other PickerVariant values should be [vendor]/[theme], but can also be just [theme] in case there is no vendor subfolder. Unlike now, there must be at least one subfolder.

2) Hardcoded tool names

The hardcoded tool names "Reset NVRAM" (which is usually added as a boot entry via Misc/Security/AllowNvramReset, but can also be added manually in the Misc/Tools section) and "UEFI Shell" (which must be added manually in Misc/Tools, as per the sample plist files) are mapped to theme icons ResetNVRAM.icns and Shell.icns respectively. (Actually these special entry names also trigger the appropriate audio prompts in boot picker audio assist.)

• It seems strange that these are mapped by entry name - e.g. what if I would like to rename my shell entry to "Open Shell"? Could they be mapped at least by binary file name OpenShell.efi and CleanNvram.efi?
• Note that these icons are per-theme, they are already part of the main theme directory

3) Custom tool icons

Tool custom icons can be put next to the tool. E.g. for Tools/OpenShell.efi we can put in place Tools/OpenShell.efi.icns.

• The fact that this exists is somewhat non-obvious, especially as this image location is not output in the log file if searched for and not found (perhaps at least this should be changed, so that this image search is logged?)
• This only works when PickerAttributes OC_ATTR_USE_VOLUME_ICON is set. To me this was also non-obvious, although the idea is that these files are logically equivalent to .VolumeIcon.icns files.
• These icons are not per-theme (since there is just one of them, they are not part of the main theme directory).
• Also, you cannot have more than one icon for the same tool; e.g. ResetSystem.efi previously could (in fact, still can) be used to provide Shutdown and Restart boot entries, but it is not possible to set a different icon for each of these. Although this case is now more or less replaced by the new Shutdown and Restart buttons in both pickers, it seems reasonable in principle to want to apply different icons to the same tool, when called with different arguments in different boot entries.

4) Custom OS icons

Apple macOS and Windows support per-theme icons Apple.icns, ExtApple.icns, Windows.icns, ExtWindows.icns.

• In addition to the above, some themes ship with themed icons for other OSes (e.g. several different icons for the several different flavours of Linux), but to use these a user has to manually copy one of them in as .VolumeIcons.icns in the appropriate location near to the relevant OS boot file
• So, apart from Apple and Windows, there is no way to set up a per-theme OS icon

5) Resolution-specific backgrounds

Background.icns is searched for and used as a background.

• Various themes ship with more than one background at different resolutions; the appropriate sized image required for the user's system must be manually copied into the theme directory

I'm mentioning this because one of the current requirements for themes (see below) is that the average normal user should not need to edit their theme directory, and can (e.g.) easily just pull updates from the theme's repo. However, this is one example where that already does not work.

6) Supported theme icons without implementations in the default themes

Some supported theme icons (e.g. ResetNVRAM.icns, Apple.icns, ExtApple.icns, ExtWindows.icns) are supported as part of custom themes, but have no implementation in the shipped themes.

• This may be a non-issue, mentioning it separately because it is somewhat relevant to 4 above and 2 below.

THEME REQUIREMENTS

1. The average user should not be expected to edit or alter the theme directory, for example so that they can easily just pull updates from the theme's repo
2. Important: not showing the variant Ext... icon (e.g. ExtHardDrive.icns instead of HardDrive.icns) when the OS is on an external drive is a security risk. (As noted in Configuration.pdf, using .VolumeIcon.icns violates this, but this is an exception and not desirable behaviour.)
3. Theme providers should NOT be expected to support every possible OS and every possible tool; not even from /Tools, never mind from elsewhere

SUGGESTION (updated and cleaner version of this is now approved)
Despite the above Theme Requirements, I feel it would be desirable to allow per-theme custom icons for tools and OSes beyond the ones in the fixed set of support.

In order to allow for per-theme custom icons for Tools, I would propose adding a new string CustomIcon key to each Misc/Tools and Misc/Entries entry. The value of this could be, e.g., Shell to select the standard Shell.icns from the theme directory, or SysRestart to select the custom SysRestart.icns. (Note: searching for icons this way could work whether or not OC_ATTR_USE_VOLUME_ICON is set, which I believe is desirable.)

In order to allow for custom icons for other OSes, I would propose adding a new Misc/CustomIcons section, e.g.:

<Misc>
    ...
    <CustomIcons>
        <dict>
            <key>PciRoot(0x0)/Pci(0x1F,0x2)/Sata(0x0,0x0,0x0)/HD(6,GPT,00000000-0000-0000-0000-000000000000,0x00000000,0x0000)/\EFI\ubuntu\grubx64.efi</key>
            <string>Ubuntu</string>
        </dict>
    </CustomIcons>
    ...
</Misc>

This assigns the per-theme custom icon Ubuntu.icns to the specified boot entry (if this icon exists in the current theme, or default OS icon otherwise). This only makes sense if at least several theme providers provide e.g. Ubuntu icons. I believe they already do.

In terms of priority, I would suggest that these custom icons are searched for first (when specified), and if not found (or not specified) all existing locations are searched next as now.

Probably both the above suggestions only make sense if we accept that users do do some manual editing and placing of their themes files, but I believe they already do, both for different sized backgrounds and to allow for (e.g.) different Unix flavour OS icons.

NB I am not suggesting that any such additional icon names become required or recommended defaults. One theme provider might provide custom Ubuntu.icns, SysShutDown.icns and SysRestart.icns, another one might provide equivalent custom icons but call them something else. The aim is only to allow theme providers to provide additional icons and to allow users a way to select them.

(EDIT: As part of the approved version of these changes, there will be a centrally maintained list of approved additional icon names, to make it easier for theme designers; all custom icons will always have a defined fallback to a (required) standard OC theme icon, so using custom icons won't break anything if you switch themes to a theme without a custom icon which you were using - e.g. Ubuntu would fallback to the default OS icon.)

[mikebeaton]

Linked to:
#1586
#1042
#1042 (comment)

[perez987]

Excellent text!!! I liked it a lot. As usual.

[mikebeaton]

Excellent text!!! I liked it a lot. As usual.

M'ok... guess a like would have been fine then, but thanks....

Have updated the issue with a much more readable TL/DR. :-)

[mikebeaton]

Here's a short story in pictures, to try to explain why I think per-theme per-OS and per-Tool icons would be good (all captured from a legacy retina MBP, where I'm using OC in order to install and run Big Sur):

1. My Apple bootpicker:

Note use of .VolumeIcon.icns files.

2. OC in Modern theme:

All looks nice, picking up the Volume Icons (after a little documented playing around with their locations). Because I have named my shell entry 'Open Shell' it is not picking up the shell icon. Because there is no shipped ResetNVRAM.icns it is not picking up an icon for that.

3. Experiments in theming (credits https://github.com/blackosx/BsxOc1_):

Hmm, looks nice! But note that I manually copied the theme icon Resources/Image/Shell.icns to Tools/OpenShell.efi.icns to get that to be used; also, I'd kind of like to use themed OS icons; so next I'll try turning off OC_ATTR_USE_VOLUME_ICON...

4. Theme with OC_ATTR_USE_VOLUME_ICON off:

Okay, pretty close - although, dammit, the shell icon has gone! (Only way to get it back is to name the entry to "UEFI Shell".) I'd also like to use one of the Linux custom icons that ship with the theme for my Ubuntu partition... that should be easy...?

5. Successful theme custom icon for non-standard set (i.e. not macOS and not Windows, which support theming) OS:

Looks great again! But no, it wasn't easy... I had to re-enable Volume Icons, then I had to delete (or rename) .VolumeIconcs.icns for all the entries which I needed to pick up standard set theme icons (in the above: my first boot entry, Big Sur and Windows), and I also had to manually copy the Unbuntu.icns shipped with the theme into the correct .VolumeIcons.icns location for the OS.

6. Result on other themes (this is back to OC Modern again):

Note that the specifically themed OS and shell icons are being used on all themes - there is no way round that. Obviously the fact that I had to delete most volume icons to get a custom OS icon into my theme is having an effect too.

Thinking about some of the slight difficulties in the above (something like!) my suggested custom icon changes (OP) would allow:

• Remove the link between Volume Icons and theming - could theme with or without volume icons enabled, because proposed custom icons settings would take precedence over volume icons
• Make it possible to set custom icons for tools other then "Reset NVRAM" and "UEFI Shell" even if Volume Icons are off; this is currently impossible
• Make it possible to use a different custom icon for the same tool called with different arguments in different entries (as previously for ResetSystem.efi when used for Shutdown and for Restart) (this is currently impossible)
• Make it possible to have per-theme icons for OSes other then macOS and Windows, e.g. Ubuntu as above; for example, I could have a couple of themes set up, and switch between them (with the OS icon changing correctly) when all I change is the theme name in my config.plist; yes, this involves a little bit of manual intervention in the theme files (e.g. the user choosing to use the custom icon name Ubuntu.icns, and then putting those icons in the correct place) rather than there being only one standard name for these (additional, custom) files
• Make it possible to have per-theme icons for Tools and Entries; same comments as previous

In the scenario above, after getting to step 4 I would have just had to add one entry in Misc/CustomIcons (for Ubuntu) and to set the new CustomIcon value for my "Open Shell" Misc/Tools entry (I might also have wanted to set a custom icon for my "NVRAM BootHelper" tool) - and, because these are custom icons, I do ofc have to make sure the right icon files are in place, from wherever I want to get them (but presumably from the theme provider) (EDIT: that step is actually not required, in cleaned, approved version of the changes 😊) - and I'd be done! No need to delete any volume icons, and no unwanted effect on any other themes at all.

[telepati]

I'm sorry, but even reading the article overwhelmed me. Everything seems very complicated. I think the given picture examples do not meet OC's understanding of simplicity and clean appearance. I think the current state of the icons is quite sufficient. My advice is; it will be creating a Theme folder and placing three different folders in it. Folder names should be as follows;

Old, Modern, Custom

If the default is to be Modern, it would be better to remove Modern and Auto from the PickerVariant and instead have the selections like this; PickerVariant = Default, Old, and Custom

If someone is going to use their own icons, it will be sufficient to drop all their icons into the Custom Folder and change them to PickerVariant = Custom.

[mikebeaton]

@telepati Thanks for your input. It might have been a mistake of mine to give extra details of the approved change and try to have my discussion of less clear changes that I'd like to make, all in the same issue. But I think the already agreed theme folder layout change isn't as complicated, nor as different from how themes currently work, as you think it is!

[perez987]

@telepati First, OpenCore doesn’t have simplicity as a must-have, al least not the more important. For me, to get hackintosh working as near as a real mac is the first target.
I like very much oc-binary icons, Modern theme, it looks as a real and modern mac picker. But browsing opencanopy icons and themes threads in InsanelyMac, it’s clear that there is a demand of picker customization. Here is where Mike's comments fit in, in the desire of quite a few users to customize the graphical interface.
Some ideas are easy to carry out (new themes folder structure) and some are not (custom icons for Linux, for example). But configuring OpenCore is in itself a relatively complex task. I don't think these changes to OpenCanopy add much more complexity.

[mikebeaton]

Just to update anyone following: something like what I have suggested, for themeable custom OS and Tool icons, has now been approved 🎉 - but made a bit less anarchic, and with more guidance for artists about filenames to use than what I proposed - and ofc with other improvements too! Details will follow.

The theme directory layout changes were designed and approved before this issue - not by me, and in consultation with theme designers - and also are (and always were) happening. 🙂

Btw, the directory layout changes will require changes to themes - specifically, at least adding one directory - but my other changes above will not require any new changes, they will allow (but not require) some more optional icons from theme designers, and some more ways to specify them, for users.

In order to avoid requiring artists to change themes without much notice, the plan is all these changes will be put live early in 0.7.0, not squeezed into the 0.6.9 release.

[blackosx]

Wow Mike!. You've given this a proper once-over and having your interest in this right now is great as while other changes to OpenCanopy are being looked at this may be the only window of opportunity to get these things at least considered.

OpenCanopy has come a long way since it's inception and is currently a slick UI thanks to the hard work of the developer(s). Maybe OpenCanopy is already close to becoming the intended vision that was set out to begin with (approved up-coming changes aside) but I also believe that your observations and suggestions could transform it from a slick UI with a working default installation to an incredible UI offering full customisation options for those whose wish to do that. I mean, with all the hard work gone in to get it to where it is, why not go the extra mile and make it better.

I understand changes take time and energy from the developers which can be hard to come by when we all have real lives and jobs etc. so I guess there is no immediate rush to implement everything at once (if decided upon). But having these things on the roadmap and slowly rolled out will result in a UI that's complete/done/finished without a need to re-visit it in six months time when more users discover OpenCore/OpenCanopy and attempt to customise it to suit their own system only to discover the same findings that you have highlighted above and post similar questions.

EDIT:
^^ Just seen your post above regarding the confirmation that your suggestions have been approved in some shape or form. Thank you guys :)