.. role:: python(code)
    :language: python
    :class: highlight


Python Quick Start
==================

Most functions in Mari are performed by using a manager object. These managers perform many operations themselves, and also provide access to other types of objects. For example, the project manager object is :py:class:`mari.projects`, and calling its :py:meth:`list()<mari.ProjectManager.list>` method provides :py:class:`ProjectInfo<mari.ProjectInfo>` objects to describe the projects that are available. The manager objects are listed in the Variables section below.



If you understand the basics of Python and want to try using it to get Mari to do something, here
are some examples of how to perform some common tasks.

.. list-table::

    * - To open a project:
      - .. code-block:: 

            mari.projects.open('your_project_name')
    * - To get a list of the available projects:
      - .. code-block:: 

            mari.projects.list()
    * - To get the currently selected geometry object:
      - .. code-block:: 

            mari.geo.current()
    * - To get a list of the image sets on the current geometry object:
      - .. code-block:: 

            mari.geo.current().imageSetList()
    * - To undo the last action:
      - .. code-block:: 

            mari.history.undo()
    * - To add a Python script to the menu:
      - .. code-block:: 

            action = mari.actions.create('Test Action', 'mari.utils.message("Hello")')
            mari.menus.addAction(action, 'MainWindow/Test Menu')
    * - To get access to the current camera:
      - .. code-block:: 

            mari.canvases.current().camera()
    * - To get access to the paint buffer:
      - .. code-block:: 

            mari.canvases.paintBuffer()
    * - To create an example PySide widget:
      - .. code-block::

            button = PySide.QtGui.QPushButton('Push Me')
            button.show()
    * - To be notified when a script error occurs:
      - .. code-block::

            def on_error(message):
                print('Script error:', message)
            script_manager = mari.ScriptManager()
            script_manager.errorOccurred.connect(on_error)
    * - To create an example QML widget:
      - .. code-block::

            view = QQuickView()
            container = QWidget.createWindowContainer(view)
            host = QWidget()
            layout = QVBoxLayout(host)
            layout.addWidget(container)
            palette = mari.palettes.create("QML Palette", host)
            palette.setBodyWidget(host)


There are also a considerable number of example scripts documented in the :py:class:`mari.examples`
module.  You can look at the source code of these to get some further ideas.  Please note though that
the source code is only useful for the examples; the source code for the "mari" module is simply a set
of generated function stubs with doc strings provided for structural reasons.

Most functions in Mari are performed by using a manager object, as above.. These managers perform 
many operations themselves, and also provide access to other types of objects. For example, the 
project manager object is :py:class:`mari.projects`, and calling its :py:meth:`list()<mari.ProjectManager.list>`
method provides :py:class:`ProjectInfo<mari.ProjectInfo>` objects to describe the projects that are available.
The manager objects are listed in the Variables section below.


Mari's Python API uses PySide. Reference documentation can be found at:
- `The PySide project <https://pypi.org/project/PySide6/>`_
- `The Qt library <https://doc.qt.io/qt-6//>`_