/**
 * Copyright 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.
 *
 */

package org.waveprotocol.wave.client.editor;

import org.waveprotocol.wave.client.editor.content.ContentElement;
import org.waveprotocol.wave.client.editor.event.EditorEvent;

/**
 * Interface of user event handlers for ContentElements. All the events here
 * match a user action (keypress, mouse click, etc.) but have already been
 * processed by Editor to relate to the content DOM tree rather than the HTML
 * implementation.
 *
 * Typically, nodes will handle the event by using the MutableDocument to
 * effect change to the content DOM.
 *
 * Each handler returns a boolean: true if the event was handled by this
 * method, false if it was not handled. If false is returned, default handling
 * logic may execute (see
 * {@link org.waveprotocol.wave.client.editor.content.NodeEventRouter}. In some
 * contexts, such as with navigation events, it is possible to allow the default
 * browser behaviour - in this case call event.allowBrowserDefault()
 *
 * The handle methods below are always called before the browser's native
 * editor has handled the event. If all the nodes asked by Editor to handle a
 * given event returns false, then Editor lets the native editor handle the
 * event.
 *
 * @author danilatos@google.com (Daniel Danilatos)
 */
public interface NodeEventHandler {

  /**
   * Called when the event handler has become active for the given element.
   *
   * It should attach any DOM event listeners, etc. at this stage.
   *
   * @param element
   */
  public void onActivated(ContentElement element);

  /**
   * Called when the event handler has been deactivated for the given element.
   *
   * It should dettach any DOM event listeners, etc. at this stage.
   *
   * @param element
   */
  public void onDeactivated(ContentElement element);

  /**
   * Handles an enter/return key from inside the node.
   *
   * @param event
   * @return true if handled
   */
  public boolean handleEnter(ContentElement element, EditorEvent event);

  /**
   * Handles a backspace that occurred with the caret immediately after this
   * node.
   *
   * @param event
   * @return true if handled
   */
  public boolean handleBackspaceAfterNode(ContentElement element, EditorEvent event);

  /**
   * Handles a backspace that occurred with the caret immediately at the
   * beginning of the node.
   *
   * @param event
   * @return true if handled
   */
  public boolean handleBackspaceAtBeginning(ContentElement element, EditorEvent event);

  /**
   * Handles a backspace that occurred with the caret past the beginning of the
   * node.
   *
   * @param event
   * @return true if handled
   */
  public boolean handleBackspaceNotAtBeginning(ContentElement element, EditorEvent event);

  /**
   * Handles a delete that occurred with the caret inside this node.
   *
   * @param event
   * @return true if handled
   */
  public boolean handleDelete(ContentElement element, EditorEvent event);

  /**
   * Handles a delete that occurred with the caret immediately before this node.
   *
   * @param event
   * @return true if handled
   */
  public boolean handleDeleteBeforeNode(ContentElement element, EditorEvent event);

  /**
   * Handles a delete that occurred with the caret immediately at the end of the
   * node.
   *
   * @param event
   * @return true if handled
   */
  public boolean handleDeleteAtEnd(ContentElement element, EditorEvent event);

  /**
   * Handles a delete that occurred with the caret before the end of the node.
   *
   * @param event
   * @return true if handled
   */
  public boolean handleDeleteNotAtEnd(ContentElement element, EditorEvent event);

  /**
   * Handles a left arrow that occurred with the caret inside this node.
   *
   * @param event
   * @return true if handled
   */
  public boolean handleLeft(ContentElement element, EditorEvent event);

  /**
   * Handles a left arrow that occurred with the caret immediately at the
   * beginning of the node.
   *
   * @param event
   * @return true if handled
   */
  public boolean handleLeftAfterNode(ContentElement element, EditorEvent event);

  /**
   * Handles a left arrow that occurred with the caret immediately after this
   * node.
   *
   * @param event
   * @return true if handled
   */
  public boolean handleLeftAtBeginning(ContentElement element, EditorEvent event);

  /**
   * Handles a right arrow that occurred with the caret inside this node.
   *
   * @param event
   * @return true if handled
   */
  public boolean handleRight(ContentElement element, EditorEvent event);

  /**
   * Handles a right arrow that occurred with the caret immediately before this
   * node.
   *
   * @param event
   * @return true if handled
   */
  public boolean handleRightBeforeNode(ContentElement element, EditorEvent event);

  /**
   * Handles a right arrow that occurred with the caret immediately at the end
   * of the node.
   *
   * @param event
   * @return true if handled
   */
  public boolean handleRightAtEnd(ContentElement element, EditorEvent event);

  /**
   * Handles a click
   *
   * @param event The click event
   * @return true if handled
   */
  public boolean handleClick(ContentElement element, EditorEvent event);

}