Resize Button Icons

[huwshimi]

Hi, I'd love to be able to control the size of icons on buttons (prior art). In my case I have some actions that make more sense to be icons than text (e.g. play/stop, arrows) and the current fixed icon size is too large for the UI elements these are associated with e.g. alongside other text-only buttons.

At the risk of complicating things, for accessibility I think it's worth considering the topic of tooltips on buttons and the ability to have both an icon and text on a button (e.g. for semantically the same action throughout the app) even if these improvements aren't all implemented together.

In terms of widgets it seems like Button is the most obvious candidate for needing to control the icon size, though possibly DetailedList could display the icon at a different size and maybe also Commands when displayed in the toolbar.

What should the API look like? Is there anything else that needs to be taken into account?

[mhsmith]

What should the API look like?

Since you've already made a PR for this, we can use that API as a starting point for discussion. Can you post a summary of it here?

[freakboy3742]

Summarising on @huwshimi's behalf: the API they proposed was to modify the constructor of Icon to incorporate a size argument. The API on Button would then be exactly as it is right now (toga.Button(icon=myicon)), with the icon that has been constructed defining the size that is used.

That's definitely the "obvious" API - however, it misses an important detail about how Toga's representation of icons.

Toga's icons are inherently multi-sized. This reflects the underlying representation of icons on some platforms - both macOS .icns files and Windows .ico files are "multisized" - they can (and should, in best practice) wrap versions of the icon at different sizes, so that a GUI can choose an appropriate size for any given usage. For platforms that don't have a multi-size representation (e.g., Linux), Toga then emulates this by providing a range of recommended sizes of "single size" icons in a format like PNG.

This API is significant in most of the places that icons are used - button is the exception, not the rule. For example, on toolbars, each platform has a very specific size that they require for icons. If you specified an icon with a specific size, there's no guarantee that the icon would be usable by the toolbar (or, at the very least, the icon with a specific size would need to be internally rescaled to a different size... at which point, why did you specify a size?)

My take on this feature request is that the size request is a description of usage, not definition. That means you specify the size you want in the place you use the icon - so, the API on Button would look something like toga.Button(icon=myicon, icon_size=preferred_size) (with an error raised if you specify a icon_size without an icon).

We would then expose some "adaptive" size constants for icons. The 48px size used as a default on mobile is deliberate - it's the smallest size that can (subjectively) be reasonable targeted by a finger with any accuracy. The 32px size on desktop was chosen for a similar reason, but the size the mice can reasonably target is smaller. Providing adaptive enum constants like Toga.Icon.Size.NORMAL,SMALL, LARGE, XLARGE that map to platform-appropriate sizes (NORMAL = 32 on desktop, 48 on mobile) means we can provide some helpful breakpoints.

Those constants would ultimately be "just integers", so you could pass in an arbitrary number to the icon_size argument - but we can strongly encourage best practices with documentation.

Internally, there's also some work that can be done with icon. GTK does mostly the right thing - it maintains an internal cache of sizes so that once you've got a NxN image, you can always get that size; but other platforms (e.g., macOS, iOS) create new images on demand. The API for getting icons of different sizes is also inconsistent - native(), _as_size(), as_drawable. Ideally, we'd have a consistent internal API, and that API would cache images as they are created. However, even the GTK implementation could be optimised - a resized icon should be based on the icon that "price-is-right" sized - the closest but larger size of an icon that has been explicitly provided (so you don't resize a resized icon).

Regarding the two other semi-related feature requests:

1. "Icon and text" buttons are certainly possible; the main reason they haven't been implemented to date is that the actual implementation is moderately complicated, because on most platforms, it requires an additional layout implementation. There's also the issue of RTL languages to consider (i.e., in most western languages, if there's an icon and text, the icon should appear on the left of the text; but in Hebrew, Farsi, Arabic, etc, the icon should appear on the right of the text). There isn't much of an API discussion to be had here; it's mostly a case of relaxing the current error condition that prevents text and icon on a button.

2. Tooltips are a completely separate issue; as noted on Tooltip on Buttons #2598, I suspect the API would be something like `toga.Button(... hint="this is a tooltip hint"), which would then be applied as appropriate.

Both of these are standalone feature requests though - I'd strongly recommend not trying to roll them into a icon sizing PR.

[huwshimi]

Thanks, and sorry for the slow reply.

Toga's icons are inherently multi-sized.

I wasn't sure where to fit this comment below so I'll leave it here. One factor in choosing the right size is that DPI is device specific. I don't know that Toga should be concerned with choosing the right DPI image at runtime (though I guess it could be depending on support from the underlying platforms), but when it picks the size from a set of icons the pixel size on disk is not necessarily the size that it will be displayed at. Maybe it's enough to recommend naming files in such a way as to target your highest supported density (e.g. my_icon_32.png will be 96px to support 3x density).

We would then expose some "adaptive" size constants for icons. The 48px size used as a default on mobile is deliberate - it's the smallest size that can (subjectively) be reasonable targeted by a finger with any accuracy. The 32px size on desktop was chosen for a similar reason, but the size the mice can reasonably target is smaller.

One thing to note is that these sizes may not reflect the size of the icon or even the button (or whichever interactive element the icon is displayed on), but rather the hit area. For example the Material guidelines recommend a minimum hit area of 48x48dp for icon buttons, even though the visible area might be as small as 32db and the icon on that button would be only 20dp.

Providing adaptive enum constants like Toga.Icon.Size.NORMAL,SMALL, LARGE, XLARGE that map to platform-appropriate sizes (NORMAL = 32 on desktop, 48 on mobile) means we can provide some helpful breakpoints.

This does seem like a helpful approach, though NORMAL might be context/widget specific, not just platform specific. I've been taking a look at what sizes each platform recommends to see what these values could be. Maybe there are some better specs somewhere as I and haven't been able to find much helpful information.

	Baseline	Icon size		Button icon size
Android	24dp	20dp, 24dp, 40dp, and 48dp	https://m3.material.io/styles/icons/designing-icons#239784d7-9226-4970-aec6-abbf45fea9c1	20dp, 24dp, 32dp, 40dp	https://m3.material.io/components/icon-buttons/specs
GTK	16px?	16×16px, 32×32px, 64×64px and 128×128px	https://developer.gnome.org/hig/guidelines/ui-icons.html
Windows		16, 20, 24, 32, 40, 48 and 64 (epx?)	https://learn.microsoft.com/en-us/windows/apps/design/style/segoe-fluent-icons-font#using-the-icons
iOS		?
macOS		?

...There's also the issue of RTL languages to consider (i.e., in most western languages, if there's an icon and text, the icon should appear on the left of the text; but in Hebrew, Farsi, Arabic, etc, the icon should appear on the right of the text).

