TOC is inserted in the position specified in ItemNo.
Possible values of ItemNo:
* 0 - inserting at the beginning of rv;
* rv.ItemCount - inserting at the end of rv
* any value from 1 to rv.ItemCount-1 - inserting before the item with this index; this item must have a page break (i.e. rv.PageBreaksBeforeItems[ItemNo] must be True), otherwise this function does nothing and returns False.

This function returns True on successful inserting. If the document does not have headings with levels in range 1..Depth, this function does nothing, but still returns True.

RVPrint must be formatted before the call of this function. After the call, it is not formatted (call RVPrint.FormatPages again before printing).

Rv is not formatted after the call of this function (call rv.Format before displaying it).

Title is added before the TOC, using TitleStyleNo and TitleParaNo styles. Depth is a maximal heading level for TOC.

TextStyleNos and ParaStyleNos are arrays containing styles for TOC. They must have Depth items.
TitleStyleNo[0] and TitleParaNo[0] are used for adding heading level 1 in TOC,
TitleStyleNo[1] and TitleParaNo[2] are used for adding heading level 2 in TOC,
and so on.

TOC is added not as an editing operation! Undo is not possible. If called for TRichViewEdit, call ClearUndo method.

TOC is added as Unicode strings in Delphi 2009-2010, and as ANSI strings in older version of Delphi (so foreign characters may be lost on conversion)

Version for TRVReportHelper

In this version of the function, the document is contained in RVReportHelper.RichView.

Additional parameters:
Canvas - a canvas that was used for RVReportHelper.Init(), or another canvas with the same resolution;
PageWidth - width of pages (used in Init).
FirstPageHeight - height of the first page (used in FormatNextPage)
PageHeight - height of other pages (used in FormatNextPage)
These parameters are used only if ItemNo<RVReportHelper.RichView.ItemCount (i.e. if TOC is added not to the end). If the TOC is added to the end, you can pass any values to these parameters.

RVReportHelper must be formatted before the call of this function.
After the call, it is not formatted.

This procedure searches for the first occurence of the paragraph with OutlineLevel=Level, and returns:
- the style of this paragraph (in ParaNo),
- the style of text in this paragraph (in StyleNo).
Paragraphs without text are ignored. If there is no such paragraph, this procedure returns 0, 0.
These values can be used as TitleStyleNo, TitleParaNo parameters for AddTableOfContents.

Possible ways to improve:
1) Inserting as an editing operation (that can be undone by the user).
2) The same function for RVReportHelper instead of RVPrint.
3) The same function for ScaleRichView.
4) Working via Unicode even for old versions of Delphi (4-2007)

A couple of questions though. Does it work if the table of content will not fit on one page ? Also, sometimes there are cover pages or titles pages before the table of content: how could it be inserted just after those pages ?

Yes, multipage TOC is handled correctly.
As for title pages... How do you think it will be convenient to define them? Specifying ItemNo where to insert TOC?
Or do you want to insert it in editor, in the caret position?

Updated. The parameter ToBeginning is superseded by the parameter ItemNo. Limitation: when inserting to the middle, there must be a hard page break at this ItemNo.

As for TRVReportHelper, it appears to be more difficult. The function needs to know not only Width specified in Init, but also heights of all pages specified in FormatNextPage, and heights of new pages (since adding TOC increases the count of pages).

Thank you, Sergey, for the GetPageNo() method and for the example.
I seem to have it working in my app, but I would like to better understand GetPageNo(). Where can I get documentation for RV 12.2.3 and/or this method? In particular, why is the first parameter necessary when I have already assigned an RVData to the RVPrint?

In GetPageNo, RVData parameter may be:
- rv.RVData, where rv is a TRichView control assigned in RVPrint.AssignSource
- table cell.
You can see how GetPageNo used in RVTOC.pas, in function BuildTOCStructure.

I have updated the unit, a function for TRVReportHelper is included.
The messages above are updated as well, with information and example for TRVReportHelper.

This version has a limitation - only two values of a page height are possible: one for the first page, one for other pages. I believe it covers 99.9% of cases, since different heights for all pages are rarely needed.

How hard would it be to update the code to also produce a table of contents for a standard TRichView(Edit) which, instead of adding fixed page numbers, would export it using the "PAGEREF" RTF code such as Microsoft Word ?

If you already have a demo on how to achieve that, it would be very useful.