Les boîtes de dialogue de langage utilisateur vous permettent de définir une interface personnalisée dans un programme de langage utilisateur. Les boîtes de dialogue de langage utilisateur sont décrites en détail dans les sections ci-dessous :
Les boîtes de dialogue prédéfinies permettent d’implémenter les boîtes de dialogue standard fréquemment utilisées pour sélectionner des noms de fichiers ou afficher des messages d’erreur.
Pour savoir comment définir vos propres boîtes de dialogue utilisateur complexes, reportez-vous à la section Objets de boîte de dialogue.
Fonction
Affiche une boîte de dialogue de répertoire.
Syntaxe
string dlgDirectory(string Title[, string Start])Résultat
La fonction dlgDirectory renvoie le chemin d’accès complet du répertoire sélectionné. Si l’utilisateur annule la boîte de dialogue, le résultat est une chaîne vide.
Voir aussi dlgFileOpen
La fonction dlgDirectory affiche une boîte de dialogue de répertoire dans laquelle l’utilisateur peut sélectionner un répertoire. L’argument Title spécifie le titre de la boîte de dialogue.
Si l’argument Start n’est pas vide, il sert de point de départ pour la fonction dlgDirectory.
Exemple
string dirName;
dirName = dlgDirectory("Select a directory", "");Fonction
Affiche une boîte de dialogue de fichier.
Syntaxe
string dlgFileOpen(string Title[, string Start[, string Filter]])
string dlgFileSave(string Title[, string Start[, string Filter]])Résultat
Les fonctions dlgFileOpen et dlgFileSave renvoient le chemin d’accès complet du fichier sélectionné. Si l’utilisateur annule la boîte de dialogue, le résultat est une chaîne vide.
Voir aussi dlgDirectory
Les fonctions dlgFileOpen et dlgFileSave affichent une boîte de dialogue dans laquelle l’utilisateur peut sélectionner un fichier. L’argument Title spécifie le titre de la boîte de dialogue.
Si l’argument Start n’est pas vide, il sert de point de départ pour la boîte de dialogue de fichier. Sinon, le répertoire actuel est utilisé.
Seuls les fichiers correspondant à l’argument Filter s’affichent. Si l’argument Filter est vide, tous les fichiers s’affichent.
Filter peut être un caractère générique simple (comme dans « *.brd ») ou une liste de caractères génériques (comme dans « *.bmp *.jpg »), ou encore contenir du texte descriptif, comme dans « Bitmap files (*.bmp) ». Si la liste déroulante « Type de fichier » de la boîte de dialogue Fichier doit contenir plusieurs entrées, elles doivent être séparées par des points-virgules doubles, comme dans « Bitmap files (*.bmp);; Other images (*.jpg *.png) ».
Exemple
string fileName;
fileName = dlgFileOpen("Select a file", "", "*.brd");Fonction
Affiche une boîte de message.
Syntaxe
int dlgMessageBox(string Message[, button_list])Résultat
La fonction dlgMessageBox renvoie l’index du bouton sélectionné par l’utilisateur. L’index du premier bouton de la liste button_list est 0.
Voir aussi status()
La fonction dlgMessageBox affiche le message spécifié dans une boîte de dialogue modale et attend que l’utilisateur sélectionne l’un des boutons définis dans button_list.
Si Message contient des balises HTML, les caractères « < », « > » et « & » doivent être spécifiés respectivement par <, > et &, s’ils sont censés s’afficher en tant que tels.
button_list est une liste facultative de chaînes séparées par des virgules, qui définit le jeu de boutons à afficher au bas de la boîte de message. Vous pouvez définir trois boutons maximum. Si l’argument button_list n’est pas spécifié, la valeur par défaut est « OK ».
Le premier bouton spécifié dans button_list devient le bouton par défaut (il est sélectionné si l’utilisateur appuie sur la touche ENTRÉE). Le dernier bouton de la liste devient le « bouton Annuler » (il est sélectionné si l’utilisateur appuie sur la touche Échap ou ferme la boîte de message). Si vous voulez qu’un autre bouton soit défini comme bouton par défaut, faites en sorte que son nom commence par « + ». Pour définir un autre bouton en tant que bouton Annuler, affectez-lui un nom qui commence par « - ». Si vous voulez réellement commencer le texte d’un bouton par le signe « + » ou « - », vous devez faire précéder le signe d’un caractère d’échappement.
Lorsque le texte d’un bouton contient le caractère « & », le caractère qui suit l’esperluette devient un raccourci clavier : lorsque l’utilisateur appuie sur la touche correspondante, ce bouton est sélectionné. Pour que le texte contienne réellement le caractère « & », ce dernier doit être précédé d’un caractère d’échappement.
Pour attribuer une icône à la boîte de message, définissez le premier caractère de la chaîne Message sur :
';' - for an Information
'!' - for a Warning
':' - for an ErrorToutefois, si la chaîne Message commence par l’un de ces caractères, il doit être précédé d’un caractère d’échappement.
Sous Mac OS X, seul le caractère « : » affiche une icône. Tous les autres sont ignorés.
Exemple
if (dlgMessageBox("!Are you sure?", "&Yes", "&No") == 0) {
// let's do it!
}Les objets de boîte de dialogue suivants sont utilisés pour créer une boîte de dialogue de langage utilisateur :
| dlgCell | contexte de cellule de grille |
| dlgCheckBox | case à cocher |
| dlgComboBox | champ de sélection de liste déroulante |
| dlgDialog | conteneur de base de toute boîte de dialogue |
| dlgGridLayout | contexte de présentation basée sur une grille |
| dlgGroup | champ de groupe |
| dlgHBoxLayout | contexte de présentation de zone horizontale |
| dlgIntEdit | champ de saisie de type entier |
| dlgLabel | étiquette de texte |
| dlgListBox | zone de liste |
| dlgListView | affichage sous forme de liste |
| dlgPushButton | bouton poussoir |
| dlgRadioButton | bouton radio |
| dlgRealEdit | champ de saisie de type réel |
| dlgSpacing | objet d’espacement de présentation |
| dlgSpinBox | champ de zone de sélection numérique |
| dlgStretch | objet d’étirement de présentation |
| dlgStringEdit | champ de saisie de chaîne |
| dlgTabPage | page d’onglet |
| dlgTabWidget | conteneur de page d’onglet |
| dlgTextEdit | champ de saisie de texte |
| dlgTextView | champ de visualiseur de texte |
| dlgVBoxLayout | contexte de présentation de zone verticale |
Fonction
Définit l’emplacement d’une cellule dans un contexte de présentation de grille.
Syntaxe
dlgCell(int row, int column[, int row2, int column2]) statementVoir aussi dlgGridLayout, dlgHBoxLayout, dlgVBoxLayout, Informations de présentation, Exemple complet
L’instruction dlgCell définit l’emplacement d’une cellule dans un contexte de présentation de grille.
Les index de ligne et de colonne commencent à 0. L’index de la cellule supérieure gauche est donc (0, 0).
Avec deux paramètres, l’objet de boîte de dialogue défini par l’instruction est placé dans la cellule définie par les arguments row et column. Avec quatre paramètres, l’objet de boîte de dialogue s’étend sur toutes les cellules allant de row/column à row2/column2.
Par défaut, un objet dlgCell contient un objet dlgHBoxLayout. Si la cellule contient plusieurs objets de boîte de dialogue, ils sont placés les uns à côté des autres horizontalement.
Exemple
string Text;
dlgGridLayout {
dlgCell(0, 0) dlgLabel("Cell 0,0");
dlgCell(1, 2, 4, 7) dlgTextEdit(Text);
}Fonction
Définit une case à cocher.
Syntaxe
dlgCheckBox(string Text, int &Checked) [ statement ]Voir aussi dlgRadioButton, dlgGroup, Informations de présentation, Exemple complet
L’instruction dlgCheckBox définit une case à cocher avec le texte spécifié par l’argument Text.
Si Text contient le caractère « & », le caractère qui suit l’esperluette devient un raccourci clavier : lorsque l’utilisateur appuie sur Alt+raccourci clavier, la case à cocher est activée. Pour que le texte contienne réellement le caractère « & », ce dernier doit être précédé d’un caractère d’échappement.
Les objets dlgCheckBox sont surtout utilisés dans les objets dlgGroup, mais ce n’est pas toujours le cas. Les cases à cocher d’une même boîte de dialogue doivent être associées à différentes variables Checked.
Si l’utilisateur active une case à cocher, la variable Checked associée est définie sur 1 ; sinon elle est définie sur 0. La valeur initiale de Checked détermine si la case à cocher est initialement activée. Si la variable Checked est non nulle, la case à cocher est activée initialement.
L’instruction facultative est exécutée chaque fois que l’utilisateur active ou désactive la case à cocher.
Exemple
int mirror = 0;
int rotate = 1;
int flip = 0;
dlgGroup("Orientation") {
dlgCheckBox("&Mirror", mirror);
dlgCheckBox("&Rotate", rotate);
dlgCheckBox("&Flip", flip);
}Fonction
Définit un champ de sélection de liste déroulante.
Syntaxe
dlgComboBox(string array[], int &Selected) [ statement ]
Voir aussi dlgListBox, dlgLabel, Informations de présentation, Exemple complet
L’instruction dlgComboBox définit un champ de sélection de liste déroulante basé sur le contenu du tableau spécifié par l’argument array.
La variable Selected reflète l’index de l’entrée de liste déroulante sélectionnée. L’index de la première entrée est 0.
Chaque élément du tableau définit le contenu d’une entrée de la liste déroulante. Aucune des chaînes du tableau ne peut être vide (si une chaîne est vide, elle est supprimée, de même que toutes les chaînes suivantes).
L’instruction facultative est exécutée dès que la sélection change dans l’objet dlgComboBox. Avant l’exécution de l’instruction, toutes les variables qui ont été utilisées avec des objets de boîte de dialogue sont mises à jour en fonction de leurs valeurs actuelles ; une fois l’instruction exécutée, toute modification apportée à ces variables dans l’instruction est reflétée dans la boîte de dialogue.
Si la valeur initiale de la variable Selected est en dehors de la plage des index du tableau, elle est définie sur 0.
Exemple
string Colors[] = { "red", "green", "blue", "yellow" };
int Selected = 2; // initially selects "blue"
dlgComboBox(Colors, Selected) dlgMessageBox("You have selected " + Colors[Selected]);Fonction
Exécute une boîte de dialogue de langage utilisateur.
Syntaxe
int dlgDialog(string Title) block ;Résultat
La fonction dlgDialog renvoie un nombre entier qui peut prendre une signification définie par l’utilisateur via un appel à la fonction dlgAccept().
Si la boîte de dialogue est simplement fermée, la valeur renvoyée est -1.
Voir aussi dlgGridLayout, dlgHBoxLayout, dlgVBoxLayout, dlgAccept, dlgReset, dlgReject, Exemple complet
La fonction dlgDialog exécute la boîte de dialogue définie par l’argument block. C’est le seul objet de boîte de dialogue qui est une fonction intégrée de langage utilisateur. Vous pouvez donc l’utiliser n’importe où, dans la mesure où un appel de fonction est autorisé.
Normalement, l’argument block contient uniquement d’autres objets de boîte de dialogue, mais il est également possible d’utiliser d’autres instructions de langage utilisateur, par exemple pour ajouter des objets à la boîte de dialogue de manière conditionnelle (voir le deuxième exemple ci-dessous).
Par défaut, un objet dlgDialog contient un objet dlgVBoxLayout. La présentation d’une boîte de dialogue simple ne pose donc aucun problème.
En principe, tout objet dlgDialog devrait contenir un appel à la fonction dlgAccept() pour permettre à l’utilisateur de fermer la boîte de dialogue et d’accepter son contenu.
Si vous avez juste besoin d’une simple boîte de message ou boîte de dialogue de fichier, vous pouvez utiliser plutôt l’une des boîtes de dialogue prédéfinies.
Exemples
int Result = dlgDialog("Hello") {
dlgLabel("Hello world");
dlgPushButton("+OK") dlgAccept();
};
int haveButton = 1;
dlgDialog("Test") {
dlgLabel("Start");
if (haveButton)
dlgPushButton("Here") dlgAccept();
};Fonction
Ouvre un contexte de présentation de grille.
Syntaxe
dlgGridLayout statementVoir aussi dlgCell, dlgHBoxLayout, dlgVBoxLayout, Informations de présentation, Exemple complet
L’instruction dlgGridLayout ouvre un contexte de présentation de grille.
Le seul objet de boîte de dialogue qui peut être utilisé directement dans l’instruction est dlgCell. Il définit l’emplacement d’un objet de boîte de dialogue particulier dans la présentation de grille.
Les index de ligne et de colonne commencent à 0. L’index de la cellule supérieure gauche est donc (0, 0).
Les nombres de lignes et de colonnes s’accroissent automatiquement en fonction de l’emplacement des objets de boîte de dialogue définis dans le contexte de présentation de grille. Vous n’avez donc pas à définir explicitement le nombre de lignes et de colonnes.
Exemple
dlgGridLayout {
dlgCell(0, 0) dlgLabel("Row 0/Col 0");
dlgCell(1, 0) dlgLabel("Row 1/Col 0");
dlgCell(0, 1) dlgLabel("Row 0/Col 1");
dlgCell(1, 1) dlgLabel("Row 1/Col 1");
}Fonction
Définit un champ de groupe.
Syntaxe
dlgGroup(string Title) statement
Voir aussi dlgCheckBox, dlgRadioButton, Informations de présentation, Exemple complet
L’instruction dlgGroup définit un groupe appelé Title.
Par défaut, un objet dlgGroup contient un objet dlgVBoxLayout. La présentation d’un groupe simple ne pose donc aucun problème.
Un objet dlgGroup sert principalement à contenir un jeu de boutons radio ou de cases à cocher, mais il peut aussi inclure d’autres objets dans l’instruction. Les boutons radio d’un objet dlgGroup sont numérotés à partir de 0.
Exemple
int align = 1;
dlgGroup("Alignment") {
dlgRadioButton("&Top", align);
dlgRadioButton("&Center", align);
dlgRadioButton("&Bottom", align);
}Fonction
Ouvre un contexte de présentation de zone horizontale.
Syntaxe
dlgHBoxLayout statementVoir aussi dlgGridLayout, dlgVBoxLayout, Informations de présentation, Exemple complet
L’instruction dlgHBoxLayout ouvre un contexte de présentation de zone horizontale pour l’instruction spécifiée.
Exemple
dlgHBoxLayout {
dlgLabel("Box 1");
dlgLabel("Box 2");
dlgLabel("Box 3");
}Fonction
Définit un champ de saisie de type entier.
Syntaxe
dlgIntEdit(int &Value, int Min, int Max)Voir aussi dlgRealEdit, dlgStringEdit, dlgLabel, Informations de présentation, Exemple complet
L’instruction dlgIntEdit définit un champ de saisie de type entier avec la valeur spécifiée par l’argument Value.
Si Value se situe initialement en dehors de la plage définie par les valeurs Min et Max, elle sera limitée à ces valeurs.
Exemple
int Value = 42;
dlgHBoxLayout {
dlgLabel("Enter a &Number between 0 and 99");
dlgIntEdit(Value, 0, 99);
}Fonction
Définit une étiquette de texte.
Syntaxe
dlgLabel(string Text [, int Update])Voir aussi Informations de présentation, Exemple complet, dlgRedisplay()
L’instruction dlgLabel définit une étiquette contenant le texte spécifié par l’argument Text.
Text peut être un littéral de type chaîne, comme « Hello » ou une variable de type chaîne.
Si Text contient des balises HTML, les caractères « < », « > » et « & » doivent être spécifiés respectivement par <, > et &, s’ils sont censés s’afficher en tant que tels.
Tout hyperlien externe inclus dans Text est ouvert à l’aide du programme d’application approprié.
Si le paramètre Update n’est pas 0 et que Text est une variable de type chaîne, son contenu peut être modifié (dans l’instruction d’un objet dlgPushButton, par exemple) et l’étiquette est automatiquement mise à jour. Évidemment, cette possibilité ne s’avère utile que si Text est une variable de type chaîne dédiée (et pas la variable de boucle d’une instruction for, par exemple).
Si Text contient le caractère « & » et que le focus clavier peut être attribué à l’objet qui suit l’étiquette, alors le caractère qui suit l’esperluette devient un raccourci clavier : lorsque l’utilisateur appuie sur Alt+raccourci clavier, le focus clavier est attribué à l’objet défini immédiatement après l’instruction dlgLabel. Pour que le texte contienne réellement le caractère « & », ce dernier doit être précédé d’un caractère d’échappement.
Exemple
string OS = "Windows";
dlgHBoxLayout {
dlgLabel(OS, 1);
dlgPushButton("&Change OS") { OS = "Linux"; }
}Fonction
Définit un champ de sélection de zone de liste.
Syntaxe
dlgListBox(string array[], int &Selected) [ statement ]Voir aussi dlgComboBox, dlgListView, dlgSelectionChanged, dlgLabel, Informations de présentation, Exemple complet
L’instruction dlgListBox définit un champ de sélection de zone de liste basé sur le contenu du tableau spécifié par l’argument array.
La variable Selected reflète l’index de l’entrée de zone de liste sélectionnée. L’index de la première entrée est 0.
Chaque élément du tableau définit le contenu d’une ligne de la zone de liste. Aucune des chaînes du tableau ne peut être vide (si une chaîne est vide, elle est supprimée, de même que toutes les chaînes suivantes).
L’instruction facultative est exécutée chaque fois que l’utilisateur double-clique sur une entrée de l’objet dlgListBox (voir dlgSelectionChanged pour en savoir plus sur l’appel à l’instruction en cas de simple modification de la sélection dans la liste). Avant l’exécution de l’instruction, toutes les variables qui ont été utilisées avec des objets de boîte de dialogue sont mises à jour en fonction de leurs valeurs actuelles ; une fois l’instruction exécutée, toute modification apportée à ces variables dans l’instruction est reflétée dans la boîte de dialogue.
Si la valeur initiale de Selected est en dehors de la plage d’index du tableau, aucune entrée n’est sélectionnée.
Exemple
string Colors[] = { "red", "green", "blue", "yellow" };
int Selected = 2; // initially selects "blue"
dlgListBox(Colors, Selected) dlgMessageBox("You have selected " + Colors[Selected]);Fonction
Définit un champ de sélection d’affichage sous forme de liste à plusieurs colonnes.
Syntaxe
dlgListView(string Headers, string array[], int &Selected[, int &Sort]) [ statement ]
Voir aussi dlgListBox, dlgSelectionChanged, dlgLabel, Informations de présentation, Exemple complet
L’instruction dlgListView définit un champ de sélection d’affichage sous forme de liste à plusieurs colonnes basé sur le contenu du tableau spécifié par l’argument array.
L’argument Headers est la liste d’en-têtes de colonnes séparés par des tabulations.
Selected reflète l’index de l’entrée d’affichage sous forme de liste sélectionnée dans le tableau. L’ordre dans lequel les entrées sont réellement affichées peut être différent, car le contenu d’un objet dlgListView peut être trié selon les colonnes. L’index de la première entrée est 0.
Si aucune entrée ne doit être sélectionnée initialement, la variable Selected doit être initialisée sur -1. Si la variable est définie sur -2, le premier élément (selon la colonne de tri actuelle) devient l’élément actif. Si aucune entrée d’affichage n’est sélectionnée, la valeur renvoyée est -1.
Sort définit la colonne à utiliser pour trier l’affichage sous forme de liste. Le numéro 1 est attribué à la colonne la plus à gauche. Le signe de cette variable définit la direction dans laquelle effectuer le tri (si la valeur est positive, le tri est effectué dans l’ordre croissant). Si la valeur de Sort est égale à 0 ou située en dehors du nombre correct de colonnes, aucun tri n’est effectué. La valeur renvoyée de Sort reflète la colonne et le mode de tri que l’utilisateur a sélectionnés en cliquant sur les en-têtes des colonnes de la liste. Par défaut, l’instruction dlgListView trie l’affichage sous forme de liste selon la première colonne et dans l’ordre croissant.
Chaque élément du tableau définit le contenu d’une ligne dans l’affichage sous forme de liste et doit contenir des valeurs séparées par des tabulations. Si le nombre de valeurs dans un élément du tableau est inférieur au nombre d’entrées dans la chaîne Headers, les autres champs sont vides. Si le nombre de valeurs dans un élément du tableau est supérieur au nombre d’entrées dans la chaîne Headers, les éléments en trop sont supprimés sans avertissement. Aucune des chaînes du tableau ne peut être vide (si une chaîne est vide, elle est supprimée, de même que toutes les chaînes suivantes).
Si une entrée de liste contient des sauts de ligne (\n), elle s’affiche sur plusieurs lignes.
L’instruction facultative est exécutée chaque fois que l’utilisateur double-clique sur une entrée de l’objet dlgListView (voir dlgSelectionChanged pour en savoir plus sur l’appel à l’instruction en cas de simple modification de la sélection dans la liste). Avant l’exécution de l’instruction, toutes les variables qui ont été utilisées avec des objets de boîte de dialogue sont mises à jour en fonction de leurs valeurs actuelles ; une fois l’instruction exécutée, toute modification apportée à ces variables dans l’instruction est reflétée dans la boîte de dialogue.
Si la valeur initiale de Selected est en dehors de la plage d’index du tableau, aucune entrée n’est sélectionnée.
Si Headers est une chaîne vide, le premier élément du tableau est utilisé comme chaîne d’en-tête. L’index de la première entrée est alors 1.
Vous pouvez trier le contenu d’un objet dlgListView selon n’importe quelle colonne en cliquant sur l’en-tête de cette dernière. Vous pouvez aussi permuter des colonnes en cliquant sur l’en-tête d’une colonne et en le faisant glisser. Notez qu’aucune de ces modifications n’aura d’effet sur le contenu du tableau. Si le contenu doit être trié par ordre alphanumérique, vous pouvez utiliser un tableau de type numeric string[].
Exemple
string Colors[] = { "red\tThe color RED", "green\tThe color GREEN", "blue\tThe color BLUE" };
int Selected = 0; // initially selects "red"
dlgListView("Name\tDescription", Colors, Selected) dlgMessageBox("You have selected " + Colors[Selected]);Fonction
Définit un bouton poussoir.
Syntaxe
dlgPushButton(string Text) statementVoir aussi Informations de présentation, Fonctions de boîte de dialogue, Exemple complet
L’instruction dlgPushButton définit un bouton poussoir avec le texte spécifié par l’argument Text.
Si Text contient le caractère « & », le caractère qui suit l’esperluette devient un raccourci clavier : lorsque l’utilisateur appuie sur Alt+raccourci clavier, le bouton est sélectionné. Pour que le texte contienne réellement le caractère « & », ce dernier doit être précédé d’un caractère d’échappement.
Si Text commence par le caractère « + », ce bouton devient le bouton par défaut : il sera sélectionné si l’utilisateur appuie sur la touche ENTRÉE. Si le texte commence par le caractère « - », ce bouton devient le bouton Annuler : il sera sélectionné si l’utilisateur ferme la boîte de dialogue.
assurez-vous que l’instruction d’un tel bouton Annuler contient un appel à dlgReject(). Sinon, l’utilisateur ne peut pas fermer la boîte de dialogue.
Pour que le texte commence réellement par le caractère « + » ou « - », ce dernier doit être précédé d’un caractère d’échappement.
Si l’utilisateur sélectionne un objet dlgPushButton, l’instruction spécifiée est exécutée. Avant l’exécution de l’instruction, toutes les variables qui ont été utilisées avec des objets de boîte de dialogue sont mises à jour en fonction de leurs valeurs actuelles ; une fois l’instruction exécutée, toute modification apportée à ces variables dans l’instruction est reflétée dans la boîte de dialogue.
Exemple
int defaultWidth = 10;
int defaultHeight = 20;
int width = 5;
int height = 7;
dlgPushButton("&Reset defaults") {
width = defaultWidth;
height = defaultHeight;
}
dlgPushButton("+&Accept") dlgAccept();
dlgPushButton("-Cancel") { if (dlgMessageBox("Are you sure?", "Yes", "No") == 0) dlgReject(); }Fonction
Définit un bouton radio.
Syntaxe
dlgRadioButton(string Text, int &Selected) [ statement ]Voir aussi dlgCheckBox, dlgGroup, Informations de présentation, Exemple complet
L’instruction dlgRadioButton définit un bouton radio avec le texte spécifié par l’argument Text.
Si Text contient le caractère « & », le caractère qui suit l’esperluette devient un raccourci clavier : lorsque l’utilisateur appuie sur Alt+raccourci clavier, le bouton est sélectionné. Pour que le texte contienne réellement le caractère « & », ce dernier doit être précédé d’un caractère d’échappement.
Un objet dlgRadioButton ne peut être utilisé que dans un objet dlgGroup. Tous les boutons radio d’un même groupe doivent utiliser la même variable Selected.
Si l’utilisateur sélectionne un objet dlgRadioButton, l’index de ce bouton dans l’objet dlgGroup est stocké dans la variable Selected. La valeur initiale de Selected définit le bouton radio initialement sélectionné. Si la variable Selected se situe en dehors de la plage valide pour ce groupe, aucun bouton radio n’est sélectionné. Pour assurer la sélection correcte du bouton radio, la variable Selected doit être définie avant que le premier objet dlgRadioButton ne soit défini, et ne doit pas être modifiée entre les ajouts des boutons radio suivants. Sinon, le bouton radio sélectionné (le cas échéant) est indéfini.
L’instruction facultative est exécutée chaque fois que l’utilisateur sélectionne le bouton radio.
Exemple
int align = 1;
dlgGroup("Alignment") {
dlgRadioButton("&Top", align);
dlgRadioButton("&Center", align);
dlgRadioButton("&Bottom", align);
}Fonction
Définit un champ de saisie de type réel.
Syntaxe
dlgRealEdit(real &Value, real Min, real Max)Voir aussi dlgIntEdit, dlgStringEdit, dlgLabel, Informations de présentation, Exemple complet
L’instruction dlgRealEdit définit un champ de saisie de type réel avec la valeur spécifiée par l’argument Value.
Si Value se situe initialement en dehors de la plage définie par les valeurs Min et Max, elle sera limitée à ces valeurs.
Exemple
real Value = 1.4142;
dlgHBoxLayout {
dlgLabel("Enter a &Number between 0 and 99");
dlgRealEdit(Value, 0.0, 99.0);
}Fonction
Définit un espace supplémentaire dans un contexte de présentation de zone.
Syntaxe
dlgSpacing(int Size)Voir aussi dlgHBoxLayout, dlgVBoxLayout, dlgStretch, Informations de présentation, Exemple complet
L’instruction dlgSpacing définit un espace supplémentaire dans un contexte de présentation de zone verticale ou horizontale.
L’argument Size définit le nombre de pixels de l’espace supplémentaire.
Exemple
dlgVBoxLayout {
dlgLabel("Label 1");
dlgSpacing(40);
dlgLabel("Label 2");
}Fonction
Définit un champ de sélection de zone de sélection numérique.
Syntaxe
dlgSpinBox(int &Value, int Min, int Max)Voir aussi dlgIntEdit, dlgLabel, Informations de présentation, Exemple complet
L’instruction dlgSpinBox définit un champ de saisie de zone de sélection numérique avec la valeur spécifiée par l’argument Value.
Si Value se situe initialement en dehors de la plage définie par les valeurs Min et Max, elle sera limitée à ces valeurs.
Exemple
int Value = 42;
dlgHBoxLayout {
dlgLabel("&Select value");
dlgSpinBox(Value, 0, 99);
}Fonction
Définit un espace vide extensible dans un contexte de présentation de zone.
Syntaxe
dlgStretch(int Factor)Voir aussi dlgHBoxLayout, dlgVBoxLayout, dlgSpacing, Informations de présentation, Exemple complet
L’instruction dlgStretch définit un espace vide extensible dans un contexte de présentation de zone verticale ou horizontale.
L’argument Factor définit le facteur d’étirement de l’espace.
Exemple
dlgHBoxLayout {
dlgStretch(1);
dlgPushButton("+OK") { dlgAccept(); };
dlgPushButton("Cancel") { dlgReject(); };
}Fonction
Définit un champ de saisie de chaîne.
Syntaxe
dlgStringEdit(string &Text[, string &History[][, int Size]])Voir aussi dlgRealEdit, dlgIntEdit, dlgTextEdit, dlgLabel, Informations de présentation, Exemple complet
L’instruction dlgStringEdit définit un champ de saisie de texte sur une ligne avec le texte spécifié par l’argument Text.
Si l’argument History est spécifié, les chaînes saisies par l’utilisateur sont stockées au fur et à mesure dans ce tableau de chaînes. Le champ de saisie comporte alors un bouton qui permet à l’utilisateur d’effectuer une sélection parmi les chaînes précédemment saisies. Si l’argument Size est défini sur une valeur positive, le nombre de chaînes stockées dans le tableau ne peut pas dépasser cette valeur. Si History contient des données au moment où la boîte de dialogue est ouverte, ces données seront utilisées pour initialiser l’historique. La dernière entrée utilisateur entrée est enregistrée sous l’index 0. Aucune chaîne enregistrée dans History ne peut être vide. Si une chaîne est vide, elle est supprimée, de même que toutes les chaînes suivantes.
Exemple
string Name = "Linus";
dlgHBoxLayout {
dlgLabel("Enter &Name");
dlgStringEdit(Name);
}Fonction
Définit une page d’onglet.
Syntaxe
dlgTabPage(string Title) statementVoir aussi dlgTabWidget, Informations de présentation, Exemple complet
L’instruction dlgTabPage définit une page d’onglet appelée Title et contenant l’instruction spécifiée.
Si Title contient le caractère « & », le caractère qui suit l’esperluette devient un raccourci clavier : lorsque l’utilisateur appuie sur Alt+raccourci clavier, le page d’onglet s’ouvre. Pour que le texte contienne réellement le caractère « & », ce dernier doit être précédé d’un caractère d’échappement.
Les pages d’onglets ne peuvent être utilisées que dans les objets dlgTabWidget.
Par défaut, un objet dlgTabPage contient un objet dlgVBoxLayoutdlgVBoxLayout. La présentation d’une page d’onglet simple ne pose donc aucun problème.
Exemple
dlgTabWidget {
dlgTabPage("Tab &1") {
dlgLabel("This is page 1");
}
dlgTabPage("Tab &2") {
dlgLabel("This is page 2");
}
}Fonction
Définit un conteneur pour les pages d’onglets.
Syntaxe
dlgTabWidget { tabpages }
dlgTabWidget(int &Index) { tabpages }Voir aussi dlgTabPage, Informations de présentation, Exemple complet
dlgTabWidget définit un conteneur pour un jeu de pages d’onglets.
tabpages doit être une séquence d’un ou de plusieurs objets dlgTabPage. Cette séquence ne doit contenir aucun autre objet de boîte de dialogue.
Index définit l’onglet qui doit être sélectionné initialement. Si cette sélection change, la variable Index est redéfinie. L’index de la première page est 0 (indépendamment de son titre).
Exemples
dlgTabWidget {
dlgTabPage("Tab &1") {
dlgLabel("This is page 1");
}
dlgTabPage("Tab &2") {
dlgLabel("This is page 2");
}
}
dlgDialog("test")
{
int TabNr = 0;
int CheckBoxValue[];
dlgTabWidget(TabNr) {
for (int i = 0; i <= 9; i++) {
string s;
sprintf(s, "%d", i);
dlgTabPage("Tab " + s) {
dlgLabel("This is page " + s);
dlgCheckBox(s, CheckBoxValue[i]) {
string Msg;
sprintf(Msg, "Value #%d: %d\n", TabNr, CheckBoxValue[TabNr]);
dlgMessageBox(Msg);
}
}
}
}
};Fonction
Définit un champ de saisie de texte multiligne.
Syntaxe
dlgTextEdit(string &Text)Voir aussi dlgStringEdit, dlgTextView, dlgLabel, Informations de présentation, Exemple complet
L’instruction dlgTextEdit définit un champ de saisie de texte multiligne avec le texte spécifié par l’argument Text.
Dans Text, les lignes doivent être délimitées par un caractère de retour à la ligne (\n). Tous les caractères d’espacement présents à la fin des lignes dans Text sont supprimés. Une fois l’instruction exécutée, il n’y a aucun caractère d’espacement à la fin des lignes. Les lignes vides à la fin du texte sont entièrement supprimées.
Exemple
string Text = "This is some text.\nLine 2\nLine 3";
dlgVBoxLayout {
dlgLabel("&Edit the text");
dlgTextEdit(Text);
}Fonction
Définit un champ de visualiseur de texte multiligne.
Syntaxe
dlgTextView(string Text)dlgTextView(string Text, string &Link) statement
Voir aussi dlgTextEdit, dlgLabel, Informations de présentation, Exemple complet
L’instruction dlgTextView définit un champ de visualisation de texte multiligne avec le texte spécifié par l’argument Text.
L’argument Text peut contenir des balises HTML.
Tout hyperlien externe inclus dans Text est ouvert à l’aide du programme d’application approprié.
Si Link est spécifié et que Text contient des hyperliens, l’instruction est exécutée chaque fois que l’utilisateur clique sur un hyperlien, avec la valeur de Link définie sur la valeur de href spécifiée par la balise <a href=...>. Si, après l’exécution de l’instruction, la variable Link n’est pas vide, le traitement par défaut des hyperliens est effectué. C’est aussi le cas si Link contient du texte avant l’ouverture de dlgTextView, ce qui permet un défilement initial vers une position donnée. Si un lien est spécifié, les hyperliens externes ne sont pas ouverts.
Exemple
string Text = "This is some text.\nLine 2\nLine 3"; dlgVBoxLayout { dlgLabel("&View the text"); dlgTextView(Text); }
Fonction
Ouvre un contexte de présentation de zone verticale.
Syntaxe
dlgVBoxLayout statementVoir aussi dlgGridLayout, dlgHBoxLayout, Informations de présentation, Exemple complet
L’instruction dlgVBoxLayout ouvre un contexte de présentation de zone verticale pour l’instruction spécifiée.
Par défaut, un objet dlgDialog contient un objet dlgVBoxLayout. La présentation d’une boîte de dialogue simple ne pose donc aucun problème.
Exemple
dlgVBoxLayout {
dlgLabel("Box 1");
dlgLabel("Box 2");
dlgLabel("Box 3");
}Tous les objets contenus dans une boîte de dialogue de langage utilisateur sont placés dans un contexte de présentation.
Un contexte de présentation peut se baser sur une présentation de grille, horizontale ou verticale.
Dans un contexte de présentation de grille, les objets doivent spécifier les coordonnées de grille de la ou des cellules où ils doivent être placés. Pour placer une étiquette de texte dans la cellule de la ligne 5 et la colonne 2, écrivez :
dlgGridLayout {
dlgCell(5, 2) dlgLabel("Text");
}Si l’objet doit s’étendre sur plusieurs cellules, spécifiez les coordonnées de la cellule de départ et de la cellule de fin. Ainsi, pour placer un groupe s’étendant de la ligne 1/colonne 2 à la ligne 3/colonne 5, écrivez :
dlgGridLayout {
dlgCell(1, 2, 3, 5) dlgGroup("Title") {
//...
}
}Dans un contexte de présentation horizontale, les objets sont placés de gauche à droite. Vous pouvez utiliser les objets spéciaux dlgStretch et dlgSpacing pour affiner la distribution de l’espace disponible.
Ainsi, pour définir deux boutons renvoyés complètement à droite dans la boîte de dialogue, écrivez :
dlgHBoxLayout {
dlgStretch(1);
dlgPushButton("+OK") dlgAccept();
dlgPushButton("Cancel") dlgReject();
}Dans un contexte de présentation verticale, les objets suivent les mêmes règles que dans un contexte de présentation horizontale, si ce n’est qu’ils sont placés de haut en bas.
Il est possible de combiner les contextes de présentation de grille, verticale et horizontale afin de créer la structure de présentation souhaitée pour une boîte de dialogue. Pour une démonstration, reportez-vous à l’exemple complet.
Vous pouvez utiliser les fonctions suivantes avec les boîtes de dialogue de langage utilisateur :
Fonction
Ferme la boîte de dialogue et accepte son contenu.
Syntaxe
void dlgAccept([ int Result ]);Voir aussi dlgReject, dlgDialog, Exemple complet
Avec la fonction dlgAccept, dlgDialog se ferme et renvoie une valeur une fois la séquence d’instruction en cours terminée.
Toute modification apportée aux valeurs de boîte de dialogue est acceptée et copiée dans les variables spécifiées lors de la définition des objets de boîte de dialogue.
L’argument facultatif Result est la valeur renvoyée par la boîte de dialogue. En général, il s’agit d’un entier positif. Si aucune valeur n’est indiquée, il est défini par défaut sur 1.
Notez que dlgAccept() renvoie à l’exécution normale du programme. Ainsi, dans la séquence suivante :
dlgPushButton("OK") {
dlgAccept();
dlgMessageBox("Accepting!");
}L’instruction qui suit dlgAccept() est exécutée.
Exemple
int Result = dlgDialog("Test") {
dlgPushButton("+OK") dlgAccept(42);
dlgPushButton("Cancel") dlgReject();
};Fonction
Affiche à nouveau la boîte de dialogue après modification des valeurs.
Syntaxe
void dlgRedisplay(void);Voir aussi dlgReset, dlgDialog, Exemple complet
Vous pouvez appeler la fonction dlgRedisplay pour actualiser immédiatement l’objet dlgDialog suite à des modifications apportées aux variables utilisées lors de la définition des objets de boîte de dialogue.
Vous ne devez appeler dlgRedisplay() que si vous voulez actualiser la boîte de dialogue tout en exécutant le code de programme. Dans l’exemple ci-dessous, l’état est défini sur « Running... » et la fonction dlgRedisplay() doit être appelée pour que cette modification prenne effet avant que l’action du programme s’exécute. Une fois que l’état est défini sur « Finished », il n’est pas nécessaire d’appeler dlgRedisplay(), car tous les objets de boîte de dialogue sont automatiquement mis à jour après la sortie de l’instruction.
Exemple
string Status = "Idle";
int Result = dlgDialog("Test") {
dlgLabel(Status, 1); // note the '1' to tell the label to be updated!
dlgPushButton("+OK") dlgAccept(42);
dlgPushButton("Cancel") dlgReject();
dlgPushButton("Run") {
Status = "Running...";
dlgRedisplay();
// some program action here...
Status = "Finished.";
}
};Fonction
Rétablit les valeurs initiales de tous les objets de boîte de dialogue.
Syntaxe
void dlgReset(void);Voir aussi dlgReject, dlgDialog, Exemple complet
La fonction dlgReset recopie les valeurs initiales dans tous les objets de boîte de dialogue de l’objet dlgDialog actif.
Toute modification apportée aux valeurs de boîte de dialogue par l’utilisateur est ignorée.
Tout appel à dlgReject() implique un appel à dlgReset().
Exemple
int Number = 1;
int Result = dlgDialog("Test") {
dlgIntEdit(Number);
dlgPushButton("+OK") dlgAccept(42);
dlgPushButton("Cancel") dlgReject();
dlgPushButton("Reset") dlgReset();
};Fonction
Ferme la boîte de dialogue et rejette son contenu.
Syntaxe
void dlgReject([ int Result ]);Voir aussi dlgAccept, dlgReset, dlgDialog, Exemple complet
Avec la fonction dlgReject, dlgDialog se ferme et renvoie une valeur une fois la séquence d’instruction en cours terminée.
Toute modification apportée aux valeurs de boîte de dialogue par l’utilisateur est ignorée. Les variables qui ont été spécifiées lors de la définition des objets de boîte de dialogue reprennent leurs valeurs d’origine dès que la boîte de dialogue renvoie une valeur.
L’argument facultatif Result est la valeur renvoyée par la boîte de dialogue. En général, il s’agit d’un entier négatif ou nul. Si aucune valeur n’est indiquée, il est défini par défaut sur 0.
Notez que dlgReject() renvoie à l’exécution normale du programme. Ainsi, dans la séquence suivante :
dlgPushButton("Cancel") {
dlgReject();
dlgMessageBox("Rejecting!");
}L’instruction qui suit dlgReject() est exécutée.
Tout appel à dlgReject() implique un appel à dlgReset().
Exemple
int Result = dlgDialog("Test") {
dlgPushButton("+OK") dlgAccept(42);
dlgPushButton("Cancel") dlgReject();
};Fonction
Indique si la sélection actuelle dans un objet dlgListView ou dlgListBox a changé.
Syntaxe
int dlgSelectionChanged(void);Résultat
La fonction dlgSelectionChanged renvoie une valeur non nulle si seule la sélection dans la liste a changé.
Voir aussi dlgListView, dlgListBox
Dans un contexte de liste, vous pouvez utiliser la fonction dlgSelectionChanged pour déterminer si l’instruction dlgListView ou dlgListBox a été appelée parce que l’utilisateur a double-cliqué sur un élément ou si seule la sélection actuelle dans la liste a changé.
Si une instruction dlgListView ou dlgListBox ne contient aucun appel à dlgSelectionChanged, cette instruction n’est exécutée que lorsque l’utilisateur double-clique sur un élément dans la liste. Toutefois, si un ULP doit réagir aux modifications apportées à la sélection actuelle dans la liste, il peut appeler dlgSelectionChanged dans l’instruction de la liste. Dans ce cas, l’instruction est également appelée en cas de modification de la sélection actuelle dans la liste.
Si un élément de liste est initialement sélectionné au moment où la boîte de dialogue est ouverte et que l’instruction de la liste contient un appel à dlgSelectionChanged, l’instruction est exécutée et dlgSelectionChanged renvoie true pour indiquer le changement d’état initial (de « aucune sélection » à une sélection effectuée). Les modifications apportées ultérieurement aux chaînes ou à la sélection de la liste via la programmation ne déclenchent pas l’exécution automatique de l’instruction de la liste. Tenez compte de ce fonctionnement lorsque l’élément de liste actuel contrôle un autre objet de boîte de dialogue (dans le cas d’un objet dlgTextView qui affiche une représentation étendue de l’élément actuellement sélectionné, par exemple).
Exemple
string Colors[] = { "red\tThe color RED", "green\tThe color GREEN", "blue\tThe color BLUE" };
int Selected = 0; // initially selects "red"
string MyColor;
dlgLabel(MyColor, 1);
dlgListView("Name\tDescription", Colors, Selected) {
if (dlgSelectionChanged())
MyColor = Colors[Selected];
else
dlgMessageBox("You have chosen " + Colors[Selected]);
}Certains caractères ont des significations spéciales dans les textes de boutons ou d’étiquettes. Lorsque vous voulez les afficher littéralement, vous devez donc les faire précéder d’un caractère d’échappement. Pour ce faire, ajoutez une barre oblique inverse devant le caractère, comme dans l’exemple suivant :
dlgLabel("Miller \\& Co.");Ainsi, la chaîne « Miller & Co. » s’affiche dans la boîte de dialogue. Notez qu’il y a ici deux barres obliques inverses, car la ligne passe d’abord par l’analyseur du langage utilisateur, qui supprime la première barre oblique inverse.
Voici un exemple complet de boîte de dialogue de langage utilisateur :
int hor = 1;
int ver = 1;
string fileName;
int Result = dlgDialog("Enter Parameters") {
dlgHBoxLayout {
dlgStretch(1);
dlgLabel("This is a simple dialog");
dlgStretch(1);
}
dlgHBoxLayout {
dlgGroup("Horizontal") {
dlgRadioButton("&Top", hor);
dlgRadioButton("&Center", hor);
dlgRadioButton("&Bottom", hor);
}
dlgGroup("Vertical") {
dlgRadioButton("&Left", ver);
dlgRadioButton("C&enter", ver);
dlgRadioButton("&Right", ver);
}
}
dlgHBoxLayout {
dlgLabel("File &name:");
dlgStringEdit(fileName);
dlgPushButton("Bro&wse") {
fileName = dlgFileOpen("Select a file", fileName);
}
}
dlgGridLayout {
dlgCell(0, 0) dlgLabel("Row 0/Col 0");
dlgCell(1, 0) dlgLabel("Row 1/Col 0");
dlgCell(0, 1) dlgLabel("Row 0/Col 1");
dlgCell(1, 1) dlgLabel("Row 1/Col 1");
}
dlgSpacing(10);
dlgHBoxLayout {
dlgStretch(1);
dlgPushButton("+OK") dlgAccept();
dlgPushButton("Cancel") dlgReject();
}
};