Class HtmlRender
Standalone static class for simple and direct HTML rendering.
For low-level control and performance consider using Html
Inheritance
Inherited Members
Namespace: TheArtOfDev.HtmlRenderer.WinForms
Assembly: Telerik.WinControls.RadMap.dll
Syntax
public static class HtmlRenderRemarks
GDI vs. GDI+ text rendering
Windows supports two text rendering technologies: GDI and GDI+.
GDI is older, has better performance and looks better on standard monitors but doesn't support alpha channel for transparency.
GDI+ is newer, device independent so work better for printers but is slower and looks worse on monitors.
HtmlRender supports both GDI and GDI+ text rendering to accommodate different needs, GDI+ text rendering methods have "GdiPlus" suffix
in their name where GDI do not.
Rendering to image
See https://htmlrenderer.codeplex.com/wikipage?title=Image%20generation
Because of GDI text rendering issue with alpha channel clear type text rendering rendering to image requires special handling.
Solid color background - generate an image where the background is filled with solid color and all the html is rendered on top
of the background color, GDI text rendering will be used. (RenderToImage method where the first argument is html string)
Image background - render html on top of existing image with whatever currently exist but it cannot have transparent pixels,
GDI text rendering will be used. (RenderToImage method where the first argument is Image object)
Transparent background - render html to empty image using GDI+ text rendering, the generated image can be transparent.
Text rendering can be controlled using System.
Overwrite stylesheet resolution
Exposed by optional "stylesheetLoad" delegate argument.
Invoked when a stylesheet is about to be loaded by file path or URL in 'link' element.
Allows to overwrite the loaded stylesheet by providing the stylesheet data manually, or different source (file or URL) to load from.
Example: The stylesheet 'href' can be non-valid URI string that is interpreted in the overwrite delegate by custom logic to pre-loaded stylesheet object
If no alternative data is provided the original source will be used.
Overwrite image resolution
Exposed by optional "imageLoad" delegate argument.
Invoked when an image is about to be loaded by file path, URL or inline data in 'img' element or background-image CSS style.
Allows to overwrite the loaded image by providing the image object manually, or different source (file or URL) to load from.
Example: image 'src' can be non-valid string that is interpreted in the overwrite delegate by custom logic to resource image object
Example: image 'src' in the html is relative - the overwrite intercepts the load and provide full source URL to load the image from
Example: image download requires authentication - the overwrite intercepts the load, downloads the image to disk using custom code and provide
file path to load the image from.
If no alternative data is provided the original source will be used.
Note: Cannot use asynchronous scheme overwrite scheme.
Examples
Simple rendering
HtmlRender.Render(g, "<div>Hello <b>World</b></div>");
HtmlRender.Render(g, "<div>Hello <b>World</b></div>", 10, 10, 500, CssData.Parse("body {font-size: 20px}")");
Image rendering
HtmlRender.RenderToImage("<div>Hello <b>World</b></div>", new Size(600,400));
HtmlRender.RenderToImage("<div>Hello <b>World</b></div>", 600);
HtmlRender.RenderToImage(existingImage, "<div>Hello <b>World</b></div>");
Methods
AddFontFamily(FontFamily)
Adds a font family to be used in html rendering.
The added font will be used by all rendering function including Html
Declaration
public static void AddFontFamily(FontFamily fontFamily)Parameters
|
System. The font family to add. |
Remarks
The given font family instance must be remain alive while the renderer is in use.
If loaded to System.
If loaded from file then the file must not be deleted.
AddFontFamilyMapping(String, String)
Adds a font mapping from fromFamily to toFamily iff the fromFamily is not found.
When the fromFamily font is used in rendered html and is not found in existing
fonts (installed or added) it will be replaced by toFamily.
Declaration
public static void AddFontFamilyMapping(string fromFamily, string toFamily)Parameters
|
System. the font family to replace |
|
System. the font family to replace with |
Remarks
This fonts mapping can be used as a fallback in case the requested font is not installed in the client system.
Measure(Graphics, String, Single, CssData, EventHandler<HtmlStylesheetLoadEventArgs>, EventHandler<HtmlImageLoadEventArgs>)
Measure the size (width and height) required to draw the given html under given max width restriction.
If no max width restriction is given the layout will use the maximum possible width required by the content,
it can be the longest text line or full image width.
Use GDI text rendering, note System.
Declaration
public static SizeF Measure(Graphics g, string html, float maxWidth = 0F, CssData cssData = null, EventHandler<HtmlStylesheetLoadEventArgs> stylesheetLoad = null, EventHandler<HtmlImageLoadEventArgs> imageLoad = null)Parameters
|
System. Device to use for measure |
|
System. HTML source to render |
|
System. optional: bound the width of the html to render in (default - 0, unlimited) |
|
Css optional: the style to use for html rendering (default - use W3 default style) |
|
System. optional: can be used to overwrite stylesheet resolution logic |
|
System. optional: can be used to overwrite image resolution logic |
Returns
|
System. the size required for the html |
MeasureGdiPlus(Graphics, String, Single, CssData, EventHandler<HtmlStylesheetLoadEventArgs>, EventHandler<HtmlImageLoadEventArgs>)
Measure the size (width and height) required to draw the given html under given max width restriction.
If no max width restriction is given the layout will use the maximum possible width required by the content,
it can be the longest text line or full image width.
Use GDI+ text rending, use System.
Declaration
public static SizeF MeasureGdiPlus(Graphics g, string html, float maxWidth = 0F, CssData cssData = null, EventHandler<HtmlStylesheetLoadEventArgs> stylesheetLoad = null, EventHandler<HtmlImageLoadEventArgs> imageLoad = null)Parameters
|
System. Device to use for measure |
|
System. HTML source to render |
|
System. optional: bound the width of the html to render in (default - 0, unlimited) |
|
Css optional: the style to use for html rendering (default - use W3 default style) |
|
System. optional: can be used to overwrite stylesheet resolution logic |
|
System. optional: can be used to overwrite image resolution logic |
Returns
|
System. the size required for the html |
ParseStyleSheet(String, Boolean)
Parse the given stylesheet to Css
If combineWithDefault is true the parsed css blocks are added to the
default css data (as defined by W3), merged if class name already exists. If false only the data in the given stylesheet is returned.
Declaration
public static CssData ParseStyleSheet(string stylesheet, bool combineWithDefault = true)Parameters
|
System. the stylesheet source to parse |
|
System. true - combine the parsed css data with default css data, false - return only the parsed css data |
Returns
|
Css the parsed css data |
See Also
Render(Graphics, String, PointF, SizeF, CssData, EventHandler<HtmlStylesheetLoadEventArgs>, EventHandler<HtmlImageLoadEventArgs>)
Renders the specified HTML source on the specified location and max size restriction.
Use GDI text rendering, note System.
If maxSize.Width is zero the html will use all the required width, otherwise it will perform line
wrap as specified in the html
If maxSize.Height is zero the html will use all the required height, otherwise it will clip at the
given max height not rendering the html below it.
Returned is the actual width and height of the rendered html.
Declaration
public static SizeF Render(Graphics g, string html, PointF location, SizeF maxSize, CssData cssData = null, EventHandler<HtmlStylesheetLoadEventArgs> stylesheetLoad = null, EventHandler<HtmlImageLoadEventArgs> imageLoad = null)Parameters
|
System. Device to render with |
|
System. HTML source to render |
|
System. the top-left most location to start render the html at |
|
System. the max size of the rendered html (if height above zero it will be clipped) |
|
Css optional: the style to use for html rendering (default - use W3 default style) |
|
System. optional: can be used to overwrite stylesheet resolution logic |
|
System. optional: can be used to overwrite image resolution logic |
Returns
|
System. the actual size of the rendered html |
Render(Graphics, String, Single, Single, Single, CssData, EventHandler<HtmlStylesheetLoadEventArgs>, EventHandler<HtmlImageLoadEventArgs>)
Renders the specified HTML source on the specified location and max width restriction.
Use GDI text rendering, note System.
If maxWidth is zero the html will use all the required width, otherwise it will perform line
wrap as specified in the html
Returned is the actual width and height of the rendered html.
Declaration
public static SizeF Render(Graphics g, string html, float left = 0F, float top = 0F, float maxWidth = 0F, CssData cssData = null, EventHandler<HtmlStylesheetLoadEventArgs> stylesheetLoad = null, EventHandler<HtmlImageLoadEventArgs> imageLoad = null)Parameters
|
System. Device to render with |
|
System. HTML source to render |
|
System. optional: the left most location to start render the html at (default - 0) |
|
System. optional: the top most location to start render the html at (default - 0) |
|
System. optional: bound the width of the html to render in (default - 0, unlimited) |
|
Css optional: the style to use for html rendering (default - use W3 default style) |
|
System. optional: can be used to overwrite stylesheet resolution logic |
|
System. optional: can be used to overwrite image resolution logic |
Returns
|
System. the actual size of the rendered html |
RenderGdiPlus(Graphics, String, PointF, SizeF, CssData, EventHandler<HtmlStylesheetLoadEventArgs>, EventHandler<HtmlImageLoadEventArgs>)
Renders the specified HTML source on the specified location and max size restriction.
Use GDI+ text rending, use System.
If maxSize.Width is zero the html will use all the required width, otherwise it will perform line
wrap as specified in the html
If maxSize.Height is zero the html will use all the required height, otherwise it will clip at the
given max height not rendering the html below it.
Returned is the actual width and height of the rendered html.
Declaration
public static SizeF RenderGdiPlus(Graphics g, string html, PointF location, SizeF maxSize, CssData cssData = null, EventHandler<HtmlStylesheetLoadEventArgs> stylesheetLoad = null, EventHandler<HtmlImageLoadEventArgs> imageLoad = null)Parameters
|
System. Device to render with |
|
System. HTML source to render |
|
System. the top-left most location to start render the html at |
|
System. the max size of the rendered html (if height above zero it will be clipped) |
|
Css optional: the style to use for html rendering (default - use W3 default style) |
|
System. optional: can be used to overwrite stylesheet resolution logic |
|
System. optional: can be used to overwrite image resolution logic |
Returns
|
System. the actual size of the rendered html |
RenderGdiPlus(Graphics, String, Single, Single, Single, CssData, EventHandler<HtmlStylesheetLoadEventArgs>, EventHandler<HtmlImageLoadEventArgs>)
Renders the specified HTML source on the specified location and max size restriction.
Use GDI+ text rending, use System.
If maxWidth is zero the html will use all the required width, otherwise it will perform line
wrap as specified in the html
Returned is the actual width and height of the rendered html.
Declaration
public static SizeF RenderGdiPlus(Graphics g, string html, float left = 0F, float top = 0F, float maxWidth = 0F, CssData cssData = null, EventHandler<HtmlStylesheetLoadEventArgs> stylesheetLoad = null, EventHandler<HtmlImageLoadEventArgs> imageLoad = null)Parameters
|
System. Device to render with |
|
System. HTML source to render |
|
System. optional: the left most location to start render the html at (default - 0) |
|
System. optional: the top most location to start render the html at (default - 0) |
|
System. optional: bound the width of the html to render in (default - 0, unlimited) |
|
Css optional: the style to use for html rendering (default - use W3 default style) |
|
System. optional: can be used to overwrite stylesheet resolution logic |
|
System. optional: can be used to overwrite image resolution logic |
Returns
|
System. the actual size of the rendered html |
RenderToImage(Image, String, PointF, SizeF, CssData, EventHandler<HtmlStylesheetLoadEventArgs>, EventHandler<HtmlImageLoadEventArgs>)
Renders the specified HTML on top of the given image.
image will contain the rendered html in it on top of original content.
image must not contain transparent pixels as it will corrupt the rendered html text.
See "Rendering to image" remarks section on Html
Declaration
public static void RenderToImage(Image image, string html, PointF location, SizeF maxSize, CssData cssData = null, EventHandler<HtmlStylesheetLoadEventArgs> stylesheetLoad = null, EventHandler<HtmlImageLoadEventArgs> imageLoad = null)Parameters
|
System. the image to render the html on |
|
System. HTML source to render |
|
System. the top-left most location to start render the html at |
|
System. the max size of the rendered html (if height above zero it will be clipped) |
|
Css optional: the style to use for html rendering (default - use W3 default style) |
|
System. optional: can be used to overwrite stylesheet resolution logic |
|
System. optional: can be used to overwrite image resolution logic |
RenderToImage(Image, String, PointF, CssData, EventHandler<HtmlStylesheetLoadEventArgs>, EventHandler<HtmlImageLoadEventArgs>)
Renders the specified HTML on top of the given image.
image will contain the rendered html in it on top of original content.
image must not contain transparent pixels as it will corrupt the rendered html text.
The HTML will be layout by the given image size but may be clipped if cannot fit.
See "Rendering to image" remarks section on Html
Declaration
public static void RenderToImage(Image image, string html, PointF location = null, CssData cssData = null, EventHandler<HtmlStylesheetLoadEventArgs> stylesheetLoad = null, EventHandler<HtmlImageLoadEventArgs> imageLoad = null)Parameters
|
System. the image to render the html on |
|
System. HTML source to render |
|
System. optional: the top-left most location to start render the html at (default - 0,0) |
|
Css optional: the style to use for html rendering (default - use W3 default style) |
|
System. optional: can be used to overwrite stylesheet resolution logic |
|
System. optional: can be used to overwrite image resolution logic |
RenderToImage(String, Size, Color, CssData, EventHandler<HtmlStylesheetLoadEventArgs>, EventHandler<HtmlImageLoadEventArgs>)
Renders the specified HTML into a new image of the requested size.
The HTML will be layout by the given size but will be clipped if cannot fit.
Limitation: The image cannot have transparent background, by default it will be white.
See "Rendering to image" remarks section on Html
Declaration
public static Image RenderToImage(string html, Size size, Color backgroundColor = null, CssData cssData = null, EventHandler<HtmlStylesheetLoadEventArgs> stylesheetLoad = null, EventHandler<HtmlImageLoadEventArgs> imageLoad = null)Parameters
|
System. HTML source to render |
|
System. The size of the image to render into, layout html by width and clipped by height |
|
System. optional: the color to fill the image with (default - white) |
|
Css optional: the style to use for html rendering (default - use W3 default style) |
|
System. optional: can be used to overwrite stylesheet resolution logic |
|
System. optional: can be used to overwrite image resolution logic |
Returns
|
System. the generated image of the html |
Exceptions
|
System. if |
RenderToImage(String, Size, Size, Color, CssData, EventHandler<HtmlStylesheetLoadEventArgs>, EventHandler<HtmlImageLoadEventArgs>)
Renders the specified HTML into a new image of unknown size that will be determined by min/max width/height and HTML layout.
If maxSize.Width is zero the html will use all the required width, otherwise it will perform line
wrap as specified in the html
If maxSize.Height is zero the html will use all the required height, otherwise it will clip at the
given max height not rendering the html below it.
If minSize (Width/Height) is above zero the rendered image will not be smaller than the given min size.
Limitation: The image cannot have transparent background, by default it will be white.
See "Rendering to image" remarks section on Html
Declaration
public static Image RenderToImage(string html, Size minSize, Size maxSize, Color backgroundColor = null, CssData cssData = null, EventHandler<HtmlStylesheetLoadEventArgs> stylesheetLoad = null, EventHandler<HtmlImageLoadEventArgs> imageLoad = null)Parameters
|
System. HTML source to render |
|
System. optional: the min size of the rendered html (zero - not limit the width/height) |
|
System. optional: the max size of the rendered html, if not zero and html cannot be layout within the limit it will be clipped (zero - not limit the width/height) |
|
System. optional: the color to fill the image with (default - white) |
|
Css optional: the style to use for html rendering (default - use W3 default style) |
|
System. optional: can be used to overwrite stylesheet resolution logic |
|
System. optional: can be used to overwrite image resolution logic |
Returns
|
System. the generated image of the html |
Exceptions
|
System. if |
RenderToImage(String, Int32, Int32, Color, CssData, EventHandler<HtmlStylesheetLoadEventArgs>, EventHandler<HtmlImageLoadEventArgs>)
Renders the specified HTML into a new image of unknown size that will be determined by max width/height and HTML layout.
If maxWidth is zero the html will use all the required width, otherwise it will perform line
wrap as specified in the html
If maxHeight is zero the html will use all the required height, otherwise it will clip at the
given max height not rendering the html below it.
Limitation: The image cannot have transparent background, by default it will be white.
See "Rendering to image" remarks section on Html
Declaration
public static Image RenderToImage(string html, int maxWidth = 0, int maxHeight = 0, Color backgroundColor = null, CssData cssData = null, EventHandler<HtmlStylesheetLoadEventArgs> stylesheetLoad = null, EventHandler<HtmlImageLoadEventArgs> imageLoad = null)Parameters
|
System. HTML source to render |
|
System. optional: the max width of the rendered html, if not zero and html cannot be layout within the limit it will be clipped |
|
System. optional: the max height of the rendered html, if not zero and html cannot be layout within the limit it will be clipped |
|
System. optional: the color to fill the image with (default - white) |
|
Css optional: the style to use for html rendering (default - use W3 default style) |
|
System. optional: can be used to overwrite stylesheet resolution logic |
|
System. optional: can be used to overwrite image resolution logic |
Returns
|
System. the generated image of the html |
Exceptions
|
System. if |
RenderToImageGdiPlus(String, Size, Size, TextRenderingHint, CssData, EventHandler<HtmlStylesheetLoadEventArgs>, EventHandler<HtmlImageLoadEventArgs>)
Renders the specified HTML into a new image of unknown size that will be determined by min/max width/height and HTML layout.
If maxSize.Width is zero the html will use all the required width, otherwise it will perform line
wrap as specified in the html
If maxSize.Height is zero the html will use all the required height, otherwise it will clip at the
given max height not rendering the html below it.
If minSize (Width/Height) is above zero the rendered image will not be smaller than the given min size.
The generated image have transparent background that the html is rendered on.
GDI+ text rending can be controlled by providing System.
See "Rendering to image" remarks section on Html
Declaration
public static Image RenderToImageGdiPlus(string html, Size minSize, Size maxSize, TextRenderingHint textRenderingHint, CssData cssData = null, EventHandler<HtmlStylesheetLoadEventArgs> stylesheetLoad = null, EventHandler<HtmlImageLoadEventArgs> imageLoad = null)Parameters
|
System. HTML source to render |
|
System. optional: the min size of the rendered html (zero - not limit the width/height) |
|
System. optional: the max size of the rendered html, if not zero and html cannot be layout within the limit it will be clipped (zero - not limit the width/height) |
|
System. optional: (default - SingleBitPerPixelGridFit) |
|
Css optional: the style to use for html rendering (default - use W3 default style) |
|
System. optional: can be used to overwrite stylesheet resolution logic |
|
System. optional: can be used to overwrite image resolution logic |
Returns
|
System. the generated image of the html |
RenderToImageGdiPlus(String, Size, TextRenderingHint, CssData, EventHandler<HtmlStylesheetLoadEventArgs>, EventHandler<HtmlImageLoadEventArgs>)
Renders the specified HTML into a new image of the requested size.
The HTML will be layout by the given size but will be clipped if cannot fit.
The generated image have transparent background that the html is rendered on.
GDI+ text rending can be controlled by providing System.
See "Rendering to image" remarks section on Html
Declaration
public static Image RenderToImageGdiPlus(string html, Size size, TextRenderingHint textRenderingHint, CssData cssData = null, EventHandler<HtmlStylesheetLoadEventArgs> stylesheetLoad = null, EventHandler<HtmlImageLoadEventArgs> imageLoad = null)Parameters
|
System. HTML source to render |
|
System. The size of the image to render into, layout html by width and clipped by height |
|
System. optional: (default - SingleBitPerPixelGridFit) |
|
Css optional: the style to use for html rendering (default - use W3 default style) |
|
System. optional: can be used to overwrite stylesheet resolution logic |
|
System. optional: can be used to overwrite image resolution logic |
Returns
|
System. the generated image of the html |
RenderToImageGdiPlus(String, Int32, Int32, TextRenderingHint, CssData, EventHandler<HtmlStylesheetLoadEventArgs>, EventHandler<HtmlImageLoadEventArgs>)
Renders the specified HTML into a new image of unknown size that will be determined by max width/height and HTML layout.
If maxWidth is zero the html will use all the required width, otherwise it will perform line
wrap as specified in the html
If maxHeight is zero the html will use all the required height, otherwise it will clip at the
given max height not rendering the html below it.
The generated image have transparent background that the html is rendered on.
GDI+ text rending can be controlled by providing System.
See "Rendering to image" remarks section on Html
Declaration
public static Image RenderToImageGdiPlus(string html, int maxWidth = 0, int maxHeight = 0, TextRenderingHint textRenderingHint, CssData cssData = null, EventHandler<HtmlStylesheetLoadEventArgs> stylesheetLoad = null, EventHandler<HtmlImageLoadEventArgs> imageLoad = null)Parameters
|
System. HTML source to render |
|
System. optional: the max width of the rendered html, if not zero and html cannot be layout within the limit it will be clipped |
|
System. optional: the max height of the rendered html, if not zero and html cannot be layout within the limit it will be clipped |
|
System. optional: (default - SingleBitPerPixelGridFit) |
|
Css optional: the style to use for html rendering (default - use W3 default style) |
|
System. optional: can be used to overwrite stylesheet resolution logic |
|
System. optional: can be used to overwrite image resolution logic |
Returns
|
System. the generated image of the html |
RenderToMetafile(String, Single, Single, Single, CssData, EventHandler<HtmlStylesheetLoadEventArgs>, EventHandler<HtmlImageLoadEventArgs>)
Declaration
public static Metafile RenderToMetafile(string html, float left = 0F, float top = 0F, float maxWidth = 0F, CssData cssData = null, EventHandler<HtmlStylesheetLoadEventArgs> stylesheetLoad = null, EventHandler<HtmlImageLoadEventArgs> imageLoad = null)Parameters
|
System.
|
|
System.
|
|
System.
|
|
System.
|
|
Css
|
|
System.
|
|
System.
|
Returns
|
System.
|