hexapdf 0.32.2 → 0.34.0

data/lib/hexapdf/configuration.rb

@@ -44,12 +44,12 @@ module HexaPDF
   # == Overview
   #
   # HexaPDF allows detailed control over many aspects of PDF manipulation. If there is a need to
-  # use a certain default value somewhere, it is defined as configuration options so that it can
+  # use a certain default value somewhere, it is defined as a configuration option so that it can
   # easily be changed.
   #
   # Some options are defined as global options because they are needed on the class level - see
-  # HexaPDF::GlobalConfiguration[index.html#GlobalConfiguration]. Other options can be configured for
-  # individual documents as they allow to fine-tune some behavior - see
+  # HexaPDF::GlobalConfiguration[index.html#GlobalConfiguration]. Other options can be configured
+  # for individual documents as they allow to fine-tune some behavior - see
   # HexaPDF::DefaultDocumentConfiguration[index.html#DefaultDocumentConfiguration].
   #
   # A configuration option name is dot-separted to provide a hierarchy of option names. For
@@ -155,9 +155,6 @@ module HexaPDF
   #    A boolean specifying whether an AcroForm field's appearances should automatically be
   #    generated if they are missing.
   #
-  # acro_form.text_field.default_width::
-  #    A number specifying the default width of AcroForm text fields which should be auto-sized.
-  #
   # acro_form.default_font_size::
   #    A number specifying the default font size of AcroForm text fields which should be auto-sized.
   #
@@ -248,7 +245,7 @@ module HexaPDF
   #
   #    The most often used filters are implemented and readily available.
   #
-  #    See PDF1.7 s7.4.1, ADB sH.3 3.3
+  #    See PDF2.0 s7.4.1, ADB sH.3 3.3
   #
   # font.map::
   #    Defines a mapping from font names and variants to font files.
@@ -271,14 +268,22 @@ module HexaPDF
   #
   #    The value needs to be an object that responds to \#call(character, font_wrapper) where
   #    +character+ is the Unicode character for the missing glyph and returns a substitute glyph to
-  #    be used instead.
+  #    be used instead. This substitute glyph needs to be from the same font, i.e. it needs to be
+  #    created through the provided +font_wrapper+ instance.
   #
   #    The +font_wrapper+ argument is the used font wrapper object, e.g.
   #    HexaPDF::Font::TrueTypeWrapper. To access the HexaPDF::Document instance from which this hook
   #    was called, you can use +font_wrapper.pdf_object.document+.
   #
   #    The default implementation returns an object of class HexaPDF::Font::InvalidGlyph which, when
-  #    not removed before encoding, will raise an error.
+  #    not removed before encoding, will raise a HexaPDF::MissingGlyphError.
+  #
+  #    If a replacement glyph should be displayed instead of an error, the following provides a good
+  #    starting implementation:
+  #
+  #      doc.config['font.on_missing_glyph'] = lambda do |character, font_wrapper|
+  #        font_wrapper.custom_glyph(font_wrapper.font_type == :Type1 ? :question : 0, character)
+  #      end
   #
   # font.on_missing_unicode_mapping::
   #    Callback hook when a character code point cannot be converted to a Unicode character.
@@ -298,11 +303,6 @@ module HexaPDF
   #
   #    See the HexaPDF::FontLoader module for information on how to implement a font loader object.
   #
-  # graphic_object.map::
-  #    A mapping from graphic object names to graphic object factories.
-  #
-  #    See HexaPDF::Content::GraphicObject for more information.
-  #
   # graphic_object.arc.max_curves::
   #    The maximum number of curves used for approximating a complete ellipse using Bezier curves.
   #
@@ -310,6 +310,11 @@ module HexaPDF
   #    to compute. It should not be set to values lower than 4, otherwise the approximation of a
   #    complete ellipse is visibly false.
   #
+  # graphic_object.map::
+  #    A mapping from graphic object names to graphic object factories.
+  #
+  #    See HexaPDF::Content::GraphicObject for more information.
+  #
   # image_loader::
   #    An array with image loader implementations. When an image should be loaded, the array is
   #    iterated in sequence to find a suitable image loader.
@@ -381,14 +386,6 @@ module HexaPDF
   #
   #    Defaults to +true+.
   #
-  # sorted_tree.max_leaf_node_size::
-  #    The maximum number of nodes that should be in a leaf node of a node tree.
-  #
-  # style.layers_map::
-  #    A mapping from style layer names to layer objects.
-  #
-  #    See HexaPDF::Layout::Style::Layers for more information.
-  #
   # signature.signing_handler::
   #   A mapping from a Symbol to a signing handler class (see
   #   HexaPDF::Document::Signatures::DefaultHandler). If the value is a String, it should contain
