Stimulus 03 Initiation au GEM en GFA

Initiation au GEM en GFA


Hum... vaste sujet. Autant dire mission impossible : il est des choses qu'on ne peut apprendre que par soi-même. Le GEM en fait partie, aussi commencerai-je par vous relater mon expérience.
Comme tous le monde, j'ai galéré, eu de nombreuses prises de têtes, de déceptions. Je lisais les articles de STMag (je ne comptais pas du tout sur AtariMag) sur la programmation GEM et GFA, j'arrivais à faire des choses valables, mais du niveau débutant. Jusqu'au jour où, souffrant d'insomnie, je pris un tas de STMag et lu la totale des articles de Claude Attard.

C'est là qu'il me vint le feeling. Je ne pourrais pas vous l'expliquer, c'est quelque chose de personnel. C'est à partir de ce moment que je pus dire "je maîtrise l'interface de mon ordinateur". Dites ça à un windaubien, vous vous ferez un ennemi pour la vie.

L'apprentissage du GEM est un long parcours, mais une fois qu'on en a saisit la philosophie, il devient clair comme de l'eau de roche, (certains ont dit qu'il était plus facile à maîtriser que d'autres interfaces).
Laissez-moi être votre guide dans cette aventure, mais comme n'importe quel étudiant ou apprenti-sorcier, je vous demanderai de potasser la littérature : Compemdium, Bible du ST, petit mémos sur le GFA, pourvu que le GEM y soit traité. Et si vous n'êtes pas papier, il existe au format HYP pour ST-Guide les docs pour le GFA Basic ou le TOS (la totale) qui valent leur pesant de cacahouettes.


Je me tâte

