Opening URLs
3
EXO Library

# Opening URLs

Display URLs using appropriate viewers

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <exo/exo.h>

    enum                ExoUrlError;
    #define             EXO_URL_ERROR
    gboolean            exo_url_show                        (const gchar *url,
                                                             gchar **envp,
                                                             GError **error);
    gboolean            exo_url_show_on_screen              (const gchar *url,
                                                             gchar **envp,
                                                             GdkScreen *screen,
                                                             GError **error);
    void                exo_url_about_dialog_hook           (GtkAboutDialog *about_dialog,
                                                             const gchar *link,
                                                             gpointer user_data);

## Description

Xfce users can configure which applications they wish to use for certain task, for example they can select their preferred web browser and mail reader from the Preferred Applications dialog. This module provides a means for applications to display an URL without having to worry about which viewer is going to ultimately handle the job.

One of the most popular use cases for this module is to provide the ability to open links from a GtkAboutDialog. Therefore a convenience hook is provided for this use case, see the documentation of `exo_url_about_dialog_hook()` for details.

## Details

### enum ExoUrlError

    typedef enum /*< skip >*/
    {
      EXO_URL_ERROR_NOT_SUPPORTED,
    } ExoUrlError;

The errors that can be returned due to bad parameters being passed to `exo_url_show()` or `exo_url_show_on_screen()`.

### EXO_URL_ERROR

    #define EXO_URL_ERROR (exo_url_error_quark ())

The domain of errors raised by this module.

### exo_url_show ()

    gboolean            exo_url_show                        (const gchar *url,
                                                             gchar **envp,
                                                             GError **error);

Convenience wrapper to `exo_url_show_on_screen()`, which shows the `url` on the default GdkScreen.

`url` :

  the URL that should be shown.

`envp` :

  child environment for the url handler or `NULL` to inherit parent's environment.

`error` :

  return location for errors or `NULL`.

Returns :

  `TRUE` on success, `FALSE` on error.

Since 0.3.1.3

### exo_url_show_on_screen ()

    gboolean            exo_url_show_on_screen              (const gchar *url,
                                                             gchar **envp,
                                                             GdkScreen *screen,
                                                             GError **error);

Tries to find a suitable handler for `url` in the list of preferred application categories and runs that handler with `url` on `screen`.

`url` :

  the URL that should be shown.

`envp` :

  child environment for the url handler or `NULL` to inherit parent's environment.

`screen` :

  the GdkScreen on which to open the URL handler for `url`.

`error` :

  return location for errors or `NULL`.

Returns :

  `TRUE` on success, `FALSE` on error.

Since 0.3.1.3

### exo_url_about_dialog_hook ()

    void                exo_url_about_dialog_hook           (GtkAboutDialog *about_dialog,
                                                             const gchar *link,
                                                             gpointer user_data);

This is a convenience function, which can be registered with GtkAboutDialog, to have the exo-url module open links clicked by the user in GtkAboutDialogs.

All you need to do is to register this hook with `gtk_about_dialog_set_url_hook()` and `gtk_about_dialog_set_email_hook()`. This can be done prior to calling `gtk_show_about_dialog()`, for example:

    static void show_about_dialog (void)
    {
      gtk_about_dialog_set_email_hook (exo_url_about_dialog_hook, NULL, NULL);
      gtk_about_dialog_set_url_hook (exo_url_about_dialog_hook, NULL, NULL);
      gtk_show_about_dialog (.....);
    }

`about_dialog` :

  the GtkAboutDialog in which the user activated a link.

`link` :

  the link, mail or web address, to open.

`user_data` :

  user data that was passed when the function was registered with `gtk_about_dialog_set_email_hook()` or `gtk_about_dialog_set_url_hook()`. This is currently unused within the context of this function, so you can safely pass `NULL` when registering this hook with GtkAboutDialog.

Since 0.3.1.3

## See Also

Executing Applications