xGUICOM : composant COM (GUI) portable pour langage Active Scripting (VBScript/JScript)

La version 1.1 :
1. ajout support du contrôle DateTimePick ;
2. ajout du contrôle MonthCalendar ;
3. ajout de la méthode LoadDialogFromRes - chargement d'un ou plusieurs dialogues à partir d'un fichier ressource .res ;
4. modification de la méthode CreateForm - si lLeft ou lTop négatifs, le dialogue sera autocentré dans l'espace de travail ;
5. modification de la méthode RemoveItem - si iIndex négatif, supprime tous les items de la liste.

Microsoft n'a pas jugé utile de doter ses langages VBScript/Jscript de la faculté de gérer une interface graphique sérieuse, y compris lorsque ceux-ci sont exécutés dans le contexte Windows Script Host. À ceux qui souhaitent, malgré tout, pouvoir en bénéficier, l'éditeur propose une solution à partir de pages DHTML interprétées par le moteur de rendu d'Internet Explorer.

Cette solution est clairement un pis-aller qui présente, à mon sens, deux inconvénients majeurs :
- le rendu final est susceptible de varier en fonction des évolutions qui sont ou seront apportées au moteur de rendu d'un produit aussi stratégique qu'IE ;
- l'interprétation effective de la page n'est pas vraiment conforme à la logique de la programmation impérative suivie par le langage lui-même et nécessite une écriture souvent verbeuse.

Pour y remédier, il existe déjà sur le net plusieurs composants COM gratuits qui permettent la création et la gestion d'une interface graphique :
- WshDialog écrit en VB6 qui utilise plusieurs autres composants ActiveX ce qui ne simplifie malheureusement pas le déploiement ;
- Quick prompts, simple, sans dépendances particulières, mais limité par sa licence à un usage non commercial ;
- WindowSystemObject (WSO) le composant de loin le plus puissant et complet (presque trop) offrant notamment la possibilité d'insérer les composants ActiveX visuels de son choix. La documentation est rigoureuse et complète mais uniquement en anglais (ou russe).

Pourquoi un "yet another" alors qu'il existe une telle offre ? Tout simplement parce que ces solutions présentent toutes les mêmes faiblesses :
- obligation préalable d'inscrire le composant dans la base de registre, sauf à rédiger un manifest, mais la complexité de l'interface ne facilite pas son écriture ;
(pour plus de détails, voir cet article)
- la disposition des contrôles dans la boîte de dialogue se fait à l'aveuglette ce qui rend très pénible la création des masques même si le composant QuickPrompts propose un "automatic form layout" utile pour les dialogues simples.

xGUICOM évite ces deux écueils puisqu'il n'a pas besoin d'être obligatoirement enregistré s'il est référencé par un moniker. Par ailleurs, si les méthodes traditionnelles de création et d'ajout de contrôles sont présentes dans le composant, celui-ci a la capacité d'exploiter des ressources binaires créées par des éditeurs externes, ce qui autorise une création confortable et visuelle de la boîte de dialogue.

Bien évidemment, il ne s'agit pas de rivaliser avec des librairies comme QT ou wxWidgets mais plus modestement de permettre l'écriture rapide d'une interface efficace pour des scripts ponctuels. Cette version 1.1 supporte néanmoins plus d'une quinzaine de contrôles de base dont vous trouverez la description détaillée ci-dessous.

xGUICOM se présente sous la forme d'un Windows Script Component (WSC), c'est-à-dire un composant COM écrit dans un langage de script interprété, en l'occurrence le VBScript. C'est un simple fichier texte dénommé xGuiCom.wsc. Cela permet à xGUICOM de proposer plusieurs niveaux d'utilisation :
- le niveau (très) basique qui consiste à traiter le dialogue créé par xGUICOM comme une MsgBox géante dont il reproduit le comportement sans se soucier de gérer les évènements de celui-ci ;
- le niveau intermédiaire qui s'attache à gérer les évènements déclenchés par les actions de l'utilisateur et de récupérer les valeurs des contrôles avant la fermeture du dialogue ;
- le niveau avancé qui ne concerne a priori qu'une petite minorité d'utilisateurs et qui consiste à modifier directement le contenu du composant, soit pour le simplifier, soit au contraire pour y ajouter des fonctionnalités comme de nouveaux évènements. Les sections 5 et 8 s'adressent tout particulièrement à ces utilisateurs avancés ;

