Class HtmlContainerInt

Low level handling of Html Renderer logic.
Allows html layout and rendering without association to actual control, those allowing to handle html rendering on any graphics object.
Using this class will require the client to handle all propagation's of mouse/keyboard events, layout/paint calls, scrolling offset, location/size/rectangle handling and UI refresh requests.

Inheritance
System.Object
HtmlContainerInt
Inherited Members
System.Object.ToString()
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
Namespace: TheArtOfDev.HtmlRenderer.Core
Assembly: Telerik.WinControls.RadMap.dll

Syntax

public sealed class HtmlContainerInt : IDisposable
Remarks

MaxSize and ActualSize:
The max width and height of the rendered html.
The max width will effect the html layout wrapping lines, resize images and tables where possible.
The max height does NOT effect layout, but will not render outside it (clip).
ActualSize can exceed the max size by layout restrictions (unwrap-able line, set image size, etc.).
Set zero for unlimited (width/height separately).

ScrollOffset:
This will adjust the rendered html by the given offset so the content will be "scrolled".
Element that is rendered at location (50,100) with offset of (0,200) will not be rendered at -100, therefore outside the client rectangle.

LinkClicked event
Raised when the user clicks on a link in the html.
Allows canceling the execution of the link to overwrite by custom logic.
If error occurred in event handler it will propagate up the stack.

StylesheetLoad event:
Raised 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.

ImageLoad event:
Raised 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.

Refresh event:
Raised when html renderer requires refresh of the control hosting (invalidation and re-layout).
There is no guarantee that the event will be raised on the main thread, it can be raised on thread-pool thread.

RenderError event:
Raised when an error occurred during html rendering.

Constructors

HtmlContainerInt(RAdapter)

Init.

Declaration
public HtmlContainerInt(RAdapter adapter)
Parameters
RAdapter adapter

Properties

ActualSize

The actual size of the rendered html (after layout)

Declaration
public RSize ActualSize { get; set; }
Property Value
RSize

AvoidAsyncImagesLoading

Gets or sets a value indicating if image asynchronous loading should be avoided (default - false).
True - images are loaded synchronously during html parsing.
False - images are loaded asynchronously to html parsing when downloaded from URL or loaded from disk.

Declaration
public bool AvoidAsyncImagesLoading { get; set; }
Property Value
System.Boolean

Remarks

Asynchronously image loading allows to unblock html rendering while image is downloaded or loaded from disk using IO ports to achieve better performance.
Asynchronously image loading should be avoided when the full html content must be available during render, like render to image.

AvoidGeometryAntialias

Gets or sets a value indicating if anti-aliasing should be avoided for geometry like backgrounds and borders (default - false).

Declaration
public bool AvoidGeometryAntialias { get; set; }
Property Value
System.Boolean

AvoidImagesLateLoading

Gets or sets a value indicating if image loading only when visible should be avoided (default - false).
True - images are loaded as soon as the html is parsed.
False - images that are not visible because of scroll location are not loaded until they are scrolled to.

Declaration
public bool AvoidImagesLateLoading { get; set; }
Property Value
System.Boolean

Remarks

Images late loading improve performance if the page contains image outside the visible scroll area, especially if there is large amount of images, as all image loading is delayed (downloading and loading into memory).
Late image loading may effect the layout and actual size as image without set size will not have actual size until they are loaded resulting in layout change during user scroll.
Early image loading may also effect the layout if image without known size above the current scroll location are loaded as they will push the html elements down.

CssData

the parsed stylesheet data used for handling the html

Declaration
public CssData CssData { get; }
Property Value
CssData

IsContextMenuEnabled

Is the build-in context menu enabled and will be shown on mouse right click (default - true)

Declaration
public bool IsContextMenuEnabled { get; set; }
Property Value
System.Boolean

IsSelectionEnabled

Is content selection is enabled for the rendered html (default - true).
If set to 'false' the rendered html will be static only with ability to click on links.

Declaration
public bool IsSelectionEnabled { get; set; }
Property Value
System.Boolean

Location

