hexapdf 0.33.0 → 0.34.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 689e6d8b70951307055c635c744a85bcade50f7065af32b35bd5fd15230cdf4e
-  data.tar.gz: a4186126b30e18ad629db5e176be38f81b7367c72c369d8e715a1e952ad49298
+  metadata.gz: 5f2aec69ce9d984994c40912cd86d4cd10c38f23d5b975288ab11cd9e967d28b
+  data.tar.gz: 3012460ef7ca03cf81d65ac4a507dd7e23f31292d60d6e101bc555eee60f66a0
 SHA512:
-  metadata.gz: 05ad5c0f6b7819499ef0f013d28c7ee821f94cdb02f3487d27bd91089c5238c3b5b91d25ed8be0dc9b548a1e3daae17dea96171f38522587afe6b0aed47d8585
-  data.tar.gz: 51119d2f079f827271378fc9a36310ff3abcda221113096cae0fe4abee42bf2421b6ac73232fe586d9cfcf0045b5f238bd8ff69491d6f6329decc77bba0285ff
+  metadata.gz: 10004ae421f4daefb3fa0a3672b56ff8cd208048ca61aaaa75de687af4ac0f9bad8470de011f4944828c4b530a61cd0f52d27dc74530af365f556bdbfcaf3373
+  data.tar.gz: 12c0e3dbca50e6dd05a8e2a211aa8459e7e085a30570769af4b98b85c46e36202275765ea64b2c5805ccca4bc8f28b3b5d1c1322085978b3e0ce5cfce6e9f6bd

data/CHANGELOG.md

