Closed Bug 24689 Opened 21 years ago Closed 13 years ago

XUL Reference Manual


(Documentation Graveyard :: Web Developer, defect, P3)



(Not tracked)



(Reporter: oeschger, Unassigned)





(1 file)

1.43 KB, application/vnd.mozilla.xul+xml
First draft is available for review. Write comments, additions, feedback, et al 
against this bug so we can update and keep track of progress on this piece of 
The specified URL did not work for me. Instead, I found a document located at:

Is this the correct URL? Thanks.
The URL works for me, though not if you click the URL link directly in bugzilla. 
The link in the text box is appended to, and a Not Found 
message results. But if I copy the and paste the URL in the Location box, it 
works for me.
The link to the XULREF has been updated. Though you can still grab it at: for some period 
of time, 
the latest and greatest will be at: 

...until I put it on mozilla. 

Updating QA Contact...adding ornduff to cc list.
QA Contact: nobody → oeschger
Ian, couple of nits....I'd change the URL in this form (in the URL field near 
the top of the bug report) to the mozilla URL. Also, I'd add a hyperlink in the 
doc itself (at the top of the doc) to the bug report. Indicate that the doc is a 
draft, and that people can add comments in the bug.

Why say that the doc is a "complete reference for the XPToolkit." Why use 
XPToolkit at all? The relationship between XUL and XPToolkit isn't explained in 
the doc, but maybe the subject is best not dealt with at all in the doc. But I 
wouldn't start the doc with that sentence without further explication.
Changed the url. Thanks, Jan. I'll add a pointer to the bug, perhaps a brief 
explanation of what the XPToolkit has to do with XUL, and a DRAFT note on the 
Sorry for the spam: updated the intro page for the XULREF per leger's 
Uh, that would be "rudman's suggestions."

Thanks for making the changes.
Could you please add a column for "methods" and "event handlers" for each xul 
element.  For instance there is an event handler called onInput for input fields 
which is special to XUL.

A great example of a really nice "road map" is this url:
It shows all of the properties,methods, and event handlers for all of the NS4 
javascript objects.  It's a nice example of a good reference guide.
The link to "broadcasters and observers" is broken.
Thanks, Andrew
Given the fact that all XUL widgets must be formatted like key/value 
pairs (e.g., onclick="doFunc()" ), I was hoping to document all the members as 
attributes regardless of their type. This may have been confusingly consistent 
of me. I know and love DannyG's layout of the Navigator JS Object Model. Let me 
look this over.
There is no documentation on the <browser> and <editor> tags. And I just learned 
that you dont have to use <html:iframe> but can use just <iframe> now...

Separating out the methods and stuff is really helpful in that it makes it 
easier to find them quickly.
There's no reference for the XML "setup" of a simple xul file - meaning there's 
no entry which explains this header info:


Also there should be references to:
1) how to insert a stylesheet
2) how to insert js code
3) how to use overlays
4) how to use RDF overlays
I mention the window "preamble" in the window area under the xmlns attribute and 
others. I need to say more about this. Note also the methods section in the 
window object's spelling.

As for these other omissions you mention, I am hoping to include these in the 
XUL Programmer's Guide and not here in the widget reference. I've sort of 
flip-flopped a couple times about the focus of this guide, about sticking just 
to the actual widgets or broadening to include information about things like 
how to include a stylesheet. I'll have to look at them one by one. 

Thanks for all your helpful feedback, Andrew.
How about all page "zip" for download?
Looks like the links to text and image elements doesnt work.  It should at least 
have "under construction" or something there instead of a broken link.
Removed the new icons and made some more changes:
* <tab> is now a closed element with the value attribute
* oncommand has been added to all the box-derived elements
* <titledbox> was added to the box page, though it doesn't actually seem to be 
working in my build.
* <stack> language was spruced up a bit
* references to <titledbutton> were squelched

