Erstellen von Vorschauhandlern

  • Artikel

In diesem Thema werden die spezifischen Schnittstellen und Methoden erläutert, die zum Erstellen eines Vorschauhandlers erforderlich sind.

Ein Vorschauhandler muss die folgenden Schnittstellen implementieren:

Wenn Ihr Vorschauhandler vom Host bereitgestellte visuelle Einstellungen wie Hintergrundfarbe und Schriftart unterstützt, muss er auch die folgende Schnittstelle implementieren:

In diesem Thema wird davon ausgegangen, dass der Vorschauhandler mit einem Stream initialisiert und für eine bestimmte Dateinamenerweiterung registriert ist.

IInitializeWithStream::Initialize

Speichern Sie die Parameter IStream und mode, damit Sie die Daten des Elements lesen können, wenn Sie bereit sind, eine Vorschau des Elements anzuzeigen. Laden Sie die Daten nicht in Initialize. Laden Sie die Daten direkt vor dem Rendern in IPreviewHandler::D oPreview .

Iobjectwithsite

IObjectWithSite::SetSite

Speichern Sie den IUnknown-Zeiger für den späteren Zugriff.

Wenn Sie derzeit über einen Verweis auf ein IPreviewHandlerFrame-Objekt verfügen, geben Sie es frei. Verwenden Sie den gespeicherten IUnknown-Zeiger , um QueryInterface auf der Website für eine neue IPreviewHandlerFrame-Referenz aufzurufen.

Wenn Sie derzeit über eine Acceleratortabelle verfügen, zerstören Sie sie. Rufen Sie IPreviewHandlerFrame::GetWindowContext auf, um eine neue Acceleratortabelle zu erhalten. Speichern Sie diese Tabelle. Beachten Sie, dass es nur als Liste von Beschleunigungsschlüsseln verwendet wird, die vom Frame unterstützt werden. Befehle in den Beschleunigereinträgen werden ignoriert.

IObjectWithSite::GetSite

Gibt den Standortzeiger zurück, unabhängig davon, was er ist.

IOleWindow

IOleWindow::ContextSensitiveHelp

Gibt E_NOTIMPL für diese Methode zurück.

IOleWindow::GetWindow

Wenn das Fenster des Vorschauhandlers derzeit vorhanden ist, geben Sie die HWND dieses Fensters zurück, und S_OK. Wenn das Fenster nicht vorhanden ist, geben Sie E_FAIL zurück.

IPreviewHandler

IPreviewHandler::SetWindow

Legen Sie den hwnd-Parameter dieser Methode auf das übergeordnete Element des HWND Ihres Vorschauhandlers fest. Diese Methode kann mehrmals aufgerufen werden. Ändern Sie die Größe Der Vorschau, sodass sie nur in dem bereich gerendert wird, der durch den prc-Parameter beschrieben wird.

Wenn der Vorschauer gerade gerendert wird, verwenden Sie die IPreviewHandler::SetWindow-Methode , um das übergeordnete Element des Vorschauers zu ändern. Ändern Sie auch den Bereich, in dem die Vorschau gerendert wird.

IPreviewHandler::SetRect

Ändern Sie die Größe Der Vorschau, sodass sie nur in dem bereich gerendert wird, der durch den Prc dieser Methode beschrieben wird.

Wenn die Vorschauversion gerade gerendert wird, ändern Sie den Bereich, in dem ihr Vorschauprogramm gerendert wird.

IPreviewHandler::D oPreview

Hier wird die eigentliche Arbeit erledigt. Da eine Vorschau dynamisch ist, sollte der Vorschauinhalt nur geladen werden, wenn er benötigt wird. Laden Sie keine Inhalte in der Initialisierung.

Wenn das Vorschauhandlerfenster nicht vorhanden ist, erstellen Sie es. Die Fenster Ihres Vorschauhandlers sollten untergeordnete Elemente des von IPreviewHandler::SetWindow bereitgestellten Fensters sein. Sie sollten die von IPreviewHandler::SetWindow und IPreviewHandler::SetRect bereitgestellte Größe aufweisen (je nachdem, welche Zuletzt aufgerufen wurde).

Sobald Sie über ein Fenster verfügen, laden Sie die Daten aus dem IStream , mit dem der Vorschauhandler initialisiert wurde, und rendern Sie diese Daten in das Fenster Ihres Vorschauhandlers.

IPreviewHandler::SetFocus

Diese Methode wird aufgerufen, wenn der Fokus über eine Registerkartenaktion in den Lesebereich gelangt. Da sie als Vorwärtsregisterkarte oder umgekehrte Registerkarte eingegeben werden kann, entscheiden Sie mithilfe des aktuellen Zustands der UMSCHALTTASTE, ob der erste oder letzte Tabstopp im Lesebereich den Fokus erhalten soll.

IPreviewHandler::QueryFocus

Diese Methode sollte die GetFocus-Funktion aufrufen und das Ergebnis dieses Aufrufs im phwnd-Parameter zurückgeben.

IPreviewHandler::TranslateAccelerator

