Estendendo a exportação de PDF do Office

Resumo: Crie um suplemento COM para o Office 2024, o Office LTSC 2024 e o Microsoft 365 versão 2408 e aplicativos posteriores com sua própria lógica de exportação para o formato PDF. A técnica descrita requer conhecimento 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 ao Office (2024) Fixed-Format Recurso de exportação

Este artigo explica como os desenvolvedores de software de terceiros podem se conectar ao recurso de exportação de formato fixo disponível nos aplicativos Office 2024, Office Office LTSC 2024, Microsoft 365 Versão 2408 e posteriores para que possam adicionar seu próprio exportador.

Os aplicativos incluem exportadores integrados para Microsoft XML Paper Specification (XPS) e Portable Document Format (PDF). Os formatos de arquivo fixo expõem o conteúdo de um documento em um formato paginado que é independente do aplicativo e da plataforma.

Os desenvolvedores de software podem adicionar seu próprio exportador, escrevendo um suplemento do Office que implementa a interface COM IMsoDocExporter . Este artigo descreve o IMsoDocExporter e sua interação com um aplicativo de hospedagem do Microsoft 365, como o Word.

A exportação de formato fixo está disponível desde a versão Office 2007 e este artigo inclui informações sobre os recursos que são novos nas versões Office 2024, Office LTSC 2024, Microsoft 365 Versão 2408.

Importante
O recurso de exportação de formato fixo está disponível em todos os aplicativos listados na seção Aplica-se a anterior. No entanto, a discussão abaixo usa o Publisher como um aplicativo de exemplo, exceto nos casos em que uma explicação é mais relevante para um aplicativo diferente.

Inicializando Add-Ins

Para que o usuário acesse a funcionalidade do suplemento, o suplemento deve adicionar um novo item de menu ou um novo botão da barra de ferramentas ao aplicativo. Quando o usuário seleciona esse item de menu ou botão, o suplemento deve usar o Modelo de Objeto do Microsoft Office para obter um ponteiro para o documento ativo. Em seguida, ele deve chamar o método ExportAsFixedFormat do documento ativo com um ponteiro de interface IUnknown que dá suporte à interface IMsoDocExporter por meio de uma chamada para o método QueryInterface . O parâmetro do modelo de objeto para o ponteiro da interface é um tipo VARIANT com VT_UNKNOWN.

Observação
Para o OneNote, o suplemento chama o método Publish com um parâmetro de cadeia de caracteres que é a ID de classe da implementação do suplemento da interface IMsoDocExporter . Em seguida, o OneNote chama CoCreateInstance com a ID de classe para obter um ponteiro de interface IUnknown da fábrica de classes do suplemento.

Depois que o Publisher tiver um ponteiro para a interface IMsoDocExporter , ele chamará de volta o suplemento por meio dos métodos expostos pelo IMsoDocExporter. Por meio desses retornos de chamada, o Word fornece ao suplemento conteúdo do documento e outras informações sobre o documento.

Uma excelente fonte de informações sobre a criação de suplementos COM para aplicativos do Microsoft Office é o artigo codeproject.com Criando um suplemento COM Office2K com VC++/ATL.

IMsoDocExporter

A interface IMsoDocExporter expõe os métodos a seguir.

Tabela 1. Métodos expostos pela interface IMsoDocExporter

Method	Descrição
HrCreateDoc	Chamado no início do processo de exportação de formato fixo.
HrAddPageFromEmf	Chamado para transmitir ao suplemento um EMF (metarquivo avançado) que representa uma exibição renderizada do conteúdo a ser exportado.
HrAddDocumentMetadataString	Chamado para especificar metadados de formato de cadeia de caracteres para o documento.
HrAddDocumentMetadataDate	Chamado para especificar metadados de formato de data para o documento.
HrSetDefaultLcid	Chamado para especificar a LCID (ID de localidade) padrão para o conteúdo a ser exportado.
HrAddOutlineNode	Chamado para especificar informações de estrutura de tópicos de documento navegáveis pelo usuário.
HrGetPageBreaks	Chamado para obter informações de paginação do suplemento.
HrSetPageHeightForPagination	Chamado para especificar a altura da página para permitir que o suplemento pagine o documento.
HrFinalize	Chamado no final do processo de exportação de formato fixo. Permite que o suplemento execute qualquer processamento final.
HrBeginStructNode	Chamado para transmitir ao suplemento a estrutura inicial de um nó de estrutura de documento que abrange várias páginas.
HrEndStructNode	Chamado para transmitir ao suplemento a estrutura final de um nó de estrutura de documento que se estende por várias páginas.
EnableCancel	Chamado para passar o suplemento um ponteiro para uma interface IDocExCancel .
GetOutputOption	Chamado para recuperar opções de saída de formato fixo.
SetOutputOption	Chamado pelo Office para definir opções de saída de formato fixo.
SetDocExporterSite	Chamado para fornecer ao suplemento um ponteiro para uma interface IMsoDocExporterSite para suporte estendido a cores.

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

Tabela 2. Métodos herdados da interface IUnknown

Method	Descrição
AddRef	Incrementa a contagem de referência.
QueryInterface	Retorna ponteiros para interfaces compatíveis. A implementação de QueryInterface do suplemento deve dar suporte ao retorno de um ponteiro de interface IMsoDocExporter do IID_IMsoPdfWriter.
Lançar	Diminui a contagem de referência.

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

Fluxo de chamadas

O diagrama a seguir mostra a sequência na qual o Publisher chama os métodos expostos em IMsoDocExporter. Nem todos os métodos são usados por todos os aplicativos do Microsoft Office e nem todos os métodos são usados para todos os documentos exportados.

Figura 1. Métodos de chamada da interface IMsoDocExporter

As seções a seguir descrevem ainda mais os métodos expostos pela interface IMsoDocExporter . Os métodos são descritos aproximadamente na ordem em que seriam chamados pelo Publisher.

GetOutputOption e SetOutputOption

O Publisher chama os métodos GetOutputOption e SetOutputOption para recuperar 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 interno no Office use GetOutputOption e SetOutputOption, um suplemento pode implementar seu próprio método de obter e definir opções e sua própria experiência do usuário para as opções.

