# -*- encoding: utf-8; frozen_string_literal: true -*-
#
#--
# This file is part of HexaPDF.
#
# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
# Copyright (C) 2014-2023 Thomas Leitner
#
# HexaPDF is free software: you can redistribute it and/or modify it
# under the terms of the GNU Affero General Public License version 3 as
# published by the Free Software Foundation with the addition of the
# following permission added to Section 15 as permitted in Section 7(a):
# FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
# THOMAS LEITNER, THOMAS LEITNER DISCLAIMS THE WARRANTY OF NON
# INFRINGEMENT OF THIRD PARTY RIGHTS.
#
# HexaPDF is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
# License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with HexaPDF. If not, see <http://www.gnu.org/licenses/>.
#
# The interactive user interfaces in modified source and object code
# versions of HexaPDF must display Appropriate Legal Notices, as required
# under Section 5 of the GNU Affero General Public License version 3.
#
# In accordance with Section 7(b) of the GNU Affero General Public
# License, a covered work must retain the producer line in every PDF that
# is created or manipulated using HexaPDF.
#
# If the GNU Affero General Public License doesn't fit your need,
# commercial licenses are available at <https://gettalong.at/hexapdf/>.
#++

require 'hexapdf/dictionary'
require 'hexapdf/utils/bit_field'
require 'hexapdf/content/color_space'

