/*******************************************************************************
 * Copyright (c) 2000, 2005 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.formatter.IContentFormatterExtension;

import dwtx.jface.text.formatter.MultiPassContentFormatter; // packageimport
import dwtx.jface.text.formatter.ContextBasedFormattingStrategy; // packageimport
import dwtx.jface.text.formatter.FormattingContext; // packageimport
import dwtx.jface.text.formatter.IFormattingStrategy; // packageimport
import dwtx.jface.text.formatter.IFormattingStrategyExtension; // packageimport
import dwtx.jface.text.formatter.IContentFormatter; // packageimport
import dwtx.jface.text.formatter.FormattingContextProperties; // packageimport
import dwtx.jface.text.formatter.ContentFormatter; // packageimport
import dwtx.jface.text.formatter.IFormattingContext; // packageimport

import dwt.dwthelper.utils;

import dwtx.jface.text.IDocument;

/**
 * Extension interface for {@link IContentFormatter}.
 * <p>
 * Updates the content formatter to be able to pass {@link IFormattingContext}
 * context objects to {@link IFormattingStrategyExtension} objects
 * operating in context based mode.
 * <p>
 * Clients using context based formatting call the method
 * <code>format(IDocument, IFormattingContext)</code> with a properly
 * initialized formatting context.<br>
 * The formatting context must be set up according to the desired formatting mode:
 * <ul>
 * <li>For whole document formatting set the property {@link FormattingContextProperties#CONTEXT_DOCUMENT}.
 * This is equivalent to setting {@link FormattingContextProperties#CONTEXT_REGION} with a region spanning
 * the whole document.</li>
 * <li>For multiple region formatting set the property {@link FormattingContextProperties#CONTEXT_REGION}.
 * Note that the content formatter automatically aligns the region to a block selected region,
 * and if the region spans multiple partitions, it also completes eventual partitions covered only
 * partially by the region.</li>
 * </ul>
 * Depending on the registered formatting strategies, more context information must
 * be passed in the formatting context, like e.g. {@link FormattingContextProperties#CONTEXT_PREFERENCES}.
 * <p>
 * Note that in context based mode the content formatter is fully reentrant, but not
 * thread-safe.
 * <p>
 *
 * @see IFormattingContext
 * @see FormattingContextProperties
 * @since 3.0
 */
public interface IContentFormatterExtension {

    /**
     * Formats the given region of the specified document.
     * <p>
     * The formatter may safely assume that it is the only subject that
     * modifies the document at this point in time. This method is fully
     * reentrant, but not thread-safe.
     * <p>
     * The formatting process performed by <code>format(IDocument, IFormattingContext)</code>
     * happens as follows:
     * <ul>
     * <li>In a first pass the content formatter formats the range of the
     * document to be formatted by using the master formatting strategy. This
     * happens regardless of the content type of the underlying partition.
     * </li>
     * <li>In the second pass, the range is formatted again, this time using
     * the registered slave formatting strategies. For each partition contained
     * in the range to be formatted, the content formatter determines its
     * content type and formats the partition with the correct formatting
     * strategy.
     * </li>
     *
     * @param document
     *                  The document to be formatted
     * @param context
     *                   The formatting context to pass to the formatting strategies.
     *                   This argument must not be <code>null</code>.
     */
    void format(IDocument document, IFormattingContext context);
}