Skip to content

Menu appearance

Alexander Spiridonov edited this page Dec 5, 2023 · 20 revisions

Appearance of the menu can be customized by adjusting options passed to GEM constructor.

AltSerialGraphicLCD version:

GEM menu(glcd[, menuPointerType[, menuItemsPerScreen[, menuItemHeight[, menuPageScreenTopOffset[, menuValuesLeftOffset]]]]]);

U8g2 version:

GEM_u8g2 menu(u8g2[, menuPointerType[, menuItemsPerScreen[, menuItemHeight[, menuPageScreenTopOffset[, menuValuesLeftOffset]]]]]);

Adafruit GFX version:

GEM_adafruit_gfx menu(tft[, menuPointerType[, menuItemsPerScreen[, menuItemHeight[, menuPageScreenTopOffset[, menuValuesLeftOffset]]]]]);

Options

  • menuPointerType [optional]
    Type: byte
    Values: GEM_POINTER_ROW, GEM_POINTER_DASH
    Default: GEM_POINTER_ROW
    Type of menu pointer visual appearance: either highlighted row or pointer to the left of the row.

  • menuItemsPerScreen [optional]
    Type: byte
    Values: number, GEM_ITEMS_COUNT_AUTO (alias for 0)
    Default: 5
    Count of the menu items per screen. Suitable for 128x64 screen with other variables at their default values. If set to GEM_ITEMS_COUNT_AUTO (available since GEM ver. 1.3), the number of menu items will be determined automatically based on actual height of the screen.

  • menuItemHeight [optional]
    Type: byte
    Units: dots
    Default: 10
    Height of the menu item. Suitable for 128x64 screen with other variables at their default values.

  • menuPageScreenTopOffset [optional]
    Type: byte
    Units: dots
    Default: 10
    Offset from the top of the screen to accommodate title of the menu page. Suitable for 128x64 screen with other variables at their default values.

  • menuValuesLeftOffset [optional]
    Type: byte
    Units: dots
    Default: 86
    Offset from the left of the screen to the value of the associated with menu item variable (effectively the space left for the title of the menu item to be printed on screen). Suitable for 128x64 screen with other variables at their default values; 86 - recommended value for 128x64 screen.

Calls to GEM, GEM_u8g2 or GEM_adafruit_gfx constructors GEM(glcd), GEM_u8g2(u8g2), GEM_adafruit_gfx(tft) without specifying additional custom parameters are equivalent to the following calls:

GEM menu(glcd, /* menuPointerType= */ GEM_POINTER_ROW, /* menuItemsPerScreen= */ 5, /* menuItemHeight= */ 10, /* menuPageScreenTopOffset= */ 10, /* menuValuesLeftOffset= */ 86);
GEM_u8g2 menu(u8g2, /* menuPointerType= */ GEM_POINTER_ROW, /* menuItemsPerScreen= */ 5, /* menuItemHeight= */ 10, /* menuPageScreenTopOffset= */ 10, /* menuValuesLeftOffset= */ 86);
GEM_adafruit_gfx menu(tft, /* menuPointerType= */ GEM_POINTER_ROW, /* menuItemsPerScreen= */ 5, /* menuItemHeight= */ 10, /* menuPageScreenTopOffset= */ 10, /* menuValuesLeftOffset= */ 86);

Note: carefully choose values of menuItemsPerScreen, menuItemHeight, menuPageScreenTopOffset, menuValuesLeftOffset in accordance to the actual size of your display. Default values of these options are suitable for 128x64 screens. But that is not the only possible option: the other combination of values you set may also be suitable - just calculate them correctly and see what works best for you.

Note: long title of the menu page GEMPage won't overflow to the new line in U8g2 version and will be truncated at the edge of the screen.

Examples

GEM menu(glcd);

Equivalent to:

GEM menu(glcd, /* menuPointerType= */ GEM_POINTER_ROW, /* menuItemsPerScreen= */ 5, /* menuItemHeight= */ 10, /* menuPageScreenTopOffset= */ 10, /* menuValuesLeftOffset= */ 86);

GEM menu(glcd, /* menuPointerType= */ GEM_POINTER_ROW, /* menuItemsPerScreen= */ 5, /* menuItemHeight= */ 10, /* menuPageScreenTopOffset= */ 10, /* menuValuesLeftOffset= */ 80);

GEM menu(glcd, /* menuPointerType= */ GEM_POINTER_DASH, /* menuItemsPerScreen= */ 5, /* menuItemHeight= */ 10, /* menuPageScreenTopOffset= */ 10, /* menuValuesLeftOffset= */ 80);

