ftxui / dom

Table des matières

• text
• vtext
• paragraph 
• border
• window
• separator
• gauge
• graph
• Couleurs
  • Palette16 
  • Palette256 
  • TrueColor
• LinearGradient
• Style
• Layout
• Table
• Canvas

Ce module définit un ensemble hiérarchique de ftxui::Element. Un élément gère la disposition et peut être réactif aux changements de dimensions du terminal. Considérez l'exemple suivant où ce module est utilisé pour créer une disposition simple avec un certain nombre d'opérateurs :

La section Example fournit une collection d'exemples.

Exemple :

namespace ftxui {
    ...
 
// Définir le document
Element document = vbox({
  text("La fenêtre") | bold | color(Color::Blue),
  gauge(0.5)
  text("Le pied de page")
});
 
// Ajouter une bordure, en appelant la fonction décoratrice `ftxui::border`.
document = border(document);
 
// Ajouter une autre bordure, en utilisant l'opérateur pipe.
document = document | border.
 
// Ajouter une autre bordure, en utilisant l'opérateur |=.
document |= border
 
...
}

Liste des éléments

La liste de tous les éléments est incluse et peut être accédée en incluant le fichier d'en-tête correspondant :

#include <ftxui/dom/elements.hpp>

// Copyright 2020 Arthur Sonzogni. Tous droits réservés.
// L'utilisation de ce code source est régie par la licence MIT que l'on peut trouver dans
// le fichier LICENSE.
#ifndef FTXUI_DOM_ELEMENTS_HPP
#define FTXUI_DOM_ELEMENTS_HPP
 
#include <functional>
#include <memory>
 
#include "ftxui/dom/canvas.hpp"
#include "ftxui/dom/direction.hpp"
#include "ftxui/dom/flexbox_config.hpp"
#include "ftxui/dom/linear_gradient.hpp"
#include "ftxui/dom/node.hpp"
#include "ftxui/screen/box.hpp"
#include "ftxui/screen/color.hpp"
#include "ftxui/screen/terminal.hpp"
#include "ftxui/util/ref.hpp"
 
