Expandir a Exportação de PDF do Office

Resumo: Crie um suplemento COM para o Office 2024, Office LTSC 2024 e o Microsoft 365 Versão 2408 e aplicações posteriores com a sua própria lógica para exportar para o formato PDF. A técnica descrita requer conhecimentos de C++ e COM.

Aplica-se a: Excel, OneNote, PowerPoint, Publisher, Visio e Word no Office 2024, Office LTSC 2024, Microsoft 365 Versão 2408 e posterior.

Introdução à Funcionalidade de Exportação de Fixed-Format do Office (2024)

Este artigo explica como os programadores de software de terceiros podem ligar-se à funcionalidade de exportação de formato fixo disponível no Office 2024, Office LTSC 2024, Microsoft 365 Versão 2408 e aplicações posteriores para que possam adicionar o seu próprio exportador.

As aplicações incluem exportadores incorporados para o Microsoft XML Paper Specification (XPS) e Portable Document Format (PDF). Os formatos de ficheiro fixo expõem o conteúdo de um documento num formulário paginado independente da aplicação e independente da plataforma.

Os programadores de software podem adicionar o seu próprio exportador ao escrever um suplemento do Office que implementa a interface IMsoDocExporter COM. Este artigo descreve o IMsoDocExporter e a interação com uma aplicação do Microsoft 365 de alojamento, como Word.

A exportação de formato fixo está disponível desde a versão do Office 2007 e este artigo inclui informações sobre as funcionalidades novas nas versões do Office 2024, Office LTSC 2024, Microsoft 365 Versão 2408.

A inicializar Add-Ins

Para o utilizador aceder à funcionalidade do suplemento, o suplemento deve adicionar um novo item de menu ou um novo botão da barra de ferramentas à aplicação. Quando o utilizador seleciona este item de menu ou botão, o suplemento deve utilizar o Modelo de Objetos do Microsoft Office para obter um ponteiro para o documento ativo. Em seguida, deve chamar o método ExportAsFixedFormat do documento ativo com um ponteiro de interface IUnknown que suporta a interface IMsoDocExporter através de uma chamada para o método QueryInterface . O parâmetro do modelo de objeto para o ponteiro da interface é uma VARIANTE com VT_UNKNOWN tipo.

Depois de o Publisher ter um ponteiro para a interface IMsoDocExporter , chama de volta o suplemento através dos métodos expostos por IMsoDocExporter. Através destas chamadas de retorno, Word fornece o suplemento com conteúdo do documento e outras informações sobre o documento.

Uma excelente fonte de informação sobre a criação de suplementos COM para aplicações do Microsoft Office é o artigo codeproject.com Building an Office2K COM Add-in with VC++/ATL (Criar um Suplemento COM do Office2K com VC++/ATL).

IMsoDocExporter

A interface IMsoDocExporter expõe os seguintes métodos.

Tabela 1. Métodos expostos pela interface IMsoDocExporter

Além disso, iMsoDocExporter também expõe os seguintes métodos que são herdados da interface IUnknown .

Tabela 2. Métodos herdados da interface IUnknown

Para obter informações sobre como implementar os métodos de interface IUnknown , veja IUnknown (COM).

Fluxo de Chamada

O diagrama seguinte mostra a sequência na qual o Publisher chama os métodos expostos em IMsoDocExporter. Nem todos os métodos são utilizados por cada aplicação do Microsoft Office e nem todos os métodos são utilizados para cada documento exportado.

Figura 1. Chamar métodos da interface IMsoDocExporter

As secções seguintes descrevem ainda os métodos expostos pela interface IMsoDocExporter . Os métodos são descritos aproximadamente pela ordem pela qual seriam chamados pelo Publisher.

GetOutputOption e SetOutputOption

O Publisher chama os métodos GetOutputOption e SetOutputOption para obter e definir opções de saída para o processo de exportação de formato fixo.

void GetOutputOption(
    MSODOCEXOPTION docexoption, 
    DWORD* pdwVal 
);
void SetOutputOption(
    MSODOCEXOPTION docexoption, 
    DWORD dwVal 
);

O parâmetro docexoption especifica a opção de saída e o parâmetro (p)dwVal especifica o valor da opção.

Embora o exportador incorporado no Office utilize GetOutputOption e SetOutputOption, um suplemento pode implementar o seu próprio método de obter e definir opções e a sua própria experiência de utilizador para as opções.

O Microsoft Office Chama GetOutputOption Apenas com msodocexOptionTargetDPIColor para Fixed-Format Add-Ins

Para a implementação da exportação de formato fixo no Office, o Publisher chama o método GetOutputOption para obter opções de saída para apresentar ao utilizador na caixa de diálogo Publicar como PDF ou XPS . Para suplementos desenvolvidos por programadores de software de terceiros, o Publisher chama GetOutputOption apenas com o valor msodocexOptionTargetDPIColor. Este é o único valor que um suplemento precisa de suportar. Se a implementação do suplemento getOutputOption for chamada com este valor, deverá devolver os pontos de destino por polegada (DPI) para rasterização de efeito 3D.

Microsoft Office Calls SetOutputOption for Fixed-Format Add-Ins

Para a implementação da exportação de formato fixo no Office e para implementações de suplementos, o Publisher chama SetOutputOption no início do processo de exportação de formato fixo. Na implementação no Office, os valores dos parâmetros transmitidos no especificam opções de saída de formato fixo. No entanto, se o suplemento implementar o seu próprio conjunto de opções, o suplemento pode ignorar as opções que lhe foram transmitidas pelo Publisher.

EnableCancel

O Publisher chama o método EnableCancel para transmitir o suplemento a um ponteiro para uma interface IMsoDocExCancel . O suplemento pode utilizar esta interface para consultar se um utilizador opta por cancelar uma operação de exportação de documentos longa.

void EnableCancel(
    IMsoDocExCancel* pdec
);

HrBeginStructNode

O Publisher chama o método HrBeginStructNode para especificar o início de um nó de estrutura de documentos para conteúdo que engloba múltiplas páginas completas no documento. Os nós de estrutura de documentos para elementos do documento que residem inteiramente numa página (por exemplo, parágrafos) são incorporados pelo Publisher no próprio metaficheiro avançado (EMF) através das estruturas de DocExComment_BeginStructNode e DocExComment_EndStructNode . Para obter mais informações sobre nós de estrutura de documentos, consulte as secções HrAddPageFromEmf e DocExComment_BeginStructNode neste artigo.

HRESULT HrBeginStructNode(
    int idNodeParent, 
    int iSortOrder, 
    const MSODOCEXSTRUCTNODE* pnode, 
    BOOL fNoEndNode
);

O parâmetro idNodeParent especifica o ID do nó que é o principal do nó que está a ser transmitido para o suplemento. Se este parâmetro for 0, o nó está localizado na raiz da árvore da estrutura do documento. Vários nós de irmãos podem estar localizados na raiz. Se este parâmetro for -1, o nó está localizado no nó atualmente aberto, ou seja, no último nó especificado por HrBeginStructNode que não foi fechado por uma chamada para HrEndStructNode.