module HexaPDF
  module Type

    # Represents an outline item dictionary.
    #
    # An item has a title and some optional attributes: the action that is activated when clicking
    # (either a simple destination or an explicit action object), the text color, and flags (whether
    # the text should appear bold and/or italic).
    #
    # Additionally, items may have child items which makes it possible to create a hierarchy of
    # items.
    #
    # If no destination/action is set, the item just acts as kind of a header. It usually only makes
    # sense to do this when the item has children.
    #
    # Outline item dictionaries are connected together in the form of a linked list using the /Next
    # and /Prev keys. Each item may have descendant items. If so, the /First and /Last keys point to
    # respectively the first and last descendant items.
    #
    # Since many dictionary keys need to be kept up-to-date when manipulating the outline item tree,
    # it is not recommended to manually do this but to rely on the provided convenience methods.
    #
    # See: PDF2.0 s12.3.3
    class OutlineItem < Dictionary

      extend Utils::BitField

      define_type :XXOutlineItem

      define_field :Title,  type: String, required: true
      define_field :Parent, type: Dictionary, required: true, indirect: true
      define_field :Prev,   type: :XXOutlineItem, indirect: true
      define_field :Next,   type: :XXOutlineItem, indirect: true
      define_field :First,  type: :XXOutlineItem, indirect: true
      define_field :Last,   type: :XXOutlineItem, indirect: true
      define_field :Count,  type: Integer
      define_field :Dest,   type: [Symbol, PDFByteString, PDFArray]
      define_field :A,      type: :Action, version: '1.1'
      define_field :SE,     type: Dictionary, indirect: true
      define_field :C,      type: PDFArray, default: [0, 0, 0], version: '1.4'
      define_field :F,      type: Integer, default: 0, version: '1.4'

      ##
      # :method: flags
      #
      # Returns an array of flag names representing the set bit flags for /F.
      #
      # The available flags are:
      #
      # :italic or 0:: The text is displayed in italic.
      # :bold or 1:: The text is displayed in bold.
      #

      ##
      # :method: flagged?
      # :call-seq:
      #   flagged?(flag)
      #
      # Returns +true+ if the given flag is set on /F. The argument can either be the flag name or
      # the bit index.
      #
      # See #flags for the list of available flags.
      #

      ##
      # :method: flag
      # :call-seq:
      #   flag(*flags, clear_existing: false)
      #
      # Sets the given flags on /F, given as flag names or bit indices. If +clear_existing+ is
      # +true+, all prior flags will be cleared.
      #
      # See #flags for the list of available flags.
      #

      ##
      # :method: unflag
      # :call-seq:
      #   flag(*flags)
      #
      # Clears the given flags from /F, given as flag names or bit indices.
      #
      # See #flags for the list of available flags.
      #
      bit_field(:flags, {italic: 0, bold: 1},
                lister: "flags", getter: "flagged?", setter: "flag", unsetter: "unflag",
                value_getter: "self[:F]", value_setter: "self[:F]")

      # Returns +true+ since outline items must always be indirect objects.
      def must_be_indirect?
        true
      end

      # :call-seq:
      #   item.title          -> title
      #   item.title(value)   -> title
      #
      # Returns the item's title if no argument is given. Otherwise sets the title to the given
      # value.
      def title(value = nil)
        if value
          self[:Title] = value
        else
          self[:Title]
        end
      end

      # :call-seq:
      #   item.text_color               -> color
      #   item.text_color(color)        -> color
      #
      # Returns the item's text color as HexaPDF::Content::ColorSpace::DeviceRGB::Color object if no
      # argument is given. Otherwise sets the text color, see
      # HexaPDF::Content::ColorSpace.device_color_from_specification for possible +color+ values.
      #
      # Note: The color *has* to be an RGB color.
      def text_color(color = nil)
        if color
          color = HexaPDF::Content::ColorSpace.device_color_from_specification(color)
          unless color.color_space.family == :DeviceRGB
            raise ArgumentError, "The given argument is not a valid RGB color"
          end
          self[:C] = color.components
        else
          Content::ColorSpace.prenormalized_device_color(self[:C])
        end
      end

      # :call-seq:
      #   item.destination             -> destination
      #   item.destination(value)      -> destination
      #
      # Returns the item's destination if no argument is given. Otherwise sets the destination to
      # the given value (see HexaPDF::Document::Destinations#use_or_create for the posssible
      # values).
      #
      # If an action is set, the destination has to be unset; and vice versa. So when setting a
      # destination value, the action is automatically deleted.
      def destination(value = nil)
        if value
          delete(:A)
          self[:Dest] = document.destinations.use_or_create(value)
        else
          self[:Dest]
        end
      end

      # :call-seq:
      #   item.action             -> action
      #   item.action(value)      -> action
      #
      # Returns the item's action if no argument is given. Otherwise sets the action to
      # the given value (needs to be a valid HexaPDF::Type::Action dictionary).
      #
      # If an action is set, the destination has to be unset; and vice versa. So when setting an
      # action value, the destination is automatically deleted.
      def action(value = nil)
        if value
          delete(:Dest)
          self[:A] = value
        else
          self[:A]
        end
      end

      # Returns the outline level this item is one.
      #
      # The level of the items in the main outline dictionary, the root level, is 1.
      #
      # Here is an illustrated example of items contained in a document outline with their
      # associated level:
      #
      #  Outline dictionary          0
      #    Outline item 1            1
      #    |- Sub item 1             2
      #    |- Sub item 2             2
      #       |- Sub sub item 1      3
      #    |- Sub item 3             2
      #    Outline item 2            1
      def level
        count = 0
        temp = self
        count += 1 while (temp = temp[:Parent])
        count
      end

      # Returns the open state of the item.
      #
      # +true+::  If this item is open, i.e. showing its child items.
      # +false+:: If this item is closed, i.e. not showing its child items.
      # +nil+::   If this item doesn't (yet) have any child items.
      def open?
        self[:First] && key?(:Count) && self[:Count] >= 0
      end

      # Returns the destination page if there is any.
      #
      # * If a destination is set, the associated page is returned.
      # * If an action is set and it is a GoTo action, the associated page is returned.
      # * Otherwise +nil+ is returned.
      def destination_page
        dest = self[:Dest]
        dest = action[:D] if !dest && (action = self[:A]) && action[:S] == :GoTo
        document.destinations.resolve(dest)&.page
      end

      # Adds, as child to this item, a new outline item with the given title that performs the
      # provided action on clicking. Returns the newly added item.
      #
      # Alternatively, it is possible to provide an already initialized outline item instead of the
      # title. If so, the only other argument that is used is +position+. Existing fields /Prev,
      # /Next, /First, /Last, /Parent and /Count are deleted from the given item and set
      # appropriately.
      #
      # If neither :destination nor :action is specified, the outline item has no associated action.
      # This is only meaningful if the new item will have children as it then acts just as a
      # container.
      #
      # If a block is specified, the newly created item is yielded.
      #
      # destination::
      #
      #     Specifies the destination that should be activated when clicking on the outline item.
      #     See HexaPDF::Document::Destinations#use_or_create for details. The argument :action
      #     takes precedence if it is also specified,
      #
      # action::
      #
      #     Specifies the action that should be taken when clicking on the outline item. See
      #     HexaPDF::Type::Action for details. If the argument :destination is also specified, the
      #     :action argument takes precedence.
      #
      # position::
      #
      #     The position where the new child item should be inserted. Can either be:
      #
      #     +:first+:: Insert as first item
      #     +:last+:: Insert as last item (default)
      #     Integer:: When non-negative inserts before, otherwise after, the item at the given
      #               zero-based index.
      #
      # open::
      #
      #     Specifies whether the outline item should be open (i.e. one or more children are shown)
      #     or closed. Default: +true+.
      #
      # text_color::
      #
      #     The text color of the outline item text which needs to be a valid RGB color (see
      #     #text_color for details). If not set, the text appears in black.
      #
      # flags::
      #
      #     An array of font variants (possible values are :bold and :italic) to set for the outline
      #     item text, see #flags for detail. Default is to use no variant.
      #
      # Examples:
      #
      #   doc.destinations.add("Title") do |item|                  # no action, just container
      #     item.add("Second subitem", destination: doc.pages[1])  # links to page 2
      #     item.add("First subitem", position: :first, destination: doc.pages[0])
      #   end
      def add_item(title, destination: nil, action: nil, position: :last, open: true,
                   text_color: nil, flags: nil) # :yield: item
        if title.kind_of?(HexaPDF::Object) && title.type == :XXOutlineItem
          item = title
          item.delete(:Prev)
          item.delete(:Next)
          item.delete(:First)
          item.delete(:Last)
          if item[:Count] && item[:Count] >= 0
            item[:Count] = 0
          else
            item.delete(:Count)
          end
          item[:Parent] = self
        else
          item = document.add({Parent: self}, type: :XXOutlineItem)
          item.title(title)
          if action
            item.action(action)
          else
            item.destination(destination)
          end
          item.text_color(text_color) if text_color
          item.flag(*flags) if flags
          item[:Count] = 0 if open # Count=0 means open if items are later added
        end

        unless position == :last || position == :first || position.kind_of?(Integer)
          raise ArgumentError, "position must be :first, :last, or an integer"
        end
        if self[:First]
          case position
          when :last, -1
            item[:Prev] = self[:Last]
            self[:Last][:Next] = item
            self[:Last] = item
          when :first, 0
            item[:Next] = self[:First]
            self[:First][:Prev] = item
            self[:First] = item
          when Integer
            temp, direction = if position > 0
                                [self[:First], :Next]
                              else
                                position = -position - 2
                                [self[:Last], :Prev]
                              end
            position.times { temp &&= temp[direction] }
            raise ArgumentError, "position out of bounds" if temp.nil?
            item[:Prev] = temp[:Prev]
            item[:Next] = temp
            temp[:Prev] = item
            item[:Prev][:Next] = item
          end
        else
          self[:First] = self[:Last] = item
        end

        # Re-calculate /Count entries
        temp = self
        while temp
          if !temp.key?(:Count) || temp[:Count] < 0
            temp[:Count] = (temp[:Count] || 0) - 1
            break
          else
            temp[:Count] += 1
          end
          temp = temp[:Parent]
        end

        yield(item) if block_given?

        item
      end

      # :call-seq:
      #   item.each_item {|descendant_item, level| block }   -> item
      #   item.each_item                                     -> Enumerator
      #
      # Iterates over all descendant items of this one.
      #
      # The descendant items are yielded in-order, yielding first the item itself and then its
      # descendants.
      def each_item(&block)
        return to_enum(__method__) unless block_given?
        return self unless (item = self[:First])

        level = self.level + 1
        while item
          yield(item, level)
          item.each_item(&block)
          item = item[:Next]
        end

        self
      end

      private

      def perform_validation # :nodoc:
        super
        first = self[:First]
        last = self[:Last]
        if (first && !last) || (!first && last)
          yield('Outline item dictionary is missing an endpoint reference', true)
          node, dir = first ? [first, :Next] : [last, :Prev]
          node = node[dir] while node[dir]
          self[dir == :Next ? :Last : :First] = node
        elsif !first && !last && self[:Count] && self[:Count] != 0
          yield('Outline item dictionary key /Count set but no descendants exist', true)
          delete(:Count)
        end

        prev_item = self[:Prev]
        if prev_item && (prev_item_next = prev_item[:Next]) != self
          if prev_item_next
            yield('Outline item /Prev points to item whose /Next points somewhere else', false)
          else
            yield('Outline item /Prev points to item without /Next', true)
            prev_item[:Next] = self
          end
        end

        next_item = self[:Next]
        if next_item && (next_item_prev = next_item[:Prev]) != self
          if next_item_prev
            yield('Outline item /Next points to item whose /Prev points somewhere else', false)
          else
            yield('Outline item /Next points to item without /Prev', true)
            next_item[:Prev] = self
          end
        end
      end

    end

  end
end