Composite Pages

Composite pages enable you to construct a page with multiple switchable sections that can cycle through different sub-views while the main part of the page stays the same (think of how manufacturers added small LCD screens between the analog clocks in the 2000’s and made it possible to change what was displayed by pressing a button on the indicator stalk or steering wheel).

Composite pages are defined as regular pages, with a page number. They are then embedded into another page at the beginning of the page definition, in a <composite> section.

If you are using a next/previous page button for the main pages rather than direct touch screen access, then any page that is included as a composite anywhere will not be included in the group of pages you can cycle through.

It is also possible to simply construct a page using 2 or more composite pages with one page per group if you wanted to. There does not have to be more than one composite page in a group. Only one page from each group will ever be displayed at the same time though.

To define the visible sections and how the sub-pages rotate between each other, composites are assigned a group. All composites with the same group id on the page are considered as a rotatable set. To this end, they need to be placed in the same (x,y) location on the page otherwise they will jump around. There is a rectangle gauge that can help with this (see later). Some of the examples later should help to make all this clearer.

In order to cycle through the views you need some sort of input mechanism (hardware button or touchscreen). If you have more than one composite group on a page you need both a cycle page button and a cycle group button.

Context:

<page>
    <pagenumber>9</pagenumber>
    <pagename>Classic Mode Dash</pagename>
    <composites>
        <group id="0">
        ....
        </group>
        <group id="1">
        ...
        </group>
    </composites>

    <gauges>
        <gauge>
        ...
        </gauge>
    </gauges>
</page>

Composite pages are defined as follows;

  1. Create the page you want to use as a composite in the standard way, and add it to the end of the <pagelist> section. It does not have to be at the end but it makes sense to separate pages used as composites from pages that are ‘parent’ pages.

  2. Define the page as a composite on the page you want it to appear on:

<composites>
    <group id="0">
        <composite page="12" x="810" y="182" xscale="1" yscale="1" highlightx="50"         highlighty="375"></composite>
    </group>
</composites>

Here, the composite being added to our parent page is page 12. It has been placed in composite group 0, and there is only the one page so no group cycling will be possible. There are some attributes assigned to the composite; these are:

  • page - the page number to embed into the parent.
  • x - the x location on the parent page where the child page should be drawn.
  • y - the y location on the parent page where the child page should be drawn.
  • xscale - this is a floating point number that allows the page to be shrunk down or magnified if needed. Values less than 1 indicate shrinkage.
  • highlightx - this is a coordinate relative to the child page’s origin of where a small red dot should be drawn showing which composite group is selected when swapping between groups.
  • highlighty - y location for highlight dot.

If you want more than one composite page in the same group, simply add another <composite> entry to the group with the new page number:

<composites>
    <group id="0">
        <composite page="12" x="810" y="182" xscale="1" yscale="1" highlightx="50" highlighty="375"></composite>
        <composite page="13" x="810" y="182" xscale="1" yscale="1" highlightx="50" highlighty="375"></composite>
    </group>
</composites>

Note how the locations are the same. When cycling through the sub-pages in the composite group only one page is drawn at a time, so if they are not in the same location things will appear to jump around the screen.

If you want more than one composite group, add another with the next id:

<composites>
    <group id="0">
        <composite page="12" x="810" y="182" xscale="1" yscale="1" highlightx="50" highlighty="375"></composite>
        <composite page="13" x="810" y="182" xscale="1" yscale="1" highlightx="50" highlighty="375"></composite>
    </group>
    <group id="1">
        <composite page="14" x="100" y="100" xscale="1" yscale="1" highlightx="50" highlighty="375"></composite>
        <composite page="15" x="100" y="100" xscale="1" yscale="1" highlightx="50" highlighty="375"></composite>
    </group>
</composites>

Notice how the second composite group all have the same location of (100,100) but the pages are different to those in group zero. This will give you 2 separate sections on your parent page, each with 2 pages that can be cycled through. You do not have to have the same number of pages in each composite group. This is a scenario where you need to be able to jump between the composite groups with either a touch or hardware button input, as well as have a cycle current composite input, in order to be able to alter their content.

The currently displayed composite is currently always restored to the first one in the list of each group when the application is booted, so you should arrange your composites so that the one you use the most is first in the list. The page number does not matter; it’s just which one is first in each composite group.