O parâmetro iSortOrder especifica a sequência de ordenação do nó de estrutura entre os respetivos irmãos. Não é possível ter dois nós com a mesma sequência de ordenação. No entanto, o conjunto de números inteiros que constituem a sequência de ordenação não tem de ser contíguo. Um valor de -1 indica que a sequência de ordenação entre irmãos é a mesma ordem pela qual os nós aparecem nos comentários do EMF.

O parâmetro pnode aponta para uma estrutura MSODOCEXSTRUCTNODE , que tem a seguinte declaração:

typedef struct _MsoDocexStructNode
{
    int idNode;
    MSODOCEXSTRUCTTYPE nodetype;
    WCHAR* pwchAltText;
    union
    {
        int iHeadingLevel;
        ULONG idPara;
        ULONG idDropCap;
        int iPage;
        WCHAR* pwchActualText;
        MSODOCEXLINEBREAKTYPE bt;
        int iListLevel;
        MSODOCEXLISTTYPE listType;
        ULONG idAtn;
        long cpLim;
        int shapeProperty;
        MsoDocexTableAttr tableAttr;
        long cpNoteRef;
        WCHAR* idTableHeader;
        long cpXchAtnMainDod;
        int iTargetParentId;
        WCHAR* wzMathMlText;
        MsoDocexListAttr* pListAttr;
    };
} MSODOCEXSTRUCTNODE;

O membro do idNode especifica o ID do nó que está a ser transmitido na chamada para HrBeginStructNode. Este membro pode não ter um valor de 0. Um valor de -1 indica que os nós subordinados não utilizam o parâmetro idNodeParent para especificar este nó como principal. Em vez disso, este nó só pode ser um elemento principal ao incluir nós subordinados no EMF. Vários nós podem ter um ID de -1. Se o ID não for -1, o valor é exclusivo em todo o documento.

A união incorporada no final do MSODOCEXSTRUCTNODE é interpretada de forma diferente consoante o tipo de nó:

• iHeadingLevel é o nível de cabeçalho de um msodocexStructTypeHeading.
• idPara é o ID de parágrafo de um P, TOCI ou ListBody.
• idDropCap é o id de um msodocexStructTypeDropCap.
• iPage é o número de página de um msodocexStructTypePage.
• bt é o tipo de quebra de linha para um msodocexStructTypeTextLine.
• iListLevel é o nível de lista de um msodocexStructTypeList ou msodocexStructTypeListItem.
• listType é o tipo de lista de um msodocexStructTypeListItem.
• idAtn é o id de um msodocexStructTypeAnnotationBegin ou msodocexStructTypeAnnotationEnd.
• cpLim é utilizado para determinar a ordem de aninhamento de tabelas nas tabelas para um msodocexStructTypeTable, msodocexStructTypeTOC ou msodocexStructTypeListBody.
• shapeProperty destina-se a um msodocexStructTypeFigure onde o conteúdo é uma forma, caixa de texto ou célula de tabela e contém campos de bits da enumeração MSODOCEXSHAPEPROPERTY.
• tableAttr é os atributos de célula da tabela para um msodocexStructTypeTH ou msodocexStructTypeTD.
• cpNoteRef é utilizado para ligar msodocexStructTypeIntLinkNoteRef a msodocexStructTypeFootnote/msodocexStructTypeEndnote. Isto é explicado mais detalhadamente mais adiante nesta secção.
• idTableHeader é o ID exclusivo de um msodocexStructTypeTH ou msodocexStructTypeTD.
• cpXchAtnMainDod é utilizado para ligar msodocexStructTypeCommentAnchor com msodocexStructTypeAnnot. Isto é explicado mais detalhadamente mais adiante nesta secção.
• iTargetParentId é o ID do nó para onde reparente um msodocexStructTypeDiagram.
• wzMathMlText é cadeia MathML para msodocexStructTypeEquation.
• pListAttr é atributos de lista para msodocexStructTypeList.

Nota: cpNoteRef, cpXchAtnMainDod, wzMathMlText e pListAttr estão disponíveis quando Word. Document.ExportAsFixedFormat3 é chamado com ImproveExportTagging = true. A versão mínima necessária é o Canal Beta do Microsoft 365 16.0.18720.20000.

Tabela 3. Enumerated values of MSODOCEXLINEBREAKTYPE

Tabela 4. Valores enumerados de MSODOCEXLISTTYPE

Tabela 5. Valores enumerados dos campos de bits MSODOCEXSHAPEPROPERTY

MsoDocexTableAttr

A estrutura MsoDocexTableAttr enquadra-se em 32 bits e inclui as informações de âmbito de linhas e colunas e de cabeçalho de uma célula de tabela.

struct MsoDocexTableAttr
{
    static constexpr unsigned int MaxSpanBits = sizeof(unsigned int) * 8 / 2 - 1;
    static constexpr unsigned int MaxSpanValue = (1u << MaxSpanBits) - 1;

    unsigned int rowSpan : MaxSpanBits;
    unsigned int fRowScope : 1;
    unsigned int colSpan : MaxSpanBits;
    unsigned int fColScope : 1;
};

Os membros da estrutura MsoDocexTableAttr são os seguintes:

• MaxSpanBits Especifica o número de bits disponíveis para os valores rowSpan e colSpan, que é 15.

• MaxSpanValue Especifica o valor máximo que pode ser especificado para rowSpan e colSpan.

• rowSpan Especifica o número de linhas que uma célula de tabela abrange.

• fRowScope Especifica se o cabeçalho é Linha/Ambas ou Coluna.

• colSpan Especifica o número de colunas que uma célula de tabela abrange.

• fColScope Especifica se o cabeçalho é Coluna/Ambas ou Linha.

MsoDocexListAttr

A estrutura MsoDocexListAttr inclui informações para uma lista.

struct MsoDocexListAttr
{
    int iListLevel;
    long cpLim;
};

Os membros da estrutura MsoDocexListAttr são os seguintes:

• iListLevel Especifica a ordem de aninhamento da lista.

• cpLim Especifica a posição no documento onde a lista termina.

Sugestões de pós-processamento

Em alguns casos, os nós têm de ser pós-processados para alcançar os resultados pretendidos.

Pós-processamento de notas de rodapé/notas de fim

Durante a exportação, as ligações de nota de rodapé/nota de fim serão etiquetadas como msodocexStructTypeIntLinkNoteRef. Os corpos de nota de rodapé/nota de fim serão marcados como msodocexStructTypeFootnote e msodocexStructTypeEndnote, respetivamente, e serão sempre nós de nível superior no nó msodocexStructTypeDocument. o nó msodocexStructTypeIntLinkNoteRef e o nó msodocexStructTypeFootnote/msodocexStructTypeEndnote correspondente terão o mesmo valor cpNoteRef. Isto pode ser utilizado para mover nós de nota de rodapé/nota de fim nos nós de ligação correspondentes para manter um sentido de leitura lógico.

Pós-processamento de comentários

