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).

../../_images/bbcodeText.png

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

../../_images/bbcodeDemo.png

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.

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] Passe le {texte} en monospace.
centré [center]{texte}[/center] Centre le {texte}.
droite [right]{texte}[/right] Aligne le {texte} à droite.
remplir [fill]{texte}[/fill] Remplit la largeur avec le {texte}.
indenter [indent]{texte}[/indent] Augmente le niveau d’indentation du {texte}.
url [url]{url}[/url] Affiche l’{url} en tant que telle.
url (ref) [url=<url>]{texte}[/url] Fait pointer le {texte} vers l’<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érer 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 d’un {texte}, utilise le format hexadécimal tel que #ff00ff ou un nom de couleur.
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 à 6 digits valide est pris en charge, par exemple [color=#ffffff]white[/color].

Pour les couleurs RVB transparentes, tout code hexadécimal à 8 digits peut être utilisé, par exemple [color=#88ffffffff]blanc translucide[/color]. Dans ce cas, notez que le canal alpha est la première composante du code couleur, et non la dernière.

Décalage vertical de l'image

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

  1. Créer une ressource BitmapFont
  2. Définissez cette police bitmap avec une valeur positive pour la propriété ascent, c'est votre décalage de hauteur
  3. 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

../../_images/wave.png

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

../../_images/tornado.png

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

../../_images/shake.png

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

../../_images/fade.png

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

../../_images/rainbow.png

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.

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

# 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

# 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

# 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]