1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
|
/*******************************************************************************
* Copyright (c) 2000, 2008 IBM Corporation and others.
*
* This program and the accompanying materials
* are made available under the terms of the Eclipse Public License 2.0
* which accompanies this distribution, and is available at
* https://www.eclipse.org/legal/epl-2.0/
*
* SPDX-License-Identifier: EPL-2.0
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.jface.text.formatter;
import org.eclipse.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>
* <p>
* The formatting process performed by <code>format(IDocument, IFormattingContext)</code>
* happens as follows:
* </p>
* <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>
* </ul>
*
* @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);
}
|
