Added more examples for documentation (text)

Source/QuestPDF.DocumentationExamples/ImageExamples.cs

@@ -0,0 +1,320 @@
+using QuestPDF.Elements;
+using QuestPDF.Fluent;
+using QuestPDF.Helpers;
+using QuestPDF.Infrastructure;
+using SkiaSharp;
+
+namespace QuestPDF.DocumentationExamples;
+
+public class ImageExamples
+{
+    [Test]
+    public void Example()
+    {
+        Document
+            .Create(document =>
+            {
+                document.Page(page =>
+                {
+                    page.MinSize(new PageSize(0, 0));
+                    page.MaxSize(new PageSize(400, 1000));
+                    page.DefaultTextStyle(x => x.FontSize(20));
+                    page.Margin(25);
+
+                    page.Content()
+                        .Grid(grid =>
+                        {
+                            grid.Columns(2);
+                            grid.Spacing(10);
+                            
+                            grid.Item(2).Text("My photo gallery:").Bold();
+                            
+                            grid.Item().Image("photo-gallery-1.jpg");
+                            grid.Item().Image("photo-gallery-2.jpg");
+                            grid.Item().Image("photo-gallery-3.jpg");
+                            grid.Item().Image("photo-gallery-4.jpg");
+                        });
+                });
+            })
+            .GenerateImages(x => "image-example.webp", new ImageGenerationSettings() { ImageFormat = ImageFormat.Webp, ImageCompressionQuality = ImageCompressionQuality.VeryHigh, RasterDpi = 144 });
+    }
+    
+    [Test]
+    public void ImageScaling()
+    {
+        Document
+            .Create(document =>
+            {
+                document.Page(page =>
+                {
+                    page.MinSize(new PageSize(0, 0));
+                    page.MaxSize(new PageSize(1000, 1500));
+                    page.Margin(25);
+
+                    page.Content()
+                        .Column(column =>
+                        {
+                            column.Item().PaddingBottom(5).Text("FitWidth").Bold();
+                            column.Item()
+                                .Width(200)
+                                .Height(150)
+                                .Border(4)
+                                .BorderColor(Colors.Red.Medium)
+                                .Image("photo.jpg")
+                                .FitWidth();
+
+                            column.Item().Height(15);
+
+                            column.Item().PaddingBottom(5).Text("FitHeight").Bold();
+                            column.Item()
+                                .Width(200)
+                                .Height(100)
+                                .Border(4)
+                                .BorderColor(Colors.Red.Medium)
+                                .Image("photo.jpg")
+                                .FitHeight();
+                            
+                            column.Item().Height(15);
+
+                            column.Item().PaddingBottom(5).Text("FitArea 1").Bold();
+                            column.Item()
+                                .Width(200)
+                                .Height(100)
+                                .Border(4)
+                                .BorderColor(Colors.Red.Medium)
+                                .Image("photo.jpg")
+                                .FitArea();
+                            
+                            column.Item().Height(15);
+                            
+                            column.Item().PaddingBottom(5).Text("FitArea 2").Bold();
+                            column.Item()
+                                .Width(200)
+                                .Height(150)
+                                .Border(4)
+                                .BorderColor(Colors.Red.Medium)
+                                .Image("photo.jpg")
+                                .FitArea();
+                            
+                            column.Item().Height(15);
+
+                            column.Item().PaddingBottom(5).Text("FitUnproportionally").Bold();
+                            column.Item()
+                                .Width(200)
+                                .Height(50)
+                                .Border(4)
+                                .BorderColor(Colors.Red.Medium)
+                                .Image("photo.jpg")
+                                .FitUnproportionally();
+                        });
+                });
+            })
+            .GenerateImages(x => "image-scaling.webp", new ImageGenerationSettings() { ImageFormat = ImageFormat.Webp, ImageCompressionQuality = ImageCompressionQuality.VeryHigh, RasterDpi = 144 });
+    }
+    
+    [Test]
+    public void DpiSetting()
+    {
+        Document
+            .Create(document =>
+            {
+                document.Page(page =>
+                {
+                    page.MinSize(new PageSize(0, 0));
+                    page.MaxSize(new PageSize(400, 1000));
+                    page.Margin(25);
+
+                    page.Content()
+                        .Column(column =>
+                        {
+                            column.Spacing(10);
+    
+                            // lower raster dpi = lower resolution, pixelation
+                            column
+                                .Item()
+                                .Image("photo.jpg")
+                                .WithRasterDpi(16);
+    
+                            // higher raster dpi = higher resolution
+                            column
+                                .Item()
+                                .Image("photo.jpg")
+                                .WithRasterDpi(288);
+                        });
+                });
+            })
+            .GenerateImages(x => "image-dpi.webp", new ImageGenerationSettings() { ImageFormat = ImageFormat.Webp, ImageCompressionQuality = ImageCompressionQuality.VeryHigh, RasterDpi = 144 });
+    }
+    
+    [Test]
+    public void CompressionSetting()
+    {
+        Document
+            .Create(document =>
+            {
+                document.Page(page =>
+                {
+                    page.MinSize(new PageSize(0, 0));
+                    page.MaxSize(new PageSize(400, 1000));
+                    page.Margin(25);
+
+                    page.Content()
+                        .Column(column =>
+                        {
+                            column.Spacing(10);
+    
+                            // low quality = smaller output file
+                            column
+                                .Item()
+                                .Image("photo.jpg")
+                                .WithCompressionQuality(ImageCompressionQuality.VeryLow);
+        
+                            // high quality / fidelity = larger output file
+                            column
+                                .Item()
+                                .Image("photo.jpg")
+                                .WithCompressionQuality(ImageCompressionQuality.VeryHigh);
+                        });
+                });
+            })
+            .GenerateImages(x => "image-compression.webp", new ImageGenerationSettings() { ImageFormat = ImageFormat.Webp, ImageCompressionQuality = ImageCompressionQuality.VeryHigh, RasterDpi = 144 });
+    }
+    
+    [Test]
+    public void GlobalSettings()
+    {
+        Document
+            .Create(document =>
+            {
+                document.Page(page =>
+                {
+                    page.Content().Image("photo.jpg");
+                });
+            })
+            .WithSettings(new DocumentSettings
+            {
+                // default: ImageCompressionQuality.High;
+                ImageCompressionQuality = ImageCompressionQuality.Medium,
+
+                // default: 288
+                ImageRasterDpi = 14
+            })
+            .GeneratePdf("image-global-settings.pdf");
+    }
+    
+    [Test]
+    public void SharedImages()
+    {
+        var image = Image.FromFile("checkbox.png");
+        
+        Document
+            .Create(document =>
+            {
+                document.Page(page =>
+                {
+                    page.MinSize(new PageSize(0, 0));
+                    page.MaxSize(new PageSize(350, 1000));
+                    page.DefaultTextStyle(x => x.FontSize(20));
+                    page.Margin(25);
+
+                    page.Content()
+                        .Column(column =>
+                        {
+                            column.Spacing(15);
+                            
+                            foreach (var i in Enumerable.Range(0, 5))
+                            {
+                                column.Item().Row(row =>
+                                {
+                                    row.AutoItem().Width(28).Image(image);
+                                    row.RelativeItem().PaddingLeft(8).AlignMiddle().Text(Placeholders.Label());
+                                });
+                            }
+                        });
+                });
+            })
+            .GenerateImages(x => "image-shared.webp", new ImageGenerationSettings() { ImageFormat = ImageFormat.Webp, ImageCompressionQuality = ImageCompressionQuality.VeryHigh, RasterDpi = 144 });
+    }
+    
+    [Test]
+    public void DynamicImage()
+    {
+        Document
+            .Create(document =>
+            {
+                document.Page(page =>
+                {
+                    page.MinSize(new PageSize(0, 0));
+                    page.MaxSize(new PageSize(350, 1000));
+                    page.DefaultTextStyle(x => x.FontSize(20));
+                    page.PageColor(Colors.Grey.Lighten3);
+                    page.Margin(25);
+
+                    page.Content()
+                        .Column(column =>
+                        {
+                            column.Spacing(10);
+
+                            column.Item().Text(text =>
+                            {
+                                text.Span("The national flag of Poland").Bold();
+                                text.Span(" consists of two horizontal stripes of equal width, the upper one white and the lower one red.");
+                            });
+                            
+                            column.Item()
+                                .AspectRatio(80 / 50f)
+                                .Border(2)
+                                .Image(GenerateNationalFlagOfPoland);
+                        });
+                    
+                    byte[]? GenerateNationalFlagOfPoland(GenerateDynamicImageDelegatePayload context)
+                    {
+                        using var whitePaint = new SKPaint
+                        {
+                            Color = SKColors.White,
+                        };
+                                    
+                        using var redPaint = new SKPaint
+                        {
+                            Color = SKColor.Parse("#BB0A30"),
+                        };
+
+                        using var bitmap = new SKBitmap(context.ImageSize.Width, context.ImageSize.Height);
+                        using var canvas = new SKCanvas(bitmap);
+                                    
+                        canvas.DrawRect(0, 0, context.ImageSize.Width, context.ImageSize.Height / 2, whitePaint);
+                        canvas.DrawRect(0, context.ImageSize.Height / 2, context.ImageSize.Width, context.ImageSize.Height, redPaint);
+                        canvas.Flush();
+
+                        using var content = bitmap.Encode(SKEncodedImageFormat.Png, 100);
+                        return content.ToArray();
+                    }
+                });
+            })
+            .GenerateImages(x => "image-dynamic.webp", new ImageGenerationSettings() { ImageFormat = ImageFormat.Webp, ImageCompressionQuality = ImageCompressionQuality.VeryHigh, RasterDpi = 144 });
+    }
+    
+    [Test]
+    public void SvgSupport()
+    {
+        Document
+            .Create(document =>
+            {
+                document.Page(page =>
+                {
+                    page.Size(PageSizes.A7.Portrait());
+                    page.Margin(25);
+
+                    // page.Content()
+                    //     .Svg("pdf-icon.svg")
+                    //     .FitArea();
+
+                    var svgContent = File.ReadAllText("pdf-icon.svg");
+                    
+                    page.Content()
+                        .Svg(svgContent);
+                });
+            })
+            .GeneratePdf("image-svg.pdf");
+    }
+}

