/** @license
Copyright 2007-2009 WebDriver committers
Copyright 2007-2009 Google Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

/**
 * @fileoverview A class for working with elements on the page under test.
 * @author jmleyba@gmail.com (Jason Leyba)
 */

goog.provide('webdriver.WebElement');

goog.require('goog.array');
goog.require('webdriver.By.Locator');
goog.require('webdriver.By.Strategy');
goog.require('webdriver.CommandName');
goog.require('webdriver.Future');


/**
 * Represents a DOM element.  WebElements can be found by searching from the
 * document root using a {@code webdriver.WebDriver}, or by searhcing under
 * another {@code webdriver.WebElement}:
 *
 *   driver.get('http://www.google.com');
 *   var searchForm = driver.findElement({tagName: 'form'});
 *   var searchBox = searchForm.findElement({name: 'q'});
 *   searchBox.sendKeys('webdriver');
 *
 * @param {webdriver.WebDriver} driver The WebDriver instance that will
 *     actually execute commands.
 * @constructor
 */
webdriver.WebElement = function(driver) {

  /**
   * The WebDriver instance to issue commands to.
   * @type {webdriver.WebDriver}
   * @private
   */
  this.driver_ = driver;

  /**
   * The UUID used by WebDriver to identify this element on the page. The ID is
   * wrapped in a webdriver.Future instance so it can be determined
   * asynchronously.
   * @type {webdriver.Future}
   * @private
   */
  this.elementId_ = new webdriver.Future(this.driver_);
};


/**
 * Adds a command to determine if an element is present under this element in
 * the DOM tree.
 * @param {webdriver.By.Locator|{*: string}} locator The locator to use for
 *     finding the element, or a short-hand object that can be converted into a
 *     locator.
 * @return {webdriver.Future} A future whose value will be set when the driver
 *     completes the search; value will be {@code true} if the element was
 *     found, false otherwise.
 * @see webdriver.By.Locator.createFromObj
 */
webdriver.WebElement.prototype.isElementPresent = function(locator) {
  locator = webdriver.By.Locator.checkLocator(locator);
  return this.driver_.callFunction(function() {
    var findCommand = this.driver_.
        addCommand(webdriver.CommandName.FIND_CHILD_ELEMENT).
        setParameters({
          'id': this.getId(),
          'using': locator.type,
          'value': locator.target
        });
    var commandFailed = false;
    var key = goog.events.listenOnce(findCommand,
        webdriver.Command.ERROR_EVENT, function(e) {
          commandFailed = true;
          this.driver_.abortCommand(e.currentTarget);
          e.preventDefault();
          e.stopPropagation();
          return false;
        }, /*capture phase*/true, this);
    return this.driver_.callFunction(function() {
      goog.events.unlistenByKey(key);
      return !commandFailed;
    });
  }, this);
};


/**
 * Adds a command to search for a single element on the page, restricting the
 * search to the descendants of the element represented by this instance.
 * @param {webdriver.By.Locator|{*: string}} locator The locator to use for
 *     finding the element, or a short-hand object that can be converted into a
 *     locator.
 * @return {webdriver.WebElement} A WebElement that can be used to issue
 *     commands on the found element.  The element's ID will be set
 *     asynchronously once the element is successfully located.
 * @see webdriver.By.Locator.createFromObj
 */
webdriver.WebElement.prototype.findElement = function(locator) {
  var webElement = new webdriver.WebElement(this.driver_);
  locator = webdriver.By.Locator.checkLocator(locator);
  var command = this.driver_.
      addCommand(webdriver.CommandName.FIND_CHILD_ELEMENT).
      setParameters({
        'id': this.getId(),
        'using': locator.type,
        'value': locator.target
      });
  webElement.getId().setValue(command.getFutureResult());
  return webElement;
};


/**
 * Adds a command to search for multiple elements on the page, restricting the
 * search to the descendants of hte element represented by this instance.
 * @param {webdriver.By.Locator|{*: string}} locator The locator to use for
 *     finding the element, or a short-hand object that can be converted into a
 *     locator.
 * @see webdriver.By.Locator.createFromObj
 */
webdriver.WebElement.prototype.findElements = function(locator) {
  locator = webdriver.By.Locator.checkLocator(locator);
  this.driver_.callFunction(function() {
    this.driver_.addCommand(webdriver.CommandName.FIND_CHILD_ELEMENTS).
        setParameters({
          'id': this.getId(),
          'using': locator.type,
          'value': locator.target
        });
    return this.driver_.callFunction(function(ids) {
      var elements = [];
      for (var i = 0; i < ids.length; i++) {
        if (ids[i]) {
          var element = new webdriver.WebElement(this.driver_);
          element.getId().setValue(ids[i]);
          elements.push(element);
        }
      }
      return elements;
    }, this);
  }, this);
};


/**
 * @return {webdriver.WebDriver} The driver that this element delegates commands
 *     to.
 */
webdriver.WebElement.prototype.getDriver = function() {
  return this.driver_;
};


