ListFormat Class

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

Represents list format which shall be applied to the contents of the parent paragraph.

public sealed class ListFormat : Format
Public NotInheritable Class ListFormat
    Inherits Format
Inheritance:
System.Object
ListFormat
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.

Constructors

ListFormat()

Initializes a new instance of the ListFormat class.

public ListFormat()
Public Sub New

Properties

IsList

Gets a value indicating whether this ListFormat defines the list.

public bool IsList { get; }
Public ReadOnly Property IsList As Boolean
Property Value
System.Boolean

true if this instance defines the list; otherwise, false.

ListLevelFormat

Gets the ListLevelFormat that is applied on the parent Paragraph.

public ListLevelFormat ListLevelFormat { get; }
Public ReadOnly Property ListLevelFormat As ListLevelFormat
Property Value
ListLevelFormat

The ListLevelFormat that is applied on the parent Paragraph.

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.

ListLevelNumber

Gets or sets the list level number for the parent paragraph.

public int ListLevelNumber { get; set; }
Public Property ListLevelNumber As Integer
Property Value
System.Int32

The list level number.

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.

Style

Gets or sets the ListStyle.

public ListStyle Style { get; set; }
Public Property Style As ListStyle
Property Value
ListStyle

The list style.

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.

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.

Clone(Boolean)

Clones this ListFormat instance.

public ListFormat Clone(bool cloneNumberingDefinitionInstance = false)
Public Function Clone(cloneNumberingDefinitionInstance As Boolean = False) As ListFormat
Parameters
cloneNumberingDefinitionInstance
System.Boolean

If true then the Numbering Definition Instance referenced by this ListFormat will also be cloned. This is useful to reset the StartAt while maintaining the rest of the ListLevelFormat.

Returns
ListFormat

Cloned ListFormat.

Equals(Object)

Determines whether the specified System.Object is equal to this ListFormat 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 format instance.

Returns
System.Boolean

true if the specified System.Object is a ListFormat and is equal to this ListFormat instance; otherwise, false.

Overrides
System.Object.Equals(System.Object)

GetHashCode()

Returns a hash code for this ListFormat instance.

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

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

Overrides
System.Object.GetHashCode()

ToString()

Returns a System.String that represents this ListFormat instance.

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

A System.String that represents this ListFormat 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(ListFormat, ListFormat)

Determines whether first and second ListFormats are equal.

public static bool operator ==(ListFormat first, ListFormat second)
Public Shared Operator =(first As ListFormat, second As ListFormat) As Boolean
Parameters
first
ListFormat

The first list format.

second
ListFormat

The second list format.

Returns
System.Boolean

true if first and second list formats are equal; otherwise, false.

Inequality(ListFormat, ListFormat)

Determines whether first and second ListFormats are not equal.

public static bool operator !=(ListFormat first, ListFormat second)
Public Shared Operator <>(first As ListFormat, second As ListFormat) As Boolean
Parameters
first
ListFormat

The first list format.

second
ListFormat

The second list format.

Returns
System.Boolean

true if first and second list formats are not equal; otherwise, false.

Inherited Properties

Document

Gets the owner document.

(Inherited from Format)