namespace ftxui {
class Node;
using Element = std::shared_ptr<Node>;
using Elements = std::vector<Element>;
using Decorator = std::function<Element(Element)>;
using GraphFunction = std::function<std::vector<int>(int, int)>;
 
/// @brief BorderStyle est une énumération qui représente les différents styles
/// de bordures pouvant être appliqués aux éléments de l'interface utilisateur du terminal.
///
/// BorderStyle est une énumération qui représente les différents styles de
/// bordures pouvant être appliqués aux éléments de l'interface utilisateur du terminal.
/// Il est utilisé pour définir l'apparence visuelle des bordures autour des éléments,
/// tels que les fenêtres, les cadres ou les séparateurs.
/// @ingroup dom
enum BorderStyle {
  LIGHT,
  DASHED,
  HEAVY,
  DOUBLE,
  ROUNDED,
  EMPTY,
};
 
// Enchaîner des éléments dans un décorateur.
// Par exemple, les lignes suivantes sont équivalentes :
// -> text("ftxui") | bold | underlined
// -> underlined(bold(text("FTXUI")))Element operator|(Element, Decorator);
Element& operator|=(Element&, Decorator);
Elements operator|(Elements, Decorator);
Decorator operator|(Decorator, Decorator);
 
// --- Composant ---
Element text(std::string text);
Element vtext(std::string text);
Element separator();
Element separatorLight();
Element separatorDashed();
Element separatorHeavy();
Element separatorDouble();
Element separatorEmpty();
Element separatorStyled(BorderStyle);
Element separator(Pixel);
Element separatorCharacter(std::string);
Element separatorHSelector(float left,
                           float right,
                           Color unselected_color,
                           Color selected_color);
Element separatorVSelector(float up,
                           float down,
                           Color unselected_color,
                           Color selected_color);
Element gauge(float progress);
Element gaugeLeft(float progress);
Element gaugeRight(float progress);
Element gaugeUp(float progress);
Element gaugeDown(float progress);
Element gaugeDirection(float progress, Direction direction);
Element border(Element);
Element borderLight(Element);
Element borderDashed(Element);
Element borderHeavy(Element);
Element borderDouble(Element);
Element borderRounded(Element);
Element borderEmpty(Element);
Decorator borderStyled(BorderStyle);
Decorator borderStyled(BorderStyle, Color);
Decorator borderStyled(Color);
Decorator borderWith(const Pixel&);
Element window(Element title, Element content, BorderStyle border = ROUNDED);
Element spinner(int charset_index, size_t image_index);
Element paragraph(const std::string& text);
Element paragraphAlignLeft(const std::string& text);
Element paragraphAlignRight(const std::string& text);
Element paragraphAlignCenter(const std::string& text);
Element paragraphAlignJustify(const std::string& text);
Element graph(GraphFunction);
Element emptyElement();
Element canvas(ConstRef<Canvas>);
Element canvas(int width, int height, std::function<void(Canvas&)>);
Element canvas(std::function<void(Canvas&)>);
 
// -- Décorateur ---
Element bold(Element);
Element dim(Element);
Element italic(Element);
Element inverted(Element);
Element underlined(Element);
Element underlinedDouble(Element);
Element blink(Element);
Element strikethrough(Element);
Decorator color(Color);
Decorator bgcolor(Color);
Decorator color(const LinearGradient&);
Decorator bgcolor(const LinearGradient&);
Element color(Color, Element);
Element bgcolor(Color, Element);
Element color(const LinearGradient&, Element);
Element bgcolor(const LinearGradient&, Element);
Decorator focusPosition(int x, int y);
Decorator focusPositionRelative(float x, float y);
Element automerge(Element child);
Decorator hyperlink(std::string link);
Element hyperlink(std::string link, Element child);
Element selectionStyleReset(Element);
Decorator selectionColor(Color foreground);
Decorator selectionBackgroundColor(Color foreground);
Decorator selectionForegroundColor(Color foreground);
Decorator selectionStyle(std::function<void(Pixel&)> style);
 
// --- Disposition ---
// Horizontal, Vertical ou empilé d'éléments.
Element hbox(Elements);
Element vbox(Elements);
Element dbox(Elements);
Element flexbox(Elements, FlexboxConfig config = FlexboxConfig());
Element gridbox(std::vector<Elements> lines);
 
Element hflow(Elements);  // Aide : flexbox par défaut avec direction de ligne.
Element vflow(Elements);  // Aide : flexbox par défaut avec direction de colonne.
 
// -- Flexibilité ---
// Définit comment partager l'espace restant lorsque tout n'est pas utilisé à l'intérieur d'un
// conteneur.
Element flex(Element);         // Développer/Réduire si possible/nécessaire.
Element flex_grow(Element);    // Développer l'élément si possible.
Element flex_shrink(Element);  // Réduire l'élément si nécessaire.
 
Element xflex(Element);         // Développer/Réduire si possible/nécessaire sur l'axe X.
Element xflex_grow(Element);    // Développer l'élément si possible sur l'axe X.
Element xflex_shrink(Element);  // Réduire l'élément si nécessaire sur l'axe X.
 
Element yflex(Element);         // Développer/Réduire si possible/nécessaire sur l'axe Y.
Element yflex_grow(Element);    // Développer l'élément si possible sur l'axe Y.
Element yflex_shrink(Element);  // Réduire l'élément si nécessaire sur l'axe Y.
 
Element notflex(Element);  // Réinitialiser l'attribut flex.
Element filler();          // Un élément vide extensible.
 
// -- Surcharger la taille ---
enum WidthOrHeight { WIDTH, HEIGHT };
enum Constraint { LESS_THAN, EQUAL, GREATER_THAN };
Decorator size(WidthOrHeight, Constraint, int value);
 
// --- Cadre ---
// Un cadre est une zone défilante. La zone interne est potentiellement plus grande que
// la zone externe. La zone interne est défilée afin de rendre visible l'élément focalisé.
Element frame(Element);
Element xframe(Element);
Element yframe(Element);
Element focus(Element);
Element select(Element e);  // Obsolète - Alias pour focus.
 
// --- Curseur ---
// Ceux-ci sont similaires à `focus`, mais changent également la forme du curseur.
Element focusCursorBlock(Element);
Element focusCursorBlockBlinking(Element);
Element focusCursorBar(Element);
Element focusCursorBarBlinking(Element);
Element focusCursorUnderline(Element);
Element focusCursorUnderlineBlinking(Element);
 
// --- Divers ---
Element vscroll_indicator(Element);
Element hscroll_indicator(Element);
Decorator reflect(Box& box);
// Avant de dessiner l'|element|, effacez le pixel en dessous. Ceci est utile en
// combinaison avec dbox.
Element clear_under(Element element);
 
// --- Utilitaire --------------------------------------------------------------------
Element hcenter(Element);
Element vcenter(Element);
Element center(Element);
Element align_right(Element);
Element nothing(Element element);
 
namespace Dimension {
Dimensions Fit(Element&, bool extend_beyond_screen = false);
}  // namespace Dimension
 
}  // namespace ftxui
 