O Microsoft Office chama GetOutputOption somente 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 recuperar opções de saída para exibição para o usuário na caixa de diálogo Publicar como PDF ou XPS . Para suplementos desenvolvidos por desenvolvedores de software de terceiros, o Publisher chama GetOutputOption apenas com o valor msodocexOptionTargetDPIColor. Esse é o único valor que um suplemento precisa dar suporte. Se a implementação de GetOutputOption do suplemento for chamada com esse valor, ela deverá retornar os DPI (pontos por polegada) de destino para rasterização de efeito 3D.

O Microsoft Office chama SetOutputOption para suplementos Fixed-Format

Para a implementação da exportação de formato fixo no Office e para implementações de suplemento, o Publisher chama SetOutputOption no início do processo de exportação de formato fixo. Na implementação no Office, os valores de parâmetro passados especificam opções de saída de formato fixo. No entanto, se o suplemento implementar seu próprio conjunto de opções, o suplemento poderá desconsiderar as opções passadas a ele pelo Editor.

EnableCancel

O Publisher chama o método EnableCancel para passar o suplemento um ponteiro para uma interface IMsoDocExCancel . O suplemento pode usar essa interface para consultar se um usuário opta por cancelar uma longa operação de exportação de documentos.

void EnableCancel(
    IMsoDocExCancel* pdec
);

HrBeginStructNode

O Publisher chama o método HrBeginStructNode para especificar o início de um nó de estrutura de documento para conteúdo que abrange várias páginas completas no documento. Os nós da estrutura do documento para elementos do documento que residem inteiramente em uma página (por exemplo, parágrafos) são inseridos pelo Publisher no próprio metarquivo aprimorado (EMF) usando as estruturas DocExComment_BeginStructNode e DocExComment_EndStructNode . Para obter mais informações sobre nós de estrutura de documento, consulte as seções HrAddPageFromEmf e DocExComment_BeginStructNode neste artigo.

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

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

O parâmetro iSortOrder especifica a ordem de classificação do nó da estrutura entre seus irmãos. Dois nós não podem ter a mesma ordem de classificação. No entanto, o conjunto de inteiros que constituem a ordem de classificação não precisa ser contíguo. Um valor de -1 indica que a ordem de classificação irmã é a mesma ordem em que os nós aparecem nos comentários 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 idNode especifica a ID do nó que está sendo passado na chamada para HrBeginStructNode. Esse membro pode não ter um valor de 0. Um valor de -1 indica que os nós filhos não usam o parâmetro idNodeParent para especificar esse nó como pai. Em vez disso, esse nó pode ser pai apenas incluindo nós filhos no EMF. Vários nós podem ter uma ID de -1. Se a ID não for -1, o valor será exclusivo em todo o documento.

A união incorporada no final do nó MSODOCEXSTRUCT

• iHeadingLevel é o nível de título de um msodocexStructTypeHeading.
• idPara é a ID de parágrafo para um P, TOCI ou ListBody.
• idDropCap é a 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 para um msodocexStructTypeList ou msodocexStructTypeListItem.
• listType é o tipo de lista para um msodocexStructTypeListItem.
• idAtn é a ID de um msodocexStructTypeAnnotationBegin ou msodocexStructTypeAnnotationEnd.
• cpLim é usado para determinar a ordem de aninhamento de tabelas dentro de tabelas para um msodocexStructTypeTable, msodocexStructTypeTOC ou msodocexStructTypeListBody.
• shapeProperty é para um msodocexStructTypeFigure em que o conteúdo é uma forma, uma caixa de texto ou uma célula de tabela e contém campos de bit da enumeração MSODOCEXSHAPEPROPERTY.
• tableAttr são os atributos da célula da tabela para um msodocexStructTypeTH ou msodocexStructTypeTD.
• O cpNoteRef é usado para vincular msodocexStructTypeIntLinkNoteRef a msodocexStructTypeFootnote/msodocexStructTypeEndnote. Isso é explicado com mais detalhes posteriormente nesta seção.
• idTableHeader é a ID exclusiva de um msodocexStructTypeTH ou msodocexStructTypeTD.
• cpXchAtnMainDod é usado para vincular msodocexStructTypeCommentAnchor a msodocexStructTypeAnnot. Isso é explicado com mais detalhes posteriormente nesta seção.
• iTargetParentId é a id do nó para o qual reparentar um msodocexStructTypeDiagram.
• wzMathMlText é uma cadeia de caracteres MathML para msodocexStructTypeEquation.
• pListAttr é uma lista de atributos para msodocexStructTypeList.

Observação: cpNoteRef, cpXchAtnMainDod, wzMathMlText e pListAttr estão disponíveis no Word. Document.ExportAsFixedFormat3 é chamado com ImproveExportTagging = true. A versão mínima necessária é Microsoft 365 versão 2506.

Tabela 3. Valores enumerados de MSODOCEXLINEBREAKTYPE

Valor	Descrição
msodocexLineBreakTypeNormal	Quebra de linha normal.
msodocexLineBreakTypeManual	Quebra de linha manual.
msodocexLineBreakTypeEOP	Fim do parágrafo.

Tabela 4. Valores enumerados de MSODOCEXLISTTYPE

Valor	Descrição
msodocexListTypeNone	Sem marcadores ou numeração.
msodocexListTypeBulletDisc	Balas em forma de disco.
msodocexListTypeBulletCircle	Balas em forma de círculo.
msodocexListTypeBulletSquare	Balas quadradas.
msodocexListTypeBulletDecimal	Numeração decimal.
msodocexListTypeUpperRoman	Numeração de algarismos romanos maiúsculos.
msodocexListTypeLowerRoman	Numeração de algarismos romanos minúsculos.
msodocexListTypeUpperAlpha	Numeração alfabética em maiúsculas.
msodocexListTypeLowerAlpha	Numeração alfabética minúscula.

Tabela 5. Valores enumerados dos campos de bit MSODOCEXSHAPEPROPERTY

Valor	Valor numérico	Descrição
msodocexShape	0x00000001	O objeto é uma forma ou caixa de texto.
msodocexShapeText	0x00000002	O objeto tem texto que não é espaço em branco.
msodocexShapePath	0x00000004	O objeto tem um preenchimento e/ou contorno.
msodocexShapeAltText	0x00000008	O objeto tem Texto Alt.
msodocexShapeEquation	0x00000010	O objeto tem texto que contém uma equação.
msodocexShapeTabelCell	0x00000020	O objeto é uma célula em uma tabela.
msodocexShapeIllustrative	0x00000040	O objeto é ilustrativo e não contente.

MsoDocexTableAttr