/**
 * @return {webdriver.Futur} The UUID of this element wrapped in a Future.
 */
webdriver.WebElement.prototype.getId = function() {
  return this.elementId_;
};


/**
 * Creates a new {@code webdriver.Command} against the element represented by
 * this instance.
 * @param {string} name The name of the command to create.
 * @return {webdriver.Command} The new command.
 * @private
 */
webdriver.WebElement.prototype.createCommand_ = function(name) {
  return this.driver_.addCommand(name, this);
};


/**
 * Adds a command to click on this element.
 */
webdriver.WebElement.prototype.click = function() {
  this.createCommand_(webdriver.CommandName.CLICK);
};


/**
 * Types a sequence on the DOM element represented by this instance.
 * <p/>
 * Modifier keys (SHIFT, CONTROL, ALT, META) are stateful; once a modifier is
 * processed in the keysequence, that key state is toggled until one of the
 * following occurs:
 * <ul>
 * <li>The modifier key is encountered again in the sequence. At this point the
 * state of the key is toggled (along with the appropriate keyup/down events).
 * </li>
 * <li>The {@code webdriver.Key.NULL} key is encountered in the sequence. When
 * this key is encountered, all modifier keys current in the down state are
 * released (with accompanying keyup events). The NULL key can be used to
 * simulate common keyboard shortcuts:
 * <code>
 *     element.sendKeys("text was",
 *                      webdriver.Key.CONTROL, "a", webdriver.Key.NULL,
 *                      "now text is");
 *     // Alternatively:
 *     element.sendKeys("text was",
 *                      webdriver.Key.chord(webdriver.Key.CONTROL, "a"),
 *                      "now text is");
 * </code></li>
 * <li>The end of the keysequence is encountered. When there are no more keys
 * to type, all depressed modifier keys are released (with accompanying keyup
 * events).
 * </li>
 * </ul>
 * If a certain character can only be generated by using the shift key, such as
 * uppercase characters or certain punctuation marks, the shift key will be
 * applied for that individual key. If the shift key was not depressed before
 * typing that key, it will be released after typing the key. If the shift key
 * was already depressed, the extra event will not be generated. For example:
 * <code>
 *    // Expect shift down/up for each character.
 *    element.sendKeys("ABC");
 *    // Shift is already depressed, so it will not be pushed again for each
 *    // character.
 *    element.sendKeys(webdriver.Key.SHIFT, "ABC");
 * </code>
 * <p/>
 * <strong>Note:</strong> On browsers where native keyboard events are not yet
 * supported (e.g. Firefox on OS X), key events will be synthesized. Special
 * punctionation keys will be synthesized according to a standard QWERTY English
 * keyboard layout.
 * @param {string|webdriver.Future} var_args The strings to type. All arguments
 *     will be joined into a single sequence (var_args is permitted for
 *     convenience).
 */
webdriver.WebElement.prototype.sendKeys = function(var_args) {
  var command = this.createCommand_(webdriver.CommandName.SEND_KEYS);
  command.setParameters.apply(command, arguments);
};

/**
 * Queries for the tag/node name of this element.
 */
webdriver.WebElement.prototype.getTagName = function() {
  return this.createCommand_(webdriver.CommandName.GET_TAG_NAME).
      getFutureResult();
};


/**
 * Queries for the computed style of the element represented by this instance.
 * If the element inherits the named style from its parent, the parent will be
 * queried for its value.  Where possible, color values will be converted to
 * their hex representation (#00ff00 instead of rgb(0, 255, 0)).
 * <em>Warning:</em> the value returned will be as the browser interprets it, so
 * it may be tricky to form a proper assertion.
 * @param {string} cssStyleProperty The name of the CSS style property to look
 *     up.
 * @return {webdriver.Future<string>} The computed style property wrapped in a
 *    Future.
 */
webdriver.WebElement.prototype.getComputedStyle = function(cssStyleProperty) {
  return this.createCommand_(webdriver.CommandName.GET_VALUE_OF_CSS_PROPERTY).
      setParameters(cssStyleProperty).
      getFutureResult();
};


/**
 * Queries for the specified attribute.
 * @param {string} attributeName The name of the attribute to query.
 */
webdriver.WebElement.prototype.getAttribute = function(attributeName) {
  return this.createCommand_(webdriver.CommandName.GET_ATTRIBUTE).
      setParameters(attributeName).
      getFutureResult();
};


/**
 * @return {webdriver.Future} The value attribute for the element represented by
 *    this instance.
 */
webdriver.WebElement.prototype.getValue = function() {
  return this.createCommand_(webdriver.CommandName.GET_VALUE).
      getFutureResult();
};


/**
 * @return {webdriver.Future} The innerText of this element, without any leading
 *     or trailing whitespace.
 */
webdriver.WebElement.prototype.getText = function() {
  return this.createCommand_(webdriver.CommandName.GET_TEXT).
      getFutureResult();
};


/**
 * Selects this element.
 */
webdriver.WebElement.prototype.setSelected = function() {
  this.createCommand_(webdriver.CommandName.SET_SELECTED);
};


