/*******************************************************************************
 * Copyright (c) 2000, 2008 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 * Port to the D programming language:
 *     Frank Benoit <benoit@tionex.de>
 *******************************************************************************/
module dwtx.jface.text.ITextViewer;

import dwtx.jface.text.ITextListener; // packageimport
import dwtx.jface.text.IUndoManager; // packageimport
import dwtx.jface.text.ITextHoverExtension2; // packageimport
import dwtx.jface.text.IViewportListener; // packageimport
import dwtx.jface.text.IRegion; // packageimport
import dwtx.jface.text.IFindReplaceTarget; // packageimport
import dwtx.jface.text.IAutoIndentStrategy; // packageimport
import dwtx.jface.text.ITextHover; // packageimport
import dwtx.jface.text.TextPresentation; // packageimport
import dwtx.jface.text.ITextDoubleClickStrategy; // packageimport
import dwtx.jface.text.ITextInputListener; // packageimport
import dwtx.jface.text.ITextOperationTarget; // packageimport
import dwtx.jface.text.IEventConsumer; // packageimport
import dwtx.jface.text.IDocument; // packageimport

import dwt.dwthelper.utils;

import dwt.custom.StyledText;
import dwt.graphics.Color;
import dwt.graphics.Point;
import dwtx.jface.viewers.ISelectionProvider;


/**
 * A text viewer connects a text widget with an
 * {@link dwtx.jface.text.IDocument}. The document is used as the
 * widget's text model.
 * <p>
 * It supports the following kinds of listeners:
 * <ul>
 * <li>view port listeners to inform about changes of the viewer's view port</li>
 * <li>text listeners to inform about changes of the document and the
 * subsequent viewer change</li>
 * <li>text input listeners to inform about changes of the viewer's input
 * document.</li>
 * </ul>
 * A text viewer supports a set of configuration options and plug-ins defining
 * its behavior:
 * <ul>
 * <li>undo manager</li>
 * <li>double click behavior</li>
 * <li>auto indentation</li>
 * <li>text hover</li>
 * </ul>
 * Installed plug-ins are not automatically activated. Plug-ins must be
 * activated with the <code>activatePlugins</code> call. Most plug-ins can be
 * defined per content type. Content types are derived from a partitioning of
 * the text viewer's input document. In case of documents that support multiple
 * partitionings, the implementer is responsible for determining the
 * partitioning to use.
 * <p>
 * A text viewer also provides the concept of event consumption. Events handled
 * by the viewer can be filtered and processed by a dynamic event consumer. With
 * {@link dwtx.jface.text.ITextViewerExtension}, this mechanism has been
 * replaced with the support for
 * {@link dwt.custom.VerifyKeyListener}.
 * <p>
 * A text viewer provides several text editing functions, some of them are
 * configurable, through a text operation target interface. It also supports a
 * presentation mode in which it only shows a specified section of its document.
 * By calling <code>setVisibleRegion</code> clients define which section is
 * visible. Clients can get access to this section by calling
 * <code>getVisibleRegion</code>. The viewer's presentation mode does not
 * affect any client of the viewer other than text listeners. With
 * {@link dwtx.jface.text.ITextViewerExtension5} the visible region
 * support has been reworked. With that extension interface, text viewers are
 * allowed to show fractions of their input document. I.e. a widget selection of
 * two visually neighboring characters is no longer guaranteed to be two
 * neighboring characters in the viewer's input document. Thus, viewers
 * implementing {@link dwtx.jface.text.ITextViewerExtension5} are
 * potentially forced to change the fractions of the input document that are
 * shown when clients ask for the visible region.
 * <p>
 *
 * In order to provide backward compatibility for clients of
 * <code>ITextViewer</code>, extension interfaces are used as a means of
 * evolution. The following extension interfaces exist:
 * <ul>
 * <li>{@link dwtx.jface.text.ITextViewerExtension} since version 2.0
 * replacing the event consumer mechanism and introducing the concept of rewrite
 * targets and means to manage the viewer's redraw behavior</li>
 * <li>{@link dwtx.jface.text.ITextViewerExtension2}since version 2.1
 * adding a way to invalidate a viewer's presentation and setters for hovers.
 * </li>
 * <li>{@link dwtx.jface.text.ITextViewerExtension3} since version 2.1
 * which itself was replaced by
 * {@link dwtx.jface.text.ITextViewerExtension5} in version 3.0</li>
 * <li>{@link dwtx.jface.text.ITextViewerExtension4} since version 3.0
 * introducing focus handling for widget token keepers and the concept of text
 * presentation listeners.</li>
 * <li>{@link dwtx.jface.text.ITextViewerExtension5} since version 3.0
 * extending the visible region concept with explicit handling and conversion
 * of widget and model coordinates.</li>
 * <li>{@link dwtx.jface.text.ITextViewerExtension6} since version 3.1
 * extending the text viewer with the ability to detect hyperlinks and access the undo manager.</li>
 * <li>{@link dwtx.jface.text.ITextViewerExtension7} since version 3.3
 * extending the text viewer with the ability to install tabs to spaces conversion.</li>
 * <li>{@link dwtx.jface.text.ITextViewerExtension8} since version 3.4
 * extending the text viewer with the ability to print and rich hover support.</li>
 * </ul></p>
 * <p>
 * Clients may implement this interface and its extension interfaces or use the
 * standard implementation {@link dwtx.jface.text.TextViewer}.</p>
 *
 * @see dwtx.jface.text.ITextViewerExtension
 * @see dwtx.jface.text.ITextViewerExtension2
 * @see dwtx.jface.text.ITextViewerExtension3
 * @see dwtx.jface.text.ITextViewerExtension4
 * @see dwtx.jface.text.ITextViewerExtension5
 * @see dwtx.jface.text.ITextViewerExtension6
 * @see dwtx.jface.text.ITextViewerExtension7
 * @see dwtx.jface.text.ITextViewerExtension8
 * @see dwtx.jface.text.IDocument
 * @see dwtx.jface.text.ITextInputListener
 * @see dwtx.jface.text.IViewportListener
 * @see dwtx.jface.text.ITextListener
 * @see dwtx.jface.text.IEventConsumer
 */
