MacOS provides a style of control called textured. Textured controls are designed for use in the window frame. They can be found in the toolbars of several native applications, including Mail, Safari, and TextEdit.
The rendering of controls in native applications may be different when the controls are on a tool bar versus in the content area of a window. A textured style is used on the tool bar by default. On macOS 10.11 (El Capitan) and later, controls on a tool bar are slightly taller than ordinary textured controls.
VAqua follows this policy by using a textured style by default for components contained inside a JToolBar and by using the tool bar specific component heights and rendering.
One implication of this policy is that components that are to be displayed inside a JToolBar may not return the tool bar specific layout sizes (e.g., preferred size) until they are actually added as children or descendants of a JToolBar. Most applications will not be affected by this limitation, but applications that perform calculations using the layout sizes should be sure to perform those calculations only after the components are in the JToolBar hierarchy.
Textured buttons in native applications use special rendering for icons whose images are template images. A template image is a monochromatic image that can be rendered in any color. Different colors are used for icons in enabled buttons, icons in disabled buttons, icons in selected (toggle) buttons, etc.
VAqua supports template icons in textured buttons. A template icon is recognized as such if its image contains only clear and (possibly translucent) black pixels.
To achieve the consistent appearance of native application tool bars, an application should use segmented button styles even for individual buttons. (Use a segmentPosition of only.)