.. oe:namespace:: OEDepict


.. meta::
   :keywords: OEMultiPageImageFile, MultiPageImageFile


.. _OEDepict_OEMultiPageImageFile:

.. oe:class:: OEMultiPageImageFile

   .. oe:api::

      class OEMultiPageImageFile

   The :ref:`OEMultiPageImageFile <OEDepict_OEMultiPageImageFile>` class supports the
   creation of multi-page images. The dimensions and orientation of
   the pages are determined when an
   :ref:`OEMultiPageImageFile <OEDepict_OEMultiPageImageFile>` object is created.
   Pages are created by calling the
   :oe:meth:`OEDepict::OEMultiPageImageFile::NewPage` method.
   See :ref:`Figure: Schematic representation of an OEMultiPageImageFile object<figure_OEMultiPageImageFile>`.

   .. _figure_OEMultiPageImageFile:

   .. figure:: ../images/OEMultiPageImageFile.*
      :align:  center

      **Schematic representation of an OEMultiPageImageFile object**

   .. seealso::

      * :ref:`chapter_multipage` chapter
      * :oe:func:`OEDepict::OEGetSupportedMultiPageImageFileExtensions` function

   .. hint::

       We highly recommend to usage of the more convenient high-level
       :ref:`OEReport <OEDepict_OEReport>` class when generating multi-page images.

       * :ref:`section_multipage_report` section
       * :ref:`section_examples_summary_mols2pdf` example
       * :ref:`section_examples_summary_viewmdlsearch` example


   .. ################################################################
      # Constructors
      ################################################################

   .. oe:method:: Constructors

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEMultiPageImageFile(double pagewidth, double pageheight)

      .. oe:language:: python

         .. oe:api:: python

            OEMultiPageImageFile(width: float, height: float) -> OEMultiPageImageFile

      Creates an :ref:`OEMultiPageImageFile <OEDepict_OEMultiPageImageFile>` object with a
      specified page width and height.
      Both the width and the height parameters have to be positive
      (non-zero) numbers.

      .. ################################################################

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEMultiPageImageFile(unsigned int orientation,
                                 unsigned int imagesize)

      .. oe:language:: python

         .. oe:api:: python

            OEMultiPageImageFile(orientation: int, imagesize: int) -> OEMultiPageImageFile

      Creates an :ref:`OEMultiPageImageFile <OEDepict_OEMultiPageImageFile>` object with
      the given orientation and size.

      *orientation*
         Determine the orientation of the pages. 
         This value has to be from the
         :oe:constns:`OEDepict::OEPageOrientation` namespace.

      *imagesize*
         Determine the width and height of the pages. 
         This value has to be from the :oe:constns:`OEDepict::OEPageSize`
         namespace.

      .. seealso::

         * :oe:func:`OEDepict::OEGetPageHeight` function
         * :oe:func:`OEDepict::OEGetPageWidth` function


   .. ################################################################
      # GetOrientation
      ################################################################

   .. oe:method:: GetOrientation

      .. oe:language:: c++ java csharp

         .. oe:api::

            unsigned int GetOrientation() const

      .. oe:language:: python

         .. oe:api:: python

            GetOrientation() -> int

      Returns the orientation of the pages.
      The return value is taken from the
      :oe:constns:`OEDepict::OEPageOrientation` namespace.

   .. ################################################################
      # GetPageHeight
      ################################################################

   .. oe:method:: GetPage

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEImage* GetPage(unsigned int page)
            const OEImage* GetPage(unsigned int page) const

      .. oe:language:: python

         .. oe:api:: python

            GetPage(page: int) -> OEImage

      Returns the :math:`p^{th}` page .

      *p*
         This value has to be in the range from `1` to
         :oe:meth:`OEDepict::OEMultiPageImageFile::NumPages()<OEDepict::OEMultiPageImageFile::NumPages>`.

      .. note::

         If :math:`p` page index is out of range, then the
         :oe:meth:`OEDepict::OEMultiPageImageFile::GetPage` method
         returns a NULL pointer.


   .. ################################################################
      # GetPageHeight
      ################################################################

   .. oe:method:: GetPageHeight

      .. oe:language:: c++ java csharp

         .. oe:api::

            double GetPageHeight() const

      .. oe:language:: python

         .. oe:api:: python

            GetPageHeight() -> float

      Returns the height of the pages.


   .. ################################################################
      # GetPageWidth
      ################################################################

   .. oe:method:: GetPageWidth

      .. oe:language:: c++ java csharp

         .. oe:api::

            double GetPageWidth() const

      .. oe:language:: python

         .. oe:api:: python

            GetPageWidth() -> float

      Returns the width of the pages.


   .. ################################################################
      # GetPages
      ################################################################

   .. oe:method:: GetPages

      .. oe:language:: c++ java csharp

         .. oe:api::

            OESystem::OEIterBase<OEImage>* GetPages()
            OESystem::OEIterBase<const OEImage>* GetPages() const

      .. oe:language:: python

         .. oe:api:: python

            GetPages() -> Iterable[OEImage]

      Returns an iterator over all pages stored in the
      :ref:`OEMultiPageImageFile <OEDepict_OEMultiPageImageFile>` object.


   .. ################################################################
      # NewPage
      ################################################################

   .. oe:method:: NewPage

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEImage& NewPage()

      .. oe:language:: python

         .. oe:api:: python

            NewPage() -> OEImage

      Returns a new page as an :ref:`OEImage <OEDepict_OEImage>` object.


   .. ################################################################
      # NumPages
      ################################################################

   .. oe:method:: NumPages

      .. oe:language:: c++ java csharp

         .. oe:api::

            unsigned int NumPages() const

      .. oe:language:: python

         .. oe:api:: python

            NumPages() -> int

      Returns the number of pages stored in the
      :ref:`OEMultiPageImageFile <OEDepict_OEMultiPageImageFile>` object.
