ftxui / dom

Table of Contents

• texto
• vtext
• párrafo
• borde
• ventana
• separador
• medidor
• gráfico
• Colores
  • Paleta16
  • Paleta256
  • ColorVerdadero
• DegradadoLineal
• Estilo
• Diseño
• Tabla
• Lienzo

Este módulo define un conjunto jerárquico de ftxui::Element. Un elemento gestiona el diseño y puede responder a los cambios de dimensión del terminal. Observe el siguiente ejemplo donde este módulo se utiliza para crear un diseño simple con una serie de operadores:

La sección Example proporciona una colección de ejemplos.

Ejemplo:

namespace ftxui {
    ...
 
// Definir el documento
Element document = vbox({
  text("La ventana") | bold | color(Color::Blue),
  gauge(0.5)
  text("El pie de página")
});
 
// Añadir un borde, llamando a la función decoradora `ftxui::border`.
document = border(document);
 
// Añadir otro borde, usando el operador pipe.
document = document | border.
 
// Añadir otro borde, usando el operador |=.
document |= border
 
...
}

Lista de elementos

La lista de todos los elementos está incluida y se puede acceder a ella incluyendo el archivo de cabecera correspondiente:

#include <ftxui/dom/elements.hpp>

// Copyright 2020 Arthur Sonzogni. Todos los derechos reservados.
// El uso de este código fuente se rige por la licencia MIT que se puede encontrar en
// el archivo 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 es una enumeración que representa los diferentes estilos
/// de bordes que se pueden aplicar a los elementos en la interfaz de usuario de la terminal.
///
/// BorderStyle es una enumeración que representa los diferentes estilos de
/// bordes que se pueden aplicar a los elementos en la interfaz de usuario de la terminal.
/// Se utiliza para definir la apariencia visual de los bordes alrededor de los elementos,
/// como ventanas, marcos o separadores.
/// @ingroup dom
enum BorderStyle {
  LIGHT,
  DASHED,
  HEAVY,
  DOUBLE,
  ROUNDED,
  EMPTY,
};
 
// Encadenar elementos en el decorador juntos.
// Por ejemplo, las siguientes líneas son equivalentes:
// -> text("ftxui") | bold | underlined
// -> underlined(bold(text("FTXUI")))
Element operator|(Element, Decorator);
Element& operator|=(Element&, Decorator);
Elements operator|(Elements, Decorator);
Decorator operator|(Decorator, Decorator);
 
// --- Elemento de Interfaz ---
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&)>);
 
// -- Decorador ---
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);
 
// --- Diseño ---
// Conjunto de elementos horizontales, verticales o apilados.
Element hbox(Elements);
Element vbox(Elements);
Element dbox(Elements);
Element flexbox(Elements, FlexboxConfig config = FlexboxConfig());
Element gridbox(std::vector<Elements> lines);
 
Element hflow(Elements);  // Helper: default flexbox with row direction.
Element vflow(Elements);  // Helper: default flexbox with column direction.
 
// -- Flexibilidad ---
// Define cómo compartir el espacio restante cuando no todo se utiliza dentro de un
// contenedor.
Element flex(Element);         // Expandir/Minimizar si es posible/necesario.
Element flex_grow(Element);    // Expandir elemento si es posible.
Element flex_shrink(Element);  // Minimizar elemento si es necesario.
 
Element xflex(Element);         // Expandir/Minimizar si es posible/necesario en el eje X.
Element xflex_grow(Element);    // Expandir elemento si es posible en el eje X.
Element xflex_shrink(Element);  // Minimizar elemento si es necesario en el eje X.
 
Element yflex(Element);         // Expandir/Minimizar si es posible/necesario en el eje Y.
Element yflex_grow(Element);    // Expandir elemento si es posible en el eje Y.
Element yflex_shrink(Element);  // Minimizar elemento si es necesario en el eje Y.
 
Element notflex(Element);  // Restablecer el atributo flex.
Element filler();          // Un elemento expandible en blanco.
 
// -- Anulación de tamaño;
enum WidthOrHeight { WIDTH, HEIGHT };
enum Constraint { LESS_THAN, EQUAL, GREATER_THAN };
Decorator size(WidthOrHeight, Constraint, int value);
 
// --- Marco ---
// Un marco es un área desplazable. El área interna es potencialmente más grande que
// la externa. El área interna se desplaza para hacer visible el
// elemento enfocado.
Element frame(Element);
Element xframe(Element);
Element yframe(Element);
Element focus(Element);
Element select(Element e);  // Obsoleto - Alias para focus.
 
// --- Cursor ---
// Son similares a `focus`, pero también cambian la forma del cursor.
Element focusCursorBlock(Element);
Element focusCursorBlockBlinking(Element);
Element focusCursorBar(Element);
Element focusCursorBarBlinking(Element);
Element focusCursorUnderline(Element);
Element focusCursorUnderlineBlinking(Element);
 
// --- Varios ---
Element vscroll_indicator(Element);
Element hscroll_indicator(Element);
Decorator reflect(Box& box);
// Antes de dibujar el |element|, borra el píxel de abajo. Esto es útil en
// combinación con dbox.
Element clear_under(Element element);
 
// --- Utilidad --------------------------------------------------------------------
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
 
// Hace que el contenedor pueda tomar cualquier número de hijos como entrada.
#include "ftxui/dom/take_any_args.hpp"
 
