Roll your own browser: An embedding how-to

  • Revision slug: Roll_your_own_browser_-_An_embedding_HowTo
  • Revision title: Roll your own browser - An embedding HowTo
  • Revision id: 79082
  • Created:
  • Creator: Nickolay
  • Is current revision? No
  • Comment wrap the warning in a div

Revision Content

Note: this document is out of date. According to Benjamin Smedberg: "build XULRunner and use that for all new embedding. You do not need/should not use embedding/config".

What bits do I need?

One of the requirements of building a SDK is the ability to identify and package up required files. Like that isn't totally obvious, nonetheless it has to be done. Here is that effort.

I have created a directory under embedding called config. Contained within this directory are a couple of makefiles:

The XPInstall packager follows the same format. However in our case, we only have one named XPI package.

After the build is done, you can change directory into mozilla/embedding/config, and do a <tt>make</tt>. This will produce a directory in DIST named Embed. It should include all of the base support that you need to get a web browser started up.

Included is the sample test application (gtkEmbed or winEmbed).

What initializations do I have to do?

Somewhere during the start of your application, you must initialize {{ mediawiki.external('XPCOM') }}. You will also want to shut this down when you quit.

Other initialization must be done to start up event queues and load some string bundles. All of this is somewhat generic and has been isolated into a static library that you can simply call on.

If you build <tt>mozilla/embedding/base/</tt>, a static library (on windows) called <tt>baseembed_s.lib</tt> is built. Just link this library to your application. There are two functions that are needed:

nsresult NS_InitEmbedding(const char *aPath);
nsresult NS_TermEmbedding();

Pretty self-explanatory. The aPath parameter will be passed to NS_InitXPCOM. NS_InitEmbedding() must be called from the main thread of your application, otherwise it won't work.

Do you have any simple examples of embedding Mozilla?

There are many examples of products already using Gecko for embedding. Here's a partial list. The sections marked 'Mozilla Examples' refer to clients and sample code to be found within the Mozilla source tree.

Linux

External projects

  • Epiphany: Part of the GNOME project. A fork of Galeon, it strives to be a more usable browser for non-technical users. (Screenshots)
  • Skipstone browser: A lightweight browser based on the GtkMozEmbed widget. HTML area + the basic navigation windows. (Screenshot)
    • Tabbed browsing as well as regular windowed browsingProggramable via plugins. Examples are included in the source
    • Bookmarks and bookmark toolbarPref dialog with lots of internal / Mozilla options to configure
    • Themable and completely configurable toolbarSSL and Java support
    • Native Prompt Dialogs support / Mozilla Helper dialogs support
  • SashXB: IBM uses Mozilla to implement part of their Sash development/desktop environment. Part of the GNOME effort.
  • Light: Very simple non-bloated GTK+ interface, familiar Netscape 4.x keyboard shortcuts, context menus, etc. (Screenshot)

Mozilla Examples

  • TestGtkEmbed: Basic browser built with the GtkMozEmbed widget. URL location field, menu bar, html area, supports SSL.

Windows

External projects

  • K-Meleon browser: the Windows answer to Galeon. Fast IE-look-alike browser, uses IE and NS bookmarking system, fast loading time, privacy features, Java support and complete control of the menus and "hotkeys". Implemented with Mozilla embedding APIs. (Screenshots)
  • NXZILLA: A set of libraries that allow Mozilla to be used with a NanoX server.
  • ActiveX control: An ActiveX control allowing for embedding the Gecko layout engine.
  • LLMozLib & uBrowser: a static library that allows you to embed Gecko and render pages to memory. Includes test applications that illustrate how to use it. Versions for Windows and Mac with Linux to follow.

Mozilla Examples

  • mfcEmbed: Standard Mozilla embedding example application for win32. Basic browser, menus, toolbar, URLbar, html area.
  • winEmbed: Obsoleted by mfcEmbed. A bare-bones browser with URLbar and html area.
  • ActiveX control: An ActiveX control for Mozilla using the Gecko layout engine. More information at 1 and 2.

Mac

External projects

  • AOL for Mac OS X: AOL chose Gecko to power web support in the OS X version of their client software.

Mozilla Examples

  • PPEmbed: Standard Mozilla sample application implemented with Metroworks' Powerplant.
  • Camino: A project aimed at delivering a best-of-breed browser on the Mac OS X platform. Camino uses Cocoazilla, a variant of Fizzilla that consists of a UNIX back end wed to a Cocoa front end.

Java

Examples

  • Java Webclient: Provides a browser-neutral Java API that enables generic web browsing capability.
  • BrowserG!: A Java application that uses Webclient for HTML rendering and surfing capabilities.


If you find any missing item, please send me an email.

Revision Source

<p>
</p>
<div class="warning">
<p><b>Note: this document is out of date. According to Benjamin Smedberg: "build <a href="en/XULRunner">XULRunner</a> and use that for all new embedding. You do not need/should not use embedding/config".</b>
</p>
</div>
<h2 name="What_bits_do_I_need.3F"> What bits do I need? </h2>
<p>One of the requirements of building a SDK is the ability
to identify and package up required files. Like that isn't
totally obvious, nonetheless it has to be done. Here is
that effort.
</p><p>I have created a directory under embedding called
<a class="external" href="http://lxr.mozilla.org/seamonkey/source/embedding/config/">config</a>.
Contained within this directory are a couple of makefiles:
</p>
<ul><li> <a class="external" href="http://lxr.mozilla.org/seamonkey/source/embedding/config/basebrowser-unix">basebrowser-unix</a>
</li><li> <a class="external" href="http://lxr.mozilla.org/seamonkey/source/embedding/config/basebrowser-win">basebrowser-win</a>
</li></ul>
<p>The <a href="en/XPInstall">XPInstall</a> <a class="external" href="http://lxr.mozilla.org/seamonkey/source/xpinstall/packager/">packager</a> follows the same format. However in our case, we only have
one named <a href="en/XPI">XPI</a> package.
</p><p>After the build is done, you can change directory into <code>mozilla/embedding/config</code>, and do a <tt>make</tt>. This will produce a directory in <code>DIST</code> named <code>Embed</code>. It should include all of the base support that you need to get a web browser started up.
</p><p>Included is the sample test application (<code>gtkEmbed</code> or <code>winEmbed</code>).
</p>
<h2 name="What_initializations_do_I_have_to_do.3F"> What initializations do I have to do? </h2>
<p>Somewhere during the start of your application, you must initialize {{ mediawiki.external('XPCOM') }}. You will also want to shut this down when you quit. </p><p>Other initialization must be done to start up event queues and load some string bundles. All of this is somewhat generic and has been isolated into a static library that you can simply call on.
</p><p>If you build <tt>mozilla/embedding/base/</tt>, a static library (on windows) called <tt>baseembed_s.lib</tt> is built. Just link this library to your application. There are two functions that are needed:
</p>
<pre class="eval">nsresult NS_InitEmbedding(const char *aPath);
nsresult NS_TermEmbedding();
</pre>
<p>Pretty self-explanatory. The <code>aPath</code> parameter will be passed to <a class="external" href="http://lxr.mozilla.org/seamonkey/source/xpcom/build/nsXPComInit.cpp#192">NS_InitXPCOM</a>. NS_InitEmbedding() must be called from the main thread of your application, otherwise it won't work.
</p>
<h2 name="Do_you_have_any_simple_examples_of_embedding_Mozilla.3F"> Do you have any simple examples of embedding Mozilla? </h2>
<p>There are many examples of products already using Gecko for embedding.
Here's a partial list. The sections marked 'Mozilla Examples' refer to clients and sample
code to be found within the Mozilla source tree.
</p>
<h3 name="Linux"> Linux </h3>
<h4 name="External_projects"> External projects </h4>
<ul><li> <a class="external" href="http://galeon.sourceforge.net/">Galeon browser</a>: Part of the <a class="external" href="http://www.gnome.org">GNOME</a> effort. Based on the <a class="external" href="http://www.mozilla.org/unix/gtk-embedding.html">GtkMozEmbed widget</a>, this fairly mature browser sports a full set of features including menus, personal toolbar, bookmark manager, cookie manager, prefs, and good dialog support. Java, SSL, plugins and helper apps work well. (<a class="external" href="http://www.mozilla.org/projects/embedding/examples/galeon.jpg">Screenshot</a>, <a class="external" href="http://www.mozilla.org/projects/embedding/examples/galeon.html">Mozilla/Galeon FAQ</a>)
</li></ul>
<ul><li> <a class="external" href="http://www.gnome.org/projects/epiphany/">Epiphany</a>: Part of the <a class="external" href="http://www.gnome.org">GNOME</a> project. A fork of Galeon, it strives to be a more usable browser for non-technical users. (<a class="external" href="http://www.gnome.org/projects/epiphany/screenshots/">Screenshots</a>)
</li></ul>
<ul><li> <a class="external" href="http://www.muhri.net/skipstone">Skipstone browser</a>: A lightweight browser based on the GtkMozEmbed widget. HTML area + the basic navigation windows. (<a class="external" href="http://www.mozilla.org/projects/embedding/examples/skipstone.jpg">Screenshot</a>)
<ul><li> Tabbed browsing as well as regular windowed browsingProggramable via plugins. Examples are included in the source
</li><li> Bookmarks and bookmark toolbarPref dialog with lots of internal / Mozilla options to configure
</li><li> Themable and completely configurable toolbarSSL and Java support
</li><li> Native Prompt Dialogs support / Mozilla Helper dialogs support
</li></ul>
</li></ul>
<ul><li> <a class="external" href="http://www-128.ibm.com/developerworks/linux/library/l-sashxb/">SashXB</a>: IBM uses Mozilla to implement part of their <a class="external" href="http://publib-b.boulder.ibm.com/Redbooks.nsf/RedbookAbstracts/sg246403.html?Open">Sash</a> development/desktop environment. Part of the <a class="external" href="http://www.gnome.org">GNOME</a> effort.
</li></ul>
<ul><li> <a class="external" href="http://www.activestate.com/Products/Komodo/index.html">ActiveState's Komodo</a>: Development environment, based on Mozilla's <a href="en/XUL">XUL</a>. (<a class="external" href="http://www.activestate.com/_images/screenshots/ss_Komodo_rails_large.gif">Screenshot</a>)
</li></ul>
<ul><li> <a class="external" href="http://www.ne.jp/asahi/linux/timecop/#light">Light</a>: Very simple non-bloated GTK+ interface, familiar Netscape 4.x keyboard shortcuts, context menus, etc. (<a class="external" href="http://www.ne.jp/asahi/linux/timecop/images/browser.png">Screenshot</a>)
</li></ul>
<ul><li> <a class="external" href="http://websvn.kde.org/*checkout*/trunk/KDE/kdebindings/xparts/doc/xparts.html">XParts</a>: KDE extension that allows Mozilla to be embedded into the Konqueror browser. Uses GtkMozEmbed widget, part of the kdebindings module and available from <a class=" external" href="http://websvn.kde.org/trunk/KDE/kdebindings/xparts/" rel="freelink">http://websvn.kde.org/trunk/KDE/kdebindings/xparts/</a>. (<a class="external" href="http://dot.kde.org/977406679/">News release</a>, <a class="external" href="http://trolls.troll.no/%7Elars/xparts">screenshot</a>)
</li></ul>
<h4 name="Mozilla_Examples"> Mozilla Examples </h4>
<ul><li> <a class="external" href="http://www.mozilla.org/unix/gtk-embedding.html">GtkMozEmbed widget</a>: Gtk widget wrapper for the Mozilla Gecko Engine.
</li></ul>
<ul><li> <a class="external" href="http://lxr.mozilla.org/seamonkey/source/embedding/browser/gtk/tests/TestGtkEmbed.cpp">TestGtkEmbed</a>: Basic browser built with the GtkMozEmbed widget. URL location field, menu bar, html area, supports SSL.
</li></ul>
<h3 name="Windows"> Windows </h3>
<h4 name="External_projects_2"> External projects </h4>
<ul><li> <a class="external" href="http://kmeleon.sourceforge.net/">K-Meleon browser</a>: the Windows answer to Galeon. Fast IE-look-alike browser, uses IE and NS bookmarking system, fast loading time, privacy features, Java support and complete control of the menus and "hotkeys". Implemented with Mozilla embedding APIs. (<a class="external" href="http://kmeleon.sourceforge.net/shots.php">Screenshots</a>)
</li></ul>
<ul><li> <a class="external" href="http://www.neoplanet.com/">Neoplanet browser</a>: A Gecko add-on for the NeoPlanet browser.
</li></ul>
<ul><li> <a class="external" href="http://www.activestate.com/Products/Komodo/index.html">ActiveState's Komodo</a>: Development environment, based on Mozilla's <a href="en/XUL">XUL</a>. (<a class="external" href="http://www.activestate.com/_images/screenshots/ss_Komodo_rails_large.gif">Screenshot</a>)
</li></ul>
<ul><li> <a class="external" href="http://www.macromedia.com/software/homesite/">Macromedia HomeSite HTML Editor</a>: Internal browser for the Homesite Studio application is implemented by embedding Mozilla. (<a class="external" href="http://www.macromedia.com/v1/handlers/index.cfm?ID=17448&amp;Method=Full&amp;Cache=Off">Mozilla blurb</a>)
</li></ul>
<ul><li> <a class="external" href="http://www.bradsoft.com/topstyle/">Bradsoft's TopStyle CSS builder</a>: Implements an <a class="external" href="http://www.bradsoft.com/support/faq/faqitem.asp?id=1">internal browser</a> using Mozilla ActiveX embedding control.
</li></ul>
<ul><li> <a class="external" href="http://nxzilla.sourceforge.net/">NXZILLA</a>: A set of libraries that allow Mozilla to be used with a <a class="external" href="http://www.microwindows.org">NanoX</a> server.
</li></ul>
<ul><li> <a class="external" href="http://www.iol.ie/~locka/mozilla/mozilla.htm">ActiveX control</a>: An ActiveX control allowing for embedding the Gecko layout engine.
</li></ul>
<ul><li> <a class="external" href="http://ubrowser.com">LLMozLib &amp; uBrowser</a>: a static library that allows you to embed Gecko and render pages to memory. Includes test applications that illustrate how to use it. Versions for Windows and Mac with Linux to follow.
</li></ul>
<h4 name="Mozilla_Examples_2"> Mozilla Examples </h4>
<ul><li> <a class="external" href="http://lxr.mozilla.org/seamonkey/source/embedding/tests/mfcembed/MfcEmbed.cpp">mfcEmbed</a>: Standard Mozilla embedding example application for win32. Basic browser, menus, toolbar, URLbar, html area.
</li></ul>
<ul><li> <a class="external" href="http://lxr.mozilla.org/seamonkey/source/embedding/tests/winEmbed/winEmbed.cpp">winEmbed</a>: Obsoleted by mfcEmbed. A bare-bones browser with URLbar and html area.
</li></ul>
<ul><li> <a class="external" href="http://lxr.mozilla.org/seamonkey/source/embedding/browser/activex/">ActiveX control</a>: An ActiveX control for Mozilla using the Gecko layout engine. More information at <a class="external" href="http://www.iol.ie/~locka/mozilla/mozilla.htm">1</a> and <a class="external" href="http://www.mozilla.org/docs/codestock99/mozcontrol/mozcontrol_files/v3_document.htm">2</a>.
</li></ul>
<h3 name="Mac"> Mac </h3>
<h4 name="External_projects_3"> External projects </h4>
<ul><li> <a class="external" href="http://www.activestate.com/Products/Komodo/index.html">ActiveState's Komodo</a>: Development environment, based on Mozilla's <a href="en/XUL">XUL</a>. (<a class="external" href="http://www.activestate.com/_images/screenshots/ss_Komodo_rails_large.gif">Screenshot</a>)
</li></ul>
<ul><li> <a class="external" href="http://www.apple.com/macosx/applications/aol/">AOL for Mac OS X</a>: AOL chose Gecko to power web support in the OS X version of their client software.
</li></ul>
<ul><li> <a class="external" href="http://www.symphonyinc.co.jp/mozilla/mazmoz/mazmoz_e/index.html">marbrow</a>: Mac port of <a class="external" href="http://www.x2web.com">X2Web</a> (ja, ko) embedding Mozilla.
</li></ul>
<h4 name="Mozilla_Examples_3"> Mozilla Examples </h4>
<ul><li> <a class="external" href="http://lxr.mozilla.org/seamonkey/source/embedding/browser/powerplant/">PPEmbed</a>: Standard Mozilla sample application implemented with Metroworks' Powerplant.
</li></ul>
<ul><li> <a class="external" href="http://www.caminobrowser.org/">Camino</a>: A project aimed at delivering a best-of-breed browser on the Mac OS X platform. Camino uses Cocoazilla, a variant of Fizzilla that consists of a UNIX back end wed to a Cocoa front end.
</li></ul>
<h3 name="Java"> Java </h3>
<h4 name="Examples"> Examples </h4>
<ul><li> <a class="external" href="http://www.mozilla.org/projects/blackwood/webclient/">Java Webclient</a>: Provides a browser-neutral Java API that enables generic web browsing capability.
</li></ul>
<ul><li> <a class="external" href="http://browserg.mozdev.org/">BrowserG!</a>: A Java application that uses Webclient for HTML rendering and surfing capabilities.
</li></ul>
<p><br>
If you find any missing item, please send <a class="link-mailto" href="mailto:dougt@netscape.com">me</a> an email.
</p>
<div class="originaldocinfo">
<h2 name="Original_Document_Information">Original Document Information</h2>
<ul><li> Author(s): <a class="link-mailto" href="mailto:dougt@netscape.com">Doug Turner</a>
</li><li> Original Document: <a class="external" href="http://www.mozilla.org/projects/embedding/howto/index.html">, </a><a class="external" href="http://www.mozilla.org/projects/embedding/howto/config.html">, </a><a class="external" href="http://www.mozilla.org/projects/embedding/howto/Initializations.html"> and </a><a class="external" href="http://www.mozilla.org/projects/embedding/examples/">
</a></li><li><a class="external" href="http://www.mozilla.org/projects/embedding/examples/"> Last Updated Date: December 8, 2004
</a></li><li><a class="external" href="http://www.mozilla.org/projects/embedding/examples/"> Copyright Information: Copyright (C) </a><a class="link-mailto" href="mailto:dougt@netscape.com">Doug Turner</a>
</li></ul>
</div>
Revert to this revision