Compilazione di gestori di anteprima

  • Articolo

Questo argomento illustra le interfacce e i metodi specifici necessari per creare un gestore di anteprima.

Un gestore di anteprima deve implementare le interfacce seguenti:

Se il gestore dell'anteprima supporta le impostazioni visive fornite dall'host, ad esempio il colore di sfondo e il tipo di carattere, deve implementare anche l'interfaccia seguente:

In questo argomento si presuppone che il gestore di anteprima venga inizializzato con un flusso e sia registrato per un'estensione di file specifica.

IInitializeWithStream::Initialize

Archiviare i parametri IStream e mode in modo da poter leggere i dati dell'elemento quando si è pronti per visualizzare in anteprima l'elemento. Non caricare i dati in Initialize. Caricare i dati in IPreviewHandler::D oPreview subito prima del rendering.

IObjectWithSite

IObjectWithSite::SetSite

Archiviare il puntatore IUnknown per un accesso successivo.

Se attualmente si dispone di un riferimento a un oggetto IPreviewHandlerFrame , rilasciarlo. Usare il puntatore IUnknown archiviato per chiamare QueryInterface nel sito per un nuovo riferimento IPreviewHandlerFrame .

Se è attualmente disponibile una tabella di tasti di scelta rapida, eliminarla. Chiamare IPreviewHandlerFrame::GetWindowContext per ottenere una nuova tabella dell'acceleratore. Archiviare questa tabella. Si noti che viene usato solo come elenco di tasti di scelta rapida supportati dal frame. I comandi nelle voci dell'acceleratore vengono ignorati.

IObjectWithSite::GetSite

Restituisce il puntatore del sito, qualunque cosa sia.

IOleWindow

IOleWindow::ContextSensitiveHelp

Restituisce E_NOTIMPL per questo metodo.

IOleWindow::GetWindow

Se la finestra del gestore di anteprima esiste attualmente, restituire il valore HWND di tale finestra e S_OK. Se la finestra non esiste, restituire E_FAIL.

IPreviewHandler

IPreviewHandler::SetWindow

Impostare il parametro hwnd di questo metodo sull'elemento padre del HWND del gestore di anteprima. Questo metodo può essere chiamato più volte. Ridimensionare l'anteprima in modo che venga eseguito il rendering solo nell'area descritta dal parametro prc .

Se il visualizzatore di anteprima è in fase di rendering, usare il metodo IPreviewHandler::SetWindow per modificare l'elemento padre del visualizzatore di anteprima. Modificare anche l'area in cui viene eseguito il rendering dell'anteprima.

IPreviewHandler::SetRect

Ridimensionare l'anteprima in modo che venga eseguito il rendering solo nell'area descritta dalla prc di questo metodo.

Se il visualizzatore di anteprima è in fase di rendering, modificare l'area in cui viene eseguito il rendering dell'anteprima.

IPreviewHandler::D oPreview

Questo è il luogo in cui viene fatto il vero lavoro. Poiché un'anteprima è dinamica, il contenuto dell'anteprima deve essere caricato solo quando è necessario. Non caricare il contenuto nell'inizializzazione.

Se la finestra del gestore di anteprima non esiste, crearla. Le finestre del gestore di anteprima devono essere figlio della finestra fornita da IPreviewHandler::SetWindow. Devono essere le dimensioni fornite da IPreviewHandler::SetWindow e IPreviewHandler::SetRect (qualsiasi sia stato chiamato più di recente).

Dopo aver creato una finestra, caricare i dati da IStream con cui è stato inizializzato il gestore di anteprima ed eseguire il rendering dei dati nella finestra del gestore di anteprima.

IPreviewHandler::SetFocus

Questo metodo viene chiamato quando lo stato attivo entra nel riquadro di lettura tramite un'azione di tabulazione. Poiché può essere immesso come tabulazione in avanti o inversa, usare lo stato corrente del tasto MAIUSC per decidere se la prima o l'ultima tabulazione nel riquadro di lettura deve ricevere lo stato attivo.

IPreviewHandler::QueryFocus

Questo metodo deve chiamare la funzione GetFocus e restituire il risultato di tale chiamata nel parametro phwnd .

IPreviewHandler::TranslateAccelerator

