Ui

Fonctions utilitaires génériques pour la construction d’interfaces utilisateur Qt et l’affichage console coloré.

Ce module regroupe :

  • des helpers pour créer et configurer rapidement des layouts Qt cohérents (onglets, groupes, formulaires, séparateurs, spinbox, etc.) ;

  • des fonctions de synchronisation de widgets (callbacks) ;

  • des fonctions d’affichage console coloré (erreurs, warnings, succès) ;

  • quelques utilitaires généraux liés à l’IHM.

L’objectif est d’assurer :

  • une ergonomie homogène sur l’ensemble des interfaces ;

  • une réduction du boilerplate Qt ;

  • une meilleure lisibilité et maintenabilité du code UI.

add_setting_row(form: QFormLayout, label: str, widget: QWidget, space: int = 0, margin: int = 0, *, tooltip: str = '')[source]

Ajoute une ligne de paramètre dans un QFormLayout.

Le champ (colonne de droite) est encapsulé dans un QHBoxLayout contenant le widget puis un stretch. Cela évite que le widget s’étire horizontalement jusqu’au bord droit de l’onglet : il conserve sa taille naturelle (sizeHint) et l’espace restant est laissé vide à droite.

Paramètres:

  • form (QFormLayout) – Formulaire cible à modifier (modification in-place via addRow()).

  • label (str) – Texte du label (colonne de gauche).

  • widget (QWidget) – Widget à placer dans la colonne de droite (spinbox, checkbox, combobox, …).

  • space (int) – Valeur (en pixels) utilisée pour l’espacement du layout. Par défaut : 0.

  • margin (int) – Valeur (en pixels) utilisée pour les marges du layout. Par défaut : 0.

  • tooltip (str) – Tooltip à ajouter (si non vide).

init_layout(layout: QLayout, space: int = 5, margin: int = 5)[source]

Configure un layout avec des marges et un espacement uniformes.

Cette fonction applique des marges identiques sur les 4 côtés et un espacement identique entre widgets / sous-layouts.

Paramètres:

  • layout (QLayout) – Layout à configurer (ex: QVBoxLayout, QGridLayout, etc.).

  • space (int) – Valeur (en pixels) utilisée pour l’espacement du layout. Par défaut : COMMON_SPACE.

  • margin (int) – Valeur (en pixels) utilisée pour les marges du layout. Par défaut : COMMON_SPACE.

make_tab(parent: QWidget | None = None, space: int = 5, margin: int = 5) → tuple[QWidget, QVBoxLayout][source]

Crée un onglet prêt à l’emploi (widget conteneur + layout vertical).

L’onglet est représenté par un QWidget et contient un QVBoxLayout configuré avec des marges et un espacement uniformes.

Paramètres:

  • parent (QWidget | None) – Parent Qt du widget onglet (peut-être None si définie plus tard).

  • space (int) – Valeur (en pixels) utilisée pour l’espacement du layout. Par défaut : COMMON_SPACE.

  • margin (int) – Valeur (en pixels) utilisée pour les marges du layout. Par défaut : COMMON_SPACE.

Renvoie:

Un tuple (tab, layout) où tab est le widget de l’onglet et layout son calque.

Type renvoyé:

tuple[QWidget, QVBoxLayout]

make_group(parent: QWidget | None = None, name: str = '', space: int = 5, margin: int = 5) → tuple[QGroupBox, QVBoxLayout][source]

Crée un QGroupBox avec un layout vertical configuré.

Paramètres:

  • parent (QWidget | None) – Parent Qt du group box (peut-être None si définie plus tard).

  • name (str) – Titre affiché dans l’entête du group box.

  • space (int) – Valeur (en pixels) utilisée pour l’espacement du layout. Par défaut : COMMON_SPACE.

  • margin (int) – Valeur (en pixels) utilisée pour les marges du layout. Par défaut : COMMON_SPACE.

Renvoie:

Un tuple (group, layout) où : group est le QGroupBox créé et layout son calque.

Type renvoyé:

tuple[QGroupBox, QVBoxLayout]

make_exclusive_btn_group(labels: list[str], space: int = 5) → tuple[QHBoxLayout, QButtonGroup, dict[str, QPushButton]][source]