Durante a exportação, cada âncora de comentário será etiquetada como msodocexStructTypeCommentAnchor. Os corpos de comentários serão marcados como msodocexStructTypeAnnot e serão sempre nós de nível superior no nó msodocexStructTypeDocument. msodocexStructTypeCommentAnchor node e o nó msodocexStructTypeAnnot correspondente terão o mesmo valor cpXchAtnMainDod. Isto pode ser utilizado para mover nós de anotação nos nós de âncora de comentário correspondentes para manter um sentido de leitura lógico.

Pós-processamento de tabelas de esquema

Durante a exportação, se detetarmos que uma tabela é uma tabela de esquema, vamos marcá-la como msodocexStructTypeTable, mas definiremos a cpLim do nó como -2 (o nosso valor constante para indicar que se trata de uma tabela de esquema). Em seguida, este valor pode ser utilizado para determinar se os nós de tabela devem ser etiquetados novamente como nós de parágrafo.

Nós que abrangem páginas pós-processamento (parágrafos, listas, tabelas)

Para parágrafos, os valores idPara de dois nós para podem ser verificados para determinar se representam o mesmo parágrafo nas páginas. Para tabelas, os valores cpLim podem ser verificados para ver se são iguais.

Para listas, adicionámos uma nova classe a MsoDocexStructNode, MsoDocexListAttr, que contém o cpLim de uma lista. Isto pode ser utilizado para marcar se dois nós de lista tiverem o mesmo cpLim, o que significa que ambos representam a mesma lista no documento.

Para os nós de estrutura da tabela, a união é interpretada como uma ordenação das extremidades da tabela relativamente a outras tabelas através da cpLim, que pode ser utilizada para determinar a ordem de aninhamento das tabelas dentro das tabelas.

No contexto da DocExComment_BeginStructNode, o suplemento pode ignorar o membro pwchActualText desta união.

O membro pwchAltText especifica texto alternativo para o nó de estrutura.

O parâmetro fNoEndNode para HrBeginStructNode especifica se o Publisher chama o método HrEndStructNode para marcar o fim do nó da estrutura. Se fNoEndNode for falso, o Publisher chama HrEndStructNode para fechar o conteúdo vinculado pelo nó. Se este parâmetro tiver um valor verdadeiro , o nó não vincula qualquer conteúdo.

O parâmetro fNoEndNode afeta a interpretação do valor do ID principal dos nós subsequentes. Se fNoEndNode for falso, os nós inseridos entre esta chamada para HrBeginStructNode e a chamada subsequente para HrEndStructNode, e que têm um ID principal de -1, são subordinados deste nó. No entanto, se fNoEndNode for verdadeiro, os nós inseridos após esta chamada para HrBeginStructNode e que têm um ID principal de -1, não são subordinados deste nó, mas são subordinados do nó especificado mais recentemente que tem fNoEndNode igual a falso.

Os nós da estrutura do documento podem ser aninhados a profundidade arbitrária.

Os nós especificados por HrBeginStructNode e os especificados por DocExComment_BeginStructNode partilham o mesmo espaço de ID e existem na mesma árvore da estrutura do documento. HrBeginStructNode e DocExComment_BeginStructNode são duas formas alternativas de adicionar nós a esta árvore. Por exemplo, se o nó aberto mais recentemente tiver sido aberto por HrBeginStructNode e o nó seguinte encontrado for de um DocExComment_BeginStructNode EMFcommentrecord com idNodeParent igual a -1, significa que o nó de HrBeginStructNode é o principal do nó do registo DocExComment_BeginStructNode .

HrEndStructNode

O Publisher chama o método HrEndStructNode para especificar o fim de um nó de estrutura de documentos para conteúdo que engloba múltiplas páginas no documento. O nó de estrutura terminado pelo HrEndStructNode foi iniciado anteriormente por uma chamada para o método HrBeginStructNode . Para obter mais informações, veja HrBeginStructNode neste artigo.

HRESULT HrEndStructNode();

HrCreateDoc

O Publisher chama o método HrCreateDoc para especificar a criação de um novo documento de formato fixo vazio.

HRESULT HrCreateDoc(
    const WCHAR* wzDocExFile
);

O Publisher chama o método HrCreateDoc no início do processo de exportação de formato fixo para especificar a criação de um documento de formato fixo vazio. O parâmetro wzDocExFile especifica um nome para o ficheiro de saída para o qual escrever o documento de formato fixo.

Para uma implementação de suplemento, o Publisher chama HrCreateDoc com o nome de ficheiro que o suplemento forneceu na chamada para o método ExportToFixedFormat no modelo de objetos do Microsoft Office. No entanto, como os suplementos normalmente fornecem IU de configuração para permitir que o utilizador especifique um nome de ficheiro de saída, o suplemento pode ignorar este nome de ficheiro durante o processo de exportação.

Para aplicações do Microsoft Office que requerem o suplemento para paginar o documento, HrCreateDoc é chamado duas vezes, uma no início da sequência de chamadas de paginação e novamente após o suplemento ter paginado o documento. Para obter mais informações, veja as descrições do método HrSetPageHeightForPagination e do método HrGetPageBreaks.

HrSetDefaultLcid

O Publisher chama o método HrSetDefaultLcid para especificar o ID de região predefinido (LCID) para o conteúdo a exportar.

HRESULT HrSetDefaultLcid(
    DWORD lcid
);

Para obter uma lista de LCIDs válidos, veja Lista de Valores de ID de Região (LCID) atribuídos pela Microsoft.

HrAddPageFromEmf

O Publisher chama o método HrAddPageFromEmf para transmitir o suplemento a um EMF dentro da memória que representa o conteúdo no documento a exportar.

HRESULT HrAddPageFromEmf(
    HENHMETAFILE hemf
);

O EMF transmitido pelo Microsoft Office para o suplemento é a principal origem do conteúdo exportado pelo suplemento como um ficheiro de formato fixo. O Microsoft Office chama HrAddPageFromEmf uma vez para cada página de conteúdo no documento de origem da aplicação.

Comentários do EMF Transmitem Informações Semânticas

Um EMF é uma sequência de comandos de desenho (comandos GDI e GDI+) que especificam como compor os elementos visuais do documento. O EMF não contém informações além destes comandos (por exemplo, "desenhar uma imagem aqui" ou "desenhar uma linha ali"). Em particular, o EMF convencional não suporta aspetos semânticos do documento, tais como hiperligações, informações de região e informações de acessibilidade. Para preservar as informações semânticas no documento exportado, o Publisher injeta registos especiais no EMF. Estes registos contêm as informações semânticas.

Os registos que representam as informações semânticas são implementados como comentários em EMF com formatação especial. O formato EMF permite tipos de registo de comentários que são ignorados pelo motor de composição da Interface de Dispositivo Gráfico (GDI), mas que podem conter informações arbitrárias.

Por exemplo, considere um documento que contém texto alternativo. (O texto alternativo é utilizado por leitores de documentos para descrever imagens para utilizadores com deficiências visuais.) O Publisher injeta comentários em EMF antes e depois de compor a imagem e estes comentários em EMF especificam o texto alternativo para a imagem. O suplemento interpreta os comentários e escreve as informações no ficheiro de exportação de formato fixo.