Questo metodo viene chiamato dal message pump del processo del gestore di anteprima (sia prevhost.exe che da un server locale personalizzato) in risposta alle sequenze di tasti utente. I gestori di anteprima devono gestire queste sequenze di tasti o inoltrarle all'host in base all'algoritmo descritto di seguito.

Tuttavia, poiché le anteprime sono di sola lettura, l'input da tastiera deve essere minimo e le ottimizzazioni come questa non sono necessarie in molti casi.

Se l'acceleratore di tastiera passato a questo metodo tramite message pump è un acceleratore accettato dal gestore di anteprima, elaborarlo e restituire S_OK. Se il gestore non accetta tale acceleratore, il messaggio dell'acceleratore può essere inviato fino al frame da gestire.

Sono disponibili due opzioni per l'inoltro degli acceleratori di tastiera al frame:

Il modello più semplice consiste nell'inoltrare tutte le sequenze di tasti all'host usando IPreviewHandlerFrame::TranslateAccelerator. Questa operazione viene eseguita nell'esempio del gestore di anteprima fornito con Windows Software Development Kit (SDK). Tutti i gestori di anteprima con integrità bassa devono usare questo modello. Se l'acceleratore non viene gestito dal gestore dell'anteprima, chiamare IPreviewHandlerFrame::TranslateAccelerator e restituirne il risultato.

L'altro modello consiste nell'usare una tabella acceleratore come ottimizzazione per evitare l'invio di troppe sequenze di tasti attraverso i limiti del processo:

  1. Quando viene chiamato IObjectWithSite::SetSite nel gestore di anteprima, acquisire la tabella dell'acceleratore tramite IPreviewHandlerFrame::GetWindowContext. Assicurarsi di liberare l'handle per la tabella dell'acceleratore quando il visualizzatore di anteprima viene eliminato definitivamente.
  2. Se l'acceleratore viene gestito dal gestore di anteprima, gestirlo e restituire S_OK.
  3. Se l'acceleratore non viene gestito dal gestore di anteprima, confrontare il messaggio usando IsAccelerator con la tabella dell'acceleratore acquisita.
  4. Se l'acceleratore corrisponde a una voce nella tabella dell'acceleratore, chiamare IPreviewHandlerFrame::TranslateAccelerator e restituirne il risultato.
  5. Se l'acceleratore non corrisponde ad alcuna voce nella tabella dell'acceleratore, restituire S_FALSE.

IPreviewHandler::Unload

Quando questo metodo viene chiamato, arrestare qualsiasi rendering, rilasciare tutte le risorse allocate leggendo i dati dal flusso e rilasciare l'IStream stesso.

Dopo aver chiamato questo metodo, il gestore deve essere reinizializzato prima di qualsiasi tentativo di chiamare nuovamente IPreviewHandler::D oPreview .

IPreviewHandlerVisuals

Questi metodi devono essere implementati quando si indirizza il gestore di anteprima per rispondere alle combinazioni di colori e tipi di carattere dell'host. L'host esegue una query sul gestore per IPreviewHandlerVisuals. Se viene trovato come supportato, l'host lo fornisce con colore, tipo di carattere e colore del testo.

IPreviewHandlerVisuals::SetBackgroundColor

Archiviare questo colore e usarlo durante il rendering quando si desidera fornire un colore di sfondo. Ad esempio, per riempire la finestra quando il gestore esegue il rendering in un'area più piccola rispetto all'area fornita da IPreviewHandler::SetWindow e IPreviewHandler::SetRect. Si noti, tuttavia, che non è consigliabile disegnare all'esterno dell'area fornita da tali metodi.

Se questo metodo viene chiamato durante il rendering dell'anteprima, il rendering deve essere riavviato usando questo colore di sfondo.

IPreviewHandlerVisuals::SetFont

Archiviare queste informazioni sul tipo di carattere e usarle durante il rendering quando si desidera visualizzare testo coerente con le impostazioni correnti di Windows Vista.

IPreviewHandlerVisuals::SetTextColor

Archiviare queste informazioni sul colore del testo e usarle durante il rendering quando si desidera visualizzare testo coerente con le impostazioni correnti di Windows Vista.

Gestori di anteprima e host di anteprima della shell

Come registrare un gestore di anteprima

Linee guida per i gestori di anteprima