BBCode dans RichTextLabel¶

Introduction¶

Les nœuds Label sont parfaits pour afficher du texte basique, mais ils ont des limites. Si vous voulez changer la couleur du texte, ou son alignement, ce changement affecte tout le texte du nœud Label. Vous ne pouvez pas avoir une seule partie du texte en une seule couleur, ou une seule partie du texte centrée. Pour contourner cette limitation, vous utiliserez un RichTextLabel.

RichTextLabel permet l'affichage de balises de texte complexes dans un Control. Il possède une API intégrée pour générer le balisage, mais peut également analyser un BBCode.

Notez que les balises BBCode peuvent également être utilisées, dans une certaine mesure, dans XML source of the class reference.

Utilisation de BBCode¶

Pour un texte formaté uniformément, vous pouvez écrire dans la propriété "Text", mais si vous voulez utiliser le balisage BBCode, vous devez utiliser la propriété "Text" dans la section "Bb Code" à la place (bbcode_text). L'écriture dans cette propriété déclenchera l'analyse de votre balisage pour formater le texte comme demandé. Avant que cela n'arrive, vous devez cocher la case "Enabled" dans la section "Bb Code" (bbcode_enabled).

Par exemple, BBCode [color=blue]blue[/color] rendrait le mot "blue" avec une couleur bleue.

Vous remarquerez qu'après avoir écrit dans la propriété "Text" du BBCode, la propriété "Text" normale a maintenant le texte sans le BBCode. Bien que la propriété de texte soit mise à jour par la propriété BBCode, vous ne pouvez pas modifier la propriété de texte ou vous perdrez le balisage BBCode. Toutes les modifications du texte doivent être effectuées dans le paramètre BBCode.

Note

Pour que les balises BBCode telles que [b] (gras) ou [i] (italique) fonctionnent, vous devez d'abord configurer des polices personnalisées pour le nœud RichTextLabel.

Il n'y a pas encore de balises BBCode pour contrôler le centrage vertical du texte.

Référence¶

Commande	Balise	Description
gras	`[b]{texte}[/b]`	Met le {texte} en gras.
italique	`[i]{texte}[/i]`	Met le {texte} italique.
souligné	`[u]{texte}[/u]`	Met le {texte} en souligné.
barré	`[s]{texte}[/s]`	Barre le {texte}.
code	`[code]{texte}[/code]`	Fait utiliser la police du code (qui est généralement monospace) pour le {texte}.
centré	`[center]{texte}[/center]`	Centre le {texte} horizontalement.
droite	`[right]{texte}[/right]`	Aligne le {texte} horizontalement à droite.
remplir	`[fill]{texte}[/fill]`	Remplit la largeur du RichTextLabel avec le {texte}.
indenter	`[indent]{texte}[/indent]`	Augmente le niveau d’indentation du {texte}.
url	`[url]{url}[/url]`	Affiche {url} en tant que tel, le souligne et le rend cliquable. Doit être géré avec le signal "meta_clicked" pour avoir un effet. Voir Gestion des clics de la balise [url].
url (ref)	`[url=<url>]{texte}[/url]`	Rend la référence {text} <url> (soulignée et cliquable). Doit être géré avec le signal "meta_clicked" pour avoir un effet. Voir Gestion des clics de la balise [url].
image	`[img]{chemin}[/img]`	Insère l’image ayant {chemin} pour chemin de ressource.
image redimensionnée	`[img=<width>]{path}[/img]`	Insérer l'image à la ressource {path} en utilisant <width> (conserve le ratio).
image redimensionnée	`[img=<width>x<height>]{path}[/img]`	Insère l'image à la ressource {path} en utilisant <width>×<height>.
police	`[font=<chemin>]{texte}[/font]`	Utilise une police personnalisée située à un <chemin> de ressource, pour le {texte}.
couleur	`[color=<code/nom>]{texte}[/color]`	Change la couleur du {texte} ; utilise un nom ou le format #, tel que `#ff00ff`.
table	`[table=<number>]{cells}[/table]`	Crée une table avec un <nombre> de colonnes.
cell	`[cell]{text}[/cell]`	Ajoute des cellules avec le {texte} à la table.

Noms de couleurs prédéfinies¶

Liste de noms de couleurs validespour le tag [color=<nom>] :

aqua
black
blue
fuchsia
gray
green
lime
maroon
navy
purple
red
silver
teal
blanc
yellow

Codes de couleur héxadécimaux¶