A tabela seguinte mostra os tipos de registos semânticos suportados pela funcionalidade de exportação de formato fixo do Microsoft Office. Estes tipos são enumerados pela enumeração MSODOCEXSTRUCTTYPE . Cada tipo corresponde a um tipo de estrutura que descreve o formato do registo.

Tabela 6. Tipos de registo semânticos suportados pela exportação de formato fixo

DocExComment_ExternalHyperlink(Rctfv)

A estrutura DocExComment_ExternalHyperlink(Rctfv) descreve uma hiperligação que liga a fora do documento, por exemplo, a um Web site na Internet.

struct DocExComment_ExternalHyperlink
{
    DWORD ident {};
    DWORD iComment {};
    union
    {
        RECT  rcdvRegion;
        struct
        {
            float xLeft;
            float yTop;
            float dxWidth;
            float dyHeight;
        } rctfvRegion;
    };
    WCHAR wzLink[MAX_PATH];
};

Os membros da estrutura DocExComment_ExternalHyperlink(Rctfv) são os seguintes:

• ident Especifica o valor constante, msodocexsignature, que identifica este comentário do EMF como contendo informações semânticas.

• iComment Especifica o valor MSODOCEXCOMMENT, msodocexcommentExternalHyperlink ou msodocexcommentExternalHyperlinkRctfv.

• rcdvRegion e rctfvRegion Uma união que especifica a região da página que é a localização de origem da hiperligação. A região pode ser representada como um tipo RECT (rcdvRegion) que utiliza píxeis do dispositivo como unidade de medida ou como uma estrutura que contém coordenadas de vírgula flutuante (rctfvRegion), caso em que a unidade de medida é pontos.

  Se o membro iComment for igual a msodocexcommentExternalHyperlink, o suplemento deverá utilizar rcdvRegion. Neste caso, o suplemento tem de aplicar a matriz de transformação do EMF atual a rcdvRegion para convertê-la no espaço de página.

  Se o membro do iComment for igual a msodocexcommentExternalHyperlinkRctfv, o suplemento deverá utilizar rctfvRegion. Neste caso, rctfvRegion já se encontra no espaço de página, pelo que não é necessária nenhuma transformação.

• wzLink[MAX_PATH] Especifica o URL de destino para esta hiperligação.

DocExComment_InternalHyperlink(Rctfv)

A estrutura DocExComment_InternalHyperlink(Rctfv) descreve uma hiperligação que liga a uma localização no documento. Tenha em atenção que, embora o Publisher transmita um EMF separado para cada página do documento, o destino da hiperligação especificada por DocExComment_InternalHyperlink(Rctfv) pode estar numa página diferente da localização de origem.

struct DocExComment_InternalHyperlink
{
    DWORD ident {};
    DWORD iComment {};
    union
    {
        RECT  rcdvRegion;
        struct
        {
            float xLeft;
            float yTop;
            float dxWidth;
            float dyHeight;
        } rctfvRegion;
    };
    DWORD iTargetPage {};
    float xtfvTarget {};
    float ytfvTarget {};
    float dytfTargetPage {};
};

Os membros da estrutura DocExComment_InternalHyperlink(Rctfv) são os seguintes:

• ident Especifica o valor constante, msodocexsignature, que identifica este comentário do EMF como contendo informações semânticas.

• iComment Especifica o valor MSODOCEXCOMMENT, msodocexcommentInternalHyperlink ou msodocexcommentInternalHyperlinkRctfv.

• rcdvRegion e rctfvRegion Como com a estrutura DocExComment_ExternalHyperlink , este membro é uma união que especifica a região da página que é a localização de origem da hiperligação. A região pode ser representada como um tipo RECT (rcdvRegion) que utiliza píxeis do dispositivo como unidade de medida ou como uma estrutura que contém coordenadas de vírgula flutuante (rctfvRegion), caso em que a unidade de medida é pontos.

  Se o membro iComment for igual a msodocexcommentInternalHyperlink, o suplemento deve utilizar rcdvRegion. Neste caso, o suplemento tem de aplicar a matriz de transformação do EMF atual a rcdvRegion para convertê-la no espaço de página.

  Se o membro do iComment for igual a msodocexcommentInternalHyperlinkRctfv, o suplemento deverá utilizar rctfvRegion. Neste caso, rctfvRegion já se encontra no espaço de página, pelo que não é necessária nenhuma transformação.

• iTargetPage Especifica o número de página da página de destino no documento.

• xtfvTarget Especifica a coordenada x da localização de destino na página de destino. A unidade de medida para este valor são pontos.

• ytfvTarget Especifica a coordenada y da localização de destino na página de destino. A unidade de medida para este valor são pontos.

• dytfTargetPage A altura da página de destino em pontos. O desvio especificado pelo membro ytfvTarget é relativo ao canto superior esquerdo da página. No entanto, alguns tipos de formato fixo utilizam um sistema de coordenadas relativo ao canto inferior esquerdo da página. Para estes tipos de documentos, a altura da página é necessária para converter o desvio.

DocExComment_ColorInfo

A estrutura DocExComment_ColorInfo especifica informações de estado de cor para o EMF. Para obter mais informações sobre esta estrutura, consulte a secção Suporte de Cores Expandidas.

struct DocExComment_ColorInfo
{
    DWORD ident {};
    DWORD iComment {};
    COLORREF clr { 0 };
    BOOL fForeColor {};
};

Os membros da estrutura DocExComment_ColorInfo são os seguintes:

• ident Especifica o valor constante, msodocexsignature, que identifica este comentário do EMF como contendo informações semânticas.

• iComment Especifica o valor MSODOCEXCOMMENT, msodocexcommentColorInfo.

• clr Especifica um ID de cor que representa um estado de cor atual no EMF.

• fForeColor Especifica se o ID de cor no membro clr representa uma cor de primeiro plano ou uma cor de fundo. Se este membro tiver um valor verdadeiro, o ID de cor representa uma cor de primeiro plano. Se este membro tiver um valor falso, o ID de cor representa uma cor de fundo.

DocExComment_ColorEnable

A estrutura DocExComment_ColorEnable especifica se o mapeamento de cores está ativado para conteúdo subsequente no EMF. Para obter mais informações sobre esta estrutura, consulte a secção Suporte de Cores Expandidas.

struct DocExComment_ColorEnable
{
    DWORD ident {};
    DWORD iComment {};
    BOOL fEnable {};
};

Os membros da estrutura DocExComment_ColorEnable são os seguintes:

• ident Especifica o valor constante, msodocexsignature, que identifica este comentário do EMF como contendo informações semânticas.

• iComment Especifica o valor MSODOCEXCOMMENT, msodocexcommentColorMapEnable.

• fEnable Especifica se o mapeamento de cores está ativado para conteúdo subsequente. Um valor verdadeiro indica que o mapeamento de cores está ativado. Um valor falso indica que o mapeamento de cores está desativado.

DocExComment_BeginStructNode

A estrutura DocExComment_BeginStructNode marca o início de um nó de estrutura de documentos. Os nós de estrutura servem uma de duas finalidades possíveis:

