Voir la source de Ncurses

[[catégorie:programmation]]

== Compilation ==

* Inclure {{tt|<curses.h>}}.
* Compiler avec l'option {{tt|-lncurses}} (sur la ligne de commandes ou dans LDFLAGS).
* Pour utiliser la bibliothèque Panel, utiliser également l'option {{tt|-lpanel}}, de préférence avant {{tt|-lncurses}}.

== Notes et astuces diverses ==

* Si une fonction nécessite un pointeur de fenêtre, c'est toujours son premier argument.
* Pour réafficher l'écran à l'identique (tel que le programme pense qu'il doit être) : {{code|wrefresh(curscr)}}

=== Débogage ===

A cause du volume d'informations y apparaissant, les fichiers journaux obtenus lorsque l'on active la trace du programme peuvent être difficiles à décoder. Le script '''{{tt|tracemunch}}''' inclus avec ncurses peut alléger le problème : il compacte les longues séquences d'opérations identiques en des "pseudo-opérations" d'une seule ligne (en majuscules).

=== Préfixes courants des fonctions ===

* {{tt|w}} : la fonction en question, mais avec une fenêtre-cible différente de stdcsr.
* {{tt|mv}} : se déplacer en (x,y) avant d'effectuer le traitement.
: Exemple : {{code|move(y, x) ; addch(c) ;}} peut être remplacé par {{code|mvaddch(y, x, c) ;}}. De même, {{code|wmove(fenetre, y, x) ; waddch(fenetre, c) ;}} sera remplacé par {{code|mvwaddch(fenetre, y, x, c) ;}}.

=== Ouvrir un shell (ou autre programme en console) ===

Se référer à la section [[#Basculer entre les modes ncurese et console]].

 addstr("Ouverture d'un shell...") ;
 def_prog_mode() ; // Sauvegarde de l'état du terminal (mode curses)
 endwin() ; // Restauration de l'état du terminal (mode console)
 system("sh") ; // Lancement du shell
 addstr("Retour au mode curses.\n") ; // Prépare le message de retour
 refresh() ; // Restaure le mode curses sauvegardé et réaffiche l'écran

=== ncurses sous Xterm ===

Lorsque l'on redimensionne Xterm, le signal {{tt|SIGWINCH}} est envoyé à l'application s'exécutant dedans. ncurses propose un gestionnaire de signal expérimental, mais n'intercepte généralement pas le signal car il ne sait pas de quelle manière il doit réafficher. Il faut écrire le gestionnaire du signal {{tt|SIGWINCH}} soi-même. Le plus facile est qu'il contienne un appel à {{code|endwin()}}, suivi d'un {{code|refresh()}} et d'un réaffichage de l'écran personnalisé. Le {{code|refresh()}} va lire la nouvelle taille de l'écran depuis l'environnement Xterm.

Cette méthode est la méthode standard (qui marche même sur certaines implémentations propriétaires de curses). L'inconvénient est que l'écran est complètement réaffiché mais que les sous-fenêtres ne sont pas redimensionnées. ncurses fournit une extension qui fonctionne mieux : {{code|resizeterm()}}. Cette fonction s'assure que toutes les fenêtres sont limitées à la nouvelle taille de l'écran, et complète avec des espaces si l'écran est plus large.

ncurses peut être configuré pour utiliser son propre gestionnaire de signal pour {{tt|SIGWINCH}}, basé sur {{code|resizeterm()}}.

=== Terminaux multiples ===

Si le programme doit ouvrir plusieurs terminaux, utiliser directement {{code|newterm()}} plutôt que {{code|initscr()}}. Voir [[#Début et fin de programme]] pour le descriptif des arguments. {{tt|stdscr}} pointe vers le dernier terminal alloué. On bascule entre les différents terminaux grâce à la fonction {{code|set_term()}}. Note : il faut appeler soi-même {{code|def_shell_mode()}} et {{code|def_prog_mode()}} pour chaque terminal.

=== Vérifier les fonctionnalités du terminal ===

{{faire|traduction}}

Sometimes you may want to write programs that test for the presence of
various  capabilities before deciding whether to go into ncurses mode.
An  easy way to do this is to call {{code|setupterm()}}, then use the functions
{{code|tigetflag()}}, {{code|tigetnum()}}, and {{code|tigetstr()}} to do your testing.

A  particularly  useful  case  of this often comes up when you want to
test  whether  a  given  terminal  type  should  be treated as `smart'
(cursor-addressable) or `stupid'. The right way to test this is to see
if the return value of tigetstr("cup") is non-NULL. Alternatively, you
can  include  the  {{tt|term.h}}  file  and  test  the  value  of  the  macro
{{tt|cursor_address}}.

=== Accélérer l'affichage ===

La fonction d'affichage de chaînes {{code|addchstr()}}, et ses petites camarades, fonctionnent plus rapidement que {{code|addstr()}} et consors. Voici les principales différences :
* le curseur n'est pas avancé ;
* les caractères spéciaux (comme {{tt|\n}}) ne sont pas traités ;
*	la chaîne est tronquée à la fin de la ligne au lieu de continuer sur une nouvelle ligne.

De manière générale, pour améliorer la vitesse d'affichage, il faut essayer de ne pas changer trop souvent d'attributs de mise en forme (et de ne pas activer {{code|immedok(TRUE)}} !).

=== Fonctionnalités spéciales de ncurses ===

{{faire|traduction}}

The  {{code|wresize()}}  function  allows  you to resize a window in place. The
associated   {{code|resizeterm()}}  function  simplifies  the  construction  of
SIGWINCH handlers, for resizing all windows.

The {{code|define_key()}} function allows you to define at runtime function-key
control  sequences  which  are  not  in  the terminal description. The
{{code|keyok()}}   function   allows  you  to  temporarily  enable  or  disable
interpretation of any function-key control sequence.

The {{code|use_default_colors()}} function allows you to construct applications
which  can use the terminal's default foreground and background colors
as  an  additional "default" color. Several terminal emulators support
this feature, which is based on ISO 6429.

Ncurses  supports  up 16 colors, unlike SVr4 curses which defines only
8. While most terminals which provide color allow only 8 colors, about
a quarter (including XFree86 xterm) support 16 colors.

== Affichage ==

=== Attributs de texte ===

Il y a deux façons de faire un surlignement :
# Faire un '''ou''' logique du caractère à modifier et de la valeur du modificateur (commençant par "A_"), dans l'appel à {{code|addch()}} ou autre.
# Sélectionner la valeur courante de surlignement, grâce aux fonctions {{code|attron()}}, {{code|attroff()}} et {{code|attrset()}}.
Les couleurs sont un type particulier de surlignement. Un surlignement est en fait une paire de couleurs, l'une pour le texte et l'autre pour le fond. On déclare ces couples grâce à {{code|init_pair()}}.

=== Affichage de formes ===

La fonction {{code|addch()}} (et certaines autres comme {{code|box()}} et {{code|border()}}) peut accepter en argument des pseudo-caractères définis par ncurses ({{tt|#define}} avec le préfixe "ACS_" dans {{tt|<curses.h>}}). Ces pseudo-caractères permettent de dessiner des boîtes et autres sur l'écran.

== Constantes et variables fournies ==

=== Définitions générales ===

* {{tt|#define bool}} : type booléen (char).
* {{tt|#define TRUE}} : booléen VRAI (1).
* {{tt|#define FALSE}} : booléen FAUX (0).
* {{tt|#define ERR}} : drapeau retourné en cas d'erreur par les routines.
* {{tt|#define OK}} : drapeau retourné par les routines quand tout va bien.

=== Description du terminal ===

* {{code|int LINES}} : nombre de lignes du terminal.
* {{code|int COLS}} : nombre de colonnes.
Note : éviter d'utiliser {{tt|LINES}} et {{tt|COLS}} ; il vaut mieux appeler la fonction {{code|getmaxyx()}} sur le {{tt|stdscr}}.

=== Fenêtres standard ===

Deux fenêtres sont fournies par défaut :
* {{code|struct WINDOW curscr}} : à quoi le terminal ressemble actuellement. Ne pas la modifier directement.
* {{code|struct WINDOW stdscr}} : à quoi le terminal ressemblera au prochain raffraichissement. De nombreuses fonctions utilisent cette fenêtre par défaut (exemple : pour ajouter un caractère à {{code|stdscr}}, on peut utiliser {{code|addch(char c)}} ; pour utiliser une autre fenêtre on utilise {{code|waddch()}}).

=== Attributs de caractères ===

* La liste des mises en valeur possibles (surlignement et couleurs) figure dans {{tt|<curses.h>}} (préfixes "A_").

== Fonctions ==

=== Début et fin de programme ===

* {{code|initscr()}} : initialise curses. Récupère les caractéristiques terminal et alloue l'espace pour {{code|curscr}} et {{code|stdscr}}. Cette fonction doit toujours être appelée avant les fonctions qui affectent les fenêtres ou le terminal. Les seules fonctions pouvant être appelées avant {{code|initscr()}} sont : {{code|slk_init()}}, {{code|filter()}}, {{code|ripoffline()}}, {{code|use_env()}}, et, en cas d'utilisation de plusieurs terminaux, {{code|newterm()}} ({{code|initscr()}} utilise en fait {{code|newterm()}}).

* {{code|SCREEN* newterm (char* type, FILE* out, FILE* in)}} : si le programme doit afficher sur plusieurs terminaux, il faut utiliser newterm() au lieu de initscr(). newterm() doit être appelé une fois par terminal. L'argument TYPE représente le type du terminal ; s'il est NULL, la variable d'environnement $TERM est utilisée. endwin() devra être appelée pour chaque terminal ouvert par newterm().
* {{code|SCREEN* set_term(SCREEN* terminal)}} : bascule vers le terminal donné, ouvert préalablement avec newterm(). Cette fonction retourne le terminal duquel on vient de basculer.
* {{code|delscreen(SCREEN* terminal)}} : désalloue les structures de données associée à un terminal. Cette fonction devrait être appelée après endwin() si un terminal n'est plus nécessaire.

* {{code|keypad(stdscr, TRUE)}} : active le support du mappage des touches de fonction (flèches, etc.). Les valeurs de pseudo-caractères {{tt|#define}} retournées sont listées dans {{tt|<curses.h>}}.

* {{code|endwin()}} : voir [[#Basculer entre les modes ncurese et console]].

=== Basculer entre les modes ncurese et console ===

* {{code|endwin()}} : restaure le terminal tel qu'il était lors de l'appel à {{code|initsrc()}}. Cette fonction devrait toujours être appelée avant la fin du programme. Elle permet aussi de basculer entre le mode console et le mode curses ; une fois en mode console, un appel à {{code|refresh()}} ou {{code|doupdate()}} restaure la fenêtre curses telle qu'elle était avant l'appel à {{code|endwin()}}.
* bool {{code|isendwin()}} : retourne TRUE si le programme est en mode console (c'est-à-dire entre un appel à {{code|endwin()}} et un appel à {{code|refresh()}}), FALSE sinon.
* {{code|def_prog_mode()}} : sauvegarde l'état du programme (mode curses).
* {{code|def_shell_mode()}} : sauvegarde l'état du programme (mode console). Appélée automatiquement par {{code|initscr()}}.
* {{code|reset_prog_mode()}} : restaure l'état du programme (mode curses). Appelée automatiquement par {{code|doupdate()}}, et donc normalement pas appelée à la main.
* {{code|reset_shell_mode()}} : restaure l'état du programme (mode console). Appelée automatiquement par {{code|endwin()}}, et donc normalement pas appelée à la main.

=== Accès bas niveau ===

; {{code|setupterm(char* term, int filnum, int* errret)}} : Appelée pour initialiser la description du terminal. Arguments :
:* {{tt|term}} : chaîne de caractères représentant le nom du terminal utilisé ({{tt|NULL}} pour utiliser le terminal désigné par {{tt|$TERM}}).
:* {{tt|filenum}} : descripteur de fichier du terminal utilisé pour la sortie.
:* "errret" : code de retour de la fonction (1 si tout va bien, 0 si le terminal n'a pas été trouvé, -1 en cas de problème pour trouver la base de données terminfo) ; on peut passer NULL si on ne veut pas récupérer le code d'erreur.
: Après l'appel à {{code|setupterm()}}, la variable globale cur_term pointe vers la structure détaillant les paramètres du terminal courant. Appeler {{code|setupterm()}} pour chaque terminal et sauver et restaurer cur_term permet d'utiliser deux terminaux (ou plus) à la fois. {{code|setupterm()}} enregistre également, dans le tableau de caractères ttytype[] (global), la section de la description du terminal concernant les noms (ce tableau est écrasé à chaque appel à {{code|setupterm()}}).

=== Gestion des fenêtres ===

* {{code|newwin()}} : créer une nouvelle fenêtre.
* {{code|derwin()}}
* {{code|subwin()}}
* {{code|delwin()}} : "allow you to get rid of  old windows"

=== Gestion du curseur ===

* {{code|[w]move(int x, int y)}} : déplacer les coordonnées courantes (autrement dit le curseur) aux coordonnées (x,y) (colonne,ligne). L'origine est le coin supérieur gauche. Retourne ERR si l'on cherche à déplacer en dehors de la fenêtre.
* {{code|leaveok()}} : placer le curseur à gauche plutôt qu'à l'endroit de la dernière action.

=== Entrées ===

* char {{code|getch()}} : si l'écho est actif, appelle {{code|addch()}} pour afficher le caractère tapé. Si l'on active l'écho, il faut que le terminal soit en mode "raw" ou "cbreak" (par défaut, l'écho est actif et le mode du terminal est "cooked", il faut donc changer l'un ou l'autre avant d'appeler {{code|getch()}}).
* {{code|[w]getstr(char* chaine)}} : récupère dans "chaine" la chaîne entrée.
* {{code|[w]scanw()}} : même style que {{code|scanf(3)}}.

=== Sorties ===

* {{code|[w]addch(char c)}} : ajouter un caractère à la fenêtre.
* {{code|[w]mvaddch(int x, int y, char c)}} : se placer en (x,y) puis ajouter c.
* {{code|addstr(char* chaine)}} : ajoute une chaîne de caractères (fait appel à {{code|addch()}}).
* {{code|printw()}} : (fait appel à {{code|addch()}}).

=== Attributs de caractères ===

* {{code|[w]attrset(int attributs)}} : active les attributs donnés.
* {{code|[w]attron(int attributs)}} : active les attributs donnés sans modifier les autres.
* {{code|[w]attroff(int attributs)}} : désactive les attributs donnés sans modifier les autres.
* [w]standend : désactive tous les attributs. Equivalent à {{code|attrset(A_NORMAL)}} ou {{code|attrset(0)}}.
* {{code|init_pair(int numero, int COLOR_TEXTE, int COLOR_FOND)}} : définit un surlignement, qui portera le numéro "numero". La définition est enregistrée au moment de la compilation dans la constante {{code|COLOR_PAIR(int numero)}}.

=== Gestion de l'affichage ===

* {{code|refresh()}} / {{code|wrefresh(win)}} : faire correspondre une section du terminal à ce que décrit une fenêtre (en clair : afficher la fenêtre à l'endroit prévu). Rafraîchit uniquement les parties modifiées. Elle fonctionne en faisant un appel à {{code|wnoutrefresh()}} puis à {{code|doupdate()}} ; quand il y a plusieurs modifications successives à faire, il est préférable de les faire via {{code|wnoutrefresh()}} puis d'appeler une seule fois {{code|doupdate()}}.
* {{code|wnoutrefresh(win)}} : copie la fenêtre donnée sur l'écran virtuel.
* {{code|doupdate()}} : met à jour l'écran (affichage à proprement parler).
* {{code|touchwin()}} : fait un "touch" sur toute la fenêtre, afin qu'elle soit réaffichée entièrement au prochain {{code|refresh()}}.

=== Débogage ===

* {{code|trace(int niveau)}} : définit le niveau de trace. Si le niveau est supérieur à zéro, l'exécution du programme générera un fichier nommé "trace" dans le répertoire courant. On peut choisir un niveau de détail plus ou moins élevé, se référer aux constantes #define dans <tt><curses.h></tt> dont le préfixe est "TRACE_". Note : il est également possible de définir un niveau de trace en assignant une valeur à la variable d'environnement NCURSES_TRACE.
* {{code|_tracef()}} : affiche des informations de débogage personnalisées dans le fichier de trace, si l'option "-lncurses_g" est passée à l'éditeur de liens.

=== Divers ===

* {{code|scrollok()}} : autoriser un écran à défiler.

* {{code|box()}}
* {{code|border()}}