ListLevelFormat Class

Namespace:
GemBox.Document
Assembly:
GemBox.Document.dll

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.Object
ListLevelFormat
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
HorizontalAlignment

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
ParagraphStyle

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.

public Picture BulletPicture { get; set; }
Public Property BulletPicture As Picture
Property Value
Picture

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
CharacterFormat

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.

public bool IsLegal { get; set; }
Public Property IsLegal As Boolean
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.

public int Level { get; }
Public ReadOnly Property Level As Integer
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.

public string NumberFormat { get; set; }
Public Property NumberFormat As String
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.

public double NumberPosition { get; set; }
Public Property NumberPosition As Double
Property Value
System.Double

The number position.

Remarks

This property is shorthand for ParagraphFormat.LeftIndentation property.

NumberStyle

Gets or sets the number style.

public NumberStyle NumberStyle { get; set; }
Public Property NumberStyle As NumberStyle
Property Value
NumberStyle

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
ParagraphFormat

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.

public int RestartAfterLevel { get; set; }
Public Property RestartAfterLevel As Integer
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.

public int StartAt { get; set; }
Public Property StartAt As Integer
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.

public double TextPosition { get; set; }
Public Property TextPosition As Double
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
ListTrailingCharacter

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.

public override void ClearFormatting()
Public Overrides Sub ClearFormatting
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
System.Object.Equals(System.Object)

GetHashCode()

Returns a hash code for this ListLevelFormat instance.

public override int GetHashCode()
Public Overrides Function GetHashCode As Integer
Returns
System.Int32

An integer value that specifies a hash value for this ListLevelFormat instance.

Overrides
System.Object.GetHashCode()

ToString()

Returns a System.String that represents this ListLevelFormat instance.

public override string ToString()
Public Overrides Function ToString As String
Returns
System.String

A System.String that represents this ListLevelFormat instance.

Overrides
System.Object.ToString()
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)