Introduction to SDialog class

Creating a custom form in script can be achieved through the use of the SDialog class.
It is done in three steps:

Create a SDialog object and set a title
Populate the dialog content with components
Execute the dialog then check the error code and the user field values.

Components

SDialog supports several types of components depending on your use case.

Component	Methods
Input text	SDialog.AddTextField
Boolean value (checkbox)	SDialog.AddBoolean
List of strings (combo box or radio buttons)	SDialog.AddChoices
Message	SDialog.AddText
Image	SDialog.AddImage
Numerical values (without unit)	SDialog.AddInt, SDialog.AddFloat
Length	SDialog.AddLength
Angle	SDialog.AddAngle
3D point coordinates	SDialog.AddPoint
3D vector coordinates	SDialog.AddVector

Note

The point and vector results are returned in WCS
Lengths are returned in the document unit
Angles are returned in degrees.

Attributes

Each component supports attributes allowing to customize the behavior and add constraints to improve the user experience.
Refer to each component documentation to additional details.

Attribute	Description	Optional
`id`	Internal unique key you will have to call to use the result	No
`name`	Text you will see in the dialog next to the component. Like the button title, field label, etc.	No
`tooltip`	Text displayed when hovering over a component.	Yes
`choices`	Table of strings: one for each choice.	No
`value`	The default value of the component.	Yes
`saveValue`	To specify whether the component value is replaced by the last value given by the user at startup.	Yes
`readOnly`	To specify if the user can edit the component or not. Consequently, the component can only display a value.	Yes
`min/max`	To restrain the range of numerical components, such as length.	Yes
`canBeEmpty`	To specify whether a field can be empty or not. If false, and empty field will turn to red and dialog buttons will be disabled.	Yes

As an example, here is a code sample to insert an angle field to an existing dialog:

var errorCodeAngle = myDialog.AddAngle({ 
    id: "key_Angle", 
    name: "Angle", 
    tooltip: "Define an angle between 0 and 360 degrees.", 
    value: 90, 
    saveValue: true, 
    min: 0, 
    max: 360
    });
 
if(errorCodeAngle.ErrorCode)
    print("Error the parameter couldn't be inserted.");

General layout

The layout of a dialog is composed of three main areas: a header, a body and a buttons area.

Header

This area allows to place some context or general instructions to the user.
By default, there is no header. It can be inserted by calling SDialog.SetHeader.
Optionally, a logo can be inserted next to the text.

Body

The main area of the dialog where all components are inserted in group.
By default, only one group is created to store all components.
Custom groups can be added through SDialog.BeginGroup.

Dialog buttons

This area contains all validation buttons of the dialog (OK, Cancel, etc.).
Any of these buttons will stop the execution of the SDialog.Run method once it has been clicked.
By default, OK and Cancel buttons are inserted. For specific cases, use SDialog.SetButtons.

Modal popup

SDialog provides also two preset popups for informing the user (SDialog.Message) or for asking the user a question (SDialog.Question).

var answer = SDialog.Question("Do you want to continue?", "Current step");
if(answer == true)
{
    // continue...
}

Running the form

Once your form is created and configured, you must call SDialog.Run to execute and show it.
Then the script execution will wait for the user to click a button from the dialog button area to continue the execution.
The output result will contain an error code corresponding to the clicked button and the fields declared as inputs("id").

Full sample

The following example describes how to instantiate a form and fill it with the most common components:

//Manage user coordinate systems and project unit
var currentUCSMatrix=SMatrix.FromActiveCS();
var scaleFactor=GetScaleFactor().Value;//from document unit to mm
 
//Create a new empty dialog form
var myDialog=SDialog.New("New dialog");
 
//Fill the dialog
myDialog.SetHeader("Welcome message", "C:\\Program Files\\Leica Geosystems\\Cyclone 3DR\\addons\\Help\\favicon.ico", 15);
 
myDialog.BeginGroup("Image and message group");
myDialog.AddText("Give any instruction or warning to the user",SDialog.EMessageSeverity.Info);
var addImageFeedBack=myDialog.AddImage("C:\\Program Files\\Leica Geosystems\\Cyclone 3DR\\addons\\Help\\spacelogo.png",-1,35,true);
if(addImageFeedBack==false) 
    print("Error when adding an image to the dialog");
 
myDialog.BeginGroup("Input values");
 
myDialog.AddAngle({ 
    id: "InputAngle", 
    name: "Angle", 
    tooltip: "The angle to set", 
    value: 90, 
    saveValue: true, 
    readOnly: false, 
    min: 0, 
    max: 360});
 
myDialog.AddLength({ 
    id: "InputLength", 
    name: "Length",
    tooltip: "The Length to set", 
    value: 10, 
    saveValue: true, 
    readOnly: false, 
    min: 0, 
    max: 100});
 
