Metodo IViewObject::D raw (oleidl.h)

Articolo
03/05/2024

Disegna una rappresentazione di un oggetto nel contesto di dispositivo specificato.

Sintassi

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

Parametri

[in] dwDrawAspect

Specifica l'aspetto da disegnare, vale a dire la modalità con cui l'oggetto deve essere rappresentato. Le rappresentazioni includono contenuto, un'icona, un'anteprima o un documento stampato. I valori validi vengono ricavati dalle enumerazioni DVASPECT e DVASPECT2. Si noti che gli oggetti e i contenitori più recenti che supportano interfacce di disegno ottimizzate supportano i valori di enumerazione DVASPECT2 . Gli oggetti e i contenitori meno recenti che non supportano interfacce di disegno ottimizzate potrebbero non supportare DVASPECT2. Gli oggetti senza finestra consentono solo DVASPECT_CONTENT, DVASPECT_OPAQUE e DVASPECT_TRANSPARENT.

[in] lindex

Parte dell'oggetto che riveste interesse per l'operazione di creazione. L'interpretazione varia a seconda del valore nel parametro dwAspect. Per altre informazioni, vedere l'enumerazione DVASPECT .

[in] pvAspect

Puntatore a informazioni aggiuntive in una struttura DVASPECTINFO che consente ottimizzazioni di disegno a seconda dell'aspetto specificato. Si noti che anche gli oggetti e i contenitori più recenti che supportano interfacce di disegno ottimizzate supportano questo parametro. Gli oggetti e i contenitori meno recenti che non supportano interfacce di disegno ottimizzate specificano sempre NULL per questo parametro.

[in] ptd

Puntatore alla struttura DVTARGETDEVICE che descrive il dispositivo per il quale deve essere eseguito il rendering dell'oggetto. Se NULL, il rendering della visualizzazione deve essere eseguito per il dispositivo di destinazione predefinito (in genere lo schermo). Un valore diverso da NULL viene interpretato insieme a hdcTargetDev e hdcDraw. Ad esempio, se hdcDraw specifica una stampante come contesto di dispositivo, il parametro ptd punta a una struttura che descrive il dispositivo della stampante. I dati possono essere effettivamente stampati se hdcTargetDev è un valore valido o possono essere visualizzati in modalità anteprima di stampa se hdcTargetDev è NULL.

[in] hdcTargetDev

Contesto informativo per il dispositivo di destinazione indicato dal parametro ptd da cui l'oggetto può estrarre le metriche del dispositivo e testare le funzionalità del dispositivo. Se ptd è NULL; l'oggetto deve ignorare il valore nel parametro hdcTargetDev .

[in] hdcDraw

Contesto del dispositivo su cui creare. Per un oggetto senza finestra, il parametro hdcDraw deve essere in modalità di mapping MM_TEXT con le coordinate logiche corrispondenti alle coordinate client della finestra contenitore. Per un oggetto senza finestra, il contesto del dispositivo deve trovarsi nello stesso stato di quello normalmente passato da un messaggio WM_PAINT.

[in] lprcBounds

Puntatore a una struttura RECTL che specifica il rettangolo in hdcDraw e in cui deve essere disegnato l'oggetto. Questo parametro controlla il posizionamento e l'estensione dell'oggetto. Questo parametro deve essere NULL per disegnare un oggetto attivo sul posto senza finestra. In ogni altra situazione, NULL non è un valore legale e deve generare un codice di errore E_INVALIDARG. Se il contenitore passa un valore non NULL a un oggetto senza finestra, l'oggetto deve eseguire il rendering dell'aspetto richiesto nel contesto del dispositivo e nel rettangolo specificati. Un contenitore può richiedere a un oggetto senza finestra di eseguire il rendering di una seconda visualizzazione non attiva dell'oggetto o di stampare l'oggetto.

[in] lprcWBounds

Se hdcDraw è un contesto di dispositivo metafile, puntatore a una struttura RECTL che specifica il rettangolo di delimitazione nel metafile sottostante. La struttura rettangolo contiene l'estensione della finestra e l'origine della finestra. Questi valori sono utili per disegnare metafile. Il rettangolo indicato da lprcBounds è annidato all'interno di questo rettangolo lprcWBounds ; si trovano nello stesso spazio delle coordinate.

Se hdcDraw non è un contesto di dispositivo metafile; lprcWBounds sarà NULL.

[in] pfnContinue

Puntatore a una funzione di callback che l'oggetto visualizzazione deve chiamare periodicamente durante un'operazione di creazione di lunga durata per determinare se l'operazione deve continuare oppure essere annullata. Questa funzione restituisce TRUE per continuare il disegno. Restituisce FALSE per arrestare il disegno nel qual caso IViewObject::D raw restituisce DRAW_E_ABORT.

dwContinue

[in] dwContinue

Valore da passare come parametro alla funzione a cui punta il parametro pfnContinue . In genere , dwContinue è un puntatore a una struttura definita dall'applicazione necessaria all'interno della funzione di callback.

