.. _chapter_multipage:

********************************************************************************
Multi Page Images
********************************************************************************

Multi-page images can be generated by the usage of the
:ref:`OEMultiPageImageFile <OEDepict_OEMultiPageImageFile>` class.
After generating a multi-page object by specifying the orientation and
the size of its pages, the individual pages can be accessed by calling
the :oe:meth:`OEDepict::OEMultiPageImageFile::NewPage` method.
The returned :ref:`OEImage <OEDepict_OEImage>` then can be used to depict
molecule(s) as demonstrated in the previous chapters.
The image created by :oe:src:`Listing 1<SNIPPET-MULTIPAGE-MultiPage>` is shown in
:ref:`Figure: Example multi-page depiction<figure_multipage>`.

.. oe:source:: MultiPage.py
   :language: python
   :refnum:   1
   :caption:  Example of multi-page depiction
   :frag:     SNIPPET-MULTIPAGE

.. oe:source:: MultiPage.cpp
   :language: c++
   :refnum:   1
   :caption:  Example of multi-page depiction
   :frag:     SNIPPET-MULTIPAGE

.. oe:source:: MultiPage.java
   :language: java
   :refnum:   1
   :caption:  Example of multi-page depiction
   :frag:     SNIPPET-MULTIPAGE

.. oe:source:: MultiPage.cs
   :language: csharp
   :refnum:   1
   :caption:  Example of multi-page depiction
   :frag:     SNIPPET-MULTIPAGE

.. _figure_multipage:

.. list-table:: **Example multi-page depiction** (The pages are reduced here for visualization convenience)
   :widths: 150 150 
   :header-rows: 1

   * - page 1
     - page 2
   * - .. image:: images/MultiPage-1.*
         :align:  center
     - .. image:: images/MultiPage-2.*
         :align:  center
 
The :oe:src:`Listing 1<SNIPPET-MULTIPAGE-MultiPage>` example creates a :file:`PDF` multi-page image
file, the multi-page image types supported by **OEDepict TK** can be accessed by
calling the :oe:func:`OEDepict::OEGetSupportedMultiPageImageFileExtensions`
function.
It returns an iterator over the file extensions that can be used when
writing a multi-page  image file by the
:oe:func:`OEDepict::OEWriteMultiPageImage` function.

.. _section_multipage_report:

Multi Page Reports
================================================================================

The :oe:src:`Listing 1<SNIPPET-MULTIPAGE-MultiPage>` example illustrates how depict a set of
molecules in a multi-page :file:`PDF` using the :ref:`OEImageGrid <OEDepict_OEImageGrid>`
and :ref:`OEMultiPageImageFile <OEDepict_OEMultiPageImageFile>` classes.
**OEDepict TK** also provides the :ref:`OEReport <OEDepict_OEReport>` class to do
this task in a more convenient way.
The :ref:`OEReport <OEDepict_OEReport>` class is a multi-page layout manager that
handles the page generation and the positioning of information
(such as text and molecule depiction).

In the :oe:src:`Listing 2<SNIPPET-MULTIPAGE-REPORT-MultiPageReport>` example, first a
:ref:`OEReportOptions <OEDepict_OEReportOptions>` object is created that stores
all properties that determine the layout of a documentation.
After generating the :ref:`OEReport <OEDepict_OEReport>` object a
molecule can be positioned on a cell that is returned by
the :oe:meth:`OEDepict::OEReport::NewCell` method.
The :oe:meth:`OEDepict::OEReport::NewCell` method creates cells
from left to right and top to bottom order on each page.
If no more cells are left on the page, then a new page is created
before returning the first cell of this new page.

After the document is generated, *i.e* all molecule are depicted,
the :oe:func:`OEDepict::OEWriteReport` function writes the multi-page
documentation into into a file with the given name.
The image created by the :oe:src:`Listing 2<SNIPPET-MULTIPAGE-REPORT-MultiPageReport>` example is the
same as depicted in :ref:`Figure: Example multi-page depiction<figure_multipage>`.

.. oe:source:: MultiPageReport.py
   :language: python
   :refnum:   2
   :caption:  Example of multi-page depiction using OEReport
   :frag:     SNIPPET-MULTIPAGE-REPORT

.. oe:source:: MultiPageReport.cpp
   :language: c++
   :refnum:   2
   :caption:  Example of multi-page depiction using OEReportOptions
   :frag:     SNIPPET-MULTIPAGE-REPORT

.. oe:source:: MultiPageReport.java
   :language: java
   :refnum:   2
   :caption:  Example of multi-page depiction using the OEReport class
   :frag:     SNIPPET-MULTIPAGE-REPORT

.. oe:source:: MultiPageReport.cs
   :language: csharp
   :refnum:   2
   :caption:  Example of multi-page depiction using the OEReport classes
   :frag:     SNIPPET-MULTIPAGE-REPORT

.. seealso::

   * :ref:`OEReportOptions <OEDepict_OEReportOptions>` class
   * :ref:`OEReport <OEDepict_OEReport>` class

