You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Skip to main content

You are here: Unix project page > GtkMozEmbed: Embedding Mozilla into Gtk Applications

GtkMozEmbed: Gtk Mozilla Embedding Widget

Introduction

GtkMozEmbed is an easy-to-use widget that will allow you to embed a Mozilla browser window into your Gtk application.

It's designed to be easy to use and uncomplicated to make the barrier for use as low as possible. This means that the functionality exposed should cover about 80% of uses. If you want to get at some of Mozilla's higher brain functions it means that you will have to write your own embedding widget.

In a future revision ( post M16 ) I will make it possible to get at the underlying nsIWebBrowser implementation from the embedding widget. This will give people that need to be able to get to Mozilla's internal interfaces a way to do so.

Additionally, using the Gtk Mozilla embedding widget means that you don't have any C++ dependencies in your code that does the embedding. This is important to some C luddites.

Please send any questions/comments or corrections to Christopher Blizzard <blizzard@mozilla.org>

Function Reference

gtkmozembed.h 

extern GtkType      gtk_moz_embed_get_type         (void);
extern GtkWidget   *gtk_moz_embed_new              (void);
extern void         gtk_moz_embed_set_comp_path    (char *aPath);
extern void         gtk_moz_embed_load_url         (GtkMozEmbed *embed, const char *url);
extern void         gtk_moz_embed_stop_load        (GtkMozEmbed *embed);
extern gboolean     gtk_moz_embed_can_go_back      (GtkMozEmbed *embed);
extern gboolean     gtk_moz_embed_can_go_forward   (GtkMozEmbed *embed);
extern void         gtk_moz_embed_go_back          (GtkMozEmbed *embed);
extern void         gtk_moz_embed_go_forward       (GtkMozEmbed *embed);
extern void         gtk_moz_embed_render_data      (GtkMozEmbed *embed, 
						    const char *data, guint32 len,
						    const char *base_uri, const char *mime_type);
extern void         gtk_moz_embed_open_stream      (GtkMozEmbed *embed,
						    const char *base_uri, const char *mime_type);
extern void         gtk_moz_embed_append_data      (GtkMozEmbed *embed,
						    const char *data, guint32 len);
extern void         gtk_moz_embed_close_stream     (GtkMozEmbed *embed);
extern char        *gtk_moz_embed_get_link_message (GtkMozEmbed *embed);
extern char        *gtk_moz_embed_get_js_status    (GtkMozEmbed *embed);
extern char        *gtk_moz_embed_get_title        (GtkMozEmbed *embed);
extern char        *gtk_moz_embed_get_location     (GtkMozEmbed *embed);
extern void         gtk_moz_embed_reload           (GtkMozEmbed *embed, gint32 flags);
extern void         gtk_moz_embed_set_chrome_mask  (GtkMozEmbed *embed, guint32 flags);
extern guint32      gtk_moz_embed_get_chrome_mask  (GtkMozEmbed *embed);

gtkmozembed_internal.h 

extern void gtk_moz_embed_get_nsIWebBrowser  (GtkMozEmbed *embed, nsIWebBrowser **retval);

gtk_moz_embed_new

Arguments: void
Returns: GtkWidget *
This function returns a new Gtk Mozilla embedding widget. On failure it will return NULL.

gtk_moz_embed_set_comp_path

Arguments: const char *aPath
Returns: void
This function must be called before the first widget is created or XPCOM is initialized. It allows you to set the path to the mozilla components.

gtk_moz_embed_load_url

Arguments: GtkMozEmbed *embed
const char *url
Returns: void
This function starts loading a url in the embedding widget. All loads are asynchronous. The url argument should be in the form of http://www.gnome.org.

gtk_moz_embed_stop_load

Arguments: GtkMozEmbed *embed
Returns: void
This function will allow you to stop the load of a document that is being loaded in the widget.

gtk_moz_embed_can_go_back

