Promotic

SelectionDialog - method of the Pm object

Description:
It allows to select the one option from the list in the input window.
This method is obsolete (but functional) and it is better to use the Pm.CreateView method - see Opening the viewer for option selection (/#glob/list).
Syntax:
Variant SelectionDialog(Array aOptions, Variant vSelected, String sDlgTitle, String sStyle, [Object oExtra])
Parameters:
aOptions(Array) 2-dimensional array with options, where the rows represent each option and the columns the option items. See (Col,Row) - 2-dimensional array meaning an array of rows.
The first column (zero-based index) is not displayed by the menu (it is invisible) and contains the identifiers of each option. The next columns are displayed in the menu. The menu has a table layout, having one column less than the used 2-dimensional array.
The first row may (not necessarily) contain the header with column titles (localized user names) in the menu. If the first row is to contain the header, then in the first column (invisible, reserved for identifiers) there must be a string with $title value.
vSelected(Variant) The identifier of the item that will be selected as default.
The value null for JavaScript or Empty for VBScript means that no item will be selected as default.
The String value represents identifier of the item, that will be selected as default. If there is no such option in the menu (e.g. empty string "" or non-existing identifier), then no item will be selected as default.
sDlgTitle(String) Title of the input window. Macro expression can be used for input ($.text ..) (it is evaluated when calling a method).
sStyle(String) Additional parameters for displaying the menu window. Entries are in the KeyVal format, for example "ontop:1;grid:1;size:350,250;".
The default value is "ontop:0;grid:0;".
ontop:nn (optional) - Specifies whether the window will be "Always on top".
0 (default) - The window will not be "Always on top".
1 - The window will be "Always on top".
grid:nn (optional) - Specifies whether the cells of displayed table will have borders.
0 (default) - have no borders.
1 - have borders.
size:dx,dy (optional) - The dimensions of the window (in pixels).
autoselect:nn (optional) - It allows to use the mode which is not requesting user input unless necessary. The window is not displayed.
0 (default) - the window will always be displayed.
1 - The window will be displayed only if there are at least two possible options.
If only a single option is available, then it is selected automatically and the method returns value of the String type (selected option identifier).
If there is no option available then the method returns: null for JavaScript or Empty for VBScript (it can be tested by the Pm.IsValid method).
oExtra[optional] (Object) Additional entry in the form of the PmMap object.
If the entry is present (recommended), then the method is called asynchronously, otherwise the method is called synchronously (see Synchronous or asynchronous calling).
The object is created by the Pm.CreatePmMap method.
This parameter has similar function as the oExtra parameter of the OpenView method.

oExtra.onClose (mandatory) - (object of the PmAction type) Designer's method is defined here and is called when the panel closes.
The object for this property is created by the Pm.CreatePmAction method.
This designer's method must have two parameters:
- oSystem: Object of the PmMap type. Properties of this object are set by system based on the source of calling. In this case the system sets the following properties:
- oSystem.CloseReason: (String) Window closing type identifier. The value "ok" means that an item has been selected in the window. Empty string ("") means that the window was closed without item selection (by the "Cancel" button).
- oSystem.ReturnValue: (Variant) Selected item identifier (value in first column).
- oPrivate: Object of the PmMap type. Properties of this object are set by the designer in the PmAction.PrivateData object. The designer does not have to set any property in this object. If some property is set the result can be for example that a one designer's method can be used for multiple purposes based on the value of the property in PrivateData it can be recognised where was the method called from.
Return value:
If the oExtra parameter is set (i.e. if the method is called asynchronously - recommended), then the method does not return any data.
If the oExtra parameter is not set (i.e. if the method is called synchronously), then:
- If the window has been closed by the "Cancel" button, then the method returns: null for JavaScript or Empty for VBScript (it can be tested by the Pm.IsValid method).
- If the window has been closed by the "OK" button, then the method returns String (the identifier of the selected item).
Note:
Synchronous or asynchronous calling:
If the method is called synchronously (i.e. if the oExtra parameter is not set), then the script in this method stops and waits until the item in the dialog is selected and the window is closed. Then this method returns the selected item. Unfortunately this approach is not supported on the Web by some browsers (e.g. Chrome) and therefore it is not recommended.
If the method is called asynchronously (i.e. if the oExtra parameter is set), then the script in the method does not stop. It just opens the window and goes on. It means that the method ends before the item is selected. The selected item can then be detected in the method defined in the oExtra.onClose parameter.

This method is also functional in Web panels. Some browsers (e.g. Chrome) do not support synchronous calling (i.e. if the oExtra parameter is not set).

The method is suitable for example for displaying the menu, prepared by the Pm.FindViewers method. This method has been designed in order to let the designer create a menu with a list of object viewers, that can be opened by methods Opening the viewer. The list is created by the Pm.FindViewers method in order to be displayed directly by the SelectionDialog method. See Example1 and Example2.
Example1:
Creates a menu with a list of all PmaPanel object viewers in the menu logical group. The menu will contain the first row with generated column names column names. Then the menu is displayed and if the user selects and confirms an item, then the selected PmaPanel object viewer will be opened.
It is supposed that the script is called in the Pmg object event (e.g. in the onButtonUp event of the PmgButton object).
JavaScriptVBScriptSelect and copy to clipboard

var oExtra = Pm.CreatePmMap();
oExtra.onClose = Pm.CreatePmAction(1, pMe, "ClosePanel");
var aOptions = Pm.FindViewers("groups:menu;viewers:panel;", "", "");
Pm.SelectionDialog(aOptions, "", "Panels", "size:400,300;", oExtra);
The window showing a list of panels opens and the system is waiting for the user to select a panel. The script continues to go. Once the user selects the panel the designer's method "CloseMethod" is called (with parameters oSystem and oPrivate). Path to selected panel is stored in the oSystem.ReturnValue property. A script for opening the selected panel can be in this method:
JavaScriptVBScriptSelect and copy to clipboard

if ("ok" == oSystem.CloseReason)
{
pMe.PmPanel.OpenView(oSystem.ReturnValue, "", "");
}
Example2:
Menu of all alarm states viewers (PmaAlarmGroup) with a detailed list of alarms counts in each possible alarm state in the additional columns.
The example is similar as Example1 with following differences:
JavaScriptVBScriptSelect and copy to clipboard

var oExtra = Pm.CreatePmMap();
oExtra.onClose = Pm.CreatePmAction(1, pMe, "ClosePanel");
var aOptions = Pm.FindViewers("groups:menu;viewers:alarm_state;", "", "columns:path,title,alstate3,alstate2,alstate1,alhoot;");
Pm.SelectionDialog(aOptions, "", "Alarms", "size:400,300;", oExtra);
Example3:
Similar as Example1 but for VBScript language and using synchronous calling. Therefore the designer's method onClose is not needed. The code is simpler but is not functional in some Web browsers (e.g. Chrome).
VBScriptSelect and copy to clipboard

Dim aOptions
aOptions = Pm.FindViewers("groups:menu;viewers:panel;", "", "")
Dim sViewer
sViewer = Pm.SelectionDialog(aOptions, "", "Panels", "size:400,300;")
If Pm.IsValid(sViewer) Then
pMe.PmPanel.OpenView sViewer, "", ""
End If
Example4:
Creates a selection window using the 2-dimensional array.
The first array index represents the window columns (the first column of identifiers is hidden).
The second array index represents the selection rows.
JavaScriptVBScriptSelect and copy to clipboard

var sId;
var oExtra = Pm.CreatePmMap();
oExtra.onClose = Pm.CreatePmAction(1, pMe, "ClosePanel");
var aOptions = Pm.CreatePmArray().Create(3,4);

aOptions.SetItem("$title", 0, 0);
aOptions.SetItem("Name", 1, 0);
aOptions.SetItem("Description", 2, 0);
aOptions.SetItem("id0", 0, 1);
aOptions.SetItem("T1", 1, 1);
aOptions.SetItem("Temperature 1", 2, 1);
aOptions.SetItem("id1", 0, 2);
aOptions.SetItem("T2", 1, 2);
aOptions.SetItem("Temperature 2", 2, 2);
aOptions.SetItem("id2", 0, 3);
aOptions.SetItem("T3", 1, 3);
aOptions.SetItem("Temperature 3", 2, 3);
sId = Pm.SelectionDialog(aOptions, "id1", "Temperature selection", "ontop:1;grid:1;size:350,250;", oExtra);
Similar as in Example1 the script in designer's method "CloseMethod" is needed. This method may contain e.g. the following script:
JavaScriptVBScriptSelect and copy to clipboard

if ("ok" == oSystem.CloseReason)
{
Pm.MessageBox("Title", oSystem.ReturnValue);
}

History:
Pm9.00.09: This method is obsolete (but functional).
Pm8.03.14: Web panels - Generalization for oExtra parameter that can be entered action to be executed after the selection window is closed. In this case the method is called asynchronously (i.e. does not stop and wait for the window to be closed).
This implementation allows functionality of this method also in the Chrome Web browser (this browser does not allow synchronous opening of modal windows).
Pm8.00.12: In the Web panel in InternetExplorer 9 displayed incorrect selection window.
Pm8.00.00: Created
PROMOTIC 9.0.27 SCADA system documentation MICROSYS, spol. s r.o.

Send page remarkContact responsible person
Navigation:
 
- Pm
 
- Abs
- Cos
- E
- Exp
- LN2
- PI
- Pow
- SelectionDialog
 
 
- Sin
- Tan
© MICROSYS, spol. s r.o.