KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jface > text > formatter > IContentFormatterExtension


1 /*******************************************************************************
2  * Copyright (c) 2000, 2005 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11
12 package org.eclipse.jface.text.formatter;
13
14 import org.eclipse.jface.text.IDocument;
15
16 /**
17  * Extension interface for {@link IContentFormatter}.
18  * <p>
19  * Updates the content formatter to be able to pass {@link IFormattingContext}
20  * context objects to {@link IFormattingStrategyExtension} objects
21  * operating in context based mode.
22  * <p>
23  * Clients using context based formatting call the method
24  * <code>format(IDocument, IFormattingContext)</code> with a properly
25  * initialized formatting context.<br>
26  * The formatting context must be set up according to the desired formatting mode:
27  * <ul>
28  * <li>For whole document formatting set the property {@link FormattingContextProperties#CONTEXT_DOCUMENT}.
29  * This is equivalent to setting {@link FormattingContextProperties#CONTEXT_REGION} with a region spanning
30  * the whole document.</li>
31  * <li>For multiple region formatting set the property {@link FormattingContextProperties#CONTEXT_REGION}.
32  * Note that the content formatter automatically aligns the region to a block selected region,
33  * and if the region spans multiple partitions, it also completes eventual partitions covered only
34  * partially by the region.</li>
35  * </ul>
36  * Depending on the registered formatting strategies, more context information must
37  * be passed in the formatting context, like e.g. {@link FormattingContextProperties#CONTEXT_PREFERENCES}.
38  * <p>
39  * Note that in context based mode the content formatter is fully reentrant, but not
40  * thread-safe.
41  * <p>
42  *
43  * @see IFormattingContext
44  * @see FormattingContextProperties
45  * @since 3.0
46  */
47 public interface IContentFormatterExtension {
48
49     /**
50      * Formats the given region of the specified document.
51      * <p>
52      * The formatter may safely assume that it is the only subject that
53      * modifies the document at this point in time. This method is fully
54      * reentrant, but not thread-safe.
55      * <p>
56      * The formatting process performed by <code>format(IDocument, IFormattingContext)</code>
57      * happens as follows:
58      * <ul>
59      * <li>In a first pass the content formatter formats the range of the
60      * document to be formatted by using the master formatting strategy. This
61      * happens regardless of the content type of the underlying partition.
62      * </li>
63      * <li>In the second pass, the range is formatted again, this time using
64      * the registered slave formatting strategies. For each partition contained
65      * in the range to be formatted, the content formatter determines its
66      * content type and formats the partition with the correct formatting
67      * strategy.
68      * </li>
69      *
70      * @param document
71      * The document to be formatted
72      * @param context
73      * The formatting context to pass to the formatting strategies.
74      * This argument must not be <code>null</code>.
75      */
76     void format(IDocument document, IFormattingContext context);
77 }
78
Popular Tags