Valore restituito

Questo metodo restituisce S_OK se l'operazione ha esito positivo. Gli altri valori restituiti possibili includono i seguenti:

Codice restituito	Descrizione
OLE_E_BLANK	Nessun dato da cui disegnare.
DRAW_E_ABORT	Operazione di disegno interrotta.
VIEW_E_DRAW	Errore nel disegno.
DV_E_LINDEX	Valore non valido per lindex; attualmente è supportato solo -1.
DV_E_DVASPECT	Valore non valido per dwAspect.
OLE_E_INVALIDRECT	Rettangolo non valido.

Commenti

Un'applicazione contenitore invia una chiamata a IViewObject::D raw per creare una rappresentazione di un oggetto contenuto. Questo metodo disegna il pezzo specificato (lindex) della visualizzazione specificata (dwAspect e pvAspect) nel contesto di dispositivo specificato (hdcDraw). La formattazione, i tipi di carattere e altre decisioni di rendering vengono prese in base al dispositivo di destinazione specificato dal parametro ptd.

Esiste una relazione tra il valore dwDrawAspect e il valore lprcbounds . Il valore lprcbounds specifica il rettangolo in hdcDraw in cui eseguire il mapping del disegno. Per DVASPECT_THUMBNAIL, DVASPECT_ICON e DVASPECT_SMALLICON, l'oggetto disegna tutto ciò che vuole disegnare e lo esegue il mapping nello spazio specificato nel modo migliore. Alcuni oggetti possono essere ridimensionati per adattarsi mentre alcuni potrebbero adattarsi ma mantenere le proporzioni. Inoltre, alcuni potrebbero ridimensionare in modo che il disegno venga visualizzato a larghezza intera, ma il fondo viene ritagliato. Il contenitore può suggerire una dimensione tramite IOleObject::SetExtent, ma non ha alcun controllo sulle dimensioni del rendering. Nel caso di DVASPECT_CONTENT, l'implementazione di IViewObject::D raw deve usare gli extent specificati da IOleObject::SetExtent o usare il rettangolo di delimitazione specificato nel parametro lprcBounds .

Per gli oggetti più recenti che supportano tecniche di disegno ottimizzate e per gli oggetti senza finestra, questo metodo deve essere usato come segue:

I nuovi aspetti di disegno sono supportati in dwAspect come definito in DVASPECT2.
Il parametro pvAspect può essere usato per passare informazioni aggiuntive che consentono l'ottimizzazione del disegno tramite la struttura DVASPECTINFO .
È possibile chiamare il metodo IViewObject::D raw per ridisegnare un oggetto attivo senza finestra impostando il parametro lrpcBounds su NULL. In ogni altra situazione, NULL è un valore non valido e deve generare un codice di errore E_INVALIDARG. Un oggetto senza finestra usa il rettangolo passato dal verbo di attivazione o chiama IOleInPlaceObject::SetObjectRects anziché usare questo parametro. Se il contenitore passa un valore non NULL a un oggetto senza finestra, l'oggetto deve eseguire il rendering dell'aspetto richiesto nel contesto del dispositivo e nel rettangolo specificati. Un contenitore può richiedere a un oggetto senza finestra di eseguire il rendering di una seconda visualizzazione non attiva dell'oggetto o di stampare l'oggetto. Per altre informazioni sul disegno di oggetti senza finestra, vedere l'interfaccia IOleInPlaceSiteWindowless .
Per gli oggetti senza finestra, il parametro dwAspect consente solo gli aspetti DVASPECT_CONTENT, DVASPECT_OPAQUE e DVASPECT_TRANSPARENT.
Per un oggetto senza finestra, il parametro hdcDraw deve essere in modalità di mapping MM_TEXT con le coordinate logiche corrispondenti alle coordinate client della finestra contenitore. Per un oggetto senza finestra, il contesto del dispositivo deve trovarsi nello stesso stato di quello normalmente passato da un messaggio WM_PAINT.

Per mantenere la compatibilità con gli oggetti e i contenitori meno recenti che non supportano le ottimizzazioni di disegno, tutti gli oggetti, rettangolari o meno, sono necessari per mantenere un'origine e un extent rettangolare. Ciò consente al contenitore di considerare ancora tutti gli oggetti incorporati come rettangoli e di passarli ai rettangoli di rendering appropriati in Draw.

L'extent di un oggetto dipende dall'aspetto del disegno. Per gli oggetti non rettangolari, l'extent deve essere la dimensione di un rettangolo che copre l'intero aspetto. Per convenzione, l'origine di un oggetto è l'angolo superiore sinistro del rettangolo dell'aspetto DVASPECT_CONTENT. In altre parole, l'origine coincide sempre con l'angolo superiore sinistro del rettangolo gestito dal sito dell'oggetto, anche per un oggetto non rettangolare.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	oleidl.h