#7 improve api documentation and make font descriptor public

2025-10-14 19:05:01 +08:00 · 2018-12-22 17:58:07 +00:00
parent d572af8a52
commit d8b5f00fa0
8 changed files with 237 additions and 41 deletions
--- a/src/UglyToad.PdfPig.Tests/PublicApiScannerTests.cs
+++ b/src/UglyToad.PdfPig.Tests/PublicApiScannerTests.cs
@@ -46,6 +46,10 @@
                "UglyToad.PdfPig.CrossReference.CrossReferenceTable",
                "UglyToad.PdfPig.CrossReference.CrossReferenceType",
                "UglyToad.PdfPig.CrossReference.TrailerDictionary",
+                "UglyToad.PdfPig.Fonts.DescriptorFontFile",
+                "UglyToad.PdfPig.Fonts.FontDescriptor",
+                "UglyToad.PdfPig.Fonts.FontDescriptorFlags",
+                "UglyToad.PdfPig.Fonts.FontStretch",
                "UglyToad.PdfPig.Tokens.ArrayToken",
                "UglyToad.PdfPig.Tokens.BooleanToken",
                "UglyToad.PdfPig.Tokens.CommentToken",
--- a/src/UglyToad.PdfPig/Fonts/DescriptorFontFile.cs
+++ b/src/UglyToad.PdfPig/Fonts/DescriptorFontFile.cs
@@ -3,7 +3,7 @@
    using Tokens;

    /// <summary>
-    /// The bytes of the stream containing the font program.
+    /// Holds the location and type of the stream containing the corresponding font program.
    /// </summary>
    /// <remarks>
    /// This can either be a Type 1 font program (FontFile - <see cref="FontFileType.Type1"/>),
@@ -11,25 +11,43 @@
    /// whose format is given by the Subtype of the stream dictionary (FontFile3 - <see cref="FontFileType.FromSubtype"/>).
    /// At most only 1 of these entries is present.
    /// </remarks>
-    internal class DescriptorFontFile
+    public class DescriptorFontFile
    {
+        /// <summary>
+        /// The object containing the stream for this font program.
+        /// </summary>
        public IndirectReferenceToken ObjectKey { get; }
-
-        public byte[] FileBytes { get; }
-
+        
+        /// <summary>
+        /// The type of the font program represented by this descriptor.
+        /// </summary>
        public FontFileType FileType { get; }

+        /// <summary>
+        /// Create a new <see cref="DescriptorFontFile"/>.
+        /// </summary>
        public DescriptorFontFile(IndirectReferenceToken key, FontFileType fileType)
        {
            ObjectKey = key;
-            FileBytes = new byte[0];
            FileType = fileType;
        }

+        /// <summary>
+        /// The type of font program represented by the stream used by this font descriptor.
+        /// </summary>
        public enum FontFileType
        {
+            /// <summary>
+            /// A Type 1 font program.
+            /// </summary>
            Type1,
+            /// <summary>
+            /// A TrueType font program.
+            /// </summary>
            TrueType,
+            /// <summary>
+            /// A type defined by the stream dictionary's Subtype entry.
+            /// </summary>
            FromSubtype
        }
    }
--- a/src/UglyToad.PdfPig/Fonts/FontDescriptor.cs
+++ b/src/UglyToad.PdfPig/Fonts/FontDescriptor.cs
@@ -5,13 +5,11 @@
    using Util.JetBrains.Annotations;

    /// <summary>
-    /// Specifies metrics and attributes of a simple font or CID Font
-    /// for the whole font rather than per-glyph.
+    /// Specifies metrics and attributes of a simple font or CID Font for the whole font rather than per-glyph.
    /// </summary>
    /// <remarks>
    /// <para>
-    /// Provides information to enable consumer applications to
-    /// find a substitute font when the font is unavailable.
+    /// Provides information to enable consumer applications to find a substitute font when the font is unavailable.
    /// </para>
    /// <para>
    /// Font descriptors are not used with Type 0 fonts.
@@ -20,7 +18,7 @@
    /// A font descriptor is a dictionary used to specify various attributes.
    /// </para>
    /// </remarks>
