Como trabalhar com comentários

Este tópico discute o Open XML SDK para a classe Office Comment e como ele se relaciona com o esquema PresentationML do Open XML File Format. Para obter mais informações sobre a estrutura geral das partes e elementos que compõem um documento PresentationML, consulte Estrutura de um documento PresentationML.

Comentários em PresentationML

A ISO /IEC 29500 descreve a seção Comentários da estrutura Open XML PresentationML da seguinte forma:

Um comentário é uma anotação de texto anexada a um slide, com o objetivo principal de permitir que os leitores de uma apresentação forneçam comentários ao autor da apresentação. Cada comentário contém uma cadeia de caracteres de texto não formatada e informações sobre seu autor e é anexado a um local específico em um slide. Os comentários podem ficar visíveis durante a edição da apresentação, mas não aparecem quando uma apresentação de slides é apresentada. O aplicativo de exibição decide quando exibir comentários e determina sua aparência visual.

A especificação ISO/IEC 29500 descreve o elemento Open XML PresentationML <cm/> usado para representar comentários em um documento PresentationML da seguinte maneira:

Esse elemento especifica um único comentário anexado a um slide. Ele contém o texto do comentário, sua posição no slide e atributos referentes ao autor e à data.

Exemplo:

<p:cm authorId="0" dt="2006-08-28T17:26:44.129" idx="1">  
   <p:pos x="10" y="10"/>  
   <p:text\>Add diagram to clarify.</p:text>  
</p:cm>

A tabela a seguir lista os elementos filho do <cm/> elemento usado ao trabalhar com comentários e as classes Open XML SDK que correspondem a eles.

A tabela a seguir da especificação ISO/IEC 29500 descreve os atributos do <cm/> elemento.

Classe de Comentário do Open XML SDK

A classe OXML SDK Comment representa o <cm/> elemento definido no esquema Open XML File Format para documentos PresentationML. Use a Comment classe para manipular elementos individuais <cm/> em um documento PresentationML.

As classes que representam elementos filho do <cm/> elemento e que, portanto, são comumente associados à Comment classe são mostradas na lista a seguir.

Classe ExtensionListWithModification

A ExtensionListWithModification classe corresponde ao <extLst/>elemento. As seguintes informações da especificação ISO/IEC 29500 introduzem o <extLst/> elemento:

Este elemento especifica a lista de extensões com capacidade de modificação dentro da qual todas as extensões futuras do tipo <ext/> de elemento são definidas. A lista de extensão, juntamente com as extensões futuras correspondentes, é usada para estender os recursos de armazenamento da estrutura PresentationML. Isso permite que vários novos tipos de dados sejam armazenados nativamente na estrutura.

Position Class

A Position classe corresponde ao <pos/>elemento. As seguintes informações da especificação ISO/IEC 29500 introduzem o <pos/> elemento:

Este elemento especifica as informações de posicionamento para o posicionamento de um comentário em uma superfície de slide. Nas versões LTR do aplicativo gerador, essas informações de posição devem se referir ao ponto superior esquerdo da forma de comentário. Nas versões RTL do aplicativo gerador, essas informações de posição devem se referir ao ponto superior direito da forma de comentário.

[Nota: O ponto de ancoragem na superfície do slide não é afetado por uma alteração de layout da direita para a esquerda ou da esquerda para a direita. Ou seja, o ponto de ancoragem permanece o mesmo para todas as versões de idioma. nota final]

[Observação: como não há tamanho ou formatação especificados para comentários, esse widget de interface do usuário usado para exibir um comentário pode ter qualquer tamanho e, portanto, o ponto inferior direito da forma do comentário é determinado pela forma como o aplicativo de visualização escolhe exibir comentários. nota final]

[Exemplo: <p:pos x="1426" y="660"/> exemplo final]

Classe de texto

A Text classe corresponde ao <text/> elemento. As seguintes informações da especificação ISO/IEC 29500 introduzem o <text/> elemento:

Esse elemento especifica o conteúdo de um comentário. Este é o texto com o qual o autor anotou o slide.

Os valores possíveis para esse elemento são definidos pelo tipo de dados Esquema string XML do W3C.

Trabalhando com a Classe Comment

Um comentário é uma anotação de texto anexada a um slide, com o objetivo principal de permitir que os leitores de uma apresentação forneçam comentários ao autor da apresentação. Cada comentário contém uma cadeia de caracteres de texto não formatada e informações sobre seu autor e é anexado a um local específico em um slide. Os comentários podem ficar visíveis durante a edição da apresentação, mas não aparecem quando uma apresentação de slides é apresentada. O aplicativo de exibição decide quando exibir comentários e determina sua aparência visual.

Conforme mostrado no exemplo de código do Open XML SDK a seguir, cada instância da Comment classe está associada a uma instância da classe, que representa uma parte de comentários de slide, uma das partes de um pacote de arquivos de apresentação PresentationML e uma parte que é necessária para cada slide em um arquivo de SlideCommentsPart apresentação que contém comentários. Cada Comment instância de classe também está associada a uma instância da classe, que por sua vez está associada a uma parte de CommentAuthor apresentação com nome semelhante, representada pela CommentAuthorsPart classe. Os autores de comentários de uma apresentação são especificados em uma lista de autores de comentários, representada pela classe, enquanto os CommentAuthorList comentários de cada slide são listados em uma lista de comentários desse slide, representada pela CommentList classe.

A Comment classe, que representa o <cm/> elemento, também está, portanto, associada a outras classes que representam os elementos filho do <cm/> elemento. Entre essas classes, conforme mostrado no exemplo de código a seguir, estão a Position classe, que especifica a posição do comentário em relação ao slide, e a Text classe, que especifica o conteúdo de texto do comentário.

Exemplo de código do Open XML SDK

O seguinte segmento de código do artigo Como adicionar um comentário a um slide em uma apresentação adiciona uma nova parte comentários a um slide existente em uma apresentação (se o slide ainda não contiver comentários) e cria uma instância de uma classe Open XML SDK Comment na parte de comentários do slide. Ele também adiciona uma lista de comentários à parte de comentários criando uma instância da CommentList classe, se ainda não existir; atribui uma ID ao comentário; e, em seguida, adiciona um comentário à lista de comentários criando uma instância da Comment classe, atribuindo os valores de atributo necessários. Além disso, ele cria instâncias das classes e Text associadas à nova Comment instância de Position classe. Para obter o exemplo de código completo, consulte o artigo mencionado anteriormente.

    <?xml version="1.0" encoding="utf-8"?>
    <p:cmAuthorLst xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main">
      <p:cmAuthor id="1"
                  name="userName"
                  initials="userInitials"
                  lastIdx="1"
                  clrIdx="0" />
    </p:cmAuthorLst>

    <?xml version="1.0" encoding="utf-8"?>
    <p:cmLst xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main">
      <p:cm authorId="1"
            dt="2010-09-07T16:01:18.5351166-07:00"
            idx="1">
        <p:pos x="100"
               y="200" />
        <p:text>commentText</p:text>
      </p:cm>
    </p:cmLst>