Modifications basées sur les événements de page XPS.NET

Quelle est l’approche événementielle en programmation ?

L’approche événementielle en programmation est un paradigme qui s’articule autour du concept d’événements et de leur gestion. Dans ce modèle, le flux du programme est déterminé par des événements, qui peuvent être des actions de l’utilisateur (comme des clics de souris ou des pressions sur des touches), des notifications générées par le système ou des messages provenant d’autres applications. Voici quelques aspects clés de l’approche événementielle :

• Événements : les événements représentent des occurrences significatives dans un programme. Ceux-ci peuvent inclure des interactions utilisateur, des modifications de données ou des messages provenant d’autres parties d’un système. Par exemple, un clic sur un bouton ou un fichier en cours de chargement peut déclencher des événements.

• Écouteurs d’événements : pour répondre aux événements, les programmeurs utilisent des écouteurs d’événements (ou gestionnaires). Il s’agit de fonctions ou de méthodes définies pour s’exécuter lorsqu’un événement spécifique se produit. Par exemple, un écouteur d’événements peut être configuré pour exécuter une fonction lorsqu’un utilisateur clique sur un bouton.

• Exécution asynchrone : le modèle basé sur les événements prend souvent en charge la programmation asynchrone, permettant aux programmes de rester réactifs en attendant que les événements se produisent. Par exemple, une application Web peut continuer à fonctionner en attendant les données d’un serveur.

• Découplage : L’approche basée sur les événements favorise le découplage entre les différentes parties d’un programme. Les composants peuvent communiquer via des événements sans avoir besoin de connaître les détails de l’implémentation de chacun, ce qui rend le code plus modulaire et plus facile à maintenir.

• Cas d’utilisation courants : la programmation basée sur les événements est largement utilisée dans les interfaces utilisateur graphiques (GUI), les applications Web et les systèmes qui nécessitent des interactions en temps réel. Les frameworks et bibliothèques comme Node.js, React et bien d’autres utilisent des modèles basés sur les événements.

• Gestion de l’état : dans un système piloté par événements, la gestion de l’état peut être cruciale puisque l’application peut se trouver dans différents états en fonction des interactions ou des événements de l’utilisateur. Des stratégies de gestion d’état appropriées sont souvent utilisées pour garantir que l’application se comporte comme prévu.

Dans l’ensemble, l’approche basée sur les événements constitue un moyen puissant de gérer les interactions et les flux de travail au sein d’un programme, ce qui la rend particulièrement efficace pour les applications nécessitant réactivité et interaction de l’utilisateur.

Événements qui se produisent lors de la conversion du document XPS

Lorsque vous devez apporter des modifications à une page spécifique d’un document XPS à l’aide de l’API Aspose.Page, vous sélectionnez généralement le document actif (s’il existe plusieurs documents dans le fichier XPS), sélectionnez la page active, puis effectuez les modifications vous-même. .

Supposons maintenant que vous deviez apporter des modifications répétitives à toutes les pages d’un fichier XPS, puis convertir le résultat au format PDF ou au format image. Quelques exemples de tels changements incluent le placement d’un filigrane sur les pages ou l’ajout d’hyperliens de navigation. La manière directe d’effectuer de telles modifications consiste à parcourir les documents du package XPS, à parcourir les pages du document actif actuel, puis, enfin, à appliquer vos modifications. Par conséquent, le code pour accomplir cette tâche ressemblerait à ceci :

for (int i = 1; i <= document.DocumentCount; i++)
{
    document.SelectActiveDocument(i);
    for (j = 1; j <= document.PageCount; j++)
    {
        document.SelectActivePage(j);
        // Your changes ...
    }
}
document.SaveAsPdf("file-name.pdf", saveOptions);

Si vous devez également effectuer des modifications irrégulières avant les modifications répétées, cette approche peut entraîner une certaine confusion ou des parcours excessifs à travers les documents et les pages, sans parler de ces boucles qui peuvent sembler un peu lourdes.

