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

Artigo
08/25/2023

Desenha uma representação de um objeto no contexto do dispositivo especificado.

Sintaxe

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 o aspecto a ser desenhado, ou seja, como o objeto deve ser representado. As representações incluem conteúdo, um ícone, uma miniatura ou um documento impresso. Os valores válidos são obtidos das enumerações DVASPECT e DVASPECT2. Observe que objetos e contêineres mais recentes que dão suporte a interfaces de desenho otimizadas dão suporte aos valores de enumeração DVASPECT2 . Objetos e contêineres mais antigos que não dão suporte a interfaces de desenho otimizadas podem não dar suporte a DVASPECT2. Objetos sem janela permitem apenas DVASPECT_CONTENT, DVASPECT_OPAQUE e DVASPECT_TRANSPARENT.

[in] lindex

Parte do objeto que é de interesse para a operação de desenho. Sua interpretação varia dependendo do valor no parâmetro dwAspect. Consulte a enumeração DVASPECT para obter mais informações.

[in] pvAspect

Ponteiro para informações adicionais em uma estrutura DVASPECTINFO que permite otimizações de desenho dependendo do aspecto especificado. Observe que objetos e contêineres mais recentes que dão suporte a interfaces de desenho otimizadas também dão suporte a esse parâmetro. Objetos e contêineres mais antigos que não dão suporte a interfaces de desenho otimizadas sempre especificam NULL para esse parâmetro.

[in] ptd

Ponteiro para a estrutura DVTARGETDEVICE que descreve o dispositivo para o qual o objeto deve ser renderizado. Se FOR NULL, a exibição deverá ser renderizada para o dispositivo de destino padrão (normalmente a exibição). Um valor diferente de NULL é interpretado em conjunto com hdcTargetDev e hdcDraw. Por exemplo, se hdcDraw especificar uma impressora como o contexto do dispositivo, o parâmetro ptd apontará para uma estrutura que descreve esse dispositivo de impressora. Os dados poderão realmente ser impressos se hdcTargetDev for um valor válido ou poderão ser exibidos no modo de visualização de impressão se hdcTargetDev for NULL.

[in] hdcTargetDev

Contexto de informações para o dispositivo de destino indicado pelo parâmetro ptd do qual o objeto pode extrair métricas do dispositivo e testar os recursos do dispositivo. Se ptd for NULL; o objeto deve ignorar o valor no parâmetro hdcTargetDev .

[in] hdcDraw

Contexto do dispositivo no qual desenhar. Para um objeto sem janelas, o parâmetro hdcDraw deve estar no modo de mapeamento MM_TEXT com suas coordenadas lógicas que correspondem às coordenadas do cliente da janela que contém. Para um objeto sem janelas, o contexto do dispositivo deve estar no mesmo estado que o normalmente passado por uma mensagem WM_PAINT.

[in] lprcBounds

Ponteiro para uma estrutura RECTL especificando o retângulo em hdcDraw e no qual o objeto deve ser desenhado. Esse parâmetro controla o posicionamento e o alongamento do objeto. Esse parâmetro deve ser NULL para desenhar um objeto ativo in-loco sem janelas. Em todas as outras situações, NULL não é um valor legal e deve resultar em um código de erro E_INVALIDARG. Se o contêiner passar um valor não NULL para um objeto sem janelas, o objeto deverá renderizar o aspecto solicitado no contexto e no retângulo do dispositivo especificados. Um contêiner pode solicitar isso de um objeto sem janelas para renderizar uma segunda exibição não ativa do objeto ou imprimir o objeto.

[in] lprcWBounds

Se hdcDraw for um contexto de dispositivo de metarquivo, ponteiro para uma estrutura RECTL especificando o retângulo delimitador no metarquivo subjacente. A estrutura do retângulo contém a extensão da janela e a origem da janela. Esses valores são úteis para desenhar metarquivos. O retângulo indicado por lprcBounds está aninhado dentro deste retângulo lprcWBounds ; eles estão no mesmo espaço de coordenadas.

Se hdcDraw não for um contexto de dispositivo de metarquivo; lprcWBounds será NULL.

[in] pfnContinue

Ponteiro para uma função de retorno de chamada que o objeto de exibição deve chamar periodicamente durante uma longa operação de desenho para determinar se a operação deve continuar ou ser cancelada. Essa função retorna TRUE para continuar desenhando. Ele retorna FALSE para interromper o desenho, caso em que IViewObject::D raw retorna DRAW_E_ABORT.

dwContinue

[in] dwContinue

