# Link Handlers

## Definition

A link handler defines how your application deals with hyperlinks, or simply links.

Eclipse plug-ins can contribute link handlers for custom URL schemes using the extension point `org.eclipse.urischeme.uriSchemeHandlers`.

## Use

You can add link handlers only by installing software into your application.

Link handlers can be enabled or disabled in the preference dialog. To do this, open the General > Link Handers preference page and select the relevant option.

## Introduction

Links are best known from the web where clicking on a links navigates the user to another web page. But the concept of links is also usefull for other use-case, for example file sharing. Here, a user uploads a file to a file hosting service and grants access to others by sending a link to that shared document through e-mail. When choosing such a link, the web browser, or another locally installed application will open this link.

### Sample

The URL of each link consists of a scheme, host, and path: `https://www.eclipse.org/downloads`

In this URL, the scheme is "https", the host name is "www.eclipse.org", and the path is "downloads". This URL addresses a hypertext document using the "https" URL scheme.

Choosing such a link, typically a web browser is opened. The web browser then downloads and displays the relevant document.

## URL Schemes

Link handlers incorporate the concept of custom URL schemes into the Eclipse platform. Different URL schemes have different meanings and need different handling. A link handler can handle specific URL schemes.

When a user clicks a link containing an URL scheme, which is enabled, the operating system will start the corresponding application or set the corresponding window to the foreground - if the application is already running. Link handling is specific to the URL scheme - it may open a file in an editor, open a dialog, install new software, clone a repository, or result in something else.

The Link Handers preference page provides a list of URL schemes which the applicaiton can handle. For each scheme, a description further explains the URL scheme. A checkbox shows if handling of this URL scheme is enabled or disabled. If handling is disabled, the list will also display if this URL scheme is handled by another application or not.

### Note

- The enabled state of each URL scheme is not persisted in the Eclipse preference store, but it is directly registered in the operating system. Therefore, this page does not take part in the export and import of preferences and does not provide a "Restore Defaults" button.
- For the "macOS" and "Linux" operating system: If an URL scheme is handled by another application (Eclipse-based or not), it cannot be enabled directly. Handling of this URL scheme must first be disabled in the other application, before it can be enabled in the current application.
- When multiple Eclipse-based applications are running at the same time, the operating system may set a window to the foreground, which cannot handle the link. In such cases, ensure that only the expected Eclipse-based application is running.
- In rare cases (e.g. PDE development) the path to the eclipse launcher can not be determined from the `eclipse.launcher` or `eclipse.home.location` system properties. The preference page will then show an error message and will not allow any interaction.