Update ModularUI Theme wiki (#50)

* theme stuff

* update

* stuff

* jei -> recipe viewer

* fix

* player inv ui factory

* more ui factory info

* typo

Author: brachy84

docs/.vitepress/config/en.ts

@@ -172,6 +172,7 @@ function wikiSidebar(): DefaultTheme.SidebarItem[] {
             { text: "Color", link: "color" },
             { text: "Drawable", link: "drawable" },
             { text: "Theme", link: "theme" },
+            { text: "Widget Theme Reference", link: "theme_ref" }
           ],
         },
       ],

docs/wiki/modularui/client-gui-tutorial.md

@@ -77,7 +77,8 @@ for client side and a diamond. Then we open the screen with `ClientGUI.open()`.
 method we just created. Now let's boot up minecraft and test it.
 
 :::info {id="info"}
-There are some overloads of `ClientGUI.open()` which allow you to pass in a `JeiSettings` or `UISettings` instance.
+There are some overloads of `ClientGUI.open()` which allow you to pass in a `RecipeViewerSettings` or `UISettings` 
+instance. (`RecipeViewer` refers to JEI in 1.12 and NEI in 1.7.10).
 :::
 
 ::: code-group

docs/wiki/modularui/framework.md

@@ -50,7 +50,7 @@ Useful methods are:
 - `getPartialTicks()` returns the partial ticks for the current frame
 - `getTheme()` returns the current active theme
 - `getUISettings()` returns the current UI settings
-- `getJeiSettings()` returns the current modifiable JEI settings
+- `getRecipeViewerSettings()` returns the current modifiable JEI/NEI settings
 
 ## ModularPanel
 

docs/wiki/modularui/getting-started.md

@@ -25,7 +25,8 @@ Check the latest version on [Github releases](https://github.com/CleanroomMC/Mod
 
 ## Development Tools
 
-I highly recommend using IntelliJ in combination with the Single Hotswap plugin.
+I highly recommend using IntelliJ in combination with the Single Hotswap plugin (doesn't work for me in newer IntelliJ
+versions, maybe it does for you).
 
 ## Other documentation
 
@@ -39,7 +40,7 @@ First you need to decide if you want a client only screen or a client-server syn
 
 Client only GUIs are easier to work with, but they can't communicate with the server.
 You can open one by calling `ClientGUI.open(ModularScreen)`. You can additionally pass in a `UISettings` or
-`JeiSettings` instance. Client only GUIs don't display JEI on the side by default. This can be changed in the
+`RecipeViewerSettings` instance. Client only GUIs don't display JEI on the side by default. This can be changed in the
 JeiSettings. The options in `UISettings` are mostly for synced GUIs. The `ModularScreen` should be a new instance.
 
 Go [here](./client-gui-tutorial.md) to get started on creating a client GUI. Even if you are looking into making a
@@ -60,12 +61,18 @@ here. A `UIFactory` is what finds the exact same `IGuiHolder` on client and serv
 `IGuiHolder` is then responsible for creating the UI. ModularUI has build-in factories for:
 
 - Standard tile entities (`GuiFactories.tileEntity()`, `PosGuiData`)
-- Items in a players hand (`GuiFactories.item()`, `HandGuiData`)
-- Sided tile entities (useful for GregTech covers) (`GuiFactories.sidedTileEntity()`, `SidedPosGuiData`)
+- Items in a players inventory (f.e. player hand or even Bauble slots, other mods can be integrated as well)
+  (`GuiFactories.playerInventory()`, `PlayerInventoryGuiData`)
+- Sided tile entities (useful for things like GregTech covers) (`GuiFactories.sidedTileEntity()`, `SidedPosGuiData`)
+- Entities (for example villager trading UI) (`GuiFactories.entity()`, `EntityGuiData`)
 - Simple factories (these always point to the same `IGuiHolder`) (`GuiFactories.createSimple()`, gui data irrelevant)
 
 Each factory may have its own custom method for opening a GUI. The factories then call `GuiManager.open(...)`.
 
+Should these not suit your needs you may implement your own factory. Just implement `UIFactory` (or `AbstractUIFactory`
+for some helpers) and register it with `GuiManager.registerFactory()`. UI factories also control the default container
+class and when the ui should be force closed (player out of range usually).
+
 Go [here](./synced-gui-tutorial.md) to get started on creating a synced GUI.
 
 #### Examples

docs/wiki/modularui/json/color.md

@@ -82,7 +82,7 @@ If `value` is not defined, [HSL](#hsl) will be used.
 ```
 :::
 
-::: note {id="note"}
+:::info Note {id="note"}
 The saturation is not the same from [HSV](#hsv) as from [HSL](#hsl) (they are calculated slightly different), but the hue is.
 :::
 
@@ -109,3 +109,27 @@ The saturation is not the same from [HSV](#hsv) as from [HSL](#hsl) (they are ca
 ::: warning {id="warning"}
 You can NOT mix any of those formats! (except of course alpha)
 :::
+
+## Predefined colors
+There is a shortcut for an invisible color:
+```json
+{
+  "color": "invisible"
+}
+```
+Which is equal to
+```json
+{
+  "color": "#00FFFFFF"
+}
+```
+Other predefined colors include for example `red`, `blue` and `green`. All predefined color ModularUI defines can be
+found [here](https://github.com/CleanroomMC/ModularUI/blob/e52f70accd97d2c9b02635f6c70627d2112d9f6f/src/main/java/com/cleanroommc/modularui/utils/Color.java#L879).
+You can also vary the shade of the predefined color by appending a ':' and a positive or negative integer. For example
+```json
+{
+  "color": "red:2"
+}
+```
+This would choose red, but two steps brighter. Negative number means darker. Zero is the main color. How many shades 
+there are for a color is not constant. You will have to look it up at the page above.

docs/wiki/modularui/json/theme.md

@@ -7,18 +7,21 @@ title: Theme
 Make sure to check out [how to register themes](../themes.md).
 
 Here we will take a look what the theme file can look like. If you are a mod developer you can directly translate it to
-your `JsonBuilder`.
+your `ThemeBuilder`.
 
-Let's look at an example. This is what the default vanilla theme as a json file would look like.
+Let's look at an example. This is what the default vanilla theme as a json file would mostly look like.
 
 ```json
 {
   "parent": "DEFAULT",
+  "defaultWidth": 18,
+  "defaultHeight": 18,
   "background": null,
   "hoverBackground": "none",
   "color": "#FFFFFFFF",
   "textColor": "#FF404040",
   "textShadow": false,
+  "iconColor": "#FF404040",
   "panel": {
     "background": {
       "type": "texture",
@@ -30,13 +33,15 @@ Let's look at an example. This is what the default vanilla theme as a json file
       "type": "texture",
       "id": "mc_button"
     },
-    "hoverBackground": {
-      "type": "texture",
-      "id": "mc_button_hovered"
-    },
     "textColor": "#FFFFFFFF",
     "textShadow": true
   },
+  "button:hover": {
+    "background": {
+      "type": "texture",
+      "id": "mc_button_hovered"
+    }
+  },
   "itemSlot": {
     "background": {
       "type": "texture",
@@ -65,20 +70,22 @@ Let's look at an example. This is what the default vanilla theme as a json file
       "type": "texture",
       "id": "mc_button"
     },
-    "hoverBackground": {
-      "type": "texture",
-      "id": "mc_button_hovered"
-    },
     "textColor": "#FFFFFFFF",
     "textShadow": true,
     "selectedBackground": {
       "type": "texture",
       "id": "mc_button_disabled"
     },
-    "selectedHoverBackground": "none",
     "selectedColor": "#FFFFFFFF",
     "selectedTextColor": "#FFFFFFFF",
     "selectedTextShadow": true
+  },
+  "toggleButton:hover": {
+    "background": {
+      "type": "texture",
+      "id": "mc_button_hovered"
+    },
+    "selectedBackground": "none"
   }
 }
 ```
@@ -87,38 +94,129 @@ First we have the `parent` property. This defines the parent theme. If a theme d
 be taken from its parent. If the `parent` property is not set, it defaults to `DEFAULT`, which is just the vanilla
 theme.
 
-After that we have the `color`, `background`, `hoverBackground`, `textColor` and `textShadow` properties. These are
-fallback properties of [widget themes](#widget-themes). You can put any properties that any widget theme can have here.
-If a widget theme does not have said property it will fall back to the top level property if defined.
-Note that `"none"` is used for `hoverBackground` so it will be ignored and the widget doesn't suddenly turn invisible.
-Read more about the difference between `"none"` and `null` [here](./drawable.md#empty-drawable)
+After that we have the `defaultWidth`, `defaultHeight`, `color`, `background`, `textColor`,
+`textShadow` and `iconColor` properties. These are fallback properties of [widget themes](#widget-themes). You can put
+any properties that any widget theme can have here. If a widget theme does not have said property it will fall back to
+the top level property if defined. The `defaultWidth` and `defaultHeight` properties determine the default widget size
+if it isn't specified. Note this won't work on every widget. `TextWidget` for example have a default size that is
+exactly the size of the text they are displaying.
+
+See [widget themes](theme_ref.md) to find out what widget themes ModularUI provides and what properties they have. 
+Addons may add more.
+
+Additionally, you can add a
+```json
+{
+  "override": true
+}
+```
+property to the top level. This will discard any previous defined themes with the same name of other resourcepacks.
+Otherwise, they will be merged, where the theme will only override properties it has defined.
+
+:::info Note {id="note"}
+All widget themes are optional. You can define as many as you like. Not defined widget themes will be taken from the
+parent theme.
+All properties of widget themes (and the fallback properties) are optional.
+:::
+
+## Hover widget themes
+You may have noticed the widget themes in the example `"button:hover": {...}` and `"toggleButton:hover": {...}`. This is
+because when a widget is hovered with the mouse a separate widget theme will be applied. This hover widget theme has all
+the properties of the non hover variant. In terms of property inheritance they behave like 
+[sub widget themes](#sub-widget-themes). If the non hover variant is specified in the current theme, then the properties
+will be inherited from there. Otherwise, it will be inherited from the hover widget theme in the parent theme. This also
+means that if the none hover variant is specified with any amount of properties, all hover effects from a parent theme
+are lost. You will have to re-add them to you current theme.
+Unlike sub widget themes, hover widget themes don't need to be registered. Just add the suffix `:hover` to any
+registered widget theme (yes, even sub widget themes) and it will work.
+
+Note that `"none"` is used for `background` inside the hover widget theme so it will be ignored
+and the widget doesn't suddenly turn invisible when you don't want a separate hover texture. Read more about the 
+difference between `"none"` and `null` [here](./drawable.md#empty-drawable).
 
-For `color` and `textColor` see [color](./color.md). For `background` and `hoverBackground`
-see [drawables](./drawable.md).
+You might think that `slotHoverColor` from item slot and fluid slot would belong in the hover widget theme, however
+these are special. Specifying them in the hover widget theme variant has no effect.
 
-Next we have objects defined with the property name `panel`, `button`, `itemSlot`, `fluidSlot`, `textField` and
-`toggleButton`.
-These are widget themes. These are all widget themes ModularUI provides. Addons may add more.
+The `defaultWidth` and the `defaultHeight` property obviously have no effect in the hover variant.
 
-## Widget themes
+## Inheritance of properties
 
-Widgets which don't use one of the existing widget themes use the fallback properties.
+All properties will default to the parent themes widget theme properties, except `color`, `textColor`, `textShadow` and
+`iconColor`. These default first to the fallback properties. You can override this behavior, by adding a `inherit` 
+property to a widget theme. The value of the property should either be a string or a list of strings where each string
+is the name of the before mentioned properties. Let's look at an example
 
-All widget themes have the properties `color`, `background`, `hoverBackground`, `textColor` and `textShadow`. Which are
-all mostly self-explanatory. `color` is applied additionally to the background (if possible).
+Let's say we have a theme A
+```json
+{
+  "button": {
+    "defaultWidth": 24,
+    "color": "#FF0000"
+  }
+}
+```
+and a theme B which is a child of A
+```json
+{
+  "parent": "A",
+  "defaultWidth": 20,
+  "color": "#00FF00",
+  "button": {
+  }
+}
+```
+Since `defaultWidth` will be inherited from the parents widget theme, the default width of the button is 24 and not 20.
+Contrary to `color` which uses the fallback value first. This means the button will have a color `#00FF00` and not
+`#FF0000`. Sometimes this behavior is not desirable. We could copy the value from the parent, but that's extra work and
+doesn't get updated when the parent value changes. Instead, we use the `inherit` property:
+```json
+{
+  "parent": "A",
+  "defaultWidth": 20,
+  "color": "#00FF00",
+  "button": {
+    "inherit": [
+      "color"
+    ]
+  }
+}
+```
+Now the button color of B will be whatever the parent widget themes values is. In this case it is `#FF0000`. Since we 
+only have one value in the inherit list, it can be shortened to `"inherit": "color"`.
 
-The `itemSlot` and `fluidSlot` also have the `slotHoverColor`, which is just the rendered color when the slot is
-hovered.
-Don't use full opacity here. Otherwise, you won't be able to see the item.
+:::info Note {id="note"}
+Note that other mods may add properties which behave similar to `color`.
+:::
 
-The `textField` theme has the `markedColor` property which is the marked text background and the `hintColor` property which is
-the color of the text that is shown when the field is empty.
+## Sub Widget Themes
+Sometimes you want to have different widget themes for the same type of widget. Let's say for example you want to color
+the player slots differently than normal slots. In java, we first need to register the sub widget theme with
+```java
+WidgetThemeKey<SlotTheme> ITEM_SLOT_PLAYER = ITEM_SLOT.createSubKey("player");
+```
 
-The `toggleButton` has `selectedBackground`, `selectedHoverBackground`, `selectedColor`, `selectedTextColor` and 
-`selectedTextShadow` which are all self-explanatory. Note that 
+Then inside a theme json we can do this.
+```json
+{
+  "itemSlot:player": {
+    "color": "#FF0000"
+  }
+}
+```
+This will color only player slots red. The syntax is `parentWidgetThemeName:subName`. Every sub widget theme has to be
+defined via a mod. ModularUI currently only has the `itemSlot:player` sub widget theme defined. Every sub theme can have
+any properties it's parent can have. Sub widget themes can have sub widget themes.
+
+Let's say that we now want to color hotbar slots a different color. We could create a new sub widget theme from 
+`ITEM_SLOT`, but if the hotbar theme is not specified it should inherit the player slot theme. We therefore create a sub
+widget theme for the just created sub widget theme.
+```java
+WidgetThemeKey<SlotTheme> ITEM_SLOT_PLAYER_HOTBAR = ITEM_SLOT_PLAYER.createSubKey("playerHotbar");
+```
+This new widget theme can be accessed with `"itemSlot:playerHotbar"` and **not** `"itemSlot:player:playerHotbar"`.
+The syntax is `rootParentWidgetThemeName:subName`. You can find the sub widget themes ModularUI provides [here](theme_ref.md#sub-widget-themes).
 
 :::info Note {id="note"}
-All widget themes are optional. You can define as many as you like. Not defined widget themes will be taken from the
-parent theme.
-All properties of widget themes (and the fallback properties) are optional.
+This feature is intended for widgets with the same type and not for different widget types which use the same widget 
+theme class.
 :::