@@ -403,6 +400,14 @@ module HexaPDF
   #    filter value of a signature dictionary is ignored since we only support the standard
   #    signature algorithms.
   #
+  # sorted_tree.max_leaf_node_size::
+  #    The maximum number of nodes that should be in a leaf node of a node tree.
+  #
+  # style.layers_map::
+  #    A mapping from style layer names to layer objects.
+  #
+  #    See HexaPDF::Layout::Style::Layers for more information.
+  #
   # task.map::
   #    A mapping from task names to callable task objects. See HexaPDF::Task for more information.
   DefaultDocumentConfiguration =
@@ -459,13 +464,13 @@ module HexaPDF
                         'HexaPDF::FontLoader::FromConfiguration',
                         'HexaPDF::FontLoader::FromFile',
                       ],
+                      'graphic_object.arc.max_curves' => 6,
                       'graphic_object.map' => {
                         arc: 'HexaPDF::Content::GraphicObject::Arc',
                         endpoint_arc: 'HexaPDF::Content::GraphicObject::EndpointArc',
                         solid_arc: 'HexaPDF::Content::GraphicObject::SolidArc',
                         geom2d: 'HexaPDF::Content::GraphicObject::Geom2D',
                       },
-                      'graphic_object.arc.max_curves' => 6,
                       'image_loader' => [
                         'HexaPDF::ImageLoader::JPEG',
                         'HexaPDF::ImageLoader::PNG',
@@ -479,15 +484,12 @@ module HexaPDF
                         image: 'HexaPDF::Layout::ImageBox',
                         column: 'HexaPDF::Layout::ColumnBox',
                         list: 'HexaPDF::Layout::ListBox',
+                        table: 'HexaPDF::Layout::TableBox',
                       },
                       'page.default_media_box' => :A4,
                       'page.default_media_orientation' => :portrait,
                       'parser.on_correctable_error' => proc { false },
                       'parser.try_xref_reconstruction' => true,
-                      'sorted_tree.max_leaf_node_size' => 64,
-                      'style.layers_map' => {
-                        link: 'HexaPDF::Layout::Style::LinkLayer',
-                      },
                       'signature.signing_handler' => {
                         default: 'HexaPDF::DigitalSignature::Signing::DefaultHandler',
                         timestamp: 'HexaPDF::DigitalSignature::Signing::TimestampHandler',
@@ -498,6 +500,10 @@ module HexaPDF
                         'ETSI.CAdES.detached': 'HexaPDF::DigitalSignature::CMSHandler',
                         'ETSI.RFC3161': 'HexaPDF::DigitalSignature::CMSHandler',
                       },
