Skip to content

Flexible background patterns

Jump to bottom
Martin Winter edited this page Mar 19, 2024 · 4 revisions

Note This Wiki page describes a proposed feature as implemented in PR https://github.com/OpenBoard-org/OpenBoard/pull/888. This is currently not available in the released versions of OpenBoard.

The Idea

Currently OpenBoard supports a limited and fixed set of background patters:

  • blank,
  • lined,
  • crossed,
  • Seyes (alternative to lined).

Additionally intermediate lines can be switched on for crossed and lined. The patterns can be applied to either a dark or light background.

There were requests to add more patterns. One of those requests resulted in the availability of a Seyes background as an alternative to the lined background pattern. But that pattern is a French specialty. Other use cases would like to have other patterns.

This resulted in the idea to implement flexible background patters, which are not implemented in code, but described in some pattern description file. Such files could easily be added without changing the OpenBoard code base. A generic painting algorithm then interprets these descriptions and creates the respective patterns.

Of course this would change the GUI. To avoid user confusion, the changes should be as minimal as possible.

User experience

For the user, the background palette now looks as follows:

grafik

In this example the Seyes background is selected. The set of available backgrounds is blank, lined, crossed 5mm, Seyes, stave lines and isometric grid. This is just one example. As we can see later, the user can now configure this palette and adapt it to their needs. To switch background color, a toggle is provided on the lower right.

This already extends the number of available backgrounds from 6 to 12.

The grid configuration tab in the property dialog now offers the following user interface:

grafik

Below the color configuration, all available patterns are presented. Below of each pattern, a short description is provided. If necessary, the pane can be scrolled. The first six patterns have a colored background. They are available in the background palette. The background patterns can be arranged as needed by dragging them to the required position:

grafik

Patterns are stored in the document pages. So if a user has designed a user specific pattern and created a document with this, they can pass this document to other users and they will see the same background. Such patterns are also automatically saved on the user's machine and are appended to the pattern list in the preferences, so that they can use it themselves in other documents. Such user defined patterns can later also be deleted by dragging them to a trash symbol appearing at the end of the list.

If somebody wants to distribute a new set of background patterns, they just have to create a document where these patterns are applied to the pages. When another user opens such a document, the patterns are automatically installed.

Background pattern design

Patterns are described in a small XML file. The complete syntax is specified using an XML schema. It is better explained with an example.

Stave lines with border

The stave lines with border are specified as follows:

<bg:background xmlns:bg="http://openboard.org/template/background/">
    <bg:uuid>1da51382-220e-40d2-804a-36ca2ab3fbd8</bg:uuid>
    <bg:description xml:lang="en">Stave lines with border</bg:description>
    <bg:description xml:lang="de">Notenlinien mit Rand</bg:description>
    <bg:description xml:lang="fr">Lignes de notes avec bordure</bg:description>
    <bg:linegroup>
        <bg:angle>0</bg:angle>
        <bg:spacing>50</bg:spacing>
        <bg:line>
            <bg:offset>0</bg:offset>
            <bg:width>1</bg:width>
        </bg:line>
        <bg:line>
            <bg:offset>5</bg:offset>
            <bg:width>1</bg:width>
        </bg:line>
        <bg:line>
            <bg:offset>10</bg:offset>
            <bg:width>1</bg:width>
        </bg:line>
        <bg:line>
            <bg:offset>15</bg:offset>
            <bg:width>1</bg:width>
        </bg:line>
        <bg:line>
            <bg:offset>20</bg:offset>
            <bg:width>1</bg:width>
        </bg:line>
        <bg:stretch>
            <bg:from>-5</bg:from>
            <bg:to>-5</bg:to>
            <bg:line>
                <bg:offset>0</bg:offset>
                <bg:width>1</bg:width>
            </bg:line>
        </bg:stretch>
        <bg:stack>
            <bg:from>0</bg:from>
            <bg:to>0</bg:to>
        </bg:stack>
    </bg:linegroup>
</bg:background>

Each pattern description has a UUID (line 2). It is followed by a descriptive text in one or several languages. We then have a linegroup element describing a group of lines. This group specifies an angle (0 = horizontally) and a spacing (distance between the group of lines). The spacing of 50 means that the specified group is repeated every 50mm. Within the group, we specify 5 lines with an offset of 0, 5, 10, 15 and 20. This are the five lines of one stave. After that, a stretch is specified. Here we have an indent on the left and the right of 5mm each from the nominal page border. We also specify a line within the stretch, which draws the lines connecting the 5 stave lines. The stack element specifies that the lines should not be stacked outside of the page boundary.

Isometric grid

Another example is the isometric grid:

<bg:background xmlns:bg="http://openboard.org/template/background/">
    <bg:uuid>07187386-b012-492c-b0a8-50faa18c28a0</bg:uuid>
    <bg:description xml:lang="en">Isometric</bg:description>
    <bg:description xml:lang="de">Isometrisches Gitter</bg:description>
    <bg:attributes crossed="true"/>
    <bg:linegroup>
        <bg:angle>30</bg:angle>
        <bg:spacing>10</bg:spacing>
        <bg:line>
            <bg:offset>0</bg:offset>
            <bg:width>1</bg:width>
        </bg:line>
    </bg:linegroup>
    <bg:linegroup>
        <bg:angle>90</bg:angle>
        <bg:spacing>10</bg:spacing>
        <bg:line>
            <bg:offset>0</bg:offset>
            <bg:width>1</bg:width>
        </bg:line>
    </bg:linegroup>
    <bg:linegroup>
        <bg:angle>150</bg:angle>
        <bg:spacing>10</bg:spacing>
        <bg:line>
            <bg:offset>0</bg:offset>
            <bg:width>1</bg:width>
        </bg:line>
    </bg:linegroup>