xGUICOM crée ses boîtes de dialogues en faisant appel à l'API Win32 de Windows. La gestion des DLL est nativement impossible en VBScript et il est donc nécessaire de recourir à un composant tiers pour y parvenir (DynamicWrapperX). Afin d'assurer son déploiement sans inscription dans la base de registre, le code du composant reprend la quasi-totalité du code décrit dans un précédent article. Seule la fonction de décodage Base64 a été légèrement modifiée pour pouvoir renvoyer une variable chaîne et pas seulement un fichier.

La section 3 contient la documentation de référence pour la mise en œuvre pratique du composant. La section 4 contient un bref tutoriel sur la manière d'utiliser un éditeur de ressources pour créer rapidement des boîtes de dialogue. Enfin, les sections 5 et 8 ne présentent d'intérêt que pour les développeurs qui voudront adapter le composant à leur convenance.

La conception d'xGUICOM s'écarte volontairement du paradigme POO pour n'en conserver que le strict minimum. Ainsi, le modèle objet du composant est réduit à un objet racine Dialog doté de dix méthodes et de sept évènements.

L'instanciation de l'objet se fait au moyen du moniker de composant, c'est-à-dire un identifiant chaîne unique composé de "script:" suivi du nom complet du fichier qui peut être une URL et terminé éventuellement par "#nomducomposant" si le fichier .wsc contient plusieurs composants distincts. La connexion sortante de l'objet n'est pas supportée dans cette configuration. Elle doit donc être réalisée séparément au moyen de la fonction ConnectObject afin de pouvoir gérer les évènements dans le script client.

Set oDlg = GetObject("script:" & Left(WScript.ScriptFullName,Len(WScript.ScriptFullName) - Len(WScript.ScriptName)) & "xGuiCom.wsc")
WScript.ConnectObject oDlg,"ev_"
                    

Les paramètres obligatoires sont mentionnés en gras. Les autres paramètres ne peuvent être omis et doivent être au moins représentés soit par une chaîne nulle, soit par la valeur zéro.

Crée une boîte de dialogue vierge sans l'afficher.
Si lLeft ou lTop sont négatifs, le dialogue sera centré dans l'espace de travail.
sCaption : chaîne - titre de la boîte.
lLeft, lTop : numérique - coordonnées relatives de l'angle haut gauche du dialogue (twips).
lWidth, lHeight : numérique - largeur et hauteur du dialogue (twips).
Valeur retournée : numérique - ID du dialogue créé (incrément automatique à partir de zéro). En cas d'erreur, renvoie -1.

Note :
La boîte créée devient le dialogue courant. Toute méthode AddControl appelée ultérieurement s'appliquera automatiquement à ce dialogue.

Ajoute un contrôle à la boîte de dialogue courante.
iID : numérique - identifiant unique entre 1..65535.
sClass : chaîne - nom de classe du contrôle (casse indifférente).
Noms supportés : commandbutton ;
                          optionbutton ;
                          checkbox ;
                          frame ;
                          edit ;
                          edpswd ;
                          memo ;
                          label ;
                          image ;
                          listbox ;
                          scrollbar ;
                          combobox ;
                          hotkey ;
                          ipcontrol ;
                          progressbar ;
                          filedlgbox.
lLeft, lTop : numérique - coordonnées relatives de l'angle haut gauche du contrôle (twips).
lWidth, lHeight : numérique - largeur et hauteur du contrôle (twips).
sData : chaîne - données initiales du contrôle.
iStyle : numérique - style propre du contrôle.
Valeur retournée : booléenne - True en cas de succès, False si l'ajout a échoué.

Note :
Selon les contrôles concernés, la syntaxe de sData sera différente :
commandbutton, optionbutton, checkbox, frame, label : légende du contrôle, chaîne libre.
edit, edpswd, memo : contenu initial du contrôle, chaîne libre.
listbox, combobox : liste des items du contrôle, chaque item est séparé par le caractère |. (ex : "poire|pomme|cerise")
hotkey : valeur initiale du contrôle, syntaxe identique à celle de la fonction VbScript SendKeys. (ex : "{^%F2}" équivaut à Ctrl + Alt + F2)
ipcontrol : valeur initiale du contrôle, chaîne conforme au format IPv4. (ex : "120.52.255.255")
filedlgbox : paramètres de la boîte de dialogue fichier séparés par le caractère | selon le format "caption|type|iodata|filename|initialdir|titre".
                 caption : chaîne, libellé du bouton d'ouverture du dialogue fichier.
                 type : 0 = OpenFileDlgBox, 1 = SaveFileDlgBox.
                 iodata : nom de variable ou ID du contrôle contenant les données en entrée (open) ou en sortie (save).
                 filename : chaîne, nom de variable ou ID du contrôle contenant le nom par défaut du fichier.
                 initialdir : chaîne, nom de variable ou ID du contrôle contenant le répertoire par défaut.
                 titre : chaîne, nom de variable ou ID du contrôle contenant le titre du dialogue.
