Window and Dialog Cookbook

The Beginnings
15 June 99
contact

Dialogs are alive and somewhat well in Mozilla, and this document attempts to explain their current status.

Change history

1 Dec 99 - This document is dead. Long live the windows document.

15 June 99 - Documented the C++ version of window.openDialog.

17 May 99 - Documented alternative JavaScript methods for opening dialogs, using window.open and window.openDialog, rather than Toolkitcore. Updated API descriptions.

1 Apr 99 - Updated the examples to mention window titles and sizing, and resisted documenting the new AI features that I didn't check in.

15 Mar 99 - Changed name of onconstruction tag to onload.

2 Mar 99 - Updated use of namespaces in the examples..

25 Feb 99 - More careful about case sensitivity in the examples. Updated example of creating a dialog from C++.

24 Feb 99 - More careful about namespaces in the examples. Added a note about XUL Document method getElementByID

23 Feb 99 - AppCoresManager name changed to XPAppCoresManager

18 Feb 99 - Updated to new command architecture and initialization code.

17 Feb 99 - Revised JavaScript for debriefing dialog elements at dismissal time. Added note about DOM interfaces available to XUL widgets (also in the Examples section).

16 Feb 99 - Revised JavaScript for initializing dialog elements at window load time

Scope

This document is not intended to be a comprehensive syntax or reference manual. With care and time, it should grow into a useful starting place for making windows and writing dialogs. The author thinks that feedback on what's missing from the document would help build a better document, so the quality of this thing is in the reader's hands. Keep that in mind while you're cursing me.

In the meantime, this document also serves as a roadmap of XPFE's dialog story. Interested parties would please review it to determine whether the package we plan to deliver will meet their needs.

Direction

Current XPFE design goals state that dialogs get no special treatment; they're just windows like any other. Windows can have parent windows, and be displayed modally, and have control callbacks, and so behave like dialogs. But our goal is that the same application code that instantiates a browser window will serve equally to instantiate a dialog window. The difference lies in the window content, and a couple of parameters controlling modality and that sort of thing.

JavaScript vs C++

Currently, all window control mechanisms flow through JavaScript. That is, any capabilities a window may have besides taking up space on the desktop are specified in the XUL describing the window, and the binding between the window content and the application is done through JavaScript in the XUL. That binding can be very short: it can fall through to application C code very quickly, but JavaScript will be part of the process. (Note that we have not yet run into any threading problems with this model, but we kind of expect to.)

JavaScript is easily added to a window: just include it in the XUL window description and follow a short but peculiar dance to hook it up. Hooking up C code involves writing a C++/JavaScript interface, and calling it from JavaScript. That interface is an AppCore, and there's a separate and much more impressive document describing them and explaining how to build them.

Make a Window

So, there are two ways to make a window or dialog: directly through C++ and from JavaScript. The resulting window is an instance of nsWebShellWindow. This means it currently contains a hulking bunch of hackery for hooking up browser-window specific contents. This causes no harm, and will be cleaned up in the future.

Note that modal dialogs or alerts are currently working only on Windows and the Macintosh, and even then, only for modal dialogs created on the UI thread. That is to say, they're only halfway there. Also note that windows are not sized to content. These are merely somewhat glorified browser windows, to which automatically sizing themselves to match their content is something of an eyebrow-furrowing concept. Specifying the size of a dialog is another future enhancement.

JavaScript

window.open will open a XUL window if given a XUL URL to load. It will open the given URL as the contents of a browser window, unless the chrome feature is specified in window.open's third ("features") parameter. Mozilla supports an extended form of window.open which can be used to pass parameters back and forth to the dialog window. It's named window.openDialog, reasonably enough, for now. Both window.openDialog and chrome are described in JavaScript Extensions.

Another JavaScript interface is a Mozilla AppCore named ToolkitCore. It contains a handful of windowing utility functions which were more useful before window.open was working properly. ToolkitCore will probably be deprecated soon.


 function MakeDialog() {
   var newWindow = window.open("resource://res/samples/madedialog.xul",
                     "itsname", "chrome");
 }
