QHeaderView sections: visualIndex vs logicalIndex

Headers provided by QHeaderView are made of sections which can be referred to by using indexes. There are two kind of indexes, visual and logical. I think the reference documentation is somewhat confusing when explaining what those indexes are and how they differ from each other. This blog entry is the result of trying to clarify those issues to myself.

Visual indexes tell us the current position that a given section occupies in the header. So let’s suposse we create a five columns table and that we label the sections of its horizontal header as C0, C1, C2, C3 and C4 (the C being a shorthand for column). The visual indexes of these sections are showed in the next figure:

	C0	C1	C2	C3	C4
Visual Index	0	1	2	3	4

By definition, the visual index of a given section will change if the section is moved to a different position. For example, if we move the C3 section to the second position of the header (via QHeaderView.moveSection(3, 1)) then the position of sections C1, C2 and C3 will change. As a result also their visual indexes will change:

	C0	C3	C1	C2	C4
Visual Index	0	1	2	3	4

As we can see even after moving around some sections the set of visual indexes remains ordered as 0, 1, 2… N. So far so good.

However there is a detail one has to be aware of: hiding/showing a given section (calling QHeaderView.hideSection method) does NOT change its visual index as one could expect. So if in our current header we hide the section C0 no visual index will change:

	C3	C1	C2	C4
Visual Index	1	2	3	4

Time to talk about logical indexes. For a given section the value of its logical index depends on the position at which it was added to the header. So when our sample table was just created we had:

	C0	C1	C2	C3	C4
Logical Index	0	1	2	3	4

because C0 was added at position 0, C1 was added at position 1 and so on. Moving sections around doesn’t change any logical index so if we move the C3 section to the second position we will have:

	C0	C3	C1	C2	C4
Logical Index	0	3	1	2	4

But inserting/removing sections (which can be done inserting/removing columns in our table model) will change the logical indexes of the implied sections. For instance, if now we insert a new column, labeled as NC for the sake of clarity, at position 2 we will have:

	C0	C3	NC	C1	C2	C4
Logical Index	0	4	2	1	3	5

The sections C0 and C1 had a logical index lower than 2 so they will keep their logical index unchanged but sections C2, C3 and C4 had a logical index greater than or equal to the logical index of the new section. As a result their logical index will be increased by one.

Hopefully you have now a better understanding of what visual and logical indexes are and will be able to use them without being puzzled by methods like logicalIndex, logicalIndexAt, visualIndex and visualIndexAt provided by QHeaderView.

Advertisement