• Os nós de estrutura podem identificar o tipo de conteúdo que contêm e especificar a relação hierárquica entre esse conteúdo e outros conteúdos no documento.

• Os nós de estrutura podem especificar texto alternativo para elementos no documento.

Se o membro do fContentNode tiver um valor verdadeiro , o DocExComment_BeginStructNode é seguido posteriormente no documento por um DocExComment_EndStructNode. O DocExComment_EndStructNode marca o fim do conteúdo moldado pelas informações no DocExComment_BeginStructNode.

A coleção de nós estruturais no documento forma uma árvore; cada nó tem um nó principal e também pode ter nós de irmãos. Os membros idNodeParent e iSortOrder descrevem a estrutura desta árvore. Tenha em atenção que um nó subordinado pode ou não aparecer entre as estruturas DocExComment_BeginStructNode e DocExComment_EndStructNode do nó principal no EMF.

struct DocExComment_BeginStructNode
{
    DWORD ident {};
    DWORD iComment {};
    int idNodeParent {};
    int iSortOrder {};
    MSODOCEXSTRUCTNODE desn;
    BOOL fContentNode {};
    int cwchAltText {};
};

Os membros da estrutura DocExComment_BeginStructNode são os seguintes:

• ident Especifica o valor constante, msodocexsignature, que identifica este comentário do EMF como contendo informações semânticas.

• iComment Especifica o valor MSODOCEXCOMMENT, msodocexcommentBeginStructNode.

• idNodeParent Especifica o ID do nó principal. Um valor de 0 especifica o nó raiz. Um valor de -1 especifica o nó de estrutura atualmente aberto, ou seja, o nó de estrutura de colocação .

• iSortOrder Especifica a sequência de ordenação do nó de estrutura entre os respetivos nós irmãos. A sequência de ordenação permite que o suplemento ordene corretamente o conteúdo no documento exportado.

  Não é possível ter dois nós com a mesma sequência de ordenação. No entanto, o conjunto de números inteiros que constituem a sequência de ordenação não tem de ser contíguo.

  Um valor de -1 indica que a ordem dos irmãos é a mesma ordem pela qual os nós aparecem nos comentários do EMF. Tenha em atenção que a ordem pela qual o conteúdo aparece no EMF não é necessariamente a ordem pela qual o conteúdo é consumido por um utilizador do documento.

• desn Especifica uma estrutura MSODOCEXSTRUCTTYPE , que é definida anteriormente no documento.

O membro do idNode especifica o ID do nó. Este membro pode não ter um valor de 0. Um valor de -1 indica que os nós subordinados não utilizam o membro idNodeParent para especificar este nó como principal. Em vez disso, este nó só pode ser um elemento principal ao incluir nós subordinados no EMF. Vários nós podem ter um ID de -1. Se o ID não for -1, o valor é exclusivo em todo o documento.

O tipo de nó especifica o tipo de nó de estrutura. Este membro é igual a um dos valores do tipo de enumeração MSODOCEXSTRUCTTYPE . A tabela seguinte lista exemplos de tipos de nós de estrutura de documentos.

Tabela 7. Tipos de nós de estrutura de documentos

Nota: msodocexStructTypeTitle, msodocexStructTypeBlockQuote, msodocexStructTypeCommentAnchor, msodocexStructTypeAnnot, msodocexStructTypeQuote e msodocexStructTypeCaption estão disponíveis quando Word. Document.ExportAsFixedFormat3 é chamado com ImproveExportTagging = true. A versão mínima necessária é o Canal Beta do Microsoft 365 16.0.18720.20000.

fContentNode Especifica se uma estrutura DocExComment_EndStructNode marca o fim deste nó de estrutura. Se fContentNode for verdadeiro, uma estrutura de DocExComment_EndStructNode fecha o conteúdo vinculado pelo nó. Se este fContentNode tiver um valor falso , o nó não vincula qualquer conteúdo.

O membro fContentNode afeta a interpretação do valor do ID principal dos nós subsequentes. Se fContentNodefor verdadeiro, os nós que são inseridos entre este DocExComment_BeginStructNode e um DocExComment_EndStructNode subsequente, e que têm um ID principal de -1, são subordinados deste nó. No entanto, se fContentNode for verdadeiro, os nós inseridos após este DocExComment_BeginStructNode e que têm um ID principal de -1, não são subordinados deste nó. São subordinados do nó especificado mais recentemente que tem fContentNode igual a falso.

Pode aninhar nós de estrutura de documentos a profundidade arbitrária.

cwchAltText Especifica o número de carateres Unicode no bloco de texto alternativo que segue a estrutura. Esta cadeia Unicode especifica texto alternativo para o nó (por exemplo, texto alternativo para uma imagem).

DocExComment_EndStructNode

A estrutura DocExComment_EndStructNode marca o fim do conteúdo decorado pelas informações na DocExComment_BeginStructNode.

struct DocExComment_EndStructNode
{
    DWORD ident {};
    DWORD iComment {};
};    

Os membros da estrutura DocExComment_EndStructNode são os seguintes:

• ident Especifica o valor constante, msodocexsignature, que identifica este comentário do EMF como contendo informações semânticas.

• iComment Especifica o valor MSODOCEXCOMMENT, msodocexcommentEndStructNode.

DocExComment_BeginTextRun

A estrutura DocExComment_BeginTextRun identifica o idioma de uma sequência de texto no documento e fornece os pontos de código Unicode para o texto.

Embora alguns registos EMF de composição de texto utilizem Unicode como representação de texto, outros utilizam os glifos desenhados no ecrã, em vez do texto de origem original. Um glifo é o índice de uma determinada forma no tipo de letra, que pode ser diferente do tipo de letra para o tipo de letra.

Podem existir casos em que vários pontos de código Unicode são combinados num único glifo ou em que um único ponto de código Unicode é dividido em vários glifos. Uma vez que o mapeamento de pontos de código para glifos é dependente do contexto, um utilizador não pode procurar texto ou copiar/colar num documento que contenha apenas glifos. Por conseguinte, por vezes, o Publisher fornece o texto Unicode, bem como os glifos.

struct DocExComment_BeginTextRun
{
    DWORD ident {};
    DWORD iComment {};
    DWORD lcid {};
    int cGlyphIndex {};
    int cwchActualText {};
};

Os membros da estrutura DocExComment_BeginTextRun são os seguintes:

• Ident Especifica o valor constante, msodocexsignature, que identifica este comentário do EMF como contendo informações semânticas.

• iComment Especifica o valor MSODOCEXCOMMENT, msodocexcommentBeginTextRun.

• lcid Especifica o LCID para a sequência de texto.

• cGlyphIndex Especifica o tamanho de uma matriz que segue esta estrutura. Esta matriz implementa uma tabela de índice glifo que mapeia pontos de código Unicode no texto real para os glifos correspondentes no EMF. Cada elemento da matriz corresponde a um ponto de código no texto. O valor desse elemento especifica o primeiro glifo utilizado para compor esse ponto de código no EMF. Dois ou mais pontos de código adjacentes podem ter o mesmo valor na matriz, o que significa que ambos resolve para o mesmo glifo. O valor também pode ser 0, o que significa que este ponto de código não mapeia a nenhum glifo.