public interface ITextViewer {


    /* ---------- widget --------- */

    /**
     * Returns this viewer's DWT control, <code>null</code> if the control is disposed.
     * <p>
     * <em>Calling API directly on the widget can interfere with features provided
     * by a text viewer. Clients who call API directly on the widget are responsible
     * to resolve such conflicts on their side.</em>
     * </p>
     *
     * @return the DWT control or <code>null</code>
     */
    StyledText getTextWidget();


    /* --------- plug-ins --------- */

    /**
     * Sets this viewer's undo manager.
     *
     * @param undoManager the new undo manager. <code>null</code> is a valid argument.
     */
    void setUndoManager(IUndoManager undoManager);

    /**
     * Sets this viewer's text double click strategy for the given content type.
     *
     * @param strategy the new double click strategy. <code>null</code> is a valid argument.
     * @param contentType the type for which the strategy is registered
     */
    void setTextDoubleClickStrategy(ITextDoubleClickStrategy strategy, String contentType);

    /**
     * Sets this viewer's auto indent strategy for the given content type. If
     * the given strategy is <code>null</code> any installed strategy for the
     * content type is removed. This method has been replaced by
     * {@link ITextViewerExtension2#prependAutoEditStrategy(IAutoEditStrategy, String)} and
     * {@link ITextViewerExtension2#removeAutoEditStrategy(IAutoEditStrategy, String)}.
     * It is now equivalent to
     * <pre>
     *      ITextViewerExtension2 extension= cast(ITextViewerExtension2) viewer;
     *      extension.removeAutoEditStrategy(oldStrategy, contentType);
     *      extension.prependAutoEditStrategy(strategy, contentType);
     * </pre>
     *
     * @param strategy the new auto indent strategy. <code>null</code> is a
     *            valid argument.
     * @param contentType the type for which the strategy is registered
     * @deprecated since 3.1, use
     *             {@link ITextViewerExtension2#prependAutoEditStrategy(IAutoEditStrategy, String)} and
     *             {@link ITextViewerExtension2#removeAutoEditStrategy(IAutoEditStrategy, String)} instead
     */
    void setAutoIndentStrategy(IAutoIndentStrategy strategy, String contentType);

    /**
     * Sets this viewer's text hover for the given content type.
     * <p>
     * This method has been replaced by {@link ITextViewerExtension2#setTextHover(ITextHover, String, int)}.
     * It is now equivalent to
     * <pre>
     *    ITextViewerExtension2 extension= cast(ITextViewerExtension2) document;
     *    extension.setTextHover(textViewerHover, contentType, ITextViewerExtension2#DEFAULT_HOVER_STATE_MASK);
     * </pre>
     *
     *
     * @param textViewerHover the new hover. <code>null</code> is a valid
     *            argument.
     * @param contentType the type for which the hover is registered
     */
    void setTextHover(ITextHover textViewerHover, String contentType);

    /**
     * Activates the installed plug-ins. If the plug-ins are already activated
     * this call has no effect.
     */
    void activatePlugins();

    /**
     * Resets the installed plug-ins. If plug-ins change their state or
     * behavior over the course of time, this method causes them to be set
     * back to their initial state and behavior. E.g., if an {@link IUndoManager}
     * has been installed on this text viewer, the manager's list of remembered
     * text editing operations is removed.
     */
    void resetPlugins();