image, scrollbar, progressbar : non exploité, peut être une chaine nulle.
Par défaut, il est assigné un style standard pour chaque contrôle et iStyle est alors égal à zéro. Le contrôle listbox est une liste classée et doté d'un ascenseur vertical, le contrôle combobox est du type dropdown avec ascenseur vertical. Il est possible d'assigner une combinaison différente de styles au contrôle en donnant au paramètre iStyle une valeur supérieure à zéro.
Néanmoins, iStyle peut avoir une signification particulière pour certains contrôles. (voir infra)

Crée une boîte de dialogue avec ses contrôles à partir de ressources binaires issues d'un éditeur externe.
sData : chaîne - nom de constante ou nom de fichier contenant les ressources. S'il s'agit d'une constante du script, les ressources sont codées en Base64.
Valeur retournée : numérique - ID du dialogue créé (incrément automatique à partir de zéro). En cas d'erreur, renvoie un nombre négatif :
-1 : objets ADO.Stream et FileSystem absents si sData est un nom de fichier existant ;
-2 : fichier et constante inexistants ;
-3 : format fichier binaire incorrect ;
-4 : erreur initialisation.

Note :
La boîte créée devient le dialogue courant. Toute méthode AddControl appelée ultérieurement s'appliquera automatiquement à ce dialogue.

Affiche la boîte de dialogue portant l'ID correspondant.
iIDD : numérique - identifiant de la boîte de dialogue préalablement créée par la méthode CreateForm ou LoadLayoutFromRes.
bOnTaskBar : booléen - flag d'affichage du script dans la barre des tâches, True = affiché False = non affiché, par défaut False.
Valeur retournée : numérique
-1 : erreur ;
0 : fermeture bouton système ;
1 : fermeture bouton par défaut ;
2 : fermeture touche Esc ou bouton "Annuler";
3..7 : ID du bouton contrôle actionné.

Note :
Les valeurs renvoyées reproduisent le comportement de la boîte de dialogue native de VbScript appelée par la fonction MsgBox. Cela implique qu'il existe des valeurs réservées pour le choix des ID (voir infra).

Lit la valeur du contrôle iID contenu dans le dialogue d'handle hWndDlg.
iID : numérique - identifiant du contrôle ;
hWndDlg : numérique - handle de la boîte de dialogue ;
Valeur retournée : dépend de la nature du contrôle (voir infra pour chaque contrôle). Si erreur renvoie VbNull.

Note : cette méthode permet notamment lors de l'évènement Close de récupérer les valeurs de certains contrôles du dialogue. S'applique aux contrôles OptionButton, CheckBox, Frame, Edit, EdPswd, Memo, ListBox, ComboBox, Image, HotKey et IPControl.

Assigne la valeur sData au contrôle iID contenu dans le dialogue d'handle hWndDlg.
iID : numérique - identifiant du contrôle ;
hWndDlg : numérique - handle de la boîte de dialogue ;
vData : chaîne/numérique - valeur assignée au contrôle, elle dépend de sa nature (voir infra pour chaque contrôle) ;
Valeur retournée : True ou False en cas d'erreur.

Note : cette méthode est particulièrement utile lors des évènements Create, Click ou Change pour mettre à jour certains contrôles du dialogue. S'applique aux contrôles OptionButton, CheckBox, Frame, Edit, EdPswd, Memo, ListBox, ComboBox, Image, HotKey et IPControl.

Ajoute un item sData à un contrôle ListBox ou ComboBox au rang d'iIndex.
Si iIndex = -1, l'item sera placé en fin de liste.
iID : numérique - identifiant du contrôle ;
hWndDlg : numérique - handle de la boîte de dialogue ;
sData : chaîne - contenu de l'item ;
iIndex : rang d'insertion de l'item (base 0) ;
Valeur retournée : rang effectif de l'item inséré ou -1 si erreur.

