--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/dwtx/jface/text/ITextViewer.d	Sat Aug 23 19:10:48 2008 +0200
@@ -0,0 +1,550 @@
+/*******************************************************************************
+ * 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 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= (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= (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();
+}