// set text string in text box object
function SetTextBox(text_box, value)
{
  text_box.value = value;
}

// retrieve text string in text box object
function GetTextBox(text_box)
{
  return text_box.value;
}

// set text string in spin box object
function SetSpinBox(spin_box, value)
{
  spin_box.SetValue(value);
}

// retrieve text string in spin box object
function GetSpinBox(spin_box)
{
  return spin_box.GetValue();
}

// check or uncheck check box
// Note: value parameter must be string "true" or "false"
function SetCheckBox(check_box, value)
{
  check_box.checked = GetBoolFromText(value);
}

// retrieve status of check box (checked or unchecked)
// Note: return value is string "true" or "false"
function GetCheckBox(check_box)
{
  return GetTextFromBool(check_box.checked);
}

// set ratio button's check on
// Note: parameter radio_buttons must be collection of radio buttons.
// The button with value property which matches with value parameter
// will be turned on.
function SetRadioButton(radio_buttons, value)
{
  for(var i = 0; i < radio_buttons.length; i++)
  {
    if(radio_buttons[i].value == value)
	  radio_buttons[i].checked = true;
  }
}

// retieve radio button's value among a collection of
// radio buttons specified.
function GetRadioButton(radio_buttons)
{
  for(var i = 0; i < radio_buttons.length; i++)
  {
    if(radio_buttons[i].checked)
	  return radio_buttons[i].value;
  } 
  return "";
}

// select item (option) which matches with value parameter in the list box.
// Note: single selection is assumed.
function SetListBox(list_box, value)
{
  var options = list_box.options;
  
  for(var i = 0; i < options.length; i++)
  {
    if(options[i].value == value)
	  list_box.options[i].selected = true;
  }
}

// retrieve selection in the list box.
function GetListBox(list_box)
{
  var options = list_box.options;
  
  for(var i = 0; i < options.length; i++)
  {
    if(options[i].selected)
	  return options[i].value;
  } 
  return "";
}

// select an item in the list by index (0, 1, 2...)
function SetListSelection(list_box, index)
{
  var options = list_box.options;
  var num_items = options.length;
  
  if(index < 0 || index > (num_items - 1))
    return;
	
  list_box.options[index].selected = true;
}

// retrieve selected item in the list
// by index (0, 1, 2...). -1 to indicate
// no selection.
function GetListSelection(list_box)
{
  var options = list_box.options;
  
  for(var i = 0; i < options.length; i++)
  {
    if(options[i].selected)
	  return i;
  } 
  return -1;
}

// clear selection of item in the list
function ClearListSelection(list_box)
{
  var items = list_box.options;
  var selected_item = GetListBox(list_box);
  var selected_id = GetListSelection(list_box);
  
  if(selected_id == -1)
    return;
	
  var el = document.createElement("OPTION");
  el.text = selected_item;
  el.value = selected_item;
  
  items.remove(selected_id);
  items.add(el, selected_id);
}

function GetNumOfListItems(list_box)
{
  var options = list_box.options;
  var num_items = options.length;
  
  return num_items;
}

// set all items in the list
// (previous items are removed)
function SetListItems(list_box, values)
{
  ClearListItems(list_box);
  AddListItems(list_box, values);
}

// add items specified in values array
// to the list
function AddListItems(list_box, values)
{
  if(values == null)
    return;
  
  for(var i = 0; i < values.length; i++)
    AddListItem(list_box, values[i], values[i]);
}

// add an item to the list
function AddListItem(list_box, text, value)
{
  var element = document.createElement("OPTION");
  element.text = text;
  element.value = value;
  list_box.options.add(element);
}

// set a list with items specified in an array
// elements whose value is "true"
function SetSelectedListItems(list_box, values)
{
  ClearListItems(list_box);
  AddSelectedListItems(list_box, values);
}

