diff --git a/com.io7m.jsycamore.api/src/main/java/com/io7m/jsycamore/api/themes/SyThemeClassNameCustom.java b/com.io7m.jsycamore.api/src/main/java/com/io7m/jsycamore/api/themes/SyThemeClassNameCustom.java index 89157119..018c3787 100644 --- a/com.io7m.jsycamore.api/src/main/java/com/io7m/jsycamore/api/themes/SyThemeClassNameCustom.java +++ b/com.io7m.jsycamore.api/src/main/java/com/io7m/jsycamore/api/themes/SyThemeClassNameCustom.java @@ -22,10 +22,13 @@ /** * A custom class name. * - * @param className The actual class name + * @param className The actual class name + * @param description The description */ -public record SyThemeClassNameCustom(String className) +public record SyThemeClassNameCustom( + String className, + String description) implements SyThemeClassNameType { private static final Pattern VALID_CLASS_NAME = @@ -33,11 +36,15 @@ public record SyThemeClassNameCustom(String className) /** * A custom class name. + * + * @param className The actual class name + * @param description The description */ public SyThemeClassNameCustom { Objects.requireNonNull(className, "name"); + Objects.requireNonNull(description, "description"); if (!VALID_CLASS_NAME.matcher(className).matches()) { throw new IllegalArgumentException( diff --git a/com.io7m.jsycamore.api/src/main/java/com/io7m/jsycamore/api/themes/SyThemeClassNameStandard.java b/com.io7m.jsycamore.api/src/main/java/com/io7m/jsycamore/api/themes/SyThemeClassNameStandard.java index b6efc1ee..47680dd5 100644 --- a/com.io7m.jsycamore.api/src/main/java/com/io7m/jsycamore/api/themes/SyThemeClassNameStandard.java +++ b/com.io7m.jsycamore.api/src/main/java/com/io7m/jsycamore/api/themes/SyThemeClassNameStandard.java @@ -29,338 +29,453 @@ public enum SyThemeClassNameStandard * A generic button class. */ - BUTTON("Button"), + BUTTON( + "Button", + "A generic button."), /** * A checkbox class. */ - CHECKBOX("Checkbox"), + CHECKBOX( + "Checkbox", + "A checkbox."), /** * A generic container class. */ - CONTAINER("Container"), + CONTAINER( + "Container", + "A generic container."), /** * A grid view class. */ - GRID_VIEW("GridView"), + GRID_VIEW( + "GridView", + "A grid view."), /** * An image view class. */ - IMAGE_VIEW("ImageView"), + IMAGE_VIEW( + "ImageView", + "An image view."), /** * A list view class. */ - LIST_VIEW("ListView"), + LIST_VIEW( + "ListView", + "A list view."), /** * A menu bar class. */ - MENU_BAR("MenuBar"), + MENU_BAR( + "MenuBar", + "A menu bar."), /** * A menu bar item. */ - MENU_BAR_ITEM("MenuBarItem"), + MENU_BAR_ITEM( + "MenuBarItem", + "A menu bar item."), /** * The text in a menu bar item. */ - MENU_BAR_ITEM_TEXT("MenuBarItemText"), + MENU_BAR_ITEM_TEXT( + "MenuBarItemText", + "The text in a menu bar item."), /** * A menu item class. */ - MENU_ITEM("MenuItem"), + MENU_ITEM( + "MenuItem", + "A menu item."), /** * A menu item class. */ - MENU_ITEM_ATOM("MenuItemAtom"), + MENU_ITEM_ATOM( + "MenuItemAtom", + "A menu atom item."), /** * A menu item class. */ - MENU_ITEM_SEPARATOR("MenuItemSeparator"), + MENU_ITEM_SEPARATOR( + "MenuItemSeparator", + "A menu separator item."), /** * A menu item class. */ - MENU_ITEM_SUBMENU("MenuItemSubmenu"), + MENU_ITEM_SUBMENU( + "MenuItemSubmenu", + "A menu submenu item."), /** * A menu class. */ - MENU("Menu"), + MENU( + "Menu", + "A menu."), /** * A menu item text class. */ - MENU_ITEM_TEXT("MenuItemText"), + MENU_ITEM_TEXT( + "MenuItemText", + "A menu item text."), /** * A generic meter class. */ - METER("Meter"), + METER( + "Meter", + "A generic meter."), /** * A horizontal scrollbar class. */ - SCROLLBAR_HORIZONTAL("ScrollbarHorizontal"), + SCROLLBAR_HORIZONTAL( + "ScrollbarHorizontal", + "A horizontal scrollbar."), /** * A horizontal scrollbar track class. */ - SCROLLBAR_HORIZONTAL_TRACK("ScrollbarHorizontalTrack"), + SCROLLBAR_HORIZONTAL_TRACK( + "ScrollbarHorizontalTrack", + "A horizontal scrollbar track."), /** * A scrollbar button class. */ - SCROLLBAR_HORIZONTAL_BUTTON_LEFT("ScrollbarHorizontalButtonLeft"), + SCROLLBAR_HORIZONTAL_BUTTON_LEFT( + "ScrollbarHorizontalButtonLeft", + "A horizontal scrollbar left button."), /** * A scrollbar button icon class. */ - SCROLLBAR_HORIZONTAL_BUTTON_LEFT_ICON("ScrollbarHorizontalButtonLeftIcon"), + SCROLLBAR_HORIZONTAL_BUTTON_LEFT_ICON( + "ScrollbarHorizontalButtonLeftIcon", + "A horizontal scrollbar left button icon."), /** * A scrollbar button class. */ - SCROLLBAR_HORIZONTAL_BUTTON_RIGHT("ScrollbarHorizontalButtonRight"), + SCROLLBAR_HORIZONTAL_BUTTON_RIGHT( + "ScrollbarHorizontalButtonRight", + "A horizontal scrollbar right button."), /** * A scrollbar button icon class. */ - SCROLLBAR_HORIZONTAL_BUTTON_RIGHT_ICON("ScrollbarHorizontalButtonRightIcon"), + SCROLLBAR_HORIZONTAL_BUTTON_RIGHT_ICON( + "ScrollbarHorizontalButtonRightIcon", + "A horizontal scrollbar right button icon."), /** * A scrollbar button class. */ - SCROLLBAR_HORIZONTAL_BUTTON_THUMB("ScrollbarHorizontalButtonThumb"), + SCROLLBAR_HORIZONTAL_BUTTON_THUMB( + "ScrollbarHorizontalButtonThumb", + "A horizontal scrollbar thumb button."), /** * A scrollbar button icon class. */ - SCROLLBAR_HORIZONTAL_BUTTON_THUMB_ICON("ScrollbarHorizontalButtonThumbIcon"), + SCROLLBAR_HORIZONTAL_BUTTON_THUMB_ICON( + "ScrollbarHorizontalButtonThumbIcon", + "A horizontal scrollbar thumb button icon."), /** * A horizontal scrollbar class. */ - SCROLLBAR_VERTICAL("ScrollbarVertical"), + SCROLLBAR_VERTICAL( + "ScrollbarVertical", + "A vertical scrollbar."), /** * A horizontal scrollbar track class. */ - SCROLLBAR_VERTICAL_TRACK("ScrollbarVerticalTrack"), + SCROLLBAR_VERTICAL_TRACK( + "ScrollbarVerticalTrack", + "A vertical scrollbar track."), /** * A scrollbar button class. */ - SCROLLBAR_VERTICAL_BUTTON_UP("ScrollbarVerticalButtonUp"), + SCROLLBAR_VERTICAL_BUTTON_UP( + "ScrollbarVerticalButtonUp", + "A vertical scrollbar up button."), /** * A scrollbar button icon class. */ - SCROLLBAR_VERTICAL_BUTTON_UP_ICON("ScrollbarVerticalButtonUpIcon"), + SCROLLBAR_VERTICAL_BUTTON_UP_ICON( + "ScrollbarVerticalButtonUpIcon", + "A vertical scrollbar up button icon."), /** * A scrollbar button class. */ - SCROLLBAR_VERTICAL_BUTTON_DOWN("ScrollbarVerticalButtonDown"), + SCROLLBAR_VERTICAL_BUTTON_DOWN( + "ScrollbarVerticalButtonDown", + "A vertical scrollbar down button."), /** * A scrollbar button icon class. */ - SCROLLBAR_VERTICAL_BUTTON_DOWN_ICON("ScrollbarVerticalButtonDownIcon"), + SCROLLBAR_VERTICAL_BUTTON_DOWN_ICON( + "ScrollbarVerticalButtonDownIcon", + "A vertical scrollbar down button icon."), /** * A scrollbar button class. */ - SCROLLBAR_VERTICAL_BUTTON_THUMB("ScrollbarVerticalButtonThumb"), + SCROLLBAR_VERTICAL_BUTTON_THUMB( + "ScrollbarVerticalButtonThumb", + "A vertical scrollbar thumb button."), /** * A scrollbar button icon class. */ - SCROLLBAR_VERTICAL_BUTTON_THUMB_ICON("ScrollbarVerticalButtonThumbIcon"), + SCROLLBAR_VERTICAL_BUTTON_THUMB_ICON( + "ScrollbarVerticalButtonThumbIcon", + "A vertical scrollbar thumb button icon."), /** * A scrollpane class. */ - SCROLLPANE("ScrollPane"), + SCROLLPANE( + "ScrollPane", + "A scroll pane."), /** * A scrollpane content area class. */ - SCROLLPANE_CONTENT_AREA("ScrollPaneContentArea"), + SCROLLPANE_CONTENT_AREA( + "ScrollPaneContentArea", + "A scroll pane content area."), /** * A scrollpane content area viewport class. */ - SCROLLPANE_CONTENT_AREA_VIEWPORT("ScrollPaneContentAreaViewport"), + SCROLLPANE_CONTENT_AREA_VIEWPORT( + "ScrollPaneContentAreaViewport", + "A scroll pane viewport."), /** * A text area class. */ - TEXT_AREA("TextArea"), + TEXT_AREA( + "TextArea", + "A text area."), /** * A text field class. */ - TEXT_FIELD("TextField"), + TEXT_FIELD( + "TextField", + "A text field."), /** * A text view class. */ - TEXT_VIEW("TextView"), + TEXT_VIEW( + "TextView", + "A text view."), /** * A multi-line text view class. */ - TEXT_MULTILINE_VIEW("TextMultilineView"), + TEXT_MULTILINE_VIEW( + "TextMultilineView", + "A multi-line text view."), /** * The close button for a window. */ - WINDOW_BUTTON_CLOSE("WindowButtonClose"), + WINDOW_BUTTON_CLOSE( + "WindowButtonClose", + "The close button for a window."), /** * The close button icon for a window. */ - WINDOW_BUTTON_CLOSE_ICON("WindowButtonCloseIcon"), + WINDOW_BUTTON_CLOSE_ICON( + "WindowButtonCloseIcon", + "The close button icon for a window."), /** * The maximize button for a window. */ - WINDOW_BUTTON_MAXIMIZE("WindowButtonMaximize"), + WINDOW_BUTTON_MAXIMIZE( + "WindowButtonMaximize", + "The maximize button for a window."), /** * The menu button for a window. */ - WINDOW_BUTTON_MENU("WindowButtonMenu"), + WINDOW_BUTTON_MENU( + "WindowButtonMenu", + "The menu button for a window."), /** * The content area for a window. */ - WINDOW_CONTENT_AREA("WindowContentArea"), + WINDOW_CONTENT_AREA( + "WindowContentArea", + "The content area for a window."), /** * The east resize area for a window. */ - WINDOW_RESIZE_E("WindowResizeE"), + WINDOW_RESIZE_E( + "WindowResizeE", + "The east resize area for a window."), /** * The north resize area for a window. */ - WINDOW_RESIZE_N("WindowResizeN"), + WINDOW_RESIZE_N( + "WindowResizeN", + "The north resize area for a window."), /** * The north-east resize area for a window. */ - WINDOW_RESIZE_NE("WindowResizeNE"), + WINDOW_RESIZE_NE( + "WindowResizeNE", + "The north-east resize area for a window."), /** * The north-west resize area for a window. */ - WINDOW_RESIZE_NW("WindowResizeNW"), + WINDOW_RESIZE_NW( + "WindowResizeNW", + "The north-west resize area for a window."), /** * The south resize area for a window. */ - WINDOW_RESIZE_S("WindowResizeS"), + WINDOW_RESIZE_S( + "WindowResizeS", + "The south resize area for a window."), /** * The south-east resize area for a window. */ - WINDOW_RESIZE_SE("WindowResizeSE"), + WINDOW_RESIZE_SE( + "WindowResizeSE", + "The south-east resize area for a window."), /** * The south-west resize area for a window. */ - WINDOW_RESIZE_SW("WindowResizeSW"), + WINDOW_RESIZE_SW( + "WindowResizeSW", + "The south-west resize area for a window."), /** * The west resize area for a window. */ - WINDOW_RESIZE_W("WindowResizeW"), + WINDOW_RESIZE_W( + "WindowResizeW", + "The west resize area for a window."), /** * The root component for a window. */ - WINDOW_ROOT("WindowRoot"), + WINDOW_ROOT( + "WindowRoot", + "The root component for a window."), /** * The title component for a window. */ - WINDOW_TITLE("WindowTitle"), + WINDOW_TITLE( + "WindowTitle", + "The title component for a window."), /** * The title text component for a window. */ - WINDOW_TITLE_TEXT("WindowTitleText"); + WINDOW_TITLE_TEXT( + "WindowTitleText", + "The title text component for a window."); private final String className; + private final String description; SyThemeClassNameStandard( - final String inClassName) + final String inClassName, + final String inDescription) { - this.className = Objects.requireNonNull(inClassName, "className"); + this.className = + Objects.requireNonNull(inClassName, "className"); + this.description = + Objects.requireNonNull(inDescription, "inDescription"); } @Override @@ -374,4 +489,10 @@ public String className() { return this.className; } + + @Override + public String description() + { + return this.description; + } } diff --git a/com.io7m.jsycamore.api/src/main/java/com/io7m/jsycamore/api/themes/SyThemeClassNameType.java b/com.io7m.jsycamore.api/src/main/java/com/io7m/jsycamore/api/themes/SyThemeClassNameType.java index 08f1e201..1cce2e8a 100644 --- a/com.io7m.jsycamore.api/src/main/java/com/io7m/jsycamore/api/themes/SyThemeClassNameType.java +++ b/com.io7m.jsycamore.api/src/main/java/com/io7m/jsycamore/api/themes/SyThemeClassNameType.java @@ -29,4 +29,10 @@ public sealed interface SyThemeClassNameType */ String className(); + + /** + * @return A humanly-readable description of the style class + */ + + String description(); } diff --git a/com.io7m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-theme-std.xml b/com.io7m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-theme-std.xml new file mode 100644 index 00000000..a8557fda --- /dev/null +++ b/com.io7m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-theme-std.xml @@ -0,0 +1,228 @@ + + + + + Name + Description + + + Button + A generic button. + + + Checkbox + A checkbox. + + + Container + A generic container. + + + GridView + A grid view. + + + ImageView + An image view. + + + ListView + A list view. + + + MenuBar + A menu bar. + + + MenuBarItem + A menu bar item. + + + MenuBarItemText + The text in a menu bar item. + + + MenuItem + A menu item. + + + MenuItemAtom + A menu atom item. + + + MenuItemSeparator + A menu separator item. + + + MenuItemSubmenu + A menu submenu item. + + + Menu + A menu. + + + MenuItemText + A menu item text. + + + Meter + A generic meter. + + + ScrollbarHorizontal + A horizontal scrollbar. + + + ScrollbarHorizontalTrack + A horizontal scrollbar track. + + + ScrollbarHorizontalButtonLeft + A horizontal scrollbar left button. + + + ScrollbarHorizontalButtonLeftIcon + A horizontal scrollbar left button icon. + + + ScrollbarHorizontalButtonRight + A horizontal scrollbar right button. + + + ScrollbarHorizontalButtonRightIcon + A horizontal scrollbar right button icon. + + + ScrollbarHorizontalButtonThumb + A horizontal scrollbar thumb button. + + + ScrollbarHorizontalButtonThumbIcon + A horizontal scrollbar thumb button icon. + + + ScrollbarVertical + A vertical scrollbar. + + + ScrollbarVerticalTrack + A vertical scrollbar track. + + + ScrollbarVerticalButtonUp + A vertical scrollbar up button. + + + ScrollbarVerticalButtonUpIcon + A vertical scrollbar up button icon. + + + ScrollbarVerticalButtonDown + A vertical scrollbar down button. + + + ScrollbarVerticalButtonDownIcon + A vertical scrollbar down button icon. + + + ScrollbarVerticalButtonThumb + A vertical scrollbar thumb button. + + + ScrollbarVerticalButtonThumbIcon + A vertical scrollbar thumb button icon. + + + ScrollPane + A scroll pane. + + + ScrollPaneContentArea + A scroll pane content area. + + + ScrollPaneContentAreaViewport + A scroll pane viewport. + + + TextArea + A text area. + + + TextField + A text field. + + + TextView + A text view. + + + TextMultilineView + A multi-line text view. + + + WindowButtonClose + The close button for a window. + + + WindowButtonCloseIcon + The close button icon for a window. + + + WindowButtonMaximize + The maximize button for a window. + + + WindowButtonMenu + The menu button for a window. + + + WindowContentArea + The content area for a window. + + + WindowResizeE + The east resize area for a window. + + + WindowResizeN + The north resize area for a window. + + + WindowResizeNE + The north-east resize area for a window. + + + WindowResizeNW + The north-west resize area for a window. + + + WindowResizeS + The south resize area for a window. + + + WindowResizeSE + The south-east resize area for a window. + + + WindowResizeSW + The south-west resize area for a window. + + + WindowResizeW + The west resize area for a window. + + + WindowRoot + The root component for a window. + + + WindowTitle + The title component for a window. + + + WindowTitleText + The title text component for a window. + +
\ No newline at end of file diff --git a/com.io7m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-theme.xml b/com.io7m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-theme.xml index 8423b54a..b7a7aa2d 100644 --- a/com.io7m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-theme.xml +++ b/com.io7m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-theme.xml @@ -1,6 +1,7 @@
@@ -84,6 +85,25 @@ fallback function should not be evaluated unless something is wrong with the theme or the component is defined in a manner that makes it incompatible with the theme. + + As components return a non-empty list of style classes in priority order, this allows components to essentially + instruct themes on how to handle the components including potential fallback behaviour. For example, a component + can return the list of style classes [AcmeMagicButton, Button]. This is the + same as stating "If you have support for + AcmeMagicButtons, then render this component as one of those. Otherwise, if you + only have support for ordinary buttons, then render this component as one of those." + + + + The jsycamore package defines a set of standard theme classes for which all + themes should attempt to support at a minimum. These names are provided as part of the + SyThemeClassNameStandard enum. + + + + + +
diff --git a/com.io7m.jsycamore.tests/src/main/java/com/io7m/jsycamore/tests/SyButtonTest.java b/com.io7m.jsycamore.tests/src/main/java/com/io7m/jsycamore/tests/SyButtonTest.java index 8b4739fe..6462d40c 100644 --- a/com.io7m.jsycamore.tests/src/main/java/com/io7m/jsycamore/tests/SyButtonTest.java +++ b/com.io7m.jsycamore.tests/src/main/java/com/io7m/jsycamore/tests/SyButtonTest.java @@ -266,7 +266,7 @@ public void testButtonTextInitial() public void testButtonTextInitialExtras() { final var c = - button(this.screen(), List.of(new SyThemeClassNameCustom("Q")), text("Z")); + button(this.screen(), List.of(new SyThemeClassNameCustom("Q", "Q")), text("Z")); assertEquals("Z", c.text().get().value()); assertEquals("Q", c.themeClassesInPreferenceOrder().get(0).className()); } diff --git a/com.io7m.jsycamore.tests/src/main/java/com/io7m/jsycamore/tests/SyThemeClassNamesStandard.java b/com.io7m.jsycamore.tests/src/main/java/com/io7m/jsycamore/tests/SyThemeClassNamesStandard.java new file mode 100644 index 00000000..4d016edf --- /dev/null +++ b/com.io7m.jsycamore.tests/src/main/java/com/io7m/jsycamore/tests/SyThemeClassNamesStandard.java @@ -0,0 +1,53 @@ +/* + * Copyright © 2022 Mark Raynsford https://www.io7m.com + * + * Permission to use, copy, modify, and/or distribute this software for any + * purpose with or without fee is hereby granted, provided that the above + * copyright notice and this permission notice appear in all copies. + * + * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY + * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR + * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + */ + + +package com.io7m.jsycamore.tests; + +import com.io7m.jsycamore.api.themes.SyThemeClassNameStandard; + +public final class SyThemeClassNamesStandard +{ + private SyThemeClassNamesStandard() + { + + } + + public static void main( + final String[] args) + { + System.out.println(""" + + + Name + Description + +"""); + + for (final var name : SyThemeClassNameStandard.values()) { + System.out.printf(""" + + %s + %s + +""", name.className(), name.description()); + } + + System.out.println(""" +
+"""); + } +} diff --git a/com.io7m.jsycamore.tests/src/main/java/com/io7m/jsycamore/tests/SyThemeClassNamesTest.java b/com.io7m.jsycamore.tests/src/main/java/com/io7m/jsycamore/tests/SyThemeClassNamesTest.java index 3ad39d3a..939997bb 100644 --- a/com.io7m.jsycamore.tests/src/main/java/com/io7m/jsycamore/tests/SyThemeClassNamesTest.java +++ b/com.io7m.jsycamore.tests/src/main/java/com/io7m/jsycamore/tests/SyThemeClassNamesTest.java @@ -35,8 +35,8 @@ private static DynamicTest validClassNameOf( final String text) { return DynamicTest.dynamicTest("testValid_" + text, () -> { - assertEquals(text, new SyThemeClassNameCustom(text).className()); - assertEquals(text, new SyThemeClassNameCustom(text).toString()); + assertEquals(text, new SyThemeClassNameCustom(text, "A").className()); + assertEquals(text, new SyThemeClassNameCustom(text, "A").toString()); }); } @@ -45,7 +45,7 @@ private static DynamicTest invalidClassNameOf( { return DynamicTest.dynamicTest("testInvalid_" + text, () -> { assertThrows(IllegalArgumentException.class, () -> { - new SyThemeClassNameCustom(text); + new SyThemeClassNameCustom(text, "A"); }); }); }