+                      'sorted_tree.max_leaf_node_size' => 64,
+                      'style.layers_map' => {
+                        link: 'HexaPDF::Layout::Style::LinkLayer',
+                      },
                       'task.map' => {
                         optimize: 'HexaPDF::Task::Optimize',
                         dereference: 'HexaPDF::Task::Dereference',
@@ -512,12 +518,19 @@ module HexaPDF
   #
   #    Classes for the most often used color space families are implemented and readily available.
   #
-  #    See PDF1.7 s8.6
+  #    See PDF2.0 s8.6
   #
   # filter.flate.compression::
   #    Specifies the compression level that should be used with the FlateDecode filter. The level
   #    can range from 0 (no compression), 1 (best speed) to 9 (best compression, default).
   #
+  # filter.flate.memory::
+  #    Specifies the memory level that should be used with the FlateDecode filter. The level can
+  #    range from 1 (minimum memory usage; slow, reduces compression) to 9 (maximum memory usage).
+  #
+  #    The HexaPDF default value of 6 has been found in tests to be nearly equivalent to the Zlib
+  #    default of 8 in terms of speed and compression level but uses less memory.
+  #
   # filter.flate.on_error::
   #    Callback hook when a potentially recoverable Zlib error occurs in the FlateDecode filter.
   #
@@ -527,13 +540,6 @@ module HexaPDF
   #
   #    The default implementation prevents errors from being raised.
   #
-  # filter.flate.memory::
-  #    Specifies the memory level that should be used with the FlateDecode filter. The level can
-  #    range from 1 (minimum memory usage; slow, reduces compression) to 9 (maximum memory usage).
-  #
-  #    The HexaPDF default value of 6 has been found in tests to be nearly equivalent to the Zlib
-  #    default of 8 in terms of speed and compression level but uses less memory.
-  #
   # filter.predictor.strict::
   #    Specifies whether the predictor algorithm used by LZWDecode and FlateDecode should operate in
   #    strict mode, i.e. adhering to the PDF specification without correcting for common deficiences
@@ -555,15 +561,15 @@ module HexaPDF
   #    This mapping is used to provide automatic wrapping of objects in the HexaPDF::Document#wrap
   #    method.
   GlobalConfiguration =
-    Configuration.new('filter.flate.compression' => 9,
-                      'filter.flate.on_error' => proc { false },
-                      'filter.flate.memory' => 6,
-                      'filter.predictor.strict' => false,
-                      'color_space.map' => {
+    Configuration.new('color_space.map' => {
                         DeviceRGB: 'HexaPDF::Content::ColorSpace::DeviceRGB',
                         DeviceCMYK: 'HexaPDF::Content::ColorSpace::DeviceCMYK',
                         DeviceGray: 'HexaPDF::Content::ColorSpace::DeviceGray',
                       },
+                      'filter.flate.compression' => 9,
+                      'filter.flate.memory' => 6,
+                      'filter.flate.on_error' => proc { false },
+                      'filter.predictor.strict' => false,
                       'object.type_map' => {
                         XRef: 'HexaPDF::Type::XRefStream',
                         ObjStm: 'HexaPDF::Type::ObjectStream',
@@ -604,6 +610,23 @@ module HexaPDF
                         XXOutlineItem: 'HexaPDF::Type::OutlineItem',
                         PageLabel: 'HexaPDF::Type::PageLabel',
                         XXMarkInformation: 'HexaPDF::Type::MarkInformation',
+                        OCG: 'HexaPDF::Type::OptionalContentGroup',
+                        OCMD: 'HexaPDF::Type::OptionalContentMembership',
+                        XXOCUsage: 'HexaPDF::Type::OptionalContentGroup::OptionalContentUsage',
+                        XXOCUsageCreatorInfo: 'HexaPDF::Type::OptionalContentGroup::OptionalContentUsage::CreatorInfo',
+                        XXOCUsageLanguage: 'HexaPDF::Type::OptionalContentGroup::OptionalContentUsage::Language',
+                        XXOCUsageExport: 'HexaPDF::Type::OptionalContentGroup::OptionalContentUsage::Export',
+                        XXOCUsageZoom: 'HexaPDF::Type::OptionalContentGroup::OptionalContentUsage::Zoom',
+                        XXOCUsagePrint: 'HexaPDF::Type::OptionalContentGroup::OptionalContentUsage::Print',
+                        XXOCUsageView: 'HexaPDF::Type::OptionalContentGroup::OptionalContentUsage::View',
+                        XXOCUsageUser: 'HexaPDF::Type::OptionalContentGroup::OptionalContentUsage::User',
+                        XXOCUsagePageElement: 'HexaPDF::Type::OptionalContentGroup::OptionalContentUsage::PageElement',
+                        XXOCProperties: 'HexaPDF::Type::OptionalContentProperties',
+                        XXOCConfiguration: 'HexaPDF::Type::OptionalContentConfiguration',
+                        XXOCUsageApplication: 'HexaPDF::Type::OptionalContentConfiguration::UsageApplication',
+                        XXReference: 'HexaPDF::Type::Form::Reference',
+                        XXCIDSystemInfo: 'HexaPDF::Type::CIDFont::CIDSystemInfo',
+                        Group: 'HexaPDF::Type::Form::Group',
                       },
                       'object.subtype_map' => {
                         nil => {
@@ -618,6 +641,7 @@ module HexaPDF
                           GoToR: 'HexaPDF::Type::Actions::GoToR',
                           Launch: 'HexaPDF::Type::Actions::Launch',
                           URI: 'HexaPDF::Type::Actions::URI',
+                          SetOCGState: 'HexaPDF::Type::Actions::SetOCGState',
                           Text: 'HexaPDF::Type::Annotations::Text',
                           Link: 'HexaPDF::Type::Annotations::Link',
                           Widget: 'HexaPDF::Type::Annotations::Widget',
@@ -639,6 +663,7 @@ module HexaPDF
                           GoToR: 'HexaPDF::Type::Actions::GoToR',
                           Launch: 'HexaPDF::Type::Actions::Launch',
                           URI: 'HexaPDF::Type::Actions::URI',
+                          SetOCGState: 'HexaPDF::Type::Actions::SetOCGState',
                         },
                         Annot: {
                           Text: 'HexaPDF::Type::Annotations::Text',