@@ -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>
0 commit comments