Valor a ser passado como um parâmetro para a função apontada pelo parâmetro pfnContinue . Normalmente, dwContinue é um ponteiro para uma estrutura definida pelo aplicativo necessária dentro da função de retorno de chamada.

Retornar valor

Esse método retorna S_OK com êxito. Outros valores retornados possíveis incluem o seguinte.

Código de retorno	Descrição
OLE_E_BLANK	Nenhum dado a ser extraído.
DRAW_E_ABORT	Operação de desenho anulada.
VIEW_E_DRAW	Erro ao desenhar.
DV_E_LINDEX	Valor inválido para lindex; Atualmente, há suporte para apenas -1.
DV_E_DVASPECT	Valor inválido para dwAspect.
OLE_E_INVALIDRECT	Retângulo inválido.

Comentários

Um aplicativo de contêiner emite uma chamada para IViewObject::D raw para criar uma representação de um objeto contido. Esse método desenha a peça especificada (lindex) da exibição especificada (dwAspect e pvAspect) no contexto do dispositivo especificado (hdcDraw). Formatação, fontes e outras decisões de renderização são tomadas com base no dispositivo de destino especificado pelo parâmetro ptd.

Há uma relação entre o valor dwDrawAspect e o valor lprcbounds . O valor lprcbounds especifica o retângulo em hdcDraw no qual o desenho deve ser mapeado. Para DVASPECT_THUMBNAIL, DVASPECT_ICON e DVASPECT_SMALLICON, o objeto desenha o que quiser desenhar e mapeia-o para o espaço fornecido da melhor maneira. Alguns objetos podem ser dimensionados para caber, enquanto alguns podem ser dimensionados para ajustar, mas preservar a taxa de proporção. Além disso, alguns podem ser dimensionados para que o desenho apareça em largura total, mas a parte inferior é cortada. O contêiner pode sugerir um tamanho por meio de IOleObject::SetExtent, mas não tem controle sobre o tamanho da renderização. No caso de DVASPECT_CONTENT, a implementação IViewObject::D raw deve usar as extensões fornecidas por IOleObject::SetExtent ou usar o retângulo delimitador fornecido no parâmetro lprcBounds .

Para objetos mais recentes que dão suporte a técnicas de desenho otimizadas e para objetos sem janelas, esse método deve ser usado da seguinte maneira:

Há suporte para novos aspectos de desenho no dwAspect , conforme definido em DVASPECT2.
O parâmetro pvAspect pode ser usado para passar informações adicionais que permitem otimizações de desenho por meio da estrutura DVASPECTINFO .
O método IViewObject::D raw pode ser chamado para redesenhar um objeto ativo in-loco sem janelas definindo o parâmetro lrpcBounds como NULL. Em todas as outras situações, NULL é um valor ilegal e deve resultar em um código de erro E_INVALIDARG. Um objeto sem janelas usa o retângulo passado pelo verbo de ativação ou chama IOleInPlaceObject::SetObjectRects em vez de usar esse parâmetro. Se o contêiner passar um valor não NULL para um objeto sem janelas, o objeto deverá renderizar o aspecto solicitado no contexto e no retângulo do dispositivo especificados. Um contêiner pode solicitar isso de um objeto sem janelas para renderizar uma segunda exibição não ativa do objeto ou imprimir o objeto. Consulte a interface IOleInPlaceSiteWindowless para obter mais informações sobre como desenhar objetos sem janelas.
Para objetos sem janela, o parâmetro dwAspect permite apenas os aspectos DVASPECT_CONTENT, DVASPECT_OPAQUE e DVASPECT_TRANSPARENT.
Para um objeto sem janelas, o parâmetro hdcDraw deve estar no modo de mapeamento MM_TEXT com suas coordenadas lógicas que correspondem às coordenadas do cliente da janela que contém. Para um objeto sem janelas, o contexto do dispositivo deve estar no mesmo estado que o normalmente passado por uma mensagem WM_PAINT.

Para manter a compatibilidade com objetos e contêineres mais antigos que não dão suporte a otimizações de desenho, todos os objetos, retangulares ou não, são necessários para manter uma origem e uma extensão retangular. Isso permite que o contêiner ainda considere todos os seus objetos inseridos como retângulos e passe os retângulos de renderização apropriados em Desenhar.

A extensão de um objeto depende do aspecto de desenho. Para objetos não retangulares, a extensão deve ser do tamanho de um retângulo que abrange todo o aspecto. Por convenção, a origem de um objeto é o canto superior esquerdo do retângulo do aspecto DVASPECT_CONTENT. Em outras palavras, a origem sempre coincide com o canto superior esquerdo do retângulo mantido pelo site do objeto, mesmo para um objeto não retangular.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	oleidl.h