/**
 * @return {webdriver.Future} The size of this element.
 */
webdriver.WebElement.prototype.getSize = function() {
  return this.createCommand_(webdriver.CommandName.GET_SIZE).
      getFutureResult();
};


/**
 * @return {webdriver.Future} The location of this element.
 */
webdriver.WebElement.prototype.getLocation = function() {
  return this.createCommand_(webdriver.CommandName.GET_LOCATION).
      getFutureResult();
};


/**
 * Drags this element by the given offset.
 * @param {number} x The horizontal amount, in pixels, to drag this element.
 * @param {number} y The vertical amount, in pixels, to drag this element.
 * @return {webdriver.Future} The new location of the element.
 */
webdriver.WebElement.prototype.dragAndDropBy = function(x, y) {
  return this.createCommand_(webdriver.CommandName.DRAG_ELEMENT).
      setParameters(x, y).
      getFutureResult();
};


/**
 * Drags this element to the location of another {@code webElement}. After this
 * command executes, this element's upper-left hand corner should be the same
 * location as the upper-left hand corner of the given {@code webElement}.
 * @param {webdriver.WebElement} webElement The element to drag this element to.
 * @return {webdriver.Future} This element's new location.
 */
webdriver.WebElement.prototype.dragAndDropTo = function(webElement) {
  if (this.driver_ != webElement.driver_) {
    throw new Error(
        'WebElements created by different drivers cannot coordinate');
  }

  var toLocation = webElement.getLocation();
  var thisLocation = this.getLocation();
  return this.driver_.callFunction(function() {
    var delta = goog.math.Coordinate.difference(
        toLocation.getValue(), thisLocation.getValue());
    return this.dragAndDropBy(delta.x, delta.y);
  }, this);
};


/**
 * @return {boolean} Whether the DOM element represented by this instance is
 *     enabled, as dictated by the {@code disabled} attribute.
 */
webdriver.WebElement.prototype.isEnabled = function() {
  return this.driver_.callFunction(function() {
    this.getAttribute('disabled');
    return this.driver_.callFunction(function(value) {
      return !!!value;
    });
  }, this);
};


/**
 * Determines if this element is checked or selected; will generate an error if
 * the DOM element represented by this instance is not an OPTION or checkbox
 * INPUT element.
 * @return {webdriver.Future} Whether this element is checked or selected.
 * @private
 */
webdriver.WebElement.prototype.isCheckedOrSelected_ = function() {
  return this.driver_.callFunction(function() {
    this.createCommand_(webdriver.CommandName.GET_TAG_NAME);
    return this.driver_.callFunction(function(prevResult) {
      var attribute = prevResult == 'input' ? 'checked' : 'selected';
      return this.getAttribute(attribute);
    }, this);
  }, this);
};


/**
 * @return {webdriver.Future} Whether this element is selected.
 */
webdriver.WebElement.prototype.isSelected = function() {
  return this.isCheckedOrSelected_();
};


/**
 * @return {webdriver.Future} Whether this element is checked.
 */
webdriver.WebElement.prototype.isChecked = function() {
  return this.isCheckedOrSelected_();
};


/**
 * Toggles the checked/selected state of this element; will generate an error if
 * the DOM element represented by this instance is not an OPTION or checkbox
 * input element.
 * @return {webdriver.Future} The new checked/selected state of this element.
 */
webdriver.WebElement.prototype.toggle = function() {
  return this.driver_.callFunction(function() {
    this.createCommand_(webdriver.CommandName.TOGGLE);
    return this.isCheckedOrSelected_();
  }, this);
};


/**
 * If this current element is a form, or an element within a form, then this
 * will that form.
 */
webdriver.WebElement.prototype.submit = function() {
  this.createCommand_(webdriver.CommandName.SUBMIT);
};


/**
 * If this instance represents a text INPUT element, or a TEXTAREA element, this
 * will clear its {@code value}.
 */
webdriver.WebElement.prototype.clear = function() {
  this.createCommand_(webdriver.CommandName.CLEAR);
};


/**
 * @return {webdriver.Future} Whether this element is currently displayed.
 */
webdriver.WebElement.prototype.isDisplayed = function() {
  return this.createCommand_(webdriver.CommandName.IS_DISPLAYED).
      getFutureResult();
};


/**
 * @return {webdriver.Future} The outer HTML of this element.
 */
webdriver.WebElement.prototype.getOuterHtml = function() {
  return this.driver_.executeScript(
      ['var element = arguments[0];',
       'if ("outerHTML" in element) {',
       '  return element.outerHTML;',
       '} else {',
       '  var div = document.createElement("div");',
       '  div.appendChild(element.cloneNode(true));',
       '  return div.innerHTML;',
       '}'].join(''), this);
};


/**
 * @return {webdriver.Future} The inner HTML of this element.
 */
webdriver.WebElement.prototype.getInnerHtml = function() {
  return this.driver_.executeScript('return arguments[0].innerHTML', this);
};