GEM menu(glcd, /* menuPointerType= */ GEM_POINTER_ROW, /* menuItemsPerScreen= */ 4, /* menuItemHeight= */ 10, /* menuPageScreenTopOffset= */ 16, /* menuValuesLeftOffset= */ 80);

Note: screenshot of the AltSerialGraphicLCD version is shown, long title of the menu page won't overflow to the new line in U8g2 version and will be truncated at the edge of the screen.


GEM menu(glcd, /* menuPointerType= */ GEM_POINTER_ROW, /* menuItemsPerScreen= */ 4, /* menuItemHeight= */ 14, /* menuPageScreenTopOffset= */ 8, /* menuValuesLeftOffset= */ 80);

GEM menu(glcd, /* menuPointerType= */ GEM_POINTER_ROW, /* menuItemsPerScreen= */ 7, /* menuItemHeight= */ 8, /* menuPageScreenTopOffset= */ 8, /* menuValuesLeftOffset= */ 80);

GEM menu(glcd, /* menuPointerType= */ GEM_POINTER_ROW, /* menuItemsPerScreen= */ 9, /* menuItemHeight= */ 6, /* menuPageScreenTopOffset= */ 10, /* menuValuesLeftOffset= */ 80);

GEM menu(glcd, /* menuPointerType= */ GEM_POINTER_DASH, /* menuItemsPerScreen= */ 9, /* menuItemHeight= */ 6, /* menuPageScreenTopOffset= */ 10, /* menuValuesLeftOffset= */ 80);

Changing text magnification (Adafruit GFX version only)

In Adafruit GFX version of GEM it is possible to change text 'magnification' size (as it is called in Adafruit GFX documentation), i.e. scale factor of the text printed on screen (and sprites of the various menu icons, although they can be scaled up to 2 times maximum):

menu.setTextSize(2);
// or
menu.setTextSize(3);

Default scale factor (magnification size) is 1. Should be called before init().

Note: supplied scale factor (magnification size) has no effect on values supplied to GEM_adafruit_gfx constructor, so choose them carefully to be the most suitable for desired text size.

Changing color (Adafruit GFX version only)

In Adafruit GFX version of GEM it is possible to change text (foreground) and background colors of the color-capable display:

menu.setForegroundColor(0x0000);
menu.setBackgroundColor(0xFFFF);

Both methods accept color in a 16-bit RGB representation. Adafruit GFX aliases, e.g. ST77XX_WHITE, ST77XX_BLACK, ST77XX_RED, etc. are supported. See Adafruit GFX documentation for detailed description of a format:

For color-capable displays, colors are represented as unsigned 16-bit values. Some displays may physically be capable of more or fewer bits than this, but the library operates with 16-bit values... these are easy for the Arduino to work with while also providing a consistent data type across all the different displays. The primary color components — red, green and blue — are all “packed” into a single 16-bit variable, with the most significant 5 bits conveying red, middle 6 bits conveying green, and least significant 5 bits conveying blue.

Color change will take effect next time menu is drawn. Default values: foreground color 0xFFFF (white), background color 0x0000 (black).

Note that it is possible that some displays may have "inverted" color representation (when R, G, B components come in different order, e.g. B, G, R). If that is the case, try initializing display with different "tab" argument passed to tft.initR() function, e.g. tft.initR(INITR_BLACKTAB), or tft.initR(INITR_GREENTAB), etc. Or just reformat your 16-bit number accordingly.

Examples

menu.setForegroundColor(ST77XX_WHITE);
menu.setBackgroundColor(ST77XX_BLACK);
// or
menu.setForegroundColor(0xFFFF);
menu.setBackgroundColor(0x0000);

menu.setForegroundColor(ST77XX_BLACK);
menu.setBackgroundColor(ST77XX_WHITE);
// or
menu.setForegroundColor(0x0000);
menu.setBackgroundColor(0xFFFF);

menu.setForegroundColor(ST77XX_GREEN);
menu.setBackgroundColor(ST77XX_BLACK);
// or
menu.setForegroundColor(0x07E0);
menu.setBackgroundColor(0x0000);

menu.setForegroundColor(ST77XX_ORANGE);
menu.setBackgroundColor(ST77XX_BLACK);
// or
menu.setForegroundColor(0xFC00);
menu.setBackgroundColor(0x0000);

menu.setForegroundColor(ST77XX_WHITE);
menu.setBackgroundColor(ST77XX_BLUE);
// or
menu.setForegroundColor(0xFFFF);
menu.setBackgroundColor(0x001F);