CreateDCW, fonction (wingdi.h)

Article
08/27/2023

La fonction CreateDC crée un contexte d’appareil (DC) pour un appareil à l’aide du nom spécifié.

Syntaxe

HDC CreateDCW(
       LPCWSTR        pwszDriver,
  [in] LPCWSTR        pwszDevice,
       LPCWSTR        pszPort,
  [in] const DEVMODEW *pdm
);

Paramètres

pwszDriver

Pointeur vers une chaîne de caractères terminée par null qui spécifie DISPLAY ou le nom d’un périphérique d’affichage spécifique. Pour l’impression, nous vous recommandons de passer null à lpszDriver , car GDI ignore lpszDriver pour les périphériques d’imprimante.

[in] pwszDevice

Pointeur vers une chaîne de caractères terminée par null qui spécifie le nom du périphérique de sortie spécifique utilisé, comme indiqué par le Gestionnaire d’impression (par exemple, Epson FX-80). Il ne s’agit pas du nom du modèle d’imprimante. Le paramètre lpszDevice doit être utilisé.

Pour obtenir des noms valides pour les affichages, appelez EnumDisplayDevices.

Si lpszDriver a la valeur DISPLAY ou le nom de l’appareil d’un périphérique d’affichage spécifique, lpszDevice doit avoir la valeur NULL ou ce même nom d’appareil. Si lpszDevice a la valeur NULL, un contrôleur de domaine est créé pour le périphérique d’affichage principal.

S’il existe plusieurs moniteurs sur le système, l’appel CreateDC(TEXT("DISPLAY"),NULL,NULL,NULL) crée un contrôleur de domaine couvrant tous les moniteurs.

pszPort

Ce paramètre est ignoré et doit être défini sur NULL. Il est fourni uniquement pour la compatibilité avec Windows 16 bits.

[in] pdm

Pointeur vers une structure DEVMODE contenant des données d’initialisation spécifiques à l’appareil pour le pilote de périphérique. La fonction DocumentProperties récupère cette structure remplie pour un appareil spécifié. Le paramètre pdm doit avoir la valeur NULL si le pilote de périphérique doit utiliser l’initialisation par défaut (le cas échéant) spécifiée par l’utilisateur.

Si lpszDriver est DISPLAY, pdm doit avoir la valeur NULL ; GDI utilise ensuite le DEVMODE actuel de l’appareil d’affichage.

Valeur retournée

Si la fonction réussit, la valeur de retour est le handle d’un contrôleur de domaine pour l’appareil spécifié.

Si la fonction échoue, la valeur de retour est NULL.

Remarques

Notez que le handle du contrôleur de domaine ne peut être utilisé que par un seul thread à la fois.

Pour les paramètres lpszDriver et lpszDevice, appelez EnumDisplayDevices pour obtenir des noms valides pour les affichages .

Lorsque vous n’avez plus besoin du contrôleur de domaine, appelez la fonction DeleteDC .

Si lpszDriver ou lpszDevice est DISPLAY, le thread qui appelle CreateDC possède le HDC créé. Lorsque ce thread est détruit, le HDC n’est plus valide. Par conséquent, si vous créez le HDC et le passez à un autre thread, puis quittez le premier thread, le deuxième thread ne pourra pas utiliser le HDC.

Lorsque vous appelez CreateDC pour créer le HDC d’un périphérique d’affichage, vous devez passer à pdmnull ou un pointeur vers DEVMODE qui correspond au DEVMODE actuel de l’appareil d’affichage spécifié par lpszDevice . Nous vous recommandons de passer la valeur NULL et de ne pas essayer de faire correspondre exactement le DEVMODE pour le périphérique d’affichage actuel.

Lorsque vous appelez CreateDC pour créer le HDC pour un périphérique d’imprimante, le pilote d’imprimante valide le DEVMODE. Si le pilote d’imprimante détermine que le DEVMODE n’est pas valide (autrement dit, le pilote d’imprimante ne peut pas convertir ou consommer le DEVMODE), le pilote d’imprimante fournit un DEVMODE par défaut pour créer le HDC pour le périphérique d’imprimante.

ICM: Pour activer ICM, définissez le membre dmICMMethod de la structure DEVMODE (pointé par le paramètre pInitData ) sur la valeur appropriée.

Exemples

Pour obtenir un exemple, consultez Capture d’une image.

Notes

L’en-tête wingdi.h définit CreateDC comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	wingdi.h (inclure Windows.h)
Bibliothèque	Gdi32.lib
DLL	Gdi32.dll