Opening URLs

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

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