====== Multi Selection List Box ======

List box control with ability to select several items.
{{ :scripting:dialogs:multi-list-box.png?150|Multi-ListBox example}}


===== Properties =====

^ Property     ^ Default Value   ^ Description    ^
| **id**    | empty | id (name) of the script data object associated with control |  
| **align**    | stretched | [[scripting:dialogs:align|Alignment]] of the control |  
| **required**    | false | required property of the control (if control is initial, "positive" buttons will be disabled) |  
| **minwidth**    | 12 | Minimum width, in characters of the list box control |  
| **extended_sel**  | false          | Extended Selection mode (previous selection is reset, if Ctrl is not pressed)       |

===== Items =====
List Box is filled by //Items//. Initial selection state for items can be set statically in-line or dynamically using associated by //id// script variable (VB Array of integers, use [[scripting:dialogs:ax2js|ax2js]] function to convert from JS array). If you pass dynamic content and define static selection, static one is ignored.

==== Item ====

^ Property     ^ Default Value   ^ Description    ^
| **text**    | empty | Item text |  
| **selected** | false | Item selected state |  

===== Example =====

<file javascript multi-list-box.hejs>
#include "he_utils.js"	// this is include file
 
var varStorage = new Storage();

// dynamically mark as selected first and third items 
// (function js2ax as ax2js defined in he_utils.js)
// value passed as part of variable storage 
varStorage.dynamic_list = js2ax(new Array(0,2));

// passing selection state using global script variable
// in this case using of Storage object is not needed
var global_dynamic_list = js2ax(new Array(1,3));

var dialog_template =
'@<dialog title="Test dialog" resizable="true" contexthelp="true" id="testdlg"> \
	<multi_listbox extended_sel="true" minwidth="24" id="global_dynamic_list"> \
		<item text="Item 1"/> \
		<item text="Item 2"/> \
		<item text="Item 3"/> \
		<item text="Item 4"/> \
		<item text="Item 5"/> \
		<item text="Item 6"/> \
		<item text="Item 7"/> \
	</multi_listbox> \
	<multi_listbox align="right" id="dynamic_list"> \
		<item text="Item 1"/> \
		<item text="Item 2"/> \
		<item text="Item 3"/> \
		<item text="Item 4"/> \
		<item text="Item 5"/> \
		<item text="Item 6"/> \
		<item text="Item 7"/> \
	</multi_listbox> \
	<multi_listbox extended_sel="true" align="left" id="static_list" required="true"> \
		<item text="Item 1" selected="true"/> \
		<item text="Item 2"/> \
		<item text="Item 3"/> \
		<item text="Item 4" selected="true"/> \
		<item text="Item 5"/> \
		<item text="Item 6"/> \
		<item text="Item 7" selected="true"/> \
	</multi_listbox> \
	<group uniform="true" align="right"> \
		<button title="&amp;OK" returnval="ok" default="true"/> \
		<button title="&amp;Cancel" returnval="cancel"/> \
	</group> \
</dialog>@';
 
// show dialog using dialog template and variables storage for passing initial data
var returnCode = dialog(dialog_template, varStorage);

Output().Clear();

// after closing of the dialog variable storage (varStorage) contains all states 
// of the controls (which has variable id connected) 
Output().writeln("Dialog returns: " + returnCode);
 
// evaluate here returnCode (returnval of selected button) and decide if varStorage shall be evaluated
if ( returnCode == "ok" ) { 
	// convert VB array to JS array and output it
	Output().writeln("Global dynamic list selection: " + ax2js(global_dynamic_list));
	Output().writeln("Dynamic list selection: " + ax2js(varStorage.dynamic_list));
	Output().writeln("Static list selection: " + ax2js(varStorage.static_list));
}
</file>

===== Dynamic content =====
Creating content dynamically is not straightforward, but possible by generating of the static template in script.

<file javascript multi-list-box-dynamic-content.hejs>
#include "he_utils.js"	// this is include file
 
var varStorage = new Storage();

var dialog_template =
'<dialog title="Test dialog" resizable="true" id="testdlg">\r\n \
 <multi_listbox extended_sel="true" minwidth="24" maxheight=8 id="dynamic_content_list">';

for(var nItem = 0; nItem < 100; ++nItem)
  dialog_template += '\r\n' + '    <item text="Item ' + nItem + '"/>';

dialog_template += '\r\n' + '  </multi_listbox> \
\r\n  <group uniform="true" align="right"> \
\r\n    <button title="&amp;OK" returnval="ok" default="true"/> \
\r\n   <button title="&amp;Cancel" returnval="cancel"/> \
\r\n  </group> \
\r\n</dialog>';
 
Output().Clear();

// show dialog using dialog template and variables storage for passing initial data
Output().writeln("Dialog returns: " + dialog(dialog_template, varStorage));
 
// evaluate here returnCode (returnval of selected button) and decide if varStorage shall be evaluated
Output().writeln("Dialog template:");
Output().writeln(dialog_template);

// convert VB array to JS array and output it
Output().writeln("List selection: " + ax2js(varStorage.dynamic_content_list));
</file>