// Incluir definiciones antiguas usando wstring.
#include "ftxui/dom/deprecated.hpp"
#endif  // FTXUI_DOM_ELEMENTS_HPP

texto

El widget más simple. Muestra un texto.

text("Soy un trozo de texto");

Soy un trozo de texto.

vtext

Código:

vtext("HELLO");

Salida del terminal:

H
E
L
L
O

párrafo

Similar a ftxui::text, pero las palabras individuales se ajustan a lo largo de múltiples líneas, dependiendo del ancho de su contenedor.

Código de ejemplo:

paragraph("Un texto muy largo")

Para un ejemplo más detallado, consulte ejemplo detallado. Párrafo también incluye una serie de otras variantes como se muestra a continuación:

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);
}

borde

Añade un borde alrededor de un elemento.

Código:

border(text("El elemento"))

Salida del terminal:

┌───────────┐
│El elemento│
└───────────┘

‍[!nota] Puedes lograr el mismo comportamiento usando el operador pipe.

Código:

text("El elemento") | border

El borde también viene en una variedad de estilos como se muestra a continuación:

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);
}

ventana

Una ftxui::window es un ftxui::border, pero con una cabecera adicional. Para añadir una ventana alrededor de un elemento, envuélvalo y especifique una cadena como cabecera. Código:

window("La ventana", text("El elemento"))

Salida del terminal:

┌La ventana─┐
│El elemento│
└───────────┘

separador

Muestra una línea vertical/horizontal para dividir visualmente el contenido de un contenedor en dos.

Código:

border(
  hbox({
    text("Izquierda"), 
    separator(),
    text("Derecha")
  })
)

Salida del terminal:

┌────┬─────┐
│izquierda│derecha│
└────┴─────┘

Los separadores vienen en una variedad de estilos como se muestra a continuación:

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);
}

medidor

Este es un elemento visual que representa una proporción de progreso.

Código:

border(gauge(0.5))

Salida del terminal:

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

Los medidores pueden mostrarse en muchas orientaciones como se muestra a continuación:

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);
}

gráfico

See:

Element graph(GraphFunction);

Colores

La mayoría de las consolas de terminal pueden mostrar texto y fondos de colores. FTXUI soporta todas las paletas de colores:

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

Galería de colores:

Paleta16

En la mayoría de los terminales se admiten los siguientes colores:

• Default
• Black
• GrayDark
• GrayLight
• White
• Blue
• BlueLight
• Cyan
• CyanLight
• Green
• GreenLight
• Magenta
• MagentaLight
• Red
• RedLight
• Yellow
• YellowLight

Ejemplo de uso de los colores anteriores usando el operador pipe:

text("Primer plano azul") | color(Color::Blue);
text("Fondo azul") | bgcolor(Color::Blue);
text("Negro sobre blanco") | color(Color::Black) | bgcolor(Color::White);

Paleta256

En terminales que soportan 256 colores.

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

ColorVerdadero

En terminales que soportan TrueColor, puedes usar directamente el espacio de color RGB de 24 bits:

Usa los constructores a continuación para especificar los valores RGB o HSV para tu color:

Hay dos constructores:

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

DegradadoLineal

FTXUI soporta degradado lineal. Ya sea en primer plano o en segundo plano.

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

Un ftxui::LinearGradient se define por un ángulo en grados y una lista de paradas de color.

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

También puedes usar constructores simplificados:

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

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

Ver demostración.

Estilo

Además de texto y fondos de colores. Muchos terminales soportan efectos de texto como: 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);

Example

Para usar estos efectos, simplemente envuelve tus elementos con el efecto deseado:

underlined(bold(text("Este texto está en negrita y subrayado")))

Alternativamente, usa el operador pipe para encadenarlo en tu elemento:

text("Este texto está en negrita") | bold | underlined

Diseño

Permite que los elementos se organicen de las siguientes maneras:

• Horizontalmente con ftxui::hbox
• Verticalmente con ftxui::vbox
• Dentro de una cuadrícula con ftxui::gridbox
• Envuelto en una dirección usando ftxui::flexbox.

Ejemplo usando ftxui::hbox, ftxui::vbox y ftxui::filler.

Ejemplo usando ftxui::gridbox:

Ejemplo usando flexbox:

Consulta este ejemplo y la demostración asociada.

El elemento también puede volverse flexible usando el decorador ftxui::flex.

Código:

hbox({
  text("izquierda") | border ,
  text("medio") | border | flex,
  text("derecha") | border,
});

Salida del terminal: bash ┌────┐┌─────────────────────────────────────────────────────┐┌─────┐ │izquierda││medio ││derecha│ └────┘└─────────────────────────────────────────────────────┘└─────┘

Código:

hbox({
  text("izquierda") | border ,
  text("medio") | border | flex,
  text("derecha") | border | flex,
});

Salida del terminal:

┌────┐┌───────────────────────────────┐┌───────────────────────────────┐
│izquierda││medio                          ││derecha                        │
└────┘└───────────────────────────────┘└───────────────────────────────┘

Tabla

Permite un formato sencillo de datos en una tabla visual ordenada.

Ejemplo de código:

Lienzo

Ver la API <ftxui/dom/canvas.hpp>

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

El dibujo se puede realizar en un ftxui::Canvas, usando caracteres braille, de bloque o simples:

Ejemplo simple:

Ejemplo complejo: