Embedding/NewApi: Difference between revisions
(→MozApp) |
(add deprecation warning) |
||
| (12 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
= '''This has been deprecated in favor of https://wiki.mozilla.org/Embedding/IPCLiteAPI''' = | |||
== Motivation == | == Motivation == | ||
The idea with the new embedding API is to provide an easier way to embed Mozilla in other applications. The existing API using XPCOM has quite a steep learning curve for new-comers. We would like to improve this with the new API. This is done by making a new API on top of the existing one, which also helps shield embedders for changes in the underlying API, hopefully making things more stable long term. | The idea with the new embedding API is to provide an easier way to embed Mozilla in other applications. The existing API using XPCOM has quite a steep learning curve for new-comers. We would like to improve this with the new API. This is done by making a new API on top of the existing one, which also helps shield embedders for changes in the underlying API, hopefully making things more stable long term. | ||
| Line 10: | Line 12: | ||
Having the common layer also makes it a lot easier to add support for additional toolkits as this should only require a relative thin wrapper. | Having the common layer also makes it a lot easier to add support for additional toolkits as this should only require a relative thin wrapper. | ||
It is however still possible to access the underlying XPCOM API, see [[Embedding/NewApi/XpcomAccess|here]] | |||
== Common Layer == | == Common Layer == | ||
There are 2 main classes for embedding | The common layer is implemented using plain C++. For strings we are using char* encoded as utf-8. When methods return pointers to newly allocated buffers (e.g. strings) it is the responsibility of the caller to free those. | ||
There are 2 main classes for embedding: | |||
=== MozView === | === MozView === | ||
This represent a browser view, capable of displaying content. It should be connected to a window or widget. It also has a listener interface that can be used to get notified of events like when a document | This represent a browser view, capable of displaying content. It should be connected to a window or widget. It also has a listener interface that can be used to get notified of events like when a document has finished loading. | ||
=== MozApp === | === MozApp === | ||
This class provides access to things like preferences. '''NOTE:''' it is optional to use this, i.e. if you don't need the functionality provided by MozApp you don't need to use it. | This class provides access to things like preferences. '''NOTE:''' it is optional to use this, i.e. if you don't need the functionality provided by MozApp you don't need to use it. | ||
=== Doxygen Documentation === | |||
You can find class documentation [http://people.mozilla.com/~mfinkle/embedding/docs/annotated.html here] | |||
== Getting the code == | == Getting the code == | ||
The code currently lives outside the main tree in a separate [http://developer.mozilla.org/en/docs/Mercurial Mercurial] repository (http://hg.mozilla.org/ | The code currently lives outside the main tree in a separate [http://developer.mozilla.org/en/docs/Mercurial Mercurial] repository (http://hg.mozilla.org/incubator/embedding/). Here is how to get it: | ||
<pre> | <pre> | ||
hg clone http://hg.mozilla.org/ | hg clone http://hg.mozilla.org/incubator/embedding/ mozembed | ||
</pre> | </pre> | ||
| Line 30: | Line 39: | ||
* [[Embedding/NewApi/Win32|windows/win32]] | * [[Embedding/NewApi/Win32|windows/win32]] | ||
* [[Embedding/NewApi/QtWin|windows/qt]] | * [[Embedding/NewApi/QtWin|windows/qt]] | ||
* linux/ | * [[Embedding/NewApi/GtkLinux|linux/gtk]] | ||
* linux/ | * [[Embedding/NewApi/QtLinux|linux/qt]] | ||
== To Do == | == To Do == | ||
See [[https://wiki.mozilla.org/Embedding Tasklist]] | |||
== Feedback == | |||
Please use: | |||
* | * [[http://groups.google.com/group/mozilla.dev.embedding/topics mozilla.dev.embedding]] newsgroup | ||
* | * #embedding channel on [[http://irc.mozilla.org Mozilla IRC]] | ||
Latest revision as of 03:18, 8 April 2014
This has been deprecated in favor of https://wiki.mozilla.org/Embedding/IPCLiteAPI
Motivation
The idea with the new embedding API is to provide an easier way to embed Mozilla in other applications. The existing API using XPCOM has quite a steep learning curve for new-comers. We would like to improve this with the new API. This is done by making a new API on top of the existing one, which also helps shield embedders for changes in the underlying API, hopefully making things more stable long term.
For some more background check Chris Blizzard's blog entry.
Structure
The new API has a common C++ layer built on top of the existing API. The new API thus encapsulates many of the complexities of setting up and using XPCOM.
The common layer is then used by platform/toolkit specific APIs. This will allow embedders to use components that fit well into their application, e.g. GTK or Qt widgets.
Having the common layer also makes it a lot easier to add support for additional toolkits as this should only require a relative thin wrapper.
It is however still possible to access the underlying XPCOM API, see here
Common Layer
The common layer is implemented using plain C++. For strings we are using char* encoded as utf-8. When methods return pointers to newly allocated buffers (e.g. strings) it is the responsibility of the caller to free those.
There are 2 main classes for embedding:
MozView
This represent a browser view, capable of displaying content. It should be connected to a window or widget. It also has a listener interface that can be used to get notified of events like when a document has finished loading.
MozApp
This class provides access to things like preferences. NOTE: it is optional to use this, i.e. if you don't need the functionality provided by MozApp you don't need to use it.
Doxygen Documentation
You can find class documentation here
Getting the code
The code currently lives outside the main tree in a separate Mercurial repository (http://hg.mozilla.org/incubator/embedding/). Here is how to get it:
hg clone http://hg.mozilla.org/incubator/embedding/ mozembed
Build Instructions
To Do
See [Tasklist]
Feedback
Please use:
- [mozilla.dev.embedding] newsgroup
- #embedding channel on [Mozilla IRC]