lists.txt

richview1.7 full.source

========== 1. Overview ==========
Bullets/numberings (lists) are implemented in the following way:
1) There is a new collection of styles: TRVStyle.ListStyles.
  Each list style contains a collection of list levels (Levels property). A list level defines the most of list properties.
2) List markers is a special kind of items. They are inserted with special functions.
  They are always inserted at the beginning of paragraph. 
  They have the following properties:
  - ListNo - index of list style in the collection of list styles
  - LevelNo - list level
  - StartFrom - starting value for list counter, if UseStartFrom=True
  - UseStartFrom - if true, list counter value for this marker is defined by StartFrom.
      If false, counter continues.

========== 2. Valid documents ========== 

There are some limitations on document structure, and list markers add a few.
This chapter has no direct relation to lists, but contains an important information.

Bellow is a summary.

Internally, each document item has properties: 
 - index of paragraph style
 - "this item starts a paragraph" flag
 - "this item starts a line inside a paragraph" flag
Not all combinations are acceptable.

All operations in editor always create a valid document (providing that it was valid before the operation).
But some operations in viewer can create invalid documents (especially DeleteItems)

Rules of valid documents:
1) All items in paragraphs must have the same index of paragraph style
  (in the most cases, RichView provide this;
   it's possible to create invalid documents by incorrect using of DeleteItems and SetAddParagraphMode)
2) First item (in document or table cell) must start a paragraph.
3) Full-line items (breaks and tables) must start a new paragraph.
   Items after full-line items must start a new paragraph
4) Table cells must contain at least one item (by default they contain one empty text item)
5) List markers must start a new paragraph.
6) Paragraph after marker must contain at least one item (may be an empty text item)
  Documents where next item after marker starts a new paragraph (or a line) are incorrect
7) Empty text items can be only in empty paragraphs (the only item in paragraph, or the only item after list marker)

========== 3. List levels and counters ========== 
Numbering can be multilevel (up to 256 levels).
A default value of counter is "value of counter of previous list marker of the same style and level"+1.
Counters can be reset in two cases:
- if UseStartFrom is true for this list marker counter is set to StartFrom value
- if there is a marker of the same style but with higher level before this marker, the counter is reset to StartFrom property value of list level (1 by defalt)
  (you can exclude rvloLevelReset from Options of list level to prevent this)
(!!!) RichView uses "modern" MS Word 97+ model of numbering: it's no matter how many paragraphs without markers (or with markers of another style) between two paragraphs with markers of the same style, counter will be incremented.
May be in future an older MS Word 95- model will be implemented too (when only adjacent paragraphs have list counter incremented; "skip numbering" command).

========== 4. List style properties ========== 
List style (TRVStyle.ListStyles[i]) does not have important properties, except from Levels - collection of TRVListLevel.
Each item of this collection defines properties of list level of given style.
Properties of list level are discussed below.

==== 4.1 Properties for list marker ====
The main property is ListType:TRVListType;
TRVListType = (rvlstBullet, rvlstPicture, rvlstImageList,
               rvlstDecimal, rvlstLowerAlpha, rvlstUpperAlpha,
               rvlstLowerRoman, rvlstUpperRoman, rvlstImageListCounter);
* rvlstBullet - unnumbered text (from FormatString property)
* rvlstUnicodeBullet - unnumbered Unicode text (from FormatStringW property)
* rvlstPicture - picture (from Picture property)
* rvlstImageList - image from imagelist (ImageList and ImageIndex properties)
* rvlstDecimal - 1, 2, 3,... (see FormatString)
* rvlstLowerAlpha - a, b, c, ..., z, aa, ab, ... (see FormatString)
* rvlstUpperAlpha - A, B, C, ..., Z, AA, AB, ... (see FormatString)
* rvlstLowerRoman - i, ii, iii, iv, ... (see FormatString)
* rvlstUpperRoman - I, II, III, IV, ... (see FormatString)
* rvlstImageListCounter - image from image list, depending on counter (ImageList and ImageIndex properties: counter=1 -> ImageIndex-th image, counter=2 -> (ImageIndex+1)-th image, and so on)

