Laboratoire #B

Transcription

Laboratoire #B

Université du Québec
École de technologie supérieure
Département de génie de la production automatisée
Édition
2001
GPA-789 ANALYSE ET CONCEPTION ORIENTÉES OBJET
LABORATOIRE #B
GPA789  Analyse et conception orientées objet
LABORATOIRE #B
Auteur: Tony Wong, Ph.D. ing.
Département de génie de la production automatisée
École de technologie supérieure
courriel: [email protected]
 2000 – 2002 DÉPARTEMENT DE GÉNIE DE LA PRODUCTION AUTOMATISÉE. TOUS DROITS RÉSERVÉS.
Table des matières
Introduction .............................................................................................................. 1
Objectifs pédagogiques........................................................................................... 1
Contenu du laboratoire............................................................................................ 2
Spécifications de l’interface graphique .............................................................. 2
Présentation de l’interface graphique ................................................................ 2
Éléments de l’interface graphique dans MFC ................................................. 10
Panneau de dialogue ................................................................................. 11
Contrôle intitulé DISQUES......................................................................... 12
Contrôle intitulé Dossiers ........................................................................... 12
Contrôle intitulé Fichiers............................................................................. 13
Contrôle intitulé Traitement ........................................................................ 14
Contrôle intitulé Action ............................................................................... 14
Quelques conseils............................................................................................ 15
Travaux à effectuer................................................................................................ 16
Liste des manipulations ................................................................................... 17
Manipulation #1 .......................................................................................... 17
Manipulation #2 .......................................................................................... 19
Manipulation #3 ......................................................................................... 20
Manipulation #4 .......................................................................................... 26
Manipulation #5 .......................................................................................... 26
Manipulation #6 .......................................................................................... 27
Manipulation #7 .......................................................................................... 29
Manipulation #8 .......................................................................................... 31
 2000 – 2002 DÉPARTEMENT DE GÉNIE DE LA PRODUCTION AUTOMATISÉE. TOUS DROITS RÉSERVÉS.
Manipulation #9 .......................................................................................... 32
Manipulation #10........................................................................................ 35
Contenu du rapport................................................................................................ 35
Annexe................................................................................................................... 36
LABORATOIRE #B  XTRACTCOMMGUI
Section
1
Laboratoire #B
Programmation MFC  Interface graphique pour XtractComm
Introduction
Le programme XtractComm a été développé dans le premier laboratoire de ce cours.
Sa fonction consistait à saisir, par la ligne de commande, un nom de fichier d’entrée et
un nom de fichier de sortie. Le fichier d’entrée doit être un fichier source en langage
C ou C++. Le fichier de sortie, après l’exécution du programme XtractComm,
contiendra les commentaires relevés dans le fichier source d’entrée. Le programme
XtractComm fonctionne en mode console. Il ne peut traiter qu’un seul fichier source
à la fois. Son utilisation est donc difficile et peu efficace.
Dans ce deuxième laboratoire, nous allons créer une interface graphique Windows
pour le programme XtractComm. La création de cette interface graphique sera
réalisée à l’aide du cadre de travail (Framework) MFC (Microsoft Foundation Library). Le
MFC réalise l’encapsulation des éléments de l’interface graphique à l’aide de classes
C++. Ainsi, les boutons, les fenêtres, et les menus, etc. sont représentés par des
classes appropriées de MFC. Le traitement des événements et des messages
normalement associé à la programmation Windows est remplacé par des tables de
messages et des fonctions membres dédiées. Ce sont les tables de messages qui
associent les messages et événements à des fonctions membres appropriées de
différentes classes MFC. Ces fonctions membres agissent donc comme des
gestionnaires de messages et événements (message and event handlers).
L’interface graphique de XtractComm sera appelée XtractCommGUI (XtractComm
Graphical User Interface). Elle permettra aux utilisateurs de sélectionner les fichiers à
traiter d’une manière visuelle. Les utilisateurs pourront sélectionner un ensemble de
fichiers à l’aide de la souris et les soumettre à XtractComm par l’activation d’un simple
bouton.
Objectifs pédagogiques
Les objectifs pédagogiques de ce laboratoire sont énumérés ci-dessous en ordre
décroissant d’importance:

Apprendre la structure d’une application Windows utilisant le MFC.
PAGE B-1

Comprendre le principe de programmation à l’aide d’un cadre de travail orientéobjet (le MFC).

Acquérir une bonne expérience dans l’utilisation des bibliothèques de classes.

Connaître les éléments de l’interface graphique Win32.

Familiariser avec l’environnement de développement Visual C++.
Contenu du laboratoire
Cette section présente les explications détaillées de ce laboratoire. Lisez attentivement
l’exposé ci-dessous puisqu’il vous aidera certainement dans la réalisation du projet de
programmation.
Spécifications de l’interface graphique
Les caractéristiques de cette interface graphique sont :
1. Visualisation de contenu des disques de l’ordinateur. Les disques réseaux doivent
également être visibles par l’utilisateur. La présentation graphique de cette
visualisation doit être semblable à celle de l’explorateur Windows.
2. Présentation d’une liste de disques disponibles. La sélection d’un disque dans
cette liste doit provoquer l’affichage de son contenu dans l’interface graphique.
3. Affichage du contenu des dossiers dans une fenêtre séparée. Les utilisateurs
pourront alors choisir les fichiers à traiter à l’aide de la souris. De plus, les
utilisateurs doivent pouvoir sélectionner plus d’un fichier à la fois. Seuls les
fichiers portant l’extension .h, .hpp, .c, .cpp seront affichés dans cette fenêtre.
4. Activation de l’XtractComm à l’aide d’un simple bouton. Les fichiers sélectionnés
par l’utilisateur seront traités par XtractComm un par un à l’arrière plan.
5. Activation d’une barre de progression pour indiquer l’avancement des travaux
effectué par le programme XtractComm.
6. Présentation d’un panneau de message indiquant le nom et le numéro de la
version du programme XtractCommGUI.
Présentation de l’interface graphique
La présentation présentée dans la Figure 1 est une présentation suggérée pour
l’interface graphique de XtractComm. La base de l’interface est un panneau de
dialogue (Dialog Box). La liste de sélection des disques est placée juste au-dessus de la
fenêtre des dossiers.
PAGE B-2
Sélection des disques
Barre de progression
Présentation des dossiers du
disque sélectionné
*
Affichage des fichiers à
sélectionner
Figure 1 Présentation suggérée de l'interface graphique.
Dans la fenêtre des dossiers, une arborescence (CTreeCtrl) est utilisée pour présenter
les dossiers du disque sélectionné. Le premier disque rigide est toujours sélectionné
par défaut puisqu’il est le seul disque permanent de l’ordinateur.
À droite de la fenêtre des dossiers est une fenêtre montrant les fichiers (CListCtrl)
contenus dans le dossier sélectionné. Noter que seuls, les fichiers .c, .cpp, .h et
.hpp sont affichés dans cette fenêtre. La raison en est simple, les fichiers qui seront
traités par XtractComm sont ceux qui contiennent du code source C/C++. Il est
donc inutile d’afficher les autres fichiers. Les utilisateurs peuvent choisir un ou
plusieurs fichiers apparaissant dans cette fenêtre.
PAGE B-3
Le bouton libellé « Action » sert à enclencher l’extraction des commentaires contenus
dans les fichiers sélectionnés. Pendant, l’extraction des commentaires, la barre de
progression est activée par le programme pour montrer l’avancement des travaux
d’ExtractComm.
Puisque l’extraction des commentaires est réalisée par XtractComm, nous devons
effectuer des appels de système pour invoquer ce programme et lui assigner les
paramètres d’entrée nécessaires. Enfin, chaque invocation d’XtractComm extrait les
commentaires d’un fichier source. Il y aura donc autant d’invocations que de fichiers
sélectionnés par l’utilisateur.
Éléments de l’interface graphique dans MFC
Cette section présente les différents éléments de l’interface graphique à utiliser dans le
cadre de travail MFC. Vous devez consulter l’aide en-ligne de MFC pour
connaître tous les détails des classes mentionnées. Un nombre de pages d’aide
sont disponibles dans l’annexe de ce document.
Dans le jargon MFC (et de la programmation Windows en général), un élément
d’interface qui effectue des actions est appelé un élément de contrôle ou
simplement un contrôle. Dorénavant, le mot contrôle signifiera un élément graphique
tel un bouton, une liste de sélection, etc. Voici les éléments de contrôle de
l’application XtractCommGUI.
Objet CPicture inséré directement à l'aide de
l'éditeur de ressource
Objet de type CComboBox
Objet de type CListCtrl
Objet de type CTreeCtrl Objet de type CProgressCtrl
Objet de type CButton
PAGE B-10
Noter également que les contrôles de l’interface graphique XtractCommGUI sont
sélectionnés et manipulés à l’aide de l’éditeur de ressources de Visual C++. Après la
création du projet, vous pouvez sélectionner l’onglet « ResourceView » pour faire
afficher les ressources utilisées par le programme. Double cliquer sur le panneau de
dialogue (généré lors de la création du projet) pour démarrer l’éditeur de ressources.
Panneau de dialogue
Le panneau de dialogue sert de cadre pour les contrôles de XtractCommGUI. Vous
devez redimensionner la taille de ce panneau pour maintenir une bonne proportion
visuelle. Veuillez nommer ce panneau de dialogue par CXtractCommGUIDlg.
Normalement, ce nom est ajusté automatiquement par le AppWizard de Visual C++
et il joue le rôle de nom de classe de notre panneau de dialogue (classe dérivée de
CDialog).
C’est dans cette classe créée par le AppWizard que nous ajouterons le codage
nécessaire pour faire fonctionner notre programme. La classe CXtractCommGUIDlg
est dérivée de CDialog (voir le fichier généré XtractCommGUIDlg.h dans le
répertoire du projet). Un ensemble de fonctions prédéfinies sont automatiquement
ajoutées par le AppWizard dans la classe CXtractCommGUIDlg lors de la création des
fichiers CXtractCommGUIDlg.h et CXtractCommGUIDlg.h.
Ainsi, lorsque nous ajoutons d’un élément de contrôle dans ce panneau de dialogue à
l’aide de l’éditeur de ressource, nous devons également déclarer son existence dans la
déclaration de la classe CXtractCommGUIDlg.
Pour ce laboratoire, nous devons déclarer, dans la classe XtractCommGUIDlg, les
objets énumérés dans le Tableau 1. Voir la liste des manipulations afin de réaliser
cette tâche.
Objet de classe
CButton
CProgressCtrl
*
Rôle
Le bouton libellé « Action ».
La barre de progression pour indiquer l’avancement des
travaux.
CListCtrl
La liste des noms de fichiers contenus dans le dossier
sélectionné.
CTreeCtrl
La liste des dossiers du disque sélectionné mais
présentée sous forme d’arborescence.
CComboBox
La boîte de sélection pour la sélection d’un des disques
reliés à l’ordinateur (disques locaux ou disques réseaux).
Tableau 1 Objets à accès publics correspondants aux contrôles de l'interface graphique.
Nous aurons également deux autres objets pour les besoins internes du panneau de
dialogue.
PAGE B-11
Objet de classe
CString
CImageList
*
Rôle
Une chaîne de caractères représentant le chemin
courant. Le chemin courant est le chemin du dossier
sélectionné par l’utilisateur.
Une liste d’images utilisées dans la présentation des
dossiers du disque sélectionné. Les images montrant un
dossier ouvert et un dossier fermé sont entreposés dans
un objet de cette classe.
Tableau 2 Objets de support à accès privés de la classe CXtractCommGUIDlg.
Les sous-sections suivantes expliqueront le rôle de ces objets dans la globalité de
l’interface graphique XtractCommGUI.
Contrôle intitulé DISQUES
Ce contrôle est une boîte combo (de classe CComboBox de MFC). Il sert à montrer les
unités disques disponibles. L’algorithme utilisé pour la détection des unités
disques (locaux et réseaux) attachés à l’ordinateur est réalisé dans une
bibliothèque DLL que vous pourrez télécharger du site web de ce cours. Ce
contrôle est un objet de la classe CComboBox. On doit installer un gestionnaire de
message pour gérée la notification générée par l’objet de classe CComboBox .

