1. Introduction▲
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.0 supporte néanmoins une quinzaine de contrôles de base dont vous trouverez la description détaillée ci-dessous.
2. Présentation de xGUICOM▲
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.
Pour des raisons d'encombrement, le code des fichiers binaires n'a pas été reproduit dans le script ci-dessous mais il est présent dans l'exemplaire téléchargeable dont le lien se trouve à la section 6.
3. Référence▲
3-1. Objet▲
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 neuf méthodes et de sept évènements.
3-1-1. Dialog▲
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.
L'instanciation correcte de l'objet est ainsi assurée en VBScript de la façon suivante (oDlg est le nom de l'instance de l'objet Dialog et "ev_" le nom du préfixe) ou son équivalent dans un autre langage :
Set oDlg = GetObject("script:" & Left(WScript.ScriptFullName,Len(WScript.ScriptFullName) - Len(WScript.ScriptName)) & "xGuiCom.wsc")
WScript.ConnectObject oDlg,"ev_"3-2. Méthodes▲
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.
3-2-1. CreateForm(sCaption, lLeft, lTop, lWidth, lHeight)▲
Crée une boîte de dialogue vierge sans l'afficher.
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.
3-2-2. AddControl(iID, sClass, lLeft, lTop, lWidth, lHeight[, sData, iStyle])▲
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 : "{^?}" é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)
3-2-3. LoadLayoutFromRes(sData)▲
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.
3-2-4. Show(iIDD, bOnTaskBar)▲
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).
3-2-5. GetValueFromID(iID, hWndDlg)▲
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.
3-2-6. SetValueFromID(iID, hWndDlg, vData)▲
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.
3-2-7. AddItem(iID, hWndDlg, sData, iIndex)▲
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.
3-2-8. RemoveItem(iID, hWndDlg, iIndex)▲
Retire un item sData de rang iIndex d'un contrôle ListBox ou ComboBox.
iID : numérique - identifiant du contrôle ;
hWndDlg : numérique - handle de la boîte de dialogue ;
iIndex : rang de l'item à supprimer (base 0) ;
Valeur retournée : nombre d'items après suppression ou -1 si erreur.
3-2-9. BinToB64(sFileName)▲
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).
3-3. Evénements▲
3-3-1. Launch▲
É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.
Si ce composant DynamicWapperX n'a pas été enregistré, l'évènement doit alors impérativement être géré par le code VBScript suivant ("ev_" est un préfixe arbitraire) ou son équivalent dans un autre langage :
Sub ev_Launch
Set oShell = CreateObject("WScript.Shell")
oShell.Run "WScript.exe " & Chr(34) & WScript.ScriptFullName & Chr(34)
WScript.Quit
End Sub3-3-2. Create(iIDD, hWndDlg)▲
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.
Attention, seule la méthode Show crée une boîte de dialogue. Comme son nom ne l'indique pas, la méthode CreateForm construit seulement une structure de données complétée par AddControl qui sera ensuite exploitée par Show.
3-3-3. Close(iIDD, hWndDlg,iID)▲
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.
3-3-4. Click(iIDD, hWndDlg, iID)▲
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.
3-3-5. Change(iIDD, hWndDlg, iID)▲
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.
3-3-6. Open(iIDD, hWndDlg, iID, sFileName)▲
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.
3-3-7. Save(iIDD, hWndDlg, iID, sFileName)▲
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.
3-4. Contrôles▲
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.
3-4-1. CommandButton▲
Bouton de commande destiné à être actionné ou cliqué par l'utilisateur.
iID : choix libre entre 1 et 65535.
Les valeurs 1 à 7 permettent de créer des boutons de fermeture et d'émuler ainsi le comportement de la fonction MsgBox. Les boutons créés avec des valeurs supérieures à 7 ne déclencheront que l'évènement Click.
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.
3-4-2. OptionButton▲
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é.
Il est nécessaire de regrouper ces contrôles dans un contrôle Frame. Il suffit de les ajouter immédiatement après un Frame.
3-4-3. CheckBox▲
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é.
3-4-4. Frame▲
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.
3-4-5. Edit▲
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.
3-4-6. EdPswd▲
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.
3-4-7. Memo▲
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.
3-4-8. Label▲
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.
3-4-9. Image▲
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.
3-4-10. ListBox▲
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).
3-4-11. ScrollBar▲
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.
Sa mise en œuvre suppose une gestion des notifications envoyées par le contrôle. Cette gestion dépend étroitement des objectifs recherchés. Aussi ce composant ne propose pas de code générique et il appartient à l'utilisateur de l'écrire.
3-4-12. ComboBox▲
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).
3-4-13. HotKey▲
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()).
3-4-14. IPControl▲
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.
3-4-15. ProgressBar▲
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.
Sa mise en œuvre requiert la création d'un timer gérant l'état d'avancement de l'opération décrite par le contrôle. La nature de ce timer étant étroitement liée à ladite opération, ce composant ne propose pas de code générique et il appartient à l'utilisateur de l'écrire.
3-4-16. FileDlgBox▲
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.
4. Création de boîtes de dialogue avec l'éditeur de ressources▲
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 (BuildConstFromBin.vbs) permet justement de créer ou de compléter un script vbs à partir d'un fichier binaire.
Le champ texte de chaque contrôle permet d'y ajouter les valeurs décrites dans la section référence. Deux contrôles présentent
une particularité :
- Image (ou Bitmap) : le style WS_TABSTOP doit impérativement être défini ;
- FileDlgBox : ce contrôle n'existe pas réellement et doit être remplacé par le contrôle CommandButton. C'est le format
du texte (caption|type) qui permettra à xGUICOM de l'identifier comme un FileDlgBox.
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.
5. Analyse▲
Il est considéré comme acquis que le lecteur maitrise les principes de base de la programmation Win32.
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 ou LoadLayoutFromRes.
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.
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.
6. Liens▲
Téléchargement du pack complet : composant, exemple et fichier ressource.
Site Resource Hacker.
Editeur Resourcer911 : lien direct package zip.
7. Remerciements▲
Je tiens à remercier bbil, ALT et Claude LELOUP pour leur relecture attentive et leurs observations pertinentes.