As you can see, rvlstBullet..rvlstImageList define unordered lists, rvlstDecimal..rvlstImageListCounter - ordered lists.

FormatString property defines how to display numbers.
For rvlstBullet list type, it completely defines a text to display.
For rvlstDecimal..rvlstUpperRoman, an actual string 
 = Format(FormatString, [CL0, CL1, ..., CLN])
where 
CL0 - string containing value of counter of the 0-th level marker
CL1 - ......................................... 1 ...............
CLN - string containing value of counter of this level marker
Example1:
FormatString = '*' // no numbering

Example2:
For 0-th level: FormatString = '%s.', ListType=rvlstDecimal
For 1-th level: FormatString = '%s.%s.', ListType=rvlstDecimal
{ 
  1. aaaaa
  2. aaaaa
    2.1. aaaaa
    2.2. aaaaa
  3. aaaaa
}

Example3:
For 0-th level: FormatString = '%s.', ListType=rvlstDecimal
For 1-th level: FormatString = '%1:s)', ListType=rvlstLowerAlpha
{  
  1. aaaaa
  2. aaaaa
    a) aaaaa
    b) aaaaa
  3. aaaaa
} 

If rvloLevelReset is in Options (default), numbering will be like this:
  1. aaaa
    a) aaaa
    b) aaaa
  2. aaaa
    a) aaaa
    b) aaaa
 If it is excluded, numbering will be like this:
  1. aaaa
    a) aaaa
    b) aaaa
  2. aaaa
    c) aaaa
    d) aaaa

If rvloLegalStyleNumbering is in Options, all roman and alpha numbering of higher levels will be changed to decimals, like this:
  I. aaaa
    1.1 aaaa
    1.2 aaaa
  II. aaaa
Font property defines a font for list marker text (rvlstBullet, rvlstDecimal..rvlstUpperRoman)

==== 4.2 Layout ====
LeftIndent - defines a left indent for all lines of marked paragraph except from the first line (overrides LeftIndent of paragraph style)
FirstIndent - defines a left indent for the first line of marked paragraph (overrides FirstIndent of paragraph style)
MarkerIndent - defines an indent of marker.
MarkerAlignment:
 * rvmaLeft - left side of marker is aligned to MarkerIndent
 * rvmaRight - right side ..................................
 * rvmaCenter - center .....................................

========== 5. RVF ========== 
Saving:
List styles are saved in RVF if rvfoSaveParaStyles is in RVFOptions.
Loading:
If RVFParaStylesListMode = rvf_sIgnore or rvf_sInsertMap, list styles in RVF are ignored.
If RVFParaStylesListMode = rvf_sInsertMerge, list styles from RVF replace existing list styles on loading, and merged with existing styles on inserting.
OnRVFImageListNeeded occurs when loading list levels with image lists.

========== 6. Methods ========== 

==== 6.1 Methods of TRichView ====

These methods cannot be undone and do not reformat document.

function SetListMarkerInfo(AItemNo, AListNo, AListLevel, AStartFrom, AParaNo: Integer;
                                     AUseStartFrom: Boolean): Integer;
Inserts list marker with the given properties.
AItemNo - index of any item in paragraph (marker will be inserted at the beginning of this paragraph).
If AItemNo<0 or >ItemCount, a new marker is added at the end of document.
If this paragraph already has a marker, this function changes its properties without inserting a new one.
This function returns an item index of marker.
AParaNo is used to define a paragraph style of marker starting a new paragraph.
If this marker is added to the existing paragraph, this parameter is ignored.

function GetListMarkerInfo(AItemNo: Integer;
                                 var AListNo, AListLevel, AStartFrom: Integer;
                                 var AUseStartFrom: Boolean): Integer;
Returns properties of list marker.
AItemNo - index of any item in paragraph.
If this paragraph does not have a marker, this function returns -1, otherwise it returns an item index of marker.

