Mise en Forme du code & Ancien Format

Text peut être représenté en utilisant un caractère spéciale indiquant un formatage de certains genres suivi d’un caractère unique indiquant le formatage spécifique à utiliser. Dans la SpongeAPI, deux caractères différents sont supportés par défaut : l’esperluette (&) et le caractère de section (§).

Ces deux mécanismes de formatage utilisent les codes trouvés sur le Wiki Minecraft. Il est important de relever que le Wiki Minecraft affiche seulement l’utilisation avec le caractère de section (§), mais les mêmes codes fonctionnent avec l’esperluette (&) également.

Avertissement

La sérialisation de Text à l’aide de tout type de code de formatage est limitée à ce qui représente seulement quelques-unes des fonctionnalités d’un Text, à savoir la mise en forme. Il ne peut pas représenter quelconque type d’actions de clic ou de survol. Si la brièveté n’est pas un problème (comme dans le chat de Minecraft), il est recommandé d’utiliser soit le Format TextXML ou le Format JSON.

Mise en Forme avec l’Esperluette

Par défaut, Sponge supporte le caractère de formatage & (esperluette). Utiliser le format de l’esperluette autorise une entrée utilisateur du formatage du texte plus simple et est utile dans les cas où la brièveté n’est pas nécessaire, comme dans la console de chat de Minecraft.

Pour utiliser ce formatage, vous pouvez accéder à son TextSerializer correspondant avec TextSerializers#FORMATTING_CODE. Depuis là, vous pouvez utiliser les méthodes serialize ou deserialize comme d’habitude :

import org.spongepowered.api.text.Text;
import org.spongepowered.api.text.format.TextColors;
import org.spongepowered.api.text.format.TextStyles;
import org.spongepowered.api.text.serializer.TextSerializers;

Text text = Text.of(TextColors.RED, TextStyles.UNDERLINE, "Hello World!");
String ampersandFormattedText = TextSerializers.FORMATTING_CODE.serialize(text);

Par exemple, le texte « Hello World! », formaté avec la couleur rouge et en souligné aurait la représentation suivante avec la mise en forme avec l’esperluette : &c&nHello World!

Ancienne Mise en Forme

L’ancienne représentation du texte est le format largement utilisé dans les anciennes versions de Minecraft, représentée par le caractère de section (§). Sponge fournit la sérialisation et la désérialisation en utilisant l’ancien format seulement pour la compatibilité. Il ne doit pas être utilisé sauf si c’est absolument nécessaire. Plutôt, il est recommandé d’utiliser le formatage avec l’esperluette, comme détaillé ci-dessus. L’ancienne mise en forme possède quelques limitations que la mise en forme avec l’esperluette n’a pas, la plus évidente parmi elles est que les utilisateurs ne peuvent pas facilement taper le caractère de section dans le chat.

Pour utiliser ce formatage, vous pouvez accéder à son TextSerializer correspondant avec TextSerializers#LEGACY_FORMATTING_CODE. Depuis là, vous pouvez utiliser les méthodes serialize ou deserialize comme d’habitude :

Text text = Text.of(TextColors.RED, TextStyles.UNDERLINE, "Hello World!");
String legacyText = TextSerializers.LEGACY_FORMATTING_CODE.serialize(text);

Par exemple, le texte « Hello World! », formaté avec la couleur rouge et en souligné aurait la représentation suivante avec l’ancienne mise en forme : §c§nHello World!

Astuce

Bien que son utilisation n’est pas recommandée, vous pouvez récupérer un FormattingCodeTextSerializer en utilisant n’importe quel caractère de mise en forme dont vous avez besoin en appelant TextSerializers#formattingCode(char), en passant un char comme le seul argument.