Calligra/Words/Tutorials/Lists

An overview of lists in ODF

In ODF, there are three reasons why a paragraph appears as a list item

  * ODF text:list
  * ODF text:numbered-parargaph
  * ODF text:heading

ODF text:list

A text:list has text:list-items inside it. list-items can inturn be lists aka sublists. A list can be associated with a list style. A list style defines the style of upto 10 levels of sublists (i.e) it says Level 1 lists are bulleted with '*', level 2 sublist is numbered and so on.

In the case where the text:list does not have an associated list style, we use the style of its parent list and so on. What if the top most list has no list style? In ODF, a paragraph style can have an associated list-style. So, ODF recommends that we use the paragraph's list style if none of the text:list have a list-style. This awful quirk of ODF causes a lot of confusion. To start with, just having a list-style in a paragraph style does not make the paragraph as a part of a list. To rephrase, the list style of a paragraph style is used ONLY when the list that it is a part of specifies no list style. Since in practice, text:list never appears without a style, the paragraph style's list style is nearly never used.

list-item can be one of the below

  * a list-header. Heading of a list which has same indentation as a list-item but not bulleting.
  * one or more paragraphs. In the case when a list-item has more than one paragraph, the rest of the paragraphs are called "unnumbered paragraphs" in kword terminology.
  * a text:list

ODF text:numbered-paragraph

Numbered paragraph's are a mechanism by which a single paragraph can have an associated list style. For example, the user wants to have a style that is used for showing "tips" in his document. This "tips" style shows a nice bulb like bullet at the beginning of the paragraph. numbered-paragraphs have an associated list style and a level that determins which level of the list-style them must follow.

Note that the paragraph having a list style is purely from a UI/user point of view. As discussed above, a paragraph's list-style is practically never used.

ODF text:heading

Pinaraf knows this best.

KWord and lists

KoListStyle represents the list-style. KoListLevelProperties represents the style of each level. In effect, KoListStyle is just QMap<level, KoListLevelProperties>.

In KOffice, an ODF list is represented by KoList. A KoList has a KoListStyle associated with it. Each level of a list is stored in a QTextList. KoList stores a QMap<level, QTextList>. In addition,

   * KoParagraphStyle::ListStyleId points to the named list style.
   * To determine the level of a block, one should use KoListStyle::Level.

Numbered paragraphs are also held together by a KoList. Since a KoList holds a KoListStyle, this makes it possible to change the level of a paragraph and automatically get the correct settings for the level (when tab is pressed for example). The main difference between a numbered paragraph and a ODF list is that KoParagraphStyle::ListLevel determines the level of the numbered-paragraph. This property is only distinction to determine if the paragraph is part of a text:list or if it is a numbered-paragraph.

List headers have the KoParagraphStyle::IsListHeader set.

Unnumbered paragraphs have the KoParagraphStyle::UnnumberedListItem set.