// add items specified in an array only if
// its value is "true"
function AddSelectedListItems(list_box, values)
{
  if(values == null)
    return;
	
  for(var value in values)
  {
    if(GetBoolFromText(values[value]))
	  AddListItem(list_box, value, value);
  }
}

// clear all items in the list
function ClearListItems(list_box)
{
  list_box.innerHTML = "";
}

// set checklist with an array of named elements,
// with each element's value is boolean text
// value ("true" or "false").
function SetCheckList(check_list, values)
{
  check_list.SetItemSelections(values);
}

// retrieve checked/unchecked status of all elements
// as an array of named elements, with each element's
// value is boolean text value ("true" or "false").
function GetCheckList(check_list)
{
  return check_list.GetSelections();
}

// set items in checklist with an array of named
// elements (but do not set check/uncheck status
// of each element.
function SetCheckListItems(check_list, items)
{
  check_list.SetItems(items);
}

// set check/uncheck status of elements with an array
// of named elements according to their values
// ("true" of "false").
function SetCheckListSelections(check_list, values)
{
  check_list.SetSelections(values);
}

// set check marks for an array of items whose
// values match items in the list.
function SelectCheckListItems(check_list, items)
{
  check_list.SelectItems(items)
}

// retrieve only items selected as an array of
// names of items.
function GetSelectedCheckListItems(check_list)
{
  return check_list.GetSelectedItems();
}

// put check marks on all elements in checklist
function SelectAllCheckListItems(check_list)
{
  check_list.SelectAll();
}

// clear check marks on all elements in checklist
function ClearAllCheckListItems(check_list)
{
  check_list.ClearAll();
}

// set enable/disable states of elements with an array
// of named elements according to their values
// ("true" of "false").
function SetCheckListEnableStates(check_list, items)
{
  check_list.SetEnableStates(items);
}

// retrieve enable/disable states of all elements
// as an array of named elements, with each element's
// value is boolean text value ("true" or "false").
function GetCheckListEnableStates(check_list, items)
{
  return check_list.GetEnableStates(items);
}

// set MS Date/Time Controller (configured to display Time) with
// specified value.
// Note: value must be in HH:MM:SS format.
function SetTimeBox(time_box, value)
{
  var values = value.split(":");
  
  if(values.length < 3)
    return;

  var hour = values[0];
  var minute = values[1];
  var second = values[2];
  
  if(hour < 0 || hour > 24)
    return;
  if(minute < 0 || minute > 59)
    return;
  if(second < 0 || second > 59)
    return;
		
  time_box.hour = hour;
  time_box.minute = minute;
  time_box.second = second;
}

// retrieve Time value in MS Date/Time Controller
function GetTimeBox(time_box)
{  
  var time_value =
    time_box.hour + ":" + time_box.minute + ":" + time_box.second; 
  return time_value;
}

// set MS Date/Time Controller (configured to display Date) with
// specified value.
// Note: value must be in MM/DD/YYYY format.
function SetDateBox(date_box, value)
{
	var values = value.split("/");
  
	if(values.length < 3)
		return;
	var month = values[0];
	var day = values[1];
	var year = values[2];
 
	if(month < 1 || month > 12)
		return;
	if(day < 1 || day > 31)
		return;
			
	date_box.month = month;
	date_box.day = day;
	date_box.year = year;
}

// retrieve Date value in MS Date/Time Controller
function GetDateBox(date_box)
{
  var date_value =
    date_box.month + "/" + date_box.day + "/" + date_box.year;
  return date_value;
}

// set check boxes next to selected folder in custom made
// folder tree control.  values must be in an array.
// this function presumes that control accepts set of paths
// delimited by '|' character.
function SetFolderTree(folder_tree, values)
{
  if(values == null)
    return;

  var paths = "";
  for(var i = 0; i < values.length; i++)
  {
    // remove appended '*' from each path
	var num_ch_to_keep = values[i].length - 1;
    var val = values[i].slice(0, num_ch_to_keep);
    paths += val;
	
	if(i < values.length - 1)
	  paths += "|";
  }
  
  folder_tree.paths = paths;
}