Source/QuestPDF.DocumentationExamples/QuestPDF.DocumentationExamples.csproj

@@ -15,6 +15,7 @@
         <PackageReference Include="NUnit" Version="3.14.0"/>
         <PackageReference Include="NUnit.Analyzers" Version="3.9.0"/>
         <PackageReference Include="NUnit3TestAdapter" Version="4.5.0"/>
+        <PackageReference Include="SkiaSharp" Version="3.116.1" />
     </ItemGroup>
 
     <ItemGroup>
@@ -41,6 +42,27 @@
       <None Update="unit-test-failed-icon.png">
         <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
       </None>
+      <None Update="photo.jpg">
+        <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+      </None>
+      <None Update="photo-gallery-1.jpg">
+        <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+      </None>
+      <None Update="photo-gallery-2.jpg">
+        <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+      </None>
+      <None Update="photo-gallery-3.jpg">
+        <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+      </None>
+      <None Update="photo-gallery-4.jpg">
+        <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+      </None>
+      <None Update="checkbox.png">
+        <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+      </None>
+      <None Update="pdf-icon.svg">
+        <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+      </None>
     </ItemGroup>
 
 </Project>

Source/QuestPDF.DocumentationExamples/pdf-icon.svg

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="75mm" height="92mm" viewBox="0 0 76 93">
+    <g transform="translate(53.548057 -183.975276) scale(1.4843)">
+        <path fill="#ff2116" d="M-29.632812 123.94727c-3.551967 0-6.44336 2.89347-6.44336 6.44531v49.49804c0 3.55185 2.891393 6.44532 6.44336 6.44532H8.2167969c3.5519661 0 6.4433591-2.89335 6.4433591-6.44532v-40.70117s.101353-1.19181-.416015-2.35156c-.484969-1.08711-1.275391-1.84375-1.275391-1.84375a1.0584391 1.0584391 0 0 0-.0059-.008l-9.3906254-9.21094a1.0584391 1.0584391 0 0 0-.015625-.0156s-.8017392-.76344-1.9902344-1.27344c-1.39939552-.6005-2.8417968-.53711-2.8417968-.53711l.021484-.002z" color="#000" font-family="sans-serif" overflow="visible" paint-order="markers fill stroke" style="line-height:normal;font-variant-ligatures:normal;font-variant-position:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-alternates:normal;font-feature-settings:normal;text-indent:0;text-align:start;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000000;text-transform:none;text-orientation:mixed;white-space:normal;shape-padding:0;isolation:auto;mix-blend-mode:normal;solid-color:#000000;solid-opacity:1"/>
+        <path fill="#f5f5f5" d="M-29.632812 126.06445h28.3789058a1.0584391 1.0584391 0 0 0 .021484 0s1.13480448.011 1.96484378.36719c.79889772.34282 1.36536982.86176 1.36914062.86524.0000125.00001.00391.004.00391.004l9.3671868 9.18945s.564354.59582.837891 1.20899c.220779.49491.234375 1.40039.234375 1.40039a1.0584391 1.0584391 0 0 0-.002.0449v40.74609c0 2.41592-1.910258 4.32813-4.3261717 4.32813H-29.632812c-2.415914 0-4.326172-1.91209-4.326172-4.32813v-49.49804c0-2.41603 1.910258-4.32813 4.326172-4.32813z" color="#000" font-family="sans-serif" overflow="visible" paint-order="markers fill stroke" style="line-height:normal;font-variant-ligatures:normal;font-variant-position:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-alternates:normal;font-feature-settings:normal;text-indent:0;text-align:start;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000000;text-transform:none;text-orientation:mixed;white-space:normal;shape-padding:0;isolation:auto;mix-blend-mode:normal;solid-color:#000000;solid-opacity:1"/>
+        <path fill="#ff2116" d="M-23.40766 161.09299c-1.45669-1.45669.11934-3.45839 4.39648-5.58397l2.69124-1.33743 1.04845-2.29399c.57665-1.26169 1.43729-3.32036 1.91254-4.5748l.8641-2.28082-.59546-1.68793c-.73217-2.07547-.99326-5.19438-.52872-6.31588.62923-1.51909 2.69029-1.36323 3.50626.26515.63727 1.27176.57212 3.57488-.18329 6.47946l-.6193 2.38125.5455.92604c.30003.50932 1.1764 1.71867 1.9475 2.68743l1.44924 1.80272 1.8033728-.23533c5.72900399-.74758 7.6912472.523 7.6912472 2.34476 0 2.29921-4.4984914 2.48899-8.2760865-.16423-.8499666-.59698-1.4336605-1.19001-1.4336605-1.19001s-2.3665326.48178-3.531704.79583c-1.202707.32417-1.80274.52719-3.564509 1.12186 0 0-.61814.89767-1.02094 1.55026-1.49858 2.4279-3.24833 4.43998-4.49793 5.1723-1.3991.81993-2.86584.87582-3.60433.13733zm2.28605-.81668c.81883-.50607 2.47616-2.46625 3.62341-4.28553l.46449-.73658-2.11497 1.06339c-3.26655 1.64239-4.76093 3.19033-3.98386 4.12664.43653.52598.95874.48237 2.01093-.16792zm21.21809-5.95578c.80089-.56097.68463-1.69142-.22082-2.1472-.70466-.35471-1.2726074-.42759-3.1031574-.40057-1.1249.0767-2.9337647.3034-3.2403347.37237 0 0 .993716.68678 1.434896.93922.58731.33544 2.0145161.95811 3.0565161 1.27706 1.02785.31461 1.6224.28144 2.0729-.0409zm-8.53152-3.54594c-.4847-.50952-1.30889-1.57296-1.83152-2.3632-.68353-.89643-1.02629-1.52887-1.02629-1.52887s-.4996 1.60694-.90948 2.57394l-1.27876 3.16076-.37075.71695s1.971043-.64627 2.97389-.90822c1.0621668-.27744 3.21787-.70134 3.21787-.70134zm-2.74938-11.02573c.12363-1.0375.1761-2.07346-.15724-2.59587-.9246-1.01077-2.04057-.16787-1.85154 2.23517.0636.8084.26443 2.19033.53292 3.04209l.48817 1.54863.34358-1.16638c.18897-.64151.47882-2.02015.64411-3.06364z"/>
+        <path fill="#2c2c2c" d="M-20.930423 167.83862h2.364986q1.133514 0 1.840213.2169.706698.20991 1.189489.9446.482795.72769.482795 1.75625 0 .94459-.391832 1.6233-.391833.67871-1.056548.97958-.65772.30087-2.02913.30087h-.818651v3.72941h-1.581322zm1.581322 1.22447v3.33058h.783664q1.049552 0 1.44838-.39184.405826-.39183.405826-1.27345 0-.65772-.265887-1.06355-.265884-.41282-.587747-.50378-.314866-.098-1.000572-.098zm5.50664-1.22447h2.148082q1.560333 0 2.4909318.55276.9375993.55276 1.4133973 1.6443.482791 1.09153.482791 2.42096 0 1.3994-.4338151 2.49793-.4268149 1.09153-1.3154348 1.76324-.8816233.67172-2.5189212.67172h-2.267031zm1.581326 1.26645v7.018h.657715q1.378411 0 2.001144-.9516.6227329-.95858.6227329-2.5539 0-3.5125-2.6238769-3.5125zm6.4722254-1.26645h5.30372941v1.26645H-4.2075842v2.85478h2.9807225v1.26646h-2.9807225v4.16322h-1.5813254z" font-family="Franklin Gothic Medium Cond" letter-spacing="0" style="line-height:125%;-inkscape-font-specification:'Franklin Gothic Medium Cond'" word-spacing="4.26000023"/>
+    </g>
+</svg>