procedure RemoveListMarker(ItemNo: Integer);
Deletes a marker.
AItemNo - index of any item in paragraph.

==== 6.2 Methods of TRichViewEdit ====

These methods can be undone and reformat document.

procedure ApplyListStyle(AListNo, AListLevel, AStartFrom: Integer;
                             AUseStartFrom, ARecursive: Boolean);
Adds/changes list markers for the selected paragraph(s);
If AListLevel=-1, levels of existing markers are not changed, new markers have level=0
ARecursive - not yet implemented (planned: include tables or not)

procedure RemoveLists(ARecursive: Boolean);
Removes markers for the selected paragraphs.
ARecursive - not yet implemented (planned: include tables or not)

procedure ChangeListLevels(LevelDelta: Integer);
Changes list levels of selected paragraphs.
For example, 
  rve.ChangeListLevels(+1) - increases level by 1, 
  rve.ChangeListLevels(-1) - decreases level by 1.

More to come...

========== 7. Limitations of RTF import/export ========== 
Richedit and Word6/95 stores lists differently from Word97,2000,XP.
Limitation when importing Word6/95 RTF:
- multilevel lists are imported as one level;
- indents in paragraphs with "skip numbering" option can be incorrect
  (smaller than in Word)
- all numbers in the same list will have the same formatting
  (formatting of the first number); bulleted lists do not have this
  limitation.
- "start from" value is set explicitly for the first number in list.
Limitation when importing Word97+ RTF:
- some font and paragraph properties that applied over lists are ignored.
  (but all significant options which can be specified in MS Word
  dialog for bullets properties are imported)
Limitation when exporting:
- bullets and numbering are saved in Word97+ format. When opening such
  RTF files with MS Word6 or richedit, bullets/numbering are converted
  to text (the same effect as loading Word97+ RTF files).
  Unicode bullets may be processed by RichEdit incorrectly (wrong characters).
MS Word image-bullets are imported as regular images.
RichView image-bullets are exported as regular images. 
========== 8. Limitations of HTML export ========== 
==== 8.1 with CSS (SaveHTMLEx) ====
Note: CSS of lists are inserted directly in HTML.
* rvlstBullet, rvlstUnicodeBullet
  - exported as bullets with default markers, 
  FormatString and Font are ignored;
* rvlstDecimal,rvlstLowerAlpha,rvlstUpperAlpha,rvlstLowerRoman,rvlstUpperRoman
  - exported as lists with correspondent numbering, 
  FormatString and Font are ignored;
* rvlstPicture,rvlstImageList,rvlstImageListCounter,
  - exported as bullet with picture;
  allows to change default image saving by OnHTMLSaveImage;
  RichView tries to avoid saving duplicates of the same image;
  rvlstImageList,rvlstImageListCounter can share image with bullet and hotspot
  item types.
Indents are saved, but not very accurately.  
==== 8.2 without CSS (SaveHTML) ====
* rvlstBullet, rvlstUnicodeBullet,rvlstPicture,rvlstImageList
  - exported as bullets with default markers, 
  FormatString, Picture, ImageList and Font are ignored;
* rvlstDecimal,rvlstLowerAlpha,rvlstUpperAlpha,rvlstLowerRoman,rvlstUpperRoman
  - exported as lists with correspondent numbering, 
  FormatString and Font are ignored;
* rvlstImageListCounter,
  - saved as decimal numbering.
Indents are not saved.
==== 8.3 Alternative mode of HTML export ====
Include rvsoMarkersAsText in the last parameter for HTML saving.
Markers will be saved without using special
HTML keywords for lists (like <OL>, <UL>, <LI>).
Font and format strings settings are respected.
Saving without CSS: all indents are ignored.
Saving with CSS: LeftIndent and MarkerIndent are retained. 
  FirstIndent are retained for non-hanging markers only (MarkerIndent>=LeftIndent),
   and in IE only (tested with IE6).
Generally, htmls saved with this option look closer to the original.

========== 9. TO-DO ========== 
Known issues:
- image list are not saved when saving RVStyle to ini-file/registry.