Margins

The margins allow to resize the screen by a number of pixels on each side of the screen.

If the initial size of the screen is screenSizeX() by screenSizeY() and margins are set to marginX and marginY, the final size is screenSizeX() - 2 * marginX by screenSizeY() - 2 * marginY.

Axis	Initial	Margins	Final
X	screenSizeX()	marginX	screenSizeX() - 2 * marginX
Y	screenSizeY()	marginY	screenSizeY() - 2 * marginY

On the example pictured above, the initial size of the screen is 416 x 240 and the margins are 40 x 20; the final size is 352 x 208.

The origin of the final screen (0, 0) corresponds to the coordinates (marginX, marginY) on the initial screen.

The margins are especially helpful when the screen is used for an interface. If the screen is under a cover with thick edges, the margins reduce the size of the active area so the finger can touch the elements. When using a grid to place the GUI elements, the margins centre the active area gracefully.

Configure

No configuration is required.

Use

myScreen.setOrientation(ORIENTATION_LANDSCAPE);
myScreen.setMarginXY(32, 16);
uint16_t marginX = myScreen.screenMarginX();
uint16_t marginX = myScreen.screenMarginY();

setMarginXY() sets the size of the margins to the number of pixels, with 0 as default value, on the x- and y-axis.

screenMarginX() and screenMarginY() return the size of the margins in pixels on the x- and y-axis.

To clear the margin, call setMarginXY(0, 0).

Note

As margins modify the size of the screen, they impact screenSizeX() and screenSizeY().

Note

The margins are related to the orientation of the screen.

Example

This is the core of the code from example Margin.ino.

void displayMargin()
{
    myScreen.setOrientation(ORIENTATION_LANDSCAPE);

    myScreen.selectFont(fontMedium);
    uint8_t dz = myScreen.characterSizeY();

    char text[64] = {0};
    strcat(text, formatString("%s %ix%i", "Initial=", myScreen.screenSizeX(), myScreen.screenSizeY()));

    myScreen.setPenSolid(true);
    myScreen.dRectangle(0, 0, myScreen.screenSizeX(), myScreen.screenSizeY(), myColours.black);
    myScreen.gText(0, 0, formatString("Margin= %ix%i", dz * 2, dz), myColours.white);

    myScreen.setMarginXY(dz * 2, dz);
    myScreen.setPenSolid(true);
    myScreen.dRectangle(0, 0, myScreen.screenSizeX(), myScreen.screenSizeY(), myColours.white);

    myScreen.gText(0 + 2, dz * 0, myScreen.WhoAmI());
    myScreen.gText(0 + 2, dz * 1, text);
    myScreen.gText(0 + 2, dz * 2, formatString("Margin= %ix%i", myScreen.screenMarginX(), myScreen.screenMarginY()));
    myScreen.gText(0 + 2, dz * 3, formatString("%s %ix%i", "Final=", myScreen.screenSizeX(), myScreen.screenSizeY()));

    myScreen.flushFast();
    myScreen.setPenSolid(false);
    myScreen.setMarginXY();

    hV_HAL_Serial_crlf();
    hV_HAL_log(LEVEL_DEBUG, myScreen.WhoAmI());
    hV_HAL_log(LEVEL_DEBUG, text);
    hV_HAL_log(LEVEL_DEBUG, "Margin= %ix%i", myScreen.screenMarginX(), myScreen.screenMarginY());
    hV_HAL_log(LEVEL_DEBUG, "%s %ix%i", "Final=", myScreen.screenSizeX(), myScreen.screenSizeY());
}