-    internal class FontDescriptor
+    public class FontDescriptor
    {
        /// <summary>
        /// The PostScript name for the font.
@@ -32,13 +30,13 @@
        /// The preferred font family.
        /// </summary>
        /// <remarks>Optional</remarks>
-        public string FontFamily { get; set; }
+        public string FontFamily { get; }

        /// <summary>
        /// The font stretch value.
        /// </summary>
        /// <remarks>Optional</remarks>
-        public FontStretch Stretch { get; set; } = FontStretch.Normal;
+        public FontStretch Stretch { get; }

        /// <summary>
        /// The weight/thickness of the font.
@@ -55,20 +53,20 @@
        /// 900<br/>
        /// Optional
        /// </remarks>
-        public decimal FontWeight { get; set; } = 400;
+        public decimal FontWeight { get; }

        /// <summary>
-        /// Defines various font characteristics. See <see cref="FontFlags"/>.
+        /// Defines various font characteristics. See <see cref="FontDescriptorFlags"/>.
        /// </summary>
        /// <remarks>Required</remarks>
-        public FontFlags Flags { get; }
+        public FontDescriptorFlags Flags { get; }

        /// <summary>
        /// A rectangle in glyph coordinates which represents the smallest
        /// rectangle containing all glyphs of the font.
        /// </summary>
        /// <remarks>Required (Except Type 3)</remarks>
-        public PdfRectangle BoundingBox { get; set; }
+        public PdfRectangle BoundingBox { get; }

        /// <summary>
        /// The angle in degrees counter-clockwise from vertical of the vertical
@@ -77,88 +75,228 @@
        /// </summary>
        /// <example>9 o'clock is represented by 90 degrees. 3 o'clock is -90 degrees.</example>
        /// <remarks>Required</remarks>
-        public decimal ItalicAngle { get; set; }
+        public decimal ItalicAngle { get; }

        /// <summary>
        /// The maximum height above the baseline for any glyph from this font (except for accents).
        /// </summary>
        /// <remarks>Required (Except Type 3)</remarks>
-        public decimal Ascent { get; set; }
+        public decimal Ascent { get; }

        /// <summary>
        /// The maximum depth below the baseline for any glyph in the font. This is negative.
        /// </summary>
        /// <remarks>Required (Except Type 3)</remarks>
-        public decimal Descent { get; set; }
+        public decimal Descent { get; }

        /// <summary>
        /// The spacing between consecutive lines of text. Default 0.
        /// </summary>
        /// <remarks>Optional</remarks>
-        public decimal Leading { get; set; }
+        public decimal Leading { get; }

        /// <summary>
        /// The vertical distance of the top of flat capital letters from the baseline.
        /// </summary>
        /// <remarks>Required (Where Latin Characters, Except Type 3)</remarks>
-        public decimal CapHeight { get; set; }
+        public decimal CapHeight { get; }

        /// <summary>
        /// The x height of the font. The vertical distance of the top of flat non-ascending
        /// lowercase letters (e.g. x) from the baseline. Default 0.
        /// </summary>
        /// <remarks>Optional</remarks>
-        public decimal XHeight { get; set; }
+        public decimal XHeight { get; }

        /// <summary>
        /// The horizontal thickness of vertical stems of glyphs.
        /// </summary>
        /// <remarks>Required (Except Type 3)</remarks>
-        public decimal StemVertical { get; set; }
+        public decimal StemVertical { get; }

        /// <summary>
        /// The vertical thickness of horizontal stems of glyphs. Default 0.
        /// </summary>
        /// <remarks>Optional</remarks>
-        public decimal StemHorizontal { get; set; }
+        public decimal StemHorizontal { get; }

        /// <summary>
        /// The average glyph width in the font. Default 0.
        /// </summary>
        /// <remarks>Optional</remarks>
-        public decimal AverageWidth { get; set; }
+        public decimal AverageWidth { get; }

        /// <summary>
        /// The maximum glyph width in the font. Default 0.
        /// </summary>
        /// <remarks>Optional</remarks>
-        public decimal MaxWidth { get; set; }
+        public decimal MaxWidth { get; }

        /// <summary>
        /// The width for character codes whose widths are not present in the Widths
        /// array of the font dictionary. Default 0.
        /// </summary>
        /// <remarks>Optional</remarks>
-        public decimal MissingWidth { get; set; }
+        public decimal MissingWidth { get; }

        /// <summary>
        /// The bytes of the font program.
        /// </summary>
        /// <remarks>Optional</remarks>
        [CanBeNull]
-        public DescriptorFontFile FontFile { get; set; }
+        public DescriptorFontFile FontFile { get; }

        /// <summary>
        /// The character names defined in a font subset.
        /// </summary>
        /// <remarks>Optional</remarks>
        [CanBeNull]
-        public string CharSet { get; set; }
+        public string CharSet { get; }

-        public FontDescriptor(NameToken name, FontFlags flags)
+        /// <summary>
+        /// Create a new <see cref="FontDescriptor"/>.
+        /// </summary>
+        public FontDescriptor(Builder builder)
        {
-            FontName = name;
-            Flags = flags;
+            FontName = builder.FontName;
+            FontFamily = builder.FontFamily;
+            Stretch = builder.Stretch;
+            FontWeight = builder.FontWeight;
+            Flags = builder.Flags;
+            BoundingBox = builder.BoundingBox;
+            ItalicAngle = builder.ItalicAngle;
+            Ascent = builder.Ascent;
+            Descent = builder.Descent;
+            Leading = builder.Leading;
+            CapHeight = builder.CapHeight;
+            XHeight = builder.XHeight;
+            StemVertical = builder.StemVertical;
+            StemHorizontal = builder.StemHorizontal;
+            AverageWidth = builder.AverageWidth;
+            MaxWidth = builder.MaxWidth;
+            MissingWidth = builder.MissingWidth;
+            FontFile = builder.FontFile;
+            CharSet = builder.CharSet;
+        }
+
+        /// <summary>
+        /// Provides a mutable way to construct a <see cref="FontDescriptor"/>.
+        /// </summary>
+        public class Builder
+        {
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.FontName"/>.
+            /// </summary>
+            public NameToken FontName { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.FontFamily"/>.
+            /// </summary>
+            public string FontFamily { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.Stretch"/>.
+            /// </summary>
+            public FontStretch Stretch { get; set; } = FontStretch.Normal;
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.FontWeight"/>.
+            /// </summary>
+            public decimal FontWeight { get; set; } = 400;
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.Flags"/>.
+            /// </summary>
+            public FontDescriptorFlags Flags { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.BoundingBox"/>.
+            /// </summary>
+            public PdfRectangle BoundingBox { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.ItalicAngle"/>.
+            /// </summary>
+            public decimal ItalicAngle { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.Ascent"/>.
+            /// </summary>
+            public decimal Ascent { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.Descent"/>.
+            /// </summary>
+            public decimal Descent { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.Leading"/>.
+            /// </summary>
+            public decimal Leading { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.CapHeight"/>.
+            /// </summary>
+            public decimal CapHeight { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.XHeight"/>.
+            /// </summary>
+            public decimal XHeight { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.StemVertical"/>.
+            /// </summary>
+            public decimal StemVertical { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.StemHorizontal"/>.
+            /// </summary>
+            public decimal StemHorizontal { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.AverageWidth"/>.
+            /// </summary>
+            public decimal AverageWidth { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.MaxWidth"/>.
+            /// </summary>
+            public decimal MaxWidth { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.MissingWidth"/>.
+            /// </summary>
+            public decimal MissingWidth { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.FontFile"/>.
+            /// </summary>
+            [CanBeNull]
+            public DescriptorFontFile FontFile { get; set; }
+
+            /// <summary>
+            /// Sets the <see cref="FontDescriptor.CharSet"/>.
+            /// </summary>
+            [CanBeNull]
+            public string CharSet { get; set; }
+
+            /// <summary>
+            /// Create a new <see cref="Builder"/>.
+            /// </summary>
+            public Builder(NameToken fontName, FontDescriptorFlags flags)
+            {
+                FontName = fontName;
+                Flags = flags;
+            }
+
+            /// <summary>
+            /// Create the <see cref="FontDescriptor"/> with values from this builder.
+            /// </summary>
+            public FontDescriptor Build()
+            {
+                return new FontDescriptor(this);
+            }
        }
    }
 }
--- a/src/UglyToad.PdfPig/Fonts/FontDescriptorFlags.cs
+++ b/src/UglyToad.PdfPig/Fonts/FontDescriptorFlags.cs
@@ -2,9 +2,15 @@
 {
    using System;

+    /// <summary>
+    /// Specifies various characteristics of a font.
+    /// </summary>
    [Flags]
-    internal enum FontFlags
+    public enum FontDescriptorFlags
    {
+        /// <summary>
+        /// No flags are set.
+        /// </summary>
        None = 0,
        /// <summary>
        /// All glyphs have the same width.
--- a/src/UglyToad.PdfPig/Fonts/FontStretch.cs
+++ b/src/UglyToad.PdfPig/Fonts/FontStretch.cs
@@ -3,17 +3,47 @@
    /// <summary>
    /// The font stretch.
    /// </summary>
-    internal enum FontStretch
+    public enum FontStretch
    {
+        /// <summary>
+        /// Not specified or not a recognised value.
+        /// </summary>
        Unknown = -1,
+        /// <summary>
+        /// Ultra Condensed.
+        /// </summary>
        UltraCondensed,
+        /// <summary>
+        /// Extra Condensed.
+        /// </summary>
        ExtraCondensed,
+        /// <summary>
+        /// Condensed.
+        /// </summary>
        Condensed,
+        /// <summary>
+        /// Semi Condensed.
+        /// </summary>
        SemiCondensed,
+        /// <summary>
+        /// Normal
+        /// </summary>
        Normal,
+        /// <summary>
+        /// Semi Expanded
+        /// </summary>
        SemiExpanded,
+        /// <summary>
+        /// Expanded
+        /// </summary>
        Expanded,
+        /// <summary>
+        /// Extra Expanded
+        /// </summary>
        ExtraExpanded,
+        /// <summary>
+        /// Ultra Expanded
+        /// </summary>
        UltraExpanded
    }
 }
--- a/src/UglyToad.PdfPig/Fonts/Parser/EncodingReader.cs
+++ b/src/UglyToad.PdfPig/Fonts/Parser/EncodingReader.cs
@@ -97,7 +97,7 @@
        {
            Encoding encoding;
            // Symbolic fonts default to standard encoding.
-            if (descriptor?.Flags.HasFlag(FontFlags.Symbolic) == true)
+            if (descriptor?.Flags.HasFlag(FontDescriptorFlags.Symbolic) == true)
            {
                encoding = StandardEncoding.Instance;
            }
--- a/src/UglyToad.PdfPig/Fonts/Parser/Parts/FontDescriptorFactory.cs
+++ b/src/UglyToad.PdfPig/Fonts/Parser/Parts/FontDescriptorFactory.cs
@@ -25,7 +25,7 @@
            var charSet = GetCharSet(dictionary);
            var fontFile = GetFontFile(dictionary);

-            return new FontDescriptor(name, flags)
+            return new FontDescriptor.Builder(name, flags)
            {
                 FontFamily = family,
                 Stretch = stretch,
@@ -44,7 +44,7 @@
                 MissingWidth = GetDecimalOrDefault(dictionary, NameToken.MissingWidth),
                 FontFile = fontFile,
                 CharSet = charSet
-            };
+            }.Build();
        }

        private static decimal GetDecimalOrDefault(DictionaryToken dictionary, NameToken name)
@@ -100,7 +100,7 @@
            return stretchName.ConvertToFontStretch();
        }

-        private static FontFlags GetFlags(DictionaryToken dictionary, bool isLenientParsing)
+        private static FontDescriptorFlags GetFlags(DictionaryToken dictionary, bool isLenientParsing)
        {
            var flags = dictionary.GetIntOrDefault(NameToken.Flags, -1);

@@ -116,7 +116,7 @@
                }
            }

-            return (FontFlags) flags;
+            return (FontDescriptorFlags) flags;
        }

        private static PdfRectangle GetBoundingBox(DictionaryToken dictionary)
--- a/src/UglyToad.PdfPig/Writer/TrueTypeWritingFont.cs
+++ b/src/UglyToad.PdfPig/Writer/TrueTypeWritingFont.cs
@@ -69,7 +69,7 @@
                { NameToken.Type, NameToken.FontDescriptor },
                { NameToken.FontName, baseFont },
                // TODO: get flags TrueTypeEmbedder.java
-                { NameToken.Flags, new NumericToken((int)FontFlags.Symbolic) },
+                { NameToken.Flags, new NumericToken((int)FontDescriptorFlags.Symbolic) },
                { NameToken.FontBbox, GetBoundingBox(bbox, scaling) },
                { NameToken.ItalicAngle, new NumericToken(postscript.ItalicAngle) },
                { NameToken.Ascent, new NumericToken(hhead.Ascender * scaling) },