IViewObject ::D raw, méthode (oleidl.h)

Article
08/25/2023

Dessine une représentation d’un objet dans le contexte d’appareil spécifié.

Syntaxe

HRESULT Draw(
  [in] DWORD                          dwDrawAspect,
  [in] LONG                           lindex,
  [in] void                           *pvAspect,
  [in] DVTARGETDEVICE                 *ptd,
  [in] HDC                            hdcTargetDev,
  [in] HDC                            hdcDraw,
  [in] LPCRECTL                       lprcBounds,
  [in] LPCRECTL                       lprcWBounds,
  [in] BOOL(* )(ULONG_PTR dwContinue) pfnContinue,
  [in] ULONG_PTR                      dwContinue
);

Paramètres

[in] dwDrawAspect

Spécifie l'aspect à dessiner, c'est-à-dire la façon dont l'objet doit être représenté. Les représentations incluent du contenu, une icône, une miniature ou un document imprimé. Les valeurs valides sont extraites des énumérations DVASPECT et DVASPECT2. Notez que les objets et conteneurs plus récents qui prennent en charge les interfaces de dessin optimisées prennent en charge les valeurs d’énumération DVASPECT2 . Les objets et conteneurs plus anciens qui ne prennent pas en charge les interfaces de dessin optimisées peuvent ne pas prendre en charge les DVASPECT2. Les objets sans fenêtre autorisent uniquement DVASPECT_CONTENT, DVASPECT_OPAQUE et DVASPECT_TRANSPARENT.

[in] lindex

Partie de l'objet appropriée pour l'opération de dessin. Son interprétation varie en fonction de la valeur dans le paramètre dwAspect. Pour plus d’informations, consultez l’énumération DVASPECT .

[in] pvAspect

Pointeur vers des informations supplémentaires dans une structure DVASPECTINFO qui permet d’optimiser le dessin en fonction de l’aspect spécifié. Notez que les objets et conteneurs plus récents qui prennent en charge les interfaces de dessin optimisées prennent également en charge ce paramètre. Les objets et conteneurs plus anciens qui ne prennent pas en charge les interfaces de dessin optimisées spécifient toujours null pour ce paramètre.

[in] ptd

Pointeur vers la structure DVTARGETDEVICE qui décrit l’appareil pour lequel l’objet doit être rendu. Si la valeur est NULL, la vue doit être rendue pour l’appareil cible par défaut (généralement l’affichage). Une valeur autre que NULL est interprétée conjointement avec hdcTargetDev et hdcDraw. Par exemple, si hdcDraw spécifie une imprimante comme contexte d’appareil, le paramètre ptd pointe vers une structure décrivant ce périphérique d’imprimante. Les données peuvent en fait être imprimées si hdcTargetDev est une valeur valide ou elles peuvent être affichées en mode aperçu avant impression si hdcTargetDev a la valeur NULL.

[in] hdcTargetDev

Contexte d’information pour l’appareil cible indiqué par le paramètre ptd à partir duquel l’objet peut extraire les métriques de l’appareil et tester les fonctionnalités de l’appareil. Si ptd a la valeur NULL ; l’objet doit ignorer la valeur dans le paramètre hdcTargetDev .

[in] hdcDraw

Contexte de périphérique sur lequel dessiner. Pour un objet sans fenêtre, le paramètre hdcDraw doit être en mode de mappage MM_TEXT avec ses coordonnées logiques correspondant aux coordonnées client de la fenêtre conteneur. Pour un objet sans fenêtre, le contexte de l’appareil doit être dans le même état que celui normalement transmis par un message WM_PAINT.

[in] lprcBounds

Pointeur vers une structure RECTL spécifiant le rectangle sur hdcDraw et dans lequel l’objet doit être dessiné. Ce paramètre contrôle le positionnement et l’étirement de l’objet. Ce paramètre doit avoir la valeur NULL pour dessiner un objet actif sur place sans fenêtre. Dans toutes les autres situations, NULL n’est pas une valeur légale et doit entraîner un code d’erreur E_INVALIDARG. Si le conteneur transmet une valeur non NULL à un objet sans fenêtre, l’objet doit restituer l’aspect demandé dans le contexte d’appareil et le rectangle spécifiés. Un conteneur peut demander cela à partir d’un objet sans fenêtre pour afficher une deuxième vue non active de l’objet ou pour imprimer l’objet.

[in] lprcWBounds

Si hdcDraw est un contexte de périphérique de métafichier, pointeur vers une structure RECTL spécifiant le rectangle englobant dans le métafichier sous-jacent. La structure rectangle contient l’étendue de la fenêtre et l’origine de la fenêtre. Ces valeurs sont utiles pour dessiner des métafichiers. Le rectangle indiqué par lprcBounds est imbriqué à l’intérieur de ce rectangle lprcWBounds ; ils se trouvent dans le même espace de coordonnées.

Si hdcDraw n’est pas un contexte d’appareil de métafichier ; lprcWBounds aura la valeur NULL.

[in] pfnContinue

