La bibliothèque GadTools

                               de Paul Miller



  L'allure professionnelle et la cohérence opérationnelle du Workbench 2.0
sont tout d'abord imputables à la construction des nouveaux gadgets, mis à
la disposition par la bibliothèque GadTools. Toute une partie de ce système
d'exploitation récent, GadTools, rassemble l'allure du 2.0 et l'aspect de
plusieurs commandes standard pour former un ensemble de nouvelles classes de
gadgets. Ceux-ci peuvent vous rendre la vie plus simple et ceci parce que
GadTools n'est pas seulement un outil - c'est une interface programmeur
facile d'emploi !
  Ce qu'il y a de mieux dans GadTools est sa facilité d'emploi. Celle-ci
permet de créer toute une liste de gadgets compliqués avec moins d'effort et
de pagaïe qu'avant. Avec une fonction et quelques paramètres, par exemple,
on peut créer un gadget pour toute une liste déroulable, complet avec sa
réglette et ses boutons pour les flèches - GadTools rassemble de manière
automatique les commandes nécessaires en un gadget unique. Vous n'aurez plus
à créer des gadgets proportionnels et à les combiner avec deux gadgets
booléens pour réaliser un cadre de défilement - demandez simplement un
gadget de type Scroller à GadTools et le système prendra en charge tout ce
travail ennuyeux ainsi que sa maintenance.
  GadTools est aussi extrêment extensible. C'est-à-dire qu'à mesure que des
nouvelles classes de gadgets et des paramètres deviendront disponibles, on
pourra les intégrer facilement en se servant des facilités offertes par les
tags du système 2.0. Les tags sont un moyen de fournir l'information à
plusieurs nouvelles fonctions du 2.0 sans avoir à remplir des structures
temporaires considérables comme NewScreen et NewWindow. Ils vous permettent
aussi d'intégrer facilement des nouvelles structures. Si l'on omet ces tags,
le système, par défaut, se tourne vers un groupe de réglages standard. Pour
cette raison, vous ne devrez employer que les paramètres spécifiques
nécessaires.
  Les tags sont définis en tant que tableaux de TagItems ou comme paramètres
variables -contenant le tag et ses données- vers la fonction. Voici le
format d'une structure TagItem :

  typedef ULONG Tag;

  struct TagItem {
  Tag ti_Tag;       /* ID du tag */
  ULONG ti_Data;
  };

  Les listes de TagItems se terminent avec un tag de type TAG_DONE ou
TAG_END.

Tag - vous êtes un gadget !

  Dans la version 36 de la gadtools.library, il y a 13 types de gadgets.
