[Fwd: gtk_show_help and gtk_show_url]



FYI,

Food for thought for hildon-help and libhildonmime maintainers.


-- 
Tommi Komulainen                            <tommi komulainen nokia com>
--- Begin Message ---
Hi,

Sketching out an API here, prototype attached.

See also http://mail.gnome.org/archives/gtk-devel-list/2007-September/msg00139.html

Some questions:
- in current GNOME, what are the right "parameters" to open a help file? (i.e. what values does gtk_help_show() need to open a gnome help file, such as document ID or anchor or whatever)

 - it looks like GTK doesn't use startup notification at all right now?
There are three ways I can think of to code launching an URL from gtk:
1) have a dbus service that does all the startup notification and other work, and invoke it from gtk 2) do all the startup notification and so forth in gtk itself, and call xdg-open (does xdg-open support SN properly?)
   3) dlopen gnome-vfs and call its code for this

- are the _with_env() flavors of these functions needed, if gtk does startup notification itself? (gnome-vfs and libgnome have with_env versions of url_show and help_show)

Sorry for the cross-post, but it affects both libgnome and gtk ...

Havoc




/*
 * Copyright (C) 2007 Red Hat, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 *
 * Author: Havoc Pennington <hp redhat com>
 */

#include <config.h>
#include "gtkdesktop.h"
#include "gtkdesktopx.h"
#include "gtkmain.h"
#include "gtkprivate.h"
#include "gtkintl.h"

#include <gdk/gdkconfig.h> /* for GDK_WINDOWING_* */

static void set_property (GObject      *object,
                          guint         prop_id,
                          const GValue *value,
                          GParamSpec   *pspec);
static void get_property (GObject      *object,
                          guint         prop_id,
                          GValue       *value,
                          GParamSpec   *pspec);
static void finalize     (GObject      *object);


enum
{
  PROP_0,
  PROP_DISPLAY
};

struct _GtkDesktopPrivate 
{
  GdkDisplay *display;
};


G_DEFINE_ABSTRACT_TYPE (GtkDesktop, _gtk_desktop, G_TYPE_OBJECT);