The top-left most location of the rendered html.
This will offset the top-left corner of the rendered html.

Declaration
public RPoint Location { get; set; }
Property Value
RPoint

MarginBottom

the bottom margin between the page end and the text

Declaration
public int MarginBottom { get; set; }
Property Value
System.Int32

MarginLeft

the left margin between the page start and the text

Declaration
public int MarginLeft { get; set; }
Property Value
System.Int32

MarginRight

the right margin between the page end and the text

Declaration
public int MarginRight { get; set; }
Property Value
System.Int32

MarginTop

the top margin between the page start and the text

Declaration
public int MarginTop { get; set; }
Property Value
System.Int32

MaxSize

The max width and height of the rendered html.
The max width will effect the html layout wrapping lines, resize images and tables where possible.
The max height does NOT effect layout, but will not render outside it (clip).
ActualSize can be exceed the max size by layout restrictions (unwrapable line, set image size, etc.).
Set zero for unlimited (width\height separately).

Declaration
public RSize MaxSize { get; set; }
Property Value
RSize

PageSize

Declaration
public RSize PageSize { get; set; }
Property Value
RSize

ScrollOffset

The scroll offset of the html.
This will adjust the rendered html by the given offset so the content will be "scrolled".

Declaration
public RPoint ScrollOffset { get; set; }
Property Value
RPoint

Examples

Element that is rendered at location (50,100) with offset of (0,200) will not be rendered as it will be at -100 therefore outside the client rectangle.

SelectedHtml

Copy the currently selected html segment with style.

Declaration
public string SelectedHtml { get; }
Property Value
System.String

SelectedText

Get the currently selected text segment in the html.

Declaration
public string SelectedText { get; }
Property Value
System.String

Methods

Clear()

Clear the content of the HTML container releasing any resources used to render previously existing content.

Declaration
public void Clear()

ClearSelection()

Clear the current selection.

Declaration
public void ClearSelection()

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration
public void Dispose()
Implements
System.IDisposable.Dispose()

GetAttributeAt(RPoint, String)

Get attribute value of element at the given x,y location by given key.
If more than one element exist with the attribute at the location the inner most is returned.

Declaration
public string GetAttributeAt(RPoint location, string attribute)
Parameters
RPoint location

the location to find the attribute at
System.String attribute

the attribute key to get value by
Returns
System.String

found attribute value or null if not found

GetElementRectangle(String)

Get the rectangle of html element as calculated by html layout.
Element if found by id (id attribute on the html element).
Note: to get the screen rectangle you need to adjust by the hosting control.

Declaration
public RRect? GetElementRectangle(string elementId)
Parameters
System.String elementId

the id of the element to get its rectangle
Returns
System.Nullable<RRect>

the rectangle of the element or null if not found

GetHtml(HtmlGenerationStyle)

Get html from the current DOM tree with style if requested.

Declaration
public string GetHtml(HtmlGenerationStyle styleGen = HtmlGenerationStyle.Inline)
Parameters
HtmlGenerationStyle styleGen

Optional: controls the way styles are generated when html is generated (default: Inline)
Returns
System.String

generated html

GetLinkAt(RPoint)

Get css link href at the given x,y location.

Declaration
public string GetLinkAt(RPoint location)
Parameters
RPoint location

the location to find the link at
Returns
System.String

css link href if exists or null

HandleKeyDown(RControl, RKeyEvent)

Handle key down event for selection and copy.

Declaration
public void HandleKeyDown(RControl parent, RKeyEvent e)
Parameters
RControl parent

the control hosting the html to invalidate
RKeyEvent e

the pressed key

HandleMouseDoubleClick(RControl, RPoint)

Handle mouse double click to select word under the mouse.

Declaration
public void HandleMouseDoubleClick(RControl parent, RPoint location)
Parameters
RControl parent

the control hosting the html to set cursor and invalidate
RPoint location

the location of the mouse

HandleMouseDown(RControl, RPoint)

Handle mouse down to handle selection.

Declaration
public void HandleMouseDown(RControl parent, RPoint location)
Parameters
RControl parent