Arguments: GtkMozEmbed *embed
Returns: gboolean
This function will return whether or not you can go backwards in the document's navigation history. It will return TRUE if it can go backwards, FALSE if it can't.

gtk_moz_embed_can_go_forward

Arguments: GtkMozEmbed *embed
Returns: gboolean
This function will return whether or not you can go forwards in the document's navigation history. It will return TRUE if it can go forwards, FALSE if it can't.

gtk_moz_embed_go_back

Arguments: GtkMozEmbed *embed
Returns: void
This function will go backwards one step in the document's navigation history.

gtk_moz_embed_go_forward

Arguments: GtkMozEmbed *embed
Returns: void
This function will go forward one step in the document's navigation history.

gtk_moz_embed_render_data

Arguments: GtkMozEmbed *embed
const char *data
guint32 len
const char *base_uri
const char *mime_type
Returns: void
This function will allow you to take a chunk of random data and render it into the document. You need to pass in the data and the length of the data. The base_uri is used to resolve internal references in the document and the mime_type is used to determine how to render the document internally.

gtk_moz_embed_open_stream

Arguments: GtkMozEmbed *embed
const char *base_uri
const char *mime_type
Returns: void
This function is used to start loading a document from an external source into the embedding widget. You need to pass in the base_uri for resolving internal links and and the mime_type of the document.

gtk_moz_embed_append_data

Arguments: GtkMozEmbed *embed
const char *data
guint32 len
Returns: void
This function allows you to append data to an already opened stream in the widget. You need to pass in the data that you want to append to the document and its length.

gtk_moz_embed_close_stream

Arguments: GtkMozEmbed *embed
Returns: void
This function closes the stream that you have been using to append data manually to the embedding widget.

gtk_moz_embed_get_link_message

Arguments: GtkMozEmbed *embed
Returns: char *
This function returns the current link message of the document if there is one. The string returned is new and it's the caller's responsibility to free the string.

gtk_moz_embed_get_js_status

Arguments: GtkMozEmbed *embed
Returns: char *
This function returns the js_status message if there is one. The string returned is new and it is the caller's responsibility to free the string.

gtk_moz_embed_get_title

Arguments: GtkMozEmbed *embed
Returns: char *
This function will get the current title for a document. The string returned is new and it is the caller's responsibility to free the string.

gtk_moz_embed_get_location

Arguments: GtkMozEmbed *embed
Returns: char *
This function will return the current location of the document. This string is new and it is the caller's responsibility to free the string.

gtk_moz_embed_reload

Arguments: GtkMozEmbed *embed
gint32 flags
Returns: void
This function reloads the document. The flags argument can be used to control the behaviour of the reload. The flags argument can be one of the following values: 
       GTK_MOZ_EMBED_FLAG_RELOADNORMAL
       GTK_MOZ_EMBED_FLAG_RELOADBYPASSCACHE
       GTK_MOZ_EMBED_FLAG_RELOADBYPASSPROXY
       GTK_MOZ_EMBED_FLAG_RELOADBYPASSPROXYANDCACHE

gtk_moz_embed_set_chrome_mask