Still waiting on <html>, <script>, and a few others before I call it Third 
new version of the zip file checked in -- the third zipped up "milestone", I 
Added text widgets reference: <text /> and <textfield />.
Both of these are begging the XBL question, which I will focus on shortly.
Summary: XUL Reference Manual First Draft → XUL Reference Manual
There is no information in the keyset/key section about the "keycode" attribute 
on the key element.  I discovered this only after scouring through chrome 
files... might be a good thing to document.
Added keycode attribute documentation to <key> and keyref.html
Thanks, Joe.
Added oncreate and ondestroy to popup-like widgets. Files: popup.html, 
popupref.html, menupop.html, menuref.html.

Scouring for more missing events in XULREF per joe hewitt's suggestion.
Added a nice little sample and screenshot of <treecol>, which was 
underdescribed. Still more work to do on tree-related attributes and events
two points. Please rename Xul_Reference.html to index.html. The way
you have it now, its hard to figure out which of the many files in that
directory is the top level one. Doing this also lets you use shorter, more
intuitive URLs.

It would also make the document a lot easier to use if you didn't use
frames. The use of frames makes it so people can't bookmark items or
use the history. Also, since you need to set the size of the right
menu bar in PX units the layout of the document is wrong for people
using nonstandard sized fonts.
Prefixed URL with http:// to make it work directly.
What about a cookbook type section showing how to create a simple UI with a 
small interface to some C++ code?
Added index.html page per endico's request, but keeping XUL_Reference.html 
around just in case. For now.

pointer is now, as it should be. Will also 
update our own links to this manual. Thanks, Dawn
Added some additional explanation to the broadcastref section per Simon's 
request. Still working on fleshing out this topic in the xulref....
Hi Ian,
two remarks, first you have a section called "Img Elements", which mislead me 
somehow, want to call it "Image Elements"? As it is empty right now, I had quite
a time with the <img> tag. Browsing the source and moving to <image> just made
it easier alot ;-)

Secondly, in the second example for trees, the <treehead> section is messed up
in the closing tags. Could you add some hints on indenting the children?

Thanx, I like those pages, otherwise I wouldn't find bugs ;-)

Added <grid> widgets, <menubutton> and menu updates
Added content windows to xulref. Need some more details, but <editor> <browser> 
and <iframe> are now under "content windows" in TOC.
Added <html> and html:namespace elements page. Updated index
Is anybody still updating this documentation ? Is this stuff current ? I am 
thinking of writing a new skin so it would be really handy for me to have a 
completely updated document for reference.

Adding myself to the CC list.
I'm missing the bulletinboard element. Shouldn't that be in here?
There are more XUL elements or attributes in
that aren't in this reference.
Looks like <template> is missing too
You may want to cooperate with the guy on He's keeping his
tutorial and reference very up to date.

The 'Content Widgets' section could do with some sprucing up.  The differences 
between <editor>, <browser> and <iframe> widgets should be highlighted.  The 
introduction to all there needs some updating.

Has anyone experimented with multiple <iframes>'s?  I'm looking to implement 
some form of multi-doc interface (MDI).
I think you want a <stack/> or <deck/> containing iframes.
The stack or deck with multiple iframes in it apparently doesn't work too well. 
The iframes compete for rendering space and sort of draw on top of one another.
Yeah, about mozilla had problems w/ this. Refer to Editor which I think solved 
this problem. At worst you should be able to hide the iframes that should not 
The introduction includes a section on XUL syntax that says "There are a couple
of very slight departures from the core XML syntax, but for the most part, the
syntax rules are the same." I'm not quite sure what the "slight departures" are,
but AFAIK XUL is a direct *application* of XML. As it reads currently, the
section implies that "XUL is essentially like XML". I'd recommend rewriting it
to say "XUL is XML". It's fine to summarize XML well-formedness rules that might
be new to HTML developers, but I'd definitely include a link to the XML 1.0 spec
as the definitive set of rules for any and all XML applications.
The sub-section titled "Organization of XUL Interfaces" in the Introduction says
that a package includes "a DTD specifying localization strings in the
interface". The role of a DTD is to specify a set of validity rules for an XML
application. DTDs can also contain entity declarations which we happen to use as
a convenient means of separating localizable strings from the structure of the
document. I'd recommend changing the words quoted above to "a DTD that contains
entity declarations for localizable strings".
Updated intro.html per vidur's comments. Thanks a lot, Vidur.