or, alternatively for now,

 function MakeDialog() {
    var toolkitCore = XPAppCoresManager.Find("ToolkitCore");
    if (!toolkitCore) {
      toolkitCore = new ToolkitCore();
      if (toolkitCore)
        toolkitCore.Init("ToolkitCore");
    }
    if (toolkitCore)
      toolkitCore.ShowWindow("resource://res/samples/madedialog.xul",
          window);
  }

An XPAppCoresManager is pre-constructed; you can access it without any more preparation than shown above. ToolkitCore is not; it requires that small bit of preparation.

C++

There are two interfaces for opening new windows from C code. They are equivalent in the sense that either will make a new window, and both share their innermost important bits. The reason for having both is part historical, and part momentum. In the future, we'd like to meld the two into one.

nsIAppShellService::CreateTopLevelWindow

The primary C++ interface is nsIAppShellService::CreateTopLevelWindow(). It's currently very clunky and will change (you'll see that statement many times in this document). But at time of writing, you create a new window like this:


  nsresult              rv;
  nsIAppShellService    *appShell;
  nsIURL                *url;
  nsIWebShellWindow     *parent, *window;
  nsIStreamObserver     *observer;
  nsIXULWindowCallbacks *callbacks;
  PRInt32               width, height;

  window = nsnull;
  rv = nsServiceManager::GetService(kAppShellServiceCID,
         kIAppShellServiceIID,
         (nsISupports**) &appShell);
  if (NS_SUCCEEDED(rv)) {
    appShell->CreateTopLevelWindow(parent, url, PR_TRUE,
                window, observer, callbacks, width, height);
    nsServiceManager::ReleaseService(kAppShellServiceCID,
                appShell);
  }

At time of writing, only url, showWindow, window, aInitialWidth and aInitialHeight are actually used. url is an URL describing the contents of the window. window is returned from the function, set to the created window. See the code for descriptions of the other parameters. This interface is a little rife with silly parameters, and is slowly being cleaned up.

There is another very similar method nsIAppShellService::CreateDialogWindow(). It takes the same parameters and currently functions exactly the same. These two methods are planned to differ only in the kind of border used on the window created. At time of writing, this decision is made at the time the window is created, before any instructions in the file behind the URL could be read and used to help make the decision.

At this time, window descriptions must be loaded from an URL. There will additionally be methods for loading windows from a stream. In fact, XPFE want to say the stream will be the preferred method, though the URL method will probably remain. Streams will disengage the toolkit further from the source of the window description, and will be our method for creating windows whose XUL is calculated at runtime, rather than being distributed as a file.

nsIDOMWindow::OpenDialog

The other C++ interface is nsIDOMWindow::OpenDialog. It has the advantage that it behaves exactly like the JavaScript window.openDialog function, being the same code used by that function, after all.

The close association between this function and JavaScript places constraints on its usage. Any parameters sent to this function must be ready for use in JavaScript handlers built into the new window, and so must be fitted into JavaScript wrappers. There must also be a "parent" window available to do the window opening and provide a JavaScript context.

The function to wrap a series of arguments is called JS_PushArguments, and is defined in jsapi.h. Its mysterious third argument is explained in that same header file. The sample code below will call OpenDialog, given an nsIDOMWindow to work with. The arguments to OpenDialog are exactly those from its JavaScript definition, explained in JavaScript Extensions. The first three are standard Open arguments. The remainder are parameters for the new window. That new window will have a property named arguments. It's an array, and arguments[0] is the string "I was born a C string", while arguments[1] is the number 298.

