/**
* 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.event;
import com.google.gwt.dom.client.Element;
import com.google.gwt.dom.client.Node;
import com.google.gwt.dom.client.Text;
import org.waveprotocol.wave.client.common.util.SignalEvent;
import org.waveprotocol.wave.client.editor.content.ContentElement;
import org.waveprotocol.wave.client.editor.content.ContentNode;
import org.waveprotocol.wave.client.editor.content.FocusedContentRange;
import org.waveprotocol.wave.model.document.AnnotationBehaviour.CursorDirection;
import org.waveprotocol.wave.model.document.util.FocusedPointRange;
import org.waveprotocol.wave.model.document.util.Point;
/**
* Provides a more restricted and higher level interface for EditorEventHandler
* to interact with the editor.
*
*/
public interface EditorInteractor {
/**
* Give editor's listeners a chance to preview the event and
* prevent it from handling it
*
* @returns true iff handled
*/
boolean notifyListeners(SignalEvent event);
/**
* Returns whether the editor is in editing mode.
*/
boolean isEditing();
/**
* @return true if the typing extractor is pending a flush
*/
boolean isTyping();
/**
* @return true if browser-triggered mutation events are expected, e.g.
* when the typing extractor has already been notified.
* Contrast with {@link #shouldIgnoreMutations()}
*/
boolean isExpectingMutationEvents();
/**
* Contrast with {@link #isExpectingMutationEvents()}
* @return true if mutations should be ignored because they are being triggered programmatically
*/
boolean shouldIgnoreMutations();
/**
* Notify the typing extractor that changes have occured at caret.
* @param caret
* @param useHtmlCaret temporary hack - the content caret cannot safely be ascertained,
* use the html caret directly instead and ignore the caret parameter.
* @param isReplace indicates whether the delete is actually the first half of a replace.
* @return false if the event should be allowed (typing extractor correctly notified)
* true if it should be cancelled (problem notifying typing extractor).
*/
boolean notifyTypingExtractor(Point<ContentNode> caret, boolean useHtmlCaret, boolean isReplace);
/**
* Force editor to flush.
*/
void forceFlush();
/**
* Delete range.
* @param first
* @param second
* @param isReplace indicates whether the delete is actually the first half of a replace.
*/
Point<ContentNode> deleteRange(Point<ContentNode> first, Point<ContentNode> second,
boolean isReplace);
/**
* Insert text into the document
* @param at
* @param text
* @param isReplace indicates whether the insert is actually the first half of a replace.
*/
Point<ContentNode> insertText(Point<ContentNode> at, String text, boolean isReplace);
/**
* Find the ContentNode corresponding to a dom node.
* @param target
*/
ContentElement findElementWrapper(Element target);
/**
* Normalizes a point so that it is biased towards text nodes, and node ends
* rather than node start.
* @param caret
*/
Point<ContentNode> normalizePoint(Point<ContentNode> caret);
/**
* Get selection points.
*/
FocusedContentRange getSelectionPoints();
/**
* Check whether the selection is within a content area.
*/
boolean hasContentSelection();
/**
* @return true if the focus is after the anchor (or the selection is collapsed)
*/
boolean selectionIsOrdered();
/**
* Set caret.
* @param caret
*/
void setCaret(Point<ContentNode> caret);
/**
* The user typed at the end of a link, and the hack described in
* {QuirksConstants#LIES_ABOUT_CARET_AT_LINK_END_BOUNDARY} occurred.
*
* @param textNode
*/
void noteWebkitEndOfLinkHackOccurred(Text textNode);
/**
* @return current html selection
*/
FocusedPointRange<Node> getHtmlSelection();
/**
* Reset the annotations on the editor's caret
*/
void clearCaretAnnotations();
/**
* Word delete from the specified location to the end of the word.
* @param caret
*/
void deleteWordStartingAt(Point<ContentNode> caret);
/**
* Word delete from the start of the word to the specified location.
* @param caret
*/
void deleteWordEndingAt(Point<ContentNode> caret);
/**
* IME composition commenced at the given location
* @param caret
*/
void compositionStart(Point<ContentNode> caret);
/**
* Composition state updated
*/
void compositionUpdate();
/**
* IME composition completed
*
* @return the new selection
*/
FocusedContentRange compositionEnd();
/**
* Adds an undo checkpoint
*/
void checkpoint(FocusedContentRange currentRange);
/**
* Rebias the selection, given an initial default direction to hint at how it should be.
*/
void rebiasSelection(CursorDirection defaultDirection);
}