Pointeur vers une fonction de rappel que l'objet de vue doit périodiquement appeler durant une longue opération de dessin afin de déterminer si l'opération doit se poursuivre ou être annulée. Cette fonction retourne TRUE pour continuer le dessin. Elle retourne FALSE pour arrêter le dessin, auquel cas IViewObject ::D raw retourne DRAW_E_ABORT.

dwContinue

[in] dwContinue

Valeur à passer en tant que paramètre à la fonction pointée par le paramètre pfnContinue . En règle générale, dwContinue est un pointeur vers une structure définie par l’application nécessaire à la fonction de rappel.

Valeur retournée

Cette méthode retourne S_OK en cas de réussite. Les autres valeurs de retour possibles sont les suivantes.

Code de retour	Description
OLE_E_BLANK	Aucune donnée à partir de quoi dessiner.
DRAW_E_ABORT	Opération de dessin abandonnée.
VIEW_E_DRAW	Erreur lors du dessin.
DV_E_LINDEX	Valeur non valide pour lindex ; Actuellement, seul -1 est pris en charge.
DV_E_DVASPECT	Valeur non valide pour dwAspect.
OLE_E_INVALIDRECT	Rectangle non valide.

Remarques

Une application conteneur émet un appel à IViewObject ::D raw pour créer une représentation d’un objet contenu. Cette méthode dessine la partie spécifiée (lindex) de la vue spécifiée (dwAspect et pvAspect) sur le contexte d’appareil spécifié (hdcDraw). La mise en forme, les polices et d’autres décisions de rendu sont prises sur la base de l’appareil cible spécifié par le paramètre ptd.

Il existe une relation entre la valeur dwDrawAspect et la valeur lprcbounds . La valeur lprcbounds spécifie le rectangle sur hdcDraw dans lequel le dessin doit être mappé. Pour DVASPECT_THUMBNAIL, DVASPECT_ICON et DVASPECT_SMALLICON, l’objet dessine ce qu’il souhaite dessiner et le mappe à l’espace donné de la meilleure façon. Certains objets peuvent être mis à l’échelle pour s’adapter, tandis que d’autres peuvent être mis à l’échelle pour s’adapter, mais conserver les proportions. En outre, certains peuvent être mis à l’échelle de sorte que le dessin apparaisse à pleine largeur, mais le bas est rogné. Le conteneur peut suggérer une taille via IOleObject ::SetExtent, mais il n’a aucun contrôle sur la taille de rendu. Dans le cas de DVASPECT_CONTENT, l’implémentation IViewObject ::D raw doit utiliser les étendues fournies par IOleObject ::SetExtent ou utiliser le rectangle englobant donné dans le paramètre lprcBounds .

Pour les objets plus récents qui prennent en charge les techniques de dessin optimisées et pour les objets sans fenêtre, cette méthode doit être utilisée comme suit :

Les nouveaux aspects de dessin sont pris en charge dans dwAspect , comme défini dans DVASPECT2.
Le paramètre pvAspect peut être utilisé pour transmettre des informations supplémentaires permettant des optimisations de dessin via la structure DVASPECTINFO .
La méthode IViewObject ::D raw peut être appelée pour redessiner un objet actif sur place sans fenêtre en définissant le paramètre lrpcBounds sur NULL. Dans toutes les autres situations, NULL est une valeur non conforme et doit entraîner un code d’erreur E_INVALIDARG. Un objet sans fenêtre utilise le rectangle transmis par le verbe d’activation ou appelle IOleInPlaceObject ::SetObjectRects au lieu d’utiliser ce paramètre. Si le conteneur transmet une valeur non NULL à un objet sans fenêtre, l’objet doit restituer l’aspect demandé dans le contexte d’appareil et le rectangle spécifiés. Un conteneur peut demander cela à partir d’un objet sans fenêtre pour afficher une deuxième vue non active de l’objet ou pour imprimer l’objet. Pour plus d’informations sur le dessin d’objets sans fenêtre, consultez l’interface IOleInPlaceSiteWindowless .
Pour les objets sans fenêtre, le paramètre dwAspect autorise uniquement les aspects DVASPECT_CONTENT, DVASPECT_OPAQUE et DVASPECT_TRANSPARENT.
Pour un objet sans fenêtre, le paramètre hdcDraw doit être en mode de mappage MM_TEXT avec ses coordonnées logiques correspondant aux coordonnées client de la fenêtre conteneur. Pour un objet sans fenêtre, le contexte de l’appareil doit être dans le même état que celui normalement transmis par un message WM_PAINT.

Pour maintenir la compatibilité avec les anciens objets et conteneurs qui ne prennent pas en charge les optimisations de dessin, tous les objets, rectangulaires ou non, doivent conserver une origine et une étendue rectangulaire. Cela permet au conteneur de considérer tous ses objets incorporés comme des rectangles et de leur passer les rectangles de rendu appropriés dans Draw.

L’étendue d’un objet dépend de l’aspect dessin. Pour les objets non rectangulaires, l’étendue doit être de la taille d’un rectangle couvrant l’aspect entier. Par convention, l’origine d’un objet est le coin supérieur gauche du rectangle de l’aspect DVASPECT_CONTENT. En d’autres termes, l’origine coïncide toujours avec le coin supérieur gauche du rectangle géré par le site de l’objet, même pour un objet non rectangulaire.

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	oleidl.h