Skip to content

Commit 75a75a3

Browse files
NichtStudioCodeNichtStudioCode
committed
Document invui-kotlin
1 parent 4628889 commit 75a75a3

25 files changed

+2806
-8
lines changed

‎invui-kotlin/src/main/kotlin/xyz/xenondevs/invui/dsl/AnvilWindowDsl.kt‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,20 +16,100 @@ import xyz.xenondevs.invui.window.setTextFieldAlwaysEnabled
1616
import kotlin.contracts.InvocationKind
1717
import kotlin.contracts.contract
1818

19+
/**
20+
* Creates an [AnvilWindow] using the DSL.
21+
*
22+
* An anvil window displays an anvil GUI with a text input field. The [upperGui][AnvilWindowDsl.upperGui]
23+
* is a 3x1 GUI representing the three anvil slots (left input, right input, result).
24+
*
25+
* ```
26+
* val myWindow = anvilWindow(player) {
27+
* title by "Rename Item"
28+
*
29+
* upperGui by gui("l r o") {
30+
* 'l' by leftInputItem
31+
* 'r' by rightInputItem
32+
* 'o' by resultItem
33+
* }
34+
* }
35+
* ```
36+
*
37+
* @see AnvilWindowDsl
38+
*/
1939
@ExperimentalDslApi
2040
inline fun anvilWindow(viewer: Player, anvilWindow: AnvilWindowDsl.() -> Unit): AnvilWindow {
2141
contract { callsInPlace(anvilWindow, InvocationKind.EXACTLY_ONCE) }
2242
return AnvilWindowDslImpl(viewer).apply(anvilWindow).build()
2343
}
2444

45+
/**
46+
* DSL scope for configuring an [AnvilWindow].
47+
*
48+
* Extends [SplitWindowDsl] with anvil-specific properties such as [text] to observe the text field
49+
* contents.
50+
*
51+
* ```
52+
* anvilWindow(player) {
53+
* title by "Enter Name"
54+
*
55+
* upperGui by gui("l r o") {
56+
* 'l' by inputItem
57+
* 'r' by materialItem
58+
* 'o' by resultItem
59+
* }
60+
* }
61+
* ```
62+
*/
2563
@ExperimentalDslApi
2664
sealed interface AnvilWindowDsl : SplitWindowDsl {
2765

66+
/**
67+
* A [Provider] that resolves to the built [AnvilWindow] instance.
68+
*
69+
* Can be used to obtain a reference to the window after the DSL block finishes and
70+
* the window is built. Accessing it before the window is built throws an
71+
* [IllegalStateException].
72+
*/
2873
override val window: Provider<AnvilWindow>
2974

75+
/**
76+
* The upper GUI (3x1) representing the three anvil slots: left input, right input,
77+
* and result.
78+
*
79+
* ```
80+
* upperGui by gui("l r o") {
81+
* 'l' by leftInputItem
82+
* 'r' by rightInputItem
83+
* 'o' by resultItem
84+
* }
85+
* ```
86+
*/
3087
val upperGui: GuiDslProperty
88+
89+
/**
90+
* A read-only [Provider] that tracks the current text in the anvil's text field,
91+
* updated as the player types.
92+
*/
3193
val text: Provider<String>
94+
95+
/**
96+
* Whether the text field is always enabled, even without an item in the left input slot.
97+
*
98+
* Defaults to `true`. Can be set to a static value or bound to a [Provider]:
99+
* ```
100+
* textFieldAlwaysEnabled by true
101+
* ```
102+
*/
32103
val textFieldAlwaysEnabled: ProviderDslProperty<Boolean>
104+
105+
/**
106+
* Whether the result slot always allows item pickup, regardless of vanilla anvil rules.
107+
*
108+
* Defaults to `false`. Can be set to a static value or bound to a [Provider]:
109+
* ```
110+
* resultAlwaysValid by true
111+
* ```
112+
*/
33113
val resultAlwaysValid: ProviderDslProperty<Boolean>
34114

35115
}

