Método IViewObject::D raw (oleidl.h)

Artículo
03/15/2023

Dibuja una representación de un objeto en el contexto de dispositivo especificado.

Sintaxis

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

Parámetros

[in] dwDrawAspect

Especifica el aspecto que se va a dibujar, es decir, cómo se representará el objeto. Las representaciones incluyen contenido, un icono, una miniatura o un documento impreso. Los valores válidos se toman de las enumeraciones DVASPECT y DVASPECT2. Tenga en cuenta que los objetos y contenedores más recientes que admiten interfaces de dibujo optimizadas admiten los valores de enumeración DVASPECT2 . Es posible que los objetos y contenedores antiguos que no admiten interfaces de dibujo optimizadas no admitan DVASPECT2. Los objetos sin ventana solo permiten DVASPECT_CONTENT, DVASPECT_OPAQUE y DVASPECT_TRANSPARENT.

[in] lindex

Parte del objeto que es de interés para la operación de dibujo. Su interpretación varía según el valor del parámetro dwAspect. Consulte la enumeración DVASPECT para obtener más información.

[in] pvAspect

Puntero a información adicional en una estructura DVASPECTINFO que permite optimizaciones de dibujo según el aspecto especificado. Tenga en cuenta que los objetos y contenedores más recientes que admiten interfaces de dibujo optimizadas también admiten este parámetro. Los objetos y contenedores antiguos que no admiten interfaces de dibujo optimizadas siempre especifican NULL para este parámetro.

[in] ptd

Puntero a la estructura DVTARGETDEVICE que describe el dispositivo para el que se va a representar el objeto. Si es NULL, la vista debe representarse para el dispositivo de destino predeterminado (normalmente la pantalla). Un valor distinto de NULL se interpreta junto con hdcTargetDev y hdcDraw. Por ejemplo, si hdcDraw especifica una impresora como contexto del dispositivo, el parámetro ptd apunta a una estructura que describe ese dispositivo de impresora. Los datos se pueden imprimir realmente si hdcTargetDev es un valor válido o se pueden mostrar en modo de vista previa de impresión si hdcTargetDev es NULL.

[in] hdcTargetDev

Contexto de información para el dispositivo de destino indicado por el parámetro ptd desde el que el objeto puede extraer las métricas del dispositivo y probar las funcionalidades del dispositivo. Si ptd es NULL; el objeto debe omitir el valor en el parámetro hdcTargetDev .

[in] hdcDraw

Contexto de dispositivo en el que se va a dibujar. Para un objeto sin ventanas, el parámetro hdcDraw debe estar en MM_TEXT modo de asignación con sus coordenadas lógicas que coincidan con las coordenadas de cliente de la ventana contenedora. Para un objeto sin ventanas, el contexto del dispositivo debe estar en el mismo estado que el que normalmente pasa un mensaje de WM_PAINT.

[in] lprcBounds

Puntero a una estructura RECTL que especifica el rectángulo en hdcDraw y en el que se debe dibujar el objeto. Este parámetro controla el posicionamiento y la extensión del objeto. Este parámetro debe ser NULL para dibujar un objeto activo en contexto sin ventanas. En cualquier otra situación, NULL no es un valor legal y debe dar lugar a un código de error E_INVALIDARG. Si el contenedor pasa un valor distinto de NULL a un objeto sin ventanas, el objeto debe representar el aspecto solicitado en el contexto de dispositivo y el rectángulo especificados. Un contenedor puede solicitarlo desde un objeto sin ventana para representar una segunda vista no activa del objeto o para imprimir el objeto.

[in] lprcWBounds

Si hdcDraw es un contexto de dispositivo de metarchivo, puntero a una estructura RECTL que especifica el rectángulo delimitador en el metarchivo subyacente. La estructura del rectángulo contiene la extensión de la ventana y el origen de la ventana. Estos valores son útiles para dibujar metarchivos. El rectángulo indicado por lprcBounds está anidado dentro de este rectángulo lprcWBounds ; están en el mismo espacio de coordenadas.

Si hdcDraw no es un contexto de dispositivo de metarchivo; lprcWBounds será NULL.

[in] pfnContinue

Puntero a una función de devolución de llamada al que el objeto de vista debe llamar periódicamente durante una operación de dibujo prolongada para determinar si la operación debe continuar o se debe cancelar. Esta función devuelve TRUE para continuar dibujando. Devuelve FALSE para detener el dibujo en cuyo caso IViewObject::D raw devuelve DRAW_E_ABORT.

dwContinue

[in] dwContinue