Source/QuestPDF/Elements/Image.cs

@@ -55,8 +55,8 @@ namespace QuestPDF.Elements
         {
             var originalImage = DocumentImage.SkImage;
             
-            if (UseOriginalImage)
-                return originalImage;
+            // if (UseOriginalImage)
+            //     return originalImage;
             
             var request = new GetImageVersionRequest
             {

Source/QuestPDF/Resources/Documentation.xml

@@ -59,9 +59,11 @@
     
     <doc for="image.rasterDPI">
         <summary>
-            <para>Specifies the DPI (dots-per-inch) for rasterizing images.</para>
+            <para>
+                Specifies the DPI (dots-per-inch) for rasterizing images, which is a measure of an image's resolution that indicates how many individual dots (or pixels) fit into one inch of a printed image. 
+                Higher DPI values result in greater detail and sharpness, making images appear clearer when printed, while lower DPI values can cause images to look blurry or pixelated.
+            </para>
             <para>The target resolution is computed by multiplying the DPI with the physical image size on the document.</para>
-            <para>Higher DPI results in superior image quality but may increase the output file size.</para>
             <para>Default DPI value is 288 DPI.</para>
         </summary>
         
@@ -76,7 +78,10 @@
 
     <doc for="image.compressionQuality">
         <summary>
-            <para>Controls the balance between encoding quality and file size.</para>
+            <para>
+                Controls the balance between an image's file size and its visual fidelity during compression.
+                Higher quality values preserve more detail with larger file sizes, while lower values reduce file size at the cost of potential image degradation, such as blurriness or artifacts.
+            </para>
             <para>Opaque images are JPEG-encoded based on this setting, while images with an alpha channel default to PNG format, disregarding this option.</para>
             <para>Default is set to "high quality".</para>
         </summary>