Impressão programática

O OLE forneceu os meios para identificar exclusivamente documentos persistentes (GetClassFile) e carregá-los em seu código associado (CoCreateInstance, , QueryInterface(IID_IPersistFile), QueryInterface(IID_IPersistStorage)e IPersistFile::LoadIPersistStorage::Load). Para aprimorar ainda mais a capacidade de imprimir documentos, a contenção ativa de documentos (usando um design OLE existente que não foi incluído originalmente no OLE 2.0) introduz uma interface padrão básica para impressão, IPrint geralmente acessível por meio de qualquer objeto que possa carregar o estado persistente do tipo de documento. Cada exibição de um documento ativo pode, opcionalmente, dar suporte à IPrint interface para fornecer esses recursos.

A IPrint interface é definida da seguinte maneira:

interface IPrint : IUnknown
    {
    HRESULT SetInitialPageNum([in] LONG nFirstPage);
    HRESULT GetPageInfo(
        [out] LONG *pnFirstPage,
        [out] LONG *pcPages);
    HRESULT Print(
        [in] DWORD grfFlags,
        [in,out] DVTARGETDEVICE **pptd,
        [in,out] PAGESET ** ppPageSet,
        [in,out] STGMEDIUM **ppstgmOptions,
        [in] IContinueCallback* pCallback,
        [in] LONG nFirstPage,
        [out] LONG *pcPagesPrinted,
        [out] LONG *pnPageLast);
    };

Clientes e contêineres simplesmente usam IPrint::Print para instruir o documento a se imprimir depois que esse documento for carregado, especificando sinalizadores de controle de impressão, o dispositivo de destino, as páginas a serem impressas e opções adicionais. O cliente também pode controlar a continuação da impressão por meio da interface IContinueCallback (veja abaixo).

Além disso, IPrint::SetInitialPageNum dá suporte à impressão de uma série de documentos como um único, numerando as páginas de forma contínua, obviamente um benefício para contêineres de documentos ativos, como o Office Binder. IPrint::GetPageInfo simplifica a exibição de informações de paginação ao permitir que o chamador recupere o número de página inicial anteriormente passado para SetInitialPageNum (ou o número de página inicial padrão interno do documento) e o número de páginas no documento.

Os objetos que dão suporte IPrint são marcados no registro com a chave "Imprimível" armazenada sob o CLSID do objeto:

HKEY_CLASSES_ROOT\CLSID\{...}\Printable

IPrint geralmente é implementado no mesmo objeto que dá suporte a um IPersistFile ou IPersistStorage. Os chamadores observam a capacidade de imprimir programaticamente o estado persistente de alguma classe procurando no registro a chave "Imprimível". Atualmente, "Imprimível" indica suporte de pelo menos IPrint; outras interfaces podem ser definidas no futuro, que estariam disponíveis por meio de QueryInterface, onde IPrint simplesmente representa o nível base de suporte.

Durante um procedimento de impressão, talvez você queira que o cliente ou contêiner que iniciou a impressão controle se a impressão deve ou não continuar. Por exemplo, o contêiner pode dar suporte a um comando "Parar Impressão" que deve encerrar o trabalho de impressão assim que possível. Para dar suporte a essa funcionalidade, o cliente de um objeto imprimível pode implementar um pequeno objeto de coletor de notificação com a interface IContinueCallback:

interface IContinueCallback : IUnknown
    {
    HRESULT FContinue(void);
    HRESULT FContinuePrinting(
        [in] LONG cPagesPrinted,
        [in] LONG nCurrentPage,
        [in] LPOLESTR pszPrintStatus);
    };

Essa interface foi projetada para ser útil como uma função de retorno de chamada de continuação genérica que assume o lugar dos vários procedimentos de continuação na API Win32 (como AbortProc para impressão e EnumMetafileProc para enumeração de meta-arquivo). Portanto, esse design de interface é útil em uma ampla variedade de processos demorados.

Nos casos mais genéricos, a função IContinueCallback::FContinue é chamada periodicamente por qualquer processo demorado. O objeto coletor retorna S_OK para continuar a operação e S_FALSE para interromper o procedimento o mais rápido possível.

FContinue, no entanto, não é usado no contexto de IPrint::Print; em vez disso, a impressão usa IContinueCallback::FContinuePrint. Qualquer objeto de impressão deve chamar FContinuePrinting periodicamente passando o número de páginas que foram impressas, o número da página que está sendo impressa e uma cadeia de caracteres adicional descrevendo o status de impressão que o cliente pode optar por exibir para o usuário (como "Página 5 de 19").

Consulte também

Contêineres de documentos ativos