    /* ---------- listeners ------------- */

    /**
     * Adds the given view port listener to this viewer. The listener
     * is informed about all changes to the visible area of this viewer.
     * If the listener is already registered with this viewer, this call
     * has no effect.
     *
     * @param listener the listener to be added
     */
    void addViewportListener(IViewportListener listener);

    /**
     * Removes the given listener from this viewer's set of view port listeners.
     * If the listener is not registered with this viewer, this call has
     * no effect.
     *
     * @param listener the listener to be removed
     */
    void removeViewportListener(IViewportListener listener);

    /**
     * Adds a text listener to this viewer. If the listener is already registered
     * with this viewer, this call has no effect.
     *
     * @param listener the listener to be added
     */
    void addTextListener(ITextListener listener);

    /**
     * Removes the given listener from this viewer's set of text listeners.
     * If the listener is not registered with this viewer, this call has
     * no effect.
     *
     * @param listener the listener to be removed
     */
    void removeTextListener(ITextListener listener);

    /**
     * Adds a text input listener to this viewer. If the listener is already registered
     * with this viewer, this call has no effect.
     *
     * @param listener the listener to be added
     */
    void addTextInputListener(ITextInputListener listener);

    /**
     * Removes the given listener from this viewer's set of text input listeners.
     * If the listener is not registered with this viewer, this call has
     * no effect.
     *
     * @param listener the listener to be removed
     */
    void removeTextInputListener(ITextInputListener listener);



    /* -------------- model manipulation ------------- */

    /**
     * Sets the given document as the text viewer's model and updates the
     * presentation accordingly. An appropriate <code>TextEvent</code> is
     * issued. This text event does not carry a related document event.
     *
     * @param document the viewer's new input document <code>null</code> if none
     */
    void setDocument(IDocument document);

    /**
     * Returns the text viewer's input document.
     *
     * @return the viewer's input document or <code>null</code> if none
     */
    IDocument getDocument();


    /* -------------- event handling ----------------- */

    /**
     * Registers an event consumer with this viewer. This method has been
     * replaces with the {@link dwt.custom.VerifyKeyListener}
     * management methods in {@link ITextViewerExtension}.
     *
     * @param consumer the viewer's event consumer. <code>null</code> is a
     *            valid argument.
     */
    void setEventConsumer(IEventConsumer consumer);

    /**
     * Sets the editable state.
     *
     * @param editable the editable state
     */
    void setEditable(bool editable);

    /**
     * Returns whether the shown text can be manipulated.
     *
     * @return the viewer's editable state
     */
    bool isEditable();


    /* ----------- visible region support ------------- */

    /**
     * Sets the given document as this viewer's model and
     * exposes the specified region. An appropriate
     * <code>TextEvent</code> is issued. The text event does not carry a
     * related document event. This method is a convenience method for
     * <code>setDocument(document);setVisibleRegion(offset, length)</code>.
     *
     * @param document the new input document or <code>null</code> if none
     * @param modelRangeOffset the offset of the model range
     * @param modelRangeLength the length of the model range
     */
    void setDocument(IDocument document, int modelRangeOffset, int modelRangeLength);

    /**
     * Defines and sets the region of this viewer's document which will be
     * visible in the presentation. Every character inside the specified region
     * is supposed to be visible in the viewer's widget after that call.
     *
     * @param offset the offset of the visible region
     * @param length the length of the visible region
     */
    void setVisibleRegion(int offset, int length);

    /**
     * Resets the region of this viewer's document which is visible in the presentation.
     * Afterwards, the whole input document is visible.
     */
    void resetVisibleRegion();

    /**
     * Returns the current visible region of this viewer's document. The result
     * may differ from the argument passed to <code>setVisibleRegion</code> if
     * the document has been modified since then. The visible region is supposed
     * to be a consecutive region in viewer's input document and every character
     * inside that region is supposed to visible in the viewer's widget.
     * <p>
     * Viewers implementing {@link ITextViewerExtension5} may be forced to
     * change the fractions of the input document that are shown, in order to
     * fulfill this contract.
     *
     * @return this viewer's current visible region
     */
    IRegion getVisibleRegion();

    /**
     * Returns whether a given range overlaps with the visible region of this
     * viewer's document.
     * <p>
     * Viewers implementing {@link ITextViewerExtension5}may be forced to
     * change the fractions of the input document that are shown in order to
     * fulfill this request. This is because the overlap is supposed to be
     * without gaps.
     *
     * @param offset the offset
     * @param length the length
     * @return <code>true</code> if the specified range overlaps with the
     *         visible region
     */
    bool overlapsWithVisibleRegion(int offset, int length);



    /* ------------- presentation manipulation ----------- */

