001: /*******************************************************************************
002: * Copyright (c) 2000, 2005 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jface.text;
011:
012: /**
013: * Extension interface for {@link org.eclipse.jface.text.IDocumentPartitioner}.
014: * <p>
015: * Extends the original concept of a document partitioner to answer the position
016: * categories that are used to manage the partitioning information.
017: * <p>
018: * This extension also introduces the concept of open and delimited partitions.
019: * A delimited partition has a predefined textual token delimiting its start and
020: * end, while an open partition can fill any space between two delimited
021: * partitions.
022: * </p>
023: * <p>
024: * An open partition of length zero can occur between two delimited partitions,
025: * thus having the same offset as the following delimited partition. The
026: * document start and end are considered to be delimiters of open partitions,
027: * i.e. there may be a zero-length partition between the document start and a
028: * delimited partition starting at offset 0.
029: * </p>
030: *
031: * @since 3.0
032: */
033: public interface IDocumentPartitionerExtension2 {
034:
035: /**
036: * Returns the position categories that this partitioners uses in order to manage
037: * the partitioning information of the documents. Returns <code>null</code> if
038: * no position category is used.
039: *
040: * @return the position categories used to manage partitioning information or <code>null</code>
041: */
042: String[] getManagingPositionCategories();
043:
044: /* zero-length partition support */
045:
046: /**
047: * Returns the content type of the partition containing the given offset in
048: * the connected document. There must be a document connected to this
049: * partitioner.
050: * <p>
051: * If <code>preferOpenPartitions</code> is <code>true</code>,
052: * precedence is given to an open partition ending at <code>offset</code>
053: * over a delimited partition starting at <code>offset</code>.
054: * <p>
055: * This method replaces {@link IDocumentPartitioner#getContentType(int)}and
056: * behaves like it when <code>prepreferOpenPartitions</code> is
057: * <code>false</code>, i.e. precedence is always given to the partition
058: * that does not end at <code>offset</code>.
059: * </p>
060: *
061: * @param offset the offset in the connected document
062: * @param preferOpenPartitions <code>true</code> if precedence should be
063: * given to a open partition ending at <code>offset</code> over
064: * a delimited partition starting at <code>offset</code>
065: * @return the content type of the offset's partition
066: */
067: String getContentType(int offset, boolean preferOpenPartitions);
068:
069: /**
070: * Returns the partition containing the given offset of the connected
071: * document. There must be a document connected to this partitioner.
072: * <p>
073: * If <code>preferOpenPartitions</code> is <code>true</code>,
074: * precedence is given to an open partition ending at <code>offset</code>
075: * over a delimited partition starting at <code>offset</code>.
076: * <p>
077: * This method replaces {@link IDocumentPartitioner#getPartition(int)}and
078: * behaves like it when <preferOpenPartitions</code> is <code>false
079: * </code>, i.e. precedence is always given to the partition that does not
080: * end at <code>offset</code>.
081: * </p>
082: *
083: * @param offset the offset for which to determine the partition
084: * @param preferOpenPartitions <code>true</code> if precedence should be
085: * given to a open partition ending at <code>offset</code> over
086: * a delimited partition starting at <code>offset</code>
087: * @return the partition containing the offset
088: */
089: ITypedRegion getPartition(int offset, boolean preferOpenPartitions);
090:
091: /**
092: * Returns the partitioning of the given range of the connected document.
093: * There must be a document connected to this partitioner.
094: * <p>
095: * If <code>includeZeroLengthPartitions</code> is <code>true</code>, a
096: * zero-length partition of an open partition type (usually the default
097: * partition) is included between two delimited partitions. If it is
098: * <code>false</code>, no zero-length partitions are included.
099: * </p>
100: * <p>
101: * This method replaces
102: * {@link IDocumentPartitioner#computePartitioning(int, int)}and behaves
103: * like it when <code>includeZeroLengthPartitions</code> is
104: * <code>false</code>.
105: * </p>
106: *
107: * @param offset the offset of the range of interest
108: * @param length the length of the range of interest
109: * @param includeZeroLengthPartitions <code>true</code> if zero-length
110: * partitions should be returned as part of the computed
111: * partitioning
112: * @return the partitioning of the range
113: */
114: ITypedRegion[] computePartitioning(int offset, int length,
115: boolean includeZeroLengthPartitions);
116: }
|