Retire un item sData de rang iIndex d'un contrôle ListBox ou ComboBox.
Si iIndex est négatif, tous les items de la liste seront supprimés.
iID : numérique - identifiant du contrôle ;
hWndDlg : numérique - handle de la boîte de dialogue ;
iIndex : rang de l'item à supprimer (base zéro) ;
Valeur retournée : nombre d'items après suppression ou -1 si erreur.

Convertit un fichier binaire en une chaîne au format B64.
sFileName : nom complet du fichier binaire cible ;
Valeur retournée : chaîne au format B64 contenant les données binaires.

Note : cette méthode n'a pas de rapport direct avec la gestion de la boîte de dialogue. Sa présence permet de simplifier l'intégration d'un dialogue sous forme binaire au sein d'un script client (voir l'exemple fourni BuildConstFromBin.vbs).

Crée une boîte de dialogue avec ses contrôles à partir de ressources issues d'un éditeur externe.
Ces ressources au format compilé res peuvent contenir plusieurs dialogues et iIndex précise le rang du dialogue choisi.
sData : chaîne - nom de constante ou nom de fichier res contenant les ressources. S'il s'agit d'une constante du script, les ressources sont codées en Base64.
iIndex : numérique - indice du dialogue sélectionné dans le fichier (base zéro).
Valeur retournée : numérique - ID du dialogue créé (incrément automatique à partir de zéro). En cas d'erreur, renvoie un nombre négatif :
-1 : objets ADO.Stream et FileSystem absents si sData est un nom de fichier existant ;
-2 : fichier et constante inexistants ;
-3 : format fichier binaire incorrect ;
-4 : erreur initialisation ;
-5 : dialogue introuvable.

Note :
La boîte créée devient le dialogue courant. Toute méthode AddControl appelée ultérieurement s'appliquera automatiquement à ce dialogue.

Éventuellement déclenché lors du premier appel des méthodes CreateForm et LoadLayoutFromRes. Il ne sera pas activé si le composant COM DynamicWapperX est déjà enregistré dans la base de registre.

Sub ev_Launch
  Set oShell = CreateObject("WScript.Shell")
  oShell.Run "WScript.exe " & Chr(34) & WScript.ScriptFullName & Chr(34)
  WScript.Quit
End Sub
                     

Déclenché lors de la création effective de la boîte de dialogue par Windows. Les contrôles existent et il est donc possible de les initialiser avec des valeurs différentes de celles définies par AddControl ou par les données de ressources binaires.
iIDD : numérique - identifiant unique du dialogue de zéro à n.
hWndDlg : numérique - handle de la fenêtre de dialogue.

Déclenché à la fermeture de la boîte de dialogue avant sa destruction. Comme la fenêtre existe encore à ce stade, c'est l'endroit idéal pour lire les valeurs utiles du dialogue entrées ou sélectionnées par l'utilisateur.
iIDD : numérique - identifiant unique du dialogue de zéro à n.
hWndDlg : numérique - handle de la fenêtre de dialogue.
iID : numérique - identifiant unique du contrôle qui est à l'origine de la fermeture. Si c'est le bouton de la barre système, iID sera égal à zéro. Cette valeur est également retournée par la méthode Show.

Déclenché par l'action du l'utilisateur sur un contrôle gérant cet évènement. Les contrôles concernés sont CommandButton, OptionButton, CheckBox et Frame.
iIDD : numérique - identifiant unique du dialogue de zéro à n.
hWndDlg : numérique - handle de la fenêtre de dialogue.
iID : numérique - identifiant unique du contrôle qui est à l'origine de l'évènement.

Déclenché par un changement de la valeur d'un contrôle gérant cet évènement. Les contrôles concernés sont Edit, EdPswd, Memo et ListBox.
iIDD : numérique - identifiant unique du dialogue de zéro à n.
hWndDlg : numérique - handle de la fenêtre de dialogue.
iID : numérique - identifiant unique du contrôle qui est à l'origine de l'évènement.

Déclenché après la fermeture du dialogue système permettant de sélectionner un fichier à ouvrir.
iIDD : numérique - identifiant unique du dialogue de zéro à n.
hWndDlg : numérique - handle de la fenêtre de dialogue.
iID : numérique - identifiant unique du contrôle qui est à l'origine de l'évènement.
sFileName : chaîne - nom complet du fichier qui a été sélectionné par l'utilisateur.

Déclenché après la fermeture du dialogue système permettant de sélectionner un nom de fichier à sauvegarder.
iIDD : numérique - identifiant unique du dialogue de zéro à n.
hWndDlg : numérique - handle de la fenêtre de dialogue.
iID : numérique - identifiant unique du contrôle qui est à l'origine de l'évènement.
sFileName : chaîne - nom complet du fichier qui a été sélectionné par l'utilisateur.

Les contrôles décrits dans la présente section sont ceux reconnus par la méthode AddControl. Il en existe d'autres qui peuvent être créés par un éditeur de ressources et qui seront reconnus par la méthode LoadLayoutFromRes. Toutefois, le code du composant devra être complété pour permettre leur gestion spécifique.

Bouton de commande destiné à être actionné ou cliqué par l'utilisateur.
iID : choix libre entre 1 et 65535.

sData : chaîne - légende du bouton de commande, le raccourci clavier est précédé du caractère &.
iStyle : une valeur égale à zéro assigne un style standard au bouton. Une valeur égale à un définit le bouton par défaut. Pour modifier en profondeur le style du contrôle, se reporter à la documentation MSDN Library.

Bouton radio permettant de définir des options alternatives. À utiliser par groupe de deux minimum.
iID : choix libre entre 8 et 65535.
sData : chaîne - légende du bouton radio, le raccourci clavier est précédé du caractère &.
iStyle : une valeur égale à un initialise le bouton en lui donnant le statut sélectionné. Pour modifier en profondeur le style du contrôle, se reporter à la documentation MSDN Library.

GetValueFromID : numérique - lit le statut du bouton - 0 : non pressé, 1 : pressé.
vData : numérique - fixe le statut du bouton - 0 : non pressé, 1 : pressé.

Case à cocher permettant de sélectionner des paramètres.
iID : choix libre entre 8 et 65535.
sData : chaîne - légende de la case à cocher, le raccourci clavier est précédé du caractère &.
iStyle : une valeur égale à un initialise la case en lui donnant le statut coché. Pour modifier en profondeur le style du contrôle, se reporter à la documentation MSDN Library.

GetValueFromID : numérique - lit le statut du bouton - 0 : non pressé, 1 : pressé.
vData : numérique - fixe le statut du bouton - 0 : non pressé, 1 : pressé.

Cadre permettant de regrouper visuellement des contrôles dans le dialogue. Ce contrôle est indispensable pour gérer les groupes de contrôles OptionButton.
iID : choix libre entre 8 et 65535.
sData : chaîne - légende du cadre (facultatif), le raccourci clavier est précédé du caractère &.
iStyle : par défaut zéro, pour modifier en profondeur le style du contrôle, se reporter à la documentation MSDN Library.

Contrôle permettant l'édition de valeurs alphanumériques sur une seule ligne.
iID : choix libre entre 8 et 65535.
sData : chaîne - valeur initiale du contrôle.
iStyle : par défaut zéro, pour modifier en profondeur le style du contrôle, se reporter à la documentation MSDN Library.

GetValueFromID : chaîne - lit le contenu du champ.
vData : chaîne - remplace le contenu du champ par vData.

Contrôle identique au précédent à l'exception des caractères masqués, ce qui le destine à la saisie des mots de passe.
iID : choix libre entre 8 et 65535.
sData : chaîne - valeur initiale du contrôle.
iStyle : par défaut zéro, pour modifier en profondeur le style du contrôle, se reporter à la documentation MSDN Library.

GetValueFromID : chaîne - lit le contenu du champ.
vData : chaîne - remplace le contenu du champ par vData.

Contrôle identique au contrôle Edit à l'exception de la saisie qui peut s'effectuer sur plusieurs lignes.
iID : choix libre entre 8 et 65535.
sData : chaîne - valeur initiale du contrôle.
iStyle : par défaut zéro, pour modifier en profondeur le style du contrôle, se reporter à la documentation MSDN Library.

GetValueFromID : chaîne - lit la première ligne du champ.
vData : chaîne - remplace la première ligne du champ par vData.

Texte statique permettant notamment de placer une légende pour les contrôles qui ne le gèrent pas.
iID : choix libre entre 8 et 65535.
sData : chaîne - contenu du contrôle, le raccourci clavier est précédé du caractère &.
iStyle : par défaut zéro, pour modifier en profondeur le style du contrôle, se reporter à la documentation MSDN Library.

Affiche une image stockée dans un fichier au format bmp.
iID : choix libre entre 8 et 65535.
sData : chaîne - nom complet du fichier contenant l'image.
iStyle : par défaut zéro, pour modifier en profondeur le style du contrôle, se reporter à la documentation MSDN Library.

GetValueFromID : chaîne - renvoie le nom complet du fichier bmp affiché.
vData : chaîne - nom complet du nouveau fichier bmp à afficher.

Contrôle affichant une liste d'items et permettant leur sélection par l'utilisateur. Suivant les dimensions de ce contrôle, une partie seulement de la liste sera affichée à la fois.
iID : choix libre entre 8 et 65535.
sData : chaîne - liste des items séparés par le caractère |.
iStyle : par défaut zéro, la liste est ordonnée et n'autorise qu'une seule sélection, pour modifier en profondeur son style, se reporter à la documentation MSDN Library.

GetValueFromID : chaîne - lit l'item sélectionné.
vData : numérique - place le curseur sur l'item d'indice vData (base zéro).

Contrôle affichant un curseur coulissant dans une barre afin de permettre d'afficher l'état d'une action ou de laisser l'utilisateur agir par le biais d'une souris.
iID : choix libre entre 8 et 65535.
sData : numérique - .
iStyle : une valeur égale à zéro définit une barre horizontale, une valeur égale à un, une barre verticale. Pour modifier en profondeur son style, se reporter à la documentation MSDN Library.

Contrôle affichant une liste déroulante d'items et l'affichage particulier de l'item sélectionné.
iID : choix libre entre 8 et 65535.
sData : chaîne - liste des items séparés par le caractère |.
iStyle : par défaut zéro, la liste n'est pas modifiable et déroulante, pour modifier en profondeur son style, se reporter à la documentation MSDN Library.

GetValueFromID : chaîne - lit l'item sélectionné.
vData : numérique - place le curseur sur l'item d'indice vData (base zéro).

Contrôle affichant un raccourci clavier et facilitant son édition directement par l'utilisateur.
iID : choix libre entre 8 et 65535.
sData : chaîne - raccourci clavier selon le format reconnu par la fonction SendKeys.
iStyle : par défaut zéro, pour modifier en profondeur son style, se reporter à la documentation MSDN Library.

GetValueFromID : chaîne - lit le raccourci du champ.
vData : chaîne - remplace le raccourci existant par celui défini dans vData (format syntaxe SendKeys()).

Contrôle affichant une adresse selon le format IPv4 et facilitant son édition par l'utilisateur.
iID : choix libre entre 8 et 65535.
sData : chaîne - adresse IPv4 conforme soit quatre groupes de trois chiffres séparés par un point.
iStyle : par défaut zéro, pour modifier en profondeur son style, se reporter à la documentation MSDN Library.

GetValueFromID : chaîne - lit le contenu du champ.
vData : chaîne - remplace le contenu du champ par vData.

Contrôle permettant d'afficher visuellement la progression d'une opération normalement invisible.
iID : choix libre entre 8 et 65535.
sData : numérique - (non géré).
iStyle : par défaut zéro, pour modifier en profondeur son style, se reporter à la documentation MSDN Library.

Contrôle affichant un bouton de commande destiné à être actionné ou cliqué par l'utilisateur. Lorsqu'il est sollicité, le contrôle affiche un dialogue système, soit pour ouvrir un fichier, soit pour le sauvegarder.
iID : choix libre entre 8 et 65535.
sData : chaîne - paramètres de la boîte de dialogue fichier séparés par le caractère | selon le format "caption|type|iodata|filename|initialdir|titre".
             caption : chaîne, libellé du bouton d'ouverture du dialogue fichier.
             type : 0 = OpenFileDlgBox, 1 = SaveFileDlgBox.
             iodata : nom de variable ou ID du contrôle contenant les données en entrée (open) ou en sortie (save).
             filename : chaîne, nom de variable ou ID du contrôle contenant le nom par défaut du fichier.
             initialdir : chaîne, nom de variable ou ID du contrôle contenant le répertoire par défaut.
             titre : chaîne, nom de variable ou ID du contrôle contenant le titre du dialogue.
iStyle : une valeur égale à zéro assigne un style standard au bouton. Une valeur égale à un définit le bouton par défaut. Pour modifier en profondeur le style du contrôle, se reporter à la documentation MSDN Library.

Contrôle affichant un champ date. Un bouton déroulant permet d'afficher un calendrier mensuel pour faciliter la saisie.
iID : choix libre entre 8 et 65535.
sData : chaîne représentant une date au format jj/mm/aaaaa ou jj/mm/aa. Par défaut, la date courante est affichée.
iStyle : par défaut zéro, pour modifier en profondeur son style, se reporter à la documentation MSDN Library.

GetValueFromID : chaîne - lit le contenu du champ.
vData : chaîne - remplace le contenu du champ par vData.

Contrôle affichant un calendrier mensuel permettant une navigation afin de sélectionner une date.
iID : choix libre entre 8 et 65535.
sData : chaîne représentant une date au format jj/mm/aaaaa ou jj/mm/aa. Par défaut, la date courante est affichée.
iStyle : par défaut zéro, pour modifier en profondeur son style, se reporter à la documentation MSDN Library.

GetValueFromID : chaîne - lit le contenu du champ.
vData : chaîne - remplace le contenu du champ par vData.

La possibilité de définir visuellement les boîtes de dialogue est un avantage notable de xGUICOM. Pour illustrer cette fonctionnalité, j'ai retenu l'éditeur Resource Hacker bien connu de tous les bidouilleurs. Comme il ne permet pas de créer un fichier ressource .res mais seulement de modifier un fichier existant, le pack à télécharger contient un fichier Dialog.res comportant une dialogbox comme seule ressource. L'ajout et le positionnement des contrôles se font à la souris de façon intuitive. Cet article n'est pas une initiation à ce logiciel et il convient de se reporter à l'aide pour plus de détails. L'utilisateur constatera que Resource Hacker propose sur sa palette plusieurs contrôles qui ne figurent pas dans la liste de xGUICOM comme SysTreeView32, SysMonthCal32 ou encore SysTabControl32. Ces contrôles seront acceptés et affichés par xGUICOM mais il appartient à l'utilisateur de compléter le code de la DialogProc afin de gérer les notifications et messages qui leur sont spécifiques.

Après avoir défini les contrôles et leurs ID, la dialogbox peut alors être compilée puis enregistrée dans un fichier sous forme binaire et non comme une ressource (cf. menu Action). Le nom du fichier est ensuite fourni comme paramètre de la méthode LoadLayoutFromRes. Ces données peuvent également être conservées sous la forme d'une constante dont le contenu codé en Base64 sera inséré dans le script client. Pour faciliter cette mise en œuvre, l'exemple fourni dans le pack (BuildConstFromRes.vbs) permet justement de créer ou de compléter un script vbs à partir d'un fichier binaire ou d'un fichier compilé au format res.

En effet, la version 1.1 a introduit la méthode LoadDialogFromRes qui peut lire la ressource dialogue à partir d'un fichier res. À la différence des fichiers binaires, les fichiers res peuvent contenir un nombre "illimité" de ressources et le paramètre iIndex permet alors de sélectionner le dialogue souhaité. Un seul fichier peut donc contenir tous les dialogues d'un script complexe.

Resource Hacker, malgré ses qualités, est un programme déjà ancien qui n'est plus mis à jour par son auteur. Il ne prend pas en compte les contrôles plus récents comme IPControl qui est reconnu par xGUICOM. Le deuxième lien concerne un éditeur dénommé Resourcer911 ou TrueResourcer qui est un peu plus complet et qui autorise également la sauvegarde individuelle d'une ressource sous forme binaire.
Malheureusement, cet éditeur en version "bêta" ne sait pas générer des fichiers ressources valides...

Aussi parmi les éditeurs disponibles, j'ai retenu une application proposée par un auteur danois, application qu'il a appelé de façon très originale ResourceEditor. À la différence d'un grand classique comme ResEdit, ResourceEditor ne masque pas d'autorité le paramètre title des propriétés des contrôles qui normalement ne le supportent pas. Cela permet d'initialiser ces contrôles directement à partir de la ressource. Il a toutefois un défaut étrange puisqu'il arme automatiquement le mot de poids fort du champ ID de chaque contrôle (v0.9.0.819). Il faut en tenir compte lors de la gestion des évènements.

L'interface xGUICOM est constituée par des boîtes de dialogue modales générées par l'API de Windows. Leur logique de fonctionnement est celle décrite dans le chapitre "Dialog Boxes" de la documentation MSDN Library. En conséquence, toute la partie navigation dans l'interface est gérée automatiquement par le dialogue ce qui permet d'alléger le code. Comme le dialogue modal devait pouvoir être créé à partir de données du script et qu'il devait être également possible d'initialiser simplement les contrôles, le choix de la fonction DialogBoxIndirectParam s'imposait.

Après son instanciation, le composant doit appeler une fois la fonction Initialize. Cette dernière permet d'une part, d'assurer l'instanciation du composant DynamicWrapperX quel que soit le contexte, selon une technique décrite dans cet article et d'autre part, de définir les différentes variables globales nécessaires à son fonctionnement. Cet appel est assuré par les méthodes CreateForm, LoadLayoutFromRes ou LoadDialogFromRes.
Les données de chaque boîte de dialogue sont conservées dans deux buffers chaîne organisés en tableau, chaque dialogue correspondant à un élément de celui-ci. Le premier, DLGTEMPLATEEX(), stocke les structures DLGTEMPLATEEX et DLGITEMTEMPLATEEX définies par Microsoft et attendues par la fonction API DialogBoxIndirectParam - pour plus de détails, voir MSDN Library - et le second aDataDlg() conserve les données d'initialisation de certains contrôles qui seront traitées lors du premier appel de la DialogProc (cf. infra). La taille de ces buffers a été définie arbitrairement à 8192 octets et devra être éventuellement augmentée si les masques comportent de nombreux contrôles.
Les données issues des ressources binaires chargées par LoadLayoutFromRes sont sauvegardées dans le buffer par la fonction ParseBinRes et celles provenant d'AddControl par la fonction BuildDataDlg.

- Initialisation des contrôles

Certains contrôles peuvent recevoir une valeur initiale qu'il est intéressant de gérer lors de la définition des contrôles au lieu d'obliger le concepteur à programmer manuellement cette initialisation lors de l'évènement Create. Elle doit être effective aussi bien en création manuelle avec la méthode AddControl qu'avec la création assistée par un éditeur de ressources.

CommandButton, OptionButton et CheckBox peuvent, outre le paramètre title définissant la légende, recevoir une valeur numérique au moyen du paramètre style que l'on définira aussi bien avec AddControl qu'avec un éditeur.

Label, Frame, Edit, Edpswd et Memo peuvent recevoir le paramètre chaîne title qui sera pris en compte sans traitement particulier.

ListBox, Image, ComboBox, HotKey, IPControl et FileDlgBox nécessitent un code d'initialisation.
ListBox : les données du paramètre title sont accessibles lors de l'appel initial de la DialogProc avec le message WM_INITDIALOG. La chaîne est découpée en items qui alimentent la liste.
Image : les données du paramètre title sont également disponibles. Il doit s'agir du nom complet d'un fichier contenant l'image à afficher au format bmp. La mise à jour est effectuée dans la DialogProc.
ComboBox, HotKey, IPControl : pour des raisons liées à l'interprétation du contenu, le paramètre title n'est pas conservé lors de l'appel initial. Il est donc nécessaire de sauvegarder les données dans un buffer avant d'appeler la fonction DialogBoxIndirectParam. Les fonctions ParseHotKey et ParseIPStr assurent l'encodage de ces données dans un format compréhensible pour ces contrôles.
FileDlgBox : il s'agit d'un pseudo-contrôle qui est traité comme un CommandButton. Le paramètre title contient les données du dialogue système. Elles seront traitées chaque fois que l'utilisateur actionne le contrôle bouton par la fonction BuildOpenFileName.
DateTimePick et MonthCalendar : Ils n'exploitent pas non plus le paramètre title qui n'est pas directement lisible. Aussi la fonction ParseDateTime assure l'encodage reconnu par ces contrôles.

La fonction DialogProc est strictement celle décrite dans la documentation de la fonction API DialogBoxIndirectParam. Elle reçoit les notifications des contrôles et permet de définir les évènements que l'on souhaite transmettre au script client. Son appel, lors de la création du dialogue, permet d'initialiser les contrôles qui nécessitent un code spécifique.

Téléchargement du pack complet : composant, exemple et fichier ressource.
Site Resource Hacker.
Editeur Resourcer911 : lien direct package zip.
ResourceEditor

Je tiens à remercier bbil, ALT et Claude LELOUP pour leur relecture attentive et leurs observations pertinentes.