// Rendre le conteneur capable de prendre n'importe quel nombre d'enfants en entrée.
#include "ftxui/dom/take_any_args.hpp"
 
// Inclure les anciennes définitions utilisant wstring.
#include "ftxui/dom/deprecated.hpp"
#endif  // FTXUI_DOM_ELEMENTS_HPP

text

Le widget le plus simple. Il affiche un texte.

text("Je suis un morceau de texte");

I am a piece of text.

vtext

Identique à ftxui::text, mais affiché verticalement.

Code:

vtext("HELLO");

Terminal output:

H
E
L
L
O

paragraph 

Similaire à ftxui::text, mais les mots individuels sont enveloppés sur plusieurs lignes, en fonction de la largeur de son conteneur.

Exemple de code :

paragraph("Un très long texte")

Pour un exemple plus détaillé, reportez-vous à exemple détaillé. Paragraph inclut également un certain nombre d'autres variantes comme indiqué ci-dessous :

namespace ftxui {
    Element paragraph(std::string text);
    Element paragraphAlignLeft(std::string text);
    Element paragraphAlignRight(std::string text);
    Element paragraphAlignCenter(std::string text);
    Element paragraphAlignJustify(std::string text);
}

border

Ajoute une bordure autour d'un élément.

Code :

border(text("L'élément"))

Sortie terminale :

┌───────────┐
│The element│
└───────────┘

Note

Vous pouvez obtenir le même comportement en utilisant l'opérateur pipe.

Code :

text("L'élément") | border

Border est également disponible dans une variété de styles, comme indiqué ci-dessous :

namespace ftxui {
    Element border(Element);
    Element borderLight(Element);
    Element borderHeavy(Element);
    Element borderDouble(Element);
    Element borderRounded(Element);
    Element borderEmpty(Element);
    Decorator borderStyled(BorderStyle);
    Decorator borderWith(Pixel);
}

window

Une ftxui::window est une ftxui::border, mais avec un en-tête supplémentaire. Pour ajouter une fenêtre autour d'un élément, enveloppez-le et spécifiez une chaîne de caractères comme en-tête. Code :

window("La fenêtre", text("L'élément"))

Sortie terminale :

┌The window─┐
│The element│
└───────────┘

separator

Affiche une ligne verticale/horizontale pour diviser visuellement le contenu d'un conteneur en deux.

Code :

border(
  hbox({
    text("Gauche"), 
    separator(),
    text("Droite")
  })
)

Sortie terminale :

┌────┬─────┐
│left│right│
└────┴─────┘

Les séparateurs sont disponibles dans une variété de styles, comme indiqué ci-dessous :

namespace ftxui {
    Element separator(void);
    Element separatorLight();
    Element separatorHeavy();
    Element separatorDouble();
    Element separatorEmpty();
    Element separatorStyled(BorderStyle);
    Element separator(Pixel);
    Element separatorCharacter(std::string);
    Element separatorHSelector(float left,
                               float right,
                               Color background,
                               Color foreground);
    Element separatorVSelector(float up,
                               float down,
                               Color background,
                               Color foreground);
}

gauge

Ceci est un élément visuel qui représente un ratio de progression.

Code :

border(gauge(0.5))

Sortie terminale :

┌────────────────────────────────────────────────────────────────────────────┐
│██████████████████████████████████████                                      │
└────────────────────────────────────────────────────────────────────────────┘

Les jauges peuvent être affichées dans de nombreuses orientations, comme indiqué ci-dessous :

namespace {
    Element gauge(float ratio);
    Element gaugeLeft(float ratio);
    Element gaugeRight(float ratio);
    Element gaugeUp(float ratio);
    Element gaugeDown(float ratio);
    Element gaugeDirection(float ratio, GaugeDirection);
}

graph

Voir :

Element graph(GraphFunction);

Couleurs

La plupart des consoles de terminal peuvent afficher du texte coloré et des arrière-plans colorés. FTXUI prend en charge toutes les palettes de couleurs :

Decorator color(Color);
Decorator bgcolor(Color);

Galerie de couleurs :

Palette16 

Sur la plupart des terminaux, les couleurs suivantes sont prises en charge :

