# Actions: Desktop

install4j BeanInfo catalog. Each entry below documents a bean class that can appear inside a `<serializedBean>` element in an install4j project file.

## Contents

- [Add a desktop link](#add-a-desktop-link) — `com.install4j.runtime.beans.actions.desktop.CreateDesktopLinkAction`
- [Add a startup executable](#add-a-startup-executable) — `com.install4j.runtime.beans.actions.desktop.AddStartupItemAction`
- [Add an executable to the dock](#add-an-executable-to-the-dock) — `com.install4j.runtime.beans.actions.desktop.AddToDockAction`
- [Create a file association](#create-a-file-association) — `com.install4j.runtime.beans.actions.desktop.CreateFileAssociationAction`
- [Create a Windows URL link](#create-a-windows-url-link) — `com.install4j.runtime.beans.actions.desktop.CreateUrlLinkAction`
- [Create default start menu entries](#create-default-start-menu-entries) — `com.install4j.runtime.beans.actions.desktop.CreateDefaultStartMenuEntriesAction`
- [Create start menu entry](#create-start-menu-entry) — `com.install4j.runtime.beans.actions.desktop.CreateStartMenuEntryAction`
- [Register a URL handler](#register-a-url-handler) — `com.install4j.runtime.beans.actions.desktop.UrlHandlerAction`
- [Register Add/Remove item](#register-add-remove-item) — `com.install4j.runtime.beans.actions.desktop.RegisterAddRemoveAction`

---

### Add a desktop link
- **Class:** `com.install4j.runtime.beans.actions.desktop.CreateDesktopLinkAction`
- **Category:** Desktop integration
- **Multiple instances:** yes
- **Installed files required:** yes

Create a link on the desktop to an installed executable or file. This action will be automatically reverted by the 'Uninstall files' action.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `file` — Target file | File | Configuration | — | The installed file or executable for which a link will be created on the desktop |
| `name` — Name | String | Configuration | — | The name of the desktop icon |
| `allUsers` — Create for all users | boolean | Windows | — | If the desktop link should be created for all users. If unselected, the link will be created for the current user only. |
| `winIconFile` — Icon file | ExternalFile suffixes=[ico] | Windows | — | An optional different icon (*.ico) for the link on Windows. |
| `unixIconFile` — Icon file | ExternalFile suffixes=[png, gif] | Unix | — | An optional image file (*.png) for the entry. If empty, no icon will be written to the desktop file. |
| `additionalDesktopFileEntries` — Additional desktop file entries | String [context=multiline] | Unix | — | Optional additional desktop file entries. If this property contains default entry types, the default values will be replaced. |
| `description` — Tooltip description | String | Windows | — | An optional description for Windows that will be displayed in the tooltip. |
| `startIn` — Start in | File | Windows | — | An optional working directory for the started executable. |
| `runAsAdministrator` — Run as administrator | boolean | Windows | — | If the desktop link should always be run as administrator. |
| `macSingleBundleTarget` — Target is Single Bundle | boolean | macOS | — | If selected and the media set is a single bundle archive, the desktop icon will point to the bundle instead. |
| `arguments` — Arguments | String | Configuration | — | Optional arguments to the executable for Windows and Unix. |

### Add a startup executable
- **Class:** `com.install4j.runtime.beans.actions.desktop.AddStartupItemAction`
- **Category:** Desktop integration
- **Multiple instances:** yes
- **Installed files required:** yes

Add an installed executable to the startup folder on Windows, as a launch agent on macOS or as a systemd user service on Linux so that it will be started automatically when the user logs in. This action will be automatically reverted by the 'Uninstall files' action.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `executable` — Startup executable | File | Configuration | — | The executable that should be started when the user logs in |
| `arguments` — Arguments | String[] | Configuration | — | The arguments passed to the executable. Please note that in the edit dialog, each argument starts on a new line. Arguments that are installer variables with array or collection values (e.g. String[], Object[] or List<File>) are expanded as separate arguments, this allows you to build a variable length list of arguments at runtime. |
| `startImmediately` — Start immediately | boolean | Configuration | — | If the executable should be started immediately by the action |
| `name` — Entry name | String | Windows | — | The name of the entry in the startup folder |
| `allUsers` — Create for all users | boolean | Windows | — | If the startup item should be created for all users. If unselected, the link will be created for the current user only. |
| `hide` — Set the hide flag | boolean | macOS | — | If the hide flag should be set for the login item. |
| `macosIdentifier` — macOS identifier | String | macOS | — | The optional identifier for the launch agent. If not specified, an identifier will be generated automatically. |
| `requireGraphicalSession` — Require graphical session | boolean | Unix | — | If the systemd user service should require a graphical session. |

### Add an executable to the dock
- **Class:** `com.install4j.runtime.beans.actions.desktop.AddToDockAction`
- **Category:** Desktop integration
- **Multiple instances:** yes
- **Installed files required:** yes

Add an installed executable to the dock on macOS. This action will be automatically reverted by the 'Uninstall files' action.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `executable` — Executable | File | Configuration | — | The executable that should be added to the dock. |

### Create a file association
- **Class:** `com.install4j.runtime.beans.actions.desktop.CreateFileAssociationAction`
- **Category:** Desktop integration
- **Multiple instances:** yes
- **Installed files required:** yes

Create an association between a file extension and a launcher, so that the launcher is invoked when the user double-clicks a file with the selected extension. If the application has not yet been started, the arguments to the main method will contain the file name. Subsequent invocations can be intercepted with the com.install4j.api.launcher.StartupNotification class. This action will be automatically reverted by the 'Uninstall files' action. For macOS, file associations have to be defined on the "Executable info->macOS options" step of the launcher wizard.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `extension` — File extension | String | General | — | The file extension for which the file association should be created. Must not include the leading dot. Multiple extensions can be separated with a comma. |
| `description` — Description | String | General | — | A description that is presented to the user as the text next to the corresponding checkbox in the "File associations" screen. |
| `launcherId` — Launcher | String [context=nonServiceLauncher] | General | — | The launcher that will be invoked when the file association is invoked by the user. |
| `selected` — Selected | boolean | General | — | If the file association is selected in the "File associations" screen. |
| `windows` — Execute on Windows | boolean | Windows | — | If the file association should be performed on Windows. |
| `windowsIconFile` — Icon file for Windows | ExternalFile | Windows | — | An optional icon file (*.ico) for the file association on Windows. If empty, a default icon will be used. |
| `winAdditionalParameters` — Additional parameters | String | Windows | — | Optional additional parameters that will be passed to the executable in front of the file to be opened. |
| `unix` — Execute on Linux/Unix | boolean | Unix | — | If the file association should be performed on Linux/Unix. A MIME type must be specified in that case. |
| `unixMimeType` — MIME type | String | Unix | — | The MIME type to be used for the Unix file association. |
| `unixIconFile` — Icon file for Linux/Unix | ExternalFile | Unix | — | An optional icon file (*.png) for the file association on Linux/Unix. If empty, a default icon will be used. A 64x64 icon is recommended. |

### Create a Windows URL link
- **Class:** `com.install4j.runtime.beans.actions.desktop.CreateUrlLinkAction`
- **Category:** Desktop integration
- **Multiple instances:** yes
- **Installed files required:** yes

Create a URL link on Windows. This is a special text file with a .url link that is supported by the Windows desktop, start menu, and explorer. To create links in the start menu, the "Create start menu entry" action can be used as well. This action will be automatically reverted by the 'Uninstall files' action.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `url` — URL | String | Configuration | — | The URL that should be linked to. If no protocol is given, http:// is assumed. |
| `file` — Target file | File | Configuration | — | The path of the URL link, including the name of the link, but without the .url extension. To create a link on the desktop, prefix with ${installer:sys.desktopDir} |
| `icon` — Icon file | ExternalFile | Configuration | — | An optional icon file (*.ico) for the URL link. If empty, the default icon will be used. |
| `useFavicon` — Use favicon | boolean | Configuration | — | If the favicon file of the URL domain should be used. This only works if the icon has been cached by Internet Explorer. |

### Create default start menu entries
- **Class:** `com.install4j.runtime.beans.actions.desktop.CreateDefaultStartMenuEntriesAction`
- **Category:** Desktop integration
- **Multiple instances:** yes
- **Installed files required:** yes
- **Customizer:** `com.install4j.runtime.beans.customizers.programgroup.ProgramGroupEntriesCustomizer`

Create default start menu entries on Windows and freedesktop.org compatible UNIX desktops. This action will be automatically reverted by the 'Uninstall files' action.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `allUsers` — Create for all users | boolean | Windows | — | If the entries are created for all users or only for the current user. |
| `folderName` — Folder name | String | Windows | — | The default value for the folder where the links will be created. If you leave this property empty, the links will be created at the top level. |
| `unixSymlinks` — Create symlinks | boolean | Unix | — | If symbolic links for all relevant launchers (those with "menu integration" enabled) should be created on UNIX. |
| `linkDirectory` — Directory for links | String | Unix | `unixSymlinks`=true | The directory in which links for all relevant launchers (those with "menu integration" enabled) will be created on UNIX. |
| `failForSymlinksNotCreated` — Fail if symlinks are not created | boolean | Unix | `unixSymlinks`=true | If selected, the action will fail if the symlinks cannot be created. Usually this is due to missing write permissions which is a common condition, so that the action does not fail by default. |
| `unixMenuEntries` — Create menu entries | boolean | Unix | — | If menu entries should be created on freedesktop.org (KDE, GNOME) systems. |
| `categories` — Application categories | String | Unix | `unixMenuEntries`=true | The freedesktop.org (KDE, GNOME) application categories used to determine the best place in the application menu. Multiple categories can be separated by semicolons. |

### Create start menu entry
- **Class:** `com.install4j.runtime.beans.actions.desktop.CreateStartMenuEntryAction`
- **Category:** Desktop integration
- **Multiple instances:** yes
- **Installed files required:** yes

Create a single start menu entry on Windows and Unix. This action will be automatically reverted by the 'Uninstall files' action.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `entryName` — Entry name | String | Configuration | — | The entry name in the start menu. On Windows, the name can contain subfolders with backslashes. |
| `file` — Target file | File | Configuration | — | The installed file or executable for which a start menu entry will be created |
| `arguments` — Arguments | String | Configuration | — | Optional arguments that should be passed to the executable when started with this entry. |
| `icon` — Icon file | ExternalFile suffixes=[ico] | Windows | — | An optional icon file (*.ico) for the entry. If empty, the default icon will be used. |
| `allUsers` — Create for all users | boolean | Windows | — | If the entry is created for all users or only for the current user. |
| `folderName` — Folder name | String | Windows | — | The default value for the folder where the link will be created. If you leave this property empty, the link will be created at the top level. |
| `startIn` — Start in | File | Windows | — | An optional working directory for the started executable. |
| `runAsAdministrator` — Run as administrator | boolean | Windows | — | If the executable should always be run as administrator. |
| `categories` — Application categories | String | Unix | — | The freedesktop.org (KDE, GNOME) application categories used to determine the best place in the application menu. Multiple categories can be separated by semicolons. |
| `unixIconFile` — Icon file | ExternalFile suffixes=[png, gif] | Unix | — | An optional image file (*.png) for the entry. If empty, no icon will be written to the desktop file. |
| `additionalDesktopFileEntries` — Additional desktop file entries | String [context=multiline] | Unix | — | Optional additional desktop file entries. If this property contains default entry types, the default values will be replaced. |

### Register a URL handler
- **Class:** `com.install4j.runtime.beans.actions.desktop.UrlHandlerAction`
- **Category:** Desktop integration
- **Multiple instances:** yes
- **Installed files required:** yes

Register a URL handler for a custom scheme, so that the launcher is invoked when the user clicks on a link with the specified scheme. On Windows and Linux, the arguments to the main method will contain the URL. On macOS, the arguments are available from the com.install4j.api.launcher.StartupNotification class. If the "Allow only a single running instance of the application" check box is selected on the "Java invocation" step of the launcher wizard, subsequent invocations are intercepted by the com.install4j.api.launcher.StartupNotification class on all platforms. This action will be automatically reverted by the 'Uninstall files' action. For macOS, URL handlers have to be defined on the "Executable info->macOS options" step of the launcher wizard.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `scheme` — Scheme | String | General | — | The scheme for which the URL handler should be created. Must not include the trailing colon. For example, the scheme hello will match URLs like hello://world. |
| `launcherId` — Launcher | String [context=nonServiceLauncher] | General | — | The launcher that will be invoked. |

### Register Add/Remove item
- **Class:** `com.install4j.runtime.beans.actions.desktop.RegisterAddRemoveAction`
- **Category:** Desktop integration
- **Multiple instances:** no
- **Installed files required:** yes

Register an Add/Remove item in the Windows software registry. If this action runs with elevated privileges, the uninstaller will be started with elevated privileges by Windows and no unelevated actions can be performed. In the event that you need to execute processes without elevation, set the "Action elevation type" property to "Do not elevate". Note that the Add/Remove item will be registered for the current user only in that case. This action will be automatically reverted by the 'Uninstall files' action.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `itemName` — Item name | String | Configuration | — | The name of the item that is displayed in the Windows software registry. |
| `iconSource` — Icon source | [IconSource](enums.md#iconsource) | Configuration | — | The source of the icon in Windows software registry. You can use the icon of the installer or specify a custom .ico file. |
| `icon` — Icon file | ExternalFile suffixes=[ico] | Configuration | `iconSource`=Custom icon | An optional icon file (*.ico). |