A estrutura MsoDocexTableAttr se ajusta em 32 bits e inclui as informações de escopo de linha e coluna e de cabeçalho para 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/Ambos ou Coluna.

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

• fColScope Especifica se o cabeçalho é Coluna/Ambos 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 em que a lista termina.

Dicas de pós-processamento

Em alguns casos, os nós precisam ser pós-processados para alcançar os resultados desejados.

Notas de rodapé/notas de fim pós-processamento

Durante a exportação, os links de nota de rodapé/nota de fim serão marcados como msodocexStructTypeIntLinkNoteRef. Os corpos de nota de rodapé/nota de fim serão marcados como msodocexStructTypeFootnote e msodocexStructTypeEndnote, respectivamente, e sempre serão nós de nível superior no nó msodocexStructTypeDocument. O nó msodocexStructTypeIntLinkNoteRef e o nó msodocexStructTypeFootnote/msodocexStructTypeEndnote correspondente terão o mesmo valor cpNoteRef. Isso pode ser usado para mover nós de nota de rodapé/nota de fim sob seus nós de link correspondentes para manter uma ordem de leitura lógica.

Pós-processamento de comentários

Durante a exportação, cada âncora de comentário será marcada como msodocexStructTypeCommentAnchor. Os corpos de comentário serão marcados como msodocexStructTypeAnnot e sempre serão nós de nível superior no nó msodocexStructTypeDocument. O nó msodocexStructTypeCommentAnchor e o nó msodocexStructTypeAnnot correspondente terão o mesmo valor cpXchAtnMainDod. Isso pode ser usado para mover nós de anotação sob seus nós âncora de comentário correspondentes para manter uma ordem de leitura lógica.

Pós-processamento de tabelas de layout

Durante a exportação, se detectarmos que uma tabela é uma tabela de layout, a marcaremos como msodocexStructTypeTable, mas definiremos o cpLim do nó como -2 (nosso valor constante para indicar que esta é uma tabela de layout). Esse valor pode ser usado para determinar se os nós da tabela devem ser marcados 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 eles representam o mesmo parágrafo entre páginas. Para tabelas, os valores de cpLim podem ser verificados para ver se são os mesmos.

Para listas, adicionamos uma nova classe ao MsoDocexStructNode, MsoDocexListAttr, que contém o cpLim de uma lista. Isso pode ser usado para marcar se dois nós de lista têm o mesmo cpLim, o que significa que ambos representam a mesma lista no documento.

Para nós de estrutura de tabela, a união é interpretada como uma ordem das extremidades da tabela em relação a outras tabelas usando cpLim, que pode ser usado para determinar a ordem de aninhamento de tabelas dentro de tabelas.

No contexto do DocExComment_BeginStructNode, o suplemento pode ignorar o membro pwchActualText dessa união.

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

O parâmetro fNoEndNode para HrBeginStructNode especifica se o Publisher chama o método HrEndStructNode para marcar o final do nó da estrutura. Se fNoEndNode for false, o Publisher chamará HrEndStructNode para fechar o conteúdo limitado pelo nó. Se esse parâmetro tiver um valor verdadeiro , o nó não vinculará nenhum conteúdo.

O parâmetro fNoEndNode afeta a interpretação do valor da ID pai dos nós subsequentes. Se fNoEndNode for false, os nós inseridos entre essa chamada para HrBeginStructNode e a chamada subsequente para HrEndStructNode e que tenham uma ID pai de -1 serão filhos desse nó. No entanto, se fNoEndNode for true, os nós inseridos após essa chamada para HrBeginStructNode e que têm uma ID pai de -1 não são filhos desse nó, mas são filhos do próximo nó especificado mais recentemente que tem fNoEndNode igual a false.

Os nós da estrutura do documento podem ser aninhados em profundidades arbitrárias.

Os nós especificados por HrBeginStructNode e aqueles especificados por DocExComment_BeginStructNode compartilham o mesmo espaço de ID e existem na mesma árvore de estrutura de documento. HrBeginStructNode e DocExComment_BeginStructNode são duas maneiras alternativas de adicionar nós a essa árvore. Por exemplo, se o nó aberto mais recentemente foi aberto por HrBeginStructNode e o próximo nó encontrado é de um DocExComment_BeginStructNode EMFcommentrecord com idNodeParent igual a -1, isso significa que o nó de HrBeginStructNode é o pai do nó do registro DocExComment_BeginStructNode .

HrEndStructNode

O Publisher chama o método HrEndStructNode para especificar o final de um nó de estrutura de documento para conteúdo que abrange várias páginas do documento. O nó da estrutura terminado pelo HrEndStructNode foi iniciado anteriormente por uma chamada para o método HrBeginStructNode . Para obter mais informações, consulte HrBeginStructNode neste artigo.

HRESULT HrEndStructNode();

HrCreateDoc

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

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 vazio de formato fixo. O parâmetro wzDocExFile especifica um nome para o arquivo de saída no qual gravar o documento de formato fixo.

Para uma implementação de suplemento, o Publisher chama HrCreateDoc com o nome de arquivo fornecido pelo suplemento na chamada para o método ExportToFixedFormat no modelo de objeto do Microsoft Office. No entanto, como os suplementos normalmente fornecem interface do usuário de configuração para permitir que o usuário especifique um nome de arquivo de saída, o suplemento pode desconsiderar esse nome de arquivo durante o processo de exportação.

Para aplicativos do Microsoft Office que exigem que o suplemento pagine o documento, HrCreateDoc é chamado duas vezes, uma no início da sequência de chamada de paginação e outra depois que o suplemento paginou o documento. Para obter mais informações, consulte as descrições do método HrSetPageHeightForPagination e do método HrGetPageBreaks.

HrSetDefaultLcid

O Publisher chama o método HrSetDefaultLcid para especificar a LCID (ID de localidade) padrão para o conteúdo a ser exportado.

HRESULT HrSetDefaultLcid(
    DWORD lcid
);

Para obter uma lista de LCIDs válidos, consulte Lista de valores de LCID (ID de localidade) conforme atribuído pela Microsoft.

HrAddPageFromEmf

O Publisher chama o método HrAddPageFromEmf para passar o suplemento a um identificador para um EMF na memória que representa o conteúdo no documento a ser exportado.

HRESULT HrAddPageFromEmf(
    HENHMETAFILE hemf
);

O EMF passado pelo Microsoft Office para o suplemento é a fonte primária do conteúdo que o suplemento exporta como um arquivo de formato fixo. O Microsoft Office chama HrAddPageFromEmf uma vez para cada página de conteúdo no documento de origem do aplicativo.