I will try to make some more updates to the xulref this week based on discussion
in this bug and emails I've been getting. Any help 24689-followers can give is
It would be nice to have some search functionality exclusive to xulref, as 
opposed to using the general search.
Made some updates this morning: added observes attribute to box (and its ilk),
fixed the observes node documentation, updated the navigation pane and the
index, fixed some typos in checkbox.html and others, added hbox and vbox docs. I
will be continuing to try and get this doc current.
Added some more: "Layout Managers" section in navbar, <bulletinboard> element
(finally), "read-only" to textfield. Changed "Content Widgets" to "View
Elements" per andreww's suggestion.  
coming shortly: scrollbox, broadcasters docs
adding "equalsize" to box-based elements, got scrollbox fixed
The documentation for XUL is very incomplete. XULPlanet is missing a lot of 
javascript info. The same with the reference. When are we going to get 
documentation that talks about everything, such as how to find out if an has a scrollbar widget in it and how to scroll the widget for 
example. Also what about interfacing to c++? I think if you can interface to 
c++ (as I have seen done in XUL) then why isn't the c++ documented either? Why 
isn't there a list that talks about what style properties don't work for 
certain XUL elements? It seems there are the DOM documentation on w3c, the xul 
dom documentation, but where is the other half?  - Implementing
Would it be possible to create a printer friendly version of the document here:
Either a single view of html or a PDF.  I'd be willing to help accomplish this.
First, a comment on the page, rather than a comment on the page content:
Why is javascript used to link to this bug? This breaks "open in new window".
Use <a href="" target="_parent">

I think subheadings of attributes, events and methods would be useful.

I think your description of context="..." is wrong, it specifies a context menu.

I think "observes" counts as a common attribute. As your description states,
"The observes attribute is available to any element". There may be others...

The titledbox supports the "title" attribute as an alternative to the element.

You should make it clear that align and valign depend on autostretch="never".
IIRC the only alignments that are supported are top, bottom, center and right;
otherwise they default to middle and left.

IIRC radio items need a group="id" attribute.
added/updated 2/22/01:
* grippy element: src and accesskey (more to come here)
* "Handles" category in navbar (navbar getting too busy, thinking about new
groupings, collapsibility,...)
* box.collapsed, box.valign
* methods and attributes on tree: tree.selectItem, selectedItems, getNextItem,
getPreviousItem, tree.collapsed, tree.getItemAtIndex, tree.valign

* removed js from bug link in intro.html
* treecell.selectedCell, treerow.selectedRow with DOM examples
added observes to all box-derived elements
fixed context description in common.html, added it to box attr list (still have
to add it to box-derived elements).

thanks, neil. Great feedback.
I like to download the Fourth Draft, but I keep getting the Third Draft! After
opening the downloaded zip file I see a link to a NEW version. Using this link,
I keep download the Third Draft, same link. Yak...

BTW, Did anybody here wrote a DTD for XUL?? I have a validator, but I'm missing
a DTD.
I notice that you mention box-derived elements; is there a hierarchy?
If so it might help if the navigation frame reflects this.

To H-J: You can't write a DTD because attributes are user-definable.
Neil, XUL needs a DTD for Internationalization, take a look at this line: "The
localized text must be defined in a separate DTD or DTD fragment." Wrtten by danm.

XUL is like (X)HTML using a pre-defined set of tagnames, and that can be stored
in a custom DTD for validation.

For Ian: 
1 - why didn't you mention a link to the: "XUL Programmer's Guide" in 
2 - why didn't you include a link to a history section (this way we know what 
    files you changed).
3 - where can we find the milestone for the next draft? Can you include that
    into the manual?
4 - when will you make a new zipfile for the link? The text "new" now is rather 
    odd because it links to an "old"(er) zipfile.
The reason dtd's will die is contained in this invalid line:
XUL is like (X)HTML using a pre-defined set of tagnames, and that can be stored
in a custom DTD for validation.

XUL does not exactly use a pre-defined set of tagnames, or at least not one 
that a validator can know w/o having access to the entire application.

