JavaFX controls in the title bar were previewed with
[JDK-8313424](https://bugs.openjdk.org/browse/JDK-8313424) (delivered in JFX
25) and the API was subsequently refined with
[JDK-8369836](https://bugs.openjdk.org/browse/JDK-8369836) (delivered in JFX
26). The feedback collected in two preview rounds suggests that the API is fit
for purpose, and no fundamental changes are required. This means that the
feature is ready to become final and permanent in JFX 27.
I propose a few small changes to smooth out remaining edges:
1. **Rename `HeaderBar.prefButtonHeight` to `HeaderBar.systemButtonHeight`**
This more clearly expresses that it is the height of the _system-provided_
buttons.
2. **Rename `HeaderBar.minSystemHeight` to `HeaderBar.systemMinHeight`**
What is meant is not a _minimum system height_ (which makes no sense), but a
_system-provided minimum height_.
3. **Add `HeaderBar.systemColorScheme`**
In the previous iteration, the color scheme of the header buttons on Windows
and Linux was determined by the brightness of the `Scene.fill` background. On
macOS, which uses header buttons drawn by the operating system, the color
scheme of the header buttons was instead determined by the color scheme of the
window itself.
The newly added `HeaderBar.systemColorScheme` attached property allows
applications to specify the color scheme for system-provided header buttons
directly, without falling back to either the scene background or the window
color scheme. The default value of the property is `null`, which means "no
preference"; in this case, the color scheme for header buttons will match the
color scheme for the window on all platforms. Setting this property to a
non-null value is only necessary in the rare case when an application needs
different color schemes for header buttons and the window (i.e. when it has a
bright title bar in dark mode, or a dark title bar in light mode).
Since these changes are only cosmetic (in the case of renamed properties) and
don't fundamentally change the API of the enhancement (in the case of
`HeaderBar.systemColorScheme`), they shouldn't need to be previewed for another
round.
The rest of the significant changes in this PR are a clean-up pass over the
documentation, and having the macOS header button implementation support the
new `HeaderBar.systemColorScheme` property.
## Note on the use of attached properties
This enhancement uses attached properties, which JavaFX has had since its
inception, in a new way. Instead of only offering a simple getter and setter,
it also adds a property getter:
public class HeaderBar {
public static void setDragType(Node child, HeaderDragType value);
public static HeaderDragType getDragType(Node child);
public static ObjectProperty<HeaderDragType> dragTypeProperty(Node child);
// <-- this is new
}
This allows developers to use the Property API to interact with attached
properties, and in the future may allow attached properties to become
CSS-styleable (#1714). This really is a missing piece that we should address,
as it makes life [much
easier](https://github.com/openjdk/jfx/pull/2015#issuecomment-3863351123) in
several scenarios. There is also an enhancement underway to formalize attached
properties in the Property API (#2015).
If we end up deciding that the Property API should _not_ support attached
properties (which would be a weird decision considering that it is a natural
extension with many downstream benefits), then the attached property getters in
the `HeaderBar` class will look a bit out of place.
---------
- [x] I confirm that I make this contribution in accordance with the [OpenJDK
Interim AI Policy](https://openjdk.org/legal/ai).
-------------
Commit messages:
- Finalize StageStyle.EXTENDED and HeaderBar
Changes: https://git.openjdk.org/jfx/pull/2188/files
Webrev: https://webrevs.openjdk.org/?repo=jfx&pr=2188&range=00
Issue: https://bugs.openjdk.org/browse/JDK-8386617
Stats: 566 lines in 24 files changed: 257 ins; 153 del; 156 mod
Patch: https://git.openjdk.org/jfx/pull/2188.diff
Fetch: git fetch https://git.openjdk.org/jfx.git pull/2188/head:pull/2188
PR: https://git.openjdk.org/jfx/pull/2188