• Par défaut
• Noir
• GrisFoncé
• GrisClair
• Blanc
• Bleu
• BleuClair
• Cyan
• CyanClair
• Vert
• VertClair
• Magenta
• MagentaClair
• Rouge
• RougeClair
• Jaune
• JauneClair

Exemple d'utilisation des couleurs ci-dessus avec l'opérateur pipe :

text("Premier plan bleu") | color(Color::Blue);
text("Arrière-plan bleu") | bgcolor(Color::Blue);
text("Noir sur blanc") | color(Color::Black) | bgcolor(Color::White);

Palette256 

Sur les terminaux prenant en charge 256 couleurs.

text("RoseVif") | color(Color::HotPink);

TrueColor

Sur les terminaux prenant en charge TrueColor, vous pouvez utiliser directement l'espace colorimétrique RVB 24 bits :

Utilisez les constructeurs ci-dessous pour spécifier les valeurs RVB ou TSV de votre couleur :

Il existe deux constructeurs :

ftxui::Color::RGB(uint8_t red, uint8_t green, uint8_t blue);
ftxui::Color::HSV(uint8_t hue, uint8_t saturation, uint8_t value);

LinearGradient

FTXUI prend en charge le dégradé linéaire. Soit au premier plan, soit à l'arrière-plan.

Decorator color(const LinearGradient&);
Decorator bgcolor(const LinearGradient&);

Un ftxui::LinearGradient est défini par un angle en degrés et une liste de points de couleur.

auto gradient = LinearGradient()
  .Angle(45)
  .AddStop(0.0, Color::Red)
  .AddStop(0.5, Color::Green)
  .AddStop(1.0, Color::Blue);

Vous pouvez également utiliser des constructeurs simplifiés :

LinearGradient(Color::Red, Color::Blue);

LinearGradient(45, Color::Red, Color::Blue);

Voir la démo.

Style

En plus du texte coloré et des arrière-plans colorés. De nombreux terminaux prennent en charge les effets de texte tels que : bold, italic, dim, underlined, inverted, blink.

Element bold(Element);
Element italic(Element);
Element dim(Element);
Element inverted(Element);
Element underlined(Element);
Element underlinedDouble(Element);
Element strikethrough(Element);
Element blink(Element);
Decorator color(Color);
Decorator bgcolor(Color);
Decorator colorgrad(LinearGradient);
Decorator bgcolorgrad(LinearGradient);

Exemple

Pour utiliser ces effets, enveloppez simplement vos éléments avec l'effet désiré :

underlined(bold(text("Ce texte est en gras et souligné")))

Alternativement, utilisez l'opérateur pipe pour le chaîner sur votre élément :

text("Ce texte est en gras") | bold | underlined

Layout

Permet d'organiser les éléments des manières suivantes :

• Horizontalement avec ftxui::hbox
• Verticalement avec ftxui::vbox
• À l'intérieur d'une grille avec ftxui::gridbox
• Enveloppé dans une direction en utilisant le ftxui::flexbox.

Exemple utilisant ftxui::hbox, ftxui::vbox et ftxui::filler.

Exemple utilisant ftxui::gridbox :

Exemple utilisant flexbox :

Consultez cet exemple et la démo associée.

L'élément peut également devenir flexible en utilisant le décorateur ftxui::flex.

Code :

hbox({
  text("gauche") | border ,
  text("milieu") | border | flex,
  text("droite") | border,
});

Sortie terminale :

┌────┐┌─────────────────────────────────────────────────────┐┌─────┐
│left││middle                                               ││right│
└────┘└─────────────────────────────────────────────────────┘└─────┘

Code :

hbox({
  text("gauche") | border ,
  text("milieu") | border | flex,
  text("droite") | border | flex,
});

Sortie terminale :

┌────┐┌───────────────────────────────┐┌───────────────────────────────┐
│left││middle                         ││right                          │
└────┘└───────────────────────────────┘└───────────────────────────────┘

Table

Permet un formatage facile des données sous une forme visuelle de tableau ordonné.

Exemple de code:

Canvas

Voir l'API <ftxui/dom/canvas.hpp>

auto c = Canvas(100, 100);
c.DrawPointLine(10, 10, 80, 10, Color::Red);
auto element = canvas(c);

Le dessin peut être effectué sur un ftxui::Canvas, en utilisant des caractères braille, des blocs ou de simples caractères :

Exemple simple :

Exemple complexe :