however, our dtd's have a much simpler structure :-)
H-J: In Mozilla DTDs are being used as localizable entity holders and not, as
you might imagine, as document type definitions. I'm afraid timeless is right
about the difficulty and unlikelihood of having a real XUL DTD some time soon,
though you _can_ make subset DTDs that do a good job or parsing what they do
know and ignoring what they don't, which is as close as I think we will get.

And I'm not sure I understand what you mean about the link to the XUL
Programmer's Guide. You mean on the docs index page? And what is the XUL
Programmer's Guide. You mean the xultu? Please advise here.

Zip file and history: I will make a new archive when I update the draft--whose
changes I will continue to note here, but maybe you're right and I should do a
history in the doc. I lose out on the cvs history goodies by getting rid of the
mozilla menu, and maybe I should find someone to get that in (particularly given
someone's recent recquest to have the xulref look more like a mozilla doc).

Thanks, H-J
Right, I will only use a custom build DTD for XUL to validate my documents. and
yes I mean the text "For more detailed information, see the XUL Programmer's
Guide." in your index.html. What's that, where can I locate that file?

Note, I wrote an XUL edition of your index.html, as an examples. The menu uses
tabs, documents are displayed with <browser>. 

Psssssss, whispering: "i'm writing a new tageditor for HomeSite. I'm also
working on a custom XUL CodeSweeper for HomeSite. Templates are finished
already. But I didn't told you this, Ok!"
Title boxes is missing a </title>

It is:
<titledbox style="background-color: lightblue;" orient="vertical">
<button value="Click Me" />
<button value="Push Me" />

It should be:
<titledbox style="background-color: lightblue;" orient="vertical">
<title>My title</title>
<button value="Click Me" />
<button value="Push Me" />
Missing the <stringbundle> and <stringbundleset> elements
.... and the (new) command="" attribute
see bug 70746 and bug 70747

<textfield/> is now <textbox/>

value changed to label for several entities (but not all)

Adding a dependency on hyatt and ben's xul 1.0 bug
Depends on: 70753
made xul 1.0 changes (still a few more to do):
value -> label in many cases, textfield -> textbox, ->
menulist.value. Will add commands attribute all over the place today, along with
context. Calling it fifth draft, will make a new zip.
Iano, the section on 'View Elements' needs updating - specifically the pages on 
the <browser>, <editor> and <iframe> elements.

It would be nice to have a little on the differences between then (especially 
<iframe> and <browser>), e.g the interfaces available via the bindings for these 
I recently posted about using the FAQ-O-Matic for this (see my post in 
n.p.m.webtools), what do you think?
I setup a playground so that you can see how the faq-o-matic works and 
how it might work for this.

For some reason, I could look at the entry you made but could not access the Appearance thing, add new entries, or Search. It's looks cool, though. Actually, Dawn Endico was talking about doing some kind of end-user documentation site for with a tool like this. It's a very compelling way to get work done.

Anyway, I like the idea of doing something like this. I wonder how navigable the xulref would be in this format, however, given its size. Like: Mightn't the xulref start to fracture in a FAQ structure like this (e.g., someone would start putting attribute descriptions as siblings of a XUL element, and this might confuse readers).

I assume you mean we would move the existing docs into a framework like this and then have people add entries about things they know. Let's talk. What does everyone else think? Votes? Other approaches?
I'll look into the permissions and start converting in entries
Ok, permissions fixed!
Just my personal opinion, whenever I see a faq-o-matic, I get discouraged.
The ones I have seen so far lacked the answers to my questions, and in general
tend to provide the questions people can answer, instead of answering the 
question newbies have.
And the colors are disgusting ;-), so you know right away what you're in for.
The ones I saw had too many subcategories.
It's not that I don't like the concept, but the ones I saw so far made me leave
I prefer one owner of a page, keeping the content simple, with a tough 

Thanks for bringing this up, as it gives me a chance to talk about some of 
the 'myths' of the faq-o-matic. First of all, I can change the colors, if we go 
live with this, that will certainly be done. Secondly, I was planning on 
allowing only a select group of users the option to do more radical 
adjustments. Any user will be able to make comments, etc... But only 
those who have been pre-screened can move around categories, make 
sub-categories, etc... We can work out the exact permissions setup later. 
To avoid the "sub-category happy" problem, I am trying to work out an 
arrangement now, which will keep the structure reasonible. Once this is 
set, I can set things so that only a very small group of people have the 
authority to change it. Also, the system can save the whole thing in other 
formats, so that if you wanted, say, a text document with the whole xul 
spec, it's just a few clicks away... I am going to post a schema here soon, 
that will show how I plan to lay things out. As always, comments are 
I changed the color scheme, it isn't perfect, but it doesn't make me puke! I 
also started to add categories, let me know what you think.

