Dialogs in Curl and in the Curl Documentation Viewer

The Curl Documentation Viewer can be a bit of a challenge if you lack a Curl book.
Here is a translation of the code docs for showing a Dialog as found in the Dialog (class) item.

show  : Show a dialog in its own window.
public  
{Dialog.show
title:String = {host-localize "Pop-up Window"},
modal?:bool = true,
center?:bool = true,
owner:#View = {View.get-default-owner},
style:DialogStyle = DialogStyle.standard,
large-icon:#Pixmap = null,
small-icon:#Pixmap = null
}:void

The first thing we need is an instance of a Dialog which we can show.
We get that with {Dialog new} or the short-cut, {Dialog}

So we can attempt to execute the documented method in the Curl IDE as

{{Dialog}.show
title = {host-localize "Pop-up Window"},
modal? = true,
center? = true,
style = DialogStyle.standard,
large-icon = null,
small-icon = null
}

You may notice that I have torn out the option for the default view owner when I tore out the type declarations.

But the Dialog is not very promising when you execute it: it is barely visible.
Try this.

{let vbox:VBox = {spaced-vbox width=2in, margin=5pt}}
{{Dialog vbox}.show
title = "Pop-up Window"
}

Now we almost have something like a Dialog to show. Add {text as follows:

{let vbox:VBox = {spaced-vbox width=2in, margin=5pt,
{text "Give us a Dialog to show"}}
}
{{Dialog vbox}.show
title = "Pop-up Window"
}

As my Grandpa would say, "Now you're cooking with gas!"
And hopefully the class-side documentation makes a little more sense to you than it did before.

The expression {Dialog vbox} is not the most common idiom.

More common might be

{let dialogTest:Dialog = {Dialog vbox, border-width = 2pt}}
{dialogTest.show
title = "Pop-up Window",
center? = true
}

And perhaps we should be using

{let dialogTest:Dialog = {Dialog vbox, border-width = 2pt}}
{value
{dialogTest.show
title = "Pop-up Window",
center? = true
}
}

{Dialog vbox} is a curious expression. It can be used because the default constructor for the class Dialog is defined with '...' for rest arguments.
In our case, the 'rest' of the arguments is a VBox. Dialog itself inherits from classes designed to provide functioning for graphics containers and for traversals.

It is curious to note that MessageDialog is not a subclass of Dialog, but a subclass of one branch of the multiple-inheritance tree of Dialog: the class StandardActiveTraversalContainer, which inherits from Frame and thereby BaseFrame which is itself the super class of MessageDisplay, the parent of MessageDialog.

FileDialog may also surprise you: it is not really a class so much as a module ( there is a variant of JavaScript, TiScript, where a Type can also be used in just this way.) It is both abstract and final.

This may be worth noting if you are interested in running Curl outside the Browser in the way that Mozilla XUL applications run outside the browser. In this case sub-applets and multi-applet behavior become important, not Dialogs. In Microsoft Windows, modal Dialogs have a troubling past. They have their counterpart in the MDI 'solution'. It is reassuring that in Curl we will be working with smart Frames and Boxes instead.

See the notes on detached-applets and the use of View. For a minimal detached-applet, you can simply use a CommandButton as follows:

{curl 5.0 applet}
{import * from CURL.GUI.BASE}
{import * from CURL.GUI.CONTROLS}
{View
{CommandButton
label = "&Click Here",
style = "standard",
{on Action at btn:CommandButton do
set btn.label = "Test with a &Click."
}
},
visibility = "normal",
{on WindowClose do
{exit}
}
}

If you are using the IDE, save the file as a detached applet with the .dcurl file extension.

To run a script using

curl.exe -l myscript.xcurl

use

{curl 5.0 script}
{import * from CURL.GUI.BASE}
{import * from CURL.GUI.CONTROLS}
let win:View = {View
{CommandButton
label = "&Click Here",
style = "standard",
{on Action at btn:CommandButton do
set btn.label = "Test with a &Click."
}
},
visibility = "normal",
{on WindowClose do
{exit}
}
}
{win.show}
{event-loop}

If you are using the Curl shell console, you will have to click back into the console after sending >>show in order for Curl to evaluate {event-loop}