// ComboBox.jsl
// Roger C. Garrett


// FUNCTIONS:
//
//		ComboBox.addItem(comboBoxId, displayText, relatedReturnValue)
//		ComboBox.empty(comboBoxId)
//		ComboBox.getSelectedIndex(comboBoxId)
//		ComboBox.getSelectedText(comboBoxId)
//		ComboBox.getNumberOfItems(comboBoxId)
//		ComboBox.setSelectedIndex(comboBoxId, desiredIndex)
//		ComboBox.selectItemNext(comboBoxId)
//		ComboBox.selectItemPrevious(comboBoxId)
//

// A dummy contructor, just so we can have functions like ComboBox.addItem().
// It's essentially a way of making the functions part of a "class", eventhough JavaScript
// doesn't really have classes.
function ComboBox()
{
}

function ComboBox.addItem(comboBoxId, displayText, relatedReturnValue)
{
	// Parameters:
	//		comboBoxId		The text string specifying the identifier of the combo box to be referenced.
	//		displayText		The text of the item to be added to the combo bx. This is the text that will
	//						be displayed in the combo box for the item. 
	//		relatedReturnValue	The text string of the value to be returned when the user selects this
	//						this item from the combo box.
	//						If this relatedReturnValue is not specified, it defaults to be the same as
	//						the displayText.
	
	if (comboBoxId == null)
	{
		reportNullObject("AddItem(comboBoxId, displayText, relatedReturnValue)", "comboBoxId");
		return false;
	}

	if (relatedReturnValue == null)
	{
		relatedReturnValue = displayText;
	}
	
	// Get the combo box.
	var theComboBox = document.getElementById(comboBoxId);
	if (theComboBox == null)
	{
		reportNullObject("AddItem(comboBoxId, displayText, relatedReturnValue)", "theComboBox");
		return false;
	}

	// Create an Option object.
	var option = document.createElement("option");
	
	if (option == null)
	{
		reportNullObject("AddItem(comboBoxId, displayText, relatedReturnValue)", "option");
		return false;
	}

	// Assign text and value to Option object
	option.text = displayText;
	option.value = relatedReturnValue;
	
		// Add the option object to Drop Down/List Box.
	theComboBox.options.add(option);
	
	return true;
}

function ComboBox.empty(comboBoxId)
{
	// Parameters:
	//		comboBoxId		The text string specifying the identifier of the combo box to be referenced.

	// Empties the combo box of all entries.
	// returns true if successful, false if not.

	if (comboBoxId == null)
	{
		reportNullObject("ComboBox.empty(comboBoxId)", "comboBoxId");
		return false;
	}

	// Get the combo box.
	var theComboBox = document.getElementById(comboBoxId);
	if (theComboBox == null)
	{
		reportNullObject("ComboBox.empty(comboBoxId)", "theComboBox");
		return false;
	}
	
	theComboBox.length = 0;
}

function ComboBox.getSelectedIndex(comboBoxId)
{
	// Parameters:
	//		comboBoxId		The text string specifying the identifier of the combo box to be referenced.

	// Returns the index of the selected item, or -1 if an error occurs.

	if (comboBoxId == null)
	{
		reportNullObject("ComboBox.getSelectedIndex(comboBoxId)", "comboBoxId");
		return -1;
	}

	// Get the combo box.
	var theComboBox = document.getElementById(comboBoxId);
	if (theComboBox == null)
	{
		reportNullObject("ComboBox.getSelectedIndex(comboBoxId)", "theComboBox");
		return -1;
	}

	var selectedIndex = theComboBox.selectedIndex;
	
	return selectedIndex;
}

function ComboBox.getSelectedText(comboBoxId)
{
	// Parameters:
	//		comboBoxId		The text string specifying the identifier of the combo box to be referenced.

	// Returns the index of the selected item, or -1 if an error occurs.

	if (comboBoxId == null)
	{
		reportNullObject("ComboBox.getSelectedIndex", "comboBoxId");
		return -1;
	}

	// Get the combo box.
	var theComboBox = document.getElementById(comboBoxId);
	if (theComboBox == null)
	{
		reportNullObject("ComboBox.getSelectedIndex(comboBoxId)", "theComboBox");
		return -1;
	}

	var selectedIndex = theComboBox.selectedIndex;

	var selectedText = theComboBox[selectedIndex].text;
		
	return selectedText;
}

function ComboBox.getNumberOfItems(comboBoxId)
{
	var theComboBox = document.getElementById(comboBoxId);
	if (theComboBox == null)
	{
		reportNullObject("ComboBox.getNumberOfItems(comboBoxId)", "theComboBox");
		return -1;
	}
	
	return theComboBox.length;
}

function ComboBox.setSelectedIndex(comboBoxId, desiredIndex)
{
	// returns true if desiredIndex is properly selected,
	// otherwise returns false (when desiredInde is not within the range
	// of available indices).
	var theComboBox = document.getElementById(comboBoxId);
	if (theComboBox == null)
	{
		reportNullObject("ComboBox.setSelectedIndex(comboBoxId, desiredIndex)", "theComboBox");
		return -1;
	}
	var numberOfItems = ComboBox.getNumberOfItems(comboBoxId);
	
	if ((desiredIndex  < 0 ) || (desiredIndex >= numberOfItems))
	{
		return false;
	}
	
	theComboBox.selectedIndex = desiredIndex;
	
	return true;
}

function ComboBox.selectItemNext(comboBoxId)
{
	// This causes the next item in the combo box to be selected.
	// returns true if successful, false otherwise.
	var index = ComboBox.getSelectedIndex(comboBoxId);
	
	++index;
	
	return ComboBox.setSelectedIndex(comboBoxId, index);
}

function ComboBox.selectItemPrevious(comboBoxId)
{
	// This causes the previous item in the combo box to be selected.
	// returns true if successful, false otherwise.
	var index = ComboBox.getSelectedIndex(comboBoxId);
	
	--index;
	
	return ComboBox.setSelectedIndex(comboBoxId, index);
}