Cette notification est envoyée par l’objet lors de la sélection
d’un article dans la boîte combo.
CBN_SELCHANGE
À la réception de ce message, on doit mettre à jour la présentation des dossiers de
l’arborescence puisque l’utilisateur a sélectionné un autre disque.
*
Figure 2 La représentation graphique d'un objet de classe CComboBox.
Contrôle intitulé Dossiers
Ce contrôle donne une arborescence (de classe CTreeCtrl de MFC) des dossiers du
disque sélectionné. Il sert à montrer les dossiers contenus dans l’unité de disque
sélectionné dans le contrôle CComboBox. L’algorithme utilisé pour la fouille des
dossiers d’un disque sélectionné est réalisé dans une bibliothèque DLL que
PAGE B-12
vous pourrez télécharger du site web de ce cours. Ce contrôle est un objet de la
classe CTreeCtrl, il a besoin d’un objet de la classe CImageList pour afficher les
images représentant les dossiers du disque sélectionné. Dans ce laboratoire, nous
utiliserons un objet de la classe CTreeCtrl pour représenter les dossiers d’une unité
de disque. Ainsi, l’objet de support (classe CImageList) doit contenir une image
montrant un dossier ouvert et une autre pour représenter un dossier fermé. Nous
devons dessiner ces images à l’aide de l’éditeur de ressources de Visual C++. Nous
devons gérer les notifications générées par l’objet de classe CTreeCtrl :

TVN_ITEMEXPANDING Répondre à cette notification lors de la sélection dans la
zone +/- de l’arbre des dossiers. Cette notification nous indiquer que l’utilisateur
désire étendre un dossier pour voir ses sous-dossiers.

TVN_SELCHANGED
Répondre à cette notification lors de la sélection d’un dossier
dans l’arborescence des dossiers. Cette notification nous indiquer que l’utilisateur
désire visualiser le contenu des fichiers dans le dossier sélectionné.
Note : Nous devons utiliser le macro ON_NOTIFY pour installer les gestionnaires de
ces deux notifications.
Image du dossier "ouvert"
Image du dossier "fermé"
Figure 3 La représentation graphique d’un objet de classe CtreeCtrl. Observer l’image dossier ouvert et dossier fermé.
Contrôle intitulé Fichiers
Ce contrôle donne une liste de fichiers (de classe CListCtrl de MFC) du dossier
sélectionné. Il sert à montrer les fichiers ligne par ligne. Le rôle de ce contrôle
ressemble à celui utilisé dans l’explorateur Windows. Nous devons filtrer les fichiers
et ne conserver que ceux portant l’extension .h, .hpp, .c et .cpp. De plus, nous
devons montrer certaines caractéristiques supplémentaires des fichiers. Par exemple,
la taille, la date de la modification, les attributs, etc. Donc, nous devons utiliser une
représentation graphique en colonnes (semblable à l’explorateur Windows).
PAGE B-13
Ce contrôle de l’interface graphique doit permettre la sélection multiple et nous
pouvons répondre à la notification suivante qui sera générée par l’objet de classe
CListCtrl :

Cette notification est générée par l’objet de classe CListCtrl lors de
la sélection par la souris d’un nom de fichier par l’utilisateur.
NM_CLICK
La représentation
graphique de l'objet de
classe CListCtrl est
organisé en colonnes
*
Figure 4 La représentation graphique de l'objet de classe CListCtrl.
Contrôle intitulé Traitement
Ce contrôle montre une barre de progression (de classe CProgressCtrl de MFC).
Cette barre de progression ne génère pas de notifications. Nous contrôlerons son
affichage par le biais de son objet associé.
*
Figure 5 La représentation graphique de l'objet de classe CProgressCtrl.
Contrôle intitulé Action
Ce contrôle est un bouton poussoir (de classe CButton de MFC). Lorsque l’utilisateur
appuie sur ce bouton, le programme démarre XtractComm pour traiter les fichiers
sélectionnés dans le contrôle intitulé Fichiers. La notification à traiter est :

BN_CLICKED.
Répondre à cette notification pour démarrer la procédure
d’extraction des commentaires. Les fichiers sources à traiter sont ceux
sélectionnés dans le contrôle Fichiers. Utiliser l’indicateur libellé Traitement
pour montrer aux utilisateurs l’avancement des travaux.
PAGE B-14
*
Figure 6 La représentation graphique de l'objet de classe CButton.
Quelques conseils

Placer le programme exécutable XtractComm.exe dans le répertoire Debug et
dans le répertoire principal de ce projet. De cette façon, vous pourrez tester le
programme XtractCommGUI à l’intérieur et à l’extérieur de l’environnement
Visual C++.

Ne pas éditer ou enlever les commentaires ajoutés par le AppWizard de Visual
C++.

Utiliser le ClassWizard pour ajouter vos classes et objets (variables membres et
fonctions membres) dans le projet.

L’initialisation des contrôles s’effectue dans la fonction OnInitDialog() de la
classe CXtractCommGUIDlg.

Les fonctions systèmes Win32 CreateProcess(), WaitForSingleObject()
GetExitCodeProcess() et CloseHandle() sont utilisées pour démarrer et
terminer XtractComm.exe afin d’extraire les commentaires des fichiers sources.
Ces fonctions systèmes sont expliquées dans les sections subséquentes de
ce document.

