Install with Portal - desktop-entry-lib 5.0 documentation

Skip to content
Back to top
View this page

# Install with Portal

desktop-entry-lib allows you to directly install a Desktop Entry using the DynamicLauncher Portal. This Portal should be working out of the box on any major Distro. You need 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.

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

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

    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 `com.example.App` you can use `com.example.App.Entry` but not `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 `install_with_portal()` with a Window Identifier. and your Icon. If you don’t have a Window Identifier, just use an empty string. If an error occurs, `install_with_portal()` will throw a `InstallWithPortalError` exception. If the User cancels the Installation, a `InstallWithPortalsCanceled` exception is thrown. If the DynamicLauncher Portal is not available, `InstallWithPortalsNotAvailable` is thrown. If everything worked, it returns a dict that contains the Name and the Icon.

    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. `install_with_portal()` has the 2 Keywords arguments `editable_name` and `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 complete example.