Can't you have a little link at the bottom the the page `Add an entry' or `Help
us with the documentation', and then if you bring up that, you get the form on
the page?

That way, we can have all the textfields and stuff hidden as long as the
user/reader doesn't want to fill out an entry.
Doing that would require chaning the perl source. I COULD do it, but 
would rather not, as it makes upgrading a problem. What would also work 
is to tell people in a blob on the front page that they may choose 
apperence and set settings there if they wish to contribute. Note that what 
everyone is able to do now will be restricted into groups. I was thinking 
that we could have one group: xulref_lovers, which can do anything 
(somewhat like a despot in despot), another group called xulref_friends 
which can't move categories around and trash categories, etc... Anyone 
else would have a reduced set of permissions. Also, the individual sub-
categories can have different permissions, so one category can let 
anyone do anything, while another is much more restricted (the front page 
could work this way). We can work out the details later. For now, I will 
leave things as they are, so that you can get a feel for the platform.
Ian, can you please change the tab info because this one is using label now
instead of value.
Attribute 'read-only' for <textbox> should be changed into 'readonly'
And what about adding attribute 'disabled' for <textbox> that one is missing now.
Just checked in some tab doc updates. May need another pass through these. Let
me know if I missed something
Ian, can you also change the 'key' documentation and add an complete and working
example how to setup key interception. I will add an example, but you don't have
to use it at all.

Attached file My example
Great example, H-J. I will put it in the xulref today. 
XULRef needs to say something about the syntax for pref tracking - pref="true"
preftype=bool" prefname="" etc. etc.

There don't seem to be docs on <outliner>
See bug 90314 for the new widget, <spinbuttons/> that I'm implementing. 

This will need to be documented, I guess, and I can do the legwork if someone
else wants to take care of the formatting...
I missed description and label, as well as deprecation notices for html, tree
and other pre XUL1.0 friends. (Lost track, but we have dependencies;-))


Finally making a concerted effort to get the xulref updated per XUL 1.0 and its
myriad recent changes. Have a long way to go, but new documentation pays quite a
bit more attention to xbl, has a structure that makes it easier to maintain
(i.e. has various "articles" that explain concepts, then element pages, separate
attribute pages, and so forth), is concise and pleasant to look at, and can be
previewed here until I move it onto

I am working currently on the xbl primer doc, available at:

Now is a great time to take a look and help me get things organized, get
everything represented, contribute articles or descriptions, make suggestions,
complain about how it looks terrible in browsers that are not Gecko-based, &
cetera. As you can see, it's little more than a shell right now. As I get a
little further along (but well before it's "done"), I will spam the newsgroups
and make more noise. Thanks a lot.

My god i just searched for XUL stuff on and it came up with your
brownhen I am in the process of totally reorganizing how the
documentation index page is done (much better now) will have a beta site up
soon. Letting you know.

BTW i have had a hell of time trying to figure out what goes where with stuff
being spread out of over xpfe, xptoolkit, xul etc.
The xulref at is SO far behind (which is why I am
working on a totally different version, noted in the comment above, maybe not
available for the moment now that I have a new ISP), but I've made some updates
per recent requests: fixed menulist attribute is selectedItem, with a capital
"I", grid documentation is being updated per evaughan's thoughtful suggestions,
and there is an updated version of the zip archive at (note the initial cap).
When using Build ID: 2002031104 to preview the renedering of the following code
in an XUL document, the XUL widgets do not display properly. The test examples
were taken from the XUL Programmers' Reference Last updated: 02/28/01. Is the
proposed XUL standard fully emplemented in this build?

<?xml-stylesheet href="chrome://global/skin/" type="text/css"?> <window
<menu name="File">
<menu name="New">
<menuitem name="Navigator" cmd="commandid:newnavigator" />
<menuitem name="Message" cmd="commandid:newmessage" />
<menuitem name="Blank Page" cmd="commandid:newblankpage" />
<menuitem name="Blank Page From Template..."
cmd="commandid:blankpagefromtemplate" />
<menuitem name="Open" cmd="commandid:open" />
<menuitem name="Close" cmd="commandid:close"/>
<menuitem name="Save As..." cmd="commandid:saveas"/>
<menuitem name="Quit" cmd="commandid:quit"/>
<menu name="Edit">

<tabcontrol align="vertical"> <tabbox align="horizontal"> <tab value="Tab One"
/> <tab value="Tab Two" /> <tab value="Tab Three" /> </tabbox> <tabpanel
flex="100%"> <button value="View One"/> <button value="View Two"/> <button
value="View Three"/> </tabpanel> </tabcontrol> <titledbox
style="background-color: lightblue;" orient="horizontal">
<title value="Nice Buttons">
<button value="Click Me" />
<button value="Push Me" />

<box width="150" orient="vertical" autostretch="never" 
  style="border: solid 2px; background-color: lightblue" 
<button value="button1" style="font-size: 12pt"/>
<button value="button2" style="font-size: 12pt"/>
<button value="button3" style="font-size: 12pt"/>

yeah, it is really exciting... but how can i distribute my software? ask users
to install mozilla or ns6 first? replace their ie or other stuff?
do you have a min-size set of dll(s), so(s) or other image that i can combine
with my code?
The zip file needs to be updated to reflect fifth draft!
Hi all,
I've just downloaded the 1.3a version of Mozilla for Window$.
I noticed :
- "image" attribute for <button> elements is said to be "src" in 
XULRef...but "src" does not work
- "position" attribute for <popup> elements is not described in the XULRef

I also tried to set a "checked" attribute to a <menuitem> without success.
    <popup id="examplesMenuPopUp" position="at_pointer">	  	
      <menuitem label="NCBI" oncommand="" checked="true"/>
      <menuitem label="Toto" oncommand="" checked="false" />		 
<box context="examplesMenuPopUp">
      Let's popup !

Did I miss a link to an update of XUL Programmer's Reference ?

Thanks for your attention,

> I also tried to set a "checked" attribute to a <menuitem> without success.

You need to use <menuitem type="checkbox">
Is there an XUL DTD to validate against?  If not, I'd like to try to put one
Depends on: 154972
It seems that in a <grid> you can nest <rows> tags. This is useful if you want
to repeat a multi-row block of data with XUL Templates. If this is an intended
feature (which I hope, since it works), maybe it should be mentioned in the manual?
Here's some code to illustrate this:

  <grid datasources="datasource.rdf" ref="urn:root">

          <rows uri="rdf:*">
              <label value="identifier:" control="identifier" />
              <textbox id="identifier"
value="rdf:" /> 
              <label value="description:" control="description" />
              <textbox id="description"
value="rdf:" />
XUL menu.label example error

On the example for Label is
missing the &gt; at the end of the tag.  It ends with "/" rather than "/>"
moving stuff over to an outside-the-firewall email for the time being, looking
for people to pick these Help and doc bugs up for me.
Assignee: oeschger → oeschger
taking over some of Ian's bugs
Assignee: oeschger → stolenclover
The link points at an old zip file, which
contains the fourth draft of the reference. The online pages, instead, are on
their fifth draft.
Anyone who may update this?
Assignee: daniel.bugmail → rudman
QA Contact: oeschger
zipped HTML version is of the fourth edtion of the reference manual. the 
webpage is the fifth version.

getItemAtIndex has wrong description.

This is a good resource, but something definitive (like a W3C TR sort of thing) would be invaluable not only to aid developers, but to encourage new developers.

I want to redirect this reference to the XUL reference on MDC, which is much more up to date. If anybody knows of useful information in that's not in the MDC reference, please migrate it to MDC (feel free to consult with me if you're unsure).
filed bug 367834 for removal of the reference.
Closed: 13 years ago
Resolution: --- → INVALID
You need to log in before you can comment on or make changes to this bug.