function SetSearchTextBox(search_text_box, value)
{
  search_text_box.SetValue(value);
}

function GetSearchTextBox(search_text_box)
{
  return search_text_box.GetValue();
}

// retrieve all selected paths from custom made
// folder tree control.  paths is returned as an array.
// this function presumes that control returns set of paths
// delimited by '|' character.
function GetFolderTree(folder_tree)
{
  var path_str = folder_tree.paths;
  var paths = path_str.split("|");

  // append '*' to each path  
  for(var i = 0; i < paths.length; i++)
    paths[i] += "*";
	
  return paths;
}

// get user readable (space delimited) text string from underscore delimited
// character string.
// Example: "Time_Of_Day" -> "Time Of Day"
function GetSpacedText(text)
{
  var new_text = "";

  for(var i = 0; i < text.length; i++)
  {
    var ch = text.charAt(i);
	if(ch == '_')
	  ch = ' ';
	new_text  += ch;
  }
  
  return new_text; 
}

// get user readable (space delimited) text string from mixed character string.
// Example: "TimeOfDay" -> "Time Of Day"
function GetMixedSpacedText(text)
{
  var new_text = "";
  var new_index = 0;

  for(var i = 0; i < text.length; i++)
  {
    var ch = text.charAt(i);
    if(i != 0 && ch < 'a')
	  new_text += " ";
	new_text  += ch;
  }
  
  return new_text; 
}

// get underscore delimited text string from space delimited string.
// Example: "Time Of Day" -> "Time_Of_Day"
function GetDelimitedText(text)
{
  var new_text = "";
  
  for(var i = 0; i < text.length; i++)
  {
    var ch = text.charAt(i);
	if(ch == ' ')
	  ch = '_';
	new_text += ch;
  }
  
  return new_text;
}

// retrieves boolean value from textual value ("true" or "false")
function GetBoolFromText(text)
{
  if(text == "true")
    return true;
  else
    return false;
}

// retrieves textual value ("true" or "false" from boolean value
// (true or false)
function GetTextFromBool(value)
{
  if(value == true)
    return "true";
  else
    return "false";
}

// get collection of objects from single element or
// collection.  This method is useful when, for example,
// call "document.all.my_elements" to get collection.
// If only one element of "my_elements" exists, it returns
// element itself (not a collection).  GetCollection()
// converts it to collection.  If "my_elements" is already
// collection, just return it.
function GetCollection(elements)
{
  var collection = null;
  
  if(elements == null)
  {
    // if no elements in it,
	// create collection with
	// no elements.
    collection = new Array();
  }
  else if(elements.length == null)
  {
    // if single element, create
	// collection with just one
	// element.
    collection = new Array();
	collection[0] = elements;
  }
  else
  {
    // if elements is collection,
	// leave it alone.
    collection = elements;
  }
	
  return collection;
}

// methods to substitute special characters in XML.
// used within HTML page scripts to escape characters 
// '<', '>', and '&' (localization consideration).

function LtCh()
{
  return '<';
}

function GtCh()
{
  return '>';
}

function AmpCh()
{
  return '&';
}

function Tag(tag_name)
{
  return '<' + tag_name + '>';
}

function NbspCh()
{
  return "&nbsp;";
}

// string comparison methods
// compares two strings but ignore differences
// in number of space characters between substrings
function CompareStrings(text1, text2)
{
  var result1 = text1.match(/\S+/g);
  var result2 = text2.match(/\S+/g);
  
  // possible empty == empty case
  if(result1 == result2)
    return true;
	
  if(result1 == null || result2 == null)
    return false;
	
  if(result1.length != result2.length)
    return false;
	
  for(var i = 0; i < result1.length; i++)
  {
    if(result1[i] != result2[i])
	  return false;
  }
  return true;
}