Crée un QGroupBox avec un layout vertical configuré.

Paramètres:

  • labels (list[str]) – Titres affiché dans les boutons.

  • space (int) – Valeur (en pixels) utilisée pour l’espacement du layout. Par défaut : COMMON_SPACE.

Renvoie:

Un tuple (group, layout) où : group est le QGroupBox créé et layout son calque.

Type renvoyé:

tuple[QHBoxLayout, QButtonGroup, dict[str, QPushButton]]

make_form(parent: QWidget | None = None, space: int = 5, margin: int = 5) → QFormLayout[source]

Crée et configure un QFormLayout pour des paramètres.

Configuration appliquée :

  • labels alignés à droite et centrés verticalement ;

  • formulaire ancré en haut à gauche ;

  • espacements horizontaux/verticaux adaptés à une UI de réglages ;

  • politique de croissance des champs : les widgets de droite restent à leur sizeHint (évite qu’ils s’étirent jusqu’au bord droit).

Paramètres:

  • parent (QWidget | None) – Parent Qt du layout (peut-être None si définie plus tard).

  • space (int) – Valeur (en pixels) utilisée pour l’espacement du layout. Par défaut : COMMON_SPACE.

  • margin (int) – Valeur (en pixels) utilisée pour les marges du layout. Par défaut : COMMON_SPACE.

Renvoie:

Le QFormLayout configuré.

Type renvoyé:

QFormLayout

make_info_grid(elements: dict[str, dict[str, QLabel | str]], title: str, size: int = 2, parent: QWidget | None = None, space: int = 5, margin: int = 5) → QGridLayout[source]

Construit une colonne d’informations structurée sous forme de QGridLayout.

La grille est composée de : un titre de section (ligne 0), un séparateur horizontal, plusieurs lignes label / value (et éventuellement unit).

La colonne value est extensible afin de conserver un alignement propre, tandis que les labels et unités gardent leur taille naturelle.

Paramètres:

  • elements (dict[str, dict[str, QLabel | str]]) –

    Dictionnaire décrivant les lignes à afficher. Chaque entrée doit contenir :

    • "label" : QLabel (libellé) ;

    • "value" : QLabel (valeur associée) ;

    • optionnellement "unit" : QLabel (unité) si size == 3 ;

    • optionnellement "tips" : str (tooltip appliqué au label).

  • title (str) – Titre de la colonne affichée en haut de la grille.

  • size (int) – Nombre de colonnes : 2 → label | value, 3 → label | value | unit.

  • parent (QWidget | None) – Parent Qt du layout (optionnel).

  • space (int) – Espacement interne entre les éléments (en pixels).

  • margin (int) – Marges du layout (en pixels).

Renvoie:

Le QGridLayout configuré.

Type renvoyé:

QGridLayout

make_file_info_group(space: int = 5, margin: int = 5) → tuple[QGroupBox, dict[str, QLabel]][source]

Construit un groupe d’information pour le listing des fichiers calculés.

Le groupe est composée de : un titre, la liste des fichiers et leurs status. :return: Le QGroupBox configuré ainsi que le lien vers les QLabel de status des fichiers.

Paramètres:
Type renvoyé:

tuple[QGroupBox, dict[str, QLabel]]

make_path_label(value: str = '', parent: QWidget | None = None) → QLabel[source]

Crée un QLabel stylisé pour afficher un chemin ou un nom de fichier.

Le label utilise un style visuel discret (texte grisé et italique), adapté à l’affichage d’informations secondaires.

Paramètres:

  • value (str) – Texte initial affiché (généralement un nom de fichier).

  • parent (QWidget | None) – Parent Qt du label.

Renvoie:

Le QLabel configuré.

Type renvoyé:

QLabel

update_path_label(lbl: QLabel, path: str | Path)[source]

Mets à jour un label de chemin avec un nouvel objet pathlib.Path.

Le texte visible correspond uniquement au name du fichier/dossier, le chemin complet est placé dans le tooltip.

Paramètres:

  • lbl (QLabel) – Label à mettre à jour.

  • path (str | Path) – Chemin à afficher.

make_vertical_separator(color: str = '#B0B0B0') → QFrame[source]