Pour les couleurs RVB opaques, tout code hexadécimal valide à 6 chiffres est pris en charge, par exemple [color=#ffffff]white[/color]. Les codes couleur RVB courts tels que #6f2 (équivalent à #66ff22) sont également pris en charge.

Pour les couleurs RVB transparentes, tout code hexadécimal à 8 chiffres peut être utilisé, par exemple [color=#88ffffff]translucent white[/color]. Dans ce cas, notez que le canal alpha est le premier composant du code couleur, et non le dernier. Les codes couleur RGBA courts tels que #86f2 (équivalent à #8866ff22) sont également pris en charge.

Gestion des clics de la balise `[url]`¶

Par défaut, les balises [url] ne font rien lorsqu'on clique dessus. Ceci afin de permettre une utilisation flexible des balises [url] plutôt que de les limiter à l'ouverture des URL dans un navigateur Web.

Pour gérer les balises [url] cliquées, connectez le signal meta_clicked du nœud RichTextLabel à une fonction de script.

Par exemple, la méthode suivante peut être connectée à meta_clicked pour ouvrir les URL cliquées à l'aide du navigateur web par défaut de l'utilisateur :

# This assumes RichTextLabel's `meta_clicked` signal was connected to
# the function below using the signal connection dialog.
func _richtextlabel_on_meta_clicked(meta):
    # `meta` is not guaranteed to be a String, so convert it to a String
    # to avoid script errors at run-time.
    OS.shell_open(str(meta))

Pour des cas d'utilisation plus avancés, il est également possible de stocker JSON dans une option de balise [url] et de l'analyser dans la fonction qui gère le signal meta_clicked. Par exemple : [url={"example": "value"}]JSON[/url]

Décalage vertical de l'image¶

Vous utilisez une police personnalisée pour votre image afin de l'aligner verticalement.

Créer une ressource BitmapFont
Définissez cette police bitmap avec une valeur positive pour la propriété ascent, c'est votre décalage de hauteur
Définir la balise BBCode de cette façon : [font=<font-path>][img]{image-path}[/img][/font]

Effets d'animation¶

Le BBCode peut également être utilisé pour créer différents effets d'animation de texte. Cinq effets personnalisables sont fournis dès le départ, et vous pouvez facilement créer les vôtres.

Vague¶

Wave fait monter et descendre le texte. Son format de balise est [wave amp=50 freq=2][/wave]. amp contrôle le niveau de l'effet, et freq contrôle la vitesse à laquelle le texte monte et descend.

Tornade¶

Tornade fait bouger le texte en cercle. Son format de balise est [tornado radius=5 freq=2][/tornado]. radius est le rayon du cercle qui contrôle le décalage, freq est la vitesse à laquelle le texte se déplace en cercle.

Tremblement¶

Le tremblement fait trembler le texte. Son format de balise est [shake rate=5 level=10][/shake]. rate contrôle la vitesse à laquelle le texte s'agite, level contrôle la distance entre le texte et l'origine.

Fondu¶

Fondu crée un effet de fondu sur le texte qui n'est pas animé. Son format de balise est [fade start=4 length=14][/fade]. start contrôle la position de départ du fondu par rapport à l'endroit où la commande de fondu est insérée, length contrôle le nombre de caractères que le fondu doit contenir.

Arc-en-ciel¶

Arc-en-ciel donne au texte une couleur arc-en-ciel qui change au fil du temps. Son format de balise est [rainbow freq=0.2 sat=10 val=20][/rainbow]. freq est le nombre de cycles complets de l'arc-en-ciel par seconde, sat est la saturation de l'arc-en-ciel, val est la valeur de l'arc-en-ciel.

Balises BBCode et effets de texte personnalisés¶

Vous pouvez étendre le type de ressource RichTextEffect pour créer vos propres balises BBCode personnalisées. Vous commencez par étendre le type de ressource RichTextEffect. Ajoutez le préfixe tool à votre fichier GDScript si vous souhaitez que ces effets personnalisés soient exécutés dans l'éditeur lui-même. Le RichTextLabel n'a pas besoin d'avoir un script attaché, ni d'être exécuté en mode tool. Le nouvel effet sera activable dans l'inspecteur via la propriété Custom Effects.

Avertissement

Si l'effet personnalisé n'est pas ajouté dans la propriété Custom Effects du RichTextLabel, aucun effet ne sera visible et la balise d'origine sera laissée telle quelle.

Il n'y a qu'une seule fonction que vous devez étendre : _processus_custom_fx(char_fx). En option, vous pouvez également fournir un identifiant BBCode personnalisé en ajoutant simplement un nom de membre bbcode. Le code vérifiera automatiquement la propriété bbcode ou utilisera le nom du fichier pour déterminer ce que doit être la balise BBCode.

`_process_custom_fx`¶

C'est là que la logique de chaque effet prend place et est appelée une fois par caractère pendant la phase de dessin du rendu du texte. Ceci passe dans un objet CharFXTransform, qui contient quelques variables pour contrôler comment le caractère associé est rendu :

identity indique quel effet personnalisé est traité. Vous devriez utiliser cela pour le contrôle de flux de code.
relative_index vous dit où vous vous trouvez dans un bloc d'effet personnalisé donné par un index.
absolute_index vous dit où vous êtes dans le texte entier par un index.
elapsed_time est la durée totale d'exécution de l'effet texte.
visible vous dira si le caractère est visible ou non et vous permettra également de cacher une partie donnée du texte.
offset un décalage de position par rapport à l'endroit où le caractère donné devrait être rendu dans des circonstances normales.
color est la couleur d'un caractère donné.
Enfin, env est un Dictionary des paramètres assignés à un effet personnalisé donné. Vous pouvez utiliser get() avec une valeur par défaut optionnelle pour récupérer chaque paramètre, si spécifié par l'utilisateur. Par exemple, [custom_fx spread=0.5 color=#FFFF00]test[/custom_fx] aurait un float spread et des paramètres de couleur color dans son dictionnaire env. Voir ci-dessous pour d'autres exemples d'utilisation.

La dernière chose à noter à propos de cette fonction est qu'il est nécessaire de retourner une valeur booléenne true pour vérifier que l'effet s'est correctement déroulé. De cette façon, s'il y a un problème avec le rendu d'un caractère donné, il ne rendra pas d'effets personnalisés jusqu'à ce que l'utilisateur corrige l'erreur survenue dans sa logique d'effets personnalisés.

Voici quelques exemples d'effets personnalisés :

Fantôme¶

tool
extends RichTextEffect
class_name RichTextGhost

# Syntax: [ghost freq=5.0 span=10.0][/ghost]

# Define the tag name.
var bbcode = "ghost"

func _process_custom_fx(char_fx):
    # Get parameters, or use the provided default value if missing.
    var speed = char_fx.env.get("freq", 5.0)
    var span = char_fx.env.get("span", 10.0)

    var alpha = sin(char_fx.elapsed_time * speed + (char_fx.absolute_index / span)) * 0.5 + 0.5
    char_fx.color.a = alpha
    return true

Pulsation¶

tool
extends RichTextEffect
class_name RichTextPulse

# Syntax: [pulse color=#00FFAA height=0.0 freq=2.0][/pulse]

# Define the tag name.
var bbcode = "pulse"

func _process_custom_fx(char_fx):
    # Get parameters, or use the provided default value if missing.
    var color = char_fx.env.get("color", char_fx.color)
    var height = char_fx.env.get("height", 0.0)
    var freq = char_fx.env.get("freq", 2.0)

    var sined_time = (sin(char_fx.elapsed_time * freq) + 1.0) / 2.0
    var y_off = sined_time * height
    color.a = 1.0
    char_fx.color = char_fx.color.linear_interpolate(color, sined_time)
    char_fx.offset = Vector2(0, -1) * y_off
    return true

Matrice¶

tool
extends RichTextEffect
class_name RichTextMatrix

# Syntax: [matrix clean=2.0 dirty=1.0 span=50][/matrix]

# Define the tag name.
var bbcode = "matrix"

func _process_custom_fx(char_fx):
    # Get parameters, or use the provided default value if missing.
    var clear_time = char_fx.env.get("clean", 2.0)
    var dirty_time = char_fx.env.get("dirty", 1.0)
    var text_span = char_fx.env.get("span", 50)

    var value = char_fx.character

    var matrix_time = fmod(char_fx.elapsed_time + (char_fx.absolute_index / float(text_span)), \
                           clear_time + dirty_time)

    matrix_time = 0.0 if matrix_time < clear_time else \
                  (matrix_time - clear_time) / dirty_time

    if value >= 65 && value < 126 && matrix_time > 0.0:
        value -= 65
        value = value + int(1 * matrix_time * (126 - 65))
        value %= (126 - 65)
        value += 65
    char_fx.character = value
    return true

Ceci ajoutera quelques nouvelles commandes BBCode, qui peuvent être utilisées de cette manière :

[center][ghost]This is a custom [matrix]effect[/matrix][/ghost] made in
[pulse freq=5.0 height=2.0][pulse color=#00FFAA freq=2.0]GDScript[/pulse][/pulse].[/center]