diff --git a/HMCL/src/main/java/org/jackhuang/hmcl/ui/construct/AdvancedListItem.java b/HMCL/src/main/java/org/jackhuang/hmcl/ui/construct/AdvancedListItem.java index 7c9b1ce144..d8e6f0794b 100644 --- a/HMCL/src/main/java/org/jackhuang/hmcl/ui/construct/AdvancedListItem.java +++ b/HMCL/src/main/java/org/jackhuang/hmcl/ui/construct/AdvancedListItem.java @@ -3,6 +3,12 @@ package org.jackhuang.hmcl.ui.construct; import javafx.beans.property.*; +import javafx.css.CssMetaData; +import javafx.css.SimpleStyleableObjectProperty; +import javafx.css.Styleable; +import javafx.css.StyleableObjectProperty; +import javafx.css.StyleableProperty; +import javafx.css.converter.PaintConverter; import javafx.event.ActionEvent; import javafx.event.EventHandler; import javafx.geometry.Insets; @@ -11,21 +17,33 @@ import javafx.scene.Node; import javafx.scene.control.Control; import javafx.scene.control.Skin; import javafx.scene.layout.BorderPane; +import javafx.scene.paint.Paint; import org.jackhuang.hmcl.ui.FXUtils; import org.jackhuang.hmcl.ui.SVG; +import org.jetbrains.annotations.NotNullByDefault; import org.jetbrains.annotations.Nullable; +import org.jetbrains.annotations.Unmodifiable; + +import java.util.ArrayList; +import java.util.List; /// Displays a two-line item with optional graphics and an action supplied by its skin. +@NotNullByDefault public class AdvancedListItem extends Control { + /// The conventional size of a left graphic, in pixels. public static final double LEFT_GRAPHIC_SIZE = 32; + /// The size of icons created by [#setLeftIcon(SVG)], in pixels. public static final double LEFT_ICON_SIZE = 20; + /// The margin applied by [#setLeftIcon(SVG)]. public static final Insets LEFT_ICON_MARGIN = new Insets(0, 6, 0, 6); - public static void setMargin(Node graphic, Insets margin) { + /// Sets the graphic's [BorderPane] margin constraint; null removes the constraint. + public static void setMargin(Node graphic, @Nullable Insets margin) { BorderPane.setMargin(graphic, margin); } - public static void setAlignment(Node graphic, Pos alignment) { + /// Sets the graphic's [BorderPane] alignment constraint; null removes the constraint. + public static void setAlignment(Node graphic, @Nullable Pos alignment) { BorderPane.setAlignment(graphic, alignment); } @@ -40,20 +58,25 @@ public class AdvancedListItem extends Control { fireEvent(new ActionEvent(this, this)); } - private final ObjectProperty leftGraphic = new SimpleObjectProperty<>(this, "leftGraphic"); + /// The optional graphic displayed to the left of the text, initially null. + private final ObjectProperty<@Nullable Node> leftGraphic = new SimpleObjectProperty<>(this, "leftGraphic"); - public ObjectProperty leftGraphicProperty() { + /// Returns the left graphic property, whose value may be null. + public ObjectProperty<@Nullable Node> leftGraphicProperty() { return leftGraphic; } - public Node getLeftGraphic() { + /// Returns the left graphic, or null if absent. + public @Nullable Node getLeftGraphic() { return leftGraphic.get(); } - public void setLeftGraphic(Node leftGraphic) { + /// Sets the left graphic; null removes it. + public void setLeftGraphic(@Nullable Node leftGraphic) { this.leftGraphic.set(leftGraphic); } + /// Replaces the left graphic with a centered, mouse-transparent icon using the standard size and margin. public void setLeftIcon(SVG svg) { Node icon = svg.createIcon(LEFT_ICON_SIZE); icon.setMouseTransparent(true); @@ -62,20 +85,28 @@ public class AdvancedListItem extends Control { leftGraphicProperty().set(icon); } - private final ObjectProperty rightGraphic = new SimpleObjectProperty<>(this, "rightGraphic"); + /// The optional graphic displayed to the right of the text, initially null. + private @Nullable ObjectProperty<@Nullable Node> rightGraphic; - public ObjectProperty rightGraphicProperty() { + /// Returns the right graphic property, whose value may be null. + public ObjectProperty<@Nullable Node> rightGraphicProperty() { + if (rightGraphic == null) + rightGraphic = new SimpleObjectProperty<>(this, "rightGraphic"); return rightGraphic; } - public Node getRightGraphic() { - return rightGraphic.get(); + /// Returns the right graphic, or null if absent. + public @Nullable Node getRightGraphic() { + return rightGraphic != null ? rightGraphic.get() : null; } - public void setRightGraphic(Node rightGraphic) { - this.rightGraphic.set(rightGraphic); + /// Sets the right graphic; null removes it. + public void setRightGraphic(@Nullable Node rightGraphic) { + if (this.rightGraphic != null || rightGraphic != null) + rightGraphicProperty().set(rightGraphic); } + /// Replaces the right graphic with a centered icon button that runs the action when activated. public void setRightAction(SVG icon, Runnable action) { var button = FXUtils.newToggleButton4(icon, 14); button.setOnAction(e -> { @@ -108,48 +139,87 @@ public class AdvancedListItem extends Control { itemSkin.setPrepareAction(action); } + /// The title text, initially null. private final StringProperty title = new SimpleStringProperty(this, "title"); + /// Returns the title property, whose value may be null. public StringProperty titleProperty() { return title; } - public String getTitle() { + /// Returns the title text, or null if unset. + public @Nullable String getTitle() { return title.get(); } - public void setTitle(String title) { + /// Sets the title text; null clears it. + public void setTitle(@Nullable String title) { this.title.set(title); } + /// The subtitle text, initially null. private final StringProperty subtitle = new SimpleStringProperty(this, "subtitle"); + /// Returns the subtitle property, whose value may be null. public StringProperty subtitleProperty() { return subtitle; } - public String getSubtitle() { + /// Returns the subtitle text, or null if unset. + public @Nullable String getSubtitle() { return subtitle.get(); } - public void setSubtitle(String subtitle) { + /// Sets the subtitle text; null removes the subtitle line in the default skin. + public void setSubtitle(@Nullable String subtitle) { this.subtitle.set(subtitle); } + /// The active state, initially false, reflected by the default skin's selected pseudo-class. private final BooleanProperty active = new SimpleBooleanProperty(this, "active"); + /// Returns the active-state property. public BooleanProperty activeProperty() { return active; } + /// Returns whether the item is active. public boolean isActive() { return active.get(); } + /// Sets whether the item is active. public void setActive(boolean active) { this.active.set(active); } + /// The CSS-configurable paint used by the default skin for the selected background. + private final StyleableObjectProperty<@Nullable Paint> selectedBackgroundFill = + new SimpleStyleableObjectProperty<>(StyleableProperties.SELECTED_BACKGROUND_FILL, this, "selectedBackgroundFill"); + + /// Returns the selected-background paint property, initially null and styled by + /// `-jfx-selected-background-fill`. Null hides the selected background without changing + /// the active state. The default skin animates the background node's opacity between zero + /// and 0.5; an opaque paint therefore appears at 50% opacity when fully selected. + /// Any transparency in the paint multiplies the node's opacity. + /// Changes repaint the background without restarting the selection transition. + /// + /// @apiNote Unbound values follow JavaFX CSS precedence. Binding this property prevents + /// CSS from changing its value. + public StyleableObjectProperty<@Nullable Paint> selectedBackgroundFillProperty() { + return selectedBackgroundFill; + } + + /// Returns the paint in [#selectedBackgroundFillProperty()], or null. + public @Nullable Paint getSelectedBackgroundFill() { + return selectedBackgroundFill.get(); + } + + /// Sets [#selectedBackgroundFillProperty()]; null hides the selected background. + public void setSelectedBackgroundFill(@Nullable Paint value) { + selectedBackgroundFill.set(value); + } + /// The handler for actions originating from this item, excluding descendant controls. private final ObjectProperty<@Nullable EventHandler> onAction = new SimpleObjectProperty<>(this, "onAction") { /// Routes only this item's actions to the registered handler. @@ -178,9 +248,48 @@ public class AdvancedListItem extends Control { return onActionProperty().get(); } + /// Creates the skin that lays out the graphics and text and handles background actions. @Override protected Skin createDefaultSkin() { return new AdvancedListItemSkin(this); } + /// Returns this control's stylesheet metadata, including inherited properties. + @Override + public @Unmodifiable List> getControlCssMetaData() { + return getClassCssMetaData(); + } + + /// Returns the immutable stylesheet metadata shared by all advanced list items. + public static @Unmodifiable List> getClassCssMetaData() { + return StyleableProperties.STYLEABLES; + } + + /// Shared stylesheet metadata for advanced list items. + private static final class StyleableProperties { + /// Maps the selected background paint to its stylesheet property. + private static final CssMetaData SELECTED_BACKGROUND_FILL = + new CssMetaData<>("-jfx-selected-background-fill", PaintConverter.getInstance()) { + /// Reports whether CSS can assign the selected background paint. + @Override + public boolean isSettable(AdvancedListItem styleable) { + return styleable.selectedBackgroundFill == null || !styleable.selectedBackgroundFill.isBound(); + } + + /// Returns the property receiving stylesheet paint values. + @Override + public StyleableProperty<@Nullable Paint> getStyleableProperty(AdvancedListItem styleable) { + return styleable.selectedBackgroundFillProperty(); + } + }; + + /// The inherited control metadata followed by the selected background paint metadata. + private static final @Unmodifiable List> STYLEABLES; + + static { + var styleables = new ArrayList<>(Control.getClassCssMetaData()); + styleables.add(SELECTED_BACKGROUND_FILL); + STYLEABLES = List.copyOf(styleables); + } + } } diff --git a/HMCL/src/main/java/org/jackhuang/hmcl/ui/construct/AdvancedListItemSkin.java b/HMCL/src/main/java/org/jackhuang/hmcl/ui/construct/AdvancedListItemSkin.java index f78b7901f4..b64add1154 100644 --- a/HMCL/src/main/java/org/jackhuang/hmcl/ui/construct/AdvancedListItemSkin.java +++ b/HMCL/src/main/java/org/jackhuang/hmcl/ui/construct/AdvancedListItemSkin.java @@ -2,10 +2,19 @@ // SPDX-License-Identifier: GPL-3.0-or-later WITH AdditionRef-HMCL package org.jackhuang.hmcl.ui.construct; +import com.jfoenix.utils.JFXNodeUtils; +import javafx.animation.FadeTransition; import javafx.css.PseudoClass; +import javafx.geometry.Insets; import javafx.scene.control.SkinBase; +import javafx.scene.layout.Background; +import javafx.scene.layout.BackgroundFill; import javafx.scene.layout.BorderPane; -import org.jackhuang.hmcl.ui.FXUtils; +import javafx.scene.layout.CornerRadii; +import javafx.scene.layout.Region; +import javafx.scene.paint.Paint; +import org.jackhuang.hmcl.ui.animation.AnimationUtils; +import org.jackhuang.hmcl.ui.animation.Motion; import org.jetbrains.annotations.Nullable; /// Lays out a two-line item, forwards background actions, and registers optional preparation. @@ -13,17 +22,22 @@ public class AdvancedListItemSkin extends SkinBase { /// The pseudo-class reflecting the item's active state. private static final PseudoClass SELECTED = PseudoClass.getPseudoClass("selected"); + /// The background node opacity when the item is fully selected. + private static final double SELECTED_BACKGROUND_OPACITY = 0.5; + /// The feedback wrapper receiving the item's preparation registration. private final RipplerContainer container; + /// The theme-colored selection background, faded independently of content and feedback. + private final Region selectionBackground = new Region(); + + /// The reusable selection fade, allocated on the first animated state change. + private @Nullable FadeTransition selectionTransition; + /// Creates the content bindings and installs preparation only when configured by the item. public AdvancedListItemSkin(AdvancedListItem skinnable) { super(skinnable); - FXUtils.onChangeAndOperate(skinnable.activeProperty(), active -> { - skinnable.pseudoClassStateChanged(SELECTED, active); - }); - BorderPane root = new BorderPane(); root.getStyleClass().add("container"); root.setPickOnBounds(false); @@ -43,10 +57,51 @@ public class AdvancedListItemSkin extends SkinBase { root.leftProperty().bind(skinnable.leftGraphicProperty()); root.rightProperty().bind(skinnable.rightGraphicProperty()); - getChildren().setAll(container); + selectionBackground.setMouseTransparent(true); + getChildren().setAll(selectionBackground, container); + updateSelectionFill(); + registerChangeListener(skinnable.selectedBackgroundFillProperty(), observable -> updateSelectionFill()); + updateSelection(false); + registerChangeListener(skinnable.activeProperty(), observable -> updateSelection(true)); + registerChangeListener(skinnable.sceneProperty(), observable -> updateSelection(false)); + registerChangeListener(JFXNodeUtils.treeVisibleProperty(skinnable), observable -> updateSelection(false)); setPrepareAction(skinnable.getPrepareAction()); } + /// Applies the control's selected background paint without changing animation progress. + private void updateSelectionFill() { + @Nullable Paint fill = getSkinnable().getSelectedBackgroundFill(); + selectionBackground.setBackground(fill == null ? null + : new Background(new BackgroundFill(fill, CornerRadii.EMPTY, Insets.EMPTY))); + } + + /// Updates selection styling and fades from the displayed opacity when the item is showing. + /// Initial, detached, hidden, and animation-disabled states are applied immediately. + private void updateSelection(boolean animate) { + AdvancedListItem item = getSkinnable(); + boolean active = item.isActive(); + item.pseudoClassStateChanged(SELECTED, active); + double target = active ? SELECTED_BACKGROUND_OPACITY : 0; + double current = selectionBackground.getOpacity(); + if (selectionTransition != null) + selectionTransition.stop(); + if (!animate || !AnimationUtils.isAnimationEnabled() || !JFXNodeUtils.isTreeShowing(item) || current == target) { + selectionBackground.setOpacity(target); + return; + } + + if (selectionTransition == null) { + selectionTransition = new FadeTransition(Motion.SHORT4, selectionBackground); + selectionTransition.setInterpolator(Motion.LINEAR); + } + // Preserve the displayed opacity when reversing an unfinished fade. + selectionBackground.setOpacity(current); + selectionTransition.setFromValue(current); + selectionTransition.setToValue(target); + selectionTransition.setOnFinished(event -> selectionBackground.setOpacity(target)); + selectionTransition.playFromStart(); + } + /// Forwards a registration while consuming the control's reference before user code executes. void setPrepareAction(@Nullable Runnable action) { AdvancedListItem item = getSkinnable(); @@ -58,9 +113,12 @@ public class AdvancedListItemSkin extends SkinBase { }); } - /// Removes background activation, releases graphics, and retains unconsumed preparation on the control. + /// Stops the selection fade, removes background activation, and releases graphics. + /// Unconsumed preparation remains on the control. @Override public void dispose() { + if (selectionTransition != null) + selectionTransition.stop(); container.setOnAction(null); container.setPrepareAction(null); BorderPane root = (BorderPane) container.getContainer(); diff --git a/HMCL/src/main/resources/assets/css/root.css b/HMCL/src/main/resources/assets/css/root.css index 03703ed382..a9bd0d1140 100644 --- a/HMCL/src/main/resources/assets/css/root.css +++ b/HMCL/src/main/resources/assets/css/root.css @@ -175,8 +175,8 @@ -fx-text-alignment: justify; } -.advanced-list-item:selected > .rippler-container { - -fx-background-color: -monet-secondary-container-transparent-50; +.advanced-list-item { + -jfx-selected-background-fill: -monet-secondary-container; } .advanced-list-item:selected > .rippler-container > .container > .two-line-list-item > .first-line > .title {