Closed Bug 141350 Opened 22 years ago Closed 18 years ago

Gecko Embedding Basics tracking bug

Categories

(Developer Documentation Graveyard :: General, defect)

Product:
Developer Documentation Graveyard
Component:
General
Platform:
x86
Windows 98
Type:
defect
Priority:
Not set
Severity:
normal

Tracking

(Not tracked)

Status:
RESOLVED INVALID

People

(Reporter: jeev13, Assigned: jeev13)

References

(
URL
)

Details

Please file any questions, additions, errors, etc re: this document here.
QA Contact: imajes → rudman
Status: NEW → ASSIGNED
Moz wrapper .css added unexpected bold to two pages.  Will do workaround.
URL: http://www.mozilla.org/projects/embed...
Looks great!  Here are some humble suggestions:

* Add the TOC to the start page, as an overview of what the guide is about.
* Is this guide linked from mozilla.org/docs and mozilla.org/catalog? If not,
hook it up for public usage. Perhaps even post a note to the front page of
www.mozilla.org so people will notice this new document.
* From the XUL/XBL page, link to www.xulplanet.com ; their documentation is by
far better (and better up-to-date) than ours.
The TOC is easily available from the opening page, and this is traditionally how
we've done the docs.  It's certainly changeable, though, if there is a strong
feeling about it.  The only link in for the moment is from the embedding project
page, which is where most folks who might need this will probably be looking. 
The doc stuff is in the process of being reorganized and will probably link to
this as well. The XUL Planet suggestion is a good one.  I'll put it on my update
to do list.  Thanks.
Excellent job Ellen!

"Netscape and Mozilla both use XUL for their interfaces, but not all embedders
chose to use it."  

I think you want to say "choose" not "chose"

On page 12 - What Gecko Provides - most of the page is bold. Is that intentional?

If you want to include any information about our support for accessibility, or
our future plans, let me know. Most of the info is at
http://www.mozilla.org/projects/ui/accessibility
Couple more spelling errors on Page 16:
- View Manger
- things like platform specific event   [ missing an s in events ]
The bold on "What You Provide" and "What Gecko Provides" are the result of the
.css file on the mozilla.org wrapper.  I'm trying to work it out.
Bold problem fixed.  
Ellen

One other thing I'd like to have is a list of interfaces that are frozen as of
Mozilla 1.0.  Not before, or not after.  In other words, a version of the doc
athttp://www.mozilla.org/projects/embedding/EmbedInterfaceFreeze.html
that is frozen as of the 1.0 release.  

James is willing to create this doc, but we don't want to duplicate effort if
you are working on this.  I apologize if you've had this discussion with James,
but can you let us know if you're working on this, or if there's any reason
James shouldn't plow ahead?

thanks

mitchell

Mitchell - 

There is the document at
http://mozilla.org/projects/embedding/embedapiref/embeddingapiTOC.html which is
a pretty good first cut at documenting the frozen interfaces as of 1.0.  Some
things haven't yet made it - the network stuff being the biggest chunk - but
they will be there in fairly short order.  It would be fairly simple to add some
sort of "frozen by <milestone>" to each of the interfaces if that would be
useful information.

James and I have exchanged emails about this - I was dismayed to hear he had
already put some time in on the work.  But it does seem as if it would be a
duplication of effort to have him develop his own cut at the APIs.

Thanks.

Ellen
I think James will be OK, I'm glad we learned of your work before he got too far.   
Your suggestion of adding a "frozen@milestone" info might be helpful. Or is
there some easier way for a reader to tell if the referenced API has been frozen?

It doesn't sound like this suggestion would actually generate a list of APIs
frozen as of 1.0.  We've talked a great deal about Mozilla 1.0 being important
because of a set of APIs that are frozen and can be relied on.  I'd like to have
a list that says "and here is that set of APIs."  An LXR query won't do it once
additional APIs are frozen after 1.0 (or even frozen on the trunk before 1.0 is
released).  Am I missing some simple technique?


mitchell
I can just version a copy of the APIs I'm doing at 1.0 - that would be simple
enough.  But there are other APIs I'm not documenting - for example the DOM
stuff, which lives in a document Ian did.  Or any of the XUL/XBL stuff. 
Creating some sort of super-index of all of them would be one way to go to get a
_Frozen at 1.0_ set.  Would James be interested in doing that?

Another thing this whole experience brings up is the woeful state of
communication re: docs between mozilla and Netscape.  We probably need to come
up with a better way of trying to keep potential reduplication (and thus waste
of precious resources) at a minimum.  Ideas?
Well, we have the newsgroup netscape.public.mozilla.documentation ... that's a
good starting point for communication across boundaries. :-)
Ditto what Hakan said. 

We did have the Mozilla Documentation Project page, which was an attempt to
provide an infrastructure for establishing who was doing what. It didn't get
very far. And though the page still exists, it doesn't appear to be accessible
from any of the new Moz doc pages. 
so now i know why i wasn't getting mail about this, *no-one* cc'ed me! :)

 -- james
Two humble suggestions:
* Replace graphic buttons with text.
* The logo "Gecko Embedding Basics" takes up much space. You could replace it by
a horizontal logo. This could sometimes prevent scrolling.
Added ref to XULPlanet
on http://www.mozilla.org/projects/embedding/embedoverview/EmbeddingBasics9.html

old:

Web browsing typically involves a large amount of string manipulation. Mozilla
has developed a hierarchy of C++ classes to facilitate such manipulation and to
render it efficient and quick.