Crée un séparateur vertical discret.

Paramètres:

color (str) – Couleur du séparateur (format CSS, ex: "#B0B0B0").

Renvoie:

Le QFrame configuré.

Type renvoyé:

QFrame

make_horizontal_separator(color: str = '#B0B0B0') → QFrame[source]

Crée un séparateur horizontal discret.

Paramètres:

color (str) – Couleur du séparateur (format CSS, ex: "#B0B0B0").

Renvoie:

Le QFrame configuré.

Type renvoyé:

QFrame

make_spin(parent: QWidget | None = None, minimum: int | float = 0, maximum: int | float = 1, step: int | float = 1, value: int | float = 0, decimals: int = 0, buttons: bool = True) → QSpinBox | QDoubleSpinBox[source]

Crée une QSpinBox ou QDoubleSpinBox configurée de manière compacte.

Le type de spinbox est choisi automatiquement : QSpinBox si decimals ≤ 0, QDoubleSpinBox sinon.

Configuration appliquée :

  • suppression des marges et paddings inutiles ;

  • alignement centré du texte ;

  • largeur ajustée dynamiquement en fonction du range et du nombre de décimales ;

  • possibilité de masquer les boutons d’incrément.

Paramètres:

  • parent (QWidget | None) – Parent Qt du widget.

  • minimum (int | float) – Valeur minimale autorisée.

  • maximum (int | float) – Valeur maximale autorisée.

  • step (int | float) – Pas d’incrément.

  • value (int | float) – Valeur initiale.

  • decimals (int) – Nombre de décimales (si > 0 → spinbox flottante).

  • buttons (bool) – Affiche ou non les boutons up/down.

Renvoie:

La spinbox configurée (QSpinBox ou QDoubleSpinBox).

Type renvoyé:

QSpinBox | QDoubleSpinBox

set_spin_width(spin: QSpinBox | QDoubleSpinBox)[source]

Ajuste la largeur fixe d’une spinbox en fonction du contenu affichable.

La largeur est estimée à partir du nombre maximal de caractères nécessaires (valeur max, signe, décimales) et de la métrique de police du widget. Cela permet d’éviter les widgets trop larges et de garantir que toutes les valeurs restent visibles sans troncature.

Paramètres:

spin (QSpinBox | QDoubleSpinBox) – Spinbox à ajuster.

sync_spin(target: QDoubleSpinBox | QSpinBox, value: float | int)[source]

Synchronise une spinbox avec la valeur envoyée (par signal).

On bloque les signaux le temps de la mise à jour pour éviter les appels en série.

Exemple d’utilisation

spin_1.valueChanged.connect(lambda v: sync_spin(spin_2, v))
spin_2.valueChanged.connect(lambda v: sync_spin(spin_1, v))
Paramètres:

  • target (QDoubleSpinBox | QSpinBox) – Spinbox à mettre à jour.

  • value (float | int) – Valeur à insérer.

update_spin_limits(spin: QDoubleSpinBox | QSpinBox, minimum: float | int | None = None, maximum: float | int | None = None)[source]

Mets à jour dynamiquement les bornes d’une spinbox.

Les bornes non spécifiées conservent leur valeur actuelle.

Note

Qt ajuste automatiquement la valeur courante si elle sort du nouvel intervalle.

Paramètres:

  • spin (QDoubleSpinBox | QSpinBox) – Spinbox cible.

  • minimum (float | int | None) – Nouvelle borne minimale (optionnelle).

  • maximum (float | int | None) – Nouvelle borne maximale (optionnelle).

print_error(msg: str)[source]

Affiche un message avec une couleur rouge

Paramètres:

msg (str) – Message à afficher

print_warning(msg: str)[source]

Affiche un message avec une couleur jaune

Paramètres:

msg (str) – Message à afficher

print_success(msg: str)[source]

Affiche un message avec une couleur verte

Paramètres:

msg (str) – Message à afficher

format_time(seconds)[source]

Fonction pour formater le temps en secondes en HH:MM:SS.

Paramètres:

seconds – Temps en secondes

Renvoie:

Chaine de caractère représentant le temps au format HH:MM:SS.