• cwchActualText Especifica o tamanho da sequência de pontos de código Unicode que seguem a tabela de índice glifo. Este é o texto que um consumidor do documento pode utilizar para procurar, copiar/colar e acessibilidade. O valor deste membro pode ser 0, o que significa que não é fornecido texto Unicode.

DocExComment_EndTextRun

A estrutura DocExComment_EndTextRun marca o fim de uma sequência de texto, sendo que o início foi marcado por uma estrutura DocExComment_BeginTextRun .

struct DocExComment_EndTextRun
{
    DWORD ident {};
    DWORD iComment {};
};    

Os membros da estrutura DocExComment_EndTextRun são os seguintes:

• ident Especifica o valor constante, msodocexsignature, que identifica este comentário do EMF como contendo informações semânticas.

• iComment Especifica o valor MSODOCEXCOMMENT, msodocexcommentEndTextRun.

DocExComment_UnicodeForNextTextOut

A estrutura DocExComment_UnicodeForNextTextOut funciona de forma semelhante às estruturas de DocExComment_BeginTextRun e DocExComment_EndTextRun . No entanto, DocExComment_UnicodeForNextTextOut especifica pontos de código Unicode apenas para o seguinte registo TEXTOut em EMF, em vez de para um bloco de conteúdo EMF vinculado por estruturas de início e de fim.

struct DocExComment_UnicodeForNextTextOut
{
    DWORD ident {};
    DWORD iComment {};
    int cGlyphIndex {};
    int cwchActualText {};
};

Os membros da estrutura DocExComment_UnicodeForNextTextOut são os seguintes:

• ident Especifica o valor constante, msodocexsignature, que identifica este comentário do EMF como contendo informações semânticas.

• iComment Especifica o valor MSODOCEXCOMMENT, msodocexcommentUnicodeForNextTextOut.

• cGlyphIndex Especifica o tamanho de uma matriz que segue esta estrutura. Esta matriz implementa uma tabela de índice glifo que mapeia pontos de código Unicode no texto real para os glifos correspondentes no EMF. Cada elemento da matriz corresponde a um ponto de código no texto. O valor desse elemento especifica o primeiro glifo utilizado para compor esse ponto de código no EMF. Dois ou mais pontos de código adjacentes podem ter o mesmo valor na matriz, o que significa que ambos resolve para o mesmo glifo.

• cwchActualText Especifica o tamanho da sequência de pontos de código Unicode que seguem a tabela de índice glifo. Este é o texto que um consumidor do documento pode utilizar para procurar, copiar/colar e acessibilidade.

DocExComment_EPSColor

A estrutura DocExComment_EPSColor especifica informações de cor para um ficheiro PostScript (EPS) encapsulado incorporado no EMF. Para obter mais informações sobre esta estrutura, consulte a secção Suporte de Cores Expandidas.

typedef struct
{
    DWORD ident {};
    DWORD iComment {};
    BYTE colorInfo[];
} DocExComment_EPSColor;

Os membros da estrutura DocExComment_EPSColor são os seguintes:

• ident Especifica o valor constante, msodocexsignature, que identifica este comentário do EMF como contendo informações semânticas.

• iComment Especifica o valor MSODOCEXCOMMENT, msodocexcommentEPSColor.

• colorInfo[] Especifica as informações de cor do ficheiro EPS. O suplemento deve transmitir estas informações ao Publisher com o método IMsoDocExporterSite::SetEPSInfo .

DocExComment_EPSColorCMYKJPEG

A estrutura DocExComment_EPSColorCMYKJPEG especifica o início, no EMF, de um objeto binário que é um fluxo de ficheiros CMYKJPEG. Para obter mais informações sobre esta estrutura, consulte a secção Suporte de Cores Expandidas.

typedef struct
{
    DWORD ident {};
    DWORD iComment {};
} DocExComment_EPSColorCMYKJPEG;

Os membros da estrutura DocExComment_EPSColorCMYKJPEG são os seguintes:

• ident Especifica o valor constante, msodocexsignature, que identifica este comentário do EMF como contendo informações semânticas.

• iComment Especifica o valor MSODOCEXCOMMENT, msodocexcommentEPSCMYKJPEG;

DocExComment_EPSColorSpotImage

A estrutura DocExComment_EPSColorSpotImage fornece informações de cor spot para a imagem RGB subsequente. Para obter mais informações sobre esta estrutura, consulte a secção Suporte de Cores Expandidas.

typedef struct
{
    DWORD ident {};
    DWORD iComment {};
    COLORREF cmykAlt { 0 };
    COLORREF rgbAlt { 0 };
    float flTintMin {};
    float flTintMax {};
    char szSpotName[1];
} DocExComment_EPSColorSpotImage;

Os membros da estrutura DocExComment_EPSColorSpotImage são os seguintes:

• ident Especifica o valor constante, msodocexsignature, que identifica este comentário do EMF como contendo informações semânticas.

• iComment Especifica o valor MSODOCEXCOMMENT, msodocexcommentEPSSpotImage.

• cmykAlt Especifica um ID de cor CMYK.

• rgbAlt Especifica um ID de cor RGB.

• flTintMin Especifica a tonalidade mínima.

• flTintMax Especifica a tonalidade máxima.

• szSpotName[1] Especifica um comprimento variável, cadeia terminada a zero que contém o nome spot.

Suporte de Cores Expandidas

Para suportar espaços de cores expandidos no Publisher, são necessários registos semânticos e interfaces EMF adicionais, uma vez que o EMF só suporta cores RGB (vermelho-verde-preto). Os espaços de cores expandidos incluem CMYK (cyan-magenta-yellow-black) e espaço de cores spot, que são normalmente utilizados na impressão comercial.

O Publisher utiliza o mapeamento de cores para representar cores expandidas no DOCUMENTO EMF. O Publisher cria uma tabela de cores para todas as cores utilizadas no documento e substitui as cores reais por IDs de cor no EMF. O tipo para o ID de cor é COLORREF, que é o mesmo tipo que é utilizado para a cor RGB. Para obter informações sobre a estrutura COLORREF, consulte COLORREF.

Para resolve IDs de cor no EMF para expandir o espaço de cores, o suplemento volta a chamar o Publisher através do método HrResolveColor da interface IMsoDocExporterSite. O suplemento transmite ao Publisher um ponteiro de interface para uma interface IDOCEXCOLOR como um dos parâmetros para HrResolveColor. O Publisher utiliza os IDs de cor, também especificados na chamada para HrResolveColor, converte-os em cor expandida (RGB, CMYK ou cor spot) e transmite-os de volta para o suplemento através dos métodos na interface IDOCEXCOLOR .

Cor do Vetor e Imagens Recoloridas