Utiliser les classes contenues dans la bibliothèque XtractUtil.dll pour obtenir
les informations suivantes :
1. La description des disques attachés à l’ordinateur. Les disques peuvent être
locaux, réseaux, amovibles, non amovibles, etc.
2. Le nom des dossiers d’un disque et le nom des sous-dossiers dans un dossier
quelconque.
3. Le nom, la taille, la date de création, la date de la dernière écriture, la date du
dernier accès des fichiers d’un dossier.
L’utilisation de cette bibliothèque est indiquée dans le manuel accompagnant le
fichier XtractUtil.dll.
PAGE B-15
Section
2
Laboratoire #B
Programmation MFC  Interface graphique pour XtractComm
Travaux à effectuer
La réalisation de l’interface graphique du programme XtractCommGUI nécessite la
maîtrise des classes MFC et de l’environnement de développement de Visual C++.
Puisqu’il n’est pas possible de résumer tous les détails de MFC et de VC++ dans ce
manuel, vous devez consulter au besoin l’aide en-ligne de l’environnement de
développement (MSDN Library). Pour obtenir l’aide en-ligne : i) Cliquer sur le bouton
; ii) Déplacer le curseur sur le mot clé (de C++ ou MFC) puisque appuyer sur la
touche F1 du clavier. Dans les deux cas, vous obtiendrez l’interface de l’aide en-ligne.
La figure ci-dessous montre les différentes zones d’édition de l’interface que vous
pourrez utiliser pour obtenir de l’information.
Les différents manuels
de l'aide en-ligne
Rechercher un mot clé, une
instruction, une commande, etc.
Rechercher un mot clé, une
phrase dans tous les documents
de l'aide en-ligne.
Placer les documents
intéressants dans cet onglet pour
faciliter leur repérage.
*
Figure 7 Zones d'édition de l'aide en-ligne.
La création de XtractCommGUI nécessite une grande utilisation de AppWizard et de
ClassWizard. Donc, prenez le temps de se familiariser avec deux outils de
l’environnement de développement Visual C++.
PAGE B-16
Liste des manipulations
Manipulation #1
Créer le projet de programmation pour XtractCommGUI. Le projet doit être de type
« MFC AppWizard (exe) ». Les paramètres de ce projet sont montrés dans les figures
suivantes. Note : Ce projet crée un programme de type « Dialog-based ».
PAGE B-17
PAGE B-18
Voici la signification des fichiers générés
par AppWizard pour ce projet de
programmation.
Ces fichiers sont nécessaires
pour la pré-compilation des fichiers d’entête.
StdAfx.*
Ces
fichiers
contiennent la déclaration et la définition
d’une
classe
nommée
CXtractCommGUIApp
dérivée
de
CWinApp.
Un
objet
de
classe
CXtractCommGUIApp est également créé pour effectuer l’enregistrement de
l’application auprès du système Windows. Enfin, le fichier XtractCommGUI.rc
contient les ressources Windows utilisées par l’application.
XtractCommGUI.*
XtractCommGUIDlg.* Ces fichiers contiennent la déclaration et la définition de la
classe CXtractCommGUIDlg. Cette classe dérivée de la classe CDialog de MFC sera
associée au panneau de dialogue de l’application. Rappelez-vous que cette application
utilise un panneau de dialogue comme cadre de base.
Ce fichier contient l’identification numérique des contrôles de
l’application. L’identification des contrôles sera donnée dans les manipulations
subséquentes. L’environnement VC++ est responsable de générer la valeur
numérique correspondante et il l’enregistre dans ce fichier.
Resource.h
Manipulation #2
Dans l’éditeur de ressources (par l’onglet ResourceView) sélectionner le panneau de
dialogue de l’application. Ce panneau de dialogue créé par AppWziard porte
l’identification IDD_XTRACTCOMMGUI_DIALOG.
Positionner les éléments de l’interface graphique sur ce panneau de dialogue. La figure
suivante vous donner un exemple. Prévoyez une taille suffisamment grande pour que
les contrôles soient facilement visibles.
PAGE B-19
Manipulation #3
À l’aide de l’éditeur des ressources, régler les propriétés
du panneau de dialogue et des contrôles. Pour activer le
panneau des propriétés d’un élément graphique,
déplacer le curseur sur l’élément désiré puis appuyer sur
le bouton droit. Ensuite sélection l’option Properties.
Par la même occasion, vous constaterez que le menu
flottant dispose également une option pour exécuter le
ClassWizard et une option pour ajouter des
gestionnaires d’événements dans le programme
(Events…). Ces options seront utilisées dans les manipulations subséquentes de ce
laboratoire. Pour le moment, simplement choisir l’option Properties de ce menu
flottant et entrer les paramètres indiqués.
PAGE B-20
Pour le panneau de dialogue du programme
Pour la zone d’édition Combo
PAGE B-21
Pour l’arborescence des dossiers
PAGE B-22
Pour la liste des fichiers
Pour l’indicateur de progression
PAGE B-23
Pour le bouton Action
Pour le logo de l’application
D’abord créer une ressource bitmap de votre choix. La ressource peut être créée
directement dans l’éditeur de ressource
en suivant les étapes indiquées.
Dans
l’onglet
« ResourceView »,
sélectionner le dossier Bitmap. Cliquer
sur le bouton droit et choisir l’option
Insert
Bitmap.
Donner une
identification appropriée à ce Bitmap
(exemple : IDB_LOGO).
PAGE B-24
Double-cliquer sur l’identification
du bitmap et créer un dessin
approprié pour le logo dans
l’espace réservé.
Vous pouvez agrandir l’espace du
bitmap au besoin.
Activer le panneau des propriétés
du logo (Objet CPicture) une
fois la création du bitmap
terminée. Entrer les paramètres suivants dans le panneau des propriétés.
Pour les textes statiques
PAGE B-25
Manipulation #4
Pour permettre à l’utilisateur de naviguer à travers les contrôles par la touche TAB,
nous devons établir l’ordre de déplacement du « focus ».
Un contrôle peut recevoir l’entrée et interagir avec l’utilisateur s’il possède le focus.
Utiliser l’option Tab Order du menu Layout pour établir cet ordre. Vous établissez
l’ordre du déplacement en cliquant sur le contrôle.
Note : Lorsqu’un contrôle est accompagné de son libellé en texte statique, l’ordre du
texte statique doit précédé l’ordre du contrôle. Par exemple, le libellé « Fichiers
sources C/C++: » est en 5e position et le contrôle de type CListCtrl est en 6e
position.
Manipulation #5
Pour la représentation graphique de l’arborescence des dossiers, nous devons créer
une image bitmap pour identifier un dossier « fermé » et un dossier « ouvert ».
Normalement un dossier est en état fermé. Quand un utilisateur sélectionne un
dossier, nous devons présenter un dossier en état ouvert pour indiquer sa sélection.
Ces deux images du dossier sont contenues dans un seul bitmap. L’image bitmap sera
encapsulée dans un objet de classe CImageList puis associer à l’objet de
l’arborescence.

Suivre les mêmes étapes que la création de l’image logo dans l’éditeur de
ressources.

Donner le nom IDB_IMAGE_DOSSIERS à la ressource bitmap.
PAGE B-26

Donner la taille 30 pixels par 12 pixels à l’image bitmap. Puisque ce bitmap
contient deux images (dossier ouvert, dossier fermé). La taille de chacune des
images est 15 pixel par 6 pixels.
Note : Cette image bitmap sera encapsulée dans un objet de classe
CImageList. Cette dernière sera passée en paramètre dans un objet de classe
CTreeCtrl associé à la représentation graphique de l’arborescence des
dossiers.
Manipulation #6
Les éléments de l’interface graphique sont maintenant établis. Il nous faut créer des
objets MFC pour mettre en fonction ces éléments graphiques. À noter que les
messages et notifications sont générés par des objets MFC. Donc, il existe une
séparation d’implantation entre la représentation graphique d’un contrôle apparaissant
à l’écran de l’ordinateur et leur fonctionnement dans le programme. Dans le
programme, nous interagissons avec le contrôle via son objet associé. L’utilisateur,
quant à lui, interagir avec le programme via la représentation graphique des contrôles.
La classe représentant le panneau de dialogue de notre
application
Notification, générée par le
bouton libellé Action, que
nous voulons gérer.
PAGE B-27
Activer le ClassWizard pour créer les objets associés aux contrôles du programme.
Pour ce faire, appuyer sur les touches ctrl-w. Le panneau des paramètres de
ClassWizard apparaîtra. Sélectionner l’onglet « Member Variables ». C’est dans cet
onglet que l’on indique à ClassWizard, le nom et le type des variables membres (lire
objets) qui seront associés à autres contrôles de l’application.

Cliquer sur la ligne correspondante à l’identificateur ID_ACTION. Rappelez-vous
que ID_ACTION est l’identificateur du bouton libellé Action. Note :
L’identification de chacun des contrôles est donnée dans la manipulation
#3.

Ensuite Cliquer sur le bouton « Add Variable ». Puisque donner le nom de l’objet
m_BoutonAction dans la zone d’édition.
Pour le bouton identifié par
ID_ACTION, donner le nom
m_BoutonAction dans la
zone « Member variable
name ».
Sélectionner
« Control » dans la liste
« Category ». Sélectionner la
classe « CButton » dans la
liste « Variable type ».
Donc, pour créer un objet MFC, il est nécessaire de donner le nom de l’objet (ex :
m_ButtonAction). Par convention de MFC, les variables membres sont préfixées de
m_ pour indiquer qu’elles sont membres d’une classe. La catégorie sert à indiquer si
l’objet est manipulé par sa valeur de retour seulement. Une variable membre qui est
représentée par valeur doit passer par le mécanisme DDX (Dynamic Data eXchange)
pour effectuer ses mises à jour. Noter que le DDX n’existe que dans les panneaux de
dialogue. Nous devons choisir la catégorie « Control » puisque nous devons pouvoir
effectuer nous-mêmes les mises à jours par programmation. Enfin, le type de la
variable membre sert à indiquer la classe MFC qui est le type de la variable à créer.

Effectuer la même opération pour tous les contrôles de l’application. Sélectionner
le fichier XtractCommGUIDlg.h après la création des variables membres de
l’interface graphique. Dans la déclaration de la classe CXtratCommGUIDlg, vous
devez retrouver les entrées suivantes :
//{{AFX_DATA(CXtractCommGUIDlg)
enum { IDD = IDD_XTRACTCOMMGUI_DIALOG };
PAGE B-28
CButton m_BoutonAction;
CProgressCtrl m_BarreProgression;
CListCtrl
m_lcFichiers;
CtreeCtrl
m_ArbreDossiers;
CComboBox
m_cbDisque;
//}}AFX_DATA
Manipulation #7
La classe représentant le panneau de dialogue de notre
application
Notification, générée par le
bouton libellé Action, que
nous voulons gérer.
Les objets MFC sont créés, nous devons maintenant instaurer les gestionnaires de
messages et de notifications.

Activer le ClassWizard par les touches ctrl-w. Sélectionner l’onglet « Message
Map ». Sélectionner ID_ACTION dans la liste « Object IDs ». Sélectionner la
notification BN_CLICKED dans la liste « Messages ». Cette notification est envoyée
au programme lorsque l’utilisateur appuie sur le bouton libellé Action. Nous
indiquons par cette procédure que nous désirons gérer cette notification. Enfin,
cliquer sur le bouton « Add Function » et donner un nom approprié aux
fonctions membres.

Répéter la même procédure pour gérer les notifications suivantes :
PAGE B-29
L’arborescence des dossiers
Notification à gérer :
1. TVN_ITEMEXPANDING. Cette notification est générée lorsque l’utilisateur
clique sur la zone +/- de l’arborescence.
2. TVN_SELCHNAGED. Cette notification est générée lorsque l’utilisateur
sélectionne un autre dossier.
La liste de description des disques
1. CBN_SELCHANGE. Cette notification est générée lorsque l’utilisateur
sélectionne un autre disque dans la boîte combo.
La liste des fichiers
1. MN_CLICK. Cette notification est générée lorsque l’utilisateur sélectionne un
fichier de la liste.
À noter que la barre de progression ainsi que l’image logo ne produisent pas de
notification. Par contre, nous contrôlerons la barre de progression directement
par programmation. Vous devriez retrouver les ajouts suivants dans les fichiers
XtractCommGUIDlg.h et XtractCommGUIDlg.cpp à la fin de cette
manipulation.
Dans le fichier XtractCommGUIDlg.h :
// Generated message map functions
//{{AFX_MSG(CXtractCommGUIDlg)
virtual BOOL OnInitDialog();
virtual void OnOK();
afx_msg void OnSysCommand(UINT nID, LPARAM lParam);
afx_msg void OnPaint();
afx_msg HCURSOR OnQueryDragIcon();
afx_msg void OnSelchangeComboDisque();
afx_msg void OnItemexpandingArbreDossiers(NMHDR* pNMHDR, LRESULT* pResult);
afx_msg void OnSelchangedArbreDossiers(NMHDR* pNMHDR, LRESULT* pResult);
afx_msg void OnAction();
afx_msg void OnClickFichierInfo(NMHDR* pNMHDR, LRESULT* pResult);
//}}AFX_MSG
Dans le fichier XtractCommGUIDlg.cpp :
BEGIN_MESSAGE_MAP(CXtractCommGUIDlg, CDialog)
//{{AFX_MSG_MAP(CXtractCommGUIDlg)
ON_WM_SYSCOMMAND()
ON_WM_PAINT()
ON_WM_QUERYDRAGICON()
ON_CBN_SELCHANGE(IDC_COMBO_DISQUE, OnSelchangeComboDisque)
PAGE B-30
ON_NOTIFY(TVN_ITEMEXPANDING, IDC_ARBRE_DOSSIERS, OnItemexpandingArbreDossiers)
ON_NOTIFY(TVN_SELCHANGED, IDC_ARBRE_DOSSIERS, OnSelchangedArbreDossiers)
ON_BN_CLICKED(ID_ACTION, OnAction)
ON_NOTIFY(NM_CLICK, IDC_FICHIER_INFO, OnClickFichierInfo)
//}}AFX_MSG_MAP
END_MESSAGE_MAP()
En résumé, cette manipulation consiste à créer des fonctions membres dans la classe
CXtractCommGUIDlg pour gérer les notifications par les contrôles de l’interface
graphique.
Note : Le ClassWizard génère les entrées dans la carte de messages et insère
les prototypes des fonctions membres dans le fichier source approprié.
Cependant, le corps de ces fonctions membres demeure vide et c’est à vous de
programmer le fonctionnement de ces fonctions membres qui agissent
comme gestionnaires de notification.
Manipulation #8
Pour réaliser l’objectif de ce projet de programmation, vous aurez besoin d’une
bibliothèque DLL appelé XtractUtil.dll. Dans cette bibliothèque vous
retrouverez deux classes :
1. GestionDisques : Cette classe repère pour vous les unités de disques attachés à
l’ordinateur. Vous devez placer dans la boîte combo (m_ArbreDossiers), la
description des disques retournée par un objet de cette classe.
2. GestionFichiers : Cette classe repère les fichiers contenus dans un dossier
d’un disque. Vous devez placer dans la liste des fichiers (m_lcFichiers), les
caractéristiques des fichiers retournées par un objet de cette classe.
De plus, cette bibliothèque DLL contient les structures de données et les signaux
d’exception nécessaires à son fonctionnement.