@@ -1,3 +1,59 @@
+## 0.34.1 - 2023-11-01
+
+### Added
+
+* Setting of /SMask key in graphics state parameters operator
+
+### Fixed
+
+* [HexaPDF::Composer#page_style] to set a page style when no attributes are
+  given but a block is
+* [HexaPDF::Type::Page#each_annotation] and
+  [HexaPDF::Type::Page#flatten_annotations] to process certain invalid /Annot
+  keys without errors
+
+
+## 0.34.0 - 2023-10-22
+
+### Added
+
+* Support for optional content groups (layers)
+* Support for reference XObjects
+* Basic support for group XObjects
+* [HexaPDF::Layout::Style#fill_horizontal] for allowing a text fragment to fill
+  the remaining space of line
+* [HexaPDF::Layout::TextFragment#text] and [HexaPDF::Layout::TextBox#text] for
+  retrieving the text represented by the stored items
+* [HexaPDF::Content::Canvas#pos] for retrieving untransformed positions
+* [HexaPDF::Type::CIDFont::CIDSystemInfo] type class
+
+### Changed
+
+* [HexaPDF::Composer#draw_box] to return the last drawn box
+* [HexaPDF::Layout::Style::LinkLayer] to support arbitrary actions
+* [HexaPDF::Layout::Frame::new] (and adapted other layout classes) to accept a
+  context argument (a page or Form XObject instance)
+* [HexaPDF::Layout::ListBox] to use its 'fill_color' style property for the item
+  marker color
+* [HexaPDF::Layout::Frame::FitResult#draw] to use optional content groups for
+  debug output
+
+### Fixed
+
+* [HexaPDF::Document::Pages#add_labelling_range] to add a correct entry for
+  the default range starting at page 1
+* [HexaPDF::Type::Page#flatten_annotations] to correctly handle scaled
+  appearances
+* Using an unknown style name in [HexaPDF:Document::Layout] method by providing
+  a useful error message
+* [HexaPDF::Layout::Box::new] to ensure that the properties attribute is always
+  a hash
+* [HexaPDF::Layout::ListBox] to work correctly if the marker height is larger
+  than the item content height
+* [HexaPDF::Dictionary] setting default values on wrong classes in certain
+  situations
+
+
 ## 0.33.0 - 2023-08-02
 
 ### Added
@@ -39,7 +95,7 @@
 
 ### Fixed
 
-**Breaking change**: [HexaPDF::Object::make_direct] now needs the document
+* **Breaking change**: [HexaPDF::Object::make_direct] now needs the document
   instance as second argument to correctly resolve references
 * [HexaPDF::Layout::ColumnBox], [HexaPDF::Layout::ListBox] and
   [HexaPDF::Layout::ImageBox] to correctly respond to `#empty?`

data/examples/026-optional_content.rb

@@ -0,0 +1,55 @@
+# # Optional Content (a.k.a. Layers)
+#
+# This example shows how to create and assign optional content groups (OCGs) to
+# parts of the content of a page.
+#
+# Four OCGs are created: Squares, Black, Blue, and Orange. The Squares one is
+# applied to everything, the others to the respectively colored squares.
+#
+# When viewed in a compatible viewer, the "Optional Content" or "Layers" panel
+# can be used to switch the layers on and off, resulting in the respective
+# squares appearing or disappearing. Initially, the blue one is not shown, only
+# the black and orange ones.
+#
+# Additionally, if supported by a viewer and if the visibility hasn't been
+# manually changed, the OCGs for the squares are also configured to only be
+# visible at certain zoom levels. For example, the black one is only visible up
+# to a zoom level of 100%.
+#
+# Usage:
+# : `ruby optional_content.rb`
+#
+require 'hexapdf'
+
+doc = HexaPDF::Document.new
+
+ocg = doc.optional_content.ocg('Squares')
+ocg1 = doc.optional_content.ocg('Black')
+ocg1.zoom(max: 1)
+ocg1.add_to_ui(path: ocg)
+ocg2 = doc.optional_content.ocg('Blue')
+ocg2.zoom(min: 1, max: 2)
+ocg2.add_to_ui(path: ocg)
+ocg2.off!
+ocg3 = doc.optional_content.ocg('Orange')
+ocg3.zoom(min: 2, max: 20)
+ocg3.add_to_ui(path: ocg)
+
+canvas = doc.pages.add([0, 0, 200, 200]).canvas
+canvas.optional_content(ocg) do
+  canvas.optional_content(ocg1) do
+    canvas.fill_color('black').rectangle(20, 80, 100, 100).fill
+  end
+  canvas.optional_content(ocg2) do
+    canvas.fill_color('hp-blue').rectangle(50, 50, 100, 100).fill
+  end
+  canvas.optional_content(ocg3) do
+    canvas.fill_color('hp-orange').rectangle(80, 20, 100, 100).fill
+  end
+end
+
+doc.optional_content.default_configuration[:AS] = [
+  {Event: :View, Category: [:Zoom], OCGs: [ocg1, ocg2, ocg3]}
+]
+
+doc.write('optional_content.pdf')

data/examples/027-composer_optional_content.rb

@@ -0,0 +1,83 @@
+# # Composer - Optional Content
+#
+# This example shows how to use the optional content feature to create a quiz
+# where the answers can be individually shown and hidden. There is also a link
+# after the questions to toggle all answers.
+#
+# Note: To provide the "All answers" layer switch functionality we need to make
+# use of optional content membership dictionaries. However, this PDF feature is
+# not supported by all PDF viewers. To enable the "All answers" switch in this
+# example, use `a1m`, `a2m`, and `a3m` instead of `a1`, `a2`, and `a3` when
+# defining the optional content for a box.
+#
+# Usage:
+# : `ruby composer_optional_content.rb`
+#
+require 'hexapdf'
+
+HexaPDF::Composer.create('composer_optional_content.pdf') do |composer|
+  composer.style(:question, font_size: 16, margin: [0, 0, 16], fill_color: 'hp-blue')
+  composer.style(:answer, font: 'ZapfDingbats', fill_color: "green")
+
+  all = composer.document.optional_content.ocg('All answers')
+  a1 = composer.document.optional_content.ocg('Answer 1')
+  a1m = composer.document.optional_content.create_ocmd([a1, all], policy: :any_on)
+  a2 = composer.document.optional_content.ocg('Answer 2')
+  a2m = composer.document.optional_content.create_ocmd([a2, all], policy: :any_on)
+  a3 = composer.document.optional_content.ocg('Answer 3')
+  a3m = composer.document.optional_content.create_ocmd([a3, all], policy: :any_on)
+
+  composer.text('The Great Ruby Quiz', align: :center, margin: [0, 0, 24],
+                font: ['Helvetica', variant: :bold], font_size: 24)
+
+  composer.list(item_type: :decimal, item_spacing: 32, style: :question) do |listing|
+    listing.multiple do |item|
+      item.text('Who created Ruby?', style: :question)
+      item.column(columns: 3, gaps: 5) do |cols|
+        cols.list(item_type: :decimal) do |answers|
+          answers.text('Guido van Rossum')
+          answers.multiple do |answer|
+            answer.text('Yukihiro “Matz” Matsumoto', position: :float)
+            answer.text("\u{a0}\u{a0}4", style: :answer,
+                        properties: {'optional_content' => a1})
+          end
+          answers.text('Rob Pike')
+        end
+      end
+    end
+
+    listing.multiple do |item|
+      item.text('When was Ruby created?', style: :question)
+      item.column(columns: 3, gaps: 5) do |cols|
+        cols.list(item_type: :decimal) do |answers|
+          answers.text('1991')
+          answers.text('1992')
+          answers.multiple do |answer|
+            answer.text('1993', position: :float)
+            answer.text("\u{a0}\u{a0}4", style: :answer,
+                        properties: {'optional_content' => a2})
+          end
+        end
+      end
+    end
+
+    listing.multiple do |item|
+      item.text('What is the best PDF library for Ruby?', style: :question)
+      answer = composer.document.layout.text('There are several PDF libraries for ' \
+                                             'Ruby but the best is HexaPDF! :)',
+                                             width: 400,
+                                             properties: {'optional_content' => a3})
+      item.formatted_text([{box: answer}], border: {width: [0, 0, 1]})
+    end
+  end
+
+  action = composer.document.wrap({Type: :Action, S: :SetOCGState})
+  action.add_state_change(:toggle, [a1, a2, a3])
+  composer.text("Click to toggle answers", border: {width: 1, color: "red"},
+                position_hint: :right, padding: 2, overlays: [[:link, action: action]])
+
+  composer.document.optional_content.default_configuration(
+    BaseState: :OFF,
+    Order: [all, a1, a2, a3],
+  )
+end

data/lib/hexapdf/cli/command.rb

@@ -53,9 +53,15 @@ module HexaPDF
       module Extensions #:nodoc:
         def help_banner #:nodoc:
           "hexapdf #{HexaPDF::VERSION} - Versatile PDF Manipulation Tool\n" \
-            "Copyright (c) 2014-2021 Thomas Leitner; licensed under the AGPLv3\n\n" \
+            "Copyright (c) 2014-2023 Thomas Leitner; licensed under the AGPLv3\n\n" \
             "#{format(usage, indent: 7)}\n\n"
         end
+
+        def help #:nodoc:
+          super << format("See https://hexapdf.gettalong.org/documentation/hexapdf.1.html " \
+                          "for the full manual page with examples.", indent: 0)
+        end
+
       end
 
       include Extensions

data/lib/hexapdf/cli/fonts.rb

@@ -127,7 +127,7 @@ module HexaPDF
           page.resources[:Font]&.each(&font_proc)
           page.resources[:XObject]&.each do |_, xobj|
             next unless xobj[:Subtype] == :Form
-            xobj.ressources[:Font]&.each(&font_proc)
+            xobj.resources[:Font]&.each(&font_proc)
           end
           page.each_annotation do |annotation|
             appearance = annotation.appearance

data/lib/hexapdf/cli/inspect.rb

@@ -93,11 +93,9 @@ module HexaPDF
 
       private
 
-      # :nodoc:
-      COMMAND_LIST = %w[object recursive stream raw-stream xref catalog trailer pages
+      COMMAND_LIST = %w[object recursive stream raw-stream xref catalog trailer pages # :nodoc:
                         page-count search quit help]
-      # :nodoc:
-      RELINE_COMPLETION_PROC = proc do |s|
+      RELINE_COMPLETION_PROC = proc do |s| # :nodoc:
         if s.empty?
           COMMAND_DESCRIPTIONS.map {|cmd, desc| cmd.ljust(35) << desc }
         else

data/lib/hexapdf/composer.rb

@@ -281,7 +281,7 @@ module HexaPDF
     #
     # See: HexaPDF::Layout::PageStyle
     def page_style(name, **attributes, &block)
-      if attributes.empty?
+      if attributes.empty? && block.nil?
         @page_styles[name]
       else
         @page_styles[name] = HexaPDF::Layout::PageStyle.new(**attributes, &block)
@@ -401,7 +401,7 @@ module HexaPDF
       @document.layout.box_creation_method?(name) || super
     end
 
-    # Draws the given HexaPDF::Layout::Box.
+    # Draws the given HexaPDF::Layout::Box and returns the last drawn box.
     #
     # The box is drawn into the current frame if possible. If it doesn't fit, the box is split. If
     # it still doesn't fit, a new region of the frame is determined and then the process starts
@@ -433,6 +433,7 @@ module HexaPDF
           end
         end
       end
+      box
     end
 
     # Creates a stamp (Form XObject) which can be used like an image multiple times on a single page

data/lib/hexapdf/configuration.rb

@@ -268,7 +268,8 @@ 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
@@ -609,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 => {
@@ -623,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',
@@ -644,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',

data/lib/hexapdf/content/canvas.rb

@@ -317,6 +317,14 @@ module HexaPDF
         @context.resources
       end
 
+      # Returns the position (x,y) transformed by the current transformation matrix.
+      #
+      # The resulting position should be interpreted in terms of the coordinate system of the
+      # context object (e.g. the page or Form XObject).
+      def pos(x, y)
+        graphics_state.ctm.evaluate(x, y)
+      end
+
       # :call-seq:
       #   canvas.save_graphics_state              => canvas
       #   canvas.save_graphics_state { block }    => canvas
@@ -2483,6 +2491,50 @@ module HexaPDF
         self
       end
 
+      # :call-seq:
+      #   canvas.optional_content(ocg, &block)                              -> canvas
+      #   canvas.optional_content(name, use_existing_ocg: true, &block)     -> canvas
+      #
+      # Inserts an optional content sequence. Returns +self+.
+      #
+      # An optional content sequence marks part of the content stream as belonging to the given
+      # optional content group. See HexaPDF::Type::OptionalContentProperties for details.
+      #
+      # If the first argument is already an optional content group dictionary, it is used.
+      # Otherwise, the first argument needs to be the name of the optional content group. In that
+      # case, the +use_existing_ocg+ specifies whether the first found optional content group with
+      # that name should be used or whether a new OCG should always be created.
+      #
+      # If invoked without a block, a corresponding call to #end_optional_content must be done.
+      # Otherwise the optional content sequence automatically ends when the block is finished.
+      #
+      # Examples:
+      #
+      #   canvas.optional_content('Hints')
+      #   # Other instructions
+      #   canvas.end_optional_content
+      #
+      #   canvas.optional_content('Hints', use_existing_ocg: false) do
+      #     # Other instructions
+      #   end
+      #
+      # See: PDF2.0 s8.11, #end_optional_content, HexaPDF::Type::OptionalContentProperties
+      def optional_content(ocg, use_existing_ocg: true, &block)
+        ocg = if ocg.kind_of?(HexaPDF::Dictionary) || !use_existing_ocg
+                context.document.optional_content.add_ocg(ocg)
+              else
+                context.document.optional_content.ocg(ocg, create: true)
+              end
+        marked_content_sequence(:OC, property_list: ocg, &block)
+      end
+
+      # Ends an optional content sequence and returns +self+.
+      #
+      # See #optional_content for details.
+      #
+      # See: PDF2.0 s8.11
+      alias :end_optional_content :end_marked_content_sequence
+
       # Creates and returns a color object from the given color specification. See #stroke_color for
       # details on the possible color specifications.
       #

data/lib/hexapdf/content/operator.rb

@@ -326,7 +326,6 @@ module HexaPDF
           ops[:M].invoke(processor, dict[:ML]) if dict.key?(:ML)
           ops[:d].invoke(processor, *dict[:D]) if dict.key?(:D)
           ops[:ri].invoke(processor, dict[:RI]) if dict.key?(:RI)
-          # TODO: dict[:SMask] works differently than operator!
 
           # No content operator exists for the following parameters
           gs = processor.graphics_state
@@ -335,6 +334,7 @@ module HexaPDF
           gs.stroke_alpha = dict[:CA] if dict.key?(:CA)
           gs.fill_alpha = dict[:ca] if dict.key?(:ca)
           gs.alpha_source = dict[:AIS] if dict.key?(:AIS)
+          gs.soft_mask = dict[:SMask] if dict.key?(:SMask)
           gs.text_knockout = dict[:TK] if dict.key?(:TK)
           if dict.key?(:Font)
             gs.font = processor.resources.document.deref(dict[:Font][0])
@@ -1001,6 +1001,8 @@ module HexaPDF
 
       # Mapping of operator names to their default operator implementations.
       DEFAULT_OPERATORS = {
+        BX: NoArgumentOperator.new('BX'),
+        EX: NoArgumentOperator.new('EX'),
         q: SaveGraphicsState.new,
         Q: RestoreGraphicsState.new,
         cm: ConcatenateMatrix.new,

data/lib/hexapdf/dictionary.rb

@@ -249,6 +249,7 @@ module HexaPDF
     # Sets all required fields that have no current value but a default value to their respective
     # default value.
     def set_required_fields_with_defaults
+      return if (type = value[:Type]) && self.class.type != type
       self.class.each_field do |name, field|
         if !key?(name) && field.required? && field.default?
           value[name] = field.default

data/lib/hexapdf/dictionary_fields.rb

@@ -313,8 +313,7 @@ module HexaPDF
         [String, Time, Date, DateTime]
       end
 
-      # :nodoc:
-      DATE_RE = /\AD:(\d{4})(\d\d)?(\d\d)?(\d\d)?(\d\d)?(\d\d)?([Z+-])?(?:(\d+)(?:'|'(\d+)'?|\z)?)?\z/n
+      DATE_RE = /\AD:(\d{4})(\d\d)?(\d\d)?(\d\d)?(\d\d)?(\d\d)?([Z+-])?(?:(\d+)(?:'|'(\d+)'?|\z)?)?\z/n # :nodoc:
 
       # Checks if the given object is a string and converts into a Time object if possible.
       # Otherwise returns +nil+.

data/lib/hexapdf/digital_signature/verification_result.rb

@@ -40,8 +40,7 @@ module HexaPDF
     # Holds the result of verifying a signature.
     class VerificationResult
 
-      # :nodoc:
-      MESSAGE_SORT_MAP = {
+      MESSAGE_SORT_MAP = { # :nodoc:
         info: {warning: 1, error: 1, info: 0},
         warning: {info: -1, error: 1, warning: 0},
         error: {info: -1, warning: -1, error: 0},

data/lib/hexapdf/document/layout.rb

@@ -607,6 +607,9 @@ module HexaPDF
       # Finally, a default font is set if necessary to ensure that the style object works in all
       # cases.
       def retrieve_style(style, properties = nil)
+        if style.kind_of?(Symbol) && !@styles.key?(style)
+          raise HexaPDF::Error, "Style #{style} not defined"
+        end
         style = HexaPDF::Layout::Style.create(@styles[style] || style || @styles[:base])
         style = style.dup.update(**properties) unless properties.nil? || properties.empty?
         style.font('Times') unless style.font?

data/lib/hexapdf/document/pages.rb

@@ -246,7 +246,7 @@ module HexaPDF
 
         labels = @document.catalog.page_labels(create: true)
         labels.add_entry(start_index, page_label)
-        labels.add_entry(0, {S: :d}) unless labels.find_entry(0)
+        labels.add_entry(0, {S: :D}) unless labels.find_entry(0)
 
         page_label
       end

data/lib/hexapdf/document.rb

@@ -538,6 +538,13 @@ module HexaPDF
       catalog.outline
     end
 
+    # Returns the main object for working with optional content (a.k.a. layers).
+    #
+    # See: Type::Catalog#optional_content
+    def optional_content
+      catalog.optional_content
+    end
+
     # Executes the given task and returns its result.
     #
     # Tasks provide an extensible way for performing operations on a PDF document without

data/lib/hexapdf/encryption/ruby_aes.rb

@@ -92,9 +92,8 @@ module HexaPDF
 
       private
 
-      # :nodoc:
       # Rijndael S-box
-      SBOX = [
+      SBOX = [ # :nodoc:
         0x63, 0x7c, 0x77, 0x7b, 0xf2, 0x6b, 0x6f, 0xc5, 0x30, 0x01, 0x67, 0x2b, 0xfe, 0xd7, 0xab, 0x76,
         0xca, 0x82, 0xc9, 0x7d, 0xfa, 0x59, 0x47, 0xf0, 0xad, 0xd4, 0xa2, 0xaf, 0x9c, 0xa4, 0x72, 0xc0,
         0xb7, 0xfd, 0x93, 0x26, 0x36, 0x3f, 0xf7, 0xcc, 0x34, 0xa5, 0xe5, 0xf1, 0x71, 0xd8, 0x31, 0x15,
@@ -113,9 +112,8 @@ module HexaPDF
         0x8c, 0xa1, 0x89, 0x0d, 0xbf, 0xe6, 0x42, 0x68, 0x41, 0x99, 0x2d, 0x0f, 0xb0, 0x54, 0xbb, 0x16
       ].freeze
 
-      # :nodoc:
       # Inverse of the Rijndael S-box
-      INV_SBOX = [
+      INV_SBOX = [ # :nodoc:
         0x52, 0x09, 0x6a, 0xd5, 0x30, 0x36, 0xa5, 0x38, 0xbf, 0x40, 0xa3, 0x9e, 0x81, 0xf3, 0xd7, 0xfb,
         0x7c, 0xe3, 0x39, 0x82, 0x9b, 0x2f, 0xff, 0x87, 0x34, 0x8e, 0x43, 0x44, 0xc4, 0xde, 0xe9, 0xcb,
         0x54, 0x7b, 0x94, 0x32, 0xa6, 0xc2, 0x23, 0x3d, 0xee, 0x4c, 0x95, 0x0b, 0x42, 0xfa, 0xc3, 0x4e,
@@ -134,12 +132,10 @@ module HexaPDF
         0x17, 0x2b, 0x04, 0x7e, 0xba, 0x77, 0xd6, 0x26, 0xe1, 0x69, 0x14, 0x63, 0x55, 0x21, 0x0c, 0x7d
       ].freeze
 
-      # :nodoc:
-      RCON = [0x8d, 0x01, 0x02, 0x04, 0x08, 0x10, 0x20, 0x40, 0x80, 0x1b, 0x36, 0x6c].freeze
+      RCON = [0x8d, 0x01, 0x02, 0x04, 0x08, 0x10, 0x20, 0x40, 0x80, 0x1b, 0x36, 0x6c].freeze # :nodoc:
 
-      # :nodoc:
       # Precomputed Galois multiplication table for multiplication with 2 in GF(2^8)
-      G2MULT = [
+      G2MULT = [ # :nodoc:
         0x00, 0x02, 0x04, 0x06, 0x08, 0x0a, 0x0c, 0x0e, 0x10, 0x12, 0x14, 0x16, 0x18, 0x1a, 0x1c, 0x1e,
         0x20, 0x22, 0x24, 0x26, 0x28, 0x2a, 0x2c, 0x2e, 0x30, 0x32, 0x34, 0x36, 0x38, 0x3a, 0x3c, 0x3e,
         0x40, 0x42, 0x44, 0x46, 0x48, 0x4a, 0x4c, 0x4e, 0x50, 0x52, 0x54, 0x56, 0x58, 0x5a, 0x5c, 0x5e,
@@ -158,9 +154,8 @@ module HexaPDF
         0xfb, 0xf9, 0xff, 0xfd, 0xf3, 0xf1, 0xf7, 0xf5, 0xeb, 0xe9, 0xef, 0xed, 0xe3, 0xe1, 0xe7, 0xe5
       ].freeze
 
-      # :nodoc:
       # Precomputed Galois multiplication table for multiplication with 3 in GF(2^8)
-      G3MULT = [
+      G3MULT = [ # :nodoc:
         0x00, 0x03, 0x06, 0x05, 0x0c, 0x0f, 0x0a, 0x09, 0x18, 0x1b, 0x1e, 0x1d, 0x14, 0x17, 0x12, 0x11,
         0x30, 0x33, 0x36, 0x35, 0x3c, 0x3f, 0x3a, 0x39, 0x28, 0x2b, 0x2e, 0x2d, 0x24, 0x27, 0x22, 0x21,
         0x60, 0x63, 0x66, 0x65, 0x6c, 0x6f, 0x6a, 0x69, 0x78, 0x7b, 0x7e, 0x7d, 0x74, 0x77, 0x72, 0x71,
@@ -179,9 +174,8 @@ module HexaPDF
         0x0b, 0x08, 0x0d, 0x0e, 0x07, 0x04, 0x01, 0x02, 0x13, 0x10, 0x15, 0x16, 0x1f, 0x1c, 0x19, 0x1a
       ].freeze
 
-      # :nodoc:
       # Precomputed Galois multiplication table for multiplication with 9 in GF(2^8)
-      G9MULT = [
+      G9MULT = [ # :nodoc:
         0x00, 0x09, 0x12, 0x1b, 0x24, 0x2d, 0x36, 0x3f, 0x48, 0x41, 0x5a, 0x53, 0x6c, 0x65, 0x7e, 0x77,
         0x90, 0x99, 0x82, 0x8b, 0xb4, 0xbd, 0xa6, 0xaf, 0xd8, 0xd1, 0xca, 0xc3, 0xfc, 0xf5, 0xee, 0xe7,
         0x3b, 0x32, 0x29, 0x20, 0x1f, 0x16, 0x0d, 0x04, 0x73, 0x7a, 0x61, 0x68, 0x57, 0x5e, 0x45, 0x4c,
@@ -200,9 +194,8 @@ module HexaPDF
         0x31, 0x38, 0x23, 0x2a, 0x15, 0x1c, 0x07, 0x0e, 0x79, 0x70, 0x6b, 0x62, 0x5d, 0x54, 0x4f, 0x46
       ].freeze
 
-      # :nodoc:
       # Precomputed Galois multiplication table for multiplication with 11 in GF(2^8)
-      G11MULT = [
+      G11MULT = [ # :nodoc:
         0x00, 0x0b, 0x16, 0x1d, 0x2c, 0x27, 0x3a, 0x31, 0x58, 0x53, 0x4e, 0x45, 0x74, 0x7f, 0x62, 0x69,
         0xb0, 0xbb, 0xa6, 0xad, 0x9c, 0x97, 0x8a, 0x81, 0xe8, 0xe3, 0xfe, 0xf5, 0xc4, 0xcf, 0xd2, 0xd9,
         0x7b, 0x70, 0x6d, 0x66, 0x57, 0x5c, 0x41, 0x4a, 0x23, 0x28, 0x35, 0x3e, 0x0f, 0x04, 0x19, 0x12,
@@ -221,9 +214,8 @@ module HexaPDF
         0xca, 0xc1, 0xdc, 0xd7, 0xe6, 0xed, 0xf0, 0xfb, 0x92, 0x99, 0x84, 0x8f, 0xbe, 0xb5, 0xa8, 0xa3
       ].freeze
 
-      # :nodoc:
       # Precomputed Galois multiplication table for multiplication with 13 in GF(2^8)
-      G13MULT = [
+      G13MULT = [ # :nodoc:
         0x00, 0x0d, 0x1a, 0x17, 0x34, 0x39, 0x2e, 0x23, 0x68, 0x65, 0x72, 0x7f, 0x5c, 0x51, 0x46, 0x4b,
         0xd0, 0xdd, 0xca, 0xc7, 0xe4, 0xe9, 0xfe, 0xf3, 0xb8, 0xb5, 0xa2, 0xaf, 0x8c, 0x81, 0x96, 0x9b,
         0xbb, 0xb6, 0xa1, 0xac, 0x8f, 0x82, 0x95, 0x98, 0xd3, 0xde, 0xc9, 0xc4, 0xe7, 0xea, 0xfd, 0xf0,
@@ -242,9 +234,8 @@ module HexaPDF
         0xdc, 0xd1, 0xc6, 0xcb, 0xe8, 0xe5, 0xf2, 0xff, 0xb4, 0xb9, 0xae, 0xa3, 0x80, 0x8d, 0x9a, 0x97
       ].freeze
 
-      # :nodoc:
       # Precomputed Galois multiplication table for multiplication with 14 in GF(2^8)
-      G14MULT = [
+      G14MULT = [ # :nodoc:
         0x00, 0x0e, 0x1c, 0x12, 0x38, 0x36, 0x24, 0x2a, 0x70, 0x7e, 0x6c, 0x62, 0x48, 0x46, 0x54, 0x5a,
         0xe0, 0xee, 0xfc, 0xf2, 0xd8, 0xd6, 0xc4, 0xca, 0x90, 0x9e, 0x8c, 0x82, 0xa8, 0xa6, 0xb4, 0xba,
         0xdb, 0xd5, 0xc7, 0xc9, 0xe3, 0xed, 0xff, 0xf1, 0xab, 0xa5, 0xb7, 0xb9, 0x93, 0x9d, 0x8f, 0x81,
@@ -263,9 +254,8 @@ module HexaPDF
         0xd7, 0xd9, 0xcb, 0xc5, 0xef, 0xe1, 0xf3, 0xfd, 0xa7, 0xa9, 0xbb, 0xb5, 0x9f, 0x91, 0x83, 0x8d
       ].freeze
 
-      # :nodoc:
       # Number of rounds needed in various parts of the algorithm, depends on the key size
-      NUMBER_OF_ROUNDS = {16 => 10, 24 => 12, 32 => 14}.freeze
+      NUMBER_OF_ROUNDS = {16 => 10, 24 => 12, 32 => 14}.freeze # :nodoc:
 
       # KeyExpansion step
       #

data/lib/hexapdf/layout/box.rb

@@ -127,10 +127,24 @@ module HexaPDF
       #
       # This can be used to store arbitrary information on boxes for later use. For example, a
       # generic style layer could use one or more custom properties for its work.
+      #
+      # The Box class itself uses the following properties:
+      #
+      # optional_content::
+      #
+      #       If this property is set, it needs to be an optional content group dictionary, a String
+      #       defining an (optionally existing) optional content group dictionary, or an optional
+      #       content membership dictionary.
+      #
+      #       The whole content of the box, i.e. including padding, border, background..., is
+      #       wrapped with the appropriate commands so that the optional content group or membership
+      #       dictionary specifies whether the content is shown or not.
+      #
+      #       See: HexaPDF::Type::OptionalContentProperties
       attr_reader :properties
 
       # :call-seq:
-      #    Box.new(width: 0, height: 0, style: nil, properties: {}) {|canv, box| block} -> box
+      #    Box.new(width: 0, height: 0, style: nil, properties: nil) {|canv, box| block} -> box
       #
       # Creates a new Box object with the given width and height that uses the provided block when
       # it is asked to draw itself on a canvas (see #draw).
@@ -138,11 +152,11 @@ module HexaPDF
       # Since the final location of the box is not known beforehand, the drawing operations inside
       # the block should draw inside the rectangle (0, 0, content_width, content_height) - note that
       # the width and height of the box may not be known beforehand.
-      def initialize(width: 0, height: 0, style: nil, properties: {}, &block)
+      def initialize(width: 0, height: 0, style: nil, properties: nil, &block)
         @width = @initial_width = width
         @height = @initial_height = height
         @style = Style.create(style)
-        @properties = properties
+        @properties = properties || {}
         @draw_block = block
         @fit_successful = false
         @split_box = false
@@ -220,6 +234,10 @@ module HexaPDF
       # instance variable to +nil+ or a valid block. This is useful to avoid unnecessary set-up
       # operations when the block does nothing.
       def draw(canvas, x, y)
+        if (oc = properties['optional_content'])
+          canvas.optional_content(oc)
+        end
+
         if style.background_color? && style.background_color
           canvas.save_graphics_state do
             canvas.opacity(fill_alpha: style.background_alpha).
@@ -233,6 +251,8 @@ module HexaPDF
         draw_content(canvas, x + reserved_width_left, y + reserved_height_bottom)
 
         style.overlays.draw(canvas, x, y, self) if style.overlays?
+
+        canvas.end_optional_content if oc
       end
 
       # Returns +true+ if no drawing operations are performed.