should be:

Web browsing (snip typically) involves...

... render it quickLY and efficientLY.
Actually, no.  "Quick and efficient" modifies "string manipulation" not
"render". The word render here means "make" not "draw on the screen"
Under common browser tasks, I think you should show people the declaration for
mWebBrowser, so they know what type it is. I haven't checked other areas of the
docs for the same problem.

//Create an instance of the Mozilla embeddable browser 
 
HRESULT CBrowserView::CreateBrowser()  
{ 
// Create a web shell  
nsresult rv; 
mWebBrowser =  
	do_CreateInstance(NS_WEBBROWSER_CONTRACTID, &rv); 
if(NS_FAILED(rv)) 
return rv; 

Ok, maybe I'm being really really picky, but I'm trying to embed Gecko into a
wxWindows-based application.  (With any luck, it'll result in the class wxGecko
:)  )

My development environment is Mandrake Linux 9.0, with the mandrake supplied
rpm's of mozilla 1.1.

I'm having a real hard time grokking how to embed Gecko.  In concept, it seems
simple enough, right?  Initialize XPCOM, make sure to terminate it.  So you
initialize it when the app starts, and you terminate it when the app terminates.

Problem is, what include files do I use?  How do I include the declarations for
the functions to initialize and terminate XPCOM, and what files do I include for
the nsWebBrowser interface (et al, it looks like that one will satisfy my needs)?

I ask, because as I'm sure you're aware, typically you have the .h files
somewhere in your include path, and you include the one you need.  Then the
linker sorts out where the functions/classes actually are.

Dave
Embedding Gecko is a somewhat more complex task that just dropping nsWebBrowser
into one's code.  As the document says, the best place to get an idea of what an
embedded browser might look like is 
mozilla.org/projects/embedding/examples/index.html, where an example from each
of the platforms is available.  Sample manifest files can be found in
mozilla/embedding/config.  
http://www.mozilla.org/projects/embedding/embedoverview/EmbeddingBasics4.html
update MRE link to www.mozilla.org/projects/embedding/GRE.html.
Updated to GRE link
At the end of the page
http://www.mozilla.org/projects/embedding/embedoverview/EmbeddingBasics6.html
there's an '"' (doublequote) missing that make the author's e-mail address look
strange.

Here is a patch generated by doctor.mozilla.org

Index: mozilla-org/html/projects/embedding/embedoverview/EmbeddingBasics6.html
===================================================================
RCS file:
/cvsroot/mozilla-org/html/projects/embedding/embedoverview/EmbeddingBasics6.html,v
retrieving revision 1.8
diff -u -r1.8 EmbeddingBasics6.html
--- mozilla-org/html/projects/embedding/embedoverview/EmbeddingBasics6.html	7
Jul 2003 20:03:36 -0000	1.8
+++ mozilla-org/html/projects/embedding/embedoverview/EmbeddingBasics6.html	29
Jul 2003 18:19:36 -0000
@@ -120,7 +120,7 @@
 <a name="1000474"> </a>For more information<br>
 </div>
 <p class="Body">
-  <a name="1000479"> </a>More information on XPCOM in general can be found at
<a href="http://mozilla.org/projects/xpcom/">mozillla.org/projects/xpcom/</a>.
For an overview of creating XPCOM components, see Chapter 8 of O'Reilly's
<i>Creating Applications with Mozilla</i>, an open source version of which is
available at<a
href="http://books.mozdev.org/chapters/ch08.html">books.mozdev.org/chapters/ch08.html</a>.
There is also a new book completely devoted to this topic, <i>Creating XPCOM
Components</i>, available at <a
href="http://mozilla.org/projects/xpcom/book/cxc/>http://mozilla.org/projects/xpcom/book/cxc/</a>.
 A fuller explanation of some of the underlying logic to COM systems can be
found in the early chapters of <i>Essential COM</i> by Don Box. While it
focusses on MSCOM in particular, the book does provide an excellent background
on some of the core rationales for using such an object model.
+  <a name="1000479"> </a>More information on XPCOM in general can be found at
<a href="http://mozilla.org/projects/xpcom/">mozillla.org/projects/xpcom/</a>.
For an overview of creating XPCOM components, see Chapter 8 of O'Reilly's
<i>Creating Applications with Mozilla</i>, an open source version of which is
available at<a
href="http://books.mozdev.org/chapters/ch08.html">books.mozdev.org/chapters/ch08.html</a>.
There is also a new book completely devoted to this topic, <i>Creating XPCOM
Components</i>, available at <a
href="http://mozilla.org/projects/xpcom/book/cxc/">http://mozilla.org/projects/xpcom/book/cxc/</a>.
 A fuller explanation of some of the underlying logic to COM systems can be
found in the early chapters of <i>Essential COM</i> by Don Box. While it
focusses on MSCOM in particular, the book does provide an excellent background
on some of the core rationales for using such an object model.
 </p>
 </blockquote>
Fixed.

Thanks.
The doc was moved into MDC wiki, so people can update it directly if needed.
Status: ASSIGNED → RESOLVED
Closed: 18 years ago
Resolution: --- → INVALID
Component: Mozilla Developer → Documentation Requests
Product: Documentation → Mozilla Developer Center
Component: Documentation Requests → Documentation
Component: Documentation → General
Product: Mozilla Developer Network → Developer Documentation
You need to log in before you can comment on or make changes to this bug.