/* Description:
 *
 * This file contains functions that create custom visual effects that are used by many web pages.
 *
 * New functions should only be added to this file if:
 *  * They are used by many different web pages;
 *  * They pertain to visual effects.
 *
 */

/* function set_scriptaculous_blind_duration(duration) {{{
 *
 * Description:
 *  Sets the global variable "blind_duration", which controls how long
 *  Scriptaculous BlindUp and BlindDown effects last for.
 *
 * Arguments:
 *  duration      The number of seconds that BlindUp and BlindDown effects should last for.
 *                This argument is optional. It defaults to 0.5 .
 *
 * Returns:
 *  Nothing
 *
 */
function set_scriptaculous_blind_duration(duration) {
  blind_duration = typeof (duration) == 'undefined' ? 0.5 : duration;
}
set_scriptaculous_blind_duration();
// }}}

/* function toggle_blinding_for(element) {{{
 *
 * Description:
 *  Toggles a DOM element to be blinded up or down, depending on
 *  whether it's currently visible or hidden.
 *
 * Arguments:
 *  element     The DOM element, or the ID of the DOM element, to toggle.
 *
 * Returns:
 *  Nothing
 *
 */
function toggle_blinding_for(element) {
  if ($(element))
    {Effect.toggle(element, 'blind', {duration: blind_duration});}
} // }}}

/* function add_blinding_to_form_field(form_field, tooltip) {{{
 *
 * Description:
 *  Causes the "tooltip" element to be shown when the "form_field" element obtains focus,
 *  and the "tooltip" element to be hidden when the "form_field" element loses focus.
 *
 * *** NOTE:
 *  Do _NOT_ use this function to set blinding on a password field that was created by an ASP.Net "TextBox" control.
 *  I don't know why, but if this function sets the "onblur" event for an ASP.Net password textbox control, the
 *  function called by the "onblur" loses all of the variables that would be expected inside the closure.
 *
 * Arguments:
 *  form_field    The DOM element, or the ID of the DOM element, that represents the form field.
 *  tooltip       The DOM element, or the ID of the DOM element, that represents the tooltip.
 *
 * Returns:
 *  Nothing
 *
 */
function add_blinding_to_form_field(form_field, tooltip) {
  var form_field_element  = $(form_field);
  var tooltip_element     = $(tooltip);

  if (form_field_element && tooltip_element) {
    form_field_element.onfocus  = function() {toggle_blinding_for(tooltip_element);}
    form_field_element.onblur   = function() {toggle_blinding_for(tooltip_element);}
  }
} // }}}

/* function hide_and_show_with_blind() {{{
 *
 * Description:
 *  If "element_to_hide" is visible, it will be hidden. "element_to_show" will then be shown.
 *
 * Arguments:
 *  element_to_hide    The element to hide *before* showing "element_to_show". This can be a DOM element object, or a string containing the ID.
 *  element_to_show    The element to show. This can be a DOM element object, or a string containing the ID.
 *
 * Returns:
 *  Nothing
 *
 */
function hide_and_show_with_blind(element_to_hide, element_to_show) {
  // If "element_to_hide" is hidden, don't call Effect.BlindUp() on it. 
  // This is because the user won't see anything, and it will delay showing "element_to_show".
  if ($(element_to_hide).visible()) {
    Effect.BlindUp(element_to_hide, {
      duration:     blind_duration,
      afterFinish:  function() {Effect.BlindDown(element_to_show, {duration: blind_duration});}
    });
  }
  else
    {Effect.BlindDown(element_to_show, {duration: blind_duration});}
} // }}}

/* show_if_hidden(element)() {{{
 *
 * Description:
 *  If "element" is hidden, it will be shown.
 *
 * Arguments:
 *  element     The element to show.
 *
 * Returns:
 *  Nothing
 *
 */
function show_if_hidden(element) {
  if ($(element) && !$(element).visible())
    {Effect.BlindDown(element, {duration: blind_duration});}
} // }}}

/* hide_if_visible(element)() {{{
 *
 * Description:
 *  If "element" is visible, it will be hidden.
 *
 * Arguments:
 *  element     The element to hide.
 *
 * Returns:
 *  Nothing
 *
 */
function hide_if_visible(element) {
  if ($(element) && $(element).visible())
    {Effect.BlindUp(element, {duration: blind_duration});}
} // }}}