the control hosting the html to invalidate
RPoint location

the location of the mouse

HandleMouseLeave(RControl)

Handle mouse leave to handle hover cursor.

Declaration
public void HandleMouseLeave(RControl parent)
Parameters
RControl parent

the control hosting the html to set cursor and invalidate

HandleMouseMove(RControl, RPoint)

Handle mouse move to handle hover cursor and text selection.

Declaration
public void HandleMouseMove(RControl parent, RPoint location)
Parameters
RControl parent

the control hosting the html to set cursor and invalidate
RPoint location

the location of the mouse

HandleMouseUp(RControl, RPoint, RMouseEvent)

Handle mouse up to handle selection and link click.

Declaration
public void HandleMouseUp(RControl parent, RPoint location, RMouseEvent e)
Parameters
RControl parent

the control hosting the html to invalidate
RPoint location

the location of the mouse
RMouseEvent e

the mouse event data

PerformLayout(RGraphics)

Measures the bounds of box and children, recursively.

Declaration
public void PerformLayout(RGraphics g)
Parameters
RGraphics g

Device context to draw

PerformPaint(RGraphics)

Render the html using the given device.

Declaration
public void PerformPaint(RGraphics g)
Parameters
RGraphics g

the device to use to render

RequestRefresh(Boolean)

Request invalidation and re-layout of the control hosting the renderer.

Declaration
public void RequestRefresh(bool layout)
Parameters
System.Boolean layout

is re-layout is required for the refresh

SetHtml(String, CssData)

Init with optional document and stylesheet.

Declaration
public void SetHtml(string htmlSource, CssData baseCssData = null)
Parameters
System.String htmlSource

the html to init with, init empty if not given
CssData baseCssData

optional: the stylesheet to init with, init default if not given

SetMargins(Int32)

Set all 4 margins to the given value.

Declaration
public void SetMargins(int value)
Parameters
System.Int32 value

Events

ImageLoad

Raised when an image is about to be loaded by file path or URI.
This event allows to provide the image manually, if not handled the image will be loaded from file or download from URI.

Declaration
public event EventHandler<HtmlImageLoadEventArgs> ImageLoad
Event Type
System.EventHandler<HtmlImageLoadEventArgs>

LinkClicked

Raised when the user clicks on a link in the html.
Allows canceling the execution of the link.

Declaration
public event EventHandler<HtmlLinkClickedEventArgs> LinkClicked
Event Type
System.EventHandler<HtmlLinkClickedEventArgs>

LoadComplete

Raised when the set html document has been fully loaded.
Allows manipulation of the html dom, scroll position, etc.

Declaration
public event EventHandler LoadComplete
Event Type
System.EventHandler

Refresh

Raised when html renderer requires refresh of the control hosting (invalidation and re-layout).

Declaration
public event EventHandler<HtmlRefreshEventArgs> Refresh
Event Type
System.EventHandler<HtmlRefreshEventArgs>

Remarks

There is no guarantee that the event will be raised on the main thread, it can be raised on thread-pool thread.

RenderError

Raised when an error occurred during html rendering.

Declaration
public event EventHandler<HtmlRenderErrorEventArgs> RenderError
Event Type
System.EventHandler<HtmlRenderErrorEventArgs>

Remarks

There is no guarantee that the event will be raised on the main thread, it can be raised on thread-pool thread.

ScrollChange

Raised when Html Renderer request scroll to specific location.
This can occur on document anchor click.

Declaration
public event EventHandler<HtmlScrollEventArgs> ScrollChange
Event Type
System.EventHandler<HtmlScrollEventArgs>

StylesheetLoad

Raised when a stylesheet is about to be loaded by file path or URI by link element.
This event allows to provide the stylesheet manually or provide new source (file or Uri) to load from.
If no alternative data is provided the original source will be used.

Declaration
public event EventHandler<HtmlStylesheetLoadEventArgs> StylesheetLoad
Event Type
System.EventHandler<HtmlStylesheetLoadEventArgs>

Extension Methods