This is also true for the icon itself where the icon may need to be mirrored for these languages. Icon sets often provide RTL versions of these icons. Possibly Toga could support this by loading a version of the icon with an _rtl suffix if it exists. Some icon sets will even provide specific language variations if the icon contains alphanumeric characters.

[freakboy3742]

Thanks, and sorry for the slow reply.

Toga's icons are inherently multi-sized.

I wasn't sure where to fit this comment below so I'll leave it here. One factor in choosing the right size is that DPI is device specific. I don't know that Toga should be concerned with choosing the right DPI image at runtime (though I guess it could be depending on support from the underlying platforms), but when it picks the size from a set of icons the pixel size on disk is not necessarily the size that it will be displayed at. Maybe it's enough to recommend naming files in such a way as to target your highest supported density (e.g. my_icon_32.png will be 96px to support 3x density).

This is true; however, the platforms that care about this sort of thing have internal representations for this - for example, macOS differentiates between icon@2x.png that is 64 pixels wide, but a 2x pixel density, and icon.png that is 64 pixels wide (and implied 1x pixel density).

When a platform doesn't have explicit DPI handling, pixel size is a reasonable first approximation.

The core point, however, is that macOS and iOS (and to a lesser extent, Windows), have icon formats that include this sort of detail - so size isn't a property of the icon, it's a property of usage (and that usage can/should include display DPI).

We would then expose some "adaptive" size constants for icons. The 48px size used as a default on mobile is deliberate - it's the smallest size that can (subjectively) be reasonable targeted by a finger with any accuracy. The 32px size on desktop was chosen for a similar reason, but the size the mice can reasonably target is smaller.

One thing to note is that these sizes may not reflect the size of the icon or even the button (or whichever interactive element the icon is displayed on), but rather the hit area. For example the Material guidelines recommend a minimum hit area of 48x48dp for icon buttons, even though the visible area might be as small as 32db and the icon on that button would be only 20dp.

Sure - but Toga's sizes are specified in "CSS pixels", which already adapt for screen density. This is why the Windows and Android backends both have scale_in() and scale_out() mechanisms whenever pixels sizes are referenced.

Providing adaptive enum constants like Toga.Icon.Size.NORMAL,SMALL, LARGE, XLARGE that map to platform-appropriate sizes (NORMAL = 32 on desktop, 48 on mobile) means we can provide some helpful breakpoints.

This does seem like a helpful approach, though NORMAL might be context/widget specific, not just platform specific.

Certainly possible - although at present, the usage on a button is the only context where we're using icons where a size definition would be applicable.

From an API perspective, I don't know if this means the "Size" enum should be button-specific (reflecting that fact that a "small" button icon might not be the same size in some other usage). While this might be technically correct, it also strikes me as a little bit YAGNI...

...There's also the issue of RTL languages to consider (i.e., in most western languages, if there's an icon and text, the icon should appear on the left of the text; but in Hebrew, Farsi, Arabic, etc, the icon should appear on the right of the text).

This is also true for the icon itself where the icon may need to be mirrored for these languages. Icon sets often provide RTL versions of these icons. Possibly Toga could support this by loading a version of the icon with an _rtl suffix if it exists. Some icon sets will even provide specific language variations if the icon contains alphanumeric characters.

I don't think a simple _rtl suffix would be sufficient here. If you have an icon that contains alphanumerics, you don't just need it to be RTL - you need it to be in Arabic/Hebrew etc. At that point, you need to start considering ISO-language code suffixes... and that seems like the start of a much bigger set of i18n/l10n issues.