Lorsque vous convertissez un document XPS en PDF ou en image, le processus se déroule page par page. Lorsque la tâche de conversion est prête à traiter la page suivante, elle déclenche un événement « avant la page ». L’utilisateur peut définir la gestion de tels événements en étendant la classe BeforePageSavingEventHandler, profitant ainsi de certains avantages décrits dans la section d’introduction de cet article.

Exemple d’ajout d’hyperliens de navigation

Nous fournirons ici un exemple lié au cas des hyperliens de navigation. Et pour rendre la tâche un peu plus compliquée, nous allons convertir uniquement un sous-ensemble de toutes les pages en PDF, comme spécifié par la propriété « PdfSaveOptions.PageNumbers ».

La classe du gestionnaire d’événements

Ci-dessous se trouve l’extension de la classe BeforePageSavingEventHandler :

/// <summary>
/// The class to handle the before-page event while converting an XPS document.
/// </summary>
public class NavigationInjector : BeforePageSavingEventHandler
{
    // The font in which navigation hyperlinks and page numbers will be displayed.
    private readonly XpsFont _font;
    // The page numbers to convert.
    private readonly SortedList<int, int> _pageNumbers;

    public NavigationInjector(XpsFont font, int[] pageNumbers)
    {
        _font = font;
        if (pageNumbers == null)
            return;

        // Turn the page number array into a sorted collection of unique values.
        _pageNumbers = new SortedList<int, int>();
        foreach (int pn in pageNumbers)
            _pageNumbers[pn] = 0;
    }

    public override void Handle(BeforeSavingEventArgs<PageAPI> args)
    {
        PageAPI api = args.ElementAPI;

        XpsGlyphs glyphs;
        // For all pages in the output PDF except the first one...
        if (args.OutputPageNumber > 1)
        {
            // ...insert a hyperlink to the first page...
            glyphs = api.CreateGlyphs(_font, 15f, 5f, api.Height - 10f, "[First]");
            glyphs.Fill = api.CreateSolidColorBrush(Color.Blue);
            glyphs.HyperlinkTarget = new XpsPageLinkTarget(_pageNumbers == null ? 1 : _pageNumbers.Keys[0]);
            api.Add(glyphs);

            // ...and to the previous page.
            glyphs = api.CreateGlyphs(_font, 15f, 60f, api.Height - 10f, "[Prev]");
            glyphs.Fill = api.CreateSolidColorBrush(Color.Blue);
            glyphs.HyperlinkTarget = new XpsPageLinkTarget(
                _pageNumbers == null ? args.AbsolutePageNumber - 1 : _pageNumbers.Keys[args.OutputPageNumber - 2]);
            api.Add(glyphs);
        }

        // For all pages in the output PDF except the last one...
        if ((_pageNumbers != null && args.OutputPageNumber < _pageNumbers.Count) ||
            (_pageNumbers == null && args.OutputPageNumber < api.TotalPageCount))
        {
            // ...insert a hyperlink to the next page...
            glyphs = api.CreateGlyphs(_font, 15f, 110f, api.Height - 10f, "[Next]");
            glyphs.Fill = api.CreateSolidColorBrush(Color.Blue);
            glyphs.HyperlinkTarget = new XpsPageLinkTarget(
                _pageNumbers == null ? args.AbsolutePageNumber + 1 : _pageNumbers.Keys[args.OutputPageNumber]);
            api.Add(glyphs);

            // ...and to the last page.
            glyphs = api.CreateGlyphs(_font, 15f, 160f, api.Height - 10f, "[Last]");
            glyphs.Fill = api.CreateSolidColorBrush(Color.Blue);
            glyphs.HyperlinkTarget = new XpsPageLinkTarget(
                _pageNumbers == null ? api.TotalPageCount : _pageNumbers.Keys[_pageNumbers.Keys.Count - 1]);
            api.Add(glyphs);
        }

        // Insert a page number in the bottom-right corner.
        glyphs = api.CreateGlyphs(_font, 15f, api.Width - 20f, api.Height - 10f, args.OutputPageNumber.ToString());
        glyphs.Fill = api.CreateSolidColorBrush(Color.Black);
        api.Add(glyphs);

        // Add an outline entry to display the links to the converted pages in the navigation pane of a PDF viewer.
        api.AddOutlineEntry(string.Format("Page {0}", args.OutputPageNumber), 1, args.AbsolutePageNumber);
    }
}