Arguments: GtkMozEmbed *embed guint32 flags
Returns: void
This function is used to set the chome mask for this window. It can be the logical or of any of the following values: 
       GTK_MOZ_EMBED_FLAG_DEFAULTCHROME
       GTK_MOZ_EMBED_FLAG_WINDOWBORDERSON
       GTK_MOZ_EMBED_FLAG_WINDOWCLOSEON
       GTK_MOZ_EMBED_FLAG_WINDOWRESIZEON
       GTK_MOZ_EMBED_FLAG_MENUBARON
       GTK_MOZ_EMBED_FLAG_TOOLBARON
       GTK_MOZ_EMBED_FLAG_LOCATIONBARON
       GTK_MOZ_EMBED_FLAG_STATUSBARON
       GTK_MOZ_EMBED_FLAG_PERSONALTOOLBARON
       GTK_MOZ_EMBED_FLAG_SCROLLBARSON
       GTK_MOZ_EMBED_FLAG_TITLEBARON
       GTK_MOZ_EMBED_FLAG_EXTRACHROMEON
       GTK_MOZ_EMBED_FLAG_WINDOWRAISED
       GTK_MOZ_EMBED_FLAG_WINDOWLOWERED
       GTK_MOZ_EMBED_FLAG_CENTERSCREEN
       GTK_MOZ_EMBED_FLAG_DEPENDENT
       GTK_MOZ_EMBED_FLAG_MODAL
       GTK_MOZ_EMBED_FLAG_OPENASDIALOG
       GTK_MOZ_EMBED_FLAG_OPENASCHROME
       GTK_MOZ_EMBED_FLAG_ALLCHROME

gtk_moz_embed_get_chrome_mask

Arguments: GtkMozEmbed *embed
Returns: guint32
This function gets the current chome mask for this window. Please see the documentation for gtk_moz_embed_set_chrome_mask for the value of the return mask.

gtk_moz_embed_get_nsIWebBrowser

Arguments: GtkMozEmbed *embed
nsIWebBrowser **retval
Returns: void
This function allows you to get the underlying nsIWebBrowser for the widget. As all good XPCOM functions do, this function will addref the nsIWebBrowser on return.

Signal Reference

link_message

Function Prototype void link_message_cb (GtkMozEmbed *embed, gpointer data);
This signal is emitted when the link message changes. This happens when the user moves the mouse over a link in a web page. Please use gtk_moz_embed_get_link_message to get the actual value of the link message.

js_status

Function Prototype void js_status_cb (GtkMozEmbed *embed, gpointer data);
This signal is emitted when the JavaScript status message changes. Please use gtk_moz_embed_get_js_status to get the actual value of the js status message.

location

Function Prototype void location_changed_cb (GtkMozEmbed *embed, gpointer data);
This signal is emitted any time that the location of the document has changed. Please use gtk_moz_embed_get_location to get the actual value of the location.

title

Function Prototype void title_changed_cb (GtkMozEmbed *embed, gpointer data);
This signal is emitted any time that the title of a document has changed. Please use the gtk_moz_embed_get_title call to get the actual value of the title.

progress

Function Prototype void progress_change_cb (GtkMozEmbed *embed, gint cur, gint max, gpointer data);
This signal is emitted any time that there is a change in the progress of loading a document.

The cur value indicates how much of the document has been downloaded.

The max value indicates the length of the document. If the value of max is less than one the full length of the document can not be determined.

net_status [ Depreciated - use net_state ]

Function Prototype void net_status_change_cb (GtkMozEmbed *embed, gint flags, gpointer data);
This signal is emitted when there's a change in the status of network loading. [ fill this in with info about the flags. ]

net_state

Function Prototype void net_state_change_cb (GtkMozEmbed *embed, gint flags, guint status, gpointer data);
This signal is emitted when there's a change in the state of the loading of a document. [ fill this in with info about the flags. ]

net_start

Function Prototype void load_started_cb (GtkMozEmbed *embed, gpointer data);
This signal is emitted any time that the load of a document has been started.

net_stop

Function Prototype void load_finished_cb (GtkMozEmbed *embed, gpointer data);
This signal is emitted any time that the loading of a document has completed.

new_window

Function Prototype void new_window_cb (GtkMozEmbed *embed, GtkMozEmbed **retval, guint chromemask, gpointer data);
This signal is emitted any time that a new toplevel window is requested by the document. This will happen in the case of a window.open() in JavaScript. Responding to this signal allows you to surround a new toplevel window with your chrome.

You should return the newly created GtkMozEmbed object via the retval.

visibility

