Compartir a través de

Documentos activos

  • Artículo

Los documentos activos extienden la tecnología de documento compuesto de OLE. Estas extensiones se proporcionan en forma de interfaces adicionales que administran vistas, de modo que los objetos pueden actuar dentro de contenedores y, aún así, conservar el control sobre sus funciones de visualización e impresión. Este proceso permite mostrar documentos en marcos externos (como Microsoft Office Binder o Microsoft Internet Explorer) y en marcos nativos (como los propios puertos de vista del producto).

En esta sección se describen los requisitos funcionales de los documentos activos. El documento activo posee un conjunto de datos y tiene acceso a un almacenamiento donde se pueden guardar y recuperar los datos. Puede crear y administrar una o varias vistas en sus datos. Además de admitir las interfaces de inserción y activación en contexto habituales de documentos OLE, el documento activo comunica su capacidad de crear vistas mediante IOleDocument. Por medio de esta interfaz, el contenedor puede pedir que se creen (y posiblemente se enumeren) las vistas que puede mostrar el documento activo. Por medio de esta interfaz, el documento activo también puede proporcionar información varia sobre sí mismo, como si admite varias vistas o rectángulos complejos.

A continuación se muestra la interfaz IOleDocument. Tenga en cuenta que la interfaz IEnumOleDocumentViews es un enumerador OLE estándar 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 activo debe tener un proveedor de marcos de vista con esta interfaz. Si el documento no está insertado en un contenedor, el propio servidor de documentos activos debe proporcionar el marco de vista. Pero si el documento activo está insertado en un contenedor de documentos activos, el contenedor proporciona el marco de vista.

Un documento activo puede crear uno o varios tipos de vistas de sus datos (por ejemplo, normal, esquema, diseño de página, etc.). Las vistas actúan como filtros mediante los cuales se pueden ver los datos. Aunque el documento solo tenga un tipo de vista, es posible que siga queriendo admitir varias vistas como medio de admitir la funcionalidad de nueva ventana (por ejemplo, el elemento Nueva ventana del menú Ventana de aplicaciones de Office).

Requisitos de los documentos activos

Un documento activo que se pueda mostrar en un contenedor de documentos activos debe:

  • Usar Archivos compuestos de OLE como mecanismo de almacenamiento mediante la implementación de IPersistStorage.

  • Admitir las características básicas de inserción de documentos OLE, incluida Crear desde archivo. Esto requiere las interfaces IPersistFile, IOleObject e IDataObject.

  • Admitir una o varias vistas capaces de activarse en contexto. Es decir, las vistas deben admitir la interfaz IOleDocumentView, así como las interfaces IOleInPlaceObject e IOleInPlaceActiveObject (mediante las interfaces IOleInPlaceSite e IOleInPlaceFrame del contenedor).

  • Admitir las interfaces de documentos activos estándar IOleDocument, IOleCommandTarget e IPrint.

El conocimiento de cuándo y cómo usar las interfaces del lado contenedor está implícito en estos requisitos.

Requisitos de los objetos de vista

Un documento activo puede crear una o varias vistas de sus datos. Funcionalmente, estas vistas son como puertos en un método determinado para mostrar los datos. Si un documento activo solo admite una vista, el documento activo y esa vista única se pueden implementar mediante una sola clase. IOleDocument::CreateView devuelve el puntero de interfaz del mismo objeto IOleDocumentView.

Para representarse en un contenedor de documentos activos, un componente de vista debe admitir IOleInPlaceObject e IOleInPlaceActiveObject, además 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 vista tiene un sitio de vista asociado que encapsula el marco de vista y el puerto de vista (HWND y un área rectangular de esa ventana). El sitio expone esta funcionalidad por medio de la interfaz estándar IOleInPlaceSite. Tenga en cuenta que es posible tener más de un puerto de vista en un único HWND.

Normalmente, cada tipo de vista tiene una representación impresa diferente. Por lo tanto, las vistas y los sitios de vista correspondientes deben implementar las interfaces de impresión IPrint e IContinueCallback, respectivamente. El marco de vista debe negociar con el proveedor de vistas mediante IPrint cuando comienza la impresión, de modo que los encabezados, los pies de página, los márgenes y los elementos relacionados se impriman correctamente. El proveedor de vistas notifica al marco eventos relacionados con la impresión por medio de IContinueCallback. Para obtener más información sobre el uso de estas interfaces, vea Impresión mediante programación.

Tenga en cuenta que si un documento activo solo admite una vista, el documento activo y esa vista única se pueden implementar mediante una sola clase concreta. IOleDocument::CreateView simplemente devuelve el puntero de interfaz del mismo objeto IOleDocumentView. En resumen, no es necesario que haya dos instancias de objeto independientes cuando solo se requiera una vista.

Un objeto de vista también puede ser un destino de comando. Al implementar IOleCommandTarget, una vista puede recibir comandos que se originan en la interfaz de usuario del contenedor (por ejemplo, Nuevo, Abrir, Guardar como, Imprimir del menú Archivo; y Copiar, Pegar, Deshacer del menú Editar). Para obtener más información, vea Control de mensajes y destinos de comando.

Consulte también

Contención de documentos activos