As cores de vetor são quaisquer valores COLORREF que o suplemento recebe do Publisher. Por exemplo, cor do texto, cor do traço da linha e cor para recolorir metaficheiro. Quando o mapeamento de cores está ativado, o Publisher utiliza um ID de cor para COLORREF em vez de um valor de cor RGB real. Se o Publisher fornecer o suplemento de um ponteiro da interface IMsoDocExporterSite ao chamar o método SetDocExporterSite da interface IMsoDocExporter , o suplemento deve chamar sempre o método IMsoDocExporterSite::HrResolveColor para converter o COLORREF numa cor expandida, que o suplemento recebe através dos métodos na interface IDOCEXCOLOR .

Para suportar o mapeamento de cores de vetor, o suplemento tem de fazer o seguinte:

• Implemente o suporte de classe para uma interface IDOCEXCOLOR . Os métodos nesta interface permitem ao Publisher transmitir a cor expandida de volta para o suplemento.

• Coloque em cache os seguintes valores de estado de cor dos registos semânticos no EMF.

• Defina a cor de primeiro plano para recoloração. Isto é definido através da estrutura DocExComment_ColorInfo .

• Defina a cor de fundo para recoloração. Isto é definido através da estrutura DocExComment_ColorInfo .

• Determinar quando o mapeamento de cores está ativado. Isto é definido através da estrutura DocExComment_ColorEnable .

• Para uma cor de vetor, crie uma interface IDOCEXCOLOR com o ID de cor, para que IDOCEXCOLOR::GetUnresolvedRGB devolva o ID de cor. O suplemento deve chamar o método IMsoDocExporterSite::HrResolveColor com a interface IDOCEXCOLOR e estados de cor em cache. O Publisher chama os métodos de interface IDOCEXCOLOR com a cor final, que pode ser RGB, CMYK, spot ou tint de registo.

• Quando a cor de primeiro plano ou a cor de fundo para recoloração são especificadas a partir de um registo semântico em EMF, o suplemento deve recolorir imagens no suplemento (por exemplo, metaficheiros ou imagens rasterísticas).

Imagens Não Recoloridas

O EMF suporta imagens CMYK com GDI+. Por conseguinte, as imagens no EMF podem ser RGB ou CMYK. Se a imagem for uma imagem CMYK, o suplemento tem de converter a imagem no espaço de cores de destino.

O Publisher mantém um espaço de cores de destino para o documento. O suplemento pode utilizar este espaço de cores de destino ao chamar o método IMsoDocExporterSite::HrConvertImageColorSpace com o espaço a cores da imagem.

Cor dos Ficheiros EPS

Encapsulated Postscript (EPS) é um tipo de metaficheiro que suporta espaços de cores expandidos. O utilizador que incorpore imagens EPS num documento do Publisher espera que as informações de cor sejam utilizadas na saída de formato fixo. No Publisher, o EPS é convertido num EMF com registos semânticos relacionados com EPS. Em seguida, este EMF é incorporado no ficheiro EMF da página que a aplicação transmite ao suplemento.

Para suportar a cor nos ficheiros EPS, o suplemento tem de fazer o seguinte:

• Chame o método IMsoDocExporterSite::SetEPSInfo para DocExComment_EPSColor registos encontrados no EMF.

• Extraia a imagem CMYK do registo DocExComment_EPSColorCMYKJPEG no EMF. Este registo contém um objeto binário que é o fluxo de ficheiros JPEG do CMYK real. Utilize-a para substituir a imagem RGB especificada na chamada subsequente para a função StretchDIBits .

• O registo DocExComment_EPSColorSpotImage fornece informações de cor spot para a imagem RGB subsequente, que é sempre uma imagem de índice. O suplemento tem de converter a imagem spot no espaço de cores de destino.

• Opcionalmente, o suplemento pode chamar o método IMsoDocExporterSite:: HrGetSpotRecolorInfo para obter a cor de destino do documento no Publisher. Em seguida, o suplemento pode recolorir a imagem RGB subsequente ao mapear as cores da paleta da imagem RGB para flTintMin e flTintMax tints especificados no registo de DoxExComment_EPSColorSpotImage . A luminosidade para cada cor da paleta é utilizada para o mapeamento.

Tenha em atenção que o registo de DocExComment_EPSStart é apenas informativo. O suplemento pode ignorar este registo.

SetDocExporterSite

O Publisher chama SetDocExporterSite para fornecer o suplemento com um ponteiro para uma interface IMsoDocExporterSite . A interface IMsoDocExporterSite expõe métodos que permitem o suporte de cores expandidas.

void SetDocExporterSite(
    IMsoDocExporterSite* pDocExporterSite
);

O parâmetro pDocExporterSite especifica o ponteiro da interface para a interface IMsoDocExporterSite .

HrSetPageHeightForPagination

Uma aplicação pode chamar o método HrSetPageHeightForPagination para especificar a altura da página em pontos.

HRESULT HrSetPageHeightForPagination(
    float dytfPageHeight
);

Algumas aplicações mantêm o documento do utilizador num formato não paginado. Nestes casos, o suplemento pagina o documento com a altura da página especificada pela aplicação na chamada para HrSetPageHeightForPagination. O parâmetro dytfPageHeight especifica a altura da página em pontos.

Depois de especificar as informações de altura da página, a aplicação transmite o suplemento todo o documento como um único ficheiro EMF dentro da memória numa chamada para HrAddPageFromEmf. Em seguida, o suplemento utiliza a altura da página e o ficheiro EMF para paginar o documento.

O suplemento devolve as informações de paginação à aplicação em chamadas subsequentes para o método HrGetPageBreaks .

HrGetPageBreaks

Uma aplicação pode chamar o método HrGetPageBreaks para obter o número e a localização das quebras de página para documentos paginados pelo suplemento.

HRESULT HrGetPageBreaks(
    float* rgdytfPageBreaks,
    int* pcchPageBreaks,
    BOOL* pfCanTrustLastBreakIsEndOfDocument
);

Depois de o suplemento paginar um documento com a altura da página especificada pelo método HrSetPageHeightForPagination , devolve as informações de paginação em chamadas subsequentes que a aplicação efetua ao método HrGetPageBreaks .

O parâmetro rgdytfPageBreaks é um ponteiro para uma matriz de valores flutuantes que especificam as localizações das quebras de página em pontos. O primeiro elemento na matriz (índice 0) é a localização da primeira quebra de página, o segundo elemento é a localização da segunda quebra de página e assim sucessivamente. Por conseguinte, os valores destes elementos estão a aumentar sucessivamente.

O parâmetro pcchPageBreaks é um ponteiro para um valor inteiro que especifica o número de quebras de página no documento.

O parâmetro pfCanTrustLastBreakIsEndOfDocument especifica se a localização da última quebra de página é o fim do documento ou o início da última página do documento. Um valor verdadeiro indica que a última quebra de página é o fim do documento.

A aplicação chama HrGetPageBreakduas vezes para obter as informações de paginação. Na primeira chamada, a aplicação chama HrGetPageBreaks para obter o número de quebras de página.

HrGetPageBreaks(NULL, &nPageBreaks, NULL);

Em seguida, a aplicação chama HrGetPageBreaks uma segunda vez para obter as localizações reais. Na segunda chamada, a aplicação transmite uma memória intermédia de tamanho suficiente para conter a matriz de localizações de quebra de página.