</bg:background>

Here we have three line groups with one line each. The angles are 30, 90 and 150 degrees and the spacing is 10mm.

Seyes

The Seyes background uses other features:

<bg:background xmlns:bg="http://openboard.org/template/background/">
    <bg:uuid>38b45f18-f6a5-4336-ae91-bedba3a2442c</bg:uuid>
    <bg:description xml:lang="en">Seyes</bg:description>
    <bg:attributes ruled="true"/>
    <bg:linegroup>
        <bg:angle>0</bg:angle>
        <bg:spacing>20</bg:spacing>
        <bg:line>
            <bg:offset>0</bg:offset>
            <bg:width>2</bg:width>
            <bg:color>
                <bg:onDark>#8e7cc3</bg:onDark>
                <bg:onLight>#8e7cc3</bg:onLight>
            </bg:color>
        </bg:line>
        <bg:line>
            <bg:offset>5</bg:offset>
            <bg:width>2</bg:width>
            <bg:color>
                <bg:onDark>#996fa8dc</bg:onDark>
                <bg:onLight>#996fa8dc</bg:onLight>
            </bg:color>
        </bg:line>
        <bg:line>
            <bg:offset>10</bg:offset>
            <bg:width>2</bg:width>
            <bg:color>
                <bg:onDark>#996fa8dc</bg:onDark>
                <bg:onLight>#996fa8dc</bg:onLight>
            </bg:color>
        </bg:line>
        <bg:line>
            <bg:offset>15</bg:offset>
            <bg:width>2</bg:width>
            <bg:color>
                <bg:onDark>#996fa8dc</bg:onDark>
                <bg:onLight>#996fa8dc</bg:onLight>
            </bg:color>
        </bg:line>
        <bg:stretch>
            <bg:from>50</bg:from>
            <bg:to>0</bg:to>
        </bg:stretch>
        <bg:stack>
            <bg:from>0</bg:from>
            <bg:to>0</bg:to>
        </bg:stack>
    </bg:linegroup>
    <bg:linegroup>
        <bg:angle>90</bg:angle>
        <bg:spacing>20</bg:spacing>
        <bg:origin>topleft</bg:origin>
        <bg:line>
            <bg:offset>0</bg:offset>
            <bg:width>2</bg:width>
            <bg:color>
                <bg:onDark>#8e7cc3</bg:onDark>
                <bg:onLight>#8e7cc3</bg:onLight>
            </bg:color>
        </bg:line>
        <bg:stretch>
            <bg:from>0</bg:from>
            <bg:to>50</bg:to>
        </bg:stretch>
        <bg:stack>
            <bg:from>0</bg:from>
            <bg:to>0</bg:to>
        </bg:stack>
    </bg:linegroup>
    <bg:linegroup>
        <bg:angle>90</bg:angle>
        <bg:origin>topleft</bg:origin>
        <bg:line>
            <bg:offset>0</bg:offset>
            <bg:width>2</bg:width>
            <bg:color>
                <bg:onDark>#ff0000</bg:onDark>
                <bg:onLight>#ff0000</bg:onLight>
            </bg:color>
        </bg:line>
        <bg:stretch>
            <bg:from>0</bg:from>
            <bg:to>50</bg:to>
        </bg:stretch>
    </bg:linegroup>
</bg:background>

The first line group describes the horizontal lines. Here each line has a specified color, independent of the color configured in the preferences. Note that each color can have the format #aarrggbb, where aa is the alpha value of the color. We also specify a stretch with this line group so that the lines do not stretch endless to the right and left, but we define a start 50mm before the left page border and end at the right page border.

The second line group is for the vertical lines. The offset shall be computed from the left page border, so we specify an origin of topleft here. Origins must always be a corner. Again stretch and stack is used to limit the extend of the lines.

Finally we have a line group without spacing. This group is therefore not repeated and draws a single vertical red line in the specified distance to the origin.

These pattern files are all that is needed to describe a background pattern. The button images are automatically created using the pattern, so there is no need to design these icons. Remember to assign a unique UUID to each pattern, as this is used internally to distinguish them. You should also check the syntax of a newly created file using the XML schema. You may use the tool linked at the top of the schema file.

Compatibility with previous document versions

To cope with the variety of background patters we now save the pattern description with each document page. Previous versions just used a set of attributes to describe lined and crossed backgrounds and intermediate grid lines.

To provide some compatibility, we can include these attributes also with a pattern description:

<bg:background xmlns:bg="http://openboard.org/template/background/">
    <bg:uuid>8ed2037b-ab38-4d4f-9b52-c4e36b1c8102</bg:uuid>
    <bg:description xml:lang="en">Crossed 5mm</bg:description>
    <bg:description xml:lang="de">Kariert 5mm</bg:description>
    <bg:attributes crossed="true" intermediateLines="true"/>

This is the beginning of the pattern description for a crossed background with intermediate lines. The attributes tag specifies the flags used for compatibility:

  • When loading a document page without embedded pattern, the flags are taken from the document. The available patters are searched for a pattern with matching flags.
  • When saving a document, the flags are written as specified in the pattern file. If we're using e.g. the pattern file shown above, previous versions of OpenBoard can interpret these flags.

Of course documents using background patterns not available in previous versions of OpenBoard will just receive a blank background. When they are saved again, the pattern information is lost. There are also compatibility issues with Seyes background: as this is a property not stored in the document but in the user preferences file, OpenBoard cannot distinguish between lines and Seyes just by reading the document.

Clone this wiki locally