Os comentários EMF transmitem informações semânticas

Um EMF é uma sequência de comandos de desenho (comandos GDI e GDI+) que especificam como renderizar os elementos visuais do documento. O EMF não contém nenhuma informação além desses comandos (por exemplo, "desenhar uma imagem aqui" ou "desenhar uma linha ali"). Em particular, os campos eletromagnéticos convencionais não suportam aspectos semânticos do documento, como hiperlinks, informações de localidade e informações de acessibilidade. Para preservar as informações semânticas no documento exportado, o Publisher injeta registros especiais no EMF. Esses registros contêm as informações semânticas.

Os registros que representam as informações semânticas são implementados como comentários EMF formatados especialmente. O formato EMF permite tipos de registro de comentário que são ignorados pelo mecanismo de renderização para GDI (Graphics Device Interface), mas podem conter informações arbitrárias.

Como exemplo, considere um documento que contém texto alternativo. (Texto alternativo é usado por leitores de documentos para descrever imagens para usuários com deficiência visual.) O Publisher injeta comentários EMF antes e depois de renderizar a imagem, e esses comentários EMF especificam o texto alternativo para a imagem. O suplemento interpreta os comentários e grava as informações no arquivo de exportação de formato fixo.

A tabela a seguir mostra os tipos de registros semânticos compatíveis com o recurso de exportação de formato fixo do Microsoft Office. Esses tipos são enumerados pela enumeração MSODOCEXSTRUCTTYPE . Cada tipo corresponde a um tipo de estrutura que descreve o formato do registro.

Tabela 6. Tipos de registro semântico compatíveis com a exportação de formato fixo

Valor do comentário	Tipo de estrutura
msodocexcommentExternalHyperlink	DocExComment_ExternalHyperlink
msodocexcommentExternalHyperlinkRctfv	DocExComment_ExternalHyperlink
msodocexcommentInternalHyperlink	DocExComment_InternalHyperlink
msodocexcommentInternalHyperlinkRctfv	DocExComment_InternalHyperlink
msodocexcommentColorInfo	DocExComment_ColorInfo
msodocexcommentColorMapEnable	DocExComment_ColorEnable
msodocexcommentBeginTextRun	DocExComment_BeginTextRun
msodocexcommentBeginTextRunRTL	DocExComment_BeginTextRun
msodocexcommentEndTextRun	DocExComment_EndTextRun
msodocexcommentBeginStructNode	DocExComment_BeginStructNode
msodocexcommentEndStructNode	DocExComment_EndStructNode
msodocexcommentUnicodeForNextTextOut	DocExComment_UnicodeForNextTextOut
msodocexcommentUnicodeForNextTextOutRTL	DocExComment_UnicodeForNextTextOut
msodocexcommentEPSColor	DocExComment_EPSColor
msodocexcommentEPSCMYKJPEG	DocExComment_EPSColorCMYKJPEG
msodocexcommentEPSSpotImage	DocExComment_EPSColorSpotImage
msodocexcommentEPSStart	DocExComment_EPSStart
msodocexcommentPageName	DocExComment_PageName
msodocexcommentTransparent	DocExComment_Transparent
msodocexcommentBoundingBox	DocExComment_BoundingBox Versão mínima 18702.

DocExComment_ExternalHyperlink(Rctfv)

A estrutura DocExComment_ExternalHyperlink(Rctfv) descreve um hiperlink vinculado a fora do documento, por exemplo, a um site da 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:

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

• iComentário Especifica o valor MSODOCEXCOMMENT msodocexcommentExternalHyperlink ou msodocexcommentExternalHyperlinkRctfv.

• rcdvRegion e rctfvRegion Uma união que especifica a região da página que é o local de origem do hiperlink. A região pode ser representada como um tipo RECT (rcdvRegion) que usa pixels de dispositivo como unidade de medida ou como uma estrutura que contém coordenadas de ponto flutuante (rctfvRegion), nesse caso, a unidade de medida são pontos.

  Se o membro iComment for igual a msodocexcommentExternalHyperlink, o suplemento deverá usar rcdvRegion. Nesse caso, o suplemento precisa aplicar a matriz de transformação EMF atual a rcdvRegion para convertê-la em espaço de página.

  Se o membro iComment for igual a msodocexcommentExternalHyperlinkRctfv, o suplemento deverá usar rctfvRegion. Nesse caso, rctfvRegion já está no espaço da página, portanto, nenhuma transformação é necessária.

• wzLink[MAX_PATH] Especifica a URL de destino desse hiperlink.

DocExComment_InternalHyperlink(Rctfv)

A estrutura DocExComment_InternalHyperlink(Rctfv) descreve um hiperlink vinculado a um local no documento. Observe que, embora o Publisher passe um EMF separado para cada página do documento, o destino do hiperlink especificado por DocExComment_InternalHyperlink(Rctfv) pode estar em uma página diferente do local 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:

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

• iComentário Especifica o valor MSODOCEXCOMMENT, msodocexcommentInternalHyperlink ou msodocexcommentInternalHyperlinkRctfv.

• rcdvRegion e rctfvRegion Assim como acontece com a estrutura DocExComment_ExternalHyperlink , esse membro é uma união que especifica a região da página que é o local de origem do hiperlink. A região pode ser representada como um tipo RECT (rcdvRegion) que usa pixels de dispositivo como unidade de medida ou como uma estrutura que contém coordenadas de ponto flutuante (rctfvRegion), nesse caso, a unidade de medida são pontos.

  Se o membro iComment for igual a msodocexcommentInternalHyperlink, o suplemento deverá usar rcdvRegion. Nesse caso, o suplemento precisa aplicar a matriz de transformação EMF atual a rcdvRegion para convertê-la em espaço de página.

  Se o membro iComment for igual a msodocexcommentInternalHyperlinkRctfv, o suplemento deverá usar rctfvRegion. Nesse caso, rctfvRegion já está no espaço da página, portanto, nenhuma transformação é necessária.

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

• xtfvTarget Especifica a coordenada x do local de destino na página de destino. A unidade de medida para esse valor é pontos.

• ytfvTarget Especifica a coordenada y do local de destino na página de destino. A unidade de medida para esse valor é pontos.

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

DocExComment_ColorInfo

A estrutura DocExComment_ColorInfo especifica informações de estado de cor para o EMF. Para obter mais informações sobre essa estrutura, consulte a seção Suporte estendido a cores.

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

