Compartilhar via

Documentos ativos

  • Artigo

Documentos ativos estendem a tecnologia de documento composto do OLE. Essas extensões são fornecidas na forma de interfaces adicionais que gerenciam exibições, para que os objetos possam funcionar dentro de contêineres e ainda manter o controle sobre suas funções de exibição e impressão. Esse processo possibilita exibir documentos em quadros estrangeiros (como o Microsoft Office Binder ou o Microsoft Internet Explorer) e em quadros nativos (como as próprias portas de exibição do produto).

Esta seção descreve os requisitos funcionais para documentos ativos. O documento ativo possui um conjunto de dados e tem acesso ao armazenamento onde os dados podem ser salvos e recuperados. Ele pode criar e gerenciar uma ou mais exibições em seus dados. Além de dar suporte às interfaces de inserção e ativação in-loco usuais de documentos OLE, o documento ativo comunica sua capacidade de criar exibições por meio de IOleDocument. Por meio dessa interface, o contêiner pode pedir para criar (e possivelmente enumerar) as exibições que o documento ativo pode exibir. Por meio dessa interface, o documento ativo também pode fornecer informações diversas sobre si mesmo, como se ele dá suporte a vários modos de exibição ou retângulos complexos.

A seguir está a interface IOleDocument. Observe que a interface IEnumOleDocumentViews é um enumerador OLE padrão para tipos IOleDocumentView*.

interface IOleDocument : IUnknown
    {
    HRESULT CreateView(
        [in] IOleInPlaceSite *pIPSite,
        [in] IStream *pstm,
        [in] DWORD dwReserved,
        [out] IOleDocumentView **ppView);

    HRESULT GetDocMiscStatus([out] DWORD *pdwStatus);

    HRESULT EnumViews(
        [out] IEnumOleDocumentViews **ppEnum,
        [out] IOleDocumentView **ppView);
    }

Cada documento ativo deve ter um provedor de quadros de exibição com essa interface. Se o documento não estiver inserido em um contêiner, o próprio servidor de documentos ativos deverá fornecer o quadro de exibição. No entanto, quando o documento ativo está inserido em um contêiner de documento ativo, o contêiner fornece o quadro de exibição.

Um documento ativo pode criar um ou mais tipos de exibições de seus dados (por exemplo, normal, estrutura de tópicos, layout de página e assim por diante). As exibições agem como filtros pelos quais os dados podem ser vistos. Mesmo que o documento tenha apenas um tipo de exibição, talvez você ainda queira dar suporte a vários modos de exibição como um meio de dar suporte à nova funcionalidade de janela (por exemplo, o item Nova Janela no menu Janela em aplicativos do Office).

Requisitos para documentos ativos

Um documento ativo que pode ser exibido em um contêiner de documento ativo deve:

  • Use os Arquivos Compostos do OLE como seu mecanismo de armazenamento implementando IPersistStorage.

  • Dê suporte aos recursos básicos de inserção de documentos OLE, incluindo Criar do Arquivo. Isso requer as interfaces IPersistFile, IOleObject e IDataObject.

  • Suporte a um ou mais modos de exibição, cada um dos quais é capaz de ativação in-loco. Ou seja, os modos de exibição devem dar suporte à interface IOleDocumentView, bem como às interfaces IOleInPlaceObject e IOleInPlaceActiveObject (usando as interfaces do contêiner IOleInPlaceSite e IOleInPlaceFrame).

  • Suporte às interfaces de documento ativo padrão IOleDocument, IOleCommandTarget e IPrint.

O conhecimento de quando e como usar as interfaces do lado do contêiner está implícito nesses requisitos.

Requisitos para exibir objetos

Um documento ativo pode criar uma ou mais exibições de seus dados. Funcionalmente, essas exibições são como portas em um método específico para exibir os dados. Se um documento ativo oferecer suporte apenas a uma única exibição, o documento ativo e essa exibição única poderão ser implementados usando uma única classe. O IOleDocument::CreateView retorna o mesmo ponteiro da interface IOleDocumentView do objeto.

Para ser representado dentro de um contêiner de documento ativo, um componente de exibição deve dar suporte a IOleInPlaceObject e IOleInPlaceActiveObject além de IOleDocumentView:

interface IOleDocumentView : IUnknown
    {
    HRESULT SetInPlaceSite([in] IOleInPlaceSite *pIPSite);
    HRESULT GetInPlaceSite([out] IOleInPlaceSite **ppIPSite);
    HRESULT GetDocument([out] IUnknown **ppunk);
    [input_sync] HRESULT SetRect([in] LPRECT prcView);
    HRESULT GetRect([in] LPRECT prcView);
    [input_sync] HRESULT SetRectComplex(
        [in] LPRECT prcView,
        [in] LPRECT prcHScroll,
        [in] LPRECT prcVScroll,
        [in] LPRECT prcSizeBox);
    HRESULT Show([in] BOOL fShow);
    HRESULT UIActivate([in] BOOL fUIActivate);
    HRESULT Open(void);
    HRESULT CloseView([in] DWORD dwReserved);
    HRESULT SaveViewState([in] IStream *pstm);
    HRESULT ApplyViewState([in] IStream *pstm);
    HRESULT Clone(
        [in] IOleInPlaceSite *pIPSiteNew,
        [out] IOleDocumentView **ppViewNew);
    }

Cada exibição tem um site de exibição associado, que encapsula o quadro de exibição e a porta de exibição (HWND e uma área retangular nessa janela). O site expõe essa funcionalidade por meio da interface padrão IOleInPlaceSite. Observe que é possível ter mais de uma porta de exibição em um único HWND.

Normalmente, cada tipo de exibição tem uma representação impressa diferente. Portanto, as exibições e os sites de exibição correspondentes devem implementar as interfaces de impressão se IPrint e IContinueCallback, respectivamente. O quadro de exibição deve negociar com o provedor de exibição por meio de IPrint quando a impressão iniciar, para que cabeçalhos, rodapés, margens e elementos relacionados sejam impressos corretamente. O provedor de exibição notifica o quadro de eventos relacionados à impressão por meio de IContinueCallback. Para obter mais informações sobre o uso dessas interfaces, consulte Impressão Programática.

Observe que, se um documento ativo dá suporte apenas a uma única exibição, o documento ativo e essa exibição única poderão ser implementados usando uma única classe concreta. O IOleDocument::CreateView simplesmente retorna o mesmo ponteiro da interface IOleDocumentView do objeto. Em suma, não é necessário que haja duas instâncias de objeto separadas quando apenas uma exibição é necessária.

Um objeto de exibição também pode ser um destino de comando. Ao implementar uma exibição IOleCommandTarget, é possível receber comandos que se originam na interface do usuário do contêiner (como Novo, Abrir, Salvar Como, Imprimir no menu Arquivo; e Copiar, Colar, Desfazer no menu Editar). Para obter mais informações, consulte Tratamento de Mensagens e Destinos de Comando.

Confira também

Contenção de documentos ativos