Télécharger la bibliothèque XtractUtil.dll à partir du site web du cours
GPA789. Comprendre l’utilisation des classes de cette bibliothèque en faisant une
lecture complète de son manuel d’utilisation. Vous pouvez aussi télécharger le
code source de cette bibliothèque afin de comprendre son fonctionnement
interne.

Insérer la bibliothèque dans le projet de programmation en cours. Pour ce faire,
1. Utiliser WinZip pour décompresser le fichier XtractUtil.zip.
2. Copier le fichier XtractUtil.h dans le dossier principal du projet.
3. Copier le fichier XtractUtil.lib dans le dossier principal du projet.
4. Copier le fichier XtractUtil.dll dans le dossier « Debug » et/ou
« Release » de votre projet.
PAGE B-31
5. Insérer le fichier XtractUtil.h dans le projet de programmation par le biais
de l’onglet « FileView ».
6. Insérer le fichier XtractUtil.lib dans le projet de programmation par le
biais de l’onglet « FileView ». Ce fichier contient tous les symboles (i.e.
variables, fonctions, classes, etc.) exportés et utilisables de la bibliothèque
DLL.

À la fin de cette manipulation vous devez avoir une organisation de l’onglet
« FileView » semblable à celle-ci :
Fichiers à insérer
dans le projet
Manipulation #9
Il est temps d’effectuer la programmation proprement dite de l’application
XtractCommGUI. Vous devez vous familiariser avec les différents objets MFC utilisés.
Pour ce faire, consulter la documentation en ligne de Visual C++. Les pages insérées
dans l’annexe de ce document est un bon point de départ.
À noter que vous pouvez ajouter des fonctions membres dans la classe
pour aider à la réaliser de l’application. Autrement dit, il est
possible d’ajouter des fonctions membres dans les sections publique, protégée
et privée de la classe CXtractCommGUIDlg en plus des fonctions membres
ajoutées par le ClassWizard.
CXtractCommGUIDlg
Par contre, vous devez ajouter manuellement les fonctions membres qui ne sont pas
gestionnaires de notifications. Le ClassWizard n’est utile que pour instaurer les
gestionnaires de messages et notifications MFC.

Le tableau ci-dessous peut vous aider à mieux comprendre le rôle des fonctions
membres générées pour la classe CXtractCommGUIDlg par le ClassWizard.
PAGE B-32
Fonction générée
Rôle
OnInitDialog()
Cette fonction membre est exécutée par le MFC tout
juste avant l’affichage graphique du panneau de
dialogue. Vous devez réaliser toutes vos initialisations
des contrôles dans cette fonction :
1. Charger l’image bitmap représentant un dossier
ouvert et un dossier fermé dans un objet de classe
CImageList.
2. Passer l’objet de classe CImageList dans l’objet
de classe CTreeCtrl (i.e. m_ArbreDossiers).
3. Régler les colonnes de la liste des fichiers (i.e.
m_lcFichiers).
4. Placer la description des disques dans le combo,
sélectionner par programmation un disque par
défaut, afficher les dossiers du disque par défaut
et afficher les fichiers trouvés dans la liste des
fichiers.
OnSelchangeComboDisque()
OnSelchangedArbreDossiers()
Cette fonction membre est exécutée par le MFC
lorsque l’utilisateur sélectionne un autre disque de la
boîte combo.
1. Prendre le disque sélectionné de la boîte combo.
2. Mettre à jour l’arborescence des dossiers.
3. Mettre à jour la liste des fichiers.
lorsque l’utilisateur sélectionne un autre dossier de
l’arborescence.
1. Former le chemin courant.
OnItemexpandingArbreDossiers()
lorsque l’utilisateur sélectionne la zone +/- d’un dossier.
1. Former le chemin courant.
2. Mettre à jour la partie de l’arborescence
sélectionnée par l’utilisateur (montrer les sous
dossiers).
OnClickFichierInfo()
lorsque l’utilisateur sélectionne un fichier de la liste des
fichiers.
1. Simplement remettre à zéro la barre de
progression si le programme n’est pas en
traitement.
PAGE B-33
OnAction()
lorsque l’utilisateur clique sur le bouton Action.
Pour chaque fichier sélectionné de la liste :
1. Exécuter XtractComm.exe en lui donnant comme
paramètre le fichier sélectionné et un nom de
fichier de sortie.
2. Faire avancer la barre de progression pour
indiquer l’état des opérations effectuées.
programmation utilise le programme XtractComm.exe,

Puisque ce projet de
copier ce programme exécutable dans le dossier principal du projet.