Diese Methode wird von der Nachrichtenpumpe des Prozesses des Vorschauhandlers (unabhängig davon, ob prevhost.exe oder ein benutzerdefinierter lokaler Server) als Reaktion auf Benutzertastenanschläge aufgerufen. Vorschauhandler sollten diese Tastenanschläge behandeln oder gemäß dem unten beschriebenen Algorithmus an ihren Host weiterleiten.

Da Vorschauversionen jedoch schreibgeschützt sind, sollte die Tastatureingabe minimal sein, und solche Optimierungen sind in vielen Fällen nicht erforderlich.

Wenn die Tastaturbeschleunigung, die über die Nachrichtenpumpe an diese Methode übergeben wird, ein Accelerator ist, den Ihr Vorschauhandler akzeptiert, verarbeiten Sie sie, und geben Sie S_OK zurück. Wenn Ihr Handler diesen Accelerator nicht akzeptiert, kann die Beschleunigungsmeldung bis zum zu behandelnden Frame zurückgesendet werden.

Es gibt zwei Optionen zum Weiterleiten von Tastaturbeschleunigungen zurück an den Frame:

Das einfachste Modell besteht darin, alle Tastenanschläge mithilfe von IPreviewHandlerFrame::TranslateAccelerator an den Host weiterzuleiten. Dies geschieht im Vorschauhandlerbeispiel, das mit dem Windows Software Development Kit (SDK) bereitgestellt wird. Alle Vorschauhandler mit niedriger Integrität müssen dieses Modell verwenden. Wenn der Accelerator nicht von Ihrem Vorschauhandler verarbeitet wird, rufen Sie IPreviewHandlerFrame::TranslateAccelerator auf, und geben Sie das Ergebnis zurück.

Das andere Modell besteht darin, eine Acceleratortabelle als Optimierung zu verwenden, um zu viele Tastenanschläge über Prozessgrenzen hinweg zu vermeiden:

  1. Wenn IObjectWithSite::SetSite in Ihrem Vorschauhandler aufgerufen wird, rufen Sie die Acceleratortabelle über IPreviewHandlerFrame::GetWindowContext ab. (Stellen Sie sicher, dass Sie das Handle für die Acceleratortabelle freigeben, wenn Ihr Vorschauprogramm zerstört wird.)
  2. Wenn der Accelerator von Ihrem Vorschauhandler verarbeitet wird, behandeln Sie sie, und geben Sie S_OK zurück.
  3. Wenn der Accelerator nicht von Ihrem Vorschauhandler verarbeitet wird, vergleichen Sie die Nachricht mithilfe von IsAccelerator mit der abgerufenen Acceleratortabelle.
  4. Wenn der Accelerator mit einem Eintrag in dieser Acceleratortabelle übereinstimmt, rufen Sie IPreviewHandlerFrame::TranslateAccelerator auf, und geben Sie das Ergebnis zurück.
  5. Wenn der Accelerator mit keinem Eintrag in der Acceleratortabelle übereinstimmt, geben Sie S_FALSE zurück.

IPreviewHandler::Unload

Wenn diese Methode aufgerufen wird, beenden Sie das Rendering, geben Sie alle Ressourcen frei, die durch Lesen von Daten aus dem Stream zugewiesen wurden, und lassen Sie den IStream selbst los.

Sobald diese Methode aufgerufen wurde, muss der Handler erneut initialisiert werden, bevor versucht wird , IPreviewHandler::D oPreview erneut aufzurufen.

IPreviewHandlerVisuals

Diese Methoden sollten implementiert werden, wenn sie den Vorschauhandler anweisen, auf die Farb- und Schriftartschemas des Hosts zu reagieren. Der Host fragt den Handler für IPreviewHandlerVisuals ab. Wenn dies als unterstützt erkannt wird, stellt der Host ihn mit Farbe, Schriftart und Textfarbe bereit.

IPreviewHandlerVisuals::SetBackgroundColor

Speichern Sie diese Farbe, und verwenden Sie sie beim Rendern, wenn Sie eine Hintergrundfarbe angeben möchten. Zum instance, um das Fenster zu füllen, wenn der Handler in einen Bereich gerendert wird, der kleiner ist als der von IPreviewHandler::SetWindow und IPreviewHandler::SetRect bereitgestellte Bereich. Beachten Sie jedoch, dass Sie nicht außerhalb des von diesen Methoden bereitgestellten Bereichs zeichnen sollten.

Wenn diese Methode aufgerufen wird, während die Vorschau bereits gerendert wird, sollte das Rendering mit dieser Hintergrundfarbe neu gestartet werden.

IPreviewHandlerVisuals::SetFont

Speichern Sie diese Schriftartinformationen, und verwenden Sie sie beim Rendern, wenn Sie Text anzeigen möchten, der mit den aktuellen Windows Vista-Einstellungen konsistent ist.

IPreviewHandlerVisuals::SetTextColor

Speichern Sie diese Textfarbeinformationen, und verwenden Sie sie beim Rendern, wenn Sie Text anzeigen möchten, der mit den aktuellen Windows Vista-Einstellungen konsistent ist.

Vorschauhandler und Shellvorschauhost

Registrieren eines Vorschauhandlers

Richtlinien für Vorschauhandler