myDialog.AddInt({
    id: "InputInteger",
    name: "Integer",
    tooltip: "The integer value to set",
    value: 5, 
    saveValue: true, 
    readOnly: false, 
    min: 1, 
    max: 10});
 
myDialog.AddFloat({
    id: "InputFloat",
    name: "Float",
    tooltip: "The float value to set",
    value: 5.1, 
    saveValue: true, 
    readOnly: false, 
    min: 0, 
    max: 1000 });
 
myDialog.AddTextField({
   id: 'InputText',
   name: 'Text',
   tooltip : "The text value to set",
   value : 'Default text',
   saveValue : true,
   readOnly: false,
   canBeEmpty : false})
 
myDialog.AddPoint({ 
    id: "InputPoint", 
    name: "Point", 
    tooltip: "The point to set", 
    saveValue: true, 
    value: SPoint.New(0,0,0), 
    readOnly: false});
 
myDialog.AddVector({ 
    id: "InputVector",
    name: "Vector",
    tooltip: "The vector to set",
    value: SVector.New(0,0,1),
    saveValue: true, 
    readOnly: false});
 
myDialog.BeginGroup("Input choices");
 
myDialog.AddBoolean({
    id: "InputBoolean",
    name: "Boolean",
    tooltip: "The boolean to set",
    value: true,
    saveValue: true, 
    readOnly: false });
 
myDialog.AddChoices({
    id: "InputChoice1",
    name: "Choice 1",
    choices: ["A","B","C"],
    tooltip: "Choose between A, B and C",
    value: 0, 
    saveValue: true, 
    readOnly: false,
    style: SDialog.ChoiceRepresentationMode.RadioButtons});
 
myDialog.AddChoices({
    id: "InputChoice2",
    name: "Choice 2",
    choices: ["a", "b", "c", "d"],
    tooltip: "Choose between a, b, c and d",
    value: 0, 
    saveValue: true, 
    readOnly: false,
    style: SDialog.ChoiceRepresentationMode.ComboBox});
 
myDialog.SetButtons(["Additional question","Watch results","Cancel"]);
 
//Display the dialog
var dialogResults=myDialog.Run();
 
//Read the results
switch(dialogResults.ErrorCode){
    case 0: //Additional question, then Watch results
        var myPopupAnswer=SDialog.Question("Did you ask for an additional question?","Question popup");  
    case 1: //Watch results
        var results="The results are:\n";
 
        results+="Angle: "+dialogResults.InputAngle+"degree"+"\n";
        results+="Angle: "+dialogResults.InputAngle*200/180+"gon"+"\n";
 
        var lengthInDocumentUnit = dialogResults.InputLength; // in document unit
        var lengthInmm=lengthInDocumentUnit*scaleFactor; //in mm
        results+="Length: "+lengthInDocumentUnit+"(document unit)"+"\n";
        results+="Length: "+lengthInmm+"(mm)"+"\n";
 
        results+="Integer: "+dialogResults.InputInteger+"\n";
 
        results+="Float: "+dialogResults.InputFloat+"\n";
 
        results+="Text: "+dialogResults.InputText+"\n";
 
        var pointInWCS = dialogResults.InputPoint; // point is given in WCS
        var pointInUCS=SPoint.New(pointInWCS);
        pointInUCS.ApplyTransformation(currentUCSMatrix); // same point given in UCS
        results+="Point: "+pointInWCS.ValuesToString()+"(WCS)"+"\n";
        results+="Point: "+pointInUCS.ValuesToString()+"(UCS)"+"\n";
 
        var vectorInWCS = dialogResults.InputVector; // vector is given in WCS
        var vectorInUCS=SVector.New(vectorInWCS);
        vectorInUCS.ApplyTransformation(currentUCSMatrix); // same vector given in UCS
        results+="Vector: "+vectorInWCS.ValuesToString()+"(WCS)"+"\n";
        results+="Vector: "+vectorInUCS.ValuesToString()+"(UCS)"+"\n";
 
        results+="Boolean: "+dialogResults.InputBoolean+"\n";
        results+="Radiobuttons Choice1: "+dialogResults.InputChoice1+"\n";
        results+="Combolist Choice2: "+dialogResults.InputChoice2;
        if(myPopupAnswer!=undefined)          
            results+="\n"+"Additionnal question: "+myPopupAnswer;
 
        var myPopupResults=SDialog.Message(results, SDialog.EMessageSeverity.Success, "Results popup");
        break;
    case 2: //Cancel
        break;
    default: //The dialog has been closed
        break;
}

This code should display this dialog:

Table of Contents