MozillaZine

Creating dialogs

From MozillaZine Knowledge Base

(Difference between revisions)
Revision as of 14:24, 20 October 2005
Unarmed (Talk | contribs)
(reverting (unintentional?) changes by Ferhatcpp)
<-- Previous diff
Revision as of 21:09, 31 October 2006
Grimholtz (Talk | contribs)
(Moved article to MDC)
Next diff -->
Line 1: Line 1:
{{extdev}} {{extdev}}
-==Dialogs in Mozilla== 
-Whenever you want to create a dialog in your application, use &lt;dialog&gt; (instead of usual &lt;window&gt;) as root element in the XUL file. This will: 
-*Handle a few keyboard events (ENTER/ESC and more), which is good for keyboard accessibility. 
-*Add OK and Cancel buttons in an order that is consistent with OS default (but the button set and layout is highly customizable, see below). 
- 
-==Simple dialog code== 
-The following XUL code defines a simple dialog with two buttons, OK and Cancel ('''buttons="accept,cancel"''' attribute on '''dialog'''). 
- 
-<pre><?xml version="1.0"?> 
-<?xml-stylesheet href="chrome://global/skin/global.css" type="text/css"?> 
- 
-<dialog xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul" 
- id="..." title="..." 
- buttons="accept,cancel" 
- ondialogaccept="return onAccept();" 
- ondialogcancel="return onCancel();"> 
- 
-<script src="chrome://..."/> 
- 
-<!-- Content --> 
- 
-</dialog></pre> 
- 
-You need to implement ''onAccept'' and ''onCancel'' functions in your script. If they return anything but '''false''', the dialog will be closed. 
- 
-==Buttons in &lt;dialog&gt;== 
-===Predefined=== 
-There are six button types you can use in the '''buttons''' attribute of dialog. They are: 
-*'''accept''' &mdash; OK button. 
-*'''cancel''' &mdash; Cancel button. 
-*'''disclosure''' &mdash; More Info button. 
-*'''help''' &mdash; Help button (Doesn't work in Thunderbird 1.0 [https://bugzilla.mozilla.org/show_bug.cgi?id=256915]) 
-*'''extra1''', '''extra2''' &mdash; Two buttons without any predefined labels or meaning. '''extra2''' is positioned at the left side of the dialog (by default). 
- 
-For each of these buttons you can set their label, accesskey and oncommand handler by adding buttonlabel<buttonname>, buttonaccesskey<buttonname> and ondialog<buttonname> attributes to the '''dialog''' element. For example, to add an an Apply button to your dialog, use the following code: 
-<pre><dialog xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"  
- id="..." 
- buttons="accept,cancel,extra1" 
- ondialogaccept="onAccept();" 
- ondialogextra1="onApply();" 
- buttonlabelextra1="Apply" 
- buttonaccesskeyextra1="A"> 
- 
-<!-- Content --> 
-</dialog> 
-</pre> 
- 
-You can even get the element object for any of predefined buttons with  
-<tt>gDialog.getButton(dlgtype);</tt>, where '''gDialog''' is the &lt;dialog&gt; element and '''dlgtype''' is one of the six button types listed above. 
- 
-===Explicit=== 
-If you are not satisfied with the layout of predefined buttons in '''dialog''', you can put explicit '''button''' elements in your XUL file and add a '''dlgtype''' attribute to them. Valid values for '''dlgtype''' are the six button types listed above. 
- 
-Be sure to use '''ondialog*''' attributes on '''dialog''' element instead of putting '''oncommand''' on the button with dlgtype, because button's oncommand is executed only when the button is pressed, and ondialog* handlers are executed for keyboard and other events too. 
- 
-'''Example:''' 
-<pre><?xml version="1.0"?> 
-<?xml-stylesheet href="chrome://global/skin/" type="text/css"?> 
- 
-<dialog xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul" 
- ondialogaccept="alert("ok!");"> 
-<hbox> 
- <label value="Hey!"/> 
- 
- <spacer flex="1"/> 
- <vbox> 
- <button dlgtype="accept"/> 
- <button dlgtype="cancel"/> 
- </vbox> 
-</hbox> 
-</dialog></pre> 
- 
-===Default button=== 
-Since Firefox 1.5, there are <code>defaultButton</code> attribute and property on the <code><dialog></code> element [https://bugzilla.mozilla.org/show_bug.cgi?id=284776]. The possible values for the attribute are the names of buttons listed above, and the default is <code>"accept"</code>, for compatibility with previous versions. 
- 
-==Using &lt;dialogheader&gt;== 
-You can use the '''dialogheader''' element to add "headers" to windows. To get an idea of what it looks like, open Options (or Preferences) dialog in Firefox or Thunderbird (''v1.0 and earlier only''). The header to the right of the sections buttons is made with &lt;dialogheader&gt;: 
- 
-<pre><dialogheader title="General" description="whatever"/></pre> 
- 
-Note, that you should only use this element in a &lt;dialog&gt;, because otherwise it may be not styled properly. (Although it seems to work in &lt;window&gt; as well). 
- 
-==Links== 
-*XulPlanet.com 
-**[http://xulplanet.com/references/elemref/ref_dialog.html '''dialog''' element]. 
-**[http://xulplanet.com/references/elemref/ref_dialogheader.html '''dialogheader''' element]. 
-**[http://xulplanet.com/tutorials/xultu/dialogs.html Creating dialogs] section from the XUL Tutorial. 
-*[http://lxr.mozilla.org/seamonkey/source/toolkit/content/widgets/dialog.xml dialog.xml] &mdash; XBL bindings for <dialog> and <dialogheader> elements. 
-*[http://groups-beta.google.com/group/netscape.public.dev.xul/msg/02075a1736406b40 Passing parameter to a dialog and getting return values from it]. 
 +[http://developer.mozilla.org/en/docs/Code_snippets:Dialogs Moved to MDC]
[[Category:Example code]] [[Category:XUL example code]] [[Category:Example code]] [[Category:XUL example code]]

Revision as of 21:09, 31 October 2006

This page is part of the extension development documentation project.

Ask your questions in MozillaZine Forums. Also try browsing example code.

Note: development documentation is in process of being moved to Mozilla Development Center (MDC).


Moved to MDC