Os membros da estrutura DocExComment_ColorInfo são os seguintes:

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

• iComentário Especifica o valor MSODOCEXCOMMENT, msodocexcommentColorInfo.

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

• fForeColor Especifica se a ID de cor no membro clr representa uma cor de primeiro plano ou uma cor de fundo. Se esse membro tiver um valor verdadeiro, a ID de cor representará uma cor de primeiro plano. Se esse membro tiver um valor falso, a ID de cor representará uma cor de tela de fundo.

DocExComment_ColorEnable

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

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

Os membros da estrutura DocExComment_ColorEnable são os seguintes:

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

• iComentário Especifica o valor MSODOCEXCOMMENT, msodocexcomment ColorMapEnable.

• fEnable Especifica se o mapeamento de cores está habilitado para conteúdo subsequente. Um valor true indica que o mapeamento de cores está habilitado. Um valor falso indica que o mapeamento de cores está desabilitado.

DocExComment_BeginStructNode

A estrutura DocExComment_BeginStructNode marca o início de um nó de estrutura do documento. Os nós de estrutura servem a um de dois propósitos 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 outro conteúdo no documento.

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

Se o membro fContentNode tiver um valor true , o DocExComment_BeginStructNode será seguido posteriormente no documento por um DocExComment_EndStructNode. A DocExComment_EndStructNode marca o fim do conteúdo que é encapsulado pelas informações no DocExComment_BeginStructNode.

A coleção de nós de estrutura dentro do documento forma uma árvore; Cada nó tem um nó pai e também pode ter nós irmãos. Os membros idNodeParent e iSortOrder descrevem a estrutura dessa árvore. Observe que um nó filho pode ou não aparecer entre as estruturas DocExComment_BeginStructNode e DocExComment_EndStructNode do nó pai no EMF.

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

Os membros da estrutura DocExComment_BeginStructNode são os seguintes:

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

• iComentário Especifica o valor MSODOCEXCOMMENT, msodocexcommentBeginStructNode.

• idNodeParent Especifica a ID do nó pai. Um valor de 0 especifica o nó raiz. Um valor de -1 especifica o nó da estrutura aberta no momento, ou seja, o nó da estrutura delimitadora .

• iSortOrder Especifica a ordem de classificação do nó da estrutura entre seus nós irmãos. A ordem de classificação permite que o suplemento ordene o conteúdo corretamente no documento exportado.

  Dois nós não podem ter a mesma ordem de classificação. No entanto, o conjunto de inteiros que constituem a ordem de classificação não precisa ser contíguo.

  Um valor de -1 indica que a ordem irmã é a mesma ordem em que os nós aparecem nos comentários EMF. Observe que a ordem em que o conteúdo aparece no EMF não é necessariamente a ordem em que o conteúdo é consumido por um usuário do documento.

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

O membro idNode especifica o ID do nó. Esse membro pode não ter um valor de 0. Um valor de -1 indica que os nós filhos não usam o membro idNodeParent para especificar esse nó como pai. Em vez disso, esse nó pode ser pai apenas incluindo nós filhos no EMF. Vários nós podem ter uma ID de -1. Se a ID não for -1, o valor será exclusivo em todo o documento.

O tipo de nó especifica o tipo de nó de estrutura. Esse membro é igual a um dos valores do tipo de enumeração MSODOCEXSTRUCTTYPE . A tabela a seguir lista exemplos de tipos de nó de estrutura do documento.

Tabela 7. Tipos de nó da estrutura do documento

Valor do Tipo	Descrição
msodocexStructTypePara	Um bloco de texto dentro de um artigo. Seu nó pai deve ser um artigo.
msodocexStructTypeFigure	Um elemento gráfico (por exemplo, uma imagem ou um conjunto de formas) que tem uma representação textual. A representação textual é o texto alternativo usado para ler ou pesquisar o documento.
msodocexStructTypeArticle	Um grupo de nós formando um único fluxo de texto que deve ser lido ou pesquisado como um bloco contíguo de conteúdo. Alguns documentos têm um único artigo e outros têm vários artigos.
msodocexStructTypeHeading	Um título no texto.
msodocexStructTypeTable	Um bloco de texto formando uma tabela.
msodocexStructTypeTR	Um bloco de texto formando uma única linha de uma tabela.
msodocexStructTypeTD	Um bloco de texto que forma uma única célula em uma linha da tabela.
msodocexStructTypeTH	Um bloco de texto que forma uma única célula de cabeçalho em uma linha da tabela.
msodocexStructTypeList	Um bloco de texto formando uma lista.
msodocexStructTypeListItem	Um bloco de texto formando um item de lista.
msodocexStructTypeListBody	Um bloco de texto que forma o corpo de um item de lista.
msodocexStructTypeDocument	Um documento.
msodocexStructTypePage	Uma página no documento.
msodocexStructTypeTOC	Um sumário.
msodocexStructTypeTOCI	Um item em um sumário.
msodocexStructTypeExtLink	Um link para um recurso externo.
msodocexStructTypeIntLink	Um link para um recurso interno.
msodocexStructTypeFootnote	Um rodapé.
msodocexStructTypeEndnote	Uma nota de fim.
msodocexStructTypeTextbox	Uma caixa de texto.
msodocexStructTypeHeader	Um bloco de texto formando um cabeçalho.
msodocexStructTypeFooter	Um rodapé.
msodocexStructInlineShape	Uma forma embutida.
msodocexStructAnnotation	Uma anotação.
msodocexStructTypeSpanBlock	Um bloco de texto.
msodocexStructTypeWorkbook	Uma pasta de trabalho.
msodocexStructTypeWorksheet	Uma planilha.
msodocexStructTypeMacrosheet	Uma macroplanilha.
msodocexStructTypeChartsheet	Uma folha de gráfico.
msodocexStructTypeDialogsheet	Uma folha de diálogo.
msodocexStructTypeSlide	Um slide.
msodocexStructTypeChart	Um gráfico.
msodocexStructTypeDiagram	Um diagrama SmartArt.
msodocexStructTypeBulletText	Texto Buller.
msodocexStructTypeTextLine	Uma linha de texto.
msodocexStructTypeDropCap	Uma letra capitular.
msodocexStructTypeSection	Uma seção.
msodocexStructTypeAnnotationBegin	O início de uma anotação.
msodocexStructTypeAnnotationEnd	O final de uma anotação.
msodocexStructTypeParaRTLAttr	Um bloco de texto dentro de um artigo com layout da direita para a esquerda.
msodocexStructTypeTableRTLAttr	Um bloco de texto formando uma tabela com layout da direita para a esquerda.
msodocexStructTypeHeadingRTLAttr	Um título no texto com layout da direita para a esquerda.
msodocexStructTypeListItemRTLAttr	Um bloco de texto formando um item de lista com layout da direita para a esquerda.
msodocexStructTypeParaUnannotatableAttr	Um bloco de texto dentro de um artigo que não é anotável.
msodocexStructTypeTHead	A área da linha de cabeçalho em uma tabela.
msodocexStructTypeTBody	A área do corpo em uma tabela, ou seja, a parte entre o THead e o TFoot.
msodocexStructTypeLabel	Um rótulo.
msodocexStructTypeEquation	Uma equação.
msodocexStructTypeIntLinkNoteRef	Uma nota de rodapé ou um link de marca de referência de nota de fim.
msodocexStructTypeTFoot	A área da linha de rodapé em uma tabela.
msodocexStructTypeTitle	Um título no texto.
msodocexStructTypeBlockQuote	Uma citação de parágrafo ou uma citação intensa.
msodocexStructTypeCommentAnchor	Algum texto vinculado a um comentário.
msodocexStructTypeAnnot	Conteúdo de um único comentário.
msodocexStructTypeQuote	Uma aspas embutidas.
msodocexStructTypeCaption	Uma legenda para uma equação/figura/tabela.
msodocexStructTypeNotes	Um bloco de anotações, como uma associada a um slide. Versão mínima 18925.
msodocexStructTypeReference	Uma referência em um sumário. Versão mínima 18925.

