IViewObject::D raw-Methode (oleidl.h)

Artikel
08/25/2023

Zeichnet eine Darstellung eines Objekts auf den angegebenen Gerätekontext.

Syntax

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
);

Parameter

[in] dwDrawAspect

Gibt den zu zeichnenden Aspekt an, d. h., wie das Objekt dargestellt werden soll. Darstellungen umfassen Inhalt, ein Symbol, eine Miniaturansicht oder ein gedrucktes Dokument. Gültige Werte stammen aus den Enumerationen DVASPECT und DVASPECT2. Beachten Sie, dass neuere Objekte und Container, die optimierte Zeichnungsschnittstellen unterstützen, die DVASPECT2-Enumerationswerte unterstützen. Ältere Objekte und Container, die keine optimierten Zeichnungsschnittstellen unterstützen, unterstützen möglicherweise keine DVASPECT2. Fensterlose Objekte lassen nur DVASPECT_CONTENT, DVASPECT_OPAQUE und DVASPECT_TRANSPARENT zu.

[in] lindex

Der Teil des Objekts, der für den Ziehvorgang relevant ist. Die Interpretation variiert je nach Wert im dwAspect-Parameter. Weitere Informationen finden Sie in der DVASPECT-Enumeration .

[in] pvAspect

Zeiger auf zusätzliche Informationen in einer DVASPECTINFO-Struktur , die Zeichnungsoptimierungen abhängig vom angegebenen Aspekt ermöglicht. Beachten Sie, dass neuere Objekte und Container, die optimierte Zeichnungsschnittstellen unterstützen, diesen Parameter ebenfalls unterstützen. Ältere Objekte und Container, die keine optimierten Zeichnungsschnittstellen unterstützen, geben für diesen Parameter immer NULL an.

[in] ptd

Zeiger auf die DVTARGETDEVICE-Struktur , die das Gerät beschreibt, für das das Objekt gerendert werden soll. Wenn NULL, sollte die Ansicht für das Standardzielgerät (in der Regel die Anzeige) gerendert werden. Ein anderer Wert als NULL wird in Verbindung mit hdcTargetDev und hdcDraw interpretiert. Wenn hdcDraw beispielsweise einen Drucker als Gerätekontext angibt, verweist der ptd-Parameter auf eine Struktur, die dieses Druckergerät beschreibt. Die Daten können tatsächlich gedruckt werden, wenn hdcTargetDev ein gültiger Wert ist, oder sie können im Druckvorschaumodus angezeigt werden, wenn hdcTargetDevNULL ist.

[in] hdcTargetDev

Informationskontext für das Zielgerät, das durch den ptd-Parameter angegeben wird, aus dem das Objekt Gerätemetriken extrahieren und die Funktionen des Geräts testen kann. Wenn ptdNULL ist; Das -Objekt sollte den Wert im hdcTargetDev-Parameter ignorieren.

[in] hdcDraw

Der Gerätekontext, auf dem gezeichnet werden soll. Bei einem fensterlosen Objekt sollte sich der hdcDraw-Parameter in MM_TEXT Zuordnungsmodus befinden, wobei seine logischen Koordinaten den Clientkoordinaten des enthaltenden Fensters entsprechen. Bei einem fensterlosen Objekt sollte sich der Gerätekontext im gleichen Zustand befinden wie der, der normalerweise von einer WM_PAINT-Nachricht übergeben wird.

[in] lprcBounds

Zeiger auf eine RECTL-Struktur, die das Rechteck in hdcDraw angibt und in dem das Objekt gezeichnet werden soll. Dieser Parameter steuert die Positionierung und Dehnung des Objekts. Dieser Parameter sollte NULL sein, um ein aktives Objekt ohne Fenster zu zeichnen. In jeder anderen Situation ist NULL kein rechtlicher Wert und sollte zu einem E_INVALIDARG Fehlercode führen. Wenn der Container einen Wert ungleich NULL an ein fensterloses Objekt übergibt, sollte das Objekt den angeforderten Aspekt im angegebenen Gerätekontext und Rechteck rendern. Ein Container kann dies von einem fensterlosen Objekt anfordern, um eine zweite, nicht aktive Ansicht des Objekts zu rendern oder das Objekt zu drucken.

[in] lprcWBounds

Wenn hdcDraw ein Metadateigerätekontext ist, zeiger auf eine RECTL-Struktur, die das umgebende Rechteck in der zugrunde liegenden Metadatei angibt. Die Rechteckstruktur enthält die Fensterausdehnung und den Fensterursprung. Diese Werte sind nützlich für das Zeichnen von Metadateien. Das durch lprcBounds angegebene Rechteck ist in diesem lprcWBounds-Rechteck geschachtelt. sie befinden sich im gleichen Koordinatenbereich.

Wenn hdcDraw kein Metadateigerätekontext ist; lprcWBounds ist NULL.

[in] pfnContinue

Der Zeiger auf eine Rückruffunktion, die das Ansichtsobjekt im Verlauf eines langwierigen Zeichenvorgangs regelmäßig aufrufen sollte, um zu bestimmen, ob der Vorgang fortgesetzt oder abgebrochen werden soll. Diese Funktion gibt TRUE zurück, um das Zeichnen fortzusetzen. Es gibt FALSE zurück, um die Zeichnung zu beenden. In diesem Fall gibt IViewObject::D raw DRAW_E_ABORT zurück.

dwContinue

[in] dwContinue

Wert, der als Parameter an die Funktion übergeben werden soll, auf die der pfnContinue-Parameter verweist. In der Regel ist dwContinue ein Zeiger auf eine anwendungsdefinierte Struktur, die innerhalb der Rückruffunktion benötigt wird.

