Skip to content

Commit f9ddf68

Browse files
author
ArthurHub
committed
* improve documentation
1 parent 0eb0c5b commit f9ddf68

5 files changed

Lines changed: 164 additions & 109 deletions

File tree

‎Source/HtmlRenderer/Entities/HtmlImageLoadEventArgs.cs‎

Lines changed: 30 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -19,19 +19,23 @@ namespace HtmlRenderer.Entities
1919
{
2020
/// <summary>
2121
/// Callback used in <see cref="HtmlImageLoadEventArgs"/> to allow setting image externally and async.<br/>
22-
/// The callback can provide path to image file or uri, or the actual image to use.<br/>
23-
/// If <paramref name="imageRectangle"/> is not <see cref="System.Drawing.Rectangle.Empty"/> then only the specified rectangle will
24-
/// be used from the loaded image and not all of it.<br/>
25-
/// if <paramref name="imageRectangle"/> is given it will be used for the size of the image and not the actual image size.
22+
/// The callback can provide path to image file path, URL or the actual image to use.<br/>
23+
/// If <paramref name="imageRectangle"/> is given (not <see cref="System.Drawing.Rectangle.Empty"/>) then only the specified rectangle will
24+
/// be used from the loaded image and not all of it, also the rectangle will be used for size and not the actual image size.<br/>
2625
/// </summary>
27-
/// <param name="path">the path to the image to load (file path or uri)</param>
28-
/// <param name="image">the image to load</param>
29-
/// <param name="imageRectangle">optional: limit to specific rectangle of the image and not all of it</param>
30-
public delegate void HtmlImageLoadCallback(string path, Image image, Rectangle imageRectangle);
26+
/// <param name="path">the path to the image to load (file path or URL)</param>
27+
/// <param name="image">the image to use</param>
28+
/// <param name="imageRectangle">optional: limit to specific rectangle in the loaded image</param>
29+
internal delegate void HtmlImageLoadCallback(string path, Image image, Rectangle imageRectangle);
3130

3231
/// <summary>
33-
/// Raised when an image is about to be loaded by file path or URI.<br/>
34-
/// This event allows to provide the image manually, if not handled the image will be loaded from file or download from URI.
32+
/// Invoked when an image is about to be loaded by file path, URL or inline data in 'img' element or background-image CSS style.<br/>
33+
/// Allows to overwrite the loaded image by providing the image object manually, or different source (file or URL) to load from.<br/>
34+
/// Example: image 'src' can be non-valid string that is interpreted in the overwrite delegate by custom logic to resource image object<br/>
35+
/// Example: image 'src' in the html is relative - the overwrite intercepts the load and provide full source URL to load the image from<br/>
36+
/// Example: image download requires authentication - the overwrite intercepts the load, downloads the image to disk using custom code and
37+
/// provide file path to load the image from. Can also use the asynchronous image overwrite not to block HTML rendering is applicable.<br/>
38+
/// If no alternative data is provided the original source will be used.<br/>
3539
/// </summary>
3640
public sealed class HtmlImageLoadEventArgs : EventArgs
3741
{
@@ -66,31 +70,32 @@ public sealed class HtmlImageLoadEventArgs : EventArgs
6670
/// <param name="src">the source of the image (file path or uri)</param>
6771
/// <param name="attributes">collection of all the attributes that are defined on the image element</param>
6872
/// <param name="callback">Callback used to allow setting image externally and async.</param>
69-
public HtmlImageLoadEventArgs(string src, Dictionary<string, string> attributes, HtmlImageLoadCallback callback)
73+
internal HtmlImageLoadEventArgs(string src, Dictionary<string, string> attributes, HtmlImageLoadCallback callback)
7074
{
7175
_src = src;
7276
_attributes = attributes;
7377
_callback = callback;
7478
}
7579

7680
/// <summary>
77-
/// the source of the image (file path or uri)
81+
/// the source of the image (file path, URL or inline data)
7882
/// </summary>
7983
public string Src
8084
{
8185
get { return _src; }
8286
}
8387

8488
/// <summary>
85-
/// collection of all the attributes that are defined on the image element
89+
/// collection of all the attributes that are defined on the image element or CSS style
8690
/// </summary>
8791
public Dictionary<string, string> Attributes
8892
{
8993
get { return _attributes; }
9094
}
9195

9296
/// <summary>
93-
/// use to cancel the image loading by html renderer, the provided image will be used.
97+
/// Indicate the image load is handled asynchronously.
98+
/// Cancel this image loading and overwrite the image asynchronously using callback method.<br/>
9499
/// </summary>
95100
public bool Handled
96101
{
@@ -99,8 +104,8 @@ public bool Handled
99104
}
100105

101106
/// <summary>
102-
/// Callback used to allow setting image externally and async.<br/>
103-
/// This call will set error image.
107+
/// Callback to overwrite the loaded image with error image.<br/>
108+
/// Can be called directly from delegate handler or asynchronously after setting <see cref="Handled"/> to True.<br/>
104109
/// </summary>
105110
public void Callback()
106111
{
@@ -109,13 +114,12 @@ public void Callback()
109114
}
110115

111116
/// <summary>
112-
/// Callback used to allow setting image externally and async.<br/>
113-
/// The callback can provide path to image file or uri, or the actual image to use.<br/>
114-
/// If <paramref name="imageRectangle"/> is not <see cref="System.Drawing.Rectangle.Empty"/> then only the specified rectangle will
115-
/// be used from the loaded image and not all of it.<br/>
116-
/// if <paramref name="imageRectangle"/> is given it will be used for the size of the image and not the actual image size.
117+
/// Callback to overwrite the loaded image with image to load from given URI.<br/>
118+
/// Can be called directly from delegate handler or asynchronously after setting <see cref="Handled"/> to True.<br/>
119+
/// If <paramref name="imageRectangle"/> is given (not <see cref="System.Drawing.Rectangle.Empty"/>) then only the specified rectangle will
120+
/// be used from the loaded image and not all of it, also the rectangle will be used for size and not the actual image size.<br/>
117121
/// </summary>
118-
/// <param name="path">the path to the image to load (file path or uri)</param>
122+
/// <param name="path">the path to the image to load (file path or URL)</param>
119123
/// <param name="imageRectangle">optional: limit to specific rectangle of the image and not all of it</param>
120124
public void Callback(string path, Rectangle imageRectangle = new Rectangle())
121125
{
@@ -126,11 +130,10 @@ public void Callback()
126130
}
127131

128132
/// <summary>
129-
/// Callback used to allow setting image externally and async.<br/>
130-
/// The callback can provide path to image file or uri, or the actual image to use.<br/>
131-
/// If <paramref name="imageRectangle"/> is not <see cref="System.Drawing.Rectangle.Empty"/> then only the specified rectangle will
132-
/// be used from the loaded image and not all of it.<br/>
133-
/// if <paramref name="imageRectangle"/> is given it will be used for the size of the image and not the actual image size.
133+
/// Callback to overwrite the loaded image with given image object.<br/>
134+
/// Can be called directly from delegate handler or asynchronously after setting <see cref="Handled"/> to True.<br/>
135+
/// If <paramref name="imageRectangle"/> is given (not <see cref="System.Drawing.Rectangle.Empty"/>) then only the specified rectangle will
136+
/// be used from the loaded image and not all of it, also the rectangle will be used for size and not the actual image size.<br/>
134137
/// </summary>
135138
/// <param name="image">the image to load</param>
136139
/// <param name="imageRectangle">optional: limit to specific rectangle of the image and not all of it</param>

‎Source/HtmlRenderer/Entities/HtmlStylesheetLoadEventArgs.cs‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,9 @@
1616
namespace HtmlRenderer.Entities
1717
{
1818
/// <summary>
19-
/// Raised when a stylesheet is about to be loaded by file path or URL in link element.<br/>
20-
/// This event allows to provide the stylesheet manually or provide new source (file or uri) to load from.<br/>
19+
/// Invoked when a stylesheet is about to be loaded by file path or URL in 'link' element.<br/>
20+
/// Allows to overwrite the loaded stylesheet by providing the stylesheet data manually, or different source (file or URL) to load from.<br/>
21+
/// 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<br/>
2122
/// If no alternative data is provided the original source will be used.<br/>
2223
/// </summary>
2324
public sealed class HtmlStylesheetLoadEventArgs : EventArgs
@@ -57,7 +58,7 @@ public sealed class HtmlStylesheetLoadEventArgs : EventArgs
5758
/// </summary>
5859
/// <param name="src">the source of the image (file path or URL)</param>
5960
/// <param name="attributes">collection of all the attributes that are defined on the image element</param>
60-
public HtmlStylesheetLoadEventArgs(string src, Dictionary<string, string> attributes)
61+
internal HtmlStylesheetLoadEventArgs(string src, Dictionary<string, string> attributes)
6162
{
6263
_src = src;
6364
_attributes = attributes;

‎Source/HtmlRenderer/Handlers/ImageLoadHandler.cs‎

Lines changed: 15 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,6 @@ namespace HtmlRenderer.Handlers
2727
/// Handler for all loading image logic.<br/>
2828
/// <p>
2929
/// Loading by <see cref="HtmlRenderer.Entities.HtmlImageLoadEventArgs"/>.<br/>
30-
/// Loading by calling property/method on bridge object.<br/>
3130
/// Loading by file path.<br/>
3231
/// Loading by URI.<br/>
3332
/// </p>
@@ -49,10 +48,10 @@ internal sealed class ImageLoadHandler : IDisposable
4948
/// <summary>
5049
/// callback raised when image load process is complete with image or without
5150
/// </summary>
52-
private readonly Utils.Action<Image, Rectangle, bool> _loadCompleteCallback;
51+
private readonly Action<Image, Rectangle, bool> _loadCompleteCallback;
5352

5453
/// <summary>
55-
/// the web client used to download image from uri (to cancel on dispose)
54+
/// the web client used to download image from URL (to cancel on dispose)
5655
/// </summary>
5756
private WebClient _client;
5857

@@ -93,7 +92,7 @@ internal sealed class ImageLoadHandler : IDisposable
9392
/// Init.
9493
/// </summary>
9594
/// <param name="loadCompleteCallback">callback raised when image load process is complete with image or without</param>
96-
public ImageLoadHandler(Utils.Action<Image, Rectangle, bool> loadCompleteCallback)
95+
public ImageLoadHandler(Action<Image, Rectangle, bool> loadCompleteCallback)
9796
{
9897
ArgChecker.AssertArgNotNull(loadCompleteCallback, "loadCompleteCallback");
9998

@@ -119,7 +118,7 @@ public Rectangle Rectangle
119118
/// <summary>
120119
/// Set image of this image box by analyzing the src attribute.<br/>
121120
/// Load the image from inline base64 encoded string.<br/>
122-
/// Or from calling property/method on the bridge object that returns image or url to image.<br/>
121+
/// Or from calling property/method on the bridge object that returns image or URL to image.<br/>
123122
/// Or from file path<br/>
124123
/// Or from URI.
125124
/// </summary>
@@ -189,12 +188,12 @@ public void Dispose()
189188
/// Load image from path of image file or uri.
190189
/// </summary>
191190
/// <param name="path">the file path or uri to load image from</param>
192-
public void SetImageFromPath(string path)
191+
private void SetImageFromPath(string path)
193192
{
194193
var uri = CommonUtils.TryGetUri(path);
195194
if (uri != null && uri.Scheme != "file")
196195
{
197-
SetImageFromUri(uri);
196+
SetImageFromUrl(uri);
198197
}
199198
else
200199
{
@@ -214,7 +213,7 @@ public void SetImageFromPath(string path)
214213
/// <summary>
215214
/// Extract image object from inline base64 encoded data in the src of the html img element.
216215
/// </summary>
217-
/// <param name="src">the source that hase the base64 encoded image</param>
216+
/// <param name="src">the source that has the base64 encoded image</param>
218217
/// <returns>image from base64 data string or null if failed</returns>
219218
private static Image GetImageFromData(string src)
220219
{
@@ -307,24 +306,24 @@ private void SetImageFromFileAsync(object source)
307306
/// <summary>
308307
/// Load image from the given URI by downloading it.<br/>
309308
/// Create local file name in temp folder from the URI, if the file already exists use it as it has already been downloaded.
310-
/// If not download the file using <see cref="SetImageFromUriAsync"/>.
309+
/// If not download the file using <see cref="SetImageFromUrlAsync"/>.
311310
/// </summary>
312311
/// <param name="source"></param>
313-
private void SetImageFromUri(Uri source)
312+
private void SetImageFromUrl(Uri source)
314313
{
315314
var filePath = CommonUtils.GetLocalfileName(source);
316315
if (filePath.Exists && filePath.Length > 0)
317316
SetImageFromFile(filePath);
318317
else
319-
ThreadPool.QueueUserWorkItem(SetImageFromUriAsync, new KeyValuePair<Uri, FileInfo>(source, filePath));
318+
ThreadPool.QueueUserWorkItem(SetImageFromUrlAsync, new KeyValuePair<Uri, FileInfo>(source, filePath));
320319
}
321320

322321
/// <summary>
323322
/// Download the requested file in the URI to the given file path.<br/>
324323
/// Use async sockets API to download from web, <see cref="OnDownloadImageCompleted"/>.
325324
/// </summary>
326-
/// <param name="data">key value pair of uri and file info to download the file to</param>
327-
private void SetImageFromUriAsync(object data)
325+
/// <param name="data">key value pair of URL and file info to download the file to</param>
326+
private void SetImageFromUrlAsync(object data)
328327
{
329328
var uri = ((KeyValuePair<Uri, FileInfo>) data).Key;
330329
var filePath = ((KeyValuePair<Uri, FileInfo>) data).Value;
@@ -337,7 +336,7 @@ private void SetImageFromUriAsync(object data)
337336
}
338337
catch (Exception ex)
339338
{
340-
_htmlContainer.ReportError(HtmlRenderErrorType.Image, "Failed to load image from uri: " + uri, ex);
339+
_htmlContainer.ReportError(HtmlRenderErrorType.Image, "Failed to load image from URL: " + uri, ex);
341340
ImageLoadComplete(false);
342341
}
343342
}
@@ -373,15 +372,15 @@ private void OnDownloadImageCompleted(object sender, AsyncCompletedEventArgs e)
373372
}
374373
else
375374
{
376-
_htmlContainer.ReportError(HtmlRenderErrorType.Image, "Failed to load image from uri: " + client.BaseAddress, e.Error);
375+
_htmlContainer.ReportError(HtmlRenderErrorType.Image, "Failed to load image from URL: " + client.BaseAddress, e.Error);
377376
ImageLoadComplete();
378377
}
379378
}
380379
}
381380
}
382381
catch (Exception ex)
383382
{
384-
_htmlContainer.ReportError(HtmlRenderErrorType.Image, "Failed to load image from uri: " + sender, ex);
383+
_htmlContainer.ReportError(HtmlRenderErrorType.Image, "Failed to load image from URL: " + sender, ex);
385384
ImageLoadComplete();
386385
}
387386
}

0 commit comments

Comments
 (0)