Install with Portal
==========================
desktop-entry-lib allows you to directly install a Desktop Entry using the `DynamicLauncher Portal <https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.DynamicLauncher.html>`_.
This Portal should be working out of the box on any major Distro. You need `jeepney <https://pypi.org/project/jeepney>`_ installed to use the Portal.
You also need a Icon and a ID.

First you need to load the Icon as bytes. It must be a png or jpeg no larger than 512x512, or an svg.

.. code:: python

    with open("/path/to/my/icon", "rb") as f:
        icon = f.read()

Now, you need to create the Entry that you want to install.

.. code:: python

    entry = desktop_entry_lib.DesktopEntry()
    entry.Name.default_text = "My Name"
    entry.desktop_id = "com.example.App.Entry"
    entry.Exec = "my-app"

The desktop_id needs to start with the ID of your App e.g. If your AppID is :code:`com.example.App` you can use :code:`com.example.App.Entry` but not :code:`com.example.Entry`.
If you are not sure, just try any ID. You will get an error message that tells you what ID is allowed.

Now you just need to call :func:`~desktop_entry_lib.__init__.DesktopEntry.install_with_portal` with a `Window Identifier <https://flatpak.github.io/xdg-desktop-portal/docs/window-identifiers.html>`_. and your Icon.
If you don't have a Window Identifier, just use an empty string.
If an error occurs, :func:`~desktop_entry_lib.__init__.DesktopEntry.install_with_portal` will throw a :class:`~desktop_entry_lib.__init__.InstallWithPortalError` exception.
If the User cancels the Installation, a :class:`~desktop_entry_lib.__init__.InstallWithPortalsCanceled` exception is thrown.
If the DynamicLauncher Portal is not available, :class:`~desktop_entry_lib.__init__.InstallWithPortalsNotAvailable` is thrown.
If everything worked, it returns a dict that contains the Name and the Icon.

.. code:: python

    try:
        entry.install_with_portal("", icon)
    except desktop_entry_lib.InstallWithPortalsNotAvailable:
        print("The DynamicLauncher portal is not available")
    except desktop_entry_lib.InstallWithPortalError as ex:
        print(ex.message)
    except desktop_entry_lib.InstallWithPortalsCanceled:
        print("The user canceled the installation")

A dialog should appear, allowing the user to install the entry.
:func:`~desktop_entry_lib.__init__.DesktopEntry.install_with_portal` has the 2 Keywords arguments :code:`editable_name` and :code:`editable_icon`, which allows to control if the User can edit the Name/Icon in the dialog.
These arguments are not guaranteed to work on every desktop.

You should also take a look at the  :doc:`complete example </examples/InstallWithPortal>`.
