0
# Text Formatting and Styling
1
2
Comprehensive formatting system with colors, decorations, events, and complete style management. The styling system provides immutable, composable formatting for all text components in Adventure.
3
4
## Capabilities
5
6
### Style Interface
7
8
The core styling interface that combines all formatting properties including colors, decorations, and events.
9
10
```java { .api }
11
/**
12
* Complete text formatting combining color, decorations, and events
13
*/
14
interface Style extends StyleGetter, StyleSetter<Style>, StyleBuilderApplicable, Buildable<Style, Style.Builder>, Examinable {
15
// Style properties
16
/**
17
* Gets the text color
18
* @return the color or null if not set
19
*/
20
@Nullable TextColor color();
21
22
/**
23
* Gets the state of a text decoration
24
* @param decoration the decoration to check
25
* @return the decoration state
26
*/
27
TextDecoration.State decoration(TextDecoration decoration);
28
29
/**
30
* Gets all decoration states
31
* @return map of decorations to their states
32
*/
33
Map<TextDecoration, TextDecoration.State> decorations();
34
35
/**
36
* Gets the click event
37
* @return the click event or null
38
*/
39
@Nullable ClickEvent clickEvent();
40
41
/**
42
* Gets the hover event
43
* @return the hover event or null
44
*/
45
@Nullable HoverEvent<?> hoverEvent();
46
47
/**
48
* Gets the insertion text
49
* @return the insertion text or null
50
*/
51
@Nullable String insertion();
52
53
/**
54
* Gets the font key
55
* @return the font key or null
56
*/
57
@Nullable Key font();
58
59
60
// Style creation and modification
61
/**
62
* Sets the text color
63
* @param color the color
64
* @return new style with color
65
*/
66
Style color(@Nullable TextColor color);
67
68
/**
69
* Sets a decoration state
70
* @param decoration the decoration
71
* @param state the state
72
* @return new style with decoration
73
*/
74
Style decoration(TextDecoration decoration, TextDecoration.State state);
75
76
/**
77
* Sets decoration to true state
78
* @param decoration the decoration
79
* @return new style with decoration enabled
80
*/
81
Style decorate(TextDecoration decoration);
82
83
/**
84
* Sets multiple decorations to true state
85
* @param decorations the decorations
86
* @return new style with decorations enabled
87
*/
88
Style decorate(TextDecoration... decorations);
89
90
/**
91
* Sets decoration to false state
92
* @param decoration the decoration
93
* @return new style with decoration disabled
94
*/
95
Style undecorate(TextDecoration decoration);
96
97
/**
98
* Sets the click event
99
* @param event the click event
100
* @return new style with click event
101
*/
102
Style clickEvent(@Nullable ClickEvent event);
103
104
/**
105
* Sets the hover event
106
* @param event the hover event
107
* @return new style with hover event
108
*/
109
Style hoverEvent(@Nullable HoverEvent<?> event);
110
111
/**
112
* Sets the insertion text
113
* @param insertion the insertion text
114
* @return new style with insertion
115
*/
116
Style insertion(@Nullable String insertion);
117
118
/**
119
* Sets the font
120
* @param font the font key
121
* @return new style with font
122
*/
123
Style font(@Nullable Key font);
124
125
126
/**
127
* Merges this style with another style
128
* @param that the other style
129
* @return merged style
130
*/
131
Style merge(Style that);
132
133
/**
134
* Merges styles with a merge strategy
135
* @param that the other style
136
* @param strategy the merge strategy
137
* @return merged style
138
*/
139
Style merge(Style that, Merge.Strategy strategy);
140
141
/**
142
* Edits this style using a consumer
143
* @param consumer style editor
144
* @return edited style
145
*/
146
Style edit(Consumer<Style.Builder> consumer);
147
148
/**
149
* Edits this style using a consumer with merge strategy
150
* @param consumer style editor
151
* @param strategy merge strategy
152
* @return edited style
153
*/
154
Style edit(Consumer<Style.Builder> consumer, Merge.Strategy strategy);
155
156
/**
157
* Unmerges a style from this style
158
* @param that the style to unmerge
159
* @return style with removed properties
160
*/
161
Style unmerge(Style that);
162
163
/**
164
* Checks if this style is empty (no formatting)
165
* @return true if empty
166
*/
167
boolean isEmpty();
168
169
// Factory methods
170
/**
171
* Creates an empty style
172
* @return empty style
173
*/
174
static Style empty();
175
176
/**
177
* Creates a style with color
178
* @param color the color
179
* @return new style
180
*/
181
static Style style(TextColor color);
182
183
/**
184
* Creates a style with decorations
185
* @param decorations the decorations
186
* @return new style
187
*/
188
static Style style(TextDecoration... decorations);
189
190
/**
191
* Creates a style with color and decorations
192
* @param color the color
193
* @param decorations the decorations
194
* @return new style
195
*/
196
static Style style(TextColor color, TextDecoration... decorations);
197
198
/**
199
* Creates a style using a consumer
200
* @param consumer style configuration
201
* @return new style
202
*/
203
static Style style(Consumer<Style.Builder> consumer);
204
205
/**
206
* Creates a style with single decoration
207
* @param decoration the decoration
208
* @return new style
209
*/
210
static Style style(TextDecoration decoration);
211
212
/**
213
* Creates a style from iterable applicables
214
* @param applicables the style applicables
215
* @return new style
216
*/
217
static Style style(Iterable<? extends StyleBuilderApplicable> applicables);
218
219
/**
220
* Creates a style builder
221
* @return new builder
222
*/
223
static Builder style();
224
225
/**
226
* Builder for creating styles
227
*/
228
interface Builder extends AbstractBuilder<Style>, StyleSetter<Builder> {
229
// Builder inherits all StyleSetter methods
230
}
231
232
/**
233
* Style merging operations
234
*/
235
interface Merge {
236
/**
237
* Merge strategy for combining styles
238
*/
239
interface Strategy {
240
/**
241
* Merges two colors
242
* @param first the first color
243
* @param second the second color
244
* @return merged color
245
*/
246
@Nullable TextColor mergeColor(@Nullable TextColor first, @Nullable TextColor second);
247
248
/**
249
* Merges decoration states
250
* @param first the first state
251
* @param second the second state
252
* @return merged state
253
*/
254
TextDecoration.State mergeDecoration(TextDecoration.State first, TextDecoration.State second);
255
256
/**
257
* Merges click events
258
* @param first the first event
259
* @param second the second event
260
* @return merged event
261
*/
262
@Nullable ClickEvent mergeClickEvent(@Nullable ClickEvent first, @Nullable ClickEvent second);
263
264
/**
265
* Merges hover events
266
* @param first the first event
267
* @param second the second event
268
* @return merged event
269
*/
270
@Nullable HoverEvent<?> mergeHoverEvent(@Nullable HoverEvent<?> first, @Nullable HoverEvent<?> second);
271
272
/**
273
* Merges insertion strings
274
* @param first the first insertion
275
* @param second the second insertion
276
* @return merged insertion
277
*/
278
@Nullable String mergeInsertion(@Nullable String first, @Nullable String second);
279
280
/**
281
* Merges fonts
282
* @param first the first font
283
* @param second the second font
284
* @return merged font
285
*/
286
@Nullable Key mergeFont(@Nullable Key first, @Nullable Key second);
287
}
288
}
289
}
290
```
291
292
**Usage Examples:**
293
294
```java
295
import net.kyori.adventure.text.format.Style;
296
import net.kyori.adventure.text.format.NamedTextColor;
297
import net.kyori.adventure.text.format.TextDecoration;
298
299
// Create styles
300
Style redBold = Style.style(NamedTextColor.RED, TextDecoration.BOLD);
301
Style blueItalic = Style.style(NamedTextColor.BLUE, TextDecoration.ITALIC);
302
303
// Build complex styles
304
Style complex = Style.style()
305
.color(NamedTextColor.GREEN)
306
.decorate(TextDecoration.UNDERLINED)
307
.clickEvent(ClickEvent.openUrl("https://example.com"))
308
.hoverEvent(HoverEvent.showText(Component.text("Click to visit website")))
309
.build();
310
311
// Merge styles
312
Style merged = redBold.merge(blueItalic); // Blue color with both bold and italic
313
314
// Apply to components
315
Component styledText = Component.text("Styled text").style(complex);
316
```
317
318
### Text Colors
319
320
Interface and implementations for text colors supporting RGB values and named colors.
321
322
```java { .api }
323
/**
324
* Interface for text colors with RGB values
325
*/
326
interface TextColor extends Examinable, StyleBuilderApplicable, TextFormat {
327
/**
328
* Gets the RGB color value
329
* @return the color value as 24-bit RGB
330
*/
331
int value();
332
333
/**
334
* Gets the red component (0-255)
335
* @return red component
336
*/
337
default int red() {
338
return (this.value() >> 16) & 0xFF;
339
}
340
341
/**
342
* Gets the green component (0-255)
343
* @return green component
344
*/
345
default int green() {
346
return (this.value() >> 8) & 0xFF;
347
}
348
349
/**
350
* Gets the blue component (0-255)
351
* @return blue component
352
*/
353
default int blue() {
354
return this.value() & 0xFF;
355
}
356
357
/**
358
* Creates a text color from RGB value
359
* @param value the RGB value
360
* @return new text color
361
*/
362
static TextColor color(int value);
363
364
/**
365
* Creates a text color from RGB components
366
* @param r red component (0-255)
367
* @param g green component (0-255)
368
* @param b blue component (0-255)
369
* @return new text color
370
*/
371
static TextColor color(int r, int g, int b);
372
373
/**
374
* Creates a text color from RGB object
375
* @param rgb the RGB object
376
* @return new text color
377
*/
378
static TextColor color(RGBLike rgb);
379
380
/**
381
* Creates a color from RGB components (0.0-1.0)
382
* @param r red component
383
* @param g green component
384
* @param b blue component
385
* @return new text color
386
*/
387
static TextColor color(float r, float g, float b);
388
389
/**
390
* Creates a color from HSV color space
391
* @param hsv HSV color representation
392
* @return new text color
393
*/
394
static TextColor color(HSVLike hsv);
395
396
/**
397
* Creates a text color from hex string
398
* @param string the hex string (e.g., "#ff0000" or "ff0000")
399
* @return new text color
400
*/
401
static TextColor fromHexString(String string);
402
403
/**
404
* Creates a text color from CSS hex string
405
* @param hex the CSS hex string
406
* @return new text color or null if invalid
407
*/
408
static @Nullable TextColor fromCSSHexString(String hex);
409
410
/**
411
* Converts to hex string representation
412
* @return hex string (e.g., "#ff0000")
413
*/
414
String asHexString();
415
416
/**
417
* Linearly interpolates between two colors
418
* @param t interpolation factor (0.0 to 1.0)
419
* @param a the first color
420
* @param b the second color
421
* @return interpolated color
422
*/
423
static TextColor lerp(float t, RGBLike a, RGBLike b);
424
}
425
```
426
427
### Named Text Colors
428
429
Standard Minecraft color constants with predefined RGB values.
430
431
```java { .api }
432
/**
433
* Standard Minecraft named colors
434
*/
435
enum NamedTextColor implements TextColor {
436
BLACK(0x000000),
437
DARK_BLUE(0x0000aa),
438
DARK_GREEN(0x00aa00),
439
DARK_AQUA(0x00aaaa),
440
DARK_RED(0xaa0000),
441
DARK_PURPLE(0xaa00aa),
442
GOLD(0xffaa00),
443
GRAY(0xaaaaaa),
444
DARK_GRAY(0x555555),
445
BLUE(0x5555ff),
446
GREEN(0x55ff55),
447
AQUA(0x55ffff),
448
RED(0xff5555),
449
LIGHT_PURPLE(0xff55ff),
450
YELLOW(0xffff55),
451
WHITE(0xffffff);
452
453
/**
454
* Gets a named color by name
455
* @param name the color name
456
* @return the named color or null
457
*/
458
static @Nullable NamedTextColor namedColor(String name);
459
460
/**
461
* Gets the nearest named color to an RGB value
462
* @param color the color to match
463
* @return nearest named color
464
*/
465
static NamedTextColor nearestTo(TextColor color);
466
467
/**
468
* Gets all named color values
469
* @return array of all named colors
470
*/
471
static NamedTextColor[] values();
472
}
473
```
474
475
476
### Text Decorations
477
478
Enumeration of text decorations like bold, italic, underlined, etc.
479
480
```java { .api }
481
/**
482
* Text decorations for styling text
483
*/
484
enum TextDecoration implements StyleBuilderApplicable, TextFormat {
485
/**
486
* Obfuscated/magic text that changes randomly
487
*/
488
OBFUSCATED("obfuscated"),
489
490
/**
491
* Bold text
492
*/
493
BOLD("bold"),
494
495
/**
496
* Strikethrough text
497
*/
498
STRIKETHROUGH("strikethrough"),
499
500
/**
501
* Underlined text
502
*/
503
UNDERLINED("underlined"),
504
505
/**
506
* Italic text
507
*/
508
ITALIC("italic");
509
510
/**
511
* Gets the decoration by name
512
* @param name the decoration name
513
* @return the decoration or null
514
*/
515
static @Nullable TextDecoration byName(String name);
516
517
/**
518
* Gets all decoration values
519
* @return set of all decorations
520
*/
521
static Set<TextDecoration> values();
522
523
/**
524
* State of a text decoration
525
*/
526
enum State {
527
/**
528
* Decoration state is not set (inherit from parent)
529
*/
530
NOT_SET,
531
532
/**
533
* Decoration is explicitly disabled
534
*/
535
FALSE,
536
537
/**
538
* Decoration is explicitly enabled
539
*/
540
TRUE;
541
542
/**
543
* Gets state by boolean value
544
* @param flag the boolean value
545
* @return TRUE if true, FALSE if false
546
*/
547
static State byBoolean(boolean flag);
548
549
/**
550
* Gets state by boolean, with NOT_SET for null
551
* @param flag the boolean value or null
552
* @return appropriate state
553
*/
554
static State byBoolean(@Nullable Boolean flag);
555
}
556
}
557
```
558
559
### Text Decoration and State
560
561
Interface combining decoration with its state for convenience.
562
563
```java { .api }
564
/**
565
* Text decoration combined with its state
566
*/
567
interface TextDecorationAndState extends Examinable {
568
/**
569
* Gets the decoration
570
* @return the decoration
571
*/
572
TextDecoration decoration();
573
574
/**
575
* Gets the state
576
* @return the state
577
*/
578
TextDecoration.State state();
579
580
/**
581
* Creates a decoration and state combination
582
* @param decoration the decoration
583
* @param state the state
584
* @return new decoration and state
585
*/
586
static TextDecorationAndState of(TextDecoration decoration, TextDecoration.State state);
587
588
/**
589
* Creates decoration with TRUE state
590
* @param decoration the decoration
591
* @return decoration with TRUE state
592
*/
593
static TextDecorationAndState of(TextDecoration decoration);
594
}
595
```
596
597
## Style Getter and Setter Interfaces
598
599
### Style Getter
600
601
Interface for objects that have style information.
602
603
```java { .api }
604
/**
605
* Interface for objects that have style information
606
*/
607
interface StyleGetter {
608
/**
609
* Gets the style
610
* @return the style
611
*/
612
Style style();
613
614
/**
615
* Gets the text color
616
* @return the color or null
617
*/
618
default @Nullable TextColor color() {
619
return this.style().color();
620
}
621
622
/**
623
* Gets a decoration state
624
* @param decoration the decoration
625
* @return the decoration state
626
*/
627
default TextDecoration.State decoration(TextDecoration decoration) {
628
return this.style().decoration(decoration);
629
}
630
631
/**
632
* Checks if a decoration is present and enabled
633
* @param decoration the decoration
634
* @return true if decoration is TRUE
635
*/
636
default boolean hasDecoration(TextDecoration decoration) {
637
return this.decoration(decoration) == TextDecoration.State.TRUE;
638
}
639
640
/**
641
* Gets the click event
642
* @return the click event or null
643
*/
644
default @Nullable ClickEvent clickEvent() {
645
return this.style().clickEvent();
646
}
647
648
/**
649
* Gets the hover event
650
* @return the hover event or null
651
*/
652
default @Nullable HoverEvent<?> hoverEvent() {
653
return this.style().hoverEvent();
654
}
655
656
/**
657
* Gets the insertion text
658
* @return the insertion text or null
659
*/
660
default @Nullable String insertion() {
661
return this.style().insertion();
662
}
663
664
/**
665
* Gets the font
666
* @return the font key or null
667
*/
668
default @Nullable Key font() {
669
return this.style().font();
670
}
671
}
672
```
673
674
### Style Setter
675
676
Interface for objects that can have style applied, providing fluent style modification methods.
677
678
```java { .api }
679
/**
680
* Interface for objects that can have style applied
681
*/
682
interface StyleSetter<T> {
683
/**
684
* Sets the style
685
* @param style the style
686
* @return object with new style
687
*/
688
T style(Style style);
689
690
/**
691
* Applies a style configurator
692
* @param applicableStyle the style to apply
693
* @return object with applied style
694
*/
695
T style(StyleBuilderApplicable applicableStyle);
696
697
/**
698
* Applies multiple style configurators
699
* @param applicableStyles the styles to apply
700
* @return object with applied styles
701
*/
702
T style(StyleBuilderApplicable... applicableStyles);
703
704
/**
705
* Merges with another style
706
* @param style the style to merge
707
* @return object with merged style
708
*/
709
T mergeStyle(Style style);
710
711
/**
712
* Merges with another style using a merge strategy
713
* @param style the style to merge
714
* @param strategy the merge strategy
715
* @return object with merged style
716
*/
717
T mergeStyle(Style style, Style.Merge.Strategy strategy);
718
719
/**
720
* Sets the text color
721
* @param color the color
722
* @return object with new color
723
*/
724
T color(@Nullable TextColor color);
725
726
/**
727
* Sets the text color using RGB
728
* @param color the RGB color
729
* @return object with new color
730
*/
731
T color(@Nullable RGBLike color);
732
733
/**
734
* Removes the text color
735
* @return object without color
736
*/
737
default T colorIfAbsent(@Nullable TextColor color) {
738
return this.color() == null ? this.color(color) : (T) this;
739
}
740
741
/**
742
* Sets a decoration state
743
* @param decoration the decoration
744
* @param state the state
745
* @return object with decoration state
746
*/
747
T decoration(TextDecoration decoration, TextDecoration.State state);
748
749
/**
750
* Sets a decoration state by boolean
751
* @param decoration the decoration
752
* @param flag the boolean state
753
* @return object with decoration state
754
*/
755
T decoration(TextDecoration decoration, boolean flag);
756
757
/**
758
* Enables a decoration
759
* @param decoration the decoration
760
* @return object with decoration enabled
761
*/
762
default T decorate(TextDecoration decoration) {
763
return this.decoration(decoration, TextDecoration.State.TRUE);
764
}
765
766
/**
767
* Enables multiple decorations
768
* @param decorations the decorations
769
* @return object with decorations enabled
770
*/
771
T decorate(TextDecoration... decorations);
772
773
/**
774
* Disables a decoration
775
* @param decoration the decoration
776
* @return object with decoration disabled
777
*/
778
default T undecorate(TextDecoration decoration) {
779
return this.decoration(decoration, TextDecoration.State.FALSE);
780
}
781
782
/**
783
* Disables multiple decorations
784
* @param decorations the decorations
785
* @return object with decorations disabled
786
*/
787
T undecorate(TextDecoration... decorations);
788
789
/**
790
* Sets the click event
791
* @param event the click event
792
* @return object with click event
793
*/
794
T clickEvent(@Nullable ClickEvent event);
795
796
/**
797
* Sets the hover event
798
* @param event the hover event
799
* @return object with hover event
800
*/
801
T hoverEvent(@Nullable HoverEvent<?> event);
802
803
/**
804
* Sets the insertion text
805
* @param insertion the insertion text
806
* @return object with insertion
807
*/
808
T insertion(@Nullable String insertion);
809
810
/**
811
* Sets the font
812
* @param font the font key
813
* @return object with font
814
*/
815
T font(@Nullable Key font);
816
}
817
```
818
819
### Mutable Style Setter
820
821
Marker interface for style setters that modify the object in place.
822
823
```java { .api }
824
/**
825
* Style setter that modifies the object in place
826
*/
827
interface MutableStyleSetter<T> extends StyleSetter<T> {
828
// Inherits all StyleSetter methods but implementations modify in place
829
}
830
```
831
832
## Style Builder Applicable
833
834
Interface for objects that can be applied to style builders for configuration.
835
836
```java { .api }
837
/**
838
* Objects that can be applied to style builders
839
*/
840
interface StyleBuilderApplicable {
841
/**
842
* Applies this object to a style builder
843
* @param builder the style builder
844
*/
845
void styleApply(Style.Builder builder);
846
}
847
```
848
849
## Text Format Base Interface
850
851
Base interface for all text formatting elements.
852
853
```java { .api }
854
/**
855
* Base interface for text formatting elements
856
*/
857
interface TextFormat extends Examinable {
858
// Marker interface - implementations provide specific formatting behavior
859
}
860
```
861
862
## Color Utility Interfaces
863
864
### RGB-Like Interface
865
866
Interface for objects with RGB color components.
867
868
```java { .api }
869
/**
870
* Interface for objects with RGB color values
871
*/
872
interface RGBLike {
873
/**
874
* Gets the red component (0-255)
875
* @return red component
876
*/
877
int red();
878
879
/**
880
* Gets the green component (0-255)
881
* @return green component
882
*/
883
int green();
884
885
/**
886
* Gets the blue component (0-255)
887
* @return blue component
888
*/
889
int blue();
890
}
891
```
892
893
### ARGB-Like Interface
894
895
Interface for objects with ARGB color components including alpha.
896
897
```java { .api }
898
/**
899
* Interface for objects with ARGB color values
900
*/
901
interface ARGBLike extends RGBLike {
902
/**
903
* Gets the alpha component (0-255)
904
* @return alpha component
905
*/
906
int alpha();
907
908
/**
909
* Gets the ARGB value as a 32-bit integer
910
* @return ARGB value
911
*/
912
default int argb() {
913
return (this.alpha() << 24) | (this.red() << 16) | (this.green() << 8) | this.blue();
914
}
915
}
916
```
917
918
### HSV-Like Interface
919
920
Interface for objects with HSV (Hue, Saturation, Value) color representation.
921
922
```java { .api }
923
/**
924
* Interface for objects with HSV color values
925
*/
926
interface HSVLike {
927
/**
928
* Gets the hue component (0.0-360.0)
929
* @return hue in degrees
930
*/
931
float h();
932
933
/**
934
* Gets the saturation component (0.0-1.0)
935
* @return saturation
936
*/
937
float s();
938
939
/**
940
* Gets the value/brightness component (0.0-1.0)
941
* @return value
942
*/
943
float v();
944
}
945
```
946
947
## Common Formatting Patterns
948
949
### Color Creation
950
951
```java
952
// Using named colors
953
TextColor red = NamedTextColor.RED;
954
TextColor blue = NamedTextColor.BLUE;
955
956
// Using hex colors
957
TextColor purple = TextColor.fromHexString("#800080");
958
TextColor orange = TextColor.color(255, 165, 0);
959
960
// Color interpolation
961
TextColor gradient = TextColor.lerp(0.5f, red, blue); // 50% between red and blue
962
```
963
964
### Style Composition
965
966
```java
967
// Building complex styles
968
Style errorStyle = Style.style()
969
.color(NamedTextColor.RED)
970
.decorate(TextDecoration.BOLD)
971
.hoverEvent(HoverEvent.showText(Component.text("Error details here")))
972
.build();
973
974
// Reusable style components
975
Style linkStyle = Style.style(NamedTextColor.BLUE, TextDecoration.UNDERLINED);
976
Style importantStyle = Style.style(NamedTextColor.YELLOW, TextDecoration.BOLD);
977
978
// Style merging
979
Style combinedStyle = linkStyle.merge(importantStyle);
980
```
981
982
### Conditional Styling
983
984
```java
985
// Apply styling based on conditions
986
Component message = Component.text(content)
987
.color(isError ? NamedTextColor.RED : NamedTextColor.GREEN)
988
.decorateIf(isImportant, TextDecoration.BOLD);
989
990
// Style inheritance patterns
991
Style baseStyle = Style.style(NamedTextColor.WHITE);
992
Style warningStyle = baseStyle.color(NamedTextColor.YELLOW);
993
Style errorStyle = baseStyle.color(NamedTextColor.RED).decorate(TextDecoration.BOLD);
994
```