Utilisation des commentaires
Cette rubrique décrit la classe Comment du Kit de développement logiciel (SDK) Open XML pour Office et comment elle est liée au schéma PresentationML au format de fichier Open XML. Pour plus d’informations sur la structure complète des composants et des éléments qui constituent un document PresentationML, voir Structure d’un document PresentationML.
Commentaires en PresentationML
La spécification ISO/IEC 29500 décrit la section Commentaires de l’infrastructure PresentationML Open XML comme suit :
Un commentaire est une note textuelle rattachée à une diapositive, ayant comme objectif principal de permettre aux lecteurs d’une présentation de fournir des commentaires à l’auteur de la présentation. Chaque commentaire contient une chaîne de texte non mise en forme et des informations sur son auteur, et elle est rattachée à un emplacement particulier sur une diapositive. Les commentaires peuvent être visibles lors de la modification de la présentation, mais ils n’apparaissent pas lors de l’exécution d’un diaporama. L’application d’affichage décide du moment où afficher les commentaires et détermine leur apparence visuelle.
La spécification ISO/IEC 29500 décrit l’élément Open XML PresentationML <cm> utilisé pour représenter les commentaires dans un document PresentationML comme suit :
Cet élément spécifie un seul commentaire lié à une diapositive. Il contient le texte du commentaire, son emplacement sur la diapositive, ainsi que les attributs qui font référence à son auteur et à sa date de création.
Exemple :
<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>
Le tableau suivant répertorie les éléments enfants de l’élément cm > utilisé lors de l’utilisation <des commentaires et les classes du Kit de développement logiciel (SDK) Open XML qui leur correspondent.
| Élément PresentationML | Classe du Kit de développement logiciel (SDK) Open XML |
|---|---|
| <extLst> | Extensionlistwithmodification |
| <Pos> | Position |
| <Texte> | Texte |
Le tableau suivant de la spécification ISO/IEC 29500 décrit les attributs de l’élément <cm> .
| Attributs | Description |
|---|---|
| authorId | Cet attribut spécifie l’auteur du commentaire. Il fait référence à l’ID d’un auteur dans la liste des auteurs de commentaires pour le document. Les valeurs possibles de cet attribut sont définies par le type de données unsignedInt du schéma XML du W3C. |
| Dt | Cet attribut spécifie la date et l’heure auxquelles ce commentaire a été modifié pour la dernière fois. Les valeurs possibles de cet attribut sont définies par le type de données datetime du schéma XML du W3C. |
| Idx | Cet attribut spécifie un identificateur pour ce commentaire, qui est unique dans la liste de tous les commentaires de cet auteur au sein de ce document. Le premier commentaire d’un auteur a le numéro d’index 1. Remarque : Étant donné que l’index est unique uniquement pour l’auteur du commentaire, un document peut contenir plusieurs commentaires avec le même index créé par différents auteurs. Les valeurs possibles de cet attribut sont définies par le type simple ST_Index (§19.7.3). |
Classe de commentaires du Kit de développement logiciel (SDK) Open XML
La classe Comment du Kit de développement logiciel (SDK) OXML représente l’élément <cm> défini dans le schéma de format de fichier Open XML pour les documents PresentationML. Utilisez la classe Comment pour manipuler des éléments cm> individuels <dans un document PresentationML.
Les classes qui représentent des éléments enfants de l’élément <cm> et qui sont donc couramment associées à la classe Comment sont affichées dans la liste suivante.
Classe ExtensionListWithModification
La classe ExtensionListWithModification correspond à l’élément <extLst>. Les informations suivantes de la spécification ISO/IEC 29500 introduisent l’élément <extLst> :
Cet élément spécifie la liste d’extensions avec possibilité de modification dans laquelle toutes les extensions futures de type <d’élément ext> sont définies. La liste des extensions et les extensions futures correspondantes sont utilisées pour étendre les possibilités de stockage de l’infrastructure PresentationML. Ceci permet à différents nouveaux types de données d’être stockés en mode natif dans l’infrastructure.
Remarque
L’utilisation de cet élément extLst permet à l’application de génération de stocker si cette propriété d’extension a été modifiée. note de fin
Classe Position
La classe Position correspond à l’élément <pos>. Les informations suivantes de la spécification ISO/IEC 29500 introduisent l’élément <pos> :
Cet élément spécifie les informations de positionnement pour le placement d’un commentaire sur une diapositive. Dans les versions de gauche à droite (GàD) de l’application de génération, ces informations de positionnement doivent faire référence au point supérieur gauche de la forme du commentaire. Dans les versions de droite à gauche (DàG) de l’application de génération, ces informations de positionnement doivent faire référence au point supérieur droit de la forme du commentaire.
[Remarque : le point d’ancrage sur la diapositive n’est pas affecté par une modification de la mise en page de droite à gauche ou de gauche à droite. En d’autres termes, le point d’ancrage reste identique pour toutes les versions linguistiques. Fin de la remarque]
[Remarque : dans la mesure où il n’existe pas de taille ou de mise en forme spécifique pour les commentaires, ce widget d’interface utilisateur pour l’affichage d’un commentaire peut avoir n’importe quelle taille ; par conséquent, le point inférieur droit de la forme du commentaire dépend de la façon dont l’application de visualisation choisit d’afficher les commentaires. Fin de la remarque]
[Exemple : <p :pos x="1426 » y="660"/> end example]
Classe Text
La classe Text correspond à l’élément <text>. Les informations suivantes de la spécification ISO/IEC 29500 présentent l’élément <text> :
Cet élément spécifie le contenu d’un commentaire. Il s’agit du texte avec lequel l’auteur a annoté la diapositive.
Les valeurs possibles de cet élément sont définies par le type de données string du schéma XML du W3C.
Utilisation de la classe Comment
Un commentaire est une note textuelle rattachée à une diapositive, ayant comme objectif principal de permettre aux lecteurs d’une présentation de fournir des commentaires à l’auteur de la présentation. Chaque commentaire contient une chaîne de texte non mise en forme et des informations sur son auteur, et elle est rattachée à un emplacement particulier sur une diapositive. Les commentaires peuvent être visibles lors de la modification de la présentation, mais ils n’apparaissent pas lors de l’exécution d’un diaporama. L’application d’affichage décide du moment où afficher les commentaires et détermine leur apparence visuelle.
Comme indiqué dans l’exemple de code du Kit de développement logiciel (SDK) Open XML qui suit, chaque instance de la classe Comment est associée à un instance de la classe SlideCommentsPart, qui représente un composant de commentaires de diapositive, l’une des parties d’un package de fichier de présentation PresentationML et un composant requis pour chaque diapositive d’un fichier de présentation contenant des commentaires. Chaque classe Comment instance est également associée à un instance de la classe CommentAuthor, qui est à son tour associée à une partie de présentation nommée de même nom, représentée par la classe CommentAuthorsPart. Les auteurs de commentaires pour une présentation sont spécifiés dans une liste d’auteurs de commentaires, représentée par la classe CommentAuthorList , tandis que les commentaires de chaque diapositive sont répertoriés dans une liste de commentaires pour cette diapositive, représentée par la classe CommentList .
La classe Comment , qui représente l’élément <cm> , est donc également associée à d’autres classes qui représentent les éléments enfants de l’élément <cm> . Parmi ces classes, comme illustré dans l’exemple de code suivant, se trouve la classe Position, qui spécifie l’emplacement du commentaire par rapport à la diapositive, ainsi que la classe Text, qui spécifie le contenu textuel du commentaire.
Exemple de code du Kit de développement logiciel (SDK) Open XML
Le segment de code suivant de l’article Guide pratique pour ajouter un commentaire à une diapositive d’une présentation ajoute un nouveau composant commentaires à une diapositive existante dans une présentation (si la diapositive ne contient pas déjà de commentaires) et crée un instance d’une classe Comment du Kit de développement logiciel (SDK) Open XML dans le composant commentaires des diapositives. Il ajoute également une liste de commentaires à la partie commentaires en créant un instance de la classe CommentList, s’il n’en existe pas déjà une ; affecte un ID au commentaire ; puis ajoute un commentaire à la liste de commentaires en créant un instance de la classe Comment, en affectant les valeurs d’attribut requises. En outre, il crée des instances des classes Position et Text associées à la nouvelle classe Comment instance. Pour obtenir l’exemple de code complet, consultez l’article ci-dessus.
// Declare a comments part.
SlideCommentsPart commentsPart;
// Verify that there is a comments part in the first slide part.
if (slidePart1.GetPartsOfType<SlideCommentsPart>().Count() == 0)
{
// If not, add a new comments part.
commentsPart = slidePart1.AddNewPart<SlideCommentsPart>();
}
else
{
// Else, use the first comments part in the slide part.
commentsPart = slidePart1.GetPartsOfType<SlideCommentsPart>().First();
}
// If the comment list does not exist.
if (commentsPart.CommentList is null)
{
// Add a new comments list.
commentsPart.CommentList = new CommentList();
}
// Get the new comment ID.
uint commentIdx = author.LastIndex is null ? 1 : author.LastIndex + 1;
author.LastIndex = commentIdx;
// Add a new comment.
Comment comment = commentsPart.CommentList.AppendChild<Comment>(
new Comment()
{
AuthorId = authorId,
Index = commentIdx,
DateTime = DateTime.Now
});
// Add the position child node to the comment element.
comment.Append(
new Position() { X = 100, Y = 200 },
new Text() { Text = text });