Composants et événements

Vos propres éléments

Très rapidement, vous allez vouloir créer vos propres éléments : pages spécifiques, contrôles…

Reprenons l’exemple le plus simple et étoffons-le.

// import des éléments nécessaires
import { Application, Button, VBox } from 'x4js';

// création de l'application
const app = new Application( );

// création de la vue principale
const frame = new VBox( {
  cls: "fit",    // la classe fit remplit le conteneur parent
  content: [
    new Button( { label: "Hello world" } ),
  ]
});

// on la déclare comme vue principale de l'application
app.setMainView( frame );

Ici, la vue principale est un objet de type VBox : les enfants sont placés les uns sous les autres. Dans la majorité des cas, ce type de construction ne suffit pas : on a besoin de répondre à des événements, et le contenu lui-même gagne à être porté par l’objet. Voici comment procéder :

import { Application, BoxProps, Button, VBox } from 'x4js';

// cette fois, on déclare une classe qui étend VBox
class MainView extends VBox {
  constructor( props: BoxProps ) {
    super( props );

    this.addClass( "fit" );

    this.setContent( [
      new Button( { label: "Hello, I'm a custom class" } ),
    ]);
  }
}

const app = new Application( );
app.setMainView( new MainView( { } ) );

Nous avons créé une classe MainView qui dérive de VBox et qui implémente son propre constructeur.

Plusieurs remarques

1. Le constructeur d’un composant accepte un unique paramètre qui définit ses propriétés. Passez-le tel quel à super( props ) : le composant le garde dans this.props. Nous verrons plus bas comment le typer pour que l’aide à la saisie propose les bonnes propriétés.
2. Une classe CSS est associée automatiquement à chaque classe de composant, d’après son nom en minuscules. Ici, l’élément porte mainview, en plus de x4vbox et x4box héritées de ses classes de base.
3. Les composants fournis portent le préfixe x4 (x4button, x4label…), ce qui évite les conflits avec d’autres bibliothèques. Vous pouvez donner un préfixe aux vôtres avec le décorateur @class_ns( "app" ).

Gestion des événements

Nous allons maintenant capter le clic sur le bouton. Pour cela, on dit au bouton qui appeler :

class MainView extends VBox {
  constructor( props: BoxProps ) {
    super( props );

    this.addClass( "fit" );

    this.setContent( [
      new Button( {
        label: "Hello, I'm a custom class",
        click: ( ) => this.onClick( ),  // appelle ma méthode onClick
      }),
    ]);
  }

  // appelée par le bouton
  private onClick( ) {
    alert( "I have been clicked" );
  }
}

Note

Le bouton émet un événement, il ne sait jamais pour qui. C’est celui qui a besoin de cet événement qui le lui dit. La mécanique est la même dans tout x4js. En poussant un peu (ce serait une mauvaise idée), on pourrait gérer une application complète directement dans la vue principale.

En suivant ce principe, on crée des « briques » logicielles : connexion, fiche utilisateur, listes, dialogues…

S’abonner après coup

Passer le gestionnaire dans les propriétés est la forme courte. On peut aussi s’abonner plus tard, avec on :

const save = new Button( { label: "Save" } );

const sub = save.on( "click", ( ) => console.log( "saved" ) );

// pour se désabonner
sub.off( );

Émettre ses propres événements

Un composant d’application déclare trois choses : ses propriétés, ses événements, et la forme de chaque événement.

import { Button, ComponentEvent, ComponentEvents, ComponentProps, EventCallback, HBox, Label } from 'x4js';

// ce que transporte l'événement
interface EvRename extends ComponentEvent {
  name: string;
}

// les événements du composant
interface TitleBarEvents extends ComponentEvents {
  rename: EvRename;
}

// ses propriétés, dont le gestionnaire en forme courte
interface TitleBarProps extends ComponentProps {
  title: string;
  rename?: EventCallback<EvRename>;
}

class TitleBar extends HBox<TitleBarProps,TitleBarEvents> {
  declare protected refs: { title: Label };

  constructor( props: TitleBarProps ) {
    super( props );

    // branche les gestionnaires reçus dans les propriétés
    this.mapPropEvents( props, "rename" );

    this.setContent( [
      this.refs.title = new Label( { flex: 1, text: props.title } ),
      new Button( { label: "Rename", click: ( ) => this.rename( "New title" ) } ),
    ]);
  }

  private rename( name: string ) {
    this.refs.title.setText( name );
    this.fire( "rename", { name } );
  }
}

Il s’utilise alors comme les composants fournis, et l’éditeur connaît ses propriétés et ses événements :

const bar = new TitleBar( {
  title: "Untitled",
  rename: ( ev ) => console.log( ev.name ),
});

Retrouver ses enfants : refs

Dans l’exemple, le libellé est rangé dans this.refs.title au moment où on construit le contenu. refs est un répertoire typé des enfants auxquels on doit accéder plus tard. On déclare sa forme dans la classe, et l’affectation s’écrit directement dans le tableau de contenu.

Un enfant auquel on n’a pas besoin de revenir n’a pas à y figurer.

Et ensuite

• État et messages : partager un état et diffuser des messages dans toute l’application.
• Contrôles standard : ce que x4js fournit déjà.