‎invui-kotlin/src/main/kotlin/xyz/xenondevs/invui/dsl/BrewingWindowDsl.kt‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,21 +14,117 @@ import xyz.xenondevs.invui.window.setFuelProgress
1414
import kotlin.contracts.InvocationKind
1515
import kotlin.contracts.contract
1616

17+
/**
18+
* Creates a [BrewingWindow] using the DSL.
19+
*
20+
* A brewing window displays a brewing stand GUI with separate areas for the ingredient input
21+
* (1x1), fuel (1x1), and result bottles (3x1).
22+
*
23+
* ```
24+
* val myWindow = brewingWindow(player) {
25+
* title by "Brewing Stand"
26+
* inputGui by gui("i") { 'i' by ingredientItem }
27+
* fuelGui by gui("f") { 'f' by fuelItem }
28+
* resultGui by gui("a b c") {
29+
* 'a' by bottleItem1
30+
* 'b' by bottleItem2
31+
* 'c' by bottleItem3
32+
* }
33+
* brewProgress by 0.5
34+
* fuelProgress by 0.75
35+
* }
36+
* ```
37+
*
38+
* @see BrewingWindowDsl
39+
*/
1740
@ExperimentalDslApi
1841
inline fun brewingWindow(viewer: Player, brewingWindow: BrewingWindowDsl.() -> Unit): BrewingWindow {
1942
contract { callsInPlace(brewingWindow, InvocationKind.EXACTLY_ONCE) }
2043
return BrewingWindowDslImpl(viewer).apply(brewingWindow).build()
2144
}
2245

46+
/**
47+
* DSL scope for configuring a [BrewingWindow].
48+
*
49+
* Extends [SplitWindowDsl] with brewing-specific GUIs ([inputGui], [fuelGui], [resultGui])
50+
* and progress indicators ([brewProgress], [fuelProgress]).
51+
*
52+
* ```
53+
* brewingWindow(player) {
54+
* title by "Brewing Stand"
55+
* inputGui by gui("i") { 'i' by ingredientItem }
56+
* fuelGui by gui("f") { 'f' by fuelItem }
57+
* resultGui by gui("a b c") {
58+
* 'a' by bottleItem1
59+
* 'b' by bottleItem2
60+
* 'c' by bottleItem3
61+
* }
62+
* brewProgress by 0.5
63+
* fuelProgress by 0.75
64+
* }
65+
* ```
66+
*/
2367
@ExperimentalDslApi
2468
sealed interface BrewingWindowDsl : SplitWindowDsl {
2569

70+
/**
71+
* A [Provider] that resolves to the built [BrewingWindow] instance.
72+
*
73+
* Can be used to obtain a reference to the window after the DSL block finishes and
74+
* the window is built. Accessing it before the window is built throws an
75+
* [IllegalStateException].
76+
*/
2677
override val window: Provider<BrewingWindow>
2778

79+
/**
80+
* The ingredient input GUI (1x1).
81+
*
82+
* ```
83+
* inputGui by gui("i") { 'i' by ingredientItem }
84+
* ```
85+
*/
2886
val inputGui: GuiDslProperty
87+
88+
/**
89+
* The fuel GUI (1x1).
90+
*
91+
* ```
92+
* fuelGui by gui("f") { 'f' by fuelItem }
93+
* ```
94+
*/
2995
val fuelGui: GuiDslProperty
96+
97+
/**
98+
* The result bottles GUI (3x1).
99+
*
100+
* ```
101+
* resultGui by gui("a b c") {
102+
* 'a' by bottleItem1
103+
* 'b' by bottleItem2
104+
* 'c' by bottleItem3
105+
* }
106+
* ```
107+
*/
30108
val resultGui: GuiDslProperty
109+
110+
/**
111+
* The brewing progress as a value from `0.0` (not started) to `1.0` (complete).
112+
*
113+
* Defaults to `0.0`. Can be set to a static value or bound to a [Provider]:
114+
* ```
115+
* brewProgress by 0.5
116+
* ```
117+
*/
31118
val brewProgress: ProviderDslProperty<Double>
119+
120+
/**
121+
* The fuel progress as a value from `0.0` (empty) to `1.0` (full).
122+
*
123+
* Defaults to `0.0`. Can be set to a static value or bound to a [Provider]:
124+
* ```
125+
* fuelProgress by 0.75
126+
* ```
127+
*/
32128
val fuelProgress: ProviderDslProperty<Double>
33129

34130
}