DoOpenDialog(nsIDOMWindow* aParent) {

  if (!aParent)
    return NS_ERROR_NULL_POINTER;

  nsresult rv = NS_ERROR_FAILURE;
  JSContext *jscx = 0;
  nsIDOMWindow *newWindow;

  // get the parent window's JS Context (this is not really a blessed thing
  // to do, but I believe it's all we have. it wants to be a real interface
  // someday.)
  nsCOMPtr<nsIScriptGlobalObject> scriptGlobalObj = do_QueryInterface(aParent);
  if (scriptGlobalObj) {
    nsCOMPtr<nsIScriptContext> scriptcx;
    scriptGlobalObj->GetContext(getter_AddRefs(scriptcx));
    if (scriptcx)
      jscx = (JSContext *) scriptcx->GetNativeContext();
  }

  // if everything went as planned...
  if (jscx) {

    // build a JavaScript "arguments" array for the OpenDialog function
    void *mark;
    jsval *argv;

    argv = JS_PushArguments(jscx, &mark, "ssssu",
      "resource://res/samples/paramdialog.xul",
      "windowName",
      "chrome",
      "I was born a C string",
      (uint32) 298);

    // if that worked, call the function.
    if (argv) {
      aParent->OpenDialog(jscx, argv, 5, &newWindow);
      JS_PopArguments(jscx, mark);
      rv = NS_OK;
    }
  }

  return rv;
}

Load a Window

Between making and showing the window, there is a callback. The resulting nsWebShellWindow comes with an associated DOM content model. Any initial control settings or content changes which must be made before the window is actually shown can be done at the time of this callback.

This callback is any JavaScript specified as the value of the onload attribute of the <window> element. In the example below, the window start tag is declared

<window ... onload="Startup()">

During the onload callback, dialog authors are free to alter control settings from JavaScript:


  function Startup() {
    // yellowize and check the "ow" button
    document.bgColor = "yellow";
    var checkbox = document.getElementByID("ow");
    if (checkbox)
      checkbox.checked = true;
  }

Except that not all properties are hooked up yet. The change to background color in the example won't do anything. But the important example does work!

Dialog preprocessing can also be done in C by defining an AppCore, loading and calling it from the Startup() method, as the ToolkitCore AppCore was called to create the window.

Debrief a Window

After the dialog has run -- a dismissal button has been clicked, say -- dialog users will need a callback in which to query the current control settings. As always, this will be done by walking the DOM content model, and accessed through a JavaScript hook.

We are uncertain whether a specific callback need be added: the event handler for the dismissal buttons may be entirely sufficient. But as the reader has no doubt guessed, there is no specific debriefing hook implemented at this time.

Data can be passed back to the calling window in more than one way. The dialog window and opener can agree to share information as properties added to the JavaScript dialog window object. Alternatively, the two windows could agree that the dialog window will call some function of its opener. A third way could be for the opener to use window.openDialog to pass parameters by reference to the dialog window. Any changes made by the dialog to these parameters would be visible in the opener window. See JavaScript Extensions or the examples for details. Two files in the source code at mozilla/xpfe/browser/samples/dexparam*.xul are a kind of test suite for parameter passing, and consequently spell out more details than will this document.

Note at time of writing, a dialog window, once closed, cannot be successfully accessed from JavaScript through the variable which was returned by window.open. This is a known bug, and wants fixing.

Examples

The following XUL describes a browser window with a simple toolbar containing a single button which will open another window: a nonmodal dialog, with a bit of imagination. It uses the extended window.open syntax to pass parameters to the dialog window. The dialog window uses these parameters to initialize its settings. It then passes the state of its checkbox back to the caller, in that same parameter.


<?xml version="1.0"?>
<?xml-stylesheet href="xul.css" type="text/css"?>
<!DOCTYPE window>
<!-- Simple sample interface for bringing up a nonmodal dialog -->
<xul:window
  xmlns:html="http://www.w3.org/1999/xhtml"
  xmlns:xul ="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
  title = "Dialog creation sample">