Observação: msodocexStructTypeTitle, msodocexStructTypeBlockQuote, msodocexStructTypeCommentAnchor, msodocexStructTypeAnnot, msodocexStructTypeQuote e msodocexStructTypeCaption estão disponíveis no Word. Document.ExportAsFixedFormat3 é chamado com ImproveExportTagging = true. A versão mínima necessária é Microsoft 365 versão 2506.

fContentNode Especifica se uma estrutura DocExComment_EndStructNode marca o final desse nó de estrutura. Se fContentNode for true, uma estrutura DocExComment_EndStructNode fechará o conteúdo limitado pelo nó. Se esse fContentNode tiver um valor falso , o nó não vinculará nenhum conteúdo.

O membro fContentNode afeta a interpretação do valor da ID pai dos nós subsequentes. Se fContentNodefor true, os nós inseridos entre esse DocExComment_BeginStructNode e um DocExComment_EndStructNode subsequente e que tenham uma ID pai de -1 serão filhos desse nó. No entanto, se fContentNode for true, os nós inseridos após esse DocExComment_BeginStructNode e que têm uma ID pai de -1 não serão filhos desse nó. Eles são filhos do próximo nó especificado mais recentemente que tem fContentNode igual a false.

Você pode aninhar nós de estrutura de documento em profundidade arbitrária.

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

cwchMathMlText Especifica o número de caracteres Unicode no bloco de texto MathML que segue a estrutura. Essa cadeia de caracteres Unicode especifica o texto MathML para o nó. A versão mínima necessária é o Microsoft 365 versão 2601.

DocExComment_EndStructNode

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

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

Os membros da estrutura DocExComment_EndStructNode são os seguintes:

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

• iComentário 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 registros EMF de renderização de texto usem Unicode como representação de texto, outros usam os glifos desenhados na tela, em vez do texto original original. Um glifo é o índice de uma determinada forma na fonte, que pode ser diferente de fonte para fonte.

Pode haver casos em que vários pontos de código Unicode são combinados em um único glifo ou onde um único ponto de código Unicode é dividido em vários glifos. Como o mapeamento de pontos de código para glifos depende do contexto, um usuário não pode pesquisar por texto ou copiar/colar em um documento que contenha apenas glifos. Portanto, às 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:

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

• iComentário Especifica o valor MSODOCEXCOMMENT, msodocexcommentBeginTextRun.

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

• cGlyphIndex Especifica o tamanho de uma matriz que segue essa estrutura. Essa matriz implementa uma tabela de índice de glifos 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 usado para renderizar 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 resolvem para o mesmo glifo. O valor também pode ser 0, o que significa que esse ponto de código não é mapeado para nenhum glifo.

• cwchActualText Especifica o tamanho da sequência de pontos de código Unicode que seguem a tabela de índice de glifos. Esse é o texto que um consumidor do documento pode usar para pesquisar, copiar/colar e acessibilidade. O valor desse membro pode ser 0, o que significa que nenhum texto Unicode é fornecido.

DocExComment_EndTextRun

A estrutura DocExComment_EndTextRun marca o fim de uma sequência de texto, cujo 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:

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

• iComentário Especifica o valor MSODOCEXCOMMENT, msodocexcommentEndTextRun.

DocExComment_UnicodeForNextTextOut

A estrutura DocExComment_UnicodeForNextTextOut funciona de forma semelhante às estruturas DocExComment_BeginTextRun e DocExComment_EndTextRun . No entanto, DocExComment_UnicodeForNextTextOut especifica pontos de código Unicode apenas para o registro EMF TextOut a seguir, em vez de para um bloco de conteúdo EMF limitado por estruturas de início e término.

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

Os membros da estrutura DocExComment_UnicodeForNextTextOut são os seguintes:

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

• iComentário Especifica o valor MSODOCEXCOMMENT, msodocexcommentUnicodeForNextTextOut.

• cGlyphIndex Especifica o tamanho de uma matriz que segue essa estrutura. Essa matriz implementa uma tabela de índice de glifos 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 usado para renderizar 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 resolvem para o mesmo glifo.

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

DocExComment_EPSColor

A estrutura DocExComment_EPSColor especifica informações de cores para um arquivo PostScript encapsulado (EPS) incorporado no EMF. Para obter mais informações sobre essa estrutura, consulte a seção Suporte estendido a cores.

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

Os membros da estrutura DocExComment_EPSColor são os seguintes:

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

• iComentário Especifica o valor MSODOCEXCOMMENT, msodocexcommentEPSColor.

• colorInfo Especifica as informações de cor para o arquivo EPS. O suplemento deve passar essas informações para o Publisher usando 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 arquivo CMYKJPEG. Para obter mais informações sobre essa estrutura, consulte a seção Suporte estendido a cores.

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

