Enable controlling the TOC entry level

[hvbargen]

In some cases, the PDF outline (TOC) generated by BIRT, does not really fit. It's ok as long as one is only using list and table groups for generating the TOC, but sometimes one needs more than this static structure.
See https://bugs.eclipse.org/bugs/show_bug.cgi?id=400954 for an example.

It would be useful if one could control the TOC level (0=root, 1=direct children of root, 2=children of level 1 etc) and maybe if this TOC entry causes to "go into" that level.

Let me explain by comparing this to HTML headings:

BIRT's default behavior is like this (the description is probably incomplete):

We start with a root node (level 0) as the "current node".
When we find a label or dynamic text item with a TOC entry, we create a new node as the child of the current node (so this has a level one higher than the current node) and we keep the current node.
When we find a list or table group with a TOC entry, we create a new node as the child of the current node like before, but we "go into" this new node, making it the current node. Only when we close the group (after creating the group footer if defined), we also close the node, making its parent the current node.

For example, assume there is a table with two groups G1 and G2 (both with a TOC entry set) and inside the table detail row there is a label with a TOC entry, then BIRT creates a TOC structure like this (the indentation representing the level):

root
    H1: G1 value 1
        H2: G2 value A
            H3: detail 1
            H3: detail 2
         H2: G2 value B
            H3: detail 3
    H1: G1 value 2
         H2: G2 value C (might be the same as A or B)
              H3: detail 4

Now consider the example from https://bugs.eclipse.org/bugs/show_bug.cgi?id=400954: Assume want to generate this instead:

root
    H1: G2 value A
        H2: detail 1
        H2: detail 2
    H1: G2 value B
        H2: detail 3
     H1: G2 value C (might be the same as A or B)
        H2: detail 4

Note: This is only one example, there are many similar cases where I would like to control the nesting level.

My idea is (to keep things simple) to introduce two new UserProperties for controlling the TOC nesting:

• TOC.Level is an integer to directly set the nesting level, if specified.
• TOC.Enter is a boolean which decides if we "enter" the new TOC node (that is, make it the new current node).

We could then set TOC.Level = 1 for the group G1.

TOC.Enter = true is not needed in this example, but it makes sense if have labels that represent "sections" of the report. We could set it for these labels.

I looked at the code for TOC generation to see if I could create a prototype for this feature, but unfortunately I do not understand it.
Relevant files are (I think), in particular ReportItemExecutor.java and TOCBuilder.java.

Note: My comparison to HTML headings is not quite correct, because HTML headings are not nested in reality.