static void
_gtk_desktop_class_init (GtkDesktopClass *class)
{
  GObjectClass *gobject_class;
  
  gobject_class = G_OBJECT_CLASS (class);
  gobject_class->finalize = finalize;

  gobject_class->set_property = set_property;
  gobject_class->get_property = get_property;
  
  g_object_class_install_property (gobject_class,
                                   PROP_DISPLAY,
                                   g_param_spec_object ("display",
							P_("Display"),
							P_("The GdkDisplay the desktop object is for"),
                                                        GDK_TYPE_DISPLAY,
							GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
}

static void
_gtk_desktop_init (GtkDesktop *desktop)
{
  desktop->priv = G_TYPE_INSTANCE_GET_PRIVATE (desktop, GTK_TYPE_DESKTOP, GtkDesktopPrivate);  
}

GtkDesktop *
_gtk_desktop_new (GdkDisplay *display)
{
  GtkDesktop *concrete = NULL;
	
#ifdef GDK_WINDOWING_X11
  concrete = _gtk_desktop_x_new (display);
  if (concrete)
    return concrete;
#endif

  /* FIXME return implementations for other platforms */

  g_warning("This platform does not implement GtkDesktop backend");
  return NULL;
}

static void
finalize (GObject *object)
{
  G_OBJECT_CLASS (_gtk_desktop_parent_class)->finalize (object);
}

static void
set_property (GObject      *object,
              guint         prop_id,
              const GValue *value,
              GParamSpec   *pspec)
{
  GtkDesktop *desktop;

  desktop = GTK_DESKTOP (object);

  switch (prop_id)
    {
    case PROP_DISPLAY:
      {
        GdkDisplay *new_display = g_value_get_object (value);
        if (new_display)
          g_object_ref (new_display);
        if (desktop->priv->display)
          g_object_unref (desktop->priv->display);
        desktop->priv->display = new_display;
      }
      break;
    default:
      g_assert_not_reached ();
      break;
    }
}

static void
get_property (GObject      *object,
              guint         prop_id,
              GValue       *value,
              GParamSpec   *pspec)
{
  GtkDesktop *desktop;

  desktop = GTK_DESKTOP (object);

  switch (prop_id)
    {
    case PROP_DISPLAY:
      g_value_set_object (value, desktop->priv->display);
      break;
    default:
      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
      break;
    }
}

GtkDesktop*
_gtk_desktop_get_for_display (GdkDisplay *display)
{
  GtkDesktop *desktop;
  
  g_return_val_if_fail (GDK_IS_DISPLAY (display), NULL);

  desktop = g_object_get_data (G_OBJECT (display), "gtk-desktop-for-display");
  if (desktop == NULL)
    {
      desktop = _gtk_desktop_new (display);
      g_object_set_data_full (G_OBJECT (display), "gtk-desktop-for-display", desktop,
                              g_object_unref);
    }

  return desktop;
}

static void
fill_defaults (GtkDesktop   *desktop,
               GdkScreen   **screen_p,
               guint32      *timestamp_p)
{
  if (*screen_p == NULL)
    *screen_p = gdk_display_get_default_screen (desktop->priv->display);
  
  if (*timestamp_p == 0)
    *timestamp_p = gtk_get_current_event_time ();
}

gboolean
_gtk_desktop_show_help (GtkDesktop  *desktop,
                        GdkScreen   *screen,
                        guint32      timestamp,
                        const char  *help_system_name,
                        char       **param_names,
                        char       **param_values,
                        GError     **error)
{
  g_return_val_if_fail (GTK_IS_DESKTOP (desktop), FALSE);

  fill_defaults (desktop, &screen, &timestamp);

  g_return_val_if_fail (GDK_IS_SCREEN (screen), FALSE);
  
  return (* GTK_DESKTOP_GET_CLASS(desktop)->show_help) (desktop, screen, timestamp,
                                                        help_system_name,
                                                        param_names, param_values,
                                                        error);
}

gboolean
_gtk_desktop_show_url (GtkDesktop  *desktop,
                       const char  *url,
                       GdkScreen   *screen,
                       guint32      timestamp,
                       GError     **error)
{
  g_return_val_if_fail (GTK_IS_DESKTOP (desktop), FALSE);

  fill_defaults (desktop, &screen, &timestamp);

  g_return_val_if_fail (GDK_IS_SCREEN (screen), FALSE);
  
  return (* GTK_DESKTOP_GET_CLASS(desktop)->show_url) (desktop, url, screen, timestamp,
                                                       error);
}

GdkDisplay*
_gtk_desktop_get_display (GtkDesktop  *desktop)
{
  g_return_val_if_fail (GTK_IS_DESKTOP (desktop), NULL);
  
  return desktop->priv->display;
}
/*
 * Copyright (C) 2007 Red Hat, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 *
 * Author: Havoc Pennington <hp redhat com>
 */

#ifndef __GTK_DESKTOP_H__
#define __GTK_DESKTOP_H__

#include <gdk/gdk.h>

G_BEGIN_DECLS

#define GTK_TYPE_DESKTOP		(_gtk_desktop_get_type ())
#define GTK_DESKTOP(obj)		(G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_DESKTOP, GtkDesktop))
#define GTK_DESKTOP_CLASS(klass)	(G_TYPE_CHECK_CLASS_CAST ((klass), GTK_TYPE_DESKTOP, GtkDesktopClass))
#define GTK_IS_DESKTOP(obj)		(G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_DESKTOP))
#define GTK_IS_DESKTOP_CLASS(klass)	(G_TYPE_CHECK_CLASS_TYPE ((klass), GTK_TYPE_DESKTOP))
#define GTK_DESKTOP_GET_CLASS(obj)    (G_TYPE_INSTANCE_GET_CLASS ((obj), GTK_TYPE_DESKTOP, GtkDesktopClass))

typedef struct _GtkDesktop GtkDesktop;
typedef struct _GtkDesktopClass GtkDesktopClass;
typedef struct _GtkDesktopPrivate GtkDesktopPrivate;

struct _GtkDesktop 
{
  GObject parent;

  GtkDesktopPrivate *priv;
};

struct _GtkDesktopClass 
{
  GObjectClass parent_class;
  
  /* VTable */
  gboolean     (* show_help)      (GtkDesktop  *desktop,
                                   GdkScreen   *screen,
                                   guint32      timestamp,
                                   const char  *help_system_name,
                                   char       **param_names,
                                   char       **param_values,
                                   GError     **error);

  gboolean     (* show_url)       (GtkDesktop  *desktop,
                                   const char  *url,
                                   GdkScreen   *screen,
                                   guint32      timestamp,
                                   GError     **error);

  
};

GType            _gtk_desktop_get_type        (void);
GtkDesktop*      _gtk_desktop_new             (GdkDisplay *display);

GtkDesktop* _gtk_desktop_get_for_display (GdkDisplay  *display);
GdkDisplay* _gtk_desktop_get_display     (GtkDesktop  *desktop);
gboolean    _gtk_desktop_show_help       (GtkDesktop  *desktop,
                                          GdkScreen   *screen,
                                          guint32      timestamp,
                                          const char  *help_system_name,
                                          char       **param_names,
                                          char       **param_values,
                                          GError     **error);
gboolean    _gtk_desktop_show_url        (GtkDesktop  *desktop,
                                          const char  *url,
                                          GdkScreen   *screen,
                                          guint32      timestamp,
                                          GError     **error);



G_END_DECLS

#endif /* __GTK_DESKTOP_H__ */
/*
 * Copyright (C) 2007 Red Hat, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 *
 * Author: Havoc Pennington <hp redhat com>
 */

#include <config.h>
#include "gtkdesktopx.h"
#include "gtkhelp.h"
#include "gtkurl.h"

struct _GtkDesktopXPrivate 
{
  int dummy;
};

G_DEFINE_TYPE (GtkDesktopX, _gtk_desktop_x, GTK_TYPE_DESKTOP);

static gboolean show_help (GtkDesktop  *desktop,
                           GdkScreen   *screen,
                           guint32      timestamp,
                           const char  *help_system_name,
                           char       **param_names,
                           char       **param_values,
                           GError     **error);
static gboolean show_url  (GtkDesktop  *desktop,
                           const char  *url,
                           GdkScreen   *screen,
                           guint32      timestamp,
                           GError     **error);
static void     finalize  (GObject     *object);


static void
_gtk_desktop_x_class_init (GtkDesktopXClass *class)
{
  GObjectClass *gobject_class;
  GtkDesktopClass *desktop_class;
  
  gobject_class = G_OBJECT_CLASS (class);
  gobject_class->finalize = finalize;
  
  desktop_class = GTK_DESKTOP_CLASS (class);
  desktop_class->show_help = show_help;
  desktop_class->show_url = show_url;
  
  g_type_class_add_private (gobject_class, sizeof (GtkDesktopXPrivate));
}

static void
_gtk_desktop_x_init (GtkDesktopX *engine)
{
  engine->priv = G_TYPE_INSTANCE_GET_PRIVATE (engine, GTK_TYPE_DESKTOP_X, GtkDesktopXPrivate);
}

GtkDesktop *
_gtk_desktop_x_new (GdkDisplay *display)
{
  GtkDesktopX *desktop_x;
	
  desktop_x = g_object_new (GTK_TYPE_DESKTOP_X,
                            "display", display,
                            NULL);
  
  
  return GTK_DESKTOP (desktop_x);
}


static void
finalize (GObject *object)
{
  GtkDesktopX *desktop_x;
  
  desktop_x = GTK_DESKTOP_X (object);
  
  G_OBJECT_CLASS (_gtk_desktop_x_parent_class)->finalize (object);
}

static gboolean
show_help (GtkDesktop  *desktop,
           GdkScreen   *screen,
           guint32      timestamp,
           const char  *help_system_name,
           char       **param_names,
           char       **param_values,
           GError     **error)
{
  g_set_error (error,
               GTK_HELP_ERROR,
               GTK_HELP_ERROR_UNKNOWN_HELP_SYSTEM,
               "No help systems have been implemented yet");

  return FALSE;
}

static gboolean
show_url (GtkDesktop  *desktop,
          const char  *url,
          GdkScreen   *screen,
          guint32      timestamp,
          GError     **error)
{
  g_set_error (error,
               GTK_URL_ERROR,
               GTK_URL_ERROR_NOT_SUPPORTED,
               "Url showing has not been implemented yet");

  return FALSE;
}
/*
 * Copyright (C) 2007 Red Hat, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 *
 * Author: Havoc Pennington <hp redhat com>
 */

#ifndef __GTK_DESKTOP_X_H__
#define __GTK_DESKTOP_X_H__

#include "gtkdesktop.h"

G_BEGIN_DECLS

#define GTK_TYPE_DESKTOP_X		(_gtk_desktop_x_get_type ())
#define GTK_DESKTOP_X(obj)		(G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_DESKTOP_X, GtkDesktopX))
#define GTK_DESKTOP_X_CLASS(klass)	(G_TYPE_CHECK_CLASS_CAST ((klass), GTK_TYPE_DESKTOP_X, GtkDesktopXClass))
#define GTK_IS_DESKTOP_X(obj)		(G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_DESKTOP_X))
#define GTK_IS_DESKTOP_X_CLASS(klass)	(G_TYPE_CHECK_CLASS_TYPE ((klass), GTK_TYPE_DESKTOP_X))
#define GTK_DESKTOP_X_GET_CLASS(obj)    (G_TYPE_INSTANCE_GET_CLASS ((obj), GTK_TYPE_DESKTOP_X, GtkDesktopXClass))

typedef struct _GtkDesktopX GtkDesktopX;
typedef struct _GtkDesktopXClass GtkDesktopXClass;
typedef struct _GtkDesktopXPrivate GtkDesktopXPrivate;

struct _GtkDesktopX 
{
  GtkDesktop parent;

  GtkDesktopXPrivate *priv;
};

struct _GtkDesktopXClass 
{
  GtkDesktopClass parent_class;
};

GType            _gtk_desktop_x_get_type (void);

GtkDesktop* _gtk_desktop_x_new      (GdkDisplay *display);

G_END_DECLS

#endif /* __GTK_DESKTOP_X_H__ */
/*
 * Copyright (C) 2007 Red Hat, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 *
 * Author: Havoc Pennington <hp redhat com>
 */

#include <config.h>
#include "gtkhelp.h"
#include "gtkdesktop.h"
#include <string.h>

/**
 * Returns the error domain quark used with #GError and
 * gtk_help_show()
 * 
 * @returns: the error domain quark for help errors
 */
GQuark
gtk_help_error_quark (void)
{
  static GQuark quark = 0;
  if (quark == 0)
    quark = g_quark_from_static_string ("gtk-help-error-quark");
  return quark;
}

/**
 * gtk_help_show:
 * @screen: the screen to display help on, or %NULL for default screen
 * @timestamp: timestamp of the event triggering the help display
 * @help_system_name: name of the help system to use
 * @error: return location for an error, if one occurs
 * @first_param_name: the name of the first parameter to pass to help system
 * @first_param_value: value of the first parameter
 * @second_param_name: %NULL if only one parameter, or the name of another parameter
 * @var_args: value of the second parameter, then more name-value pairs, then %NULL
 * @returns: %FALSE if error is set, %TRUE otherwise 
 * 
 * Displays a help document. The details depend on the help system; a
 * help system defines what help files you install where, and in what
 * format. Depending on the help system, you may have to provide different
 * parameters to allow the help system to locate the part of the help you have
 * in mind.
 *
 * Unknown parameters are ignored; this allows new, optional parameters to
 * be introduced, but can make debugging annoying if you spell a parameter
 * incorrectly.
 * 
 * The simplest help system, which is always available, is called
 * "browser" and the possible parameters are "url" and "filename" - it
 * opens that url or filename in a browser.
 * 
 * On the GNOME platform, you can also use the "gnome" help system. Its
 * parameters are: FIXME
 * 
 */
gboolean
gtk_help_show (GdkScreen   *screen,
               guint32      timestamp,
               const char  *help_system_name,
               GError     **error,
               const char  *first_param_name,
               const char  *first_param_value,
               const char  *second_param_name,
               ...)
{
  va_list args;
  gboolean result;
  
  va_start (args, second_param_name);
  
  result = gtk_help_show_valist (screen, timestamp, help_system_name,
                                 error,
                                 first_param_name, first_param_value, second_param_name,
                                 args);

  va_end (args);

  return result;
}

/**
 * gtk_help_show_valist:
 * @screen: the screen to display help on, or %NULL for default screen
 * @timestamp: timestamp of the event triggering the help display
 * @help_system_name: name of the help system to use
 * @error: return location for an error, if one occurs
 * @first_param_name: the name of the first parameter to pass to help system
 * @first_param_value: value of the first parameter
 * @second_param_name: %NULL if only one parameter, or the name of another parameter
 * @var_args: value of the second parameter, then more name-value pairs, then %NULL
 * @returns: %FALSE if error is set, %TRUE otherwise 
 * 
 * Identical to gtk_help_show(), but the parameters are provided as a va_list rather than varargs.
 * This function is probably most useful for language bindings, not for C applications.
 * 
 */
gboolean
gtk_help_show_valist (GdkScreen   *screen,
                      guint32      timestamp,
                      const char  *help_system_name,
                      GError     **error,
                      const char  *first_param_name,
                      const char  *first_param_value,
                      const char  *second_param_name,
                      va_list      var_args)
{
#define MAX_PARAMS 10
  char *names[MAX_PARAMS+1];
  char *values[MAX_PARAMS+1];
  int i;

  g_return_val_if_fail (first_param_name != NULL, FALSE);
  g_return_val_if_fail (first_param_value != NULL, FALSE);
  
  i = 0;
  names[i] = (char*) first_param_name;
  values[i] = (char*) first_param_value;
  ++i;
  
  if (second_param_name != NULL)
    {
      names[i] = (char*) second_param_name;
      values[i] = va_arg (var_args, char*);
      ++i;

      for (; i < MAX_PARAMS; ++i)
        {
          names[i] = va_arg (var_args, char*);
          values[i] = va_arg (var_args, char*);

          if (names[i] == NULL)
            break;

          /* note that a value is allowed to be NULL */
          
          ++i;
        }
    }

  names[i] = NULL;
  values[i] = NULL;
  
  return gtk_help_show_array (screen, timestamp, help_system_name,
                              names, values,
                              error);
}

static gboolean
show_help_in_browser (GtkDesktop  *desktop,
                      GdkScreen   *screen,
                      guint32      timestamp,
                      char       **param_names,
                      char       **param_values,
                      GError     **error)
{
  const char *url;
  const char *filename;
  
  url = NULL;
  filename = NULL;  
  if (strcmp (param_names[0], "url") == 0)
    url = param_values[0];
  else if (strcmp (param_names[0], "filename") == 0)
    filename = param_values[0];

  if (filename)
    {
      /* FIXME add an url encoder to GLib and use it here */
      char *file_url;
      gboolean result;
      
      file_url = g_strdup_printf ("file://%s", filename);
      result = _gtk_desktop_show_url (desktop, file_url, screen, timestamp, error);
      g_free (file_url);
      return result;
    }
  else
    {
      return _gtk_desktop_show_url (desktop, url, screen, timestamp, error);
    }
}

/**
 * gtk_help_show_array:
 * @screen: the screen to display help on, or %NULL for default screen
 * @timestamp: timestamp of the event triggering the help display
 * @help_system_name: name of the help system to use
 * @param_names: %NULL-terminated array of parameter names
 * @param_values: array of parameter values, corresponding to the names; values may be %NULL so array's length comes from names array length
 * @error: return location for an error, if one occurs
 * @returns: %FALSE if error is set, %TRUE otherwise
 *
 * Identical to gtk_help_show(), but the parameters are provided as an array rather than varargs.
 * This function is probably most useful for language bindings, not for C applications.
 */
gboolean
gtk_help_show_array (GdkScreen   *screen,
                     guint32      timestamp,
                     const char  *help_system_name,
                     char       **param_names,
                     char       **param_values,
                     GError     **error)
{
  GtkDesktop *desktop;

  g_return_val_if_fail (help_system_name != NULL, FALSE);

  desktop = _gtk_desktop_get_for_display (screen != NULL ? gdk_screen_get_display (screen) : gdk_display_get_default ());
  
  if (strcmp (help_system_name, "browser") == 0)
    {
      return show_help_in_browser (desktop, screen, timestamp,
                                   param_names, param_values,
                                   error);
    }
  else
    {
      return _gtk_desktop_show_help (desktop, screen, timestamp,
                                     help_system_name, param_names, param_values,
                                     error);
    }
}

/*
 * Copyright (C) 2007 Red Hat, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 *
 * Author: Havoc Pennington <hp redhat com>
 */

#ifndef __GTK_HELP_H__
#define __GTK_HELP_H__

#include <gdk/gdk.h>
#include <stdarg.h>

G_BEGIN_DECLS

typedef enum {
  GTK_HELP_ERROR_FAILED,
  GTK_HELP_ERROR_UNKNOWN_HELP_SYSTEM,
  GTK_HELP_ERROR_NOT_FOUND
} GnomeHelpError;

#define GTK_HELP_ERROR (gtk_help_error_quark ())
GQuark gtk_help_error_quark (void) G_GNUC_CONST;

gboolean gtk_help_show        (GdkScreen   *screen,
                               guint32      timestamp,
                               const char  *help_system_name,
                               GError     **error,
                               const char  *first_param_name,
                               const char  *first_param_value,
                               const char  *second_param_name,
                               ...);
gboolean gtk_help_show_valist (GdkScreen   *screen,
                               guint32      timestamp,
                               const char  *help_system_name,
                               GError     **error,
                               const char  *first_param_name,
                               const char  *first_param_value,
                               const char  *second_param_name,
                               va_list      var_args);
gboolean gtk_help_show_array  (GdkScreen   *screen,
                               guint32      timestamp,
                               const char  *help_system_name,
                               char       **param_names,
                               char       **param_values,
                               GError     **error);


G_END_DECLS

#endif /* __GTK_HELP_H__ */
/*
 * Copyright (C) 2007 Red Hat, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 *
 * Author: Havoc Pennington <hp redhat com>
 */

#include <config.h>
#include "gtkurl.h"
#include "gtkdesktop.h"

/**
 * Returns the error domain quark used with #GError and
 * gtk_url_show()
 * 
 * @returns: the error domain quark for url errors
 */
GQuark
gtk_url_error_quark (void)
{
  static GQuark quark = 0;
  if (quark == 0)
    quark = g_quark_from_static_string ("gtk-url-error-quark");
  return quark;
}

/**
 * gtk_url_show:
 * @url: the URL to display in a browser
 * @screen: the screen to display url on, or %NULL for default screen
 * @timestamp: timestamp of the event triggering the url display
 * @error: return location for an error, if one occurs
 * @returns: %FALSE if error is set, %TRUE otherwise 
 * 
 * Displays a url in a browser. Attempts to use the user's preferred
 * browser.
 */
gboolean
gtk_url_show (const char  *url,
              GdkScreen   *screen,
              guint32      timestamp,
              GError     **error)
{
  GtkDesktop *desktop;

  desktop = _gtk_desktop_get_for_display (screen != NULL ? gdk_screen_get_display (screen) : gdk_display_get_default ());

  return _gtk_desktop_show_url (desktop, url, screen, timestamp,
                                error);
}
/*
 * Copyright (C) 2007 Red Hat, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 *
 * Author: Havoc Pennington <hp redhat com>
 */

#ifndef __GTK_URL_H__
#define __GTK_URL_H__

#include <gdk/gdk.h>
#include <stdarg.h>

G_BEGIN_DECLS

typedef enum {
  GTK_URL_ERROR_FAILED,
  GTK_URL_ERROR_NOT_FOUND,
  GTK_URL_ERROR_PARSE,
  GTK_URL_ERROR_LAUNCH,
  GTK_URL_ERROR_NOT_SUPPORTED,
  GTK_URL_ERROR_CANCELLED  /* FIXME GTK is schizo on how many "L" are in this, it varies in other places */
} GtkUrlError;

#define GTK_URL_ERROR (gtk_url_error_quark ())
GQuark gtk_url_error_quark (void) G_GNUC_CONST;

gboolean gtk_url_show        (const char  *url,
                              GdkScreen   *screen,
                              guint32      timestamp,
                              GError     **error);


G_END_DECLS

#endif /* __GTK_URL_H__ */
_______________________________________________
gtk-devel-list mailing list
gtk-devel-list gnome org
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

--- End Message ---


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]