The UI

Question

In the script documentation and in a few articles we have described how a script may utilize the "selection" as an input from the user. However, sometimes its requires to collect further input from the user or offer some options or just let him select an input or output file. These kind of user interactions are key to write interactive scripts with at least some kind of user interface. To support that, we have started some effort to provide at least a simple and static UI API, basically concentrating on opening various standard dialogues, like text input or file selection.

Attached to this article you will find a first version of the "ui.js" library that - as other articles here - provides an initial API as a script that you can build on and experiment with and in best case comment and help to improve.

The library offers basically three simple dialog functions:

1: openFile(extension) - to open the file dialog

The only expected argument is an array of valid file extensions, for example

var file = openFile(["*.jpg", "*.img"]);

2: inputText(title, message, initialValue, validator) - to open an input dialog for a single line text input

Arguments should be self explanatory, at least the first three. The last one is optional and may specify a function to validate the input, returning null for okay or any string if not okay (used as the error message).

3. selectOption(title, message, buttons) - to show an option dialog with multiple buttons a user may press

The last argument is an array of options so for example:

var option = selectOption("Your Choise", "Do you want to XXX?", ["Yes", "Hmm", "Maybe"] );

Apart from these rather straight dialog functions the library also offers a sophisticated function to select an element. The function is defined as:

4. selectElement(title, type, multiple, root) - to select one or more elements

Type is a metaclass while "multiple" can be set to true to allow multi-selection in the dialog. The last argument is optional. If it is not given, the dialog will by default use the project as the scope to offer the selection from, same as the tool typically does. However, the script may pass an array of objects here to limit the scope of potential objects to just that array. For example:

// select among packages that are named "Hardware"
var target = selectElement("Target", 
 Metamodel.projectmodel.PJPackage,
 false, finder.findByType(Metamodel.projectmodel.PJPackage).and("name", "Hardware").toArray());

Attached to this article there is also an example file which illustrates the usage of the library as well.

Happy Scripting

Jan

medini_1024169437 · Answer

Thanks Todd for contributing!

Jan

medini_1064792687 · Answer

Helpful to point out that root parameter of selectElement can be an array to expand the selection criteria.

Here's an example with a function I created that lets me easily switch between a single select source and a multi-select destinations:

function getSourceDestination(selectionType, multiSelect, selectionScope) {
 if (selectionScope instanceof Metamodel.sysml.SysMLContainerPackage) {
 var target = selectElement(
 selectionType,
 [Metamodel.sysml.SysMLPart, Metamodel.sysml.SysMLPort],
 multiSelect,
 selectionScope
 );
 }
 return target;
}

The second argument to selectElement is the array [Metamodel.sysml.SysMLPart, Metamodel.sysml.SysMLPort] so that I get parts and ports in my selection list.

Had to poke around the selectElement source to find this was possible.

medini_1024169437 · Answer

Hi Tony,

the second argument was named "filterPath" which is a bit misleading. It reflects the original API which we are using here that is misleading too :-) As you may have guested, its the initial folder that is selected in the dialog so I changed that to "initialPath". Secondly there was a bug actually in the function code - that's fixed now too. An example would look like:

// open a directory (a folder on file system)
	var folder = openDirectory("Please select an output filter", "C:\Temp");
	if (folder) {
		// result is of type java.io.File
		console.log("The user selected {0} as output folder, can write: {1}", folder.name, folder.canWrite());
	}

I'll update library and test sample on the overview page too, including your contribution :-)

Happy Scripting

Jan