-
Notifications
You must be signed in to change notification settings - Fork 891
Graphic Engine
Graphic Engine is an pluggable component (since 0.97.0
) behind IXLGraphicEngine
interface that is responsible for working with image formats and fonts. Both image reading and rendered size measurement is a non-trivial problem that is out of scope of ClosedXML.
A default graphic engine ClosedXML.Graphic.DefaultGraphicEngine.Instance
) uses "Microsoft Sans Serif" as a fallback font, if workbook tries to render something a missing font. The font is unlikely to be found on non-Windows systems. You might need to create an engine with a font that can be found in the SystemFonts
collection (see source) from SixLabors.Fonts
library.
// A line needed to be used in non-windows environment before instantiating a workbook.
// On linux, we can't rely on installed fonts, we must specify the fallback font that is actually present.
LoadOptions.DefaultGraphicsEngine = new DefaultGraphicEngine("Tahoma"); // If there is a Tahoma font installed
If the program doesn't use font sizes (AdjustToContent) or contain any pictures, it is possible to omit configuration on linux.
You can keep the default engine (no need to configure anything and ClosedXML should just work) or you can specify a different one.
You can specify a different engine globally or individually for each workbook. Global level is done by through a static LoadOptions.DefaultGraphicEngine
property
// On Windows
LoadOptions.DefaultGraphicEngine = new SomeGraphicEngine();
// All workbooks created after setting of the engine will use the specified engine.
using var workbook = new XLWorkbook();
If you need to specify an engine on per-workbook basis, use the LoadOptions.GraphicEngine
property
// Only workbooks created with the options will use the engine
var loadOptions = new LoadOptions { GraphicEngine = new SomeGraphicEngine() };
using var workbook = new XLWorkbook(loadOptions);
Workbook will use the best engine in the following order:
-
LoadOptions.GraphicEngine
- if user specified a specific engine just for the workbook, use that. -
LoadOptions.DefaultGraphicsEngine
- is user specified default engine for all new workbooks, use that. -
DefaultGraphicEngine.Instance
- a graphic engine that usesSixLabors.Fonts
library and a custom picture parsing
- Draft of documentation for unreleased version 0.97.1
Client-side Blazor can't use filesystem and the default instance isn't very useful for them, because it loads system fonts from the filesystem. In a situation where filesystem is not available, it is possible to use a constructor of DefaultGraphicEngine
that accepts a stream containing a fallback font.
using Stream fallbackFontStream = Assembly.GetManifestResourceStream("SomeEmbeddedFont.ttf");
LoadOptions.DefaultGraphicEngine = new DefaultGraphicEngine(fallbackFontStream);
Stream must be seekable, so unfortunately it is no possible to load font directly from S3 or other http place without an intermediate stream.
There is also a possibility to load some additional fonts through streams, not just fallback one. That can be done by passing an extra streams to the constructor.
using Stream fallbackFontStream = Assembly.GetManifestResourceStream("SomeEmbeddedFont.ttf");
using Stream calibriFont = /* a way to get stream for a font */;
using Stream arialFont = /* a way to get stream for a font */;
LoadOptions.DefaultGraphicEngine = new DefaultGraphicEngine(fallbackFontStream, calibriFont, arialFont);
Additional fonts are used in lieu of fallback font, if the cell contains one of the passed fonts.
- How do I deliver an Excel file in ASP.NET?
- Does it support Excel 2003 and prior formats (.xls)?
- How can I insert an image?
- Text with numbers are getting converted to numbers, what's up with that?
- How do I get the result of a formula?
- Data Types
- Creating Multiple Worksheets
- Organizing Sheets
- Loading and Modifying Files
- Using Lambda Expressions
- Cell Values
- Workbook Properties
- Using Formulas
- Evaluating Formulas
- Creating Rows And Columns Outlines
- Hide Unhide Rows And Columns
- Freeze Panes
- Copying Worksheets
- Using Hyperlinks
- Data Validation
- Hide Worksheets
- Sheet Protection
- Tab Colors
- Conditional Formatting
- Pivot Table example
- Sparklines
- Copying IEnumerable Collections
- Inserting Data
- Inserting Tables
- Adding DataTable as Worksheet
- Adding DataSet
- Styles - Alignment
- Styles - Border
- Styles - Fill
- Styles - Font
- Styles - NumberFormat
- NumberFormatId Lookup Table
- Style Worksheet
- Style Rows and Columns
- Using Default Styles
- Using Colors
- ClosedXML Predefined Colors
- Excel Indexed Colors
- Using Rich Text
- Using Phonetics
- Defining Ranges
- Merging Cells
- Clearing Ranges
- Deleting Ranges
- Multiple Ranges
- Shifting Ranges
- Transpose Ranges
- Named Ranges
- Accessing Named Ranges
- Copying Ranges
- Using Tables
- Sorting Data
- Selecting Cells and Ranges
- Row Height and Styles
- Selecting Rows
- Inserting Rows
- Inserting and Deleting Rows
- Adjust Row Height and Column Width to Contents
- Row Cells
- Column Width and Styles
- Selecting Columns
- Inserting Columns
- Inserting and Deleting Columns
- Adjust Row Height and Column Width to Contents
- Column Cells
- Pages Tab
- Paper Size Lookup Table
- Margins Tab
- Headers and Footers Tab
- Sheet Tab
- Print Areas and Page Breaks