Criando manipuladores de visualização

  • Artigo

Este tópico discute as interfaces e os métodos específicos necessários para criar um manipulador de visualização.

Um manipulador de visualização deve implementar as seguintes interfaces:

Se o manipulador de visualização der suporte a configurações visuais fornecidas pelo host, como cor da tela de fundo e fonte, ele também deverá implementar a seguinte interface:

Este tópico pressupõe que o manipulador de visualização seja inicializado com um fluxo e esteja registrado para uma extensão de nome de arquivo específica.

IInitializeWithStream::Initialize

Armazene os parâmetros IStream e mode para que você possa ler os dados do item quando estiver pronto para visualizar o item. Não carregue os dados em Inicializar. Carregue os dados em IPreviewHandler::D oPreview pouco antes de renderizar.

Iobjectwithsite

IObjectWithSite::SetSite

Armazene o ponteiro IUnknown para acesso posterior.

Se você tiver atualmente uma referência a um objeto IPreviewHandlerFrame , solte-o. Use o ponteiro IUnknown armazenado para chamar QueryInterface no site para uma nova referência IPreviewHandlerFrame .

Se você tiver atualmente uma tabela aceleradora, destrua-a. Chame IPreviewHandlerFrame::GetWindowContext para obter uma nova tabela de aceleradores. Armazene esta tabela. Observe que ele é usado apenas como uma lista de teclas de acelerador compatíveis com o quadro. Os comandos nas entradas de acelerador são ignorados.

IObjectWithSite::GetSite

Retorne o ponteiro do site, seja o que for.

Iolewindow

IOleWindow::ContextSensitiveHelp

Retornar E_NOTIMPL para esse método.

IOleWindow::GetWindow

Se a janela do manipulador de visualização existir no momento, retorne o HWND dessa janela e S_OK. Se a janela não existir, retorne E_FAIL.

IPreviewHandler

IPreviewHandler::SetWindow

Defina o parâmetro hwnd desse método como o pai do HWND do manipulador de visualização. Esse método pode ser chamado várias vezes. Redimensione sua visualização para que ela seja renderizada somente na área descrita pelo parâmetro prc .

Se o visualizador estiver em processo de renderização, use o método IPreviewHandler::SetWindow para alterar o pai do visualizador. Altere também a área na qual o visualizador está sendo renderizado.

IPreviewHandler::SetRect

Redimensione sua visualização para que ela seja renderizada apenas na área descrita pela prc desse método.

Se o visualizador estiver em processo de renderização, altere a área na qual o visualizador é renderizado.

IPreviewHandler::D oPreview

É aqui que o trabalho real é feito. Como uma visualização é dinâmica, o conteúdo de visualização só deve ser carregado quando necessário. Não carregue conteúdo na inicialização.

Se a janela do manipulador de visualização não existir, crie-a. As janelas do manipulador de visualização devem ser filhos da janela fornecida por IPreviewHandler::SetWindow. Eles devem ser o tamanho fornecido por IPreviewHandler::SetWindow e IPreviewHandler::SetRect (o que foi chamado mais recentemente).

Depois de ter uma janela, carregue os dados do IStream com o qual o manipulador de visualização foi inicializado e renderize esses dados na janela do manipulador de visualização.

IPreviewHandler::SetFocus

Esse método é chamado quando o foco entra no painel de leitura por meio de uma ação de guia. Como ele pode ser inserido como uma guia de avanço ou guia inversa, use o estado atual da chave SHIFT para decidir se a primeira ou última parada de tabulação no painel de leitura deve receber o foco.

IPreviewHandler::QueryFocus

Esse método deve chamar a função GetFocus e retornar o resultado dessa chamada no parâmetro phwnd .

IPreviewHandler::TranslateAccelerator

Esse método é chamado pela bomba de mensagem do processo do manipulador de visualização (seja prevhost.exe ou um servidor local personalizado) em resposta a pressionamentos de teclas do usuário. Os manipuladores de visualização devem lidar com esses pressionamentos de tecla ou encaminhá-los para o host de acordo com o algoritmo detalhado abaixo.

No entanto, como as visualizações são somente leitura, a entrada de teclado deve ser mínima e otimizações como essa não são necessárias em muitos casos.

Se o acelerador de teclado passado para esse método por meio da bomba de mensagem for um acelerador aceito pelo manipulador de visualização, processe-o e retorne S_OK. Se o manipulador não aceitar esse acelerador, a mensagem de acelerador poderá ser enviada de volta até o quadro a ser manipulado.

Há duas opções para encaminhar os aceleradores de teclado de volta para o quadro:

O modelo mais simples é encaminhar todos os pressionamentos de tecla para o host usando IPreviewHandlerFrame::TranslateAccelerator. Isso é feito no exemplo de manipulador de visualização fornecido com o SDK (Software Development Kit) do Windows. Todos os manipuladores de versão prévia de baixa integridade devem usar esse modelo. Se o acelerador não for manipulado pelo manipulador de visualização, chame IPreviewHandlerFrame::TranslateAccelerator e retorne seu resultado.

O outro modelo é usar uma tabela de aceleradores como uma otimização para evitar o envio de muitos pressionamentos de tecla entre os limites do processo:

  1. Quando IObjectWithSite::SetSite for chamado em seu manipulador de visualização, adquira a tabela de acelerador por meio de IPreviewHandlerFrame::GetWindowContext. (Certifique-se de liberar o identificador para a tabela de aceleradores quando o visualizador for destruído.)
  2. Se o acelerador for manipulado pelo manipulador de visualização, manipule-o e retorne S_OK.
  3. Se o acelerador não for manipulado pelo manipulador de visualização, compare a mensagem usando IsAccelerator com a tabela aceleradora adquirida.
  4. Se o acelerador corresponder a uma entrada nessa tabela de aceleradores, chame IPreviewHandlerFrame::TranslateAccelerator e retorne seu resultado.
  5. Se o acelerador não corresponder a nenhuma entrada na tabela de aceleradores, retorne S_FALSE.

IPreviewHandler::Unload

Quando esse método é chamado, interrompa qualquer renderização, libere todos os recursos alocados lendo dados do fluxo e libere o IStream em si.

Depois que esse método for chamado, o manipulador deverá ser reinicializado antes de qualquer tentativa de chamar IPreviewHandler::D oPreview novamente.

IPreviewHandlerVisuals

Esses métodos devem ser implementados ao direcionar o manipulador de visualização para responder aos esquemas de cor e fonte do host. O host consulta o manipulador para IPreviewHandlerVisuals. Se houver suporte, o host fornecerá cor, fonte e cor do texto.

IPreviewHandlerVisuals::SetBackgroundColor

Armazene essa cor e use-a durante a renderização quando quiser fornecer uma cor da tela de fundo. Por exemplo, para preencher a janela quando o manipulador é renderizado em uma área menor que a área fornecida por IPreviewHandler::SetWindow e IPreviewHandler::SetRect. Observe, no entanto, que você não deve desenhar fora da área fornecida por esses métodos.

Se esse método for chamado enquanto a visualização já estiver sendo renderizada, a renderização deverá ser reiniciada usando essa cor de tela de fundo.

IPreviewHandlerVisuals::SetFont

Armazene essas informações de fonte e use-as durante a renderização quando quiser exibir texto consistente com as configurações atuais do Windows Vista.

IPreviewHandlerVisuals::SetTextColor

Armazene essas informações de cor de texto e use-as durante a renderização quando quiser exibir texto consistente com as configurações atuais do Windows Vista.

Visualizar manipuladores e host de visualização do Shell

Como registrar um manipulador de visualização

Diretrizes do manipulador de visualização