S
M
L
D
I
A
L
O
G
S

Tutorial

Building Dialogs in SML

Building
Dialogs in SMLin

TNTmips
TNTedit™
®
TNTview
page 1®

Building Dialogs in SML

Before Getting Started
For complex SML scripts that process multiple input objects and require user
input for numerous parameter settings, consider creating custom dialog windows
to streamline user interaction with the script. You can use two different approaches
to constructing custom dialogs, each of which provides access to all the major
types of dialog controls. This booklet shows you how to construct custom dialogs
and how to use them with an SML script.
Prerequisite Skills This booklet assumes that you have completed the exercises inthe Displaying Geospatial Data, Navigating, and Writing Scripts with SML tutorial booklets. Those exercises introduce essential skills and basic techniques thatare not covered again here. Please consult those booklets and the TNTmips Reference Manual for any review you need.
Sample Data The exercises presented in this booklet use sample data that is dis-tributed with the TNT products. If you do not have access to a TNT products CD,
you can download the data from the MicroImages web site. In particular, thisbooklet uses sample files in the SMLDLG and CB_DATA sample data collections.
More Documentation This booklet is intended only as an introduction to creating

dialog windows in SML scripts. Consult the TNTmips reference manual andespecially the online SML Reference for more information about dialogs using
Motif widgets. The Reference Guide to SML Dialog Specifications in XML isavailable from the MicroImages web site and is also included as an appendix inelectronic versions of this tutorial booklet.
TNTmips and TNTlite® TNTmips comes in two versions: the professional version

and the free TNTlite version. This booklet refers to both versions as “TNTmips.”
If you did not purchase the professional version (which requires a software license key), TNTmips operates in TNTlite mode, which limits object size andenables data sharing only with other copies of TNTlite.
All the exercises can be completed in TNTlite using the sample geodata provided.
Randall B. Smith, Ph.D.,12 June 2003
©MicroImages, Inc., 2003

It may be difficult to identify the important points in some illustrations without acolor copy of this booklet. You can print or read this booklet in color fromMicroImages’ Web site. The Web site is also your source for the newest Tutorial
booklets on other topics. You can download an installation guide, sample data,
and the latest version of TNTlite.
http://www.microimages.com
page 2

Building Dialogs in SML

Welcome to Building Dialogs in SML
You can use the Spatial Manipulation Language(SML) to write many types of custom programs that
operate on the geospatial data objects in your TNT
Project Files. If you are writing a script for a onetime processing operation, the processing parameters
and names of input and output objects and files canbe written explicitly into the script. But any script
you plan to reuse or provide to others should include
interactive dialogs to let the user select objects andenter program parameters.
SML provides several ways for you to include interactive dialogs in your scripts. The Raster, Vector,
CAD, TIN, and File function groups each include
GetInput...() , GetOutput...(), and other functions that
pop up a dialog so the user can select or create objects and files as needed as the script is executed.
The functions in the Popup Dialog group provide
dialogs that prompt the user to enter numeric andother types of parameter values. These functions areeasy to use, but each opens a separate transient dialog window, so a complex processing script might
require a barrage of popup dialogs.
You can make complex scripts
easier to use by creating one
or more custom dialog windows that bring together
object selection and parameter
inputs. Custom dialog windows in SML can include text
and icon pushbuttons, toggle
and radio buttons, text andnumeric fields, labels, menu
buttons, listboxes, and comboboxes, among others.
This booklet provides an introduction to building
custom dialog windows for use in your SML scripts.
It provides many sample dialog scripts and several
complete scripts that incorporate complex custom
dialog windows.

page 3

STEPS; choose Process / SML /Edit Script... from the
TNTmips main menu to
open the Spatial
Manipulation Language
editor window
The two main methods forcreating custom SML dialogs
are outlined on page 4.
Dialog specifications in XML
are introduced on pages 515 with examples of all
avaliable dialog elements.
Pages 16-19 describe how
to set up the script toprocess the dialog
specification and open the
dialog. The optional use of
an XML Editor is discussed
on pages 20-21. Further
techniques for integrating the
dialog with the script are
illustrated on pages 22-27.
Dialogs constructed using
Motif widget classes are
discussed on Pages 28-31.

An example of a custom
dialog window. We will
examine this dialog and its
components in more detailon a later page.

Building Dialogs in SML

