Skip to content

Commit 5cd75d0

Browse files
boriskatinboriskatin
committed
Document OnFontSubstituted conversion event
1 parent b2b9cea commit 5cd75d0

3 files changed

Lines changed: 153 additions & 6 deletions

File tree

‎net/developer-guide/advanced-usage/conversion-events.md‎

Lines changed: 105 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ title: Conversion events
55
linkTitle: Conversion events
66
weight: 4
77
description: "Subscribe to pipeline lifecycle and per-result conversion events through the typed ConversionEvents aggregator in GroupDocs.Conversion for .NET."
8-
keywords: ConversionEvents, OnConversionStarted, OnConversionProgress, OnConversionCompleted, OnDocumentConverted, OnDocumentFailed, OnPageConverted, OnPageFailed, OnCompressionCompleted, WithEvents, conversion lifecycle, event handlers
8+
keywords: ConversionEvents, OnConversionStarted, OnConversionProgress, OnConversionCompleted, OnDocumentConverted, OnDocumentFailed, OnPageConverted, OnPageFailed, OnCompressionCompleted, OnFontSubstituted, FontSubstitutionContext, WithEvents, conversion lifecycle, event handlers
99
productName: GroupDocs.Conversion for .NET
1010
hideChildren: False
1111
toc: True
@@ -21,7 +21,7 @@ The aggregator is registered with the [Converter](https://reference.groupdocs.co
2121

2222
## Event groups
2323

24-
`ConversionEvents` exposes two distinct groups of handlers.
24+
`ConversionEvents` exposes three distinct groups of handlers.
2525

2626
### Pipeline lifecycle
2727

@@ -51,6 +51,16 @@ Fire **once per produced item** — each converted document, each converted page
5151

5252
See [Context Objects — Complete Guide]({{< ref "conversion/net/developer-guide/basic-usage/context-objects-complete-guide.md" >}}) for the properties exposed by `ConvertedContext`, `ConvertContext`, and `ConvertedPageContext`.
5353

54+
### Diagnostics
55+
56+
Report a condition detected while processing the source document, rather than the outcome of a produced item.
57+
58+
| Handler | Signature | When it fires |
59+
|---------|-----------|---------------|
60+
| `OnFontSubstituted` | `Action<FontSubstitutionContext>` | Once per distinct missing font in a source document, when that font is substituted during conversion |
61+
62+
See [Font substitution notifications](#font-substitution-notifications) below for the full handler reference.
63+
5464
## Registering events with the classic API
5565

5666
Pass a `ConversionEvents` factory as the third argument to the `Converter` constructor:
@@ -170,6 +180,99 @@ FluentConverter
170180

171181
The previous late-stage `.OnCompressionCompleted(stream => ...)` placed after `.Compress(...)` continues to work but is obsolete — the `IConversionCompressResultCompleted` interface that declares it is planned for removal in v26.9.
172182

183+
## Font substitution notifications
184+
185+
`OnFontSubstituted` notifies you whenever a font referenced by the source document is unavailable and gets substituted during conversion — either because the font is missing from the machine, or because you configured a [FontSubstitute](https://reference.groupdocs.com/conversion/net/groupdocs.conversion.contracts/fontsubstitute/) rule (see [Specify font substitution]({{< ref "conversion/net/developer-guide/advanced-usage/loading/load-options-for-different-document-types/load-wordprocessing-document-with-options.md#specify-font-substitution" >}})). The handler receives a `FontSubstitutionContext` describing the substitution.
186+
187+
### Subscribe (classic API)
188+
189+
```csharp
190+
using GroupDocs.Conversion;
191+
using GroupDocs.Conversion.Contracts;
192+
using GroupDocs.Conversion.Options.Convert;
193+
194+
var events = new ConversionEvents
195+
{
196+
OnFontSubstituted = context =>
197+
{
198+
// Prefer the typed names when present; otherwise use the verbatim Reason.
199+
var detail = context.OriginalFontName != null
200+
? $"{context.OriginalFontName} -> {context.SubstituteFontName}"
201+
: context.Reason;
202+
Console.WriteLine($"Font substituted in '{context.SourceFileName}': {detail}");
203+
}
204+
};
205+
206+
using (var converter = new Converter("source.docx", () => new ConverterSettings(), () => events))
207+
{
208+
converter.Convert("output.pdf", new PdfConvertOptions());
209+
}
210+
```
211+
212+
### Subscribe (fluent API)
213+
214+
```csharp
215+
using GroupDocs.Conversion;
216+
using GroupDocs.Conversion.Options.Convert;
217+
218+
FluentConverter
219+
.WithEvents(e => e.OnFontSubstituted = ctx =>
220+
Console.WriteLine($"Font substituted: {ctx.Reason ?? ctx.OriginalFontName}"))
221+
.Load("source.docx")
222+
.ConvertTo("output.pdf").WithOptions(new PdfConvertOptions())
223+
.Convert();
224+
```
225+
226+
### Notify on a customer-supplied substitution rule
227+
228+
When you provide your own substitution rules through the load options (supported for Word-processing, Spreadsheet, and PDF documents), `OnFontSubstituted` reports each rule that is applied:
229+
230+
```csharp
231+
using GroupDocs.Conversion;
232+
using GroupDocs.Conversion.Contracts;
233+
using GroupDocs.Conversion.Options.Convert;
234+
using GroupDocs.Conversion.Options.Load;
235+
236+
using (var converter = new Converter(
237+
"source.docx",
238+
_ => new WordProcessingLoadOptions
239+
{
240+
FontSubstitutes = new List<FontSubstitute> { FontSubstitute.Create("MissingFont", "Arial") }
241+
},
242+
() => new ConverterSettings(),
243+
() => events))
244+
{
245+
converter.Convert("output.pdf", new PdfConvertOptions());
246+
}
247+
```
248+
249+
### `FontSubstitutionContext` members
250+
251+
| Member | Description |
252+
|--------|-------------|
253+
| `SourceFileName` | The source document's file name (a generated id when the source is a non-file stream). |
254+
| `OriginalFontName` | The font referenced by the document but unavailable. May be `null` for formats that report only descriptive text. |
255+
| `SubstituteFontName` | The font used instead. May be `null` — read `Reason`. |
256+
| `Reason` | The substitution message exactly as reported, verbatim. Names both fonts when the typed members are `null`. |
257+
258+
See [Context Objects — Complete Guide]({{< ref "conversion/net/developer-guide/basic-usage/context-objects-complete-guide.md#fontsubstitutioncontext" >}}) for more detail.
259+
260+
### Supported documents
261+
262+
| Document family | Missing-font substitution | Rule-driven substitution |
263+
|-----------------|:-------------------------:|:------------------------:|
264+
| Word-processing, Spreadsheet, PDF | ✔ | ✔ |
265+
| Presentation, Diagram, PCL, TeX | ✔ | — |
266+
267+
Image conversions are out of scope — see the behavior notes below.
268+
269+
### Behavior notes
270+
271+
- Fired once per distinct missing font per source document within a single `Convert(...)` call (deduplicated).
272+
- Raised synchronously on the conversion thread.
273+
- Not raised for image *source* conversions (raster images carry no fonts). Converting *to* an image still reports substitutions from the source document.
274+
- For presentation documents, substitution is detected on Windows only.
275+
173276
## Compatibility with the previous API
174277

175278
The previous registration mechanisms continue to work, but are obsolete and planned for removal in **v26.9**:

‎net/developer-guide/basic-usage/context-objects-complete-guide.md‎

Lines changed: 47 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ url: conversion/net/context-objects-complete-guide
44
title: Context Objects - Complete Guide
55
weight: 6
66
description: "Learn how to use Context Objects in GroupDocs.Conversion for .NET v24.10+. Context objects are foundational to all delegate-based patterns."
7-
keywords: Context Objects, LoadContext, ConvertContext, SaveContext, SavePageContext, ConvertedContext, ConvertedPageContext, GroupDocs.Conversion delegates
7+
keywords: Context Objects, LoadContext, ConvertContext, SaveContext, SavePageContext, ConvertedContext, ConvertedPageContext, FontSubstitutionContext, GroupDocs.Conversion delegates
88
productName: GroupDocs.Conversion for .NET
99
hideChildren: False
1010
---
@@ -24,9 +24,9 @@ Context objects provide:
2424
- **Dynamic configuration**: Configure options based on actual document properties
2525
- **Lifecycle callbacks**: Monitor conversion progress page-by-page or document-level
2626

27-
## The Six Context Types
27+
## The Context Types
2828

29-
GroupDocs.Conversion provides six context types, each serving a specific purpose:
29+
GroupDocs.Conversion provides six **configuration/result** context types that drive delegate-based patterns, plus one **diagnostic** context (`FontSubstitutionContext`, available since v26.6) delivered to a conversion event:
3030

3131
| Context Type | Used In | Purpose |
3232
|--------------|---------|---------|
@@ -36,6 +36,7 @@ GroupDocs.Conversion provides six context types, each serving a specific purpose
3636
| [SavePageContext](https://reference.groupdocs.com/conversion/net/groupdocs.conversion/savepagecontext/) | `Func<SavePageContext, Stream>` | Provides page-specific information for stream output |
3737
| [ConvertedContext](https://reference.groupdocs.com/conversion/net/groupdocs.conversion/convertedcontext/) | `Action<ConvertedContext>` | Callback after entire document conversion completes |
3838
| [ConvertedPageContext](https://reference.groupdocs.com/conversion/net/groupdocs.conversion/convertedpagecontext/) | `Action<ConvertedPageContext>` | Callback after each page conversion completes |
39+
| [FontSubstitutionContext](#fontsubstitutioncontext) | `Action<FontSubstitutionContext>` | Diagnostic — reports a font substituted while processing the source document |
3940

4041
---
4142

@@ -287,6 +288,49 @@ using (var converter = new Converter("monthly-report.pdf"))
287288

288289
---
289290

291+
## FontSubstitutionContext
292+
293+
**Used in**: the `OnFontSubstituted` handler of [ConversionEvents](https://reference.groupdocs.com/conversion/net/groupdocs.conversion/conversionevents/) (`Action<FontSubstitutionContext>`)
294+
295+
**Purpose**: Unlike the six context types above — which configure delegates or report a produced result — `FontSubstitutionContext` is a **diagnostic** context. Starting with **GroupDocs.Conversion for .NET v26.6**, it is delivered to the `OnFontSubstituted` event whenever a font referenced by the source document is unavailable and gets substituted during conversion (a missing system font, or a [FontSubstitute](https://reference.groupdocs.com/conversion/net/groupdocs.conversion.contracts/fontsubstitute/) rule you configured).
296+
297+
### Properties
298+
299+
| Property | Type | Description |
300+
|----------|------|-------------|
301+
| `SourceFileName` | `string` | Name of the source file (a generated id when the source is a non-file stream) (read-only) |
302+
| `OriginalFontName` | `string` | The font referenced by the document but unavailable. May be `null` for formats that report only descriptive text (read-only) |
303+
| `SubstituteFontName` | `string` | The font used instead. May be `null` — read `Reason` (read-only) |
304+
| `Reason` | `string` | The substitution message exactly as reported, verbatim. Names both fonts when the typed members are `null` (read-only) |
305+
306+
### Example
307+
308+
```csharp
309+
using GroupDocs.Conversion;
310+
using GroupDocs.Conversion.Contracts;
311+
using GroupDocs.Conversion.Options.Convert;
312+
313+
var events = new ConversionEvents
314+
{
315+
OnFontSubstituted = (FontSubstitutionContext context) =>
316+
{
317+
var detail = context.OriginalFontName != null
318+
? $"{context.OriginalFontName} -> {context.SubstituteFontName}"
319+
: context.Reason;
320+
Console.WriteLine($"Font substituted in '{context.SourceFileName}': {detail}");
321+
}
322+
};
323+
324+
using (var converter = new Converter("source.docx", () => new ConverterSettings(), () => events))
325+
{
326+
converter.Convert("output.pdf", new PdfConvertOptions());
327+
}
328+
```
329+
330+
See [Conversion events — Font substitution notifications]({{< ref "conversion/net/developer-guide/advanced-usage/conversion-events.md#font-substitution-notifications" >}}) for the supported-document matrix and behavior notes.
331+
332+
---
333+
290334
## Working with Container Documents
291335

292336
The `HierarchyLevel` and `ItemIndex` properties become relevant when converting **container documents** that can hold multiple items in a hierarchical structure.

‎net/getting-started/features-overview.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ You can obtain the [complete list of possible conversions]({{< ref "conversion/n
4141

4242
### Fonts replacement
4343

44-
It is a common use case when a source document references some specific fonts that are not present in the environment where you launch your application. GroupDocs.Conversion for .NET provides a solution - you can [substitute missing fonts]({{< ref "conversion/net/developer-guide/advanced-usage/loading/load-options-for-different-document-types/load-wordprocessing-document-with-options#specify-font-substitution" >}}) with fonts of your choice that will preserve your document appearance.
44+
It is a common use case when a source document references some specific fonts that are not present in the environment where you launch your application. GroupDocs.Conversion for .NET provides a solution - you can [substitute missing fonts]({{< ref "conversion/net/developer-guide/advanced-usage/loading/load-options-for-different-document-types/load-wordprocessing-document-with-options#specify-font-substitution" >}}) with fonts of your choice that will preserve your document appearance. You can also [subscribe to the `OnFontSubstituted` event]({{< ref "conversion/net/developer-guide/advanced-usage/conversion-events.md#font-substitution-notifications" >}}) to be notified whenever a font is substituted during conversion.
4545

4646
### Watermarking converted document
4747

0 commit comments

Comments
 (0)