Os membros da estrutura DocExComment_EPSColorCMYKJPEG são os seguintes:

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

• iComentário Especifica o valor MSODOCEXCOMMENT, msodocexcommentEPSCMYKJPEG;

DocExComment_EPSColorSpotImage

A estrutura DocExComment_EPSColorSpotImage fornece informações de cores especiais para a imagem RGB subsequente. Para obter mais informações sobre essa estrutura, consulte a seção Suporte estendido a cores.

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:

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

• iComentário Especifica o valor MSODOCEXCOMMENT, msodocexcommentEPSSpotImage.

• cmykAlt Especifica uma ID de cor CMYK.

• rgbAlt Especifica uma ID de cor RGB.

• flTintMin Especifica a tonalidade mínima.

• flTintMax Especifica a tonalidade máxima.

• szSpotName[1] Especifica uma cadeia de caracteres de comprimento variável, terminada em zero, que contém o nome do ponto.

Suporte Estendido a Cores

Para dar suporte a espaços de cores estendidos no Publisher, são necessários registros semânticos e interfaces EMF adicionais porque o EMF é compatível apenas com cores RGB (vermelho-verde-preto). Os espaços de cores estendidos incluem CMYK (ciano-magenta-amarelo-preto) e espaço de cores exatas, que são comumente usados em impressão comercial.

O Publisher usa o mapeamento de cores para representar cores estendidas no EMF do documento. O Publisher cria uma tabela de cores para todas as cores usadas no documento e substitui as cores reais por IDs de cor no EMF. O tipo da ID de cor é COLORREF, que é o mesmo tipo usado para cores RGB. Para obter informações sobre a estrutura COLORREF, consulte COLORREF.

Para resolver IDs de cor no EMF de volta para o espaço de cores estendido, o suplemento chama de volta para o Publisher por meio do método HrResolveColor da interface IMsoDocExporterSite. O suplemento passa ao Publisher um ponteiro de interface para uma interface IDOCEXCOLOR como um dos parâmetros para HrResolveColor. O Publisher usa as IDs de cor, também especificadas na chamada para HrResolveColor, converte-as em cores estendidas (RGB, CMYK ou cores especiais) e as passa de volta para o suplemento por meio dos métodos na interface IDOCEXCOLOR .

Cor vetorial e imagens recoloridas

Cores vetoriais são quaisquer valores COLORREF que o suplemento recebe do Publisher. Por exemplo, cor do texto, cor do traço de linha e cor para recolorir o metarquivo. Quando o mapeamento de cores está ativado, o Publisher usa uma ID de cor para COLORREF em vez de um valor de cor RGB real. Se o Publisher fornecer ao suplemento um ponteiro de interface IMsoDocExporterSite chamando o método SetDocExporterSite da interface IMsoDocExporter , o suplemento sempre deverá chamar o método IMsoDocExporterSite::HrResolveColor para converter o COLORREF em uma cor estendida, que o suplemento recebe por meio dos métodos na interface IDOCEXCOLOR .

Para dar suporte ao mapeamento de cores vetoriais, o suplemento precisa fazer o seguinte:

• Implemente o suporte de classe para uma interface IDOCEXCOLOR . Os métodos nessa interface permitem que o Publisher passe a cor estendida de volta para o suplemento.

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

• Defina a cor do primeiro plano para recoloração. Isso é definido por meio da estrutura DocExComment_ColorInfo .

• Defina a cor da tela de fundo para recoloração. Isso é definido por meio da estrutura DocExComment_ColorInfo .

• Determine quando o mapeamento de cores está habilitado. Isso é definido por meio da estrutura DocExComment_ColorEnable .

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

• Quando a cor do primeiro plano ou da tela de fundo para recoloração é especificada a partir de um registro semântico EMF, o suplemento deve recolorir as imagens do suplemento (por exemplo, metarquivos ou imagens rasterizadas).

Imagens não recoloridas

EMF suporta imagens CMYK usando GDI+. Portanto, as imagens no EMF podem ser RGB ou CMYK. Se a imagem for CMYK, o suplemento precisará convertê-la no espaço de cores de destino.

O Publisher mantém um espaço de cores de destino para o documento. O suplemento pode usar esse espaço de cores de destino chamando o método IMsoDocExporterSite::HrConvertImageColorSpace com o espaço de cores da imagem.

Cor dos Files EPS

O EPS (Postscript Encapsulado) é um tipo de metarquivo que oferece suporte a espaços de cores estendidos. O usuário que incorpora imagens EPS em um documento do Publisher espera que as informações de cor sejam usadas na saída de formato fixo. Dentro do Publisher, o EPS é convertido em um EMF com registros semânticos relacionados ao EPS. Esse EMF é então inserido no arquivo EMF de página que o aplicativo passa para o suplemento.

Para dar suporte a cores em arquivos EPS, o suplemento precisa fazer o seguinte:

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

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

• O registro DocExComment_EPSColorSpotImage fornece informações de cores especiais para a imagem RGB subsequente, que é sempre uma imagem índice. O suplemento precisa converter a imagem especial 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 do Publisher. Em seguida, o suplemento pode recolorir a imagem RGB subsequente mapeando cores da paleta da imagem RGB para as tonalidades flTintMin e flTintMax especificadas no registro DoxExComment_EPSColorSpotImage . A luminosidade de cada cor da paleta é usada para o mapeamento.

Observe que o registro DocExComment_EPSStart é apenas informativo. O suplemento pode ignorar esse registro.

SetDocExporterSite

O Publisher chama SetDocExporterSite para fornecer ao suplemento um ponteiro para uma interface IMsoDocExporterSite . A interface IMsoDocExporterSite expõe métodos que habilitam o suporte estendido a cores.

void SetDocExporterSite(
    IMsoDocExporterSite* pDocExporterSite
);

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

HrSetPageHeightForPagination

Um aplicativo pode chamar o método HrSetPageHeightForPagination para especificar a altura da página em pontos.

HRESULT HrSetPageHeightForPagination(
    float dytfPageHeight
);

Alguns aplicativos mantêm o documento do usuário em um formato não paginado. Nesses casos, o suplemento pagina o documento usando a altura da página especificada pelo aplicativo 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, o aplicativo passa o suplemento para todo o documento como um único arquivo EMF na memória em uma chamada para HrAddPageFromEmf. Em seguida, o suplemento usa a altura da página e o arquivo EMF para paginar o documento.