Rückgabewert

Diese Methode gibt S_OK bei Erfolg zurück. Weitere mögliche Rückgabewerte:

Rückgabecode	Beschreibung
OLE_E_BLANK	Keine Daten, aus der gezeichnet werden kann.
DRAW_E_ABORT	Der Zeichnungsvorgang wurde abgebrochen.
VIEW_E_DRAW	Fehler beim Zeichnen.
DV_E_LINDEX	Ungültiger Wert für lindex; derzeit wird nur -1 unterstützt.
DV_E_DVASPECT	Ungültiger Wert für dwAspect.
OLE_E_INVALIDRECT	Ungültiges Rechteck.

Hinweise

Eine Containeranwendung ruft IViewObject::D raw auf, um eine Darstellung eines enthaltenen Objekts zu erstellen. Diese Methode zeichnet den angegebenen Teil (lindex) der angegebenen Ansicht (dwAspect und pvAspect) im angegebenen Gerätekontext (hdcDraw). Formatierung, Schriftarten und andere Renderingentscheidungen werden auf der Grundlage des Zielgeräts getroffen, das durch den ptd-Parameter angegeben wird.

Es besteht eine Beziehung zwischen dem dwDrawAspect-Wert und dem lprcbounds-Wert . Der Lprcbounds-Wert gibt das Rechteck in hdcDraw an, dem die Zeichnung zugeordnet werden soll. Für DVASPECT_THUMBNAIL, DVASPECT_ICON und DVASPECT_SMALLICON zeichnet das Objekt alles, was es zeichnen möchte, und ordnet es dem gegebenen Raum auf die beste Weise zu. Einige Objekte können entsprechend skaliert werden, während andere angepasst werden können, aber das Seitenverhältnis beibehalten. Darüber hinaus können einige skaliert werden, sodass die Zeichnung in voller Breite angezeigt wird, die untere Seite jedoch zugeschnitten ist. Der Container kann über IOleObject::SetExtent eine Größe vorschlagen, hat aber keine Kontrolle über die Renderinggröße. Im Fall von DVASPECT_CONTENT sollte die IViewObject::D raw-Implementierung entweder die von IOleObject::SetExtent angegebenen Blöcke verwenden oder das im lprcBounds-Parameter angegebene begrenzungsfähige Rechteck verwenden.

Für neuere Objekte, die optimierte Zeichnungstechniken unterstützen, und für fensterlose Objekte sollte diese Methode wie folgt verwendet werden:

Neue Zeichnungsaspekte werden in dwAspect unterstützt, wie in DVASPECT2 definiert.
Der parameter pvAspect kann verwendet werden, um zusätzliche Informationen zu übergeben, die Zeichnungsoptimierungen durch die DVASPECTINFO-Struktur ermöglichen.
Die IViewObject::D raw-Methode kann aufgerufen werden, um ein fensterloses aktives Objekt neu zu zeichnen, indem der lrpcBounds-Parameter auf NULL festgelegt wird. In jeder anderen Situation ist NULL ein unzulässiger Wert und sollte zu einem E_INVALIDARG Fehlercode führen. Ein fensterloses Objekt verwendet das Rechteck, das vom Aktivierungsverb übergeben wird, oder ruft IOleInPlaceObject::SetObjectRects auf, anstatt diesen Parameter zu verwenden. Wenn der Container einen Wert ungleich NULL an ein fensterloses Objekt übergibt, sollte das Objekt den angeforderten Aspekt im angegebenen Gerätekontext und Rechteck rendern. Ein Container kann dies von einem fensterlosen Objekt anfordern, um eine zweite, nicht aktive Ansicht des Objekts zu rendern oder das Objekt zu drucken. Weitere Informationen zum Zeichnen fensterloser Objekte finden Sie auf der IOleInPlaceSiteWindowless-Schnittstelle .
Für fensterlose Objekte lässt der dwAspect-Parameter nur die Aspekte DVASPECT_CONTENT, DVASPECT_OPAQUE und DVASPECT zu_TRANSPARENT.
Bei einem fensterlosen Objekt sollte sich der hdcDraw-Parameter in MM_TEXT Zuordnungsmodus befinden, wobei seine logischen Koordinaten den Clientkoordinaten des enthaltenden Fensters entsprechen. Bei einem fensterlosen Objekt sollte sich der Gerätekontext im gleichen Zustand befinden wie der, der normalerweise von einer WM_PAINT-Nachricht übergeben wird.

Um die Kompatibilität mit älteren Objekten und Containern zu gewährleisten, die keine Zeichnungsoptimierungen unterstützen, müssen alle Objekte , ob rechteckig oder nicht, einen Ursprung und einen rechteckigen Bereich beibehalten. Dadurch kann der Container weiterhin alle eingebetteten Objekte als Rechtecke betrachten und ihnen entsprechende Renderingrechtecke in Draw übergeben.

Die Ausdehnung eines Objekts hängt vom Zeichnungsaspekt ab. Bei nicht rechteckigen Objekten sollte der Bereich die Größe eines Rechtecks aufweisen, das den gesamten Aspekt abdeckt. Gemäß der Konvention ist der Ursprung eines Objekts die obere linke Ecke des Rechtecks des DVASPECT_CONTENT-Aspekts. Anders ausgedrückt: Der Ursprung fällt immer mit der oberen linken Ecke des Rechtecks zusammen, die von der Website des Objekts verwaltet wird, auch für ein nicht rechteckiges Objekt.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	oleidl.h