Skip to content

Menu appearance

Jump to bottom
Alexander Spiridonov edited this page Dec 28, 2023 · 20 revisions

Appearance of the menu can be customized by adjusting options, that can be passed to GEM (GEM_u8g2, GEM_adafruit_gfx) constructor individually or as a part of GEMAppearance object.

AltSerialGraphicLCD version:

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

U8g2 version:

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

Adafruit GFX version:

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

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.

  • appearance [optional]
    Type: GEMAppearance
    Object of type GEMAppearance that holds values of appearance settings that define how menu is rendered on screen. Essentially allows to pass appearance as a single object instead of specifying each option as a aseparate argument.

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.

Note: it is possible to customize appearance of each menu page individually (since GEM ver. 1.5) by using GEMAppearance object.

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);

GEMAppearance

Data structure that holds values of appearance settings that define how menu is rendered on screen. Can be submitted to GEM (GEM_u8g2, GEM_adafruit_gfx) constructor instead of specifying each option as a separate argument, or passed as an argument to GEM::setAppearance() (GEM_u8g2::setAppearance(), GEM_adafruit_gfx::setAppearance()) method to set general appearance of the menu (that will be used for every menu page if not overridden). Pointer to object of type GEMAppearance can be passed to GEMPage::setAppearance() method to customize appearance of corresponding menu page individually.

Object of type GEMAppearance defines as follows:

GEMAppearance appearanceGeneral = {menuPointerType, menuItemsPerScreen, menuItemHeight, menuPageScreenTopOffset, menuValuesLeftOffset}

Basic example of use:

// Create GEMAppearance object with general values (that will be used for every menu page if not overridden)
GEMAppearance appearanceGeneral = {/* menuPointerType= */ GEM_POINTER_ROW, /* menuItemsPerScreen= */ GEM_ITEMS_COUNT_AUTO, /* menuItemHeight= */ 10, /* menuPageScreenTopOffset= */ 10, /* menuValuesLeftOffset= */ 86}
// Create GEMAppearance object as a copy of appearanceGeneral (its values can be customized later in sketch).
// Note that it should be created in a global scope of the sketch (in order to be passed as a pointer to menu page)
GEMAppearance appearanceSettings = appearanceGeneral;

// Create menu object (and pass appearanceGeneral as an argument to constructor)
GEM menu(glcd, appearanceGeneral);

...

// Later in sketch, e.g. in setupMenu()
void setupMenu() {
  ...
  appearanceSettings.menuValuesLeftOffset = 70;
  menuPageSettings.setAppearance(&appearanceSettings); // Note `&` operator
  ...
}

Alternatively:

// Create empty GEMAppearance object (its values can be populated later in sketch).
// Note that it should be created in a global scope of the sketch (in order to be passed as a pointer to menu page)
GEMAppearance appearanceSettings;

// Create menu object (its appearance settings will be populated with default values)
GEM menu(glcd);

...

// Later in sketch, e.g. in setupMenu()
void setupMenu() {
  ...
  // Create GEMAppearance object with general values (that will be used for every menu page if not overridden)
  GEMAppearance appearanceGeneral;
  appearanceGeneral.menuPointerType = GEM_POINTER_ROW;
  appearanceGeneral.menuItemsPerScreen = GEM_ITEMS_COUNT_AUTO;
  appearanceGeneral.menuItemHeight = 10;
  appearanceGeneral.menuPageScreenTopOffset = 10;
  appearanceGeneral.menuValuesLeftOffset = 86;

  // Set appearanceGeneral as a general appearance of the menu
  menu.setAppearance(appearanceGeneral); // Note there is no `&` operator when setting general (or global) appearance of the menu

  // Copy values from appearanceGeneral object to appearanceSettings for further customization
  appearanceSettings = appearanceGeneral;
  appearanceSettings.menuValuesLeftOffset = 70;
  menuPageSettings.setAppearance(&appearanceSettings); // Note `&` operator
  ...
}

Passing GEMAppearance object to GEMPage::setAppearance() method as a pointer allows to change appearance of the individual menu page dynamically by changing values stored in object (and making sure that menu.drawMenu(); is called afterwards) without need for additional call to GEMPage::setAppearance(). In contrast, to change general appearance of the menu (and not individual page) menu.setAppearance(appearanceGeneral); method should be called with new or updated GEMAppearance object supplied as an argument (and menu.drawMenu(); should be called afterwards as well).

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);

General

Customization

Examples

Clone this wiki locally