<html:script> <![CDATA[ var dialogWindow = null; var ioSettings = new Boolean(); // create a newdialog window, passing a couple of named parameters function MakeParamDialog() { var newWin = window.openDialog("resource://res/samples/madedialog.xul", "New", "chrome", {remind:true, prompt:"Give me your money and convertible bonds"}); return newWin; }
// cheesy demonstration that values are being returned function DumpObject(what) { dump("dumping object: " + what + "\n"); for (prop in what) dump(" property '" + prop + "' = '" + what[prop] + "'\n"); dump("dumped.\n"); } ]]> </html:script>

<xul:toolbox> <xul:toolbar> <xul:titledbutton value="Make Dialog" onclick="dialogWindow=MakeParamDialog()" style="background-color:rgb(192,192,192);"/> <xul:titledbutton value="Dump Window" onclick="DumpObject(dialogWindow.arguments[0])" style="background-color:rgb(192,192,192);"/> </xul:toolbar> </xul:toolbox> </xul:window>

Note that only html widgets will have the expected html-specific DOM attributes like "checked" for checkboxes. XUL buttons will respond to their own APIs (to be documented in separate, dedicated papers), as well as to the core DOM interfaces. Generally, as in titledbutton above, attribute names match their HTML counterparts. But see specific widget documentation to be certain.

The above code will produce a live window with a functional button if placed in a file named, perhaps, makedialog.xul in the res/samples subdirectory within the directory containing apprunner. (Placing it in that directory allows it to find the stylesheet xul.css mentioned in the stylesheet processing instruction.) Launch apprunner pointing at that URL to load it into the main window.

apprunner -url resource:/res/samples/makedialog.xul

A suitable dialog description XUL file (named madedialog.xul in the above code) will be loaded when the Make Dialog button is pressed. The following example contains initialization code as mentioned in this document.

The authors have turned a jaundiced eye toward any sense of aesthetics in the design of this dialog. It's ugly. It will show up directly on top of the main "browser" window. I plan to rely on the estimable work of a colleague to provide some documentation for what sorts of visual effects can be accomplished with dialog controls and provide a link to a separate document with prettier samples.


<?xml version="1.0"?>
<?xml-stylesheet href="xul.css" type="text/css"?>
<!DOCTYPE window>
<!-- dialog containing a control requiring initial setup -->
<xul:window
    xmlns:html="http://www.w3.org/1999/xhtml"
    xmlns:xul ="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
    onload = "SetFromParams()"
    title = "Things to do"
    height = "200" width = "300">

  <html:script>
    <![CDATA[
    // Initialize controls from parameters sent through openDialog
  function SetFromParams() {
    // look in arguments[0] for interesting properties and values
    // set checkbox from that, if present
    if (window.arguments && window.arguments[0]) {
      var setting;
      var control;
      // set checkbox from the value of argment[0]'s "value" property
      if (window.arguments[0].remind) {
        setting = window.arguments[0].remind;
        control = document.getElementById("remind");
        if (control)
          if (typeof setting == "boolean")
            control.checked = setting;
          else if (typeof setting == "object")
            control.checked = setting.valueOf();
      }
      // set prompt from the value of argment[0]'s "prompt" property
      if (window.arguments[0].prompt) {
        setting = window.arguments[0].prompt;
        if (typeof setting == "string") {
          control = document.getElementById("prompt");
          if (control) {
            control = control.firstChild;
            if (control && control.nodeType == 3) // TEXT_NODE
              control.data = setting;
          }
        }
      }
    }
  }

  // OK button handler
  // return the setting of the "remind" checkbox in the arguments
  // and then close the window (disabled for now, since that crashes)
  function DoOK() {
    var checkbox = document.getElementById("remind");
    if (checkbox) {
      // if we were given an openDialog parameter, set its value
      if (window.arguments && window.arguments[0])
        window.arguments[0].remind = checkbox.checked;
    }
    // window.close(); (crashes, at time of writing)
  }
  ]]>
  </html:script>

  <html:table>
    <html:tr>
      <html:td html:id="prompt">Give me your money</html:td>
    </html:tr>
    <html:tr>
      <html:td>
        <!-- note the html namespace on the id attribute, which
             seems at this time to be required by getAttribute() -->
        <html:input type="checkbox" html:id="remind"/>Remind me
      </html:td>
    </html:tr>
    <html:tr>
      <html:td>
        <html:button onclick="DoOK()">OK</html:button>
      </html:td>
    </html:tr>
  </html:table>
</xul:window>

Note the window will not be dismissed when the OK button is pressed. The current state of the code will require that you hit "OK" and then the window close box.