Promotic
WikipediaLinkedInYoutubeTwitterFacebook

SelectionDialog - method of object Pm

Description:
Enables to select the option from the list in the input box.
Syntax:
SelectionDialog(aOptions As Array, vSelected As Variant, sDlgTitle As String, sStyle As String, [oExtra As Object]) As Variant
Calling:
Pm.SelectionDialog(aOptions, vSelected, sDlgTitle, sStyle, oExtra)
Parameters:
aOptions(Array) 2-dimensional array with optionsi, where the rows represent each option and the columns the option items.
The first column (index 0) 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 data 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 Empty value meand, 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 item in the menu (e.g. empty string "" or non-existing identifier), no item will be selected as default.
sDlgTitle(String) Title of the window. Macro expression can be used for input ($.text ..) (it is evaluated while calling a method).
sStyle(String) The text list of the additional parameters for displaying the menu window. The parameters with assigned values are here separated by a semicolon. For example "ontop:1;grid:1;size:350,250;". The preset value is "ontop:0;grid:0;".
ontop:nn (optional) - Defines 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) - Defines 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) - 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 automaticaly and the returned value is of the String type (selected option identifier). If there is no option available, then the Empty value is returned.
oExtra[optional] (Object) Additional entry in the form of 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) User method is defined here and is called when the panel closes.

The object for this property is created by the Pm.CreatePmAction method.

This user method must have two parameters:

- oSystem: Object of the PmMap type. The properties of this object are set by system based on the source of calling. In such case the system sets the following properties:
- oSystem.CloseReason: (String) Window closing type identifier. Value "ok" means that an item has been selected in the window. Empty string ("") means that the window was closed without item selection (by pressing the "Cancel" button).
- oSystem.ReturnValue: (Variant) Selected item identifier (value in first column).
- oPrivate: Object of the PmMap type. The properties of this object are set by the designer in the PmAction.PrivateData object. The application designer does not have to set any property in this object. If some property is set the result can be for example that a single 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 Values:
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 is not set (i.e. the method is called synchronously) then the method returns:

<Empty> - If the window has been closed by the Cancel button, the returned value will be of the Empty type (it can be tested by the Pm.IsValid method).
<String> - If the window has been closed by the OK button, the returned value will be of the String type and contains 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. This means that the method ends before the item is selected. The selected item can then be detected in the method defined in oExtra.onClose parameter.

 
The method can also be called in the graphic item events for 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 e.g. 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 Object viewer open methods. The list is created by the Pm.FindViewers method in order to be displayed directly by the SelectionDialog method. See Example1 and Example2.
Example1:
Create a menu with a list of all PmPanel 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 when the user selects and confirms an item, the selected PmPanel object viewer will be opened.

It is supposed that the script is called in the graphic item event (e.g. in the onButtonUp event of PmiButton item).

Example for JavaScript language.

var oExtra = Pm.CreatePmMap();
oExtra.onClose = Pm.CreatePmAction(1, pMe, "CloseMethod");
var aOptions = Pm.FindViewers("groups:menu;viewers:panel;", "", "");
Pm.SelectionDialog(aOptions, "", "Panels", "size:400,300;", oExtra);
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 user 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:
Example2:
Menu of all alarm states (PmAlarmEvent) viewers 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:

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 user method onClose is not needed. The code is simpler but also not functional in some WEB browsers (e.g. Chrome).
Dim aOptions, sViewer
aOptions = Pm.FindViewers("groups:menu;viewers:panel;", "", "")
sViewer = Pm.SelectionDialog(aOptions, "", "Panels", "size:400,300;")
If Pm.IsValid(sViewer) Then
  pMe.PmPanel.OpenView sViewer, "", ""
End If
Example4:
Creating a user generated selection window using the two dimensional array. The first array index represents the window columns (the first identifier column is hidden). The second index represents the selection rows.

Example for JavaScript language.

var oExtra = Pm.CreatePmMap();
oExtra.onClose = Pm.CreatePmAction(1, pMe, "CloseMethod");
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);
var sId = Pm.SelectionDialog(aOptions, "id1", "Temperature selection", "ontop:1;grid:1;size:350,250;", oExtra);
Similar as in Example1 the script in "CloseMethod" user method is needed. This method may contain e.g. the following script:
Navigation:
 
- Pm
 
- Abs
- Cos
- E
- Exp
- LN2
- PI
- Pow
- SelectionDialog
 
 
- Sin
- Tan
© MICROSYS, spol. s r. o.Tavičská 845/21 703 00 Ostrava-Vítkovice