/*
formhelpers_setFocus function
You can use me to put the cursor into the first form field that 
had an error as determined by qForm validation.
e.g.: objForm.onValidate = _setFocus;
precondition: objForm should be declared as a qForm
postcondition: focus is in first field with errors found by the qForm utility
*/
function formhelpers_setFocus() {
	// optional override of default qForm name objForm 
	var theQForm = ( arguments.length > 0 ? arguments[0] : objForm );
	var aryErrorFields = theQForm._queue.errorFields.split( "," );
	var objField = null;
	
	if ( aryErrorFields[0].length > 0 )
		objField = theQForm[aryErrorFields[0]]; 
	else if ( aryErrorFields.length > 1 )
		objField = theQForm[aryErrorFields[1]];
	
	if ( objField != null )
		objField.focus();

	return true;
}

// for a group of check boxes: check all if there's any unchecked, otherwise uncheck all 
// in: arrFormField should be the variable for the group of check boxes you want to set. 
//     note that all check boxes in the group need the same name (can have different values) 
// out: all check boxes are checked or unchecked. it returns the proper choice. 
// dependent: upon function setChecked( arrFormField, blnChecked ) 
function toggleChecked( arrFormField )
{
	var intFieldNumber = arrFormField.length;
	var blnAllChecked = true;
	// figure out if all of the checks are selected: try to find an unchecked 
	while ( blnAllChecked && intFieldNumber > 0 ) {
		--intFieldNumber;
		blnAllChecked = arrFormField[intFieldNumber].checked;
	}
	// blnAllChecked will be false if any unchecked boxes are found. 
	return setChecked( arrFormField, !blnAllChecked );
}

// set all of a group of check boxes to checked or unchecked 
// in: arrFormField should be the variable for the group of check boxes you want to set. 
//     note that all check boxes in the group need the same name (can have different values) 
// in: blnChecked is true or false to tell whether you want to check or uncheck all 
// out: all check boxes are checked or unchecked. it returns the proper choice. 
function setChecked( arrFormField, blnChecked )
{
	var intFieldNumber = arrFormField.length;
	while ( intFieldNumber > 0 ) {
		--intFieldNumber;
		arrFormField[intFieldNumber].checked = blnChecked;
	}
	return blnChecked;
}

// we could make a function that's called validateList(). you pass it a set of valid list delimiters 
// and a validation function to run on each list item. 
// like objForm.field.validateList( ",;", _isEmail, "optional custom message just like any other validation funct has" );