Chaque type possède un ensemble de tags indiquant l'information nécessaire
ou particulière d'un gadget donné.

  GENERIC_KIND (un type de gadget standard) et BUTTON_KIND (un bouton
d'action) acceptent tous les deux le tag d'invalidation. Ceci s'applique
aussi à la plupart des autres gadgets :

  GA_DISABLED (BOOL; default = FALSE)
    Mis à TRUE pour invalider le gadget, autrement à FALSE.

  CHECKBOX_KIND est un gadget de sélection d'états. Une marque de contrôle
s'affiche, quand on active le gadget. Avec celui-ci, on peut utiliser le tag
de contrôle :

  GTCB_Checked (BOOL; default = FALSE)
    Etat initial de la marque de contrôle (TRUE = CHECKED).

  CYCLE_KIND est un bouton unique avec plusieurs états possibles. Ce gadget
permet de passer en revue une liste de chaînes de caractères vers l'avant à
chaque fois qu'on clique sur lui. Il peut aussi passer en revue cette même
liste vers l'arrière, si l'on appuie sur la touche SHIFT et que l'on clique
sur celui-ci. Voici les tags correspondants :

  GTCY_Labels (STRPTR *)
    Un tag requis, c'est un tableau de pointeurs de chaînes de caractères se
    terminant par NULL. Ces chaînes comportent les propositions du gadget.
  GTCY_Active ((UWORD: default = 0)
    Numéro d'ordre (compté à partir de zéro) du choix initialement actif
    pour le passage en revue de la liste.

  INTEGER_KIND est un gadget d'édition de chaînes ordinaire qui ne vous
permet d'éditer que des entiers. Ce gadget accepte les tags suivants :

  GTIN_Number (ULONG; default = 0)
    Détermine le contenu initial du gadget Integer.
  GTIN_MaxChars (UWORD; default = 10)
    Nombre maximal de chiffres que le gadget Integer pourra contenir.

  LISTVIEW_KIND, un gadget puissant, affiche une liste d'articles qu'on peut
sélectionner et faire défiler. Ce gadget possède une barre de défilement
optionnelle avec des flèches et des facilités optionnelles d'édition de
l'article choisi. ListView accepte différents tags :

  GTLV_Top (UWORD; default = 0)
    Détermine le premier article (ordinal) visible de la liste.
  GTLV_Labels (struct List *)
    Un tag requis, celui-ci agit comme un pointeur sur une Liste Exec
    d'étiquettes dont les champs ln_Name sont affichés dans la liste.
  GTLV_ReadOnly (BOOL; default = FALSE)
    Si TRUE, le gadget ListView ne sert qu'à la lecture.
  GTLV_ScrollWidth (UWORD; default = 16)
    Détermine la largeur de la barre de défilement.
  GTLV_ShowSelected (struct gadget *)
    Le mettre à NULL pour pouvoir avoir l'article actuellement sélectionné
    affiché au-dessous de la liste. Alternativement, si l'on souhaite avoir
    un affichage éditable de l'article couramment sélectionné, le mettre sur
    un pointeur sur un gadget STRING_KIND de GadTools déjà existant.
  GTLV_Selected (UWORD; default = -0)
    Numéro d'ordre du gadget actuellement sélectionné ou -0 si couramment on
    n'a pas fait de sélection.
  LAYOUTA_SPACING (default = 0);
    Espace supplémentaire à mettre entre les lignes de la liste.

  Le gadget MX_KIND met à la disposition un ensemble d'articles qu'on ne
peut sélectionner -comme les commandes radio- qu'un seul à la fois. Voici
les tags possibles :

  GTMX_Labels (STRPTR *)
    Ce tag est nécessaire. Il sert de valeur NULL de fin à un tableau de
    pointeurs de chaînes de caractères. Celles-ci apparaitront comme des
    étiquettes au-delà des choix du gadget.
  GTMX_Active (UWORD; default = 0)
    Numéro d'ordre (compté à partir de zéro) du choix initialement actif
    dans le gadget.
  GTMX_Spacing (UWORD; default = 1)
    L'espace présent entre chaque choix d'un ensemble de gadgets qui peuvent
    être mutuellement exclus. Cet espace, qu'on ajoute à la hauteur de la
    fonte, engendre le défilement vertical des différents choix.

  NUMBER_KIND est un gadget d'affichage utilisé seulement en lecture. Il
admet les tags suivants :

  GTNM_Number (default = 0)
    Un entier long signé qui pourra être affiché en tant que nombre destiné
    à la lecture.
  GTNM_Border (BOOL; default = FALSE)
    Si TRUE, ce flag permet l'affichage dans le gadget d'un bord absent.

  Le gadget PALETTE_KIND renferme un affichage de toutes les couleurs
disponibles dans l'écran courant, outre à une boîte qui renferme la couleur
"courante" - qui est la couleur sélectionnée à partir du gadget. Les tags du
gadget palette comprennent :

  GTPA_Depth (UWORD; default = 1)
    Met en place le nombre de plans de bits de la palette.
  GTPA_Color (UBYTE; default = 1)
    Couleur de palette initialement sélectionnée.
  GTPA_ColorOffset (UBYTE; default = 0)
    Détermine la couleur à utiliser en première dans la palette.
  GTPA_IndicatorWidth (UWORD)
    Détermine la largeur de l'indicateur de la couleur courante. Mettez-le
    à 1, si vous souhaitez que l'indicateur s'affiche au-dessus de la
    palette.
  GTPA_IndicatorHeight (UWORD)
    Détermine la hauteur de l'indicateur de la couleur courante. Utilisez ce
    tag si vous souhaitez mettre l'indicateur à gauche de la palette.

  Le gadget SCROLLER_KIND rassemble une réglette proportionnelle et deux
boutons de flèche optionnels. Ce qui donne pour résultat un gadget de
défilement opérationnel qui suit automatiquement la position et la taille de
la commande de la réglette. Pour ce gadget, il existe un choix de plusieurs
tags :

  GTSC_Top (WORD; default = 0)
    Détermine ce qui s'affichera dans la partie supérieure de la zone
    décrite par le cadre de défilement.
  GTSC_Total (WORD; default = 0)
    Nombre total d'articles dans la zone du cadre de défilement.
  GTSC_Visible (WORD; default = 2)
    Nombre de choses visibles dans le cadre de défilement.
  GTSC_Arrows (UWORD)
    Relie les flèches au cadre de défilement. La largeur qu'on fournit est
    utilisée pour la largeur du bouton de chaque flèche d'un cadre de
    défilement horizontal ou pour la hauteur de chaque bouton d'un cadre de
    défilement vertical (les autres dimensions du cadre concordent).
  PGA_FREEDOM (default = LORIENT_HORIZ)
    Détermine si le cadre de défilement est horizontal ou vertical. A
    choisir avec LORIENT_VERT ou de LORIENT_HORIZ.
  GA_IMMEDIATE (BOOL; default = FALSE)
    Le mettre à TRUE, si vous souhaitez qu'on vous informe de tout événement
    de type GADGETDOWN qui se produira dans le cadre de défilement.
  GA_RELVERIFY (BOOL; default = FALSE)
    Le mettre à TRUE, si vous souhaitez qu'on vous informe de tout événement
    de type GADGETUP qui se produira dans le cadre de défilement.

  Le gadget SLIDER_KIND rassemble un gadget proportionnel et, en option, un
affichage numérique qui dépeint le niveau ou l'intensité de chaque valeur.
Voici les tags correspondants :

  GTSL_Min (WORD; default = 0)
    Met en place le niveau minimal de la réglette.    
  GTSL_Max (WORD; default = 15)
    Niveau maximal de la réglette.
  GTSL_Level (WORD; default = 0)
    Niveau actuel de la réglette.
  GTSL_MaxLevelLen (UWORD)
    Longueur maximale des caractères de la chaîne de la réglette, lorsqu'on
    en fait le rendu au-dela des limites de la réglette elle-même.
  GTSL_LevelFormat (STRPTR)
    Une chaîne de formatage dans le style du C pour le niveau de la
    réglette. Assurez-vous d'employer un modificateur l (long). Cette chaîne
    sera traitée par la fonction RawDoFmt() d'Exec.
  GTSL_LevelPlace (default = PLACETEXT_LEFT)
    Indique où s'affichera l'indicateur de niveau en liaison avec la
    réglette. Voici les réglages possibles : PLACETEXT_LEFT,
    PLACETEXT_RIGHT, PLACETEXT_ABOVE ou PLACETEXT_BELOW.
  GTSL_DispFunc ([LONG(*function)(struct gadget *,WORD)]; default = 0)
    Cette fonction calcule le niveau qui doit être affiché. Par exemple,
    pour sélectionner le nombre de couleurs, une réglette pourrait avoir
    besoin ici d'une fonction (1<<n). Votre fonction devra prendre comme
    premier paramètre un pointeur sur un gadget, comme deuxième le niveau
    (un WORD) et retourner le résultat en tant que valeur de type LONG.
  GA_IMMEDIATE (BOOL; default = FALSE)
    Le mettre à TRUE, si vous souhaitez qu'on vous informe de tout événement
    de type GADGETDOWN qui se produira dans la réglette.
  GA_RELVERIFY (BOOL; default = FALSE)
    Le mettre à TRUE, si vous souhaitez qu'on vous informe de tout événement
    de type GADGETUP qui se produira dans la réglette.
  PGA_FREEDOM (default = LORIENT_HORIZ)
    Le mettre à LORIENT_VERT ou à LORIENT_HORIZ pour créer une réglette
    verticale ou horizontale.

  STRING_KIND est un gadget d'édition de chaîne alphanumérique ordinaire.
Voici les tags qu'il accepte :

  GTST_STRING (STRPTR; default = NULL)
    Indique le contenu initial du gadget chaîne de caractères. Mettez-le à
    NULL, si le début de la chaîne doit être vide.
  GTST_MaxChars (UWORD)
    Nombre maximal de caractères pouvant être contenu dans le gadget chaîne
    de caractères.

  TEXT_KIND, dernier type de gadget, est destiné à l'affichage d'un texte
alphanumérique seulement en lecture. Vous pouvez choisir parmi les tags
suivants :

  GTTX_Text (default = NULL)
    Sert comme pointeur sur une chaîne de caractères se terminant par NULL
    devant être affichée en tant que gadget d'affichage de texte seulement
    en lecture ou en tant que NULL.
  GTTX_CopyText (BOOL; default = FALSE)
    Ce flag dit au gadget d'affichage de texte de copier la chaîne de texte
    fournie au lieu de continuer à faire référence à l'adresse de la chaîne
    fournie.
  GTTX_Border (BOOL; default = FALSE)
    Si TRUE, ce flag oblige un bord éloigné à entourer le gadget.

Mise en place et démarrage

  Etant donné que GadTools est dans une bibliothèque en ROM, auparavant on
devra faire quelques réglages avant de pouvoir réellement créer un gadget.
GadTools a besoin aussi d'un pointeur sur un bloc VisualInfo, qu'on peut
obtenir en accédant à l'écran du Workbench ou à un écran utilisateur. Enfin,
comme le Workbench 2.0 permet à l'utilisateur de choisir comme fonte
standard presque n'importe quelle fonte, GadTools est très tâtillon sur la
taille de la fonte et devra, par conséquent, connaître la fonte choisie pour
pouvoir placer le texte du gadget de façon correcte. Typiquement, vous aurez
envie de forcer Topaz 80, par conséquent faites-en la demande de manière
explicite. Pour l'initialisation que nous décrivons ici, voyez la fonction
setup() du programme de démonstration (dans le tiroir Miller de la
disquette).
  Maintenant, vous voilà prêts pour créer une liste de gadgets. Etant donné
que tous les gadgets de GadTools sont affectés de manière dynamique,
GadTools met à la disposition un moyen simple pour relier, ajouter,
rafraîchir et libérer des listes entières de gadgets. Pour définir votre
preopre liste de gadgets, déclarez un pointeur sur une structure gadget et
appelez la fonction CreateContext() de GadTools avec l'adresse du pointeur :

  struct gadget *glist = NULL;
  struct gadget *gad;
  gad = CreateContext(&glist);

  Ceci affecte un gadget privé qui décrit la liste. Ceci constitue aussi la
base à partir d'où l'on pourra ajouter des gadgets supplémentaires et sur
qui on pourra effectuer des opérations d'ajout et de rafraîchissement des
gadgets. Employez le pointeur de gadget en retour comme base de construction
de votre liste de gadgets avec CreateGadget().
  CreateGadget() est une version à arguments variables de la fonction
d'affectation de gadgets et a besoin, comme paramètres, du type du gadget,
d'un pointeur sur le gadget précédent, d'un pointeur sur une structure
NewGadget et des tags de gadgets de GadTools. On spécifie la description
physique du gadget dans la structure NewGadget :

  struct NewGadget
    {
      WORD ng_LeftEdge, ng_TopEdge; /* coin supérieur gauche */
      WORD ng_Width, ng_Heigth;     /* dimensions */
      UBYTE *ng_GadgetText;         /* étiquette texte */
      struct TextAttr *ng_TextAttr; /* étiquette fonte */
      UWORD ng_GadgetID;            /* ID du gadget */
      ULONG ng_Flags;               /* flags spéciaux */
      APTR ng_VisualInfo;           /* Visual Info */
      APTR ng_Userdata;             /* données personnelles */
    };

  Maintenant, on doit assigner le pointeur (obtenu précédemment) au champ
ng_VisualInfo et assigner une structure TextAttr déclarée au préalable au
champ ng_TextAttr. Puis, enfin, vous voici prêts à la création du gadget.
  Remplissez une structure NewGadget avec la position et les dimensions du
gadget, un titre et un ID en même temps que les informations concernant Font
et VisualInfo. Pour créer un gadget simple de type BUTTON_KIND, on transmet
tout simplement les informations nécessaires :

  gad = CreateGadget(BUTTON_KIND, gad, &newgad, TAG_DONE);

  Pour un type de gadget plus complexe, disons un gadget de type Scroller,
vous pourriez vouloir ajouter quelques tags supplémentaires :

  gad = CreateGadget(SCROLLERN_KIND, gad, &newgad,
    PGA_FREEDOM, LORIENT_VERT,
    GTSC_Total, 20,
    GTSC_Visible, 10,
    GTSC_Arrows, 16,
    GA_RELVERIFY, TRUE,
    TAG_DONE);

  Pour affecter une liste complète de gadgets, commencez par le pointeur
retourné par l'appel à CreateContext(). Faites les réglages nécessaires dans
votre structure NewGadget entre chaque appel à CreateGadget() et transmettez
le pointeur retourné par chaque appel comme ancien pointeur lors de l'appel
suivant. Il ne vous faudra pas faire de vérification pour les affectations
avant de demander le dernier gadget car CreateGadget() retourne un pointeur
NULL si elle reçoit NULL comme pointeur sur le gadget précédent.
  Une fois que vous aurez votre liste de gadgets, vous pourrez la relier à
une fenêtre et rafraîchir toute l'imagerie avec les fonctions ordinaires
d'Intuition pour les gadgets. Vous devrez ensuite appeler GT_RefreshWindow()
pour la fenêtre pour que l'imagerie particulière de GadTools puisse ainsi
recevoir le traitement approprié. En supplément, on pourra disposer des
nouvelles fonctions GT_BeginRefresh() et GT_EndRefresh() pour remplacer les
fonctions standard de rafraîchissement des fenêtres d'Intuition.

Autres événements

  GadTools peut aussi traiter les événements des gadgets beaucoup plus
simplement. L'emploi des nouvelles fonctions GT_GetIMsg() et GT_ReplyIMsg(),
dans une boucle de traitement des événements en entrée, vous permet de gérer
de manière correcte les opérations particulières de GadTools. En outre, ces
fonctions retournent des informations bien utiles dans le champ Code
d'IntuiMessage. Par exemple, par ce champ, on peut connaître la position
réelle du cadre de déroulement ou celle de la réglette, aussi bien que la
couleur sélectionnée à partir du gadget Palette.
  Dès que vous en aurez terminé avec votre liste de gadgets, vous pourrez
liquider tout l'ensemble par un simple appel à FreeGList(), en lui passant
le pointeur original sur la liste des gadgets fourni par CreateContext().
  La création et l'utilisation des GadTools n'est pas seulement simple, leur
amélioration et leur modification est aussi facile. Etant donné la quantité
d'informations existant uniquement sur les gadgets de GadTools, je
n'entrerai pas dans les facilités offertes pour les nouveaux menus (qui
simplifient énormement la création des menus), voyez l'article "Menus for a
New Generation" de David Joiner dans le numéro d'Avril/Mai '91, p. 4) ainsi
que quelques autres spécificités et facteurs dans l'emploi de GadTools.
Si vous souhaitez aller plus à fond dans les rouages de GadTools, je vous
suggère d'étudier les fichiers en-tête de la GadTools 2.0.
  Il est important de se souvenir que GadTools n'est pas compatible avec
le SE 1.3, ainsi faites très attention lorsque vous employez cette puissante
bibliothèque. En théorie, vous devriez fournir au programme un dispositif de
remplacement utilisant les gadgets standard. Si vous n'avez pas la
possibilité de le faire, appelez le système 2.0 de manière explicite et,
ensuite, sortez avec élégance si celui-ci n'est pas disponible. Si vous
voulez mettre votre programme en vente dans le commerce ou le distribuer
partout dans le monde Amiga, vous devriez considérer comme une obligation la
compatibilité avec le système 1.3 - tout au moins pour l'instant.