Pour exécuter un programme à partir d’un autre (ce qui est notre cas), utiliser les
fonctions systèmes Win32 énumérées ci-dessous. Consulter la documentation enligne pour comprendre leur utilisation.
1. CreateProcess() : Cette fonction système vous permettra exécuter
n’importe quel programme Win32 sous forme d’un processus. Il existe un
grand nombre de paramètres à fournir. Voici l’usage recommandé de cette
fonction Win32 :
if( !CreateProcess( Prog, /* Nom du programme */
CmdLine.GetBuffer(CmdLine.GetLength()), /* Ligne de commande */
NULL,
/* Process handle non heritable */
NULL,
/* Thread handle non heritable. */
FALSE,
/* handle heritage est FALSE */
DETACHED_PROCESS, /* Tâche sans console ni fenêtre. */
NULL,
/* Utilise l'environment du parent */
NULL,
/* Utilise le répertoire de départ du parent */
&si,
/* Pointeur à la structure STARTUPINFO */
&pi )
/* Pointeur à la structure PROCESS_INFORMATION */
) {
// Message d’erreur
} else {
// tout va bien continuer le travail …
}
2. WaitForSingleObject() : Lorsque le processus est créé par
CreateProcess(), vous devez attendre la fin de l’exécution du processus
avant d’en créer un autre (si l’utilisateur a sélectionné plus d’un fichier source
à traiter). Cette fonction Win32 bloquera tant et aussi longtemps que le
processus est en exécution. L’identificateur (i.e. PID) du processus est
nécessaire pour cette fonction Win32.
3. GetExitCodeProcess() : Lorsque le processus termine son exécution, il
retourne un statut de retour (voir le code source du programme XtractComm
pour connaître la signification de ses valeurs de retour). Vous pouvez obtenir
la valeur de retour d’un processus par cette fonction Win32.
4. CloseHandle() : Fermer la communication avec le processus. Cette
fonction est nécessaire pour libérer les ressources (mémoire, structure de
données systèmes, etc.) utilisées par le processus.
PAGE B-34
C’est à l’aide de ces fonctions systèmes que nous pourrons exécuter
XtractComm.exe silencieusement en arrière plan.
Note : Toutes ces fonctions systèmes exigent des paramètres. Vous devez
consulter l’aide en-ligne pour bien comprendre la signification des ces
paramètres avant de les utiliser. Une erreur de programmation peut
entraîner le blocage de votre ordinateur !
Manipulation #10
Enfin, tester le programme réalisé. Valider XtractCommGUI par des fichiers sources.
Tester le fonctionnement de la boîte combo, de l’arborescence des dossiers, de la liste
des fichiers (avec des sélections multiples), le bouton Action ainsi que la barre de
progression.
Contenu du rapport
La durée de ce laboratoire est de trois semaines. Vous devez remettre un rapport à
la 4e semaine. Le contenu du rapport est donné ci-dessous :
1. Introduction L’exposé du problème consiste à reprendre la description du
laboratoire tout en précisant les difficultés et les problèmes pouvant survenir
à la réalisation de ce projet de programmation. Ne pas recopier la
description de ce laboratoire!
2. Description fonctionnelle Décrire les étapes nécessaires à la résolution du
problème. Les étapes sont celles menant à la réalisation de XtractCommGUI.
3. Résultat/Discussion Présenter les résultats obtenus, les notes et remarques
pertinentes. Proposer les améliorations possibles dans un développement
futur.
4. Conclusion Reprendre la présentation du rapport mais en ordre
chronologique inversé. Ne pas présenter vos résultats dans cette section. Ils
doivent être présentés dans la section Résultat/Discussion.
5. Code source Présenter le code source dans une section dédiée à la fin du
rapport.
Vous devez remettre une disquette contenant le programme exécutable et
tous ses fichiers de support.
PAGE B-35
Annexe
PAGE B-36
CButton
Page 1 sur 2
CButton
The CButton class provides the functionality of Windows button controls. A button control
is a small, rectangular child window that can be clicked on and off. Buttons can be used
alone or in groups and can either be labeled or appear without text. A button typically
changes appearance when the user clicks it.
Typical buttons are the check box, radio button, and pushbutton. A CButton object can
become any of these, according to the button style specified at its initialization by the
Create member function.
In addition, the CBitmapButton class derived from CButton supports creation of button
controls labeled with bitmap images instead of text. A CBitmapButton can have separate
bitmaps for a button's up, down, focused, and disabled states.
You can create a button control either from a dialog template or directly in your code. In
both cases, first call the constructor CButton to construct the CButton object; then call
the Create member function to create the Windows button control and attach it to the
CButton object.
Construction can be a one-step process in a class derived from CButton. Write a
constructor for the derived class and call Create from within the constructor.
If you want to handle Windows notification messages sent by a button control to its parent
(usually a class derived from CDialog), add a message-map entry and message-handler
member function to the parent class for each message.
Each message-map entry takes the following form:
ON_Notification( id, memberFxn )
where id specifies the child window ID of the control sending the notification and
memberFxn is the name of the parent member function you have written to handle the
notification.
The parent’s function prototype is as follows:
afx_msg void memberFxn( );
Potential message-map entries are as follows:
Map entry
Sent to parent when...
ON_BN_CLICKED
The user clicks a button.
ON_BN_DOUBLECLICKED
The user double-clicks a button.
If you create a CButton object from a dialog resource, the CButton object is automatically
mk:@MSITStore:D:\Microsoft%20Visual%20Studio\MSDN\99OCT\.../_mfc_cbutton.ht
28/01/01
CButton
Page 2 sur 2
destroyed when the user closes the dialog box.
If you create a CButton object within a window, you may need to destroy it. If you create
the CButton object on the heap by using the new function, you must call delete on the
object to destroy it when the user closes the Windows button control. If you create the
CButton object on the stack, or it is embedded in the parent dialog object, it is destroyed
automatically.
#include <afxwin.h>
Class Members | Base Class | Hierarchy Chart
See Also CWnd, CComboBox, CEdit, CListBox, CScrollBar, CStatic, CBitmapButton,
CDialog
Send feedback to MSDN. Look here for MSDN Online resources.
mk:@MSITStore:D:\Microsoft%20Visual%20Studio\MSDN\99OCT\.../_mfc_cbutton.ht
28/01/01
CComboBox
Page 1 sur 3
CComboBox
The CComboBox class provides the functionality of a Windows combo box.
A combo box consists of a list box combined with either a static control or edit control. The
list-box portion of the control may be displayed at all times or may only drop down when
the user selects the drop-down arrow next to the control.
The currently selected item (if any) in the list box is displayed in the static or edit control.
In addition, if the combo box has the drop-down list style, the user can type the initial
character of one of the items in the list, and the list box, if visible, will highlight the next
item with that initial character.
The following table compares the three combo-box styles.
Style
When is list box visible?
Static or edit control?
Simple
Always
Edit
Drop-down
When dropped down
Edit
Drop-down list
When dropped down
Static
You can create a CComboBox object from either a dialog template or directly in your code.
In both cases, first call the constructor CComboBox to construct the CComboBox object;
then call the Create member function to create the control and attach it to the
CComboBox object.
If you want to handle Windows notification messages sent by a combo box to its parent
(usually a class derived from CDialog), add a message-map entry and message-handler
member function to the parent class for each message.
Each message-map entry takes the following form:
ON_Notification( id, memberFxn )
where id specifies the child-window ID of the combo-box control sending the notification
and memberFxn is the name of the parent member function you have written to handle the
notification.
The parent’s function prototype is as follows:
afx_msg void memberFxn( );
The order in which certain notifications will be sent cannot be predicted. In particular, a
CBN_SELCHANGE notification may occur either before or after a CBN_CLOSEUP
notification.
Potential message-map entries are the following:
mk:@MSITStore:D:\Microsoft%20Visual%20Studio\MSDN\99O.../_mfc_ccombobox.ht
28/01/01
CComboBox
Page 2 sur 3
ON_CBN_CLOSEUP (Windows 3.1 and later.) The list box of a combo box has
closed. This notification message is not sent for a combo box that has the
CBS_SIMPLE style.
ON_CBN_DBLCLK The user double-clicks a string in the list box of a combo box.
This notification message is only sent for a combo box with the CBS_SIMPLE style.
For a combo box with the CBS_DROPDOWN or CBS_DROPDOWNLIST style, a doubleclick cannot occur because a single click hides the list box.
ON_CBN_DROPDOWN The list box of a combo box is about to drop down (be
made visible). This notification message can occur only for a combo box with the
CBS_DROPDOWN or CBS_DROPDOWNLIST style.
ON_CBN_EDITCHANGE The user has taken an action that may have altered the
text in the edit-control portion of a combo box. Unlike the CBN_EDITUPDATE
message, this message is sent after Windows updates the screen. It is not sent if the
combo box has the CBS_DROPDOWNLIST style.
ON_CBN_EDITUPDATE The edit-control portion of a combo box is about to display
altered text. This notification message is sent after the control has formatted the text
but before it displays the text. It is not sent if the combo box has the
CBS_DROPDOWNLIST style.
ON_CBN_ERRSPACE The combo box cannot allocate enough memory to meet a
specific request.
ON_CBN_SELENDCANCEL (Windows 3.1 and later.) Indicates the user’s selection
should be canceled. The user clicks an item and then clicks another window or control
to hide the list box of a combo box. This notification message is sent before the
CBN_CLOSEUP notification message to indicate that the user’s selection should be
ignored. The CBN_SELENDCANCEL or CBN_SELENDOK notification message is
sent even if the CBN_CLOSEUP notification message is not sent (as in the case of a
combo box with the CBS_SIMPLE style).
ON_CBN_SELENDOK The user selects an item and then either presses the ENTER
key or clicks the DOWN ARROW key to hide the list box of a combo box. This
notification message is sent before the CBN_CLOSEUP message to indicate that the
user’s selection should be considered valid. The CBN_SELENDCANCEL or
CBN_SELENDOK notification message is sent even if the CBN_CLOSEUP
notification message is not sent (as in the case of a combo box with the
CBS_SIMPLE style).
ON_CBN_KILLFOCUS The combo box is losing the input focus.
ON_CBN_SELCHANGE The selection in the list box of a combo box is about to be
changed as a result of the user either clicking in the list box or changing the selection
by using the arrow keys. When processing this message, the text in the edit control
of the combo box can only be retrieved via GetLBText or another similar function.
GetWindowText cannot be used.
ON_CBN_SETFOCUS The combo box receives the input focus.
If you create a CComboBox object within a dialog box (through a dialog resource), the
CComboBox object is automatically destroyed when the user closes the dialog box.
If you embed a CComboBox object within another window object, you do not need to
destroy it. If you create the CComboBox object on the stack, it is destroyed automatically.
If you create the CComboBox object on the heap by using the new function, you must call
28/01/01
CComboBox
Page 3 sur 3
delete on the object to destroy it when the Windows combo box is destroyed.
#include <afxwin.h>
Sample MFC Sample CTRLBARS
See Also CWnd, CButton, CEdit, CListBox, CScrollBar, CStatic, CDialog
28/01/01
CDialog
Page 1 sur 2
CDialog
The CDialog class is the base class used for displaying dialog boxes on the screen. Dialog
boxes are of two types: modal and modeless. A modal dialog box must be closed by the
user before the application continues. A modeless dialog box allows the user to display the
dialog box and return to another task without canceling or removing the dialog box.
A CDialog object is a combination of a dialog template and a CDialog-derived class. Use
the dialog editor to create the dialog template and store it in a resource, then use
ClassWizard to create a class derived from CDialog.
A dialog box, like any other window, receives messages from Windows. In a dialog box, you
are particularly interested in handling notification messages from the dialog box’s controls
since that is how the user interacts with your dialog box. ClassWizard browses through the
potential messages generated by each control in your dialog box, and you can select which
messages you wish to handle. ClassWizard then adds the appropriate message-map entries
and message-handler member functions to the new class for you. You only need to write
application-specific code in the handler member functions.
If you prefer, you can always write message-map entries and member functions yourself
instead of using ClassWizard.
In all but the most trivial dialog box, you add member variables to your derived dialog class
to store data entered in the dialog box’s controls by the user or to display data for the user.
ClassWizard browses through those controls in your dialog box that can be mapped to data
and prompts you to create a member variable for each control. At the same time, you
choose a variable type and permissible range of values for each variable. ClassWizard adds
the member variables to your derived dialog class.
ClassWizard then writes a data map to automatically handle the exchange of data between
the member variables and the dialog box’s controls. The data map provides functions that
initialize the controls in the dialog box with the proper values, retrieve the data, and
validate the data.
To create a modal dialog box, construct an object on the stack using the constructor for
your derived dialog class and then call DoModal to create the dialog window and its
controls. If you wish to create a modeless dialog, call Create in the constructor of your
dialog class.
You can also create a template in memory by using a DLGTEMPLATE data structure as
described in the Win32 SDK documentation. After you construct a CDialog object, call
CreateIndirect to create a modeless dialog box, or call InitModalIndirect and DoModal to
create a modal dialog box.
ClassWizard writes the exchange and validation data map in an override of
CWnd::DoDataExchange that ClassWizard adds to your new dialog class. See the
DoDataExchange member function in CWnd for more on the exchange and validation
functionality.
Both the programmer and the framework call DoDataExchange indirectly through a call to
mk:@MSITStore:D:\Microsoft%20Visual%20Studio\MSDN\99OCT\1.../_mfc_cdialog.ht
28/01/01
CDialog
Page 2 sur 2
CWnd::UpdateData.
The framework calls UpdateData when the user clicks the OK button to close a modal
dialog box. (The data is not retrieved if the Cancel button is clicked.) The default
implementation of OnInitDialog also calls UpdateData to set the initial values of the
controls. You typically override OnInitDialog to further initialize controls. OnInitDialog is
called after all the dialog controls are created and just before the dialog box is displayed.
You can call CWnd::UpdateData at any time during the execution of a modal or modeless
dialog box.
If you develop a dialog box by hand, you add the necessary member variables to the
derived dialog-box class yourself, and you add member functions to set or get these values.
For more on ClassWizard, see Using ClassWizard in the Visual C++ Programmer's Guide.
Call CWinApp::SetDialogBkColor to set the background color for dialog boxes in your
application.
A modal dialog box closes automatically when the user presses the OK or Cancel buttons or
when your code calls the EndDialog member function.
When you implement a modeless dialog box, always override the OnCancel member
function and call DestroyWindow from within it. Don’t call the base class
CDialog::OnCancel, because it calls EndDialog, which will make the dialog box invisible
but will not destroy it. You should also override PostNcDestroy for modeless dialog boxes
in order to delete this, since modeless dialog boxes are usually allocated with new. Modal
dialog boxes are usually constructed on the frame and do not need PostNcDestroy
cleanup.
For more information on CDialog, see the article Dialog Box Topics in Visual C++
Programmer's Guide.
#include <afxwin.h>
Samples MFC Sample DBFETCH | MFC Sample DLGCBR32 | MFC Sample DLGTEMPL |
MFC Sample EXTBIND | MFC Sample FTPTREE | MFC Sample HELLO | MFC Sample
MDIBIND | MFC Sample VCTERM
mk:@MSITStore:D:\Microsoft%20Visual%20Studio\MSDN\99OCT\1.../_mfc_cdialog.ht
28/01/01
CProgressCtrl
Page 1 sur 1
CProgressCtrl
A “progress bar control” is a window that an application can use to indicate the progress of
a lengthy operation. It consists of a rectangle that is gradually filled, from left to right, with
the system highlight color as an operation progresses.
The CProgressCtrl class provides the functionality of the Windows common progress bar
control. This control (and therefore the CProgressCtrl class) is available only to programs
running under Windows 95 and Windows NT version 3.51 and later.
A progress bar control has a range and a current position. The range represents the entire
duration of the operation, and the current position represents the progress the application
has made toward completing the operation. The window procedure uses the range and the
current position to determine the percentage of the progress bar to fill with the highlight
color and to determine the text, if any, to display within the progress bar. Because the
range and current position values are expressed as signed integers, the possible range of
current position values is from -217483648 to 217483647 inclusive.
For more information on using CProgressCtrl, seeControl Topics andUsing CProgressCtrl in
the Visual C++ Programmer’s Guide.
#include <afxcmn.h>
Samples MFC Sample CMNCTRL2 | MFC Sample FIRE
Send feedback to MSDN.Look here for MSDN Online resources.
mk:@MSITStore:D:\Microsoft%20Visual%20Studio\MSDN\99.../_mfc_cprogressctrl.ht
28/01/01
CTreeCtrl
Page 1 sur 1
CTreeCtrl
A “tree view control” is a window that displays a hierarchical list of items, such as the
headings in a document, the entries in an index, or the files and directories on a disk. Each
item consists of a label and an optional bitmapped image, and each item can have a list of
subitems associated with it. By clicking an item, the user can expand and collapse the
associated list of subitems.
The CTreeCtrl class provides the functionality of the Windows common tree view control.
This control (and therefore the CTreeCtrl class) is available only to programs running
under Windows 95 and Windows NT versions 3.51 and later.
For more information on using CTreeCtrl, seeControl Topics,Using CTreeCtrl in the Visual
C++ Programmer’s Guide,andTree View Control Reference in the Platform SDK.
#include <afxcmn.h>
Samples MFC Sample CMNCTRL1 | MFC Sample FIRE | MFC Sample FTPTREE
See Also CImageList
Send feedback to MSDN.Look here for MSDN Online resources.
mk:@MSITStore:D:\Microsoft%20Visual%20Studio\MSDN\99OCT\.../_mfc_ctreectrl.ht
28/01/01
CListCtrl
Page 1 sur 3
CListCtrl
The CListCtrl class encapsulates the functionality of a “list view control,” which displays a
collection of items each consisting of an icon (from an image list) and a label. In addition to
an icon and label, each item can have information displayed in colums to the right of the
icon and label. This control (and therefore the CListCtrl class) is available only to programs
running under Windows 95 and Windows NT version 3.51 and later.
The following is a brief overview of the CListCtrl class. For a detailed, conceptual
discussion, seeUsing CListCtrl andControl Topics in the Visual C++ Programmer’s Guide.
Views
List view controls can display their contents in four different ways, called “views.”
Icon view
Each item appears as a full-sized icon (32 x 32 pixels) with a label below it. The user
can drag the items to any location in the list view window.
Small icon view
Each item appears as a small icon (16 x 16 pixels) with the label to the right of it.
The user can drag the items to any location in the list view window.
List view
Each item appears as a small icon with a label to the right of it. Items are arranged in
columns and cannot be dragged to any location in the list view window.
Report view
Each item appears on its own line, with additional information arranged in columns to
the right. The leftmost column contains the small icon and label, and subsequent
columns contain subitems as specified by the application. An embedded header
control (class CHeaderCtrl) implements these columns. For more information on the
header control and columns in a report view, seeUsing CListCtrl: Adding Columns to
the Control (Report View).
The style of the control’s current list view determines the current view. For more
information on these these styles and their usage, see Using CListCtrl: Changing List
Control Styles.
Extended Styles
CListCtrl
In addition to the standard list styles, class
supports a large set of extended
styles, providing enriched functionality. Some examples of this functionality include:
Hover selection
When enabled, allows automatic selection of an item when the cursor remains over
the item for a certain period of time.
Virtual list views
DWORD
When enabled, allows the control to support up to
items. This is possible by
placing the overhead of managing item data on the application. Except for the item
selection and focus information, all item information must be managed by the
mk:@MSITStore:D:\Microsoft%20Visual%20Studio\MSDN\99OCT\1.../_mfc_clistctrl.ht
28/01/01
CListCtrl
Page 2 sur 3
application. For more information, see Using CListCtrl: Virtual List Controls.
One– and two– click activation
When enabled, allows hot tracking (automatic highlighting of the item text) and one–
or two– click activation of the highlighted item.
Drag and drop column ordering
When enabled, allows drag-and-drop reordering of columns in a list view control. Only
available in report view.
For information on using these new extended styles, see Using CListCtrl: Changing List
Control Styles.
Items and Subitems
Each item in a list view control consists of an icon (from an image list), a label, a current
state, and an application-defined value (referred to as “item data”). One or more subitems
can also be associated with each item. A “subitem” is a string that, in report view, can be
displayed in a column to the right of an item’s icon and label. All items in a list view control
must have the same number of subitems.
CListCtrl
Class
provides several functions for inserting, deleting, finding, and modifying
these items. For more information, see CListCtrl::GetItem, CListCtrl::InsertItem, and
CListCtrl::FindItem, Using CListCtrl: Adding Items to the Control, and Using CListCtrl:
Scrolling, Arranging, Sorting, and Finding in List Controls.
By default, the list view control is responsible for storing an item's icon and text attributes.
However, in addition to these item types, class
supports “callback items.” A
“callback item” is a list view item for which the application — rather than the control —
stores the text, icon, or both. A callback mask is used to specify which item attributes (text
and/or icon) are supplied by the application. If an application uses callback items, it must
be able to supply the text and/or icon attributes on demand. Callback items are helpful
when your application already maintains some of this information. For more information,
see CListCtrl::GetCallBackMask and Using CListCtrl: Callback Items and the Callback Mask.
CListCtrl
Image Lists
The icons, header item images, and application– defined states for list view items are
contained in several image lists (implemented by class CImageList), which you create and
assign to the list view control. Each list view control can have up to four different types of
image lists:
Large icon
Used in the icon view for full-sized icons.
Small icon
Used in the small icon, list, and report views for smaller versions of the icons used in
the icon view.
Application-defined state
Contains state images, which are displayed next to an item’s icon to indicate an
application-defined state.
Header item
Used in the report view for small images that appear in each header control item.
By default, a list view control destroys the image lists assigned to it when it is destroyed;
however, the developer can customize this behavior by destroying each image list when it
is no longer used, as determined by the application. For more information, see Using
CListCtrl: List Items and Image Lists and Using CListCtrl: List Items and Image Lists.
28/01/01
CListCtrl
Page 3 sur 3
#include <afxcmn.h>
Samples
MFC Sample DAOTABLE | MFC Sample HTTPSVR | MFC Sample LISTHDR |
MFC Sample ROWLIST | MFC Sample DBVLIST
See Also
CImageList
28/01/01
CreateProcess
Page 1 sur 6
Platform SDK: DLLs, Processes, and Threads
CreateProcess
The CreateProcess function creates a new process and its primary thread. The new process runs the
specified executable file.
To create a process that runs in a different security context, use the CreateProcessAsUser or
CreateProcessWithLogonW function.
BOOL CreateProcess(
LPCTSTR lpApplicationName, // name of executable module
LPTSTR lpCommandLine,
// command line string
LPSECURITY_ATTRIBUTES lpProcessAttributes,
LPSECURITY_ATTRIBUTES lpThreadAttributes,
BOOL bInheritHandles,
// handle inheritance flag
DWORD dwCreationFlags,
// creation flags
LPVOID lpEnvironment,
// new environment block
LPCTSTR lpCurrentDirectory, // current directory name
LPSTARTUPINFO lpStartupInfo,
LPPROCESS_INFORMATION lpProcessInformation
);
Parameters
lpApplicationName
Pointer to a null-terminated string that specifies the module to execute.
The string can specify the full path and file name of the module to execute or it can specify a partial
name. In the case of a partial name, the function uses the current drive and current directory to
complete the specification. The function will not use the search path.
The lpApplicationName parameter can be NULL. In that case, the module name must be the first white
space-delimited token in the lpCommandLine string. If you are using a long file name that contains a
space, use quoted strings to indicate where the file name ends and the arguments begin; otherwise,
the file name is ambiguous. For example, consider the string "c:\program files\sub dir\program name".
This string can be interpreted in a number of ways. The system tries to interpret the possibilities in the
following order:
c:\program.exe files\sub dir\program name
c:\program files\sub.exe dir\program name
c:\program files\sub dir\program.exe name
c:\program files\sub dir\program name.exe
The specified module can be a Win32-based application. It can be some other type of module (for
example, MS-DOS or OS/2) if the appropriate subsystem is available on the local computer.
Windows NT/2000: If the executable module is a 16-bit application, lpApplicationName should be
NULL, and the string pointed to by lpCommandLine should specify the executable module as well as its
arguments. A 16-bit application is one that executes as a VDM or WOW process.
lpCommandLine
Pointer to a null-terminated string that specifies the command line to execute. The system adds a null
character to the command line, trimming the string if necessary, to indicate which file was actually
used.
Windows NT/2000: The Unicode version of this function, CreateProcessW, will fail if this parameter
is a const string.
The lpCommandLine parameter can be NULL. In that case, the function uses the string pointed to by
lpApplicationName as the command line.
If both lpApplicationName and lpCommandLine are non-NULL, *lpApplicationName specifies the
module to execute, and *lpCommandLine specifies the command line. The new process can use
GetCommandLine to retrieve the entire command line. C runtime processes can use the argc and
argv arguments. Note that it is a common practice to repeat the module name as the first token in the
command line.
If lpApplicationName is NULL, the first white-space – delimited token of the command line specifies the
module name. If you are using a long file name that contains a space, use quoted strings to indicate
where the file name ends and the arguments begin (see the explanation for the lpApplicationName
parameter). If the file name does not contain an extension, .exe is appended. If the file name ends in
a period (.) with no extension, or if the file name contains a path, .exe is not appended. If the file
name does not contain a directory path, the system searches for the executable file in the following
sequence:
1. The directory from which the application loaded.
2. The current directory for the parent process.
3. Windows 95/98: The Windows system directory. Use the GetSystemDirectory function to
get the path of this directory.
Windows NT/2000: The 32-bit Windows system directory. Use the GetSystemDirectory
function to get the path of this directory. The name of this directory is System32.
mk:@MSITStore:D:\Microsoft%20Visual%20Studio\MSDN\99OCT\.../prothred_9dpv.ht
28/01/01
CreateProcess
4.
5.
Page 2 sur 6
Windows NT/2000: The 16-bit Windows system directory. There is no Win32 function that
obtains the path of this directory, but it is searched. The name of this directory is System.
The Windows directory. Use the GetWindowsDirectory function to get the path of this
directory.
6. The directories that are listed in the PATH environment variable.
SECURITY_ATTRIBUTES
Windows NT/2000: lpSecurityDescriptor
lpProcessAttributes
Pointer to a
structure that determines whether the returned handle can be
inherited by child processes. If lpProcessAttributes is NULL, the handle cannot be inherited.
The
member of the structure specifies a security
descriptor for the new process. If lpProcessAttributes is NULL, the process gets a default security
descriptor.
SECURITY_ATTRIBUTES
Windows NT/2000: lpSecurityDescriptor
lpThreadAttributes
Pointer to a
structure that determines whether the returned handle can be
inherited by child processes. If lpThreadAttributes is NULL, the handle cannot be inherited.
The
member of the structure specifies a security
descriptor for the main thread. If lpThreadAttributes is NULL, the thread gets a default security
descriptor.
bInheritHandles
Indicates whether the new process inherits handles from the calling process. If TRUE, each inheritable
open handle in the calling process is inherited by the new process. Inherited handles have the same
value and access privileges as the original handles.
dwCreationFlags
Specifies additional flags that control the priority class and the creation of the process. The following
creation flags can be specified in any combination, except as noted.
Value
CREATE_BREAKAWAY_
FROM_JOB
Meaning
Windows 2000: The child processes of a process
associated with a job are not associated with the job.
If the calling process is not associated with a job, this
flag has no effect. If the calling process is associated
with a job, the job must set the
JOB_OBJECT_BREAKAWAY_OK limit or
will fail.
CreateProcess
CREATE_DEFAULT_
ERROR_MODE
The new process does not inherit the error mode of
the calling process. Instead,
gives
the new process the current default error mode. An
application sets the current default error mode by
calling
.
This flag is particularly useful for multi-threaded shell
applications that run with hard errors disabled.
The default behavior for
is for the
new process to inherit the error mode of the caller.
Setting this flag changes that default behavior.
CreateProcess
SetErrorMode
CreateProcess
CREATE_FORCE_DOS
Windows NT/2000: This flag is valid only when
starting a 16-bit bound application. If set, the system
will force the application to run as an MS-DOS-based
application rather than as an OS/2-based application.
CREATE_NEW_CONSOLE
The new process has a new console, instead of
inheriting the parent's console. This flag cannot be
used with the DETACHED_PROCESS flag.
CREATE_NEW_
PROCESS_GROUP
The new process is the root process of a new process
group. The process group includes all processes that
are descendants of this root process. The process
identifier of the new process group is the same as the
process identifier, which is returned in the
lpProcessInformation parameter. Process groups are
used by the
function to
enable sending a CTRL+C or CTRL+BREAK signal to a
group of console processes.
GenerateConsoleCtrlEvent
CREATE_NO_WINDOW
CREATE_SEPARATE_
WOW VDM
starting a console application. If set, the console
application is run without a console window.
starting a 16-bit Windows-based application. If set,
28/01/01
CreateProcess
WOW_VDM
CREATE_SHARED_
WOW_VDM
Page 3 sur 6
starting a 16 bit Windows based application. If set,
the new process runs in a private Virtual DOS
Machine (VDM). By default, all 16-bit Windows-based
applications run as threads in a single, shared VDM.
The advantage of running separately is that a crash
only terminates the single VDM; any other programs
running in distinct VDMs continue to function
normally. Also, 16-bit Windows-based applications
that are run in separate VDMs have separate input
queues. That means that if one application stops
responding momentarily, applications in separate
VDMs continue to receive input. The disadvantage of
running separately is that it takes significantly more
memory to do so. You should use this flag only if the
user requests that 16-bit applications should run in
them own VDM.
Windows NT/2000: The flag is valid only when
starting a 16-bit Windows-based application. If the
DefaultSeparateVDM switch in the Windows section of
WIN.INI is TRUE, this flag causes the
function to override the switch and run the new
process in the shared Virtual DOS Machine.
CreateProcess
CREATE_SUSPENDED
The primary thread of the new process is created in a
suspended state, and does not run until the
function is called.
CREATE_UNICODE_
ENVIRONMENT
Indicates the format of the lpEnvironment parameter.
If this flag is set, the environment block pointed to by
lpEnvironment uses Unicode characters. Otherwise,
the environment block uses ANSI characters.
DEBUG_PROCESS
If this flag is set, the calling process is treated as a
debugger, and the new process is debugged. The
system notifies the debugger of all debug events that
occur in the process being debugged.
If you create a process with this flag set, only the
calling thread (the thread that called
) can call the
function.
This flag is not valid if the new
process is a 16-bit application.
ResumeThread
CreateProcess
Windows 95/98:
WaitForDebugEvent
DEBUG_ONLY_THIS_
PROCESS
If this flag is not set and the calling process is being
debugged, the new process becomes another process
being debugged by the calling process's debugger. If
the calling process is not a process being debugged,
no debugging-related actions occur.
DETACHED_PROCESS
For console processes, the new process does not
have access to the console of the parent process. The
new process can call the
function at a
later time to create a new console. This flag cannot
be used with the CREATE_NEW_CONSOLE flag.
AllocConsole
The dwCreationFlags parameter also controls the new process's priority class, which is used to
determine the scheduling priorities of the process's threads. If none of the following priority class flags
is specified, the priority class defaults to NORMAL_PRIORITY_CLASS unless the priority class of the
creating process is IDLE_PRIORITY_CLASS or BELOW_NORMAL_PRIORITY_CLASS. In this case, the
child process receives the default priority class of the calling process. One of the following flags can be
specified:
Priority
ABOVE_NORMAL_
PRIORITY_CLASS
BELOW_NORMAL_
PRIORITY_CLASS
Meaning
Windows 2000: Indicates a process that has priority
higher than NORMAL_PRIORITY_CLASS but lower than
HIGH_PRIORITY_CLASS.
Windows 2000: Indicates a process that has priority
higher than IDLE_PRIORITY_CLASS but lower than
NORMAL_PRIORITY_CLASS.
28/01/01
CreateProcess
Page 4 sur 6
HIGH_PRIORITY_CLASS
Indicates a process that performs time-critical tasks.
The threads of a high-priority class process preempt
the threads of normal-priority or idle-priority class
processes. An example is the Task List, which must
respond quickly when called by the user, regardless of
the load on the system. Use extreme care when using
the high-priority class, because a CPU-bound
application with a high-priority class can use nearly all
available cycles.
IDLE_PRIORITY_CLASS
Indicates a process whose threads run only when the
system is idle and are preempted by the threads of
any process running in a higher priority class. An
example is a screen saver. The idle priority class is
inherited by child processes.
NORMAL_PRIORITY_
CLASS
Indicates a normal process with no special scheduling
needs.
REALTIME_PRIORITY_
CLASS
Indicates a process that has the highest possible
priority. The threads of a real-time priority class
process preempt the threads of all other processes,
including operating system processes performing
important tasks. For example, a real-time process that
executes for more than a very brief interval can cause
disk caches not to flush or cause the mouse to be
unresponsive.
lpEnvironment
Pointer to an environment block for the new process. If this parameter is NULL, the new process uses
the environment of the calling process.
An environment block consists of a null-terminated block of null-terminated strings. Each string is in
the form:
name=value
Because the equal sign is used as a separator, it must not be used in the name of an environment
variable.
If an application provides an environment block, rather than passing NULL for this parameter, the
current directory information of the system drives is not automatically propagated to the new process.
For a discussion of this situation and how to handle it, see the following Remarks section.
An environment block can contain either Unicode or ANSI characters. If the environment block pointed
to by lpEnvironment contains Unicode characters, set the dwCreationFlags field's
CREATE_UNICODE_ENVIRONMENT flag. Otherwise, do not set this flag.
Note that an ANSI environment block is terminated by two zero bytes: one for the last string, one
more to terminate the block. A Unicode environment block is terminated by four zero bytes: two for
the last string, two more to terminate the block.
lpCurrentDirectory
Pointer to a null-terminated string that specifies the current drive and directory for the child process.
The string must be a full path and file name that includes a drive letter. If this parameter is NULL, the
new process will have the same current drive and directory as the calling process. This option is
provided primarily for shells that need to start an application and specify its initial drive and working
directory.
lpStartupInfo
Pointer to a STARTUPINFO structure that specifies how the main window for the new process should
appear.
lpProcessInformation
Pointer to a PROCESS_INFORMATION structure that receives identification information about the
new process.
Return Values
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
The CreateProcess function is used to run a new program. The WinExec and LoadModule functions are
still available, but they are implemented as calls to CreateProcess.
In addition to creating a process, CreateProcess also creates a thread object. The thread is created with
an initial stack whose size is described in the image header of the specified program's executable file. The
28/01/01
CreateProcess
Page 5 sur 6
thread begins execution at the image's entry point.
When created, the new process and the new thread handles receive full access rights. For either handle, if
a security descriptor is not provided, the handle can be used in any function that requires an object handle
to that type. When a security descriptor is provided, an access check is performed on all subsequent uses
of the handle before access is granted. If access is denied, the requesting process cannot use the handle
to gain access to the thread.
The process is assigned a 32-bit process identifier. The identifier is valid until the process terminates. It
can be used to identify the process, or specified in the OpenProcess function to open a handle to the
process. The initial thread in the process is also assigned a 32-bit thread identifier. The identifier is valid
until the thread terminates and can be used to uniquely identify the thread within the system. These
identifiers are returned in the PROCESS_INFORMATION structure.
When specifying an application name in the lpApplicationName or lpCommandLine strings, it doesn't
matter whether the application name includes the file name extension, with one exception: an MS-DOS –
based or Windows-based application whose file name extension is .com must include the .com extension.
The calling thread can use the WaitForInputIdle function to wait until the new process has finished its
initialization and is waiting for user input with no input pending. This can be useful for synchronization
between parent and child processes, because CreateProcess returns without waiting for the new process
to finish its initialization. For example, the creating process would use WaitForInputIdle before trying to
find a window associated with the new process.
The preferred way to shut down a process is by using the ExitProcess function, because this function
sends notification of approaching termination to all DLLs attached to the process. Other means of shutting
down a process do not notify the attached DLLs. Note that when a thread calls ExitProcess, other threads
of the process are terminated without an opportunity to execute any additional code (including the thread
termination code of attached DLLs).
ExitProcess, ExitThread, CreateThread, CreateRemoteThread, and a process that is starting (as the
result of a call by CreateProcess) are serialized between each other within a process. Only one of these
events at a time can happen in an address space, and the following restrictions apply.
During process startup and DLL initialization routines, new threads can be created, but they do not
begin execution until DLL initialization is finished for the process.
Only one thread at a time can be in a DLL initialization or detach routine.
The ExitProcess function does not return until there are no threads are in their DLL initialization or
detach routines.
The created process remains in the system until all threads within the process have terminated and all
handles to the process and any of its threads have been closed through calls to CloseHandle. The handles
for both the process and the main thread must be closed through calls to CloseHandle. If these handles
are not needed, it is best to close them immediately after the process is created.
When the last thread in a process terminates, the following events occur:
All objects opened by the process are implicitly closed.
The process's termination status (which is returned by GetExitCodeProcess) changes from its initial
value of STILL_ACTIVE to the termination status of the last thread to terminate.
The thread object of the main thread is set to the signaled state, satisfying any threads that were
waiting on the object.
The process object is set to the signaled state, satisfying any threads that were waiting on the object.
If the current directory on drive C is \MSVC\MFC, there is an environment variable called =C: whose value
is C:\MSVC\MFC. As noted in the previous description of lpEnvironment, such current directory information
for a system's drives does not automatically propagate to a new process when the CreateProcess
function's lpEnvironment parameter is non-NULL. An application must manually pass the current directory
information to the new process. To do so, the application must explicitly create the =X environment
variable strings, get them into alphabetical order (because the system uses a sorted environment), and
then put them into the environment block specified by lpEnvironment. Typically, they will go at the front of
the environment block, due to the previously mentioned environment block sorting.
One way to obtain the current directory variable for a drive X is to call GetFullPathName("X:",. .). That
avoids an application having to scan the environment block. If the full path returned is X:\, there is no
need to pass that value on as environment data, since the root directory is the default current directory for
drive X of a new process.
The handle returned by the CreateProcess function has PROCESS_ALL_ACCESS access to the process
object.
The current directory specified by the lpcurrentDirectory parameter is the current directory for the child
process. The current directory specified in item 2 under the lpCommandLine parameter is the current
directory for the parent process.
Windows NT/2000: When a process is created with CREATE_NEW_PROCESS_GROUP specified, an
implicit call to SetConsoleCtrlHandler(NULL,TRUE) is made on behalf of the new process; this means
that the new process has CTRL+C disabled. This lets good shells handle CTRL+C themselves, and
selectively pass that signal on to sub-processes. CTRL+BREAK is not disabled, and may be used to
interrupt the process/process group.
Requirements
Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98: Requires Windows 95 or later.
Windows CE: Requires version 1.0 or later.
28/01/01
CreateProcess
Page 6 sur 6
Header: Declared in winbase.h.
Import Library: Use kernel32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.
See Also
Processes and Threads Overview, Process and Thread Functions, AllocConsole, CloseHandle,
CreateProcessAsUser, CreateProcessWithLogonW, CreateRemoteThread, CreateThread,
ExitProcess, ExitThread, GenerateConsoleCtrlEvent, GetCommandLine, GetEnvironmentStrings,
GetExitCodeProcess, GetFullPathName, GetStartupInfo, GetSystemDirectory,
GetWindowsDirectory, LoadModule, OpenProcess, PROCESS_INFORMATION, ResumeThread,
SECURITY_ATTRIBUTES, SetConsoleCtrlHandler, SetErrorMode, STARTUPINFO,
TerminateProcess, WaitForInputIdle, WaitForDebugEvent, WinExec
Built on Friday, May 14, 1999
28/01/01
WaitForSingleObject
Page 1 sur 2
WaitForSingleObject
WaitForSingleObject
The
function returns when one of the following occurs:
The specified object is in the signaled state.
The time-out interval elapses.
To enter an alertable wait state, use the
function. To wait for multiple objects,
use the
.
WaitForMultipleObjects
WaitForSingleObjectEx
DWORD WaitForSingleObject(
HANDLE hHandle,
// handle to object to wait for
DWORD dwMilliseconds
// time-out interval in milliseconds
);
Parameters
hHandle
Handle to the object. For a list of the object types whose handles can be specified, see the following
Remarks section.
Windows NT/2000: The handle must have SYNCHRONIZE access. For more information, see
Standard Access Rights.
dwMilliseconds
Specifies the time-out interval, in milliseconds. The function returns if the interval elapses, even if the
object's state is nonsignaled. If dwMilliseconds is zero, the function tests the object's state and returns
immediately. If dwMilliseconds is INFINITE, the function's time-out interval never elapses.
Return Values
If the function succeeds, the return value indicates the event that caused the function to return. This value
can be one of the following.
Value
Meaning
WAIT_ABANDONED
The specified object is a mutex object that was not released
by the thread that owned the mutex object before the
owning thread terminated. Ownership of the mutex object is
granted to the calling thread, and the mutex is set to
nonsignaled.
WAIT_OBJECT_0
The state of the specified object is signaled.
WAIT_TIMEOUT
The time-out interval elapsed, and the object's state is
nonsignaled.
If the function fails, the return value is WAIT_FAILED. To get extended error information, call
GetLastError.
Remarks
The WaitForSingleObject function checks the current state of the specified object. If the object's state is
nonsignaled, the calling thread enters an efficient wait state. The thread consumes very little processor
time while waiting for the object state to become signaled or the time-out interval to elapse.
Before returning, a wait function modifies the state of some types of synchronization objects. Modification
occurs only for the object whose signaled state caused the function to return. For example, the count of a
semaphore object is decreased by one.
The WaitForSingleObject function can wait for the following objects:
Change notification
Console input
Event
Job
Mutex
Process
Semaphore
Thread
Waitable timer
For more information, see Synchronization Objects.
Use caution when calling the wait functions and code that directly or indirectly creates windows. If a thread
creates any windows, it must process messages. Message broadcasts are sent to all windows in the
system. A thread that uses a wait function with no time-out interval may cause the system to become
deadlocked. Two examples of code that indirectly creates windows are DDE and COM CoInitialize.
mk:@MSITStore:D:\Microsoft%20Visual%20Studio\MSDN\99OCT\1.../synchro_4ldg.ht
28/01/01
WaitForSingleObject
Page 2 sur 2
Therefore, if you have a thread that creates windows, use MsgWaitForMultipleObjects or
MsgWaitForMultipleObjectsEx, rather than WaitForSingleObject.
Requirements
See Also
Synchronization Overview, Synchronization Functions, MsgWaitForMultipleObjects,
MsgWaitForMultipleObjectsEx, WaitForMultipleObjects, WaitForSingleObjectEx
mk:@MSITStore:D:\Microsoft%20Visual%20Studio\MSDN\99OCT\1.../synchro_4ldg.ht
28/01/01
GetExitCodeProcess
Page 1 sur 1
GetExitCodeProcess
The GetExitCodeProcess function retrieves the termination status of the specified process.
BOOL GetExitCodeProcess(
HANDLE hProcess,
// handle to the process
LPDWORD lpExitCode
// address to receive termination status
);
Parameters
hProcess
Handle to the process.
Windows NT/2000: The handle must have PROCESS_QUERY_INFORMATION access. For more
information, see Process Security and Access Rights.
lpExitCode
Pointer to a 32-bit variable to receive the process termination status.
Return Values
Remarks
If the specified process has not terminated, the termination status returned is STILL_ACTIVE. If the
process has terminated, the termination status returned may be one of the following:
The exit value specified in the ExitProcess or TerminateProcess function.
The return value from the main or WinMain function of the process.
The exception value for an unhandled exception that caused the process to terminate.
Requirements
See Also
Processes and Threads Overview, Process and Thread Functions, ExitProcess, ExitThread,
TerminateProcess, WinMain
mk:@MSITStore:D:\Microsoft%20Visual%20Studio\MSDN\99OCT\.../prothred_4k6r.ht
28/01/01
CloseHandle
Page 1 sur 1
Platform SDK: Interprocess Communications
CloseHandle
The CloseHandle function closes an open object handle.
BOOL CloseHandle(
HANDLE hObject
);
// handle to object
Parameters
hObject
[in/out] Handle to an open object.
Return Values
Windows NT/2000: Closing an invalid handle raises an exception when the application is running under
a debugger. This includes closing a handle twice, and using CloseHandle on a handle returned by the
FindFirstFile function.
Remarks
The CloseHandle function closes handles to the following objects:
Access token
Communications device
Console input
Console screen buffer
Event
File
File mapping
Job
Mailslot
Mutex
Named pipe
Process
Semaphore
Socket
Thread
CloseHandle invalidates the specified object handle, decrements the object's handle count, and performs
object retention checks. After the last handle to an object is closed, the object is removed from the
system.
Closing a thread handle does not terminate the associated thread. To remove a thread object, you must
terminate the thread, then close all handles to the thread.
Use CloseHandle to close handles returned by calls to the CreateFile function. Use FindClose to close
handles returned by calls to FindFirstFile.
MAPI: For more information, see Syntax and Limitations for Win32 Functions Useful in MAPI Development.
Requirements
Header: Declared in winbase.h; include windows.h.
Library: Use kernel32.lib.
See Also
Handles and Objects Overview, Handle and Object Functions, CreateFile, DeleteFile, FindClose,
FindFirstFile
Built on Tuesday, August 17, 1999
mk:@MSITStore:D:\Microsoft%20Visual%20Studio\MSDN\99OCT\.../handobj_289x.ht
28/01/01