Author:         Marc Culler
State:          Final
Type:           Project
Vote:           Done
Created:        18-Sep-2022
Keywords:       Tk, Aqua
Tcl-Version:    8.7
Tk-Branch: mac_styles_87
Vote-Summary   Accepted 4/0/0
Votes-For:     FV, JN, KW, MC
Votes-Against: none
Votes-Present: none

Abstract

This TIP applies only to the Aqua port of Tk. It proposes adding several new values for the -style option of the ttk::button widget and a new image type named nsimage.

Background

Apple's Human Interface Guidelines list many types of buttons for which there is no Tk equivalent. Developers of Tk applications for macOS would benefit from being able to use widgets in their Tk applications that play prominent roles in the HIG. These include Disclosure Buttons, Disclosure Triangles, Help Buttons, Image Buttons, Inline Buttons, Gradient Buttons, Rounded Rectangular Buttons, and Recessed Buttons.

The model for the approach taken in this tip is the existing Toolbutton value for the -style option of a ttk::button. This TIP adds additional values which modify the appearance of a ttk::button. In order to support the Image Button, which is heavily used in the macOS preferences app as well as in applications, this Tip also adds a new Tk image type named nsimage which leverages the capabilities of Apple's NSImage class. The nsimage type includes all of the features of the ::tk::mac::iconBitmap object and adds more features. But the resulting image name is an allowable value of the -image option of objects such as ttk::button and ttk::label. The name of a ::tk::mac::iconBitmap object is an allowable value for the -bitmap option, but need not be a bitmap. It can be a full color image. In the long run it would make more sense to either eliminate the -bitmap option or make it refer specifically to black and white images rather than allowing full color images to be treated as bitmaps. However, this TIP does not address this issue directly. It just provides an image type with all of the features of the ::tk::mac::iconBitmap as well as other features needed to create a Tk replica of Apple's Image Button.

Specification

The proposed new values for the -style option of a ttk::button are: DisclosureButton, DisclosureTriangle, HelpButton, ImageButton, InlineButton, GradientButton, BRoundedRectButton, and RecessedButton.

Usage

The nsimage image type accepts the following options:

-source (the value is an arbitrary string)
-as (the value is one of name, file, path, or filetype)
-pressed (the value is boolean)
-template (the value is boolean)

The -as option specifies how the value of the -source option should be interpreted. The name value means that the source should be the name of a named system image. The file option means that the source is a path to an image file with a format understood by the NSImage class. The path value means that the source is a path to an existing file and that the resulting image should be the system icon for files of the same filetype as the file with the given path. Finally, the filetype value means that the image should be the system icon for the filetype specified by the source, either as a filename extension, or an Apple Uniform Type Identifier, or as a four character OSCode as used in the now obsolete HFS filesystem to specify file types.

If -pressed is true the image is algorithmically modified so that it will be darker then the original in light mode and lighter than the original in dark mode. This is meant to produce an alternate image to be used when a ttk::button is in the pressed state.

If -template is true then the resulting image will be marked as a template image. Template images have all black pixels with alpha values. The system automatically changes the black to a light gray color when in dark mode. (Any NSImage can be marked as a template, but the algorithm does no work correctly unless the image has only black and alpha channels.)

Here are some examples:

image create nsimage bonjour -source NSBonjour -as name -width 48 -height 48

image create nsimage bonjour -source NSBonjour -as name -width 48 -height 48 -pressed 1

image create nsimage feather -source feather.png -as file -width 48 -height 48

To create a ttk::button using one of the new styles, simply provide the new style as the value of the -style option. For example:

ttk::button $w.imagebutton -style ImageButton -text Bonjour -image {bonjour pressed bonjour1}

Compatibility

This tip proposes new allowed values for the -style option and a new image type. It does not change any existing syntax. So it should not create any compatibility issues.

Extensibility

It might be useful to add even more of the button types listed in the HIG, or to add new styles for other widgets, such as a circular progress meter replicating the widget which is now heavily used by Apple. These extensions would follow the same paradigm. Additional values for the -style option of, say, a ttk::progressBar, could be added to produce different variants of the widgets.

Reference Implementation

These features are implemented in the mac_styles_87 branch. The branch is now 3 years old, has been synchronized with Tk 8.7 regularly, and is currently being used in commercial products based on Tk.

Copyright

This document has been placed in the public domain.

TIP 639: Include the mac_styles features in Tk 8.7