HrGetPageBreaks(rgPageBreaks, &nPageBreaks, fCanStopAtLastPageBreak);

Depois de receber as informações de quebra de página do suplemento, a aplicação reinicia o processo de exportação de formato fixo, começando com uma chamada para o método HrCreateDoc , seguida de uma chamada para HrAddPageFromEmf para cada uma das páginas fornecidas pelas informações de quebra de página.

HrAddOutlineNode

O Publisher chama o método HrAddOutlineNode para transmitir o suplemento a uma estrutura que descreve um nó dentro de um destaque navegável pelo utilizador para o documento exportado.

HRESULT HrAddOutlineNode(
    int idNodeParent 
    const MSODOCEXOUTLINENODE* pNode
);    

O código de exportação de formato fixo pode utilizar as informações transmitidas pelo método HrAddOutlineNode para construir um destaque navegável pelo utilizador do documento de exportação. Do ponto de vista do utilizador, cada nó no destaque é representado por algum texto de título que mapeia para uma localização específica no documento.

Cada chamada para HrAddOutlineNode especifica informações para um único nó neste destaque. Cada nó é identificado por um ID de nó que é exclusivo dentro do destaque. Um ID de 0 está reservado para o nó raiz. O destaque é hierárquico, ou seja, tem uma estrutura de árvore na qual cada nó tem um único elemento principal e zero ou mais nós subordinados.

O primeiro parâmetro para HrAddOutlineNode fornece o ID do nó que é o principal do nó que está a ser transmitido.

O Publisher chama sempre HrAddOutlineNode para um nó principal antes de chamar o método para qualquer um dos subordinados do nó principal. Por outras palavras, o código de exportação tem a certeza de já ter as informações do nó para o nó identificado pelo parâmetro idNodeParent . A única exceção é a chamada inicial para HrAddOutlineNode que especifica o nó raiz. Para esta chamada, o valor de idNodeParent é 0.

As informações adicionais de que o código de exportação precisa para cada nó são transmitidas por HrAddOutlineNode numa estrutura MSODOCEXOUTLINENODE apontada pelo parâmetro pNode .

typedef struct _MsoDocexOutlineNode
{
    int idNode {};
    WCHAR rgwchNodeText[cwchMaxNodeText];
    int iDestPage {};
    float dytfvDestPage {};
    float dxtfvDestOffset {};
    float dytfvDestOffset {};
} MSODOCEXOUTLINENODE;

Os membros do MSODOCEXOUTLINENODE são descritos da seguinte forma:

• idNode O ID do nó. Um valor de -1 indica que este nó não pode ter nós subordinados no destaque. Caso contrário, este membro tem um valor exclusivo em todo o documento.

• rgwchNodeText Uma cadeia Unicode que representa o texto do título de cada nó. Este texto não tem de ser exclusivo em todo o destaque.

• iDestPage O número de página da página que contém a localização de destino no documento.

• dytfvDestPage A altura da página de destino em pontos. O desvio especificado pelo membro dytfvDestOffset é relativo ao canto superior esquerdo da página. No entanto, alguns tipos de formato fixo utilizam um sistema de coordenadas relativo ao canto inferior esquerdo da página. Para estes tipos de documentos, a altura da página é necessária para converter o desvio.

• dxtfvDestOffset O deslocamento horizontal da localização de destino na página de destino.

• dytfvDestOffset O deslocamento vertical da localização de destino na página de destino.

HrAddDocumentMetadataString

O Publisher chama o método HrAddDocumentMetadataString para especificar metadados do documento sob a forma de uma cadeia Unicode.

HRESULT HrAddDocumentMetadataString(
    MSODOCEXMETADATA metadataType, 
    const WCHAR* pwchValue
);

O parâmetro metadadostype especifica o tipo de metadados representados pela cadeia. O parâmetro metadadostype tem de ser um dos seguintes valores do tipo de enumeração MSODOCEXMETADATA.

Tabela 8. Valores enumerados de MSODOCEXMETADATA

Para um determinado documento, cada tipo de metadados só pode ter uma cadeia associada. Por exemplo, se o documento tiver várias palavras-chave, estas são transmitidas para o suplemento como uma cadeia concatenada.

O parâmetro pwchValue especifica uma cadeia Unicode que contém os próprios metadados.

A forma como o suplemento incorpora os metadados da cadeia de texto no documento exportado depende dos detalhes de implementação do código de exportação e do tipo de formato fixo utilizado no documento exportado.

HrAddDocumentMetadataDate

O Publisher chama o método HrAddDocumentMetadataDate para especificar metadados do documento sob a forma de uma estrutura FILETIME.

HRESULT HrAddDocumentMetadataDate(
    MSODOCEXMETADATA metadataType, 
    const FILETIME* pftLocalTime
);

O parâmetro metadadostype especifica o tipo de metadados representados pela estrutura FILETIME . O parâmetro metadadostype tem de ser um dos seguintes valores do tipo de enumeração MSODOCEXMETADATA.

Tabela 9. Valores enumerados de MSODOCEXMETADATA

O parâmetro pftLocalTime especifica um ponteiro para uma estrutura FILETIME que contém as informações de data e hora dos metadados. O fragmento de código seguinte demonstra como extrair estas informações da estrutura.

SYSTEMTIME st = { 0 };
WCHAR s[100];
FileTimeToSystemTime(pfiletime, &st);
swprintf(s, 99, L" %04d-%02d-%02dT%02d:%02d:%02dZ", st.wYear % 10000, 
    st.wMonth % 100, st.wDay % 100, st.wHour % 100, st.wMinute % 100, 
    st.wSecond % 100);

A forma como o suplemento incorpora os metadados de data e hora no documento exportado depende dos detalhes de implementação do código de exportação e do tipo de formato fixo utilizado no documento exportado.

HrFinalize

O Publisher chama o método HrFinalize no final do processo de exportação de documentos.

HRESULT HrFinalize();

O código que implementa a exportação de formato fixo deve utilizar HrFinalize para executar tarefas como remover memórias intermédias de dados, escrever dados restantes no disco e libertar memória e outros recursos.

Conclusão

Pode expandir a funcionalidade de exportação de formato fixo das aplicações do Office ao implementar a interface IMsoDocExporter . Os métodos desta interface fornecem um canal para as aplicações do Office comunicarem com o suplemento os conteúdos visuais e as informações semânticas no documento a exportar. O conteúdo visual do documento é fornecido ao suplemento como um ou mais metaficheiros melhorados na memória. As informações semânticas são fornecidas como registos de comentários especialmente formatados neste EMF. Métodos adicionais na interface permitem que as aplicações do Office comuniquem metadados e informações estruturais sobre o documento.

Recursos adicionais

Para obter mais informações, consulte os seguintes recursos:

• Word. Document.ExportAsFixedFormat3

• Excel.Workbook.ExportAsFixedFormat

• PowerPoint.Presentation.ExportAsFixedFormat3

• Project.Project.ExportAsFixedFormat

• Publisher.Documents.ExportAsFixedFormat

• Visio.Document.ExportAsFixedFormat

• OneNote.Application.Publish