O suplemento retorna as informações de paginação de volta para o aplicativo em chamadas subsequentes para o método HrGetPageBreaks .

HrGetPageBreaks

Um aplicativo pode chamar o método HrGetPageBreaks para obter o número e o local das quebras de página para documentos paginados pelo suplemento.

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

Depois que o suplemento pagina um documento usando a altura da página especificada pelo método HrSetPageHeightForPagination , ele retorna as informações de paginação em chamadas subsequentes que o aplicativo faz para o método HrGetPageBreaks .

O parâmetro rgdytfPageBreaks é um ponteiro para uma matriz de valores flutuantes que especificam os locais das quebras de página em pontos. O primeiro elemento na matriz (índice 0) é o local da primeira quebra de página, o segundo elemento é o local da segunda quebra de página e assim por diante. Portanto, os valores desses elementos estão aumentando 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 o local da última quebra de página é o final do documento ou o início da última página do documento. Um valor verdadeiro indica que a última quebra de página é o final do documento.

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

HrGetPageBreaks(NULL, &nPageBreaks, NULL);

Em seguida, o aplicativo chama HrGetPageBreaks uma segunda vez para obter os locais reais. Na segunda chamada, o aplicativo passa um buffer de tamanho suficiente para manter a matriz de locais de quebra de página.

HrGetPageBreaks(rgPageBreaks, &nPageBreaks, fCanStopAtLastPageBreak);

Depois de receber as informações de quebra de página do suplemento, o aplicativo reinicia o processo de exportação de formato fixo, começando com uma chamada para o método HrCreateDoc , seguido por 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 ao suplemento uma estrutura que descreve um nó em uma estrutura de tópicos navegável pelo usuário para o documento exportado.

HRESULT HrAddOutlineNode(
    int idNodeParent 
    const MSODOCEXOUTLINENODE* pNode
);    

O código de exportação de formato fixo pode usar as informações passadas pelo método HrAddOutlineNode para construir uma estrutura de tópicos navegável pelo usuário do documento de exportação. Da perspectiva do usuário, cada nó na estrutura de tópicos é representado por um texto de título que mapeia para um local específico no documento.

Cada chamada para HrAddOutlineNode especifica informações para um único nó nesta estrutura de tópicos. Cada nó é identificado por uma ID de nó que é exclusiva dentro da estrutura de tópicos. Um ID de 0 é reservado para o nó raiz. O contorno é hierárquico, ou seja, possui uma estrutura de árvore na qual cada nó possui um único pai e zero ou mais nós filhos.

O primeiro parâmetro para HrAddOutlineNode fornece a ID do nó que é o pai do nó que está sendo passado.

O Publisher sempre chama HrAddOutlineNode para um nó pai antes de chamar o método para qualquer um dos filhos do nó pai. Em outras palavras, o código de exportação tem a garantia 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 essa chamada, o valor de idNodeParent é 0.

As informações adicionais de que o código de exportação precisa para cada nó são passadas por HrAddOutlineNode em uma 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 nó MSODOCEXOUTLINESÃO descritos da seguinte forma:

• idNode A ID do nó. Um valor de -1 indica que esse nó não pode ter nós filhos no contorno. Caso contrário, esse membro terá um valor exclusivo em todo o documento.

• rgwchNodeText Uma cadeia de caracteres Unicode que representa o texto do título para cada nó. Esse texto não precisa ser exclusivo em toda a estrutura de tópicos.

• iDestPage O número da página que contém o local de destino dentro do documento.

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

• dxtfvDestOffset O deslocamento horizontal do local de destino na página de destino.

• dytfvDestOffset O deslocamento vertical do local de destino na página de destino.

HrAddDocumentMetadataString

O Publisher chama o método HrAddDocumentMetadataString para especificar metadados de documento na forma de uma cadeia de caracteres Unicode.

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

O parâmetro metadatatype especifica o tipo de metadados representado pela cadeia de caracteres. O parâmetro metadatatype deve ser um dos seguintes valores do tipo de enumeração MSODOCEXMETADATA.

Tabela 8. Valores enumerados de MSODOCEXMETADATA

Valor	Descrição
msodocexMetadataTitle	O título do documento.
msodocexMetadataAuthor	O autor do documento
msodocexMetadataSubject	Cadeia de caracteres que descreve o assunto do documento (por exemplo, negócios ou ciências).
msodocexMetadataKeywords	Palavra-chave relevante para o conteúdo do documento.
msodocexMetadataCreator	O criador do documento, possivelmente distinto do autor.
msodocexMetadataProducer	O produtor do documento, possivelmente distinto do autor ou criador.
msodocexMetadataCategory	Cadeia de caracteres que descreve o tipo de documento (por exemplo, memorando, artigo ou livro).
msodocexMetadataStatus	Status do documento. Esse campo pode refletir onde o documento está no processo de publicação (por exemplo, rascunho ou final).
msodocexMetadataComments	Comentários diversos relevantes para o documento.

Para um determinado documento, cada tipo de metadados pode ter apenas uma cadeia de caracteres associada a ele. Assim, por exemplo, se o documento tiver várias palavras-chave, elas serão passadas para o suplemento como uma cadeia de caracteres concatenada.

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

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

HrAddDocumentMetadataDate

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

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

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

Tabela 9. Valores enumerados de MSODOCEXMETADATA

Valor	Descrição
msodocexMetadataCreationDate	A data de criação do documento.
msodocexMetadataModDate	A data da última modificação do documento.

O parâmetro pftLocalTime especifica um ponteiro para uma estrutura FILETIME que contém as informações de data e hora para os metadados. O trecho de código a seguir demonstra como extrair essas 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 maneira 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 usado no documento exportado.

HrFinalize

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

HRESULT HrFinalize();

O código que implementa a exportação de formato fixo deve usar HrFinalize para executar tarefas como liberar buffers de dados, gravar dados restantes em disco e liberar memória e outros recursos.

Conclusão

Você pode estender o recurso de exportação de formato fixo dos aplicativos do Office implementando a interface IMsoDocExporter . Os métodos dessa interface fornecem um canal para que os aplicativos do Office se comuniquem com o suplemento o conteúdo visual e as informações semânticas no documento a ser exportado. O conteúdo visual do documento é fornecido ao suplemento como um ou mais metarquivos aprimorados na memória. As informações semânticas são fornecidas como registros de comentários especialmente formatados dentro deste EMF. Métodos adicionais na interface permitem que os aplicativos 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