Valor que se va a pasar como parámetro a la función a la que apunta el parámetro pfnContinue . Normalmente, dwContinue es un puntero a una estructura definida por la aplicación necesaria dentro de la función de devolución de llamada.

Valor devuelto

Este método devuelve S_OK cuando funciona correctamente. Otros posibles valores devueltos son los siguientes.

Código devuelto	Descripción
OLE_E_BLANK	No hay datos de los que extraer.
DRAW_E_ABORT	Operación de dibujo anulada.
VIEW_E_DRAW	Error en el dibujo.
DV_E_LINDEX	Valor no válido para lindex; actualmente solo se admite -1.
DV_E_DVASPECT	Valor no válido para dwAspect.
OLE_E_INVALIDRECT	Rectángulo no válido.

Comentarios

Una aplicación contenedora emite una llamada a IViewObject::D raw para crear una representación de un objeto contenido. Este método dibuja la pieza especificada (lindex) de la vista especificada (dwAspect y pvAspect) en el contexto de dispositivo especificado (hdcDraw). El formato, las fuentes y otras decisiones de representación se toman en función del dispositivo de destino especificado por el parámetro ptd.

Hay una relación entre el valor dwDrawAspect y el valor lprcbounds . El valor lprcbounds especifica el rectángulo en hdcDraw en el que se asignará el dibujo. Para DVASPECT_THUMBNAIL, DVASPECT_ICON y DVASPECT_SMALLICON, el objeto dibuja lo que quiera dibujar y lo asigna al espacio proporcionado de la mejor manera. Algunos objetos se pueden escalar para ajustarse, mientras que algunos se pueden escalar para ajustarse, pero conservar la relación de aspecto. Además, algunos pueden escalar para que el dibujo aparezca en el ancho completo, pero la parte inferior está recortada. El contenedor puede sugerir un tamaño a través de IOleObject::SetExtent, pero no tiene control sobre el tamaño de representación. En el caso de DVASPECT_CONTENT, la implementación de IViewObject::D raw debe usar las extensiones proporcionadas por IOleObject::SetExtent o usar el rectángulo delimitador especificado en el parámetro lprcBounds .

Para los objetos más recientes que admiten técnicas de dibujo optimizadas y para objetos sin ventanas, este método debe usarse de la siguiente manera:

Se admiten nuevos aspectos de dibujo en dwAspect , tal como se define en DVASPECT2.
El parámetro pvAspect se puede usar para pasar información adicional que permite optimizaciones de dibujo a través de la estructura DVASPECTINFO .
Se puede llamar al método IViewObject::D raw para volver a dibujar un objeto activo en contexto sin ventana estableciendo el parámetro lrpcBounds en NULL. En cualquier otra situación, NULL es un valor no válido y debe dar lugar a un código de error E_INVALIDARG. Un objeto sin ventanas usa el rectángulo pasado por el verbo de activación o llama a IOleInPlaceObject::SetObjectRects en lugar de usar este parámetro. Si el contenedor pasa un valor distinto de NULL a un objeto sin ventanas, el objeto debe representar el aspecto solicitado en el contexto de dispositivo y el rectángulo especificados. Un contenedor puede solicitarlo desde un objeto sin ventana para representar una segunda vista no activa del objeto o para imprimir el objeto. Vea la interfaz IOleInPlaceSiteWindowless para obtener más información sobre el dibujo de objetos sin ventana.
En el caso de objetos sin ventanas, el parámetro dwAspect solo permite los aspectos DVASPECT_CONTENT, DVASPECT_OPAQUE y DVASPECT_TRANSPARENT.
Para un objeto sin ventanas, el parámetro hdcDraw debe estar en MM_TEXT modo de asignación con sus coordenadas lógicas que coincidan con las coordenadas de cliente de la ventana contenedora. Para un objeto sin ventanas, el contexto del dispositivo debe estar en el mismo estado que el que normalmente pasa un mensaje de WM_PAINT.

Para mantener la compatibilidad con objetos y contenedores antiguos que no admiten optimizaciones de dibujo, todos los objetos, rectangulares o no, son necesarios para mantener un origen y una extensión rectangular. Esto permite que el contenedor tenga en cuenta todos sus objetos incrustados como rectángulos y pasarlos rectángulos de representación adecuados en Draw.

La extensión de un objeto depende del aspecto del dibujo. Para los objetos no rectangulares, la extensión debe ser el tamaño de un rectángulo que cubre todo el aspecto. Por convención, el origen de un objeto es la esquina superior izquierda del rectángulo del aspecto DVASPECT_CONTENT. En otras palabras, el origen siempre coincide con la esquina superior izquierda del rectángulo mantenido por el sitio del objeto, incluso para un objeto no rectangular.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	oleidl.h