‎invui-kotlin/src/main/kotlin/xyz/xenondevs/invui/dsl/CartographyWindow.kt‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,18 +14,101 @@ import xyz.xenondevs.invui.window.setView
1414

1515
// TODO: map image
1616

17+
/**
18+
* Creates a [CartographyWindow] using the DSL.
19+
*
20+
* A cartography window displays a cartography table GUI with an input area (1x2) and a result
21+
* slot (1x1), along with a map preview controlled by [icons][CartographyWindowDsl.icons] and
22+
* [view][CartographyWindowDsl.view].
23+
*
24+
* ```
25+
* val myWindow = cartographyWindow(player) {
26+
* title by "Cartography Table"
27+
* inputGui by gui("a", "b") {
28+
* 'a' by mapItem
29+
* 'b' by paperItem
30+
* }
31+
* resultGui by gui("r") { 'r' by resultItem }
32+
* icons by setOf(myMapIcon)
33+
* }
34+
* ```
35+
*
36+
* @see CartographyWindowDsl
37+
*/
1738
@ExperimentalDslApi
1839
fun cartographyWindow(viewer: Player, cartographyWindow: CartographyWindowDsl.() -> Unit): CartographyWindow =
1940
CartographyWindowDslImpl(viewer).apply(cartographyWindow).build()
2041

42+
/**
43+
* DSL scope for configuring a [CartographyWindow].
44+
*
45+
* Extends [SplitWindowDsl] with cartography-specific GUIs ([inputGui], [resultGui]) and
46+
* map display properties ([icons], [view]).
47+
*
48+
* ```
49+
* cartographyWindow(player) {
50+
* title by "Cartography Table"
51+
* inputGui by gui("a", "b") {
52+
* 'a' by mapItem
53+
* 'b' by paperItem
54+
* }
55+
* resultGui by gui("r") { 'r' by resultItem }
56+
* icons by setOf(myMapIcon)
57+
* }
58+
* ```
59+
*/
2160
@ExperimentalDslApi
2261
sealed interface CartographyWindowDsl : SplitWindowDsl {
2362

63+
/**
64+
* A [Provider] that resolves to the built [CartographyWindow] instance.
65+
*
66+
* Can be used to obtain a reference to the window after the DSL block finishes and
67+
* the window is built. Accessing it before the window is built throws an
68+
* [IllegalStateException].
69+
*/
2470
override val window: Provider<CartographyWindow>
2571

72+
/**
73+
* The input GUI (1x2) for the map and paper/glass pane slots.
74+
*
75+
* ```
76+
* inputGui by gui("a", "b") {
77+
* 'a' by mapItem
78+
* 'b' by paperItem
79+
* }
80+
* ```
81+
*/
2682
val inputGui: GuiDslProperty
83+
84+
/**
85+
* The result GUI (1x1) for the output map.
86+
*
87+
* ```
88+
* resultGui by gui("r") { 'r' by resultItem }
89+
* ```
90+
*/
2791
val resultGui: GuiDslProperty
92+
93+
/**
94+
* The set of map icons to display on the map preview.
95+
*
96+
* Defaults to an empty set. Can be set to a static value or bound to a [Provider]:
97+
* ```
98+
* icons by setOf(myMapIcon)
99+
* ```
100+
*/
28101
val icons: ProviderDslProperty<Set<CartographyWindow.MapIcon>>
102+
103+
/**
104+
* The map view mode controlling how the map preview is displayed.
105+
*
106+
* Defaults to [CartographyWindow.View.NORMAL]. Can be set to a static value or bound to
107+
* a [Provider]:
108+
* ```
109+
* view by CartographyWindow.View.ZOOMED
110+
* ```
111+
*/
29112
val view: ProviderDslProperty<CartographyWindow.View>
30113

31114
}

0 commit comments

Comments
 (0)