La classe de gestionnaire doit connaître les pages que nous souhaitons enregistrer au format PDF afin de créer les cibles de lien hypertexte correctes. Par conséquent, le constructeur doit prendre la propriété array des options comme argument. Si le tableau de numéros de page est spécifié, nous créons une collection triée de ceux-ci, en évitant en même temps les doublons. (Soit dit en passant, cette solution n’est pas tout à fait exacte. Pouvez-vous comprendre ce qui pourrait provoquer une incohérence dans la sortie ?) Nous aurons également besoin d’un objet « XpsFont » contenant les données de police pour le texte du lien hypertexte.

La méthode Handle() remplacée est l’endroit où tout se passe. L’argument de la méthode est un objet qui contient l’API de modification pour la page actuelle, le numéro du document dans le package XPS, le numéro de page absolu dans tous les documents, le numéro de page relatif dans le document actuel (qui est égal au numéro précédent dans le cas d’un seul document dans le package), et le numéro de page de sortie (qui est égal au numéro de page absolu lorsque nous convertissons l’ensemble du package).

La logique des deux blocs « if » suivants est assez simple. Il est basé sur l’analyse de l’argument de l’événement OutputPageNumber pour omettre certains liens le cas échéant : les liens [First] et [Prev] seront ajoutés à toutes les pages de sortie sauf la première, tandis que le Les liens [Suivant] et [Dernier] apparaîtront sur toutes les pages sauf la dernière. La logique est également adaptée aux deux cas, que les numéros de page soient spécifiés ou non.

Après les blocs « if », il y a un code pour ajouter un numéro de page dans le coin inférieur droit de la page.

La dernière ligne ajoute l’entrée de plan de la page, l’élément qui sera affiché dans le volet de navigation d’une visionneuse PDF (si pris en charge).

Le code de conversion

Maintenant que le gestionnaire d’événements “avant la page” est défini, nous pouvons écrire le code qui convertit le document :

// The path to the documents directory.
string dataDir = RunExamples.GetDataDir_WorkingWithPages();
// Open an XPS document
using (XpsDocument doc = new XpsDocument(dataDir + "Sample3.xps"))
// Create a font
using (Stream fontStream = File.OpenRead(dataDir + "arialbd.ttf"))
{
    // Create options for conversion to PDF
    PdfSaveOptions options = new PdfSaveOptions();
    // Set the filter for the pages that need conversion
    options.PageNumbers = new int[] { 2, 6, 7, 13 };
    // Add the event handler that will execute right before the conversion of each page
    options.BeforePageSavingEventHandlers.Add(new NavigationInjector(doc.CreateFont(fontStream), options.PageNumbers));
    // Save resultant XPS document
    doc.SaveAsPdf(dataDir + "ModifyPageOnConversion_out.pdf", options);
}

Nous ouvrons un fichier XPS puis instancions un objet flux avec le fichier de données de police. Ensuite, nous créons une instance de la classe PdfSaveOptions et spécifions le nombre de pages que nous devons convertir. La ligne suivante est l’endroit où le gestionnaire d’événements “page avant” devient “connecté” au travail de conversion via l’option de collection BeforePageSavingEventHandlers.

Il ne reste plus qu’à exécuter la conversion en PDF en utilisant la méthode SaveAsPdf() du document.

Conclusion

Dans cet article, nous avons exploré les points clés de l’approche basée sur les événements en programmation, examiné la méthode directe de modification des pages d’un document XPS et appris une technique plus avancée et sophistiquée pour apporter des modifications répétitives à toutes les pages de sortie au cours du processus. processus de conversion, en utilisant l’insertion d’hyperliens de navigation comme exemple.

Pour les exemples complets, explorez notre Exemple de projet.