[huwshimi]

I wasn't sure where to fit this comment below so I'll leave it here. One factor in choosing the right size is that DPI is device specific. I don't know that Toga should be concerned with choosing the right DPI image at runtime (though I guess it could be depending on support from the underlying platforms), but when it picks the size from a set of icons the pixel size on disk is not necessarily the size that it will be displayed at. Maybe it's enough to recommend naming files in such a way as to target your highest supported density (e.g. my_icon_32.png will be 96px to support 3x density).

This is true; however, the platforms that care about this sort of thing have internal representations for this - for example, macOS differentiates between icon@2x.png that is 64 pixels wide, but a 2x pixel density, and icon.png that is 64 pixels wide (and implied 1x pixel density).

I guess I don't full have my head around how the underlying systems work for each platform. If it's enough to just provide a base image name e.g. Icon("resources/my_icon") then maybe it just becomes a documentation issues to guide people on how to add high DPI versions for each platform.

We would then expose some "adaptive" size constants for icons. The 48px size used as a default on mobile is deliberate - it's the smallest size that can (subjectively) be reasonable targeted by a finger with any accuracy. The 32px size on desktop was chosen for a similar reason, but the size the mice can reasonably target is smaller.

One thing to note is that these sizes may not reflect the size of the icon or even the button (or whichever interactive element the icon is displayed on), but rather the hit area. For example the Material guidelines recommend a minimum hit area of 48x48dp for icon buttons, even though the visible area might be as small as 32db and the icon on that button would be only 20dp.

Sure - but Toga's sizes are specified in "CSS pixels", which already adapt for screen density. This is why the Windows and Android backends both have scale_in() and scale_out() mechanisms whenever pixels sizes are referenced.

Oh sorry my point wasn't so much about the density as it was about the relationship between icon size and hit area. I was just noting that the icon size doesn't need to match the minimum hit area size - it will sometimes be much smaller.

Providing adaptive enum constants like Toga.Icon.Size.NORMAL,SMALL, LARGE, XLARGE that map to platform-appropriate sizes (NORMAL = 32 on desktop, 48 on mobile) means we can provide some helpful breakpoints.

This does seem like a helpful approach, though NORMAL might be context/widget specific, not just platform specific.

Certainly possible - although at present, the usage on a button is the only context where we're using icons where a size definition would be applicable.

This comment made me realise that in Toga you can use an Image in an ImageView but not an Icon whereas the various platforms don't make that distinction (in terms of semantics) and they have guidelines on icons when used next to text (about matching size, weight etc.) where NORMAL might be the font size (or a size related to the font size).

Is there a technical reason for this? A quick look at the Image docs suggests that you don't get the "closest size" benefits of the Icon.

From an API perspective, I don't know if this means the "Size" enum should be button-specific (reflecting that fact that a "small" button icon might not be the same size in some other usage). While this might be technically correct, it also strikes me as a little bit YAGNI...

Looking at the intersection of sizes from the different guidelines (and the lack of specifics for the Apple platforms) the enums could look like this:

	SMALL	NORMAL	LARGE	EXTRA LARGE
Android/iOS	20	24	40	48
GTK/Windows/macOS	16	32	64	128

I don't think a simple _rtl suffix would be sufficient here. If you have an icon that contains alphanumerics, you don't just need it to be RTL - you need it to be in Arabic/Hebrew etc. At that point, you need to start considering ISO-language code suffixes... and that seems like the start of a much bigger set of i18n/l10n issues.

Agreed.

[freakboy3742]

I guess I don't full have my head around how the underlying systems work for each platform. If it's enough to just provide a base image name e.g. Icon("resources/my_icon") then maybe it just becomes a documentation issues to guide people on how to add high DPI versions for each platform.

That is indeed the API at present - you specify a generic resource name, and the platform works out how to resolve that into one (or many) images, as the platform allows.

Oh sorry my point wasn't so much about the density as it was about the relationship between icon size and hit area. I was just noting that the icon size doesn't need to match the minimum hit area size - it will sometimes be much smaller.

That seems like a distinction that we don't really need to care about. In all the instances where icons are being used by Toga, the icon isn't the active element - the button/toolbar etc is the active element. It's up to the button/toolbar etc to determine how big the active area is - and that area will always be bigger than the icon.

This comment made me realise that in Toga you can use an Image in an ImageView but not an Icon whereas the various platforms don't make that distinction (in terms of semantics) and they have guidelines on icons when used next to text (about matching size, weight etc.) where NORMAL might be the font size (or a size related to the font size).

Is there a technical reason for this? A quick look at the Image docs suggests that you don't get the "closest size" benefits of the Icon.

Yes - an icon isn't an image (and vice versa).

Looking at the intersection of sizes from the different guidelines (and the lack of specifics for the Apple platforms) the enums could look like this:

SMALL NORMAL LARGE EXTRA LARGE
Android/iOS 20 24 40 48
GTK/Windows/macOS 16 32 64 128

Those desktop breakpoints makes sense to me - the sizes for Android/iOS sizes all look "off by 2x" (the current "normal" size on both is 48 CSS pixels).