ListLevelFormat Class
Represents formatting definition which specifies the appearance and behavior of a list level. A list level contains a set of properties for the display of the numbering for a given list level.
public sealed class ListLevelFormat : Format
Public NotInheritable Class ListLevelFormat
Inherits Format
- Inheritance:
- System.ObjectListLevelFormat
Remarks
List (for example, ordered - with numbers, or unordered - with bullets) appearance in GemBox.Document is defined through ListFormat class that is set on Paragraph's ListFormat property or ParagraphStyle's ListFormat property.
ListFormat is different from other formats (ParagraphFormat and CharacterFormat) because it doesn't directly contain any formatting properties.
It contains a reference to a ListStyle which exposes ListLevelFormats for every list (indentation) level through its ListLevelFormats property.
ListLevelFormats contain direct formatting properties that affect the appearance of the list. Every ListStyle contains exactly 9 ListLevelFormats, one for each possible list (indentation) level.
Paragraph's list (indentation) level can be adjusted with ListLevelNumber property. Paragraph's list-related formatting will then be collected from the ListLevelFormat instance contained in the ListLevelFormats at the position ListLevelNumber. This ListLevelFormat can also be retrieved from the ListLevelFormat property.
ListLevelFormat retrieved from the ListLevelFormat property can be additionally modified to enable overriding property values of ListLevelFormat instance contained in the ListLevelFormats at the position ListLevelNumber on a Paragraph or ParagraphStyle basis.
To create a list in a document, first ListStyle instance has to be created from one of the predefined list style types specified with ListTemplateType enumeration. After that, ListFormat can be created with a specified ListStyle and assigned to a Paragraph's ListFormat property. For a complete example, see Lists example.
If ListStyle is not referenced from anywhere in the document (from any Paragraph or ParagraphStyle, then it won't be saved to a Word Document (DOCX) file, unless it is added to Styles collection.
Paragraph's list content, which prefixes paragraph content, is represented by ListItem type.
ListItems are not permanently stored in model nor they are written to file formats which fully support ListFormat, instead they are recreated each time CalculateListItems() method is called.
If document content or formatting is changed, then CalculateListItems() method should be called again to retrieve the latest list items.
For convenience, after calling CalculateListItems() method, ListItem can also be retrieved from ListItem property.
After calling System.IDisposable.Dispose on System.Collections.Generic.IEnumerator<T> instance retrieved by calling System.Collections.Generic.IEnumerable<T>.GetEnumerator() on instance returned from CalculateListItems() method, paragraph's ListItem property will be null even if paragraph's IsList is true. This enables easy iteration over ListItems returned from CalculateListItems() method by using foreach statement and removing all references to ListItems after the iteration is finished.
Properties
Alignment
Gets or sets the horizontal alignment used on a list level's text specified in the NumberFormat property within a given list level.
public HorizontalAlignment Alignment { get; set; }
Public Property Alignment As HorizontalAlignment
Property Value
The horizontal alignment used on a list level's text specified in the NumberFormat property within a given list level.
Remarks
This alignment is applied relative to the text margin of the parent numbered paragraph in the document.
Default value is Left.
Exceptions
- System.InvalidOperationException
ListLevelFormat supports only Left, Center and Right horizontal alignment.
AssociatedParagraphStyle
Gets or sets the ParagraphStyle which shall use this list level when applied to the contents of the document.
public ParagraphStyle AssociatedParagraphStyle { get; set; }
Public Property AssociatedParagraphStyle As ParagraphStyle
Property Value
The ParagraphStyle which shall use this list level when applied to the contents of the document.
Remarks
When a ParagraphStyle is defined to include a ListFormat, any list level defined by ListLevelNumber shall be ignored, and instead this property shall specify the list level associated with that ParagraphStyle.
Default value is null which means that no ParagraphStyle is associated with this list level.
BulletPicture
Gets or sets a picture which shall be used as a list symbol for a given list level.
Property Value
A picture which shall be used as a list symbol for a given list level.
Remarks
The picture shall be added to the list level by replacing each character in the NumberFormat with one instance of this image.
Default value is null.
CharacterFormat
Gets or sets the character format which shall be applied to the list level's text specified in the NumberFormat property when it is applied to paragraphs in this document.
public CharacterFormat CharacterFormat { get; set; }
Public Property CharacterFormat As CharacterFormat
Property Value
The character format which shall be applied to the list level's text specified in the NumberFormat property when it is applied to paragraphs in this document.
Remarks
This character format is applied to all numbering level text used by a list level. It should be noted that character format specified on a numbered paragraph itself, or on text runs within a numbered paragraph, are separate from the character format specified within a list level, as the latter affects only the numbering text itself, not the remainder of runs in the numbered paragraph.
IsLegal
Gets or sets the value which specifies whether or not all previous levels displayed for a given list level's text specified in the NumberFormat property shall be displayed using the Decimal (Arabic numerals), regardless of the actual NumberStyle of that level in the list.
Property Value
- System.Boolean
The value which specifies whether or not all previous levels displayed for a given list level's text specified in the NumberFormat property shall be displayed using the Decimal (Arabic numerals), regardless of the actual NumberStyle of that level in the list.
Remarks
If this property is true, then all list levels present in the NumberFormat property shall be converted to their decimal equivalents when they are displayed in this level. If this property is false, then each level is displayed using the NumberStyle of that level.
Default value is false.
Level
Gets the level of this ListLevelFormat.
Property Value
- System.Int32
The level of this ListLevelFormat.
Remarks
This value is a zero-based index of the number of list levels in the document. For example, a value of 2 is the 3rd list level in the document.
NumberFormat
Gets or sets a value which specifies the textual content which shall be displayed when displaying a paragraph with the given list level.
Property Value
- System.String
A value which specifies the textual content which shall be displayed when displaying a paragraph with the given list level.
Remarks
All text in this property's value shall be taken as literal text to be repeated in each instance of this list level, except for any use of the percent symbol (%) followed by a number, which shall be used to indicate the one-based index of the number to be used at this level. Any number of a level higher than this level shall be ignored.
When the % syntax is used, the number shall be incremented for each subsequent paragraph of that level (sequential or not), until the restart level is seen between two subsequent paragraphs of this level.
Default value is System.String.Empty.
NumberPosition
Gets or sets the position (in points) of the number or bullet for the list level.
Property Value
- System.Double
The number position.
Remarks
This property is shorthand for ParagraphFormat.LeftIndentation property.
NumberStyle
Gets or sets the number style.
Property Value
The number style.
Remarks
This property specifies the number style which shall be used to display all numbering at this level. This information is used to replace the level text string %x in NumberFormat property, where x is a particular one based level index, with the appropriate value. This value shall be calculated by counting the number of paragraphs at this level since the last restart using the numbering system defined in this property.
Default value is Decimal.
ParagraphFormat
Gets the paragraph format which shall be applied as part of a given list level. This paragraph format is applied to any numbered paragraph that uses this list level.
public ParagraphFormat ParagraphFormat { get; }
Public ReadOnly Property ParagraphFormat As ParagraphFormat
Property Value
The paragraph format which shall be applied as part of a given list level.
Remarks
Paragraph format properties specified on the numbered paragraph itself override the paragraph format properties specified on a list level used by that paragraph.
RestartAfterLevel
Gets or sets the list level that must appear before the specified list level restarts numbering.
Property Value
- System.Int32
The list level that must appear before the specified list level restarts numbering.
Remarks
This property specifies a one-based index which determines when a list level should restart to its StartAt value. A list level restarts when an instance of the specified list level, which shall be higher (earlier than the this level) is used in the given document's contents.
Default value is zero-based level of this ListLevelFormat which means that list level shall restart each time the previous list level is used. If the specified level is higher than the current level, then this element shall be ignored. As well, a value of 0 shall specify that this level shall never restart.
StartAt
Gets or sets the starting number for this list level.
Property Value
- System.Int32
The starting number for this list level.
Remarks
This value is used when this level initially starts in a document, as well as whenever it is restarted via the RestartAfterLevel property.
Default value is 0.
TextPosition
Gets or sets the position (in points) of the text.
Property Value
- System.Double
The text position.
Remarks
This property is shorthand for ParagraphFormat.SpecialIndentation property.
TrailingCharacter
Gets or sets the value which specifies the content which shall be added between a given list level's text specified in the NumberFormat property and the text of every numbered paragraph which references that list level.
public ListTrailingCharacter TrailingCharacter { get; set; }
Public Property TrailingCharacter As ListTrailingCharacter
Property Value
The value which specifies the content which shall be added between a given list level's text specified in the NumberFormat property and the text of every numbered paragraph which references that list level.
Remarks
Default value is Tab.
Methods
ClearFormatting()
Clears the formatting.
Overrides
Remarks
This method will clear all directly set formatting values. When retrieving formatting value, they can still come from other sources, as explained in formats and styles article.
Equals(Object)
Determines whether the specified System.Object is equal to this ListLevelFormat instance.
public override bool Equals(object obj)
Public Overrides Function Equals(obj As Object) As Boolean
Parameters
obj
- System.Object
The System.Object to compare with this list level format instance.
Returns
- System.Boolean
true if the specified System.Object is a ListLevelFormat and is equal to this ListLevelFormat instance; otherwise, false.
Overrides
GetHashCode()
Returns a hash code for this ListLevelFormat instance.
Returns
- System.Int32
An integer value that specifies a hash value for this ListLevelFormat instance.
Overrides
ToString()
Returns a System.String that represents this ListLevelFormat instance.
Returns
- System.String
A System.String that represents this ListLevelFormat instance.
Overrides
Remarks
This method should be used primarily for debugging purposes and should be considered volatile (format of its return value might change in future versions).
Operators
Equality(ListLevelFormat, ListLevelFormat)
Determines whether first
and second
ListLevelFormats are equal.
public static bool operator ==(ListLevelFormat first, ListLevelFormat second)
Public Shared Operator =(first As ListLevelFormat, second As ListLevelFormat) As Boolean
Parameters
first
- ListLevelFormat
The first list level format.
second
- ListLevelFormat
The second list level format.
Returns
- System.Boolean
true if first
and second
list level formats are equal; otherwise, false.
Inequality(ListLevelFormat, ListLevelFormat)
Determines whether first
and second
ListLevelFormats are not equal.
public static bool operator !=(ListLevelFormat first, ListLevelFormat second)
Public Shared Operator <>(first As ListLevelFormat, second As ListLevelFormat) As Boolean
Parameters
first
- ListLevelFormat
The first list level format.
second
- ListLevelFormat
The second list level format.
Returns
- System.Boolean
true if first
and second
list level formats are not equal; otherwise, false.
Inherited Properties
Document | Gets the owner document. (Inherited from Format) |