Two Types of SML Dialogs
STEPS; choose Insert / Function; press [Function Group...]on the Insert Function
window; select Widget from thescrolled list in the popup
Function Group window,
then press [OK[; scroll through the list of
Widget functions, thenpress [Close]; choose Insert / Class; in the Insert Class
window, scroll down tothe bottom to locate the
Motif widget classes,
which begin with Xm; now scroll up to find thegeneric GUI dialog
classes, which begin
with GUI.
; close the Insert Class
window

A simple dialog via OSF/
Motif classes. OK and
Cancel buttons must be
explicitly coded. Available
only in SML/X.

SML provides two ways for you to create custom
dialog windows for your SML scripts. The older
method uses the Motif widget (dialog component)
set that is used to create all of the windows in the X
Windows versions of the TNT products. You use
SML functions in the Widget function group to create dialog components and set their attributes using
members of the various widget classes (which begin
with the letters Xm). All dialog components (including essential buttons such as OK and Cancel) must
be explicitly created in the script. This method is
not available in SML for Windows (SML/W), but
can be used on any supported computer platform(Windows, MacOS X, UNIX, and Linux) under X
Windows (SML/X).
The newer method for creating custom dialogs lets
you create and arrange dialog components and set
their characteristics using a simple set of tags andattributes in XML-formatted text. The dialog specification can be embedded in the script as a string
variable or read in from an XML file. The dialog
specification is interpreted by SML and mapped to aset of generic dialog classes (each beginning withGUI_) that use dialog components appropriate forthe operating environment. In the X Windows environment (SML/X) the Motif widgets are used, but
in SML/W the dialog is constructed from native Windows components. Essential buttons such as OK,
Apply, and Cancel are supplied automatically. In
most cases this method greatly simplifies the task ofcreating custom dialog windows.
Dialog via an XML dialog
specification using GUI dialog
classes. OK and Cancel
buttons are automaticallyprovided. Available in either
SML/W (left, using native
Windows components) or
SML/X (right, using Motif
components).

page 4

Building Dialogs in SML

A Simple Dialog Specification in XML
Because of their ease of use, we will first focus on
creating dialog specifications in XML. XML makes
use of tags (enclosed between < and > characters) todelimit and identify elements of text data. In an SML
dialog specification in XML, the data elements identified by the tags correspond to specific components
of a dialog window, such as buttons and labels. Tags
occur in pairs, with a start tag and end tag enclosing
the relevant text.
As an example, look at the dialog specification for
the Hello World dialog window shown below. Thiswindow consists of a label element and two
pushbuttons (OK and Cancel, which are supplied
automatically). The two <label> tags enclose andidentify the text to be used for the label on the dialog. Note that start and end tags use the same tag
name, but in the end tag it is preceded by the forward slash ( / ) character.

STEPS; choose File / Open /*.SML File..., navigate to
the SMLDLG directory, andselect GENDLG.SML.
; run the script; when prompted to selectthe dialog specification,
select HELLO.XML in the
SMLDLG directory and click[OK]; compare the dialog
window to its
specification; keep the Hello World
dialog open and proceed
to the next page

Data elements in XML <?xml version="1.0"?>
can be nested inside <root><dialog id="hello" Title="Hello World">
other data elements (in<label>Sample Dialog Window</label>
one or more levels) to </dialog>
indicate membership </root>in a group. This is a good match to the structure of a
dialog window, in which some window components XML, the Extensible Markup
Language, is a genericare contained within other components. In this ex- meta-language that allows
ample the dialog element (which identifies the dialog the creation of structured,window as a whole) contains the label element. The self-describing text. XML
dialog is in turn contained within the root element, supplies a structure andsyntax, but a specific set ofwhich is the required top-level element in any dialog tags and attributes is
specification.
required to define theFor ease of editing and reading a dialog specification, the start and end tags for “container” dialog
elements should be placed on separate text lines, withthe contained elements identified on intervening
lines. Different levels of indents should also be used
to clarify this nested, tree-like structure.

page 5

meaning of the elements in
an XML file. MicroImages
has supplied such a set oftags and attributes to identify
the various types of dialog
components and theirproperties in each particularinstance where they areused.

Building Dialogs in SML

Using Attributes for Tags
STEPS
; examine the attributes
for the elements in the
dialog specification; click [OK] on the Hello
World dialog window to
end the script

To conform to XML format
standards, the dialog
specification should begin
with a standard XML
Declaration specifying theversion of XML.

Start-tags can also include one or more attributes,
which are predefined keywords to which you canassign a value. The assignment has the form:
attribute = “value”

In a dialog specification, each type of dialog component has a predefined set of attributes. Each time
you use that component type, you can assign attributevalues to define the specific properties you want thatcomponent to have. Attribute names are case-sensitive, but you can list attributes in any order within
the start-tag.
Any dialog component can have an id attribute, aunique identifier for that element. The value of an
id attribute can be any character string, but it must
be unique within the dialog. Use an id attribute forthe dialog element and any other element that yourscript needs to access, such as to set or read values.
In the Hello World dialog, the dialog element
has an id attribute thatthe script uses to create
and open the actual dialog window. It also hasa Title attribute that supplies the text for the window
title. The label element in the dialog could also havean id attribute, but here it doesn’t need one. The
label text is simply a static part of the dialog, so there
is no need for the script to have any interactive access to it. Therefore the id attribute is omitted.

<?xml version="1.0"?><root><dialog id="hello" Title="Hello World"><label>Sample Dialog Window</label></dialog></root>In order for SML to correctlyinterpret the dialog
specification, it must follow
the simple syntax rules thatdefine a well-formed XML
document:z every element must haveboth start and end tagsz all attribute values must
be in quotesz elements may notoverlap

In the next few pages we will examine several additional dialog windows and their specifications in
XML to illustrate the use of other dialog components.
We will then discuss methods for using a dialog specification with an SML script and how a script
communicates with the dialog window.

page 6

Building Dialogs in SML

Togglebuttons and Empty Tags
The Extraction Options sample dialog window has
a label and three togglebuttons. Each of these components is represented by an element within the
dialog element in the dialog specification. Note thatthese components are laid out from top to bottom inthe window, rather than from left to right. This is
the default layout order for components in a dialog.
Later we will see how you can control the layout
orientation.
Each togglebutton element in this example has three
attributes: id, Name, and Selected. The id attributeis needed so that the SML script can find out
whether each togglebutton has been set or not. The
Name attribute specifies text for the label that is
automatically placed to the right of the button. The
Selected attribute lets you set the default state foreach button when the dialog window opens. The
button is pushed in (on) if you set Selected = “true”
and pushed out (off) if you set Selected = “false”.

STEPS; run the GENDLG scriptagain; when prompted to selectthe dialog specification,
select TIGEROP.XML in the
SMLDLG directory and click[OK]; compare the dialog
window to its
specification; click [OK] on the
Extraction Options dialog
window to end the script<?xml version="1.0"?><root><dialog id="tigerop" Title="Extraction Options"><label>Extract from TIGER:</label><togglebutton id="citybtn" Name="City Polygons"
Selected="true"/><togglebutton id="votebtn" Name="Voting Districts"
Selected="false"/><togglebutton id="congbtn" Name="Congressional Districts"
Selected="false"/></dialog></root>Note that all of the information required to set up a
togglebutton is included in the start tag name and its
attributes. Unlike the label element, there is no othertext to be enclosed by separate start and end tags. In
this case the two tags can be combined into a single
empty tag. The slash character ( / ) that normally
begins an end tag is placed before the closing > character of an empty tag.

page 7The dialog specifications
shown in this booklet arecolor-coded for ease ofreading. Standard XML
formatting characters are inblue, tag names are in purple
or red, attribute keywords
are in green, and attributevalues and other text are inblack.

Building Dialogs in SML

Combobox and Items
STEPS; run the GENDLG scriptagain; when prompted to selectthe dialog specification,
select SELCOMP.XML in the
SMLDLG directory and click[OK]; compare the dialog
window to its
specification; click [OK] on the SelectComposite dialog
window to end the script

The Select Composite sample dialog window includes a label and a type of menu control called acombobox. A recessed box resembling an editabletext field shows the current menu selection, and asmall icon at the right side of the control is used todrop down the menu choices.
The possible selections for any menu-type control(combobox, listbox, and menubutton) are created ina dialog specification by adding item elements within
the parent control element. In this example the
combobox control element includes three item elements that specify different types of color composite
raster. An item element resembles a label element inthat its start and end tags enclose the text for themenu entry. However, an item element also has a
Value attribute. The text string you assign to this
attribute becomes the “value” of the combobox control when that menu item is selected. Each item in amenu control therefore should have a different character string assigned for its value. The item value
strings in this example are numbers corresponding
to the bit-depths of the composites.

Menu-type controls that show the selected menu item
(combobox and listbox) have a Default attribute thatyou can use to indicate which item should be the
You can use the TNTmips
Text File Editor or any otherdefault selection. Simply assign that item’s value
text editor to open andstring as the value of the Default attribute. As an
examine the dialog
alternative,
you can use the item attribute Selected,
specification XML files usedwhichiseither“true” or “false”. If Selected=“true”,
in these exercises.
that item is initially selected (overriding the Default
attribute of<?xml version="1.0"?><root>
the parent<dialog id="selcomp" Title="Select Composite"> control, if<label>Select Composite Type:</label>any).
<combobox id="comptype" Default="24"><item Value="24">24-bit composite</item><item Value="16">16-bit composite</item><item Value="8">8-bit composite</item></combobox></dialog></root>page 8

Building Dialogs in SMLRadiogroup and Groupbox
The Select Process sample dialog window includes
a hybrid type of control called a radiogroup. A
radiogroup is a group of small buttons (resembling
togglebuttons) in which only one button can be turnedon at a time. Turning on one button automaticallyturns off any other button that was previously turned
on. So a radiogroup functions like a menu in which
all selections are constantly visible.
The specification for a radiogroup has the same structure as the other menu-type controls. The item
elements inside the radiogroup element provide thenames for the buttons (analagous to the entries in amenu) and the value for the control when that button
is turned on. This example shows an alternative
method for specifying the text string for a menu item.
In the example on the previous page, the item namewas provided as text between start and end tags. In
the Select Process dialog, the items are specified
using empty tags with a Name attribute. Either
method can be used for any menu-type control.
This dialog also includes a groupbox, a simple rectangular frame around one or more other controls,
which can also be automatically provided with a label inside the top edge using a Name attribute. A
groupbox is one type of layout component in a dialog. A layout component does not provide any
program control, but merely aids in the layout of the
dialog window. Other layout components are shownin later sample dialogs.

STEPS; run the GENDLG scriptagain; when prompted to selectthe dialog specification,
select RADIOGP.XML in the
SMLDLG directory and click[OK]; compare the dialog
window to its
specification; click [OK] on the SelectProcess dialog window
to end the script

In the sample dialog
specifications in this booklet,tags for control components
are shown in red and tags
for layout and main-level
dialog elements are shownin purple.

<?xml version="1.0"?><root><dialog id="radiogp" Title="Select Process"><groupbox Name=" Process: " ExtraBorder="4"><radiogroup id="processgp" Default="entire"><item Value="entire" Name="Entire Scene"/><item Value="polygon" Name="AOI Polygon"/><item Value="manual" Name="Manual Selection"/></radiogroup></groupbox></dialog></root>page 9Building Dialogs in SML

Numeric Fields and Layout Panes
STEPS; run the GENDLG scriptagain; when prompted to selectthe dialog specification,
select TIGRDS.XML in the
SMLDLG directory and click[OK]; compare the dialog
window to its
specification; click [OK] on the TIGER
Road Options dialog
window to end the script

An invisible layout pane withhorizontal orientation
contains these dialog
components.

The TIGER Road Options sample dialog window
introduces the layout element you will probably use
most often, the pane. A layout pane is simply aninvisible container in which you can place multiple
dialog components and control their arrangement.
The most important attribute of a pane element isOrientation, which can be either “horizontal” or “vertical”. The three components near the bottom of this
dialog window (two labels surrounding an editablenumeric field) are placed within a pane with horizontal orientation, so the components are arranged
in order from left to right across the pane. If
the pane orientation is set to “vertical”, the elements within the pane are arranged from top tobottom.
The numeric field is created using an
editnumber element in the dialog specification.
The Width attribute sets the width in typicalcharacters, while the Precision attribute sets thenumber of digits after the decimal point (the default
is 6). The Default and MinVal attributes set the value
initially displayed in the field and the minimum allowed value, respectively. There also an available
MaxVal attribute to set the maximum allowed value.
This control has no built-in label, so the dialog uses
a label element to the left of the field to label its
purpose and another to the right to identify the units.

<?xml version="1.0"?><root><dialog id="tigrds" Title="TIGER Road Options"><label>Road processing options:</label><togglebutton id="getrds" Name="Extract Road Lines"/><togglebutton id="mkbuf" Name="Make Roads Buffer Zone"/><pane Orientation="horizontal"><label>Buffer Distance:</label><editnumber id="buffdist" Width="4" Precision="0"
Default="100" MinVal="0"/><label>meters</label></pane></dialog></root>page 10

Building Dialogs in SML

Pushbuttons and Listbox
The Languages sample dialog window illustrates theuse of pushbuttons and a listbox. The upper pane ofthe dialog includes two pushbuttons, one with a text
label and one with an icon. Use the Name attributefor the pushbutton tag to specify the text for the button label or the Icon attribute to specify the name of
the icon to be used. The icon name must match an
iconid listed in the internal TNT reference files. To
see a complete list of the valid iconids, open the Insert Class window from the SML editor and selectthe GUI_CTRL_TOGGLEBUTTON class. The
valid iconid values are listed under the iconid parameter of the CreateIcon() class method.

STEPS; run the GENDLG scriptagain; when prompted to selectthe dialog specification,
select LANGUAGE.XML in the
SMLDLG directory and click[OK]; select several languages
in the listbox; compare the dialog
window to its
specification; click [OK] on the
Languages dialog
window to end the script

A listbox provides a list of selectable items. If thevalue for the Height attribute is less than the numberof items, the box is provided with a vertical scrollbar.
A listbox can be set to allow the selection of morethan one of its items by using the SelectStyle attribute.
The default value “single” for this attribute permits
only one item to be selected at a time. The value“multi” used in this dialog specification allows theuser to select multiple entries by simply clicking oneach one (clicking on an already-selected item toggles
it off). The value “extended” allows Windows-style
item selection by using the mouse with the SHIFTor CTRL key.
<?xml version="1.0"?><root><dialog id="language" Title="Languages"><pane Orientation="horizontal"><pushbutton id="dict" Name="Dictionary..."/><pushbutton id="file" Icon="CREATE_FILE"/></pane><label>Select languages:</label><listbox id="language" Height="4" SelectStyle="multi"><item Value="english" Selected="true">English</item><item Value="french">French</item><item Value="spanish">Spanish</item><item Value="japanese">Japanese</item><item Value="german">German</item></listbox></dialog></root>page 11

Building Dialogs in SML

Menubuttons
STEPS; run the GENDLG scriptagain; when prompted to selectthe dialog specification,
select PROCPTS.XML in the
SMLDLG directory and click[OK]; click on the two menu
buttons in the upper partof the dialog window; compare the dialog
window to its
specification; click [OK] on theProcess Selected Points
dialog window to end thescriptA dialog window can also include menubuttons, buttons that drop down a selection menu when pressed.
Like a pushbutton, a menubutton can have either an
icon or a static text label. Since a menubutton has
no way of showing which item is currently selected,
it is best used to launch one of several alternative
actions from the dialog.
The Process Selected Point sample dialog might beused with a Tool Script that allows the user to selectpoints in a View window. It has two menubuttons,
one with an icon and one with a label. The two
menubuttons are inside a horizontal pane so they
appear side by side in the dialog window. Like othermenu controls, selections for a menubutton are registered using items within the menubutton element.
When you use an icon for a pushbutton, togglebutton,
or menubutton, you can use the ToolTip attribute to
set the text to be shown in the popup ToolTip whenthe mouse cursor hovers overthe icon.

<?xml version="1.0"?><root><dialog id="procpts" Title="Process Selected Points"><pane Orientation="horizontal"><menubutton id="file" Icon="DESKTOP_FILE"
ToolTip="Text File..."><item Value="open">Open Text File</item><item Value="close">Close Text File</item></menubutton><menubutton id="ptaction" Name="Point Action..."><item Value="save">Save Coordinates to Text File</item><item Value="buffer">Compute Buffer Zone</item><item Value="polygon">Find Enclosing Polygon</item></menubutton></pane></dialog></root>page 12

Building Dialogs in SML

Edittext and Colorbutton
The Name and Color sample dialog window shows
two additional types of controls, an edittext and acolorbutton. An edittext control allows the user toenter and/or edit a text string. The MaxLength attribute specifies the maximum allowed length of thestring in characters, while the Width attribute specifies the width of the editable field (in “typical”
characters). Text is aligned to the left side of the
field by default. To right-align the text, use the Justify attribute with the value “right”. The edittext
control does not have a built-in label.

STEPS; run the GENDLG scriptagain; when prompted to selectthe dialog specification,
select NMCOLOR.XML in the
SMLDLG directory and click[OK]; compare the dialog
window to its
specification; click [OK] on the Name
and Color dialog window
to end the script

Pressing the colorbutton control opens a standard
Color Editor window to allow the selection of a color

from a palette or by specifying
RGB, HIS or other color values. The selected color isshown on the colorbutton after the selection dialog
is closed. The selected color is maintained in a
COLOR class structure as red, green, and blue values (each 0 to 100) and an optional transparency value(also 0 to 100). The colorbutton control does nothave a built-in label.
<?xml version="1.0"?><root><dialog Title="Name and Color" id="nmcolor"><pane Orientation="horizontal"><label>Enter Name:</label><edittext id="name" MaxLength="10" Width="10"/></pane><pane Orientation="horizontal"><label>Choose Color:</label><colorbutton id="colorbtn" AllowTransparent="true"/></pane></dialog></root>page 13

Building Dialogs in SML

Using Tabbed Pages
STEPS; run the GENDLG scriptagain; when prompted to selectthe dialog specification,
select FLOWPATH.XML in the
SMLDLG directory and click[OK]; click on each of thepanel tabs to examine
the included controls; compare the dialog
window to its
specification; click [OK] on the Flow
Path and Buffer Zone
dialog window to end thescriptThe FLOWPATH tool script
performs watershed analysis
operations on an elevation
model shown in a View
window, using seed points
placed in the window
interactively by the point tool
invoked by the script.

If you are creating a dialog window with many controls, you can group controls together on separate
tabbed panels. To do so, you first create a book element and create one or more page elements inside it.
Each page element corresponds to a tabbed panel.
The Name attribute value that you assign for eachpage provides the text that is placed on the panel’stab. Controls can be placed and arranged within apage just as in the main dialog or in any layout element.
The Flowpath sample dialog provides an example
based on the control dialog for the Flowpath script,
one of the sample tool scripts distributed with
TNTmips. The two panels of this dialog are illustrated below, and the dialog specification is shownon the facing page. This dialog places the book oftabbed pages immediately inside the dialog element,
but the book could be placed inside any layout element (except directly inside another book element).
One page includes a number of different types ofcontrols for general toolscript operations, while theother page provides a set of colorbuttons to designate colors for different vector overlays created by
the script.

page 14

Building Dialogs in SML

Specification for Flowpath Dialog<?xml version="1.0"?><!DOCTYPE root SYSTEM “smlforms.dtd”><root><dialog id="flowpath" Title="Flow Path and Buffer Zone"><book><page Name="Controls"><pane Orientation="horizontal"><pushbutton Name="Save" Icon="FILE_SAVE"
ToolTip="Save Output Layers..."/><pushbutton Name="Remove" Icon="CONTROL_SUBTRACT_CYAN"
ToolTip="Remove Output Layers"/><pushbutton Name="Number of Seedpoints..."/></pane><pane Orientation="vertical"><togglebutton id="btnSnap" Name="Move Seed Point toFlow Path" Selected="false"/><togglebutton id="btnFlow" Name="Compute Flow Path"
Selected="true"/><togglebutton id="btnBasin" Name="Compute Upstream
Basin" Selected="true"/><togglebutton id="btnBuffer" Name="Compute Buffer Zone"
Selected="false"/></pane><pane Orientation="horizontal"><label>Buffer Distance: </label><editnumber id="buffDist" Width="5" Default="100"Precision="0" MinVal="0"/></pane></page><page Name="Colors" Orientation="vertical"><pane Orientation="horizontal"><colorbutton id="fcolor"/><label> Flow path color</label></pane><pane Orientation="horizontal"><colorbutton id="bacolor"/><label> Basin color</label></pane><pane Orientation="horizontal"><colorbutton id="bucolor"/><label> Buffer zone color</label></pane><pane Orientation="horizontal"><colorbutton id="bocolor"/><label> Extents box color</label></pane></page></book></dialog></root>page 15

Building Dialogs in SML

Using an XML Dialog Specification
STEPS; choose File / Open /*.SML File... from the
SML editor window; select HELLOXML1.SML fromthe SMLDLG directory; examine the script; repeat, but this time
select HELLOXML2.SML fromthe SMLDLG directory; run the second script; press [OK] on the Hello
World sample dialog
window to end the script

Now that we have introduced the components of a
dialog and the structure of the dialog specification,
we can begin to examine how to use a specification
with an SML script. The dialog specification must
be read and interpreted when the script is run to create an XML document structure in memory. This
structure is an instance of the class XMLDOC. The
specification can either be in a separate file or embedded in the script. Different XMLDOC classmethods are used in these two situations to ingest
the specification and assign it to the class instance.
The two scripts for this exercise implement the Hello
World sample dialog and illustrate these two approaches (script excerpts below).

Script helloXML1.sml ingests the specification froma separate file in the same directory using thestring xmlfile$;
Read(xmlfile$) classxmlfile$ = _context.ScriptDir + "/hello.xml";
method in XMLDOC.
This method reads the file and parses the text toclass XMLDOC dlgdoc;
dlgdoc.Read(xmlfile$); create the XML structure in memory. The filename
passed to the Read() method must include the full
directory path to the file as well as the file extension.
The filename string is constructed in this example
by a string expression using the script’s CONTEXT
class structure. The class member _context.ScriptDirprovides the path to the directory containing the current SML script. The string expression concatenates
the path with the name of the file.
# helloXML1.sml

The sample script helloXML2.sml has the dialog
specification embedded within it, assigned to a string
string xml$;
xml$='<?xml version="1.0"?> variable. Note the single quotation marks en<root>
closing the specification,<dialog id = "hello" title="Hello World"> which enable multiple<label>Sample Dialog Window</label>lines of text to be used</dialog>
within the assignment statement. The string vari</root>';
able is then passed to the XMLDOC class methodclass XMLDOC dlgdoc;
Parse(xml$), which interprets the text and creates
dlgdoc.Parse(xml$);
the XMLDOC class instance in memory.
# helloXML2.sml

page 16

Building Dialogs in SML

Creating and Opening the Dialog Window
The XML structure created in memory by the Read()or Parse() method of class XMLDOC contains all of
the elements in the dialog specification in a hierarchical, tree-like structure. Each element, including
the dialog element itself, can also be thought of as a“node” in the structure. To create and open the dialog window, your SML script must retrieve the dialog
node from the parsed XML document structure andidentify it as the source for the dialog window.

STEPS; examine the second halfof the HELLOXML2.SML
script

The two scripts you ran on the previous page differ A modal dialog window
only in how they ingest the dialog specification; the created using an XML
specification is automaticallysecond half of each (excerpted below) is identical, provided with OK andand implements the steps outlined above. The dia- Cancel buttons.
log node in the Hello World specification has theunique id attribute “hello” that can be used to retrieve it. This is done usingclass XMLNODE dlgnode;
the XMLDOC class method dlgnode = dlgdoc.GetElementByID("hello");
GetElementByID(), which
returns an instance of class class GUI_DLG dlgwin;
XMLNODE. This is the dlgwin.SetXMLNode(dlgnode);
dlgwin.DoModal();class that represents any
given node in a parsed XML document. In this script
the dialog node is represented by the class variable
dlgnode.
The dialog window itself is an instance of class
GUI_DLG, represented in this script by class variable dlgwin. The class method SetXMLNode() inclass GUI_DLG is used to identify the dialog nodein the XML structure as the source for the dialog
window. The final script statement uses the
GUI_DLG class method DoModal() to create andopen the dialog window. This method opens thewindow as a modal dialog, meaning that the dialog
takes control and does not allow any other parts ofthe script to be executed until the dialog is closed.
Modal dialogs are the most appropriate form for most
SML applications.

page 17

Nonmodal dialogs allow
other program operations
and user interactions tocontinue while they are
open, but require explicit
management by the script. A
nonmodal dialog window is
automatically provided with
Apply and Close buttons.
Two GUI_DLG classmethods are used to create
and then open a nonmodal
dialog: CreateModeless()and Open().

Building Dialogs in SML

Trapping XML Errors
STEPS; choose File / Open /*.SML File... and select
XMLERRS1.SML from the
SMLDLG directory; run the script; note that itends without opening the
dialog but does notreport any errors; choose File / Openagain, and select
XMLERRS2.SML; in the Message windowthat opens, press the
Details button; press the [OK] button on
both Message windows
to end the script

In order for SML to interpret a dialog specification
correctly, the specification must be well-formed,
meaning that it uses the proper notation for tags andattributes and has the nested structure expected of
an XML document. The syntax of the dialog specification is checked by the Read() or Parse() classmethod when the script is run, but XML syntax errors are not automatically reported to you by SML.
The excerpt of script xmlerrs2.sml below shows how
you can get an XML syntax error report.

The Read() and Parse() class methods return a numeric value that is an error code (a negative value) if
there are XML syntax errors or 0 if there are no errors. The sample script assigns the returned value toa numeric variable errXML, then checks the value ofnumeric errXML;
the variable. If errXML is less than 0, the error value
class XMLDOC dlgdoc;
is passed to the PopupError() function,
errXML = dlgdoc.Read(xmlfile$);which opens a Message window reportif (errXML < 0) {ing that there is an XML syntax error. If you press
PopupError(errXML);the Details button on this window, a second mesExit();sage window opens and lists the errors.
}

The specification read by thetwo sample scripts in this exercise (excerpted below) is acopy of the groupbox/radiobox
dialog specification described previously, but theclosing double quotation
mark is omitted for the
Value attribute value in thethird radiogroup item. Subs e q u e n t<radiogroup id="processgp" Default="entire">
portions of the<item Value="entire" Name="Entire Scene"/><item Value="polygon" Name="AOI Polygon"/>specification<item Value="manual Name="Manual Selection"/> cannot be in</radiogroup>
terpreted
The closing quotation markcorrectly, triggering a number of error listings in theis missing for the Value
details message window.
attribute.

page 18

Building Dialogs in SML

Trapping Dialog ID Errors
Even if the dialog specification is well-formed XML,
there may be errors in the use or spelling of attributenames and values that cause the layout of the dialog
to be incorrect. Most such errors are not detected orreported when the dialog specification is interpretedby SML. If you are using the SML editor or a text
editor to create the dialog specification, you shouldcarefully examine the spelling and use of attributenames and values to ensure that they are consistent
within the specification and script and that they conform to the usage rules outlined in the Reference
Guide to SML Dialog Specifications in XML. The
Guide lists the attributes that are predefined for use
with each dialog element. Valid values are also listed
for those attributes that have a fixed set of possible
values.

STEPS; choose File / Open /*.SML File... and select
XMLERRS3.SML from the
SMLDLG directory; run the script; note theerror message thatappears; press [OK] on themessage window to end
the script
The Reference Guide to
SML Dialog Specifications in
XML is available from theMicroImages web site and isappended to electronic
versions of this booklet.

<?xml version="1.0"?>

Problems with at- <root><dialog id="dlg" Title="Select Process">
tribute names may
also prevent the dialog
from opening at all. In the example used for this The dialog id attribute value
in the specification does not
exercise, the dialog element id values in the dialog match the id value expected
specification and the SML script do not match. The by the script.
class XMLNODE dlgnode;
dlgnode = dlgdoc.GetElementByID("radiogp");
if (dlgnode == 0) {PopupMessage("Could not find dialog node in XML document");}

script excerpt shown here illustrates how
the script can check for this condition. The
GetElementByID() method in class
XMLDOC returns a valid instance of class
XMLNODE if the specified dialog id isfound. If it is not, the class instance returned is empty.
In SML an empty class instance can be represented
by the numeric value 0. The script excerpt compares
the returned class to 0 and if the comparison is true
it opens a message window stating that the dialog
node was not found.
page 19

Performing a manual syntax
check from the SML editor
window (Syntax / Check...)does not evaluate the XML
syntax of any embedded orreferenced dialog
specification.

Building Dialogs in SML

Using an XML Editor
You can create embedded dialog specifications directly with the SML editor or
create separate dialog specification files with any text editor. But you may find it
easier to create your specifications using a specialized XML editor. A number of
free, shareware, and commercial XML editors are available for download via theWorld Wide Web. Nearly all XML editors can check that the XML is well-formed,
and many provide a graphical Tree View of the document structure that simplifies
editing. Some editors can compare the XML to a document model that specifies
the available tags, their allowed attributes, and the relationships permitted between elements (for example, the only allowed child element of a <combobox> is
an <item>). An XML file that conforms to its document model is said to be valid,
and the checking procedure is called validation. The most widely-supported formof XML document model is a Document Type Definition (DTD). MicroImages
has created a DTD for dialog specifications (smlforms.dtd) that can be found in
the SMLDLG directory. An excerpt of this file is shown below.
<!-- SMLFORMS DTD Version 1.0 --><!-- For use with SML Dialog Specifications in XML --><!-- MicroImages, Inc. -->Excerpt showing<!-- ======================================= --><!-MAIN ELEMENTS--><!-- ======================================= -->the beginning linesof the SMLFORMS
DTD file, defining
the main elements<root>, <script>,and <dialog>.

<!ELEMENT root (dialog | script)* ><!ELEMENT script (#PCDATA)><!ELEMENT dialog (book | pane | groupbox | label | pushbutton |togglebutton | colorbutton | edittext | editnumber | radiogroup |combobox | menubutton | listbox )*>MicroImages has also provided a Dialog Specification Template File (dlgtempl.xml,
shown below) that you can open in a validating XML editor to create your dialog
specifications. The template includes the <root> and <dialog> elements precededby a Document Type Declaration that defines the name of the root element (<root>)and the name of the DTD and its location (in the same directory as the XML file
being edited). Most validating XML editors read the DTD and provide menus ofvalid elements that can be inserted into the current element, menus of attributes
available to be added for<?xml version="1.0"?>
each type of element, and<!DOCTYPE root SYSTEM "smlforms.dtd">menus of attribute values<root>
Dialog Specification Template File<dialog>
for those attributes that
(dlgtempl.xml) containing the</dialog>
have a fixed set of valid
Document Type Declaration and</root><root> and <dialog> elements.
values.

page 20

Building Dialogs in SML

An Example of a Validating XML Editor
Xerlin is a free, open-source
XML editor that is available fordownload at www.xerlin.com. It
is written in Java and will run on
any computer platform that has
the Java 2 runtime environment
installed (Java SDK 1.2.2 orhigher, available for free download from java.sun.com/j2se/).
Xerlin allows you to easily create a valid dialog specification
using the SML dialog specification DTD. It provides a tree viewthat allows you to select dialog
elements with the mouse and editor add elements to the selected
one using the right mouse button.
When you are adding an element,
the Add option provides asubmenu showing
all dialog elementsthat are valid aschildren of the selected element.
The available attributes for theselected element
are listed in theright-hand panelof the window.
Attribute values
can be filled in as
needed or selectedfrom dropdown
combobox-stylemenus.

Tree view of
dialog specification.
Xerlin editor withthe dialog template
file loaded. Dialog
elements can be

added or editedusing rightmouse button
menus.

Xerlin editor with the Flowpath dialog specification
loaded. Available attributes are listed for theselected element on the panel to the right.

Menu of valid
values for the
HorizResize
attribute.

Another free, validating, Java-based XML editor that works well is XMLmind Standard
Edition, available for download from www.xmlmind.com/xmleditor.

page 21

Building Dialogs in SML

Using Callbacks
STEPS; choose File / Open /*.SML File... and selectBONJOUR1.SML from the
SMLDLG directory; run the script; select a language fromthe listbox; a translation of “Hello!” isprinted to the Console
window in the selectedlanguage; repeat using a different
language; examine the callback
procedure in the script; press [OK] on the
Bonjour! sample dialog
window to end the script

You can also program controls in a custom dialog
window to initiate actions through the use of callbacks, which are pointers to procedures or functions
defined in the script. Each type of control element
in a dialog (including the dialog element itself) canhave one or more types of callback, each of which isa predefined attribute of the control’s tag in the dialog specification. Each callback type is activated(called back) by the control in response to a specificcircumstance, and the callback attribute is named toindicate that circumstance. For example, editnumber
and edittext controls can each have an OnChanged
callback (invoked when the control value is changed)
and an OnActivate callback (invoked when the userpresses [Enter] with the cursor in the edit control.
Callbacks can be used to change the state of othercontrols in the dialog or to perform specific operations on data being processed.
In this example, the OnChangeSelection callback forthe listbox control calls a script procedure[SayHello()] that prints “Hello!” to the console window in the selected language when the listbox
selection changes. The OnOpen callback for the dialog window points to the same procedure so that thedefault language (French) is used to print “Bonjour!”when the dialog first opens. The first part of the
dialog specification, which includes the callback attribute assignments (circled), is shown below.

<?xml version="1.0"?><!DOCTYPE root SYSTEM "smlforms.dtd"><root><dialog id="hello" Title="Bonjour!" OnOpen="SayHello()"><pane><groupbox Name="Language" ExtraBorder="4"><listbox id="listbox" SelectStyle="single" Height="3"
Default="French" OnChangeSelection="SayHello()">

NOTE: The predefined callback attributes available for each dialog control andthe circumstances under which each is activated are described in the Reference
Guide to SML Dialog Specifications in XML.
page 22

Building Dialogs in SML

Getting Values from the Dialog
One main role of a dialog window is to record parameter choices and values for later use by the SML
script. The script for this exercise shows several different methods you can use to get values and settingsfrom a dialog window, in this case from the TIGER
Road Options dialog described on a previous page.
When you press OK, a procedure assigned to the
dialog’s OnOK callback prints the control value settings to the SML console window. The settings are
retrieved in four different ways that are describedbriefly below.
The first approach gets all of the dialog control settings at once using the GetValues() class method inclass GUI_DLG (the dialog window class). The values are returned as an instance of class
GUI_FORMDATA, which you must have previously
declared. You can then use GetValueNum() and
GetValueStr() methods in the latter class to read out
the stored values (as a number or as a string, respectively) as needed.

STEPS; choose File / Open /*.SML File... and selectGETDATA.SML from the
SMLDLG directory; run the script; in the TIGER Road
Options dialog, set theRoad processing options
and edit the Buffer
Distance field, then pressOK; note the dialog values
printed to the SML
Console Window; examine the script
examples of the four
methods of reading
values from the dialog; press [OK] on the TIGER
Road Options sample
dialog window to end thescriptThe second approach uses methods in class
GUI_DLG to get the value for each control fromthe dialog individually using the control’s id:
GetCtrlValueNum(id) and GetCtrlValueStr(id).
The third and fourth approaches use the
GetCtrlByID(id) method in class GUI_DLG to
get a handle for each control, then a GetValue(),
GetSelected(), or othersimilar method from the individual control class to get
the control’s setting. The
control handle can be stored as a control class instance that is then used to get the setting, or the
methods to get the control handle and its value canbe strung together, omitting the control handle classvariable (a more compact but perhaps less obvious
approach).
page 23

Settings for modal dialog
windows should be retrievedby callback procedures forindividual controls or by the
dialog’s OnOK callback
procedure.

Building Dialogs in SML

Using the Script Tag
STEPS; choose File / Open /*.SML File... and selectBONJOUR2.SML from the
SMLDLG directory; runt the script as you didin the last exercise

The SML code executed by a dialog’s callbacks canreside in the main SML script (as in the previous
exercise), or within the dialog specification file itself. The <script> element in a dialog specification
is defined as a container for SML code. This is amain-level element within the root element of the
file. The <script> element can include the code forone or more callback procedures. Any global variables or functions you define in the main SML script
are also available for use by the code in the dialog
specification’s <script> element.
The example in this exercise uses the same dialog as
the preceding exercise. The only difference here isthat the SayHello() procedure is in the <script> element of the dialog specification (excerpted below).

<?xml version="1.0"?><!DOCTYPE root SYSTEM "smlforms.dtd"><root><dialog id="hello" Title="Bonjour" OnOpen="SayHello()">... [layout and control specifications omitted] ...
</dialog><script>
beginning CDATA delimiter<![CDATA[
proc SayHello () {clear();
local string language$;
language$ = dlg.GetCtrlValueStr("listbox");if ( language$ == "English" ) thenprint("Hello!");else if ( language$ == "French" ) thenprint("Bonjour!");else if ( language$ == "German" ) thenprint("Hallo!");else if ( language$ == "Spanish") thenprint("Hola!");}ending CDATA delimiter]]></script></root>page 24

The SML code for yourcallbacks might containcharacters (such as <, >,and &) that have special
significance in XML
syntax. For this reason
the SML code should be
enclosed within CDATA
delimiters as shown. They
tell the XML parser that theenclosed section shouldbe treated as regular text(“character data”) thatshould not be interpretedwith XML syntax rules.

Building Dialogs in SML

Changing Control Settings in Callbacks
You can also use callbacks to show the results ofcomputations in the dialog and to change the statusof other dialog controls. The script for this exercise
performs area unit conversions using a value youenter in an editnumber control and input and output
units you select from combobox controls. The output area is computed and shown in an edittext control
when you press the [OK] button. The edittext is set
to be read-only, which disables manual editing of
the output value. When you enter a new input areaor select different area units, callbacks for those controls clear the output edittext control.
You can change control settings using class methods in either the dialog window’s class (an instanceof GUI_DLG) or the individual control classes. The
OnOK callback function for this dialog window[called Recalculate()] uses the method
SetCtrlValueStr(id) in class
GUI_DLG to set the value
for the output area edittext
control. The callback procedures for the input area
editnumber control and thetwo combox controls use the ClearValue() method
in class GUI_CTRL_EDIT_STRING to blank theedittext control when you change any of the othercontrol settings.

STEPS; choose File / Open /*.SML File... and selectAREACALC.SML from the
SMLDLG directory; examine the procedureand function definitionsin the script; run the script; enter an area value inthe upper numeric field; select input and output
area units from the
combobox controls; press [OK] to computethe output area
; when you are finished,press [Cancel] to closethe dialog and exit the
scriptThe AREACALC script also
prints the output units, scale
factor for the units
conversion, and the output
area value to the Console
Window.

In order to force the Area Unit Conversion window
to stay open after the OK button is pressed, the OnOK
callback for the dialog element is defined in the script
as a function that returns the value 0 (after its otheroperations are complete). In addition, the attributeassignment for the OnOK callback in the dialog specification <?xml version="1.0" encoding="UTF-8"?><!DOCTYPE root SYSTEM "smlforms.dtd">must have the keyword “return” <root>
preceding the function name, as<dialog id="areacalc"
Title="Area Unit Conversion"
shown in the excerpt to the
OnOK="return Recalculate()">right.

page 25

Building Dialogs in SML

Managing a Complex Dialog Window
STEPS; choose File / Open /*.SML File... and select
PANSHARPCOMP.SML fromthe SMLDLG directory; run the script; in the Make PanSharpened Color
Composite window,
press [Red...]; use the Select Object
dialog to navigate into
the BIGPINE Project File in
the SMLDLG directory andselect raster BAND_3; press [Green...] andselect raster BAND_2; press [Blue...] and selectraster BAND_1; press [Pan...] and selectraster BAND_8; choose a Color Blending
Mode and a Composite
Type; press [OK] to name an
output color composite
raster and run theprocess; examine the script

The script in this exercise provides an example of afully-functioning processing script that creates a relatively complex custom dialog window to manage its
inputs. The script creates a pan-sharpened colorcomposite raster from three bands of a multispectral
image and a higher-resolution panchromatic(grayscale) image, each of which is selected using a
pushbutton. Read-only edittext controls are used toshow the file and object names for each of the selected input objects. The dialog provides
togglebuttons that allow you to apply a saved contrast table (if present) to each input raster, a listbox
to select from three color blending modes, and acombobox to choose the bit-depth of the output color
composite.
The dialog specification for the Make Pan-Sharpened Color Composite window is embedded in the
SML script. The dialog controls and their callbacks
are designed to lead the user through the controls inproper sequence. Only the Red... and Cancel buttons are intially active. (The dialog specification
sets an Enabled attribute to 0 for the Green..., Blue...,and Pan... pushbuttons and for all of the Apply Contrast toggle buttons so thatthese controls are initiallydimmed and disabled. An
OnOpen callback for the dialog window disables the OK
button when the window first
opens.) The OnPressed callback for the Red... pushbutton
enables its Apply Contrast
toggle button as well as theGreen... pushbutton. Pressing each successive input raster button activates the next one, until pressing
the Pan button activates the dialog’s OK button.

page 26

Building Dialogs in SML

Dynamically Adding Dialog Components
The script in this exercise is designed to modify cellvalues in a set of multispectral image bands to suppress the contribution of vegetation. Most processing
parameters are set on the main dialog window (shown
below). However, each band to be processed mustalso be corrected for additive brightness effects ofatmospheric haze by subtracting a “dark pixel value”(determined by the user) from each cell value. These
values are set using a second dialog opened by the
OnPressed callback procedure [SetDP()] for the Set
dark pixel values... pushbutton. The Set Dark Pixel
Values window lists the bands (filename and objectname) and provides an editnumber field showing adefault dark pixel value (the minimum cell value forthe raster). The tricky part is that the number andselection of bands to be processed can vary.
The SetDP() procedure includes only a skeletal dialog specification with the dialog title, labels at thetop, and the groupbox with a contained pane to holdall other controls. The procedure parses this skeletal
specification, then modifies the XML structure inmemory to add a series of horizontal panes, eachcontaining a text label and an editnumber control.
These changes are made using methods in class
XMLNODE: NewChild(), SetAttribute(), and
SetText(). The completed dialog is then opened.

page 27

STEPS; choose File / Open /*.SML File... and select
DEVEG68.SML from the
SMLDLG directory; run the script; in the dialog window that
opens, press [select
NIR...], navigate into the
INYOTM Project File in the
SMLDLG directory, andselect BAND_4; press [Select RED...]and select BAND_3; turn on the Devegetate
NIR and Devegetate
RED toggle buttons; type “3” into the “Numberof additional bands todevegetate” field andpress <Enter>; press [Select Bands...]; select BAND_1, BAND_2,
and BAND_5; press [Set dark pixel
values...]; press [OK] in the Set
Dark Pixel Values
window that opens; press [Select Output
File...] and name a new
Project File to containthe output objects; press [Directory...] andselect the directory inwhich TNTmips isinstalled; press [OK] to start
processing

Building Dialogs in SML

A Simple Dialog Using Widget Classes
STEPS; choose File / Open /*.SML File... and selectWIDGET1.SML from the
SMLDLG directory; run the script; study the script sections
that define the different
parts of the Hello World
dialog window; press [Close] on the
Hello World window

We will now consider some examples of custom dialog windows constructed using Motif widget classes.
Although this method is more cumbersome than using dialog specifications in XML, widget classes
allow for more complex dialog designs not currently
available through XML.

The sample script in this exercise creates and opens
a very simple dialog window that displays a label
string and has a Close button. Each of these components is a separate widget contained in an XmForm
widget. An XmForm widget lets you place its "children" (contained widgets) using a simple relative
positioning scheme. Each widget can be attached
to another widget on its top, bottom, left, and right,
and you can specify an offset value (in screen pixels) for each side as well. In this example# WIDGET1.SML# Sample script for Building Dialogs in SML.
# Creates and opens a simple dialog window
the label widget (class XmLabel) is at# using Motif Widget classes.
tached to the form on its top, left, and# Define parent widget for dialog window.
class XmForm win1;
right sides. The Close Button (class# Procedure for closing window
XmPushButton) is attached at its top toproc OnClose() {DialogClose(win1);
the label widget and on the left and right
DestroyWidget(win1);}
sides to the form. The form widget au# Set up dialog window
win1 = CreateFormDialog(“Hello World”);
tomatically resizes to accommodate all
win1.MarginHeight = 5;
win1.MarginWidth = 5;of the contained widgets.
# Create label text for windowclass XmLabel winLabel;
winLabel = CreateLabel(win1,”Sample Dialog Window”);
winLabel.TopWidget = win1;
winLabel.LeftWidget = win1;
winLabel.LeftOffset = 10;
winLabel.RightWidget = win1;
winLabel.RightOffset = 10;

Control widgets can have one or more
callbacks relating to different control actions. Class XmPushButton, forexample, has an ActivateCallback class# Create Close button attached to label on# on top and to window margin on left and rightmember that is invoked by pressing theclass XmPushButton closeButton;
closeButton = CreatePushButton(win1,”Close”);
closeButton.TopWidget = winLabel;button. For most types of controls, youcloseButton.TopOffset = 5;closeButton.leftWidget = win1;
register a procedure or function in yourcloseButton.rightWidget = win1;
closeButton.bottomWidget = win1;
script with a particular control callback
WidgetAddCallback(closeButton.ActivateCallback,OnClose);by using the WidgetAddCallback() func# Open dialog window and keep script active# until window is closed.
tion. This function takes a widget
DialogOpen(win1);
DialogWaitForClose(win1);
callback class followed by the name ofthe procedure. In this dialog, activating the Close
button calls the OnClose() procedure defined at the
beginning of the script.

page 28

Building Dialogs in SML

A Dialog Using Varied Widget Classes
Sample script WIDGET2.SML creates a more complex
dialog window that is similar to the one created via
an XML specification in the AREACALC script. The
dialog uses a variety of widget types, including labels, a field for entering a numeric value, a frame(similar to a groupbox), a separator line, and two
option menus. The menus are used to select input
and output area units, and are populated automatically from TNT reference files using a
CreateUnitOptionMenu() function that creates an
instance of the XmOptionMenu widget class. The
computed area is output to a text label.
The buttons at the bottom of the window use a different widget class than the button in the previous
script. They are instances of class PushButtonItem,
which can be used for either text buttons or icon
buttons. Text buttons must be placed in a buttonrow, a specific type of XmForm, and icon buttons
must be placed in an XmRowColumn widget, a typeof container widget that lets you layout widgets in a
grid.
You don't need to use the WidgetAddCallback() function to define the action of a PushButtonItem; thefunction that defines the item requires the name of
the callback function or procedure as one of its arguments. The unit option menu widget also uses thelatter method to define the procedure called when
the unit is changed.

STEPS; choose File / Open /*.SML File and selectWIDGET2.SML from the
SMLDLG directory; run the script; in the dialog window
opened by the script,
enter a value in the Enter
Area Value field; choose an input area unit
from the upper unit menu
; choose an output area
unit from the lower unit
menu
; Press the Convert button; study the script sections
that define the different
window components andactions; click [Close] when you
are finished working withthe dialog window
An XmForm is a genericcontainer widget. A dialog
window is an XmForm, andyou can use additional
XmForm widgets within the
dialog like layout panes toorganize and align controls.
You can also create a
scrolled window using the
XmScrolled Window widget
in place of the main
XmForm.

Widget classes used to create the Area Unit Conversion dialog window
PromptNum(includes
label)

XmOptionMenu

XmFramewith child
XmFormXmLabelXmSeparator

XmForm(dialog window)

PushButtonItem in
XmForm button row

page 29

XmLabelBuilding Dialogs in SML

Creating and Using a Drawing Area
STEPS
; choose File / Open /*SML File and selectDRAWDLG.SML from the
SMLDLG directory; run the script; study the script sections
that define the different
window components andactions; click [Close] when you
are finished working withthe dialog window

Filledrectangle[ FillRect() ]Filled circle[ FillCircle() ]In some instances you may want to design a dialog
window that incorporates a graph created from yourinput data or from the process output, or some othergraphic. Numerous functions in the Drawing function group allow you to draw lines, geometric shapes,
and text, and to set color and other style characteristics. To utilize these functions you must include an
XmDrawingArea widget in your dialog window.
The DRAWDLG.SML script illustrates how to set up anduse a drawing area in a dialog window. When you
create the drawing area, you specify its height andwidth in screen pixels along with the parent widget
and attachment settings. Placement of elements inthe drawing area is referenced to an X-Y coordinate
system with units of screen pixels and an origin (0,0position) at the upper left corner of the drawing area.
When you use functions such as SetColor(),
SetLineWidth(), and DrawTextSetFont(), these settings are used by subsequent drawing functions until
you call the relevant "Set" functions again to change
them. These parameters are stored in a structure
called a graphics context, which is created by thefunction CreateGCForDrawingArea(). The GC mustalso be activated by the ActivateGC() function before it can be used.

Circle [ DrawCircle() ]Text (rotated)[ DrawTextSimple() ]The DRAWDLG.SML script uses
a drawing area widget todraw (in order) a filled white
rectangle, a filled red circle,
an open yellow circle, and asimple text string.

If your dialog window is covered by another window and then exposed again, regular Xm widgets
are redrawn automatically. If you use a drawing area,
however, your script must explicitly handle thisevent. You must add an ExposeCallback to the callback list of your drawing area widget. This callback
is triggered automatically when the window is
opened or otherwise exposed. All of the drawing
instructions must be placed inside the callback procedure so that drawing is triggered by any expose
event. A graphics context requires an active window, so the GC must also be created and activatedwithin the callback.

page 30

Building Dialogs in SML

Creating a View in a Dialog Window
A dialog window created by an SML script can display input or output objects in a view. The
GroupCreateView() function is used to create theview widget to display a geodata group within theparent dialog. Other functions in the Geodata Display, Geodata Display Group, Geodata Display
Layout, and Geodata Display View function groups
allow you to set up a group to display, to add objects, and to access coordinate and scale information.

STEPS; select File / Open /*.SML File and select
VIEW.SML from the SMLDLG
directory; run the script using as
input raster _8_BIT fromthe CB_COMP Project Filein CB_DATA sample data
directory; select View / Close to
close the window

Sample script VIEW.SML shows the basic steps required to open a view window of a group anddisplay an input raster. Sample script BOXCAR2.SML
creates a more complex dialog window incorporating a number of other widgets in addition to theview.

Sample script
BOXCAR2.SML
provides a more
complexexample of a
dialog window
incorporating aview.

By default, aview widget
includes thestandard
menus, basic
toolbar, scale /position line,
and status line.
A createflag$ parameter of the GroupCreateView()function allows you to eliminate selected window
elements if you wish. For example, the Boxcar view
does not have a Scale / Position line or status line.

page 31; select File / Open /*.SML File and select
BOXCAR2.SML from the
SMLDLG directory; run the script, selecting
for input rasters RED,
GREEN, and BLUE from the
CB_TM Project File in the
CB_DATA directory; press [Process] on the
Boxcar Classification
window to run using thedefault values; study the script to see
how the various window
components areconstructed and how
actions are controlled

Advanced Software for Geospatial Analysis

Building Dialogs in SML

MicroImages, Inc. publishes a complete line of professional software for advanced geospatial
data visualization, analysis, and publishing. Contact us or visit our web site for detailed product information.
TNTmips TNTmips is a professional system for fully integrated GIS, image analysis, CAD,
TIN, desktop cartography, and geospatial database management.
TNTedit TNTedit provides interactive tools to create, georeference, and edit vector,
image, CAD, TIN, and relational database project materials in a wide variety of formats.
TNTview TNTview has the same powerful display features as TNTmips and is perfect for
those who do not need the technical processing and preparation features of TNTmips.
TNTatlas TNTatlas lets you publish and distribute your spatial project materials on CDROM at low cost. TNTatlas CDs can be used on any popular computing platform.
TNTserver TNTserver lets you publish TNTatlases on the Internet or on your intranet.
Navigate through geodata atlases with your web browser and the TNTclient Java applet.
TNTliteTNTlite is a free version of TNTmips for students and professionals with small
projects. You can download TNTlite from MicroImages’ web site, or you can order
TNTlite on CD-ROM.

Index
book element........................................14
callback....................................22-29
colorbutton....................................13,14
combobox.....................................8,25,26
control settings..................................23
dialog element.................................5,6,7
drawing area.....................................30
editnumber..............................10,25
edittext..................................13,25,26
frame............................................29
groupbox...................................................9
id attribute..........................................6,7
item................................8,9,11,12
label...............................5,8,10,28,29
layout component.................................9
listbox..................................................8,11,26
menubutton..................................8,12
modal dialog......................................17
Motif.........................................4
Popup dialog........................................3

page element......................................14
pane.................................................10-12
Parse(xml$)............................16,17
pushbutton...............................5,11,12,28
radiogroup............................................9
Read(xmlfile$).............................16,17
root element..........................................5
script element...........................................24
togglebutton.................................7,12,26
view................................................31
widget............................................4,28,29
XML.......................................................................4,5
attributes.................................6
editors..................................20-21
elements.............................................5
empty tag........................................7
errors............................................18-19
tags..............................5,7,22,24
valid................................20-21
well-formed.................................6,18,20

MicroImages, Inc.
11th Floor - Sharp Tower
206 South 13th Street
Lincoln, Nebraska 68508-2010 USA
Voice: (402) 477-9554
FAX: (402) 477-9559

page 32 email: info@microimages.com

internet: www.microimages.com

S
M
L
D
I
A
L
O
G
S

Reference Guide to SML Dialog Specifications in XML
This document is a reference to the creation of custom SML dialog window specifications in XML format. A dialog
specification is a simple text file (or text character string embedded in the SML script) that conforms to the basic
format and syntax rules of the Extensible Markup Language (XML). The XML text consists of a set of predefined
XML tags and attributes (described in this document) in a nested, hierarchical structure that mirrors the grouping ofcomponents in the dialog window. In comparison to the previously-available X-Motif class structures in SML for
custom dialogs, XML specifications provide a simpler, more highly-structured approach to constructing custom
SML dialogs, as well as streamlined methods for accessing information input via the dialog. Custom dialog
windows created using an XML specification can be used in either SML for X or SML for Windows. Dialogs
created using the X-Motif classes can be used only in SML for X.

About XMLXML is a markup meta-language that is designed to allow the creation of structured, self-describing text. XML
makes use of tags (enclosed between < and > characters) to delimit and identify pieces (elements) of text data. In
an SML dialog specification, the data elements identified by the tags correspond to specific components of a dialog
window, such as buttons and labels. Delimiting tags occur as a pair, a start tag and end tag, that enclose the relevant
text. The start and end tag use the same tag name, but in the end tag the name is preceded by the forward slash “/”character. For example, here is the entry for a text label in an SML dialog specification in XML:<label>Select Composite Type:</label>In this case the <label> tags bracket the text to be used for the label on the dialog.
Data elements in XML can be nested inside other data elements to indicate membership in a group. There may be
multiple levels of membership, forming a hierarchical or tree-like data model. This model is well suited to describe
a dialog window, because many dialog elements, such as panes, list boxes, and menu buttons, act as “containers”
that have other elements as their “contents”. (Another way of stating this is that the container element is the“parent” and the contained elements are the “children”). In a dialog specification in XML the contained elements
are nested inside the tag pair for the container element. For example, the excerpt below shows the specification for alayout pane that includes two text labels sandwiched around a numeric entry control:<pane Orientation="horizontal"><label>Buffer Distance:</label><editnumber id="buffdist" Width="4" Precision="0" Default="100" MinVal="0"/><label>meters</label></pane>For ease of editing and reading the dialog specification, the start and end tags for a parent element should be placedon separate lines in the text, with the contained elements identified on the intervening lines. You should also indentlines corresponding to child elements by an equal amount relative to their parent element tags.
Start tags can also include attributes. A specific, predefined set of attributes are available for each type of dialog
element in an SML dialog specification. You use these attributes to define the individual characteristics and settingsfor each dialog element, to provide a control handle for the SML script to use to access the control, and to specify acallback procedure associated with a control (if needed). To use an attribute within an element tag, you list the
attribute name and assign it a value (in double quotation marks) using an equals sign ( = ). In the specification
excerpt immediately above, the layout pane has an attribute called Orientation that has been assigned the value
horizontal. Attribute names and predefined nonnumeric values are case-sensitive.
Some dialog elements can be completely specified using the tag name and a list of start-tag attributes. There is noother “text” associated with the element to be bracketed by separate start and end tags. In this case the two tags are
combined into a so-called empty tag. In an empty tag the forward slash character ( / ) normally used to begin an end
tag is placed just before the final character ( > ) of the tag. The editnumber tag in the specification excerpt
immediately above is an example of an empty tag.

© 2003 MicroImages, Inc. 206 South 13th Street, Lincoln, Nebraska 68508-2010 www.microimages.com

Reference Guide to SML Dialog Specification in XML

TNT Products 6.8, 12 June 2003

In order for SML to correctly parse and interpret a document specification, the specification must follow some
simple syntax rules that define a well-formed XML document:
1) An element containing text or other elements must have both start and end tags.
2) An empty element tag must have a forward slash ( / ) before the ending bracket3) All attribute values must be in quotes.
4) Elements may not overlap.
In general uses of XML, the meanings of tags and attributes are specified in a document type definition (DTD),
which can be either contained in the XML file or referenced by it, or alternatively in an external XML Schema.
However, the XML text describing an SML dialog does not need to reference a DTD or Schema, because the tag
and attribute meanings are processed by the SML parser.
To conform to XML standards, the dialog specification should begin with an XML Declaration containing theversion of XML:<?xml version="1.0"?>.

For further information about XML, please consult the following:
Learning XML, by Erik T. Ray. O’Reilly & Associates, Sebastopol, CA, 2001. 354 pages.
Mastering XML, by Ann Navarro, Chuck White, and Linda Burman. SYBEX, San Francisco, CA, 2000, 882 pages.
XML Handbook, by Charles F. Goldfarb and Paul Prescod. Prentice-Hall PTR, Upper Saddle River, NJ, 4th Ed.,
2002, 1147 pages.
www.w3.org/XML/: XML web site maintained by the World Wide Web Consortium (W3C), the organization that
formulates and publishes XML standards. Includes technical specifications and links to other web resources on
XML, including tutorials and books.
www.xml.org: Industry web portal on XML maintained by OASIS, the nonprofit Organization for the Advancementof Structured Information Systems. Includes sections on XML basics.
xml.coverpages.org/xml.html: XML section of Cover Pages, maintained by Robin Cover and hosted by OASIS.
www.xml.com: XML site by O'Reilly & Associates.

2© 2003 MicroImages, Inc. 206 South 13th Street, Lincoln, Nebraska 68508-2010 www.microimages.com

TNT Products 6.8, 12 June 2003

Reference Guide to SML Dialog Specification in XML

Overview of Tag Set and Classes for SML Dialog Specifications
A dialog created using an XML dialog specification makes use of a set of Graphical User Interface (GUI) classes in
SML. Most of the XML tag types in a dialog specification correspond to specific GUI classes. In essence, the XML
specification provides a shorthand way to set up and access the various class structures that underlie a custom dialog
window. The following is a list of the available dialog elements with their tag name and corresponding GUI class.
Each element type is documented fully in subsequent sections of this document.
Tag

Description

Class<root><dialog><script>

Main Elements
root element of the document
dialog window
container for an SML script

None
GUI_DLG
None<book><page><pane><groupbox>

Layout Elementsbook of tabbed pages
tabbed page in a bookwindow layout paneframe around other controls

GUI_LAYOUT_BOOK
GUI_LAYOUT_PAGE
GUI_LAYOUT_PANE
GUI_CTRL_GROUPBOX<label><pushbutton><togglebutton><colorbutton><edittext><editnumber><radiogroup><combobox><menubutton><listbox><item>

Control Elements
simple text label
push button with text or icon
independent toggle buttoncolor selection button
text entry control
numeric entry control
group of radio (mutually exclusive) buttons
combobox menu
button with drop-down menu
scrolled list for selection
item in a list, menu, combobox, or radiogroup

GUI_CTRL_LABEL
GUI_CTRL_PUSHBUTTON
GUI_CTRL_TOGGLEBUTTON
GUI_CTRL_COLORBUTTON
GUI_CTRL_EDIT_STRING
GUI_CTRL_EDIT_NUMBER
GUI_FORM_RADIOGROUPGUI_CTRL_COMBOBOX
GUI_CTRL_MENUBUTTON
GUI_CTRL_LISTBOXNone

In addition to the classes listed above, two other SML classes provide methods to interact with dialog specifications
in XML:class XMLDOC: an XML document. Methods in this class are used to read and parse the XML text.
class XMLNODE: an element (node) in an XML document. Methods in this class allow the script to access the
XML elements that correspond to particular components of the dialog.

© 2003 MicroImages, Inc. 206 South 13th Street, Lincoln, Nebraska 68508-2010 www.microimages.com

3Reference Guide to SML Dialog Specification in XML

TNT Products 6.8, 12 June 2003

Callbacks
All dialog elements that represent actual controls can have callback attributes. The attribute is named in such a way
as to indicate the type of action happening, like OnClicked, or OnValueChanged.
The value of a callback attribute is a small fragment of SML code, usually a call to a function or procedure definedin the main SML script or in the dialog specification within a <script> element. If the value used for a callback
attribute is a call to a function or procedure, include the full procedure name (including parentheses) as the callback
value in the dialog specification, as for the OnOK attribute in the following example:<dialog id="tigerops" title="Extraction options" OnOK="CheckTogs()">All callbacks can return a numeric value and return 1 by default. Some callbacks, like OnOK for dialogs canprevent the default action by returning 0 instead. If the returned value is required for use in the main script, thevalue for the callback should be a statement with the keyword "return" followed by the name of the associated userdefined function, as in the following example:<dialog id="tigerops" title="Extraction options" OnOK="return CheckTogs()">The SML code within a <script> element can consist of one or more callback procedures for individual dialog
controls, including the dialog's OK and Cancel buttons. In some cases the code within the <script> tag could carryout most of the intended data processing. However, a separate SML script is required to read in the dialog
specification file and open the dialog window described in the specification.
Within the SML code in a <script> element, the following conditions apply:Global variables and functions defined in the main SML script are available within the <script> elementcode.
The default MDLGPARENT for the SMLCONTEXT is set to the LAYOUT_PANE containing the control
so that any dialogs popped up while within the callback will automatically appear over the dialog, notsomewhere else.
The variable this is predefined to be the control causing the event. The variable corresponds to a classvariable of one of the classes derived from GUI_CTRL. The control will already reflect the changes made,so if the event is a toggle button being toggled, this.GetValue() will return true if the button was
toggled on and false if it was toggled off. To use the variable, you need to do two things: (1) the value you
assign for the callback attribute should include this as a parameter of the procedure or function; (2) in thedefinition of the procedure or function, declare this as an instance of the relevant GUI_CTRL class. The
excerpt below illustrates this structure for a listbox control whose OnChangeSelection callback calls a
procedure called SayHello().

<root><dialog id="hello" Title="Bonjour!"...
<listbox id="listbox" SelectStyle="single" Height="3" Default="French"
OnChangeSelection="SayHello(this)">...
<\dialog><script><![CDATA[
proc SayHello (class GUI_CTRL_LISTBOX this) {local string $language;
language$ = this.GetSelectedItemID();
...
}
]]>
</script></root>4© 2003 MicroImages, Inc. 206 South 13th Street, Lincoln, Nebraska 68508-2010 www.microimages.com

TNT Products 6.8, 12 June 2003

Reference Guide to SML Dialog Specification in XML

Example Dialog Specification in XML
This dialog specification describes a dialog window with three tabbed panels that include various types of controls.

<?xml version="1.0"?><root><dialog id="test" title="This is a test" Orientation="vertical" OnOK="GetDlgValues()"><book><page Name="Page1"><label>This is some text in a label</label><pushbutton Name="Ignore This" OnPressed="TestFunc2();"/><combobox id="combo"><item Value="item1">If it's not one thing</item><item Value="item2">it's another</item></combobox><pane Orientation="horizontal"><pushbutton Name="Test" Icon="CHECKBOX_BLACK" ToolTip="Check This!"/><togglebutton id="tbutton" Name="This is a togglebutton"/></pane></page><page Name="Edit"><pane Orientation="horizontal"><label WidthGroup="1">First Name:</label><edittext id="fname" width="20"/></pane><pane Orientation="horizontal"><label WidthGroup="1">Last Name:</label><edittext id="lname" width="20"/></pane><pane Orientation="horizontal"><label WidthGroup="1">Password:</label><edittext id="password" Opaque="true" width="20"/></pane></page><page Name="Radiogroup"><groupbox Name="This is a groupbox"><radiogroup id="radiogroup"><item Value="button1" Name="If it's not one thing"/><item Value="button2" Name="it's another"/></radiogroup></groupbox></page></book></dialog><script language="SML"><![CDATA[
func TestFunc2() {PopupMessage("I said to ignore this!");return (0);}]]></script></root>© 2003 MicroImages, Inc. 206 South 13th Street, Lincoln, Nebraska 68508-2010 www.microimages.com

5Reference Guide to SML Dialog Specification in XML

TNT Products 6.8, 12 June 2003

Common Dialog Element Attributes
This is a list of attributes that are common to many of the dialog elements. They are documented here to avoid
redundancy. In the succeeding documentation of individual elements, the attributes unique to that element are
documented in full, but the available common attributes are merely listed for each element.
id – All elements can have an id attribute. The value of an id attribute can be any string, but must be unique withina given XML document. You are not allowed to have two tags with the same id. This is what allows you togain access to the elements within SML and is also the key used to set/retrieve the data for the form. You
don’t have to assign ids to elements that you don’t need to read or change, such as labels and icons.
Orientation – Either “horizontal” or “vertical”. The default is the opposite of the parent’s orientation or vertical
for the main form. All children of the form are laid out from left to right or top to bottom. To make more
complex layouts, nest <panes> with alternating orientations.
HorizAlign – Controls how the control is aligned horizontally in the available space. Possible values are “Left”(the default), “Right” and “Center”.
VertAlign – Controls how the control is aligned vertically in the available space. Possible values are “Top” (thedefault), “Bottom” and “Center”.
HorizResize – Controls how the control behaves when the parent is resized. Possible values are:”Expand” – Expands horizontally to fill the available space.
”Fixed” – Width stays the same.
”Relative” – Expands horizontally, keeping the same percentage of space as it had before.
VertResize – Controls how the control behaves when the parent is resized. Possible values are:”Expand” – Expands vertically to fill the available space.
”Fixed” – Width stays the same.
”Relative” – Expands vertically, keeping the same percentage of space as it had before.
ChildSpacing – Space between children. The default value is 4.
ExtraBorder – Extra border around inside of pane, in addition to ChildSpacing. The default value is 0.
WidthGroup – If specified, all controls with the same WidthGroup value will be adjusted to be as wide as thewidest control in the group.
ResourceLookup – Either “true” or “false”. If “false”, the string is used as-is. If “true” any string shown on the
dialog for the element (such as a label or dialog name) is translated through the X resource filetntxres.txt. This means that the values for labels should be specified using the standard identifier for the
specific label string in the X resource file. (If the string you provide does not correspond to an identifier inthe resource file, the string is also used as-is.) You can use this setting to create an automatically-localized
custom dialog if the resource file has been translated into the appropriate language. The default is to inherit
the value from the parent, except for <form> and <dialog>, which default to “true”.
Enabled – Either “true” or “false”. If “true” (the default), the control is enabled. If “false”, it’s initially disabledand grayed out. The control stays this way unless changed via SML script or C++ code.
NOTE. Any attribute that has “true” and “false” as valid values also accepts “yes” and “no” or “1” and “0”.

6

© 2003 MicroImages, Inc. 206 South 13th Street, Lincoln, Nebraska 68508-2010 www.microimages.com

TNT Products 6.8, 12 June 2003

Reference Guide to SML Dialog Specification in XML

Dialog (Form) Elements
Main Elements<root>
Description: The required root element of the document. All elements described subsequently must be contained
within <root> or one of its children.
Valid inside: nothing
Valid children: <script>, <dialog>
Attributes: none
SML Class: none

<dialog>
Description: A dialog window.
A dialog can be modal or non-modal, but that is up to the SML code that opens the dialog, not the XML
specification. A modal dialog is one that takes control and won’t let the program do anything else until the dialog
closes. Modal dialogs are automatically provided with “OK” and “Cancel” buttons. If there is a HelpID attribute in
the XML specification of the dialog, it will also have a “Help” button. Non-modal dialogs permit program
operations and user interactions to continue while they’re open. In this case, the “OK” and “Cancel” buttons are
replaced with “Apply” and “Close”.
Valid inside: <root>
Valid children: Any layout element except <page>; any control element except <item>
Attributes:
id, HorizAlign, VertAlign, HorizResize, VertResize, ChildSpacing,
ExtraBorder, ResourceLookup, Orientation
OnApply – SML Code to execute when user presses the “Apply” button.
OnOK – SML Code to execute when user presses the “OK” button. After your OnOK callback is called, thedialog will be closed. You can prevent it from closing by having your callback return 0.
OnCancel – SML Code to execute when the user presses the “Cancel” button. After your OnCancel
callback is called, the dialog will be closed. You can prevent it from closing by having yourcallback return 0.
OnOpen – SML Code to execute when the dialog opens.
OnClose – SML Code to execute when the dialog closes. After your OnClose callback is called, thedialog will be closed. You can prevent it from closing by having your callback return 0.
Title – The title of the dialog.
HelpID – A key into tnthelp.txt. If set, the dialog gets a “help” button that opens a help window.
SML Class: GUI_DLG© 2003 MicroImages, Inc. 206 South 13th Street, Lincoln, Nebraska 68508-2010 www.microimages.com

7Reference Guide to SML Dialog Specification in XML

TNT Products 6.8, 12 June 2003

<script>
Description: Container for an SML script. An SML script can be enclosed in an XML wrapper. If the file has a.sml extension but an XML header, the SML parser will look for a script tag and run that. The rest of the XML
document will be parsed and accessible to the script.
Note that the contents of the script tag must start with <![CDATA[ and end with ]]>. Without this, you would
have to escape every ampersand (&), greater-than (>), less-than (<) and both single and double quotes.
Valid inside: <root>
Valid children: Only a CDATA containing SML code
Attributes:
id – Unique identifier for the script (not usually necessary)language – TNTmips only recognizes “SML”, which is the default. Include this attribute to ensure that
other XML viewers don’t try to interpret the CDATA as some other language such as Javascript.
Usage – One of the following values specifying the type of script:“standalone”“style-point”, “style-line”, “style-poly”“select-point”, “select-line”, “select-poly”“geoformula”, “macroscript”, “toolscript”
StrictSyntax – either “true” or “false”. If “true” (the default) the parser enforces stricter syntax rules(requires semicolons at the end of lines, predeclared variables, etc.).
SML Class: none

Layout Elements<pane>
Description: A layout pane
Valid inside: <dialog>, <page>, <pane>, <groupbox>
Valid children: Any layout element except <page>; any control element except <item>
Attributes:
id, HorizAlign, VertAlign, HorizResize, VertResize, ChildSpacing,
ExtraBorder, ResourceLookup
Orientation – Either “horizontal” or “vertical” (default is the opposite of the parent pane). All childrenof the form will be laid out from left to right or top to bottom. For more complex layouts, nest
<pane>s with alternating orientations.
SML Class: GUI_LAYOUT_PANE<page>
Description: A tabbed page in a <book>
Valid inside: <book>
Valid children: Any layout element except <page>; any control element except <item>

8© 2003 MicroImages, Inc. 206 South 13th Street, Lincoln, Nebraska 68508-2010 www.microimages.com

TNT Products 6.8, 12 June 2003

Reference Guide to SML Dialog Specification in XML

Attributes:
id, Orientation, ResourceLookup
Name – the label on the page’s tab
OnSetActive – SML code to execute when the page is activated
SML Class:

GUI_LAYOUT_PAGE<book>
Description: book of tabbed pages
Valid inside: <dialog>, <page>, <pane>, <groupbox>
Valid children: <page>
Attributes:
id, HorizAlign, VertAlign, HorizResize, VertResize, ChildSpacing,
ExtraBorder, ResourceLookup
SML Class: GUI_LAYOUT_BOOK<groupbox>
Description: A frame around other controls
Valid inside: <dialog>, <page>, <pane>, <groupbox>
Valid children: Any layout element except <page>; any control element except <item>
Attributes:
id, HorizAlign, VertAlign, HorizResize, VertResize, ChildSpacing,
ExtraBorder, Orientation, ResourceLookup, Enabled
Name – the label on the upper left edge of the box (optional)
SML Class: GUI_CTRL_GROUPBOX

Control Elements<label>Description: A simple text label
Valid inside: any layout element except <book>
Valid children: text
Attributes:
id, HorizAlign, VertAlign, HorizResize, VertResize, ResourceLookup,
WidthGroup, Enabled
TextAlign – How to align the text of the label. Possible options are:“LeftNoWrap” – Left justify without word wrapping“Left” – Left justify, MFC may word-wrap if too long, but X won’t© 2003 MicroImages, Inc. 206 South 13th Street, Lincoln, Nebraska 68508-2010 www.microimages.com

9Reference Guide to SML Dialog Specification in XML

TNT Products 6.8, 12 June 2003

“Center” – Center, MFC may word-wrap if too long, but X won’t“Right” – Right justify, MFC may word-wrap if too long, but X won’t
SML Class: GUI_CTRL_LABEL<pushbutton>
Description: A push button with either text or icon.
Valid inside: any layout element except <book>
Valid children: none
Attributes:
id, HorizAlign, VertAlign, HorizResize, VertResize, WidthGroup,
ResourceLookup, Enabled
Name – the text to be placed on the button.
Icon – Icon to display based on ICONID values. For example, to use ICONID_CREATE_FILE, use thestring “CREATE_FILE”.
ToolTip – tooltip text to display for the button (only if it has an icon)
OnPressed – SML code to execute to call when the button is pressed. See section on callbacks fordetails.
SML Class: GUI_CTRL_PUSHBUTTON<colorbutton>
Description: A color selection button.
The button has no text, but the body of the button will show the selected color. Pushing the button pops up a color
selection dialog.
Valid inside: any layout element except <book>
Valid children: none
Attributes:
id, HorizAlign, VertAlign, HorizResize, VertResize, WidthGroup, Enabled
ReadOnly – Either “true” or “false”. If true, the button shows a color but the user cannot change it. The
default is “false”
AllowTransparent – Either “true” or “false”. If true, the color selection dialog will allow
transparency settings. The default is “false”.
OnChangeColor – SML code to execute to call when color is changed. See section on callbacks fordetails.
SML Class: GUI_CTRL_COLORBUTTON<togglebutton>
Description: A toggle button.
Valid inside: any layout element except <book>10© 2003 MicroImages, Inc. 206 South 13th Street, Lincoln, Nebraska 68508-2010 www.microimages.com

TNT Products 6.8, 12 June 2003

Reference Guide to SML Dialog Specification in XML

Valid children: none
Attributes:
id, HorizAlign, VertAlign, HorizResize, VertResize, WidthGroup,
ResourceLookup, Enabled
Name – the label to be placed next to the button
Icon – Icon to display. Based on ICONID values. For example, to use ICONID_CREATE_FILE, use
the string “CREATE_FILE”. You can get a full list of valid Icon IDs by looking at the
documentation for the GUI_CTRL_TOGGLEBUTTON class in SML.
ToolTip – tooltip text to display for the button (only if it has an icon)
Type – “check” or “radio”. Radio buttons are round. A check box is square. The default is “check”. Notethat radio behavior is not automatic. If you want automatic radio behavior, create a<radiogroup> with an <item> for each radio button.
Selected – Either “true” or “false”. If true, the button is initially selected. This can be overridden
through commands in the SML script.
OnChanged – SML code to execute when the button’s state changes (when the user toggles the button
on or off). For radio buttons, an OnChanged callback is also triggered for the button that is being
toggled off. See section on callbacks for details.
Note: to create mutually exclusive radio buttons, create a <radiogroup> with <item>s instead of<togglebutton>s
SML Class: GUI_CTRL_TOGGLEBUTTON<edittext>
Description: A text entry control.
The control has no built-in text label.
Valid inside: any layout element except <book>
Valid children: none
Attributes:
id, HorizAlign, VertAlign, HorizResize, VertResize, WidthGroup,
ResourceLookup, Enabled
OnChanged – SML code to execute when the value is edited.
Width – Width of the text control in “typical” characters.
MaxLength – Maximum length of text to allow.
Justify – Text alignment. Either “left” or “right”. The default is “left”.
OnActivate – SML code to execute when the user presses <Enter> with the cursor in the edit control.
ReadOnly – Either “true” or “false”. If “true”, the user cannot change the value, but the control does notlook disabled. The default is “false”.
Opaque – Either “true” or “false”. If “true”, the control shows “*” for password input. Default is “false”.
SML Class: GUI_CTRL_EDIT_STRING© 2003 MicroImages, Inc. 206 South 13th Street, Lincoln, Nebraska 68508-2010 www.microimages.com

11Reference Guide to SML Dialog Specification in XML

TNT Products 6.8, 12 June 2003

<editnumber>
Description: A numeric entry control.
The control has no built-in text label.
Valid inside: any layout element except <book>
Valid children: none
Attributes:
id, HorizAlign, VertAlign, HorizResize, VertResize, WidthGroup,
ResourceLookup, Enabled
OnChanged – SML code to execute when the value is edited.
Width – Width of the text control in “typical” characters.
MaxLength – Maximum length of text to allow.
Justify – Text justification. Either “left” or “right”. The default is “right”.
OnActivate – SML code to execute when the user presses <Enter> in the edit control.
ReadOnly – Either “true” or “false”. If “true”, the user cannot change the value, but the control does notlook disabled. The default is “false”
Default – The default value (optional)
MinVal – Minimum allowed value. Default is no minimum.
MaxVal – Maximum allowed value. Default is no maximum.
AddOne – Either “true” or “false”. If “true”, the value shown in the control is always one more than theactual data value. Default is “false”.
BlankZero – Either “true” or “false”. If “true”, blank the field if the value is 0.0. The default is “false”.
Note, the IEEE NaN value will always cause the control to show blank.
Format – One of the following:“Decimal” – Normal decimal format (default)“Exponential” – Show in scientific notation.
“Latitude” – A latitude value. Actual prompt value is decimal degrees.
“Longitude” – A longitude value. Actual prompt value is decimal degrees.
“DegMinSec” – An angle in Degrees, Minutes and Seconds. Actual prompt value is decimaldegrees.
Precision – Number of digits after the decimal place (Default is 6)
SML Class: GUI_CTRL_EDIT_NUMBER<item>
Description: An item in a listbox, combobox, menubutton, or radio group.
Valid inside: <combobox>, <listbox>, <menubutton>, <radiogroup>
Valid children: text
Attributes:
ResourceLookup
Name – The button label for a radiogroup button or the item's menu entry for the other parent controls.
Value – The value of this item. This is the value that is returned when calling GetValue() on the parent
object if this item is selected. If omitted, the default value is the item’s index, starting at 1.

12© 2003 MicroImages, Inc. 206 South 13th Street, Lincoln, Nebraska 68508-2010 www.microimages.com

TNT Products 6.8, 12 June 2003

Reference Guide to SML Dialog Specification in XML

Selected – Either “true” or “false”. If true, the item is selected by default. This overrides theDefault attribute of the parent. Default is false. If more than one item is marked as selected,
the last one marked is the one selected unless the parent is a multi-select list.
Icon – An icon ID (only valid if the <item> is inside a <radiogroup>).
SML Class: none<radiogroup>
Description: A group of radio buttons (mutually exclusive).
Valid inside: any layout element except <book>
Valid children: <item>
Attributes:
id, HorizAlign, VertAlign, HorizResize, VertResize, WidthGroup,
Orientation, ResourceLookup, Enabled
Default – The Value of the button that is to be on by default. This can be overridden by setting the
Selected attribute of one of the items in the group
OnSelection – SML code to execute when the selected button changes.
SML Class: GUI_FORM_RADIOGROUP<combobox>
Description: A combo-box.
Valid inside: any layout element except <book>
Valid children: <item>
Attributes:
id, HorizAlign, VertAlign, HorizResize, VertResize, WidthGroup,
ResourceLookup, Enabled
Default – The Value of the item that is to be selected by default. This can be overridden by setting
the Selected attribute of one of the items in the combobox.
OnSelection – SML code to execute when the selected item changes.
Width – Width of the control in “typical” characters. The default is to base the width on the width of thewidest item in the list.
Height – The maximum number of items to show when the list is opened. Default is 7. If there are more
items than that, the list has a scrollbar.
Sort – Either “true” or “false”. If “true”, then the values are sorted. The default is false.
SML Class: GUI_CTRL_COMBOBOX<listbox>
Description: A simple scrolled list from which the user can view and select items.
Valid inside: any layout element except <book>© 2003 MicroImages, Inc. 206 South 13th Street, Lincoln, Nebraska 68508-2010 www.microimages.com

13

Reference Guide to SML Dialog Specification in XML

TNT Products 6.8, 12 June 2003

Valid children: <item>
Attributes:
id, HorizAlign, VertAlign, HorizResize, VertResize, WidthGroup,
ResourceLookup, Enabled
Default – The Value of the item that is to be selected by default. This can be overridden by setting
the Selected attribute of one of the items in the combobox.
OnChangeSelection – SML code to execute when the selected item changes.
Width – Width of the control in “typical” characters. The default is to base the width on the width of thewidest item in the list.
Height – Height of the list in lines (default is 5).
Sort – Either “true” or “false”. If “true”, then the values are sorted. The default is false.
SelectStyle – One of the following:“single” – (the default) allows one item to be selected.
“multi” – Multiple items selectable by simple toggle of each item
“extended” – Multiple items selected by SHIFT/CTRL key and mouse
SML Class: GUI_CTRL_LISTBOX<menubutton>
Description: A pushbutton (text or icon) with a drop-down menu.
Valid inside: any layout element except <book>
Valid children: <item>
Attributes:
id, HorizAlign, VertAlign, HorizResize, VertResize, WidthGroup,
ResourceLookup, Enabled
Name – the text to be placed on the button
Icon – Icon to display. Based on ICONID values. For example, to use ICONID_CREATE_FILE, use
the string “CREATE_FILE”. You can get a full list of valid Icon IDs by looking at the
documentation for the GUI_CTRL_TOGGLEBUTTON class in SML.
ToolTip – tooltip text to display for the button (only if it has an icon)
OnSelection – SML code to execute when a menu item is selected.
OnMenuPopup – SML code to execute just before the menu is shown.
SML Class: GUI_CTRL_MENUBUTTON

14© 2003 MicroImages, Inc. 206 South 13th Street, Lincoln, Nebraska 68508-2010 www.microimages.com

TNT Products 6.8, 12 June 2003

Reference Guide to SML Dialog Specification in XML

Using an XML Dialog Specification with an SML Script
To use a dialog specification in XML in conjunction with an SML script, the script must first declare an instance ofthe class XMLDOC. Methods within this class are then used to ingest and parse the XML text, creating thenecessary structures in memory for use throughout the remainder of the SML script.
The XML dialog specification used with a particular SML script can be either embedded in the script or in a
separate file. Different methods in class XMLDOC are used to ingest the XML text in these two cases. If you want
to incorporate the dialog specification directly within the SML script, you assign the XML-formatted text containing
the specification to a string variable. In most cases this specification will span multiple lines of text. You can
include multiple text lines in an assignment statement by enclosing the text in single quotation marks, as in thefollowing example:
xml$ = '<?xml version="1.0"?><root><dialog id="hello" title="Hello, world!" ResourceLookup="false"><pane><label WidthGroup="A" HorizAlign="Center">Sample Dialog Window</label><groupbox Name="Language" ExtraBorder="2"><combobox id="combobox" HorizAlign="Center" Width="20"><item Value="English" Name="English"/><item Value="French" Name="French"/><item Value="German" Name="German"/><item Value="Spanish" Name="Spanish"/></combobox></groupbox><pushbutton Name="Print to Console" WidthGroup="A" OnPressed="Proc1()"/></pane></dialog></root>';class XMLDOC doc;
doc.Parse(xml$);As the above example shows, when the XML text has been assigned to a text string, the XMLDOC class method
Parse(xml$) is used to parse the XML text.
If you prefer to compose the XML text in an external editor and keep it as a separate .xml file, you use the
XMLDOC class method Read(filename$) to read the external file and automatically parse its contents. The
filename passed to this method must include the full directory path to the file as well as its filename and extension.
If you keep the SML script and XML file in the same directory, you can simplify the task of specifying the path (andmake the script more readily portable) by using the CONTEXT class structure. When a script is run, an instance of
this class called _context is created automatically. The class member _context.ScriptDir finds the path tothe directory the script is in, and can be used as a substitute for this path in string expressions, as in the following
example that refers to a dialog specification file “text.xml” in the same directory as the SML script. A string
expression is used to concatenate the script’s directory path with the name of the target file:class XMLDOC doc;
xmlfile$ = _context.ScriptDir + "/test.xml";
doc.Read(xmlfile$);Both the Parse(xml$) and Read(xmlfile$) class methods also check the XML syntax of the dialog
specification and return an error code (a negative integer) if syntax errors are found. You can write the script tocheck the returned value and pop up an error message dialog if needed, as shown below:© 2003 MicroImages, Inc. 206 South 13th Street, Lincoln, Nebraska 68508-2010 www.microimages.com

15

Reference Guide to SML Dialog Specification in XML

TNT Products 6.8, 12 June 2003

numeric err;class XMLDOC doc;
xmlfile$ = _context.ScriptDir + "/test.xml";
err = doc.Read(xmlfile$);if (err < 0) {PopupError(err);
Exit();}

Pressing the Details... button on the error message dialog opens another window listing the syntax errors. Note thata single error (such as missing closing quotes on an attribute value or a missing end tag) may trigger a number oflistings in this window.

16© 2003 MicroImages, Inc. 206 South 13th Street, Lincoln, Nebraska 68508-2010 www.microimages.com

TNT Products 6.8, 12 June 2003

Reference Guide to SML Dialog Specification in XML

Opening the Dialog
Opening the dialog specified by the XML text requires several steps:
1) Use the XMLDOC class method GetElementByID() to get the dialog element from the parsed XML and assign
it to an instance of class XMLNODE, the class used to represent elements in a parsed XML structure.
2) Set that XMLNODE instance as the source for an instance of class GUI_DLG, the SML class that actually
represents the dialog window.
3) Use a GUI_DLG class method to open the dialog window as either a modal or nonmodal dialog. A modal dialog
takes control and won’t let the SML program do anything else until the dialog closes. Modal dialogs areautomatically provided with “OK” and “Cancel” buttons. Nonmodal dialogs allow other program operations anduser interactions to continue while they are open. They are automatically provided with “Apply” and “Close”
buttons.
The script excerpt below carries out these steps for a modal dialog:class XMLNODE dlgnode;# “hello” is the value assigned to the id attribute# for the dialog element in the XML text
# pop up an error message if dialog node can’t be founddlgnode = doc.GetElementByID("hello");if (dlgnode == 0) {PopupMessage("Could not find dialog node in XML document");
Exit();}
class GUI_DLG dlg;
dlg.SetXMLNode(dlgnode);
numeric ret;
ret = dlg.DoModal();# set this XML node as the source for the dialog window#open the window as a modal dialog

When the DoModal() class method is called in the script, the method remains active until the user closes the modal
dialog. The method then returns the value -1 if the user pressed the Cancel button, or 0 if the user pressed the OK
button. The script can assign the returned value to a numeric variable (the variable ret in the above example), thencheck this value to determine succeeding actions. This strategy provides an easier alternative to writing explicit
OnCancel() and OnOK() callback procedures.
To create and open the dialog as a nonmodal dialog, you would use the GUI_DLG class methods
CreateModeless() and Open().

Reading Dialog Control Values
Once the dialog has been opened and the user has set its controls, the script needs to get the control settings tocontinue with further processing. Each control in a dialog has a “value” that is either a number or a string. For
editnumber and edittext controls, the value is simply the number or string (respectively) entered by the user.
For a togglebutton, the value can be retrieved as either a number or a string; it is 1 or "yes" if set and 0 or "no" if
not set. For controls that involve selection of an item (combobox, listbox, menubutton, and radiogroup), thevalue of the control is the value of the selected item. The value of each item is set by the Value attribute you
assigned to that item in the dialog specification. You can use any character string for the item attribute, but
obviously each item in a particular control should have a unique value. If you use only numerals in the attributestring, you can read the value as either a number or a string. If you omit Value attributes for the items, the default
value is the numeric index (position) in the list, beginning with 1.
For modal dialogs, dialog settings should be retrieved before the dialog closes and the controls are destroyed.
Settings can be retrieved within callback procedures for individual controls or within the OnOK callback procedure© 2003 MicroImages, Inc. 206 South 13th Street, Lincoln, Nebraska 68508-2010 www.microimages.com

17Reference Guide to SML Dialog Specification in XML

TNT Products 6.8, 12 June 2003

for the dialog window. There are several methods that can be used to get control settings. The simplest and mostdirect way to get the control settings is to use the GUI_DLG class method GetValues() to read the values of all of
the controls at once. These values are returned as an instance of the class GUIFORMDATA. You can then use
GUIFORMDATA class methods GetValueNum(ctrl_id$) or GetValueStr(ctrl_id$), where ctrl_id$ is
the id attribute you assigned for the control, to read each control value out of this structure as needed.
An alternate method is to use the GUI_DLG class methods GetCtrlValueNum(ctrl_id$) and
GetCtrlValueStr(ctrl_id$) to retrieve the value of any control individually from the dialog. This method isless efficient than the previous one if you need to retrieve values for several controls. Internally each of thesefunctions calls the GetValues() class method to read all the control values, but returns only the requested value
and discards the rest.
A third method uses the GetCtrlByID() class method in GUI_DLG to get the control handle for a dialog control,then a GetValueNum() or GetValueStr() method in the individual GUI_CTRL_... class to read the value.

Setting Dialog Control Values
For most dialog windows, you can set the default condition for each control (such as default value for an
editnumber field, default state for a togglebutton, and default selection for a combobox) in the dialog
specification in XML using the attribute provided for each control. However, you can also use statements in themain SML script (or in callbacks for other controls in the dialog) to set a control. For example, in a dialog that
requires the selection of several input objects, you might want the dialog to show the name of the object after eachhas been selected. You can use an edittext control (set to be read-only) next to the selection button for thispurpose. The callback for the selection button can construct a text string from the file name and object name of theselected object and set this as the value for the edittext control. Class methods in the GUI_DLG class(SetCtrlValueNum(ctrl_id$) and SetCtrlValueStr(ctrl_id$) ) provide the simplest means to set control
values. There are also methods in the GUI_CTRL_... class for the individual control type that can be used to set thecontrol value or to set which item is selected by default in a group control.

Sample Script: Read and Set Control Values
The sample script below (xmldlg.sml) opens the dialog created by the specification on page 5 of this document(from a file named test.xml). After the user sets the controls on the dialog and presses the OK button, the script
reads the values from the dialog using each of the methods outlined above and prints the values to the SML Console
Window. It also sets default values for several of the controls before the dialog is opened. You can download thescript and dialog specification from www.microimages.com/freestuf/xmlscripts.htm.
numeric err, ret;
string xmlfile$;
class GUI_DLG dlg;

# variable declarations

func TestFunc() {# define test callback function
PopupMessage("I Said Ignore it!");}proc GetDlgValues() {# Here are four ways to get settings out of the dialog. The extracted values are printed# to the console window as an example.
# 1 -- Use the GetValues() class method in GUI_DLG to get all of the control settings at#
at once. They are returned to a previously-declared instance of class GUI_FORMDATA.
#
Use GetValue...() methods in that class to read the values as needed.
printf("Method 1...\n");class GUI_FORMDATA data;18© 2003 MicroImages, Inc. 206 South 13th Street, Lincoln, Nebraska 68508-2010 www.microimages.com

TNT Products 6.8, 12 June 2003

Reference Guide to SML Dialog Specification in XML

data = dlg.GetValues();
printf(" RadioGroup value = %s\n", data.GetValueStr("radiogroup") );printf(" FirstName: %s\n", data.GetValueStr("fname") );printf(" Togglebutton numeric value = %d\n", data.GetValueNum("tbutton") );printf(" Togglebutton string value = %s\n\n", data.GetValueStr("tbutton") );# 2 -- Use GetCtrlValueNum() and GetCtrlValueStr() class methods in GUI_DLG to ask the#
dialog for each control value individually as needed. No GUI_FORMDATA class#instance is required. Less efficient than #1 if multiple control values are#needed. Internally it calls dlg.GetValues(), pulls out the one value asked for,#and discards the rest.
printf("Method2...\n");printf(" RadioGroup value = %s\n", dlg.GetCtrlValueStr("radiogroup") );printf(" FirstName: %s\n", dlg.GetCtrlValueStr("fname") );printf(" Togglebutton numeric value = %d\n", dlg.GetCtrlValueNum("tbutton") );printf(" Togglebutton string value = %s\n\n", dlg.GetCtrlValueStr("tbutton") );# 3 -- Use the GetCtrlByID() method in GUI_DLG to get the control handle for a control class,#then a GetValue...() method in the individual GUI_CTRL_... class to read the control#
value individually as needed.
printf("Method3...\n");class GUI_CTRL_EDIT_STRING fname;class GUI_FORM_RADIOGROUP radio;class GUI_CTRL_TOGGLEBUTTON tbutton;
fname = dlg.GetCtrlByID("fname");radio = dlg.GetCtrlByID("radiogroup");tbutton = dlg.GetCtrlByID("tbutton");printf(" RadioGroup value = %s\n", radio.GetSelected() );printf(" FirstName: %s\n", fname.GetValue() );printf(" Togglebutton numeric value = %d\n", tbutton.GetValueNum() );printf(" Togglebutton string value = %s\n\n", tbutton.GetValueStr() );# 4 -- A more compact (but perhaps less clear) version of method 3. Methods to get the control#
handle and its value are strung together, eliminating the need to declare the control handle#
class variable.
printf("Method 4...\n");printf(" RadioGroup value = %s\n", dlg.GetCtrlByID("radiogroup").GetValueStr() );printf(" FirstName: %s\n", dlg.GetCtrlByID("fname").GetValueStr() );printf(" Togglebutton numeric value = %d\n",dlg.GetCtrlByID("tbutton").GetValueNum() );printf(" Togglebutton string value = %s\n\n",dlg.GetCtrlByID("tbutton").GetValueStr() );# NOTE: if the control value must be accessed in several places, store it as a variable for# reuse. Values read from GUIFORMDATA or the dialog would be stored as numeric or string# variables.
} # end GetDlgValues()##### Main script #####
clear();# clear the console windowclass XMLDOC doc;
xmlfile$ = _context.ScriptDir + "/test.xml";
err = doc.Read(xmlfile$);# read and parse the dialog specification© 2003 MicroImages, Inc. 206 South 13th Street, Lincoln, Nebraska 68508-2010 www.microimages.com

19Reference Guide to SML Dialog Specification in XML

if (err < 0) {PopupError(err);
Exit();}TNT Products 6.8, 12 June 2003

# Popup an error dialog. "Details" button will say what's wrong.

class XMLNODE dlgnode;dlgnode = doc.GetElementByID("test");# get the dialog element from the# parsed XML

if (dlgnode == 0) {PopupMessage("Could not find dialog node in XML document");
Exit();}
dlg.SetXMLNode(dlgnode); # set the XML dialog element as the source for dialog class
dlg.SetCtrlValueStr("fname", "Fred");# set value for edittext control "fname"
dlg.SetCtrlValueStr("radiogroup", "button2");# set value for radiogroup control
ret = dlg.DoModal();# open as modal dialog# Note: ret will be -1 if user hit cancel, 0 for OK
printf("DoModal() returned %d\n", ret);

Dynamic Customization of Dialogs
In a script that launches a complex processing sequence, it may not be possible to bring all the required controls
together into one dialog window. In such cases, a push button on the main dialog window can be set up to open an
auxiliary dialog window that is also specified in XML. One example is provided by the sample script devegX.sml.
This script is designed to process a multispectral image to suppress the expression of vegetation. The script and acolor plate describing it are available from www.microimages.com/freestuf/xmlscripts.htm.

The illustration above left shows the main dialog window created by the devegetation script. A numeric Dark Pixel
value is required for each multispectral image band to be processed. To enter these values, the user presses the Set
dark pixel values... pushbutton on the main dialog window; the callback procedure for this button creates and opens
the auxiliary Set Dark Pixel Values window (above right). This window shows a list of the bands to be processed;

20© 2003 MicroImages, Inc. 206 South 13th Street, Lincoln, Nebraska 68508-2010 www.microimages.com

TNT Products 6.8, 12 June 2003

Reference Guide to SML Dialog Specification in XML

each entry consists of a label element (with the file name and object name) and an editnumber control, both ofwhich are contained in a layout pane with horizontal orientation.
Note that the file and object names required for the Set Dark Pixel Values dialog are not known in advance, andeven the number of bands to be processed is not fixed. Therefore only a skeletal representation of this dialog can beprovided by the embedded XML specification in the callback. This static specification sets up the dialog itself, thelabel at the top, the groupbox, and a blank layout pane within the groupbox. After the static specification isparsed into memory, the remaining elements of the dialog specification must be added dynamically to the XML
structure in memory, using information from the input objects the user has selected, before the dialog is opened.
Methods in the class XMLNODE are used to modify the XML dialog structure in memory. You can add a new"child" element to any existing element and set their attribute values. Any element of the static XML specificationthat needs to be modified later should have an id attribute so the element can be accessed. In this case the blanklayout pane inside the groupbox is assigned the id "dplist". To add each entry in the required list, a horizontal
pane is added as a child element to dplist. The new pane for the current entry then is used as the parent for a childlabel element and a child editnumber element, with attribute values derived from the corresponding input object.
The script excerpt below shows the first portion of the callback procedure, which includes the static XML
specification for the Set Dark Pixel Values dialog and the code that adds the first band entry to the window. The
other band entries are handled in a similar manner.
proc SetDP () {### Create string variable with XML specification of dialog### to enter dark-pixel-correction values
xmldp$ = '<?xml version="1.0"?><root><dialog id = "dpdlg" title = "Set Dark Pixel Values" OnOK = "dpOK()" ><label>Set Dark Pixel (Path Radiance)</label><label>Correction Values:</label><groupbox ExtraBorder = "3"><pane id = "dplist" Orientation = "Vertical"/></groupbox></dialog></root>';### Parse XML text for dialog into memory; return error if there are syntax errors.
err = docdp.Parse(xmldp$);
if ( err < 0 ) {PopupError( err );# pop up an error dialog
Exit( );}################################ Modify the XML structure in### memory before opening the dialog################################# Get the id for the parent pane that will contain the list of bands and the### numeric fields for the correction values
class XMLNODE dplist;
dplist = docdp.GetElementByID( "dplist" );© 2003 MicroImages, Inc. 206 South 13th Street, Lincoln, Nebraska 68508-2010 www.microimages.com

21

Reference Guide to SML Dialog Specification in XML

TNT Products 6.8, 12 June 2003########################### Add horizontal pane for the first row of dialog elements### (label and numeric field for NIR band)########################
class XMLNODE paneNIR;
paneNIR = dplist.NewChild( "pane" );paneNIR.SetAttribute( "Orientation", "Horizontal");# Add label with name of NIR band to the NIR paneclass XMLNODE labelNIR;
labelNIR = paneNIR.NewChild( "label" );nirprtext$ = sprintf("%s.%s \\ %s", FileNameGetName(nirfile$),FileNameGetExt(nirfile$), nirobjname$);labelNIR.SetText(nirprtext$);# Add editnumber field to the NIR pane and set its attributes
class XMLNODE prEditNIR;
prEditNIR = paneNIR.NewChild( "editnumber" );prEditNIR.SetAttribute( "id", "prEditNIR" );prEditNIR.SetAttribute( "Width", "5" );prEditNIR.SetAttribute( "MinVal", "0" );prEditNIR.SetAttribute( "MaxVal", "255" );prEditNIR.SetAttribute( "Default", NumToStr(nirmin) );prEditNIR.SetAttribute( "Precision", "0" );[...code for additional list entries...]}22# end of SetDP()© 2003 MicroImages, Inc. 206 South 13th Street, Lincoln, Nebraska 68508-2010 www.microimages.com