org.eclipse.jface.text.formatter

Package Specification

To set up a proper working text edit based content formatter, the following steps are needed:

• Create an instance of IFormattingContext. The default implementation FormattingContext already provides support for the conversion of preferences from a preference store to a map and vice versa. The method getPreferenceKeys usually has to be overridden to return the appropriate keys of the preferences used during the formatting process. Then register a map of preferences with the formatting context by calling setProperty(String, Object) with the property identifier FormattingContextProperties.CONTEXT_PREFERENCES.
• Create an instance of the text edit based content formatter class MultiPassContentFormatter. The document partitioning and its associated default content type have to be passed to the constructor. This information is needed since the content formatter is able to format documents according to arbitrary partitionings and default content types.
• Register the formatting strategies for the content types that have to be formatted. If a formatting strategy is registered as master strategy, it is automatically associated with the default content type of the specified partitioning. If the formatting strategy is registered as slave strategy, it is associated with the indicated content type during the registration. Note that the master strategy can also be registered as a slave strategy for a content type other than the default content type.
• Specify the proper formatting mode (see FormattingContextProperties):
  • For whole document formatting set the property CONTEXT_DOCUMENT of the created formatting context to true. This is equivalent to setting CONTEXT_REGION with a region spanning the whole document.
  • For multiple region formatting set the property CONTEXT_REGION of the formatting context. Note that the content formatter automatically aligns the offset of a region to a line start for the master formatting strategy, it also completes eventual partitions covered only partially by the region for the slave formatting strategies.
  • For explicit formatting of a partition with the formatting strategy registered for a certain content type use the property CONTEXT_PARTITION. Note that the region denoted by this property must correspond to a partition relative to the specified partitioning in the document to be formatted. The content type of this property overrides the content type of the partition in the document.
• Call the method MultiPassContentFormatter#format(IDocument, IFormattingContext) with the created formatting context and the document to be formatted.

Updates the content formatter to be able to pass IFormattingContext context objects to IFormattingStrategyExtension objects operating in context based mode.

Clients using context based formatting call the method format(IDocument, IFormattingContext) with a properly initialized formatting context.
The formatting context must be set up according to the desired formatting mode:

• For whole document formatting set the property FormattingContextProperties.CONTEXT_DOCUMENT . This is equivalent to setting FormattingContextProperties.CONTEXT_REGION with a region spanning the whole document.
• For multiple region formatting set the property 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.

Updates formatting strategies to be able to receive a more general IFormattingContext object from its associated content formatters.

Each formatting process calls the strategy's methods in the following sequence:

• formatterStarts
• format
• formatterStops

Note that multiple calls to formatterStarts can be issued to a strategy before launching the formatting process with format.

This interface must be implemented by clients.

Two kinds of formatting strategies can be registered with this formatter:

• one master formatting strategy for the default content type
• one formatting strategy for each non-default content type