Unified Tool Bars

VAqua supports three styles of windows with unified tool bars. All three styles use a textured window background that paints a gradient behind the title bar and tool bar. The styles differ in the placement of the tool bar relative to the title bar.

A unified tool bar window style is selected by setting the Aqua.windowStyle client property on the root pane to one of these values:

unifiedToolBar - This style creates the traditional unified tool bar look, with the tool bar positioned immediately below the title bar.
combinedToolBar - This style combines the title bar and tool bar, with the tool bar placed to the right of the title bar (stoplight) buttons. (This style is used by Safari.)
texturedToolBar - This style displays the tool bar in place of the title bar.

Certain requirements must be met to use a unified tool bar window style. The window must be a decorated window. The content pane must be a Swing component that contains a non-floatable JToolBar or a tool bar panel (see below). The tool bar must be positioned at the top edge of the content pane. These requirements must be satisfied and the style client property must be specified at the time the window is made displayable (made visible or packed). Changes to the client property or replacement of the content pane or toolbar after the window becomes displayable are not supported.

A window using a unified tool bar style may optionally define a bottom window margin.

Sample code

Tool Bar Panels

Instead of a non-floatable JToolBar, the window may contain a tool bar panel. A tool bar panel is an arbitrary Swing container whose Aqua.isToolBarPanel client property has the value (Boolean) true. The components of a tool bar panel are given the same tool bar specific styles as components of a JToolBar. Dynamic changes to this client property are supported only for instances of JPanel.

Implementation Restrictions

VAqua makes some changes to application components to implement a unified tool bar window style. The window title is cleared for those styles where the tool bar is combined with or replaces the title bar. (The title bar is still present, but it has a transparent background.) The content pane, tool bar, and any intermediate containers are made not opaque, to allow the textured background to be visible. A default border is defined for the tool bar, with insets that position it correctly relative to the title bar. The default border also paints a horizontal line below the tool bar. A mouse listener is installed on the tool bar to implement dragging of the window by the title bar or tool bar backgrounds. An application should not interfere with these changes unless it can emulate their effects.

On macOS 10.10 (Yosemite), the window system continues to implement moving the window when the user drags the title bar area, even though the title bar may have a transparent background or be completely invisible and even though the mouse events are (also) delivered to Java. Therefore, on macOS 10.10, when the tool bar overlaps the title bar area, the tool bar must not contain components that use drag gestures. Ordinary buttons are fine. Combo boxes and text fields are not.