Function Prototype void visibility_cb (GtkMozEmbed *embed, gboolean visibility, gpointer data);
This signal is emitted when the toplevel window in question needs to be shown or hidden. If the visibility argument is TRUE then the window should be shown. If it's FALSE it should be hidden.

destroy_browser

Function Prototype void destroy_brsr_cb (GtkMozEmbed *embed, gpointer data);
This signal is emitted when the document as requested that the toplevel window be closed. This will happen in the case of a JavaScript window.close().

open_uri

Function Prototype gint open_uri_cb (GtkMozEmbed *embed, const char *uri, gpointer data);
This signal is emitted when the document tries to load a new document, for example when someone clicks on a link in a web page. This signal gives the embedder the opportunity to keep the new document from being loaded. The uri argument is the uri that's going to be loaded.

If you return TRUE from this signal, the new document will NOT be loaded. If you return FALSE the new document will be loaded. This is somewhat non-intuitive. Think of it as the Mozilla engine is asking if you want to interrupt the loading of a new document. By returning TRUE you are saying "don't load this document."

FAQ

How do I use the Gtk native scrollbars instead of the cheezy Mozilla one?

The simple answer is you can't. Mozilla uses its own native scrollbars for reasons that have been well hashed out in other forums. There might be other answers for creating the look and feel of the gtk scrollbars coming down the road. Stay tuned.

How do I catch the output of a form that I've created?

You can't do this yet. [ put bug # in here. ]

Is there a way for me to catch the load of images and other resources in a document?

This question is asked because you might be rendering some content where the images or other multimedia resources in a document might be taken from some other resource that Mozilla doesn't know how to get. The theory is that you want to be able to do this without writing an entire protocol handler and be able to get the data into the document handler for that media type via the embedding interface or some kind of callback.

Mozilla's architecture doesn't allow for this yet but there are bugs to be able to add this functionality. [ insert bug #s here. ]

Revision Information

M17

The net_status flag has been replaced with the net_state signal with new flags. This is because of underlying changes in the progress listener in mozilla.

A new function gtk_moz_embed_set_comp_path has been added.

Added the gtkmozembed_internal.h header. This will allow you to get some mozilla specific data. It's seperated from gtkmozembed.h since it's nice to allow people to use the widget without all of the mozilla headers installed.

A new function gtk_moz_embed_get_nsIWebBrowser has been added.

M16

With M16 comes the first version of the embedding widget that can be used by non-heroic programmers.

Since the last release the following functions have been added:

  • Plays nice with gtk's focus system.
  • Can interrupt url loading.
  • Can go forward and back through a navigation set.
  • Can render arbitrary data given a mime type and area of memory.
  • Can stream data into the widget without having to have all of document in one place ( incremental loading. )

The following signals have been added:

  • link_message: Change in link message.
  • js_status: Change in the JS status.
  • location: The location of the document has changed.
  • title: The title for the loaded document has changed.
  • progress: Progress has been made loading data
  • net_status: There has been a change in the network status while loading data.
  • net_start: A document has started loading.
  • net_stop: A document has finished loading.
  • new_window: The document has requested creating a new toplevel window.
  • visibility: The document has requested hiding or showing a toplevel window.
  • destroy_browser: The document has requested that a toplevel window be destroyed.
  • open_uri: The document has requested that a new document be loaded.

Known problems:

  • Assertion:
    ###!!! ASSERTION: GetShellWidget() fails: 'mIMEShellWidget', file ../../../../mozilla/widget/src/gtk/nsWidget.cpp, line 3273
    This is an assertion from the IM code in the widget code. It's caused by the assumption that the toplevel Mozilla window is always a toplevel window which it isn't in the embedding case. It's harmless but annoying. Should be fixed in the next release [insert bug #here]
  • Before first document is loaded, area doesn't repaint with a solid color. [ insert bug #here ]

M15

First release of the embedding widget. Can't do much except load a url. It also doesn't play nice in Gtk's focus model and is pretty easy to crash.

Blizzard