Le GEM est composé de l'AES, qui gère les événements tels que le temps, les clics souris, la gestion des fenêtres... et la VDI qui s'occupe de l'affichage à l'écran ou sur l'imprimante. On commencera par l'AES, partie la plus haute dans ce qu'on nomme la couche logicielle de notre système d'exploitation.
En fait, programmer GEM signifie appeler les fonctions adéquates qui se trouvent dans le TOS, d'utiliser de bons paramètres, et tenir compte du résultat. Exemple :
ap_id&=APPL_INIT()
Nous avons appelé la fonction primordiale de l'AES, celle qui donne un numéro d'identification à notre programme (très utile en multitache). Il n'y a pas de paramètres à fournir, la fonction renvoie comme résultat notre ap_id& ou application_identifier.
Autre exemple :
handle%=WIND_CREATE(composants%,x&,y&,larg&,haut&)
Nous avons simplement demandé à l'AES de créer une fenêtre pour nous. composant% est un champ de bits qui va décrire les propriétés de la fenêtre, avec des coordonnées bidons. Notez qu'en AES, on parle toujours x,y,larg,haut, jamais x1,y1,x2,y2 (ça c'est de la VDI). Autre précision, le champ de bit est un mot long (%), les coordonnées un mot (&). Faites attention à la nature des paramètres que vous utilisez dans vos fonctions, ça peut bugger si ça ne convient pas.
On obtient en retour un handle%, qui est s'il est supérieur à 0, est le numéro identificateur de notre fenêtre. S'il est égal à 0 ou négatif, il n'y a eut problème donc pas de création de la fenêtre.
Un appel GEM, c'est toujours ça : une fonction qui existe dans le système d'exploitation. Je me suis rendu compte qu'il existait beaucoup de fonctions GEM depuis le TOS 1.0 pour faire des choses incroyables, des boîtes de dialogue non bloquantes, des pop-ups menus... Tout y est, il faut seulement connaître ces fonctions et jongler avec. Je vous renvoie donc à la littérature.

Ce qu'on appelle la doc développeur n'est pas autre chose que ça : un ouvrage de référence contenant toutes les réponses qu'on peut se poser. Tel problème ? Telle fonction qui répond à mes attentes. Je conserve sur mon disque dur le fichier TOS.HYP (allemand, dommage mais qui est compréhensible), et je le consulte chaque fois que calle sur quelque chose.
Pour la petite histoire, c'est cette doc qu'Atari Corp (et France) distribuait à compte goutte, paralysant la moitié des développements de logiciels sur notre machine chérie. Que pourrait-on imaginer si tous les ataristes un peu bidouilleurs avaient eu en main ce précieux document ? La face du monde informatique en serait-elle changée ?
Bon, on ne va pas changer l'histoire. Atari n'est pas prêt de se réveiller. Les ataristes ont en leur main leur destinée. Pour notre bonheur, la doc développeur est diffusée comme un domaine public (TOS.HYP) ou vendue pour pas trop cher (genre Compemdium). On va pouvoir s'amuser comme des fous !


Nous avons de la ressource !

Vous êtes ataristes, vous savez donc qu'un fichier RSC accompagne souvent le PRG ou APP, sinon l'application GEM ne marche pas.
Ce fichier RSC ou ressource contient en fait l'interface de votre programme : boîtes d'alertes, menus, chaînes de texte, icônes... tout sauf les fenêtres ! Ce fichier peut être facilement créé, modifiée, traduit en allemand via un éditeur de ressources (RSC2.PRG, INTERFACE.PRG, WERCS.PRG). Donc les bugs survenant lors de la traduction de logiciels n'ont pas lieu d'avoir (au contraire d'un certain windaube). Mais attention, quand on crée quelque chose dans le ressource (ou quand on l'enlève), l'ordre des objets dans le ressource est modifié, et le programme, qui tient compte de l'ordre de ces objets, ne marche plus. L'ordre est donc important : chaque objet dans le ressource a un numéro ou index. Le programme se repère à cet index pour pourvoir manipuler l'objet.
Exemple :
OB_H(adtree%(1),0)=12
Attention, ce n'est pas du C, mais du GFA. OB_H détermine la hauteur de l'objet 0 dans l'arbre 1. Vous aurez compris que la hauteur de cet objet sera égale à 12 pixels après l'opération.
Oups, il vous faut plus d'explications.
Les objets sont regroupés en arbres : un menu est un arbre, une boîte de dialogue est un arbre... allez voir dans votre doc-dev, voulez-vous ? Les arbres sont repérés non par avec des index, mais avec des adresses. Ces dernières sont récupérées par le programme avec la fonction RSRC_GADDR(0,n,adtree%(n)).
Vous remarquez que j'emploie un tableau pour gérer les adresses de mes arbres, juste par confort.
Bien. Dans ces arbres 1 à n sont disposés des objets, avec une relation de filiation entre les objets. Tous les objets sont fils d'un cadre (G_BOX) dont l'index est 0. On peut gérer les filiations avec les fonctions OB_HEAD, OB_NEXT, OB_TAIL et OB_ORDER. On peut aussi connaître la nature des objets avec OB_TYPE, qui donne un code particulier (qu'il faut connaître) selon les objets.

Mais on parle d'objets, de filiation, ça ressemble beaucoup à du C. En fait c'est du C. Le GEM, donc l'AES, a été fait avec. Habituez-vous donc à gérér les structures (adresse+offset), les chaînes de textes (avec CHR$(0) ou nullbyte en fin de chaîne), les pointeurs ou adresses, les pointeurs sur pointeurs ou {adresses}, les champs de bits... un petit ouvrage genre 'le C facile' serait une bonne acquisition...

Par soucis de concision, je vais abréger les fontions à leur simple nom, en omettant leur paramètres. Prière d'aller voir dans la documentation.

Un peu de pratique: OB_SPEC() donne des renseignements selon le OB_TYPE de l'objet. Le plus souvent, c'est une adresse (OB_SPEC() est donc dans ce cas-là un pointeur) sur une structure. A vous de connaître la structure, car selon la nature de l'objet, elle sera différente et contiendra diverses informations qu'il vous faudra traiter.

Exemple :
Si l'objet est une chaîne de texte (G_STRING), OB_TYPE() est égal à 28, et l'OB_SPEC() est l'adresse% mémoire de la chaîne de texte. Notez qu'elle se termine par un nullbyte (CHR$(0)) comme toute chaîne C qui se respecte. On récupère ou on écrit une chaîne C avec CHAR{OB_SPEC()} (qui est une fonction GFA).
Deuxième exemple :
Si l'objet est un champ de texte éditable encadré (G_FBOXTEXT et OB_TYPE()=30), alors OB_SPEC() est une adresse% qui pointe sur la structure TEDINFO, qui est de la forme :
typedef struct
{
   BYTE    *te_ptext;          /* Zeiger auf einen String          */
   BYTE    *te_ptmplt;         /* Zeiger auf die Stringmaske       */
   BYTE    *te_pvalid;         /* Zeiger auf den Gültigkeitsstring */
   WORD     te_font;           /* Zeichensatz                      */
   WORD     te_fontid;         /* GDOS Font-ID                     */

   WORD     te_just;           /* Justierung des Textes:
                                  0 = linksbündig
                                  1 = rechtsbündig
                                  2 = zentriert                    */

   WORD     te_color;          /* Farbe                            */
   WORD     te_fontsize;       /* GDOS Font-Größe in Punkten       */
   WORD     te_thickness;      /* Rahmenbreite                     */
   WORD     te_txtlen;         /* Maximale Länge des Textes        */
   WORD     te_tmplen;         /* Länge der Stringmaske            */
} TEDINFO;
Doucement, il ne faut pas avoir peur ! En fait, pour ce qui nous concerne, nous nous occupons principalement du premier BYTE (=CHAR), c'est à dire à l'adresse% +offset 0. Les amateurs du C reconnaîtrons un pointeur. Nous avons donc un pointeur sur pointeur. C'est pour cela que, quand nous récupérons la chaîne de texte qu'on a édité (avec ce champ éditable, rappelez vous OB_TYPE()=30), on fait CHAR{{OB_SPEC()}} (double accolade). C'est une des erreurs majeures des débutants.
Vous voulez modifier la couleur de l'objet ? Faites donc WORD{OB_SPEC()+offset}=coul&. Je vous laisse calculer l'offset. Aide : les 3 premières valeurs sont des adresses donc sur 4 octets, les autres sont des mots donc sur 2 octets. Et on calcule les offsets en octets.


GEM, the final frontier...

Rien de mieux que la pratique. Je vous conseille :
d'éditer certains fichiers RSC avec un éditeur de ressource (il y en a un bien sur le cédérom #2 de STraTOS).
de créer vos propres ressources
de regarder quelques sources en GFA
de zyeuter la doc-dev... à ce propos le fichier AES.H (et quelques autres) des langages C est des plus instructif. Les noms des constantes peuvent paraître ésotériques, elles sont néanmoins employées dans le langage GEM courant. Ça vous mettra dans le bain.
J'en ai fini pour cette fois. En vous souhaitant de délicieuses nuits blanches, sans trop de maux de têtes, ni crises de colère...
N'hésitez pas à me coller un e-mail sur nef@mygale.org au cas où ça vous démangerait. On se retrouve la prochaine fois pour voir comment on fait un petit programme en GEM.



Rajah Lone
écrit le 21 Février 1998