HCDialog 3.8 XCMD (décembre 2004)

HCDialog est une commande externe universelle de gestion de boîtes de dialogue avec HyperCard.
Elle permet de modifier par script le nom des rubriques (items) de la boîte de dialogue et leur état (activé, visible, etc.)
Elle permet d' ouvrir plusieurs dialogues simultanément; pour chacun elle restitue le nom des cases à cocher et des boutons radios activés, les options de PopUp Menus choisies et les textes éditables, bref tout ce que l'utilisateur peut actionner dans une boîte de Dialogue.

Sans quitter le dialogue, elle permet d'associer à un bouton une action : callback appelant un script présent dans la carte courante ou modification de l'aspect du dialogue en cours (activation du bouton OK par exemple).

2 modes de fonctionnement de la fenêtre de dialogue sont possibles :

HCDialog détermine elle même le mode de fonctionnement: lorsque le premier item du dialogue est un bouton, le dialogue est modal.

Paramètres d'appel

HCDialog DialogNo,[Commandes, Position, TheFont]

DialogNo : ID de la ressource DLOG créée par ResEdit pour le dialogue: la ressource DITL correspondante doit aussi avoir le même ID. Ce paramètre est obligatoire à chaque appel.
Commandes : commandes passées à l'XCMD pour modifier l'aspect des items de la boîte de dialogue.
Position : position de la fenêtre de Dialogue (par défaut centrée sur l'écran) en coordonnées (pixels) par rapport au coin supérieur gauche de l'écran.
TheFont : nom et taille de la police dans laquelle seront affichés les textes du dialogue.

Pour un dialogue modal la variable "the result" rend la liste donnant les éléments choisis:

Pour un dialogue non modal, the result est vide.

En cas d'anomalie, rend "erreur" suivi du libellé correspondant.

Construire le dialogue avec Resedit

Créez votre Dialogue avec Resedit en commençant par la ressource DLOG. Assignez lui une ID supérieure à 1000 pour éviter les conflits avec les propres ressources d'HyperCard, donnez lui un nom, choisissez le style de la fenêtre et décochez les options "close box" et "Initially visible". Si vous désirez de la couleur, choisissez "Custom color" ce qui crée une ressource "dtcb".

Ci dessous, un exemple de DLOG :

Double-cliquez le DLOG ce qui ouvre l'éditeur de DITL. Ce dernier doit obligatoirement avoir le même ID que le DLOG correspondant; donnez lui aussi le même nom.

Créez vos items en tenant compte du fait que dans le cas d'un dialog de type modal :

- le 1er item doit toujours être un bouton et qu'il s'agit du bouton par défaut (en tapant sur la touche entrée, cela revient à cliquer dessus),

- le 2ème est le bouton "Annuler" qui fait rendre "the result" = "cancel" à la commande externe.

Ci dessous, un exemple de DITL modal :

DITL

Les « user item » servent à définir un cadre, une liste, un menu local, une picture ou une icone. Les boutons radio appartenant à un même groupe (quand on en clique un, on désélectionne les autres) doivent être dans un ordre consécutif, sinon le groupe ne marche pas.

Voici le DLOG tel qu'affiché par HCDialog :

Enregistrez votre travail et retournez à HyperCard. Vous pouvez tester directement vos commandes, ou plus simplement aller à la carte "Outils" de cette pile pour effectuer la mise au point.

Les commandes de modification d'items de dialogue

Les commande sont séparée les unes des autres par un "return" ou un ";". Elles sont exécutées dans l'ordre où elles sont reçues; si une erreur se présente, un dialogue d'erreur signale la commande défectueuse.

Commandes d'item


Icone

Picture

Useritem
? Commande visualisation des numéros d'items sans passer par Resedit - - -------
Aplace le curseur dans le champ éditable spécifié (à défaut, c'est le premier).--------
CCommande par un item de dialogue. "C,i,Cmd" associe à l'élément i la commande interne ou externe qui sera exécutée quand vous cliquerez l'élément.-----
Ddésactive l'item de dialogue
Eactive l'item de dialogue
F "F,i,item 1,item 2,…,item n" associe une liste au useritem i comprenant les items 1 à n.--------
GG,i1,i2,i3 définit un groupe de boutons comprenant les boutons i1 à i2: lorsque vous cliquez un bouton du groupe, vous désactivez les autres. i3 est le numéro de l'item activé par défaut (par défaut: i1). Attention : les boutons radios doivent former une   ------
Hsélectionne (contraste) l'item de dialogue-------
I"I,i,ICON ID" dessine une icone dans le rectangle du useritem ou de l'icône. S'il y a une resource cicn de même ID, c'est elle qui sera dessinée.-------
KCommande de fermeture d'un dialogue en mode prompt---------
L"L,i,no,item 1,item 2,…,item n" associe un menu local au useritem i comprenant les items 1 à n. Le menu est initialisé avec l'item no de ce menu.--------
Mmasque l'item de dialogue n°i
N"N,i,valeur" préselectionne la ligne du menu égale à la valeur.----- - 
P"P,chaîne 1,chaîne 2,chaîne 3,chaîne 4" remplace les caractères ^0 à ^3 des textes statiques par chacune des chaînes spécifiées.--------
Q"Q,i,nom d'une picture en ressource" dessine l'image sur le user item.--------
Rdessine un cadre autour de l'item i et colore le rectangle avec la couleur RGBcolor (3 valeurs séparées par des ","). Pour un affichage correct des couleurs, la boîte de dialogue doit posséder une ressource 'dctb' associée.
Saffiche l'item de dialogue n°i
Tinitialise le texte d'un texte statique:éditable à "chaîne" ou met le nom d'un contrôle à "chaîne".---
Udésélectionne (contraste) l'item de dialogue-------

Association de commandes HCDialog à un item de type "contrôle" : bouton, case à cocher, bouton radio, popupmenu

La syntaxe est "C, n° de l'item, Cmd"
"Cmd" peut être :

Vous pouvez tester ce paramètre dans votre script pour déclencher l'action adéquate en fonction de l'item choisi par l'utilisateur:

On MyScript NomdeBouton
   if NomdeBouton : "titi" then
     (vos instructions...)
   else if NomdeBouton : "toto" then
     (vos instructions...)
   else…
end MyScript

Attention ! Lorsque le script comporte une erreur, HyperCard n'exécute pas le rétro-appel et ne signale rien. Vérifiez soigneusement votre script... Si vous ne trouvez pas l'erreur, appelez le script depuis un bouton pour accéder au débogueur symbolique d'HyperTalk.

Rétro-appel et passage de commandes par une variable globale

Dans le script "rétro-appelé", vous pouvez par le biais d'une variable globale, retourner de nouvelles commandes destinées à modifier le dialogue. Le nom de cette Globale est construit à partir de l'id de la ressource DLOG : "DLG"+id dialogue + "cmds"

exemple: DLOG ID=1128.

On myScript NomdeBouton
   Global DLG1128Cmds
   (vos instructions donnant les modifications d'items à effectuer...)
   put commandes into DLG1128Cmds
end myScript

Lorsque myScript aura été exécuté, HCDialog exécutera les commandes passées par la variable globale DLG1128Cmds.

Ressource Dialog Command“DCMD”

HCDialog recherche dans les fichiers ouverts la présence éventuelle d'une ressource "DCMD" de même ID que celle du dialogue spécifié : cette ressource, propre à HCDialog, contient une liste de commandes précompilées chargée au premier appel à HCDialog et exécutées avant celles passées en paramètre. On y mettra donc tout ce qui est commun, quelque soit la situation : la définition des groupes de boutons radios par exemple.
On peut créer aussi la ressource DCMD avec Resedit en ouvrant celle-ci comme une ressource TEXT. La syntaxe est la même que le passage ordinaire de paramètres.

En présence d'une ressource DCMD, les commandes qu'elle contient sont exécutées en priorité à celles passées en paramètre.
On peut inhiber la DCMD par le biais de la variable globale HCDLogDebugIt : si dans votre script vous faites :

Global HCDLogDebugIt
put "*" into HCDLogDebugIt -- inhibe le chargement de la DCMD
…
put " " into HCDLogDebugIt -- restaure le chargement de la DCMD

La carte "HCDialog Outils" de cette pile permet de créer la ressource "DCMD" associée au dialogue.

Problèmes Classiques