| <!DOCTYPE html PUBLIC "-//w3c//dtd html 4.0 transitional//en"> |
| <html> |
| <head> |
| <meta content="text/html; charset=iso-8859-1" |
| http-equiv="Content-Type"> |
| <meta content="IBM" name="Author"> |
| <title>Package-level Javadoc</title> |
| </head> |
| <body> |
| Provides a content formatter add-on for an <tt>ITextViewer</tt>. |
| A content formatter changes the formatting of a document region while |
| preserving and correctly updating the positions of the document. |
| <h2>Package Specification</h2> |
| <tt>IContentFormatter</tt> defines the concept of a text formatter. It |
| collaborates with content type specific formatting stratgies (<tt>IFormattingStrategy</tt>) |
| which for a given document region format the subregion with the |
| matching |
| content type. The package contains a default implementation of <tt>IContentFormatter</tt> |
| (<tt>ContentFormatter</tt>).<br> |
| Additionally, an implementation of <tt>IContentFormatterExtension</tt> |
| is provided |
| for text edit based formatting strategies. This implementation only |
| accepts formatting strategies |
| implementing the extension interface <tt>IFormattingStrategyExtension</tt>. |
| These formatting strategies are required to handle the position |
| updating of the document. To facilitate the work with these text edit |
| based formatting strategies, a default implementation called <tt>ContextBasedFormattingStrategy</tt> |
| is provided. Formatting strategies inheriting from this class are text |
| edit based and behave context dependent. Depending on the formatting |
| context that is passed |
| to the content formatter, different preferences and modes can be used |
| to format different parts of a document. |
| <p>To set up a proper working text edit based content formatter, the |
| following steps are needed: |
| </p> |
| <ul> |
| <li>Create an instance of <tt>IFormattingContext</tt>. The default |
| implementation <tt>FormattingContext</tt> already |
| provides support for the conversion of preferences from a preference |
| store to a map and vice versa. The method <tt>getPreferenceKeys</tt> |
| 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 <tt>setProperty(String, Object)</tt> |
| with the property identifier <tt>FormattingContextProperties.CONTEXT_PREFERENCES</tt>.</li> |
| <li>Create an instance of the text edit based content formatter class |
| <tt>MultiPassContentFormatter</tt>. 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.</li> |
| <li>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.</li> |
| <li>Specify the proper formatting mode (see |
| FormattingContextProperties): |
| <ul> |
| <li>For whole document formatting set the property <tt>CONTEXT_DOCUMENT</tt> |
| of the created formatting context to <tt>true</tt>. This is |
| equivalent to setting <code>CONTEXT_REGION</code> with a region |
| spanning the whole document.</li> |
| <li>For multiple region formatting set the property <code>CONTEXT_REGION</code> |
| 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.</li> |
| <li>For explicit formatting of a partition with the formatting |
| strategy registered for a certain content type use the |
| property <tt>CONTEXT_PARTITION</tt>. 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.</li> |
| </ul> |
| </li> |
| <li>Call the method <tt>MultiPassContentFormatter#format(IDocument, |
| IFormattingContext)</tt> with the created formatting context |
| and the document to be formatted.</li> |
| </ul> |
| <p></p> |
| </body> |
| </html> |