    /**
     * Applies the color information encoded in the given text presentation.
     * <code>controlRedraw</code> tells this viewer whether it should take care of
     * redraw management or not. If, e.g., this call is one in a sequence of multiple
     * presentation calls, it is more appropriate to explicitly control redrawing at the
     * beginning and the end of the sequence.
     *
     * @param presentation the presentation to be applied to this viewer
     * @param controlRedraw indicates whether this viewer should manage redraws
     */
    void changeTextPresentation(TextPresentation presentation, bool controlRedraw);

    /**
     * Marks the currently applied text presentation as invalid. It is the
     * viewer's responsibility to take any action it can to repair the text
     * presentation.
     * <p>
     * See {@link ITextViewerExtension2#invalidateTextPresentation(int, int)}
     * for a way to invalidate specific regions rather than the presentation as
     * a whole.
     *
     * @since 2.0
     */
    void invalidateTextPresentation();

    /**
     * Applies the given color as text foreground color to this viewer's
     * selection.
     *
     * @param color the color to be applied
     */
    void setTextColor(Color color);

    /**
     * Applies the given color as text foreground color to the specified section
     * of this viewer. <code>controlRedraw</code> tells this viewer whether it
     * should take care of redraw management or not.
     *
     * @param color the color to be applied
     * @param offset the offset of the range to be changed
     * @param length the length of the range to be changed
     * @param controlRedraw indicates whether this viewer should manage redraws
     */
    void setTextColor(Color color, int offset, int length, bool controlRedraw);


    /* --------- target handling and configuration ------------ */

    /**
     * Returns the text operation target of this viewer.
     *
     * @return the text operation target of this viewer
     */
    ITextOperationTarget getTextOperationTarget();

    /**
     * Returns the find/replace operation target of this viewer.
     *
     * @return the find/replace operation target of this viewer
     */
    IFindReplaceTarget getFindReplaceTarget();

    /**
     * Sets the strings that are used as prefixes when lines of the given content type
     * are prefixed using the prefix text operation. The prefixes are considered equivalent.
     * Inserting a prefix always inserts the defaultPrefixes[0].
     * Removing a prefix removes all of the specified prefixes.
     *
     * @param defaultPrefixes the prefixes to be used
     * @param contentType the content type for which the prefixes are specified
     * @since 2.0
     */
    void setDefaultPrefixes(String[] defaultPrefixes, String contentType);

    /**
     * Sets the strings that are used as prefixes when lines of the given content type
     * are shifted using the shift text operation. The prefixes are considered equivalent.
     * Thus "\t" and "    " can both be used as prefix characters.
     * Shift right always inserts the indentPrefixes[0].
     * Shift left removes all of the specified prefixes.
     *
     * @param indentPrefixes the prefixes to be used
     * @param contentType the content type for which the prefixes are specified
     */
    void setIndentPrefixes(String[] indentPrefixes, String contentType);



    /* --------- selection handling -------------- */

    /**
     * Sets the selection to the specified range.
     *
     * @param offset the offset of the selection range
     * @param length the length of the selection range. A negative length places
     *            the caret at the visual start of the selection.
     */
    void setSelectedRange(int offset, int length);

    /**
     * Returns the range of the current selection in coordinates of this viewer's document.
     *
     * @return a <code>Point</code> with x as the offset and y as the length of the current selection
     */
    Point getSelectedRange();

    /**
     * Returns a selection provider dedicated to this viewer. Subsequent
     * calls to this method return always the same selection provider.
     *
     * @return this viewer's selection provider
     */
    ISelectionProvider getSelectionProvider();


    /* ------------- appearance manipulation --------------- */

    /**
     * Ensures that the given range is visible.
     *
     * @param offset the offset of the range to be revealed
     * @param length the length of the range to be revealed
     */
    void revealRange(int offset, int length);

    /**
     * Scrolls the widget so that the given index is the line
     * with the smallest line number of all visible lines.
     *
     * @param index the line which should become the top most line
     */
    void setTopIndex(int index);

    /**
     * Returns the visible line with the smallest line number.
     *
     * @return the number of the top most visible line
     */
    int getTopIndex();

    /**
     * Returns the document offset of the upper left corner of this viewer's view port.
     *
     * @return the upper left corner offset
     */
    int getTopIndexStartOffset();

    /**
     * Returns the visible line with the highest line number.
     *
     * @return the number of the bottom most line
     */
    int getBottomIndex();

    /**
     * Returns the document offset of the lower right
     * corner of this viewer's view port. This is the visible character
     * with the highest character position. If the content of this viewer
     * is shorter, the position of the last character of the content is returned.
     *
     * @return the lower right corner offset
     */
    int getBottomIndexEndOffset();

    /**
     * Returns the vertical offset of the first visible line.
     *
     * @return the vertical offset of the first visible line
     */
    int getTopInset();
}