nbgl_layout.h

Go to the documentation of this file.

 
#ifndef NBGL_LAYOUT_H
#define NBGL_LAYOUT_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include "nbgl_obj.h"
#include "nbgl_screen.h"
#include "nbgl_types.h"
#include "nbgl_content.h"
#ifdef HAVE_PIEZO_SOUND
#include "os_io_seproxyhal.h"
#endif
 
/*********************
 *      INCLUDES
 *********************/
 
/*********************
 *      DEFINES
 *********************/
#define NBGL_NO_TUNE               NB_TUNES
#define NBGL_NO_PROGRESS_INDICATOR 0xFF
 
#define NBGL_INVALID_TOKEN 0xFF
 
#ifdef HAVE_SE_TOUCH
#define EXIT_PAGE 0xFF
 
#ifdef TARGET_STAX
#define NB_MAX_SUGGESTION_BUTTONS         12
// only 4 buttons are visible at the same time on Stax
#define NB_MAX_VISIBLE_SUGGESTION_BUTTONS 4
#define TOUCHABLE_HEADER_BAR_HEIGHT       88
#define TOUCHABLE_MAIN_BAR_HEIGHT         96
#define TOUCHABLE_BAR_HEIGHT              96
#define SMALL_FOOTER_HEIGHT               88
#define SIMPLE_FOOTER_HEIGHT              92
#define SMALL_CENTERING_HEADER            32
#define MEDIUM_CENTERING_HEADER           56
#define LONG_PRESS_BUTTON_HEIGHT          128
#else  // TARGET_STAX
#define NB_MAX_SUGGESTION_BUTTONS         8
// only 2 buttons are visible at the same time on Flex
#define NB_MAX_VISIBLE_SUGGESTION_BUTTONS 2
#define TOUCHABLE_HEADER_BAR_HEIGHT       96
#define TOUCHABLE_MAIN_BAR_HEIGHT         100
#define TOUCHABLE_BAR_HEIGHT              92
#define SMALL_FOOTER_HEIGHT               96
#define SIMPLE_FOOTER_HEIGHT              96
#define SMALL_CENTERING_HEADER            40
#define MEDIUM_CENTERING_HEADER           64
#define LONG_PRESS_BUTTON_HEIGHT          152
#endif  // TARGET_STAX
 
#define AVAILABLE_WIDTH (SCREEN_WIDTH - 2 * BORDER_MARGIN)
 
#define NB_MAX_LINES NB_MAX_LINES_IN_DETAILS
 
#ifdef TARGET_STAX
#define PRE_TEXT_MARGIN     32
#define TEXT_SUBTEXT_MARGIN 16
#define POST_SUBTEXT_MARGIN 28
#else  // TARGET_STAX
#define PRE_TEXT_MARGIN     28
#define TEXT_SUBTEXT_MARGIN 14
#define POST_SUBTEXT_MARGIN 26
#endif  // TARGET_STAX
 
#else  // HAVE_SE_TOUCH
// 7 pixels on each side
#define AVAILABLE_WIDTH (SCREEN_WIDTH - 2 * 7)
// maximum number of lines in screen
#define NB_MAX_LINES    4
 
#endif  // HAVE_SE_TOUCH
 
/**********************
 *      TYPEDEFS
 **********************/
 
typedef void *nbgl_layout_t;
 
typedef void (*nbgl_layoutTouchCallback_t)(int token, uint8_t index);
 
typedef void (*nbgl_layoutButtonCallback_t)(nbgl_layout_t *layout, nbgl_buttonEvent_t event);
 
typedef struct {
    uint8_t token;               
    uint8_t nbPages;             
    uint8_t activePage;          
    bool    withExitKey;         
    bool    withBackKey;         
    bool    withSeparationLine;  
    bool withPageIndicator;  
    bool visibleIndicator;   
#ifdef HAVE_PIEZO_SOUND
    tune_index_e tuneId;  
#endif                    // HAVE_PIEZO_SOUND
} nbgl_layoutNavigationBar_t;
 
typedef enum {
    HORIZONTAL_NAV,  
    VERTICAL_NAV     
} nbgl_layoutNavDirection_t;
 
typedef enum {
    NO_ARROWS = 0,
    LEFT_ARROW,   
    RIGHT_ARROW,  
} nbgl_layoutNavIndication_t;
 
typedef struct {
    nbgl_layoutNavDirection_t  direction;   
    nbgl_layoutNavIndication_t indication;  
} nbgl_layoutNavigation_t;
 
typedef struct nbgl_layoutDescription_s {
    bool modal;  
#ifdef HAVE_SE_TOUCH
    bool withLeftBorder;  
    const char *tapActionText;  
    uint8_t tapActionToken;     
#ifdef HAVE_PIEZO_SOUND
    tune_index_e tapTuneId;  
#endif                       // HAVE_PIEZO_SOUND
    nbgl_layoutTouchCallback_t
        onActionCallback;  
#else                      // HAVE_SE_TOUCH
    nbgl_layoutButtonCallback_t
            onActionCallback;  
#endif                     // HAVE_SE_TOUCH
    nbgl_screenTickerConfiguration_t ticker;  // configuration of ticker (timeout)
} nbgl_layoutDescription_t;
 
typedef struct {
    const nbgl_icon_details_t
               *iconLeft;  
    const char *text;      
    const nbgl_icon_details_t *iconRight;  
    const char *subText;                   
    bool        large;                     
    uint8_t     token;     
    bool        inactive;  
    bool        centered;  
#ifdef HAVE_PIEZO_SOUND
    tune_index_e tuneId;  
#endif                    // HAVE_PIEZO_SOUND
} nbgl_layoutBar_t;
 
typedef nbgl_contentSwitch_t nbgl_layoutSwitch_t;
 
typedef nbgl_contentRadioChoice_t nbgl_layoutRadioChoice_t;
 
typedef const char *(*nbgl_menuListCallback_t)(uint8_t choiceIndex);
 
typedef struct {
    nbgl_menuListCallback_t callback;        
    uint8_t                 nbChoices;       
    uint8_t                 selectedChoice;  
 
} nbgl_layoutMenuList_t;
 
typedef nbgl_contentTagValue_t nbgl_layoutTagValue_t;
 
typedef nbgl_contentTagValueList_t nbgl_layoutTagValueList_t;
 
typedef nbgl_contentCenteredInfo_t nbgl_layoutCenteredInfo_t;
 
#ifdef HAVE_SE_TOUCH
 
typedef struct {
    const char *url;         
    const char *text1;       
    const char *text2;       
    int16_t     offsetY;     
    bool        centered;    
    bool        largeText1;  
} nbgl_layoutQRCode_t;
 
typedef enum {
    ROUNDED_AND_FOOTER_STYLE = 0,    
    STRONG_ACTION_AND_FOOTER_STYLE,  
    SOFT_ACTION_AND_FOOTER_STYLE     
} nbgl_layoutChoiceButtonsStyle_t;
 
// for backward compatibility
#define BOTH_ROUNDED_STYLE SOFT_ACTION_AND_FOOTER_STYLE
 
typedef struct {
    const char                *topText;     
    const char                *bottomText;  
    const nbgl_icon_details_t *topIcon;     
    uint8_t                    token;  
    nbgl_layoutChoiceButtonsStyle_t style;  
#ifdef HAVE_PIEZO_SOUND
    tune_index_e tuneId;  
#endif                    // HAVE_PIEZO_SOUND
} nbgl_layoutChoiceButtons_t;
 
typedef struct {
    const nbgl_icon_details_t *leftIcon;    
    const char                *rightText;   
    uint8_t                    leftToken;   
    uint8_t                    rightToken;  
#ifdef HAVE_PIEZO_SOUND
    tune_index_e tuneId;  
#endif                    // HAVE_PIEZO_SOUND
} nbgl_layoutHorizontalButtons_t;
 
typedef enum {
    BLACK_BACKGROUND
        = 0,           
    WHITE_BACKGROUND,  
    NO_BORDER,         
    LONG_PRESS         
} nbgl_layoutButtonStyle_t;
 
typedef struct {
    const char                *text;   
    const nbgl_icon_details_t *icon;   
    uint8_t                    token;  
    nbgl_layoutButtonStyle_t   style;
    bool fittingContent;  
    bool onBottom;        
#ifdef HAVE_PIEZO_SOUND
    tune_index_e tuneId;  
#endif                    // HAVE_PIEZO_SOUND
} nbgl_layoutButton_t;
 
typedef enum {
    KEYBOARD_WITH_SUGGESTIONS,  
    KEYBOARD_WITH_BUTTON,       
    NB_KEYBOARD_CONTENT_TYPES
} nbgl_layoutKeyboardContentType_t;
 
typedef struct {
    const char **buttons;  
    int firstButtonToken;  
    uint8_t nbUsedButtons;  
} nbgl_layoutSuggestionButtons_t;
 
typedef struct {
    const char *text;    
    int         token;   
    bool        active;  
} nbgl_layoutConfirmationButton_t;
 
typedef struct {
    nbgl_layoutKeyboardContentType_t type;   
    const char                      *title;  
    const char                      *text;   
    bool    numbered;   
    uint8_t number;     
    bool    grayedOut;  
    int     textToken;  
    union {
        nbgl_layoutSuggestionButtons_t
            suggestionButtons;  
        nbgl_layoutConfirmationButton_t
            confirmationButton;  
    };
#ifdef HAVE_PIEZO_SOUND
    tune_index_e tuneId;  
#endif                    // HAVE_PIEZO_SOUND
} nbgl_layoutKeyboardContent_t;
 
typedef enum {
    HEADER_EMPTY = 0,      
    HEADER_BACK_AND_TEXT,  
    HEADER_BACK_AND_PROGRESS,  
    HEADER_TITLE,              
    HEADER_EXTENDED_BACK,      
    HEADER_RIGHT_TEXT,         
    NB_HEADER_TYPES
} nbgl_layoutHeaderType_t;
 
typedef struct {
    nbgl_layoutHeaderType_t type;  
    bool separationLine;  
    union {
        struct {
            uint16_t height;
        } emptySpace;  
        struct {
            const char  *text;    
            uint8_t      token;   
            tune_index_e tuneId;  
        } backAndText;            
        struct {
            const nbgl_icon_details_t *actionIcon;  
            uint8_t                    activePage;
            uint8_t                    nbPages;
            bool                       withBack;
            uint8_t                    token;        
            uint8_t                    actionToken;  
            tune_index_e               tuneId;       
        } progressAndBack;                           
        struct {
            const char *text;
        } title;  
        struct {
            const nbgl_icon_details_t *actionIcon;   
            const char                *text;         
            uint8_t                    textToken;    
            uint8_t                    backToken;    
            uint8_t                    actionToken;  
            tune_index_e               tuneId;       
        } extendedBack;                              
        struct {
            const char  *text;    
            uint8_t      token;   
            tune_index_e tuneId;  
        } rightText;              
    };
} nbgl_layoutHeader_t;
 
typedef enum {
    FOOTER_EMPTY = 0,    
    FOOTER_SIMPLE_TEXT,  
    FOOTER_DOUBLE_TEXT,  
    FOOTER_TEXT_AND_NAV,   
    FOOTER_NAV,            
    FOOTER_SIMPLE_BUTTON,  
    FOOTER_CHOICE_BUTTONS,  
    NB_FOOTER_TYPES
} nbgl_layoutFooterType_t;
 
typedef struct {
    nbgl_layoutFooterType_t type;  
    bool separationLine;  
    union {
        struct {
            uint16_t height;
        } emptySpace;  
        struct {
            const char  *text;
            bool         mutedOut;  
            uint8_t      token;
            tune_index_e tuneId;
        } simpleText;  
        struct {
            const char  *leftText;
            const char  *rightText;
            uint8_t      leftToken;
            uint8_t      rightToken;
            tune_index_e tuneId;
        } doubleText;  
        struct {
            nbgl_layoutNavigationBar_t navigation;
            const char                *text;
            uint8_t                    token;
            tune_index_e               tuneId;
        } textAndNav;                              
        nbgl_layoutNavigationBar_t navigation;     
        nbgl_layoutButton_t        button;         
        nbgl_layoutChoiceButtons_t choiceButtons;  
    };
} nbgl_layoutFooter_t;
 
typedef enum {
    UP_FOOTER_LONG_PRESS = 0,      
    UP_FOOTER_BUTTON,              
    UP_FOOTER_HORIZONTAL_BUTTONS,  
    UP_FOOTER_TIP_BOX,             
    UP_FOOTER_TEXT,                
    NB_UP_FOOTER_TYPES
} nbgl_layoutUpFooterType_t;
 
typedef struct {
    nbgl_layoutUpFooterType_t type;  
    union {
        struct {
            const char  *text;       
            uint8_t      token;      
            tune_index_e tuneId;     
        } longPress;                 
        nbgl_layoutButton_t button;  
        nbgl_layoutHorizontalButtons_t
                             horizontalButtons;  
        nbgl_contentTipBox_t tipBox;             
        struct {
            const char  *text;    
            uint8_t      token;   
            tune_index_e tuneId;  
        } text;                   
    };
} nbgl_layoutUpFooter_t;
#endif  // HAVE_SE_TOUCH
 
typedef struct {
    uint8_t     percentage;  
    const char *text;        
    const char *subText;     
} nbgl_layoutProgressBar_t;
 
typedef struct {
    uint32_t keyMask;  
    keyboardCallback_t callback;     
    bool               lettersOnly;  
    keyboardMode_t     mode;         
#ifdef HAVE_SE_TOUCH
    keyboardCase_t casing;  
#else                       // HAVE_SE_TOUCH
    bool    enableBackspace;   
    bool    enableValidate;    
    uint8_t selectedCharIndex;
#endif                      // HAVE_SE_TOUCH
} nbgl_layoutKbd_t;
 
/**********************
 * GLOBAL PROTOTYPES
 **********************/
nbgl_layout_t *nbgl_layoutGet(const nbgl_layoutDescription_t *description);
int nbgl_layoutAddCenteredInfo(nbgl_layout_t *layout, const nbgl_layoutCenteredInfo_t *info);
int nbgl_layoutAddContentCenter(nbgl_layout_t *layout, const nbgl_contentCenter_t *info);
int nbgl_layoutAddProgressBar(nbgl_layout_t *layout, const nbgl_layoutProgressBar_t *barLayout);
 
#ifdef HAVE_SE_TOUCH
int nbgl_layoutAddTopRightButton(nbgl_layout_t             *layout,
                                 const nbgl_icon_details_t *icon,
                                 uint8_t                    token,
                                 tune_index_e               tuneId);
int nbgl_layoutAddTouchableBar(nbgl_layout_t *layout, const nbgl_layoutBar_t *barLayout);
int nbgl_layoutAddSwitch(nbgl_layout_t *layout, const nbgl_layoutSwitch_t *switchLayout);
int nbgl_layoutAddText(nbgl_layout_t *layout, const char *text, const char *subText);
int nbgl_layoutAddTextWithAlias(nbgl_layout_t *layout,
                                const char    *text,
                                const char    *subText,
                                uint8_t        token,
                                uint8_t        index);
int nbgl_layoutAddSubHeaderText(nbgl_layout_t *layout, const char *text);
int nbgl_layoutAddRadioChoice(nbgl_layout_t *layout, const nbgl_layoutRadioChoice_t *choices);
int nbgl_layoutAddQRCode(nbgl_layout_t *layout, const nbgl_layoutQRCode_t *info);
int nbgl_layoutAddChoiceButtons(nbgl_layout_t *layout, const nbgl_layoutChoiceButtons_t *info);
int nbgl_layoutAddHorizontalButtons(nbgl_layout_t                        *layout,
                                    const nbgl_layoutHorizontalButtons_t *info);
int nbgl_layoutAddTagValueList(nbgl_layout_t *layout, const nbgl_layoutTagValueList_t *list);
int nbgl_layoutAddLargeCaseText(nbgl_layout_t *layout, const char *text);
int nbgl_layoutAddTextContent(nbgl_layout_t *layout,
                              const char    *title,
                              const char    *description,
                              const char    *info);
int nbgl_layoutAddSeparationLine(nbgl_layout_t *layout);
 
int nbgl_layoutAddButton(nbgl_layout_t *layout, const nbgl_layoutButton_t *buttonInfo);
int nbgl_layoutAddLongPressButton(nbgl_layout_t *layout,
                                  const char    *text,
                                  uint8_t        token,
                                  tune_index_e   tuneId);
int nbgl_layoutAddFooter(nbgl_layout_t *layout,
                         const char    *text,
                         uint8_t        token,
                         tune_index_e   tuneId);
int nbgl_layoutAddSplitFooter(nbgl_layout_t *layout,
                              const char    *leftText,
                              uint8_t        leftToken,
                              const char    *rightText,
                              uint8_t        rightToken,
                              tune_index_e   tuneId);
int nbgl_layoutAddHeader(nbgl_layout_t *layout, const nbgl_layoutHeader_t *headerDesc);
int nbgl_layoutAddExtendedFooter(nbgl_layout_t *layout, const nbgl_layoutFooter_t *footerDesc);
int nbgl_layoutAddUpFooter(nbgl_layout_t *layout, const nbgl_layoutUpFooter_t *upFooterDesc);
int nbgl_layoutAddNavigationBar(nbgl_layout_t *layout, const nbgl_layoutNavigationBar_t *info);
int nbgl_layoutAddBottomButton(nbgl_layout_t             *layout,
                               const nbgl_icon_details_t *icon,
                               uint8_t                    token,
                               bool                       separationLine,
                               tune_index_e               tuneId);
int nbgl_layoutAddProgressIndicator(nbgl_layout_t *layout,
                                    uint8_t        activePage,
                                    uint8_t        nbPages,
                                    bool           withBack,
                                    uint8_t        backToken,
                                    tune_index_e   tuneId);
int nbgl_layoutAddSpinner(nbgl_layout_t *layout, const char *text, bool fixed);
int nbgl_layoutAddSwipe(nbgl_layout_t *layout,
                        uint16_t       swipesMask,
                        const char    *text,
                        uint8_t        token,
                        tune_index_e   tuneId);
#else   // HAVE_SE_TOUCH
int nbgl_layoutAddText(nbgl_layout_t                  *layout,
                       const char                     *text,
                       const char                     *subText,
                       nbgl_contentCenteredInfoStyle_t style);
int nbgl_layoutAddNavigation(nbgl_layout_t *layout, nbgl_layoutNavigation_t *info);
int nbgl_layoutAddMenuList(nbgl_layout_t *layout, nbgl_layoutMenuList_t *list);
#endif  // HAVE_SE_TOUCH
 
#ifdef NBGL_KEYBOARD
/* layout objects for page with keyboard */
int nbgl_layoutAddKeyboard(nbgl_layout_t *layout, const nbgl_layoutKbd_t *kbdInfo);
#ifdef HAVE_SE_TOUCH
int            nbgl_layoutUpdateKeyboard(nbgl_layout_t *layout,
                                         uint8_t        index,
                                         uint32_t       keyMask,
                                         bool           updateCasing,
                                         keyboardCase_t casing);
bool           nbgl_layoutKeyboardNeedsRefresh(nbgl_layout_t *layout, uint8_t index);
DEPRECATED int nbgl_layoutAddSuggestionButtons(nbgl_layout_t *layout,
                                               uint8_t        nbUsedButtons,
                                               const char  *buttonTexts[NB_MAX_SUGGESTION_BUTTONS],
                                               int          firstButtonToken,
                                               tune_index_e tuneId);
DEPRECATED int nbgl_layoutUpdateSuggestionButtons(
    nbgl_layout_t *layout,
    uint8_t        index,
    uint8_t        nbUsedButtons,
    const char    *buttonTexts[NB_MAX_SUGGESTION_BUTTONS]);
DEPRECATED int nbgl_layoutAddEnteredText(nbgl_layout_t *layout,
                                         bool           numbered,
                                         uint8_t        number,
                                         const char    *text,
                                         bool           grayedOut,
                                         int            offsetY,
                                         int            token);
DEPRECATED int nbgl_layoutUpdateEnteredText(nbgl_layout_t *layout,
                                            uint8_t        index,
                                            bool           numbered,
                                            uint8_t        number,
                                            const char    *text,
                                            bool           grayedOut);
DEPRECATED int nbgl_layoutAddConfirmationButton(nbgl_layout_t *layout,
                                                bool           active,
                                                const char    *text,
                                                int            token,
                                                tune_index_e   tuneId);
DEPRECATED int nbgl_layoutUpdateConfirmationButton(nbgl_layout_t *layout,
                                                   uint8_t        index,
                                                   bool           active,
                                                   const char    *text);
int nbgl_layoutAddKeyboardContent(nbgl_layout_t *layout, nbgl_layoutKeyboardContent_t *content);
int nbgl_layoutUpdateKeyboardContent(nbgl_layout_t *layout, nbgl_layoutKeyboardContent_t *content);
#else   // HAVE_SE_TOUCH
int nbgl_layoutUpdateKeyboard(nbgl_layout_t *layout, uint8_t index, uint32_t keyMask);
int nbgl_layoutAddEnteredText(nbgl_layout_t *layout, const char *text, bool lettersOnly);
int nbgl_layoutUpdateEnteredText(nbgl_layout_t *layout, uint8_t index, const char *text);
#endif  // HAVE_SE_TOUCH
#endif  // NBGL_KEYBOARD
 
#ifdef NBGL_KEYPAD
#ifdef HAVE_SE_TOUCH
/* layout objects for page with keypad (Stax) */
int nbgl_layoutAddKeypad(nbgl_layout_t *layout, keyboardCallback_t callback, bool shuffled);
int nbgl_layoutUpdateKeypad(nbgl_layout_t *layout,
                            uint8_t        index,
                            bool           enableValidate,
                            bool           enableBackspace,
                            bool           enableDigits);
DEPRECATED int nbgl_layoutAddHiddenDigits(nbgl_layout_t *layout, uint8_t nbDigits);
DEPRECATED int nbgl_layoutUpdateHiddenDigits(nbgl_layout_t *layout,
                                             uint8_t        index,
                                             uint8_t        nbActive);
int            nbgl_layoutAddKeypadContent(nbgl_layout_t *layout,
                                           const char    *title,
                                           bool           hidden,
                                           uint8_t        nbDigits,
                                           const char    *text);
int            nbgl_layoutUpdateKeypadContent(nbgl_layout_t *layout,
                                              bool           hidden,
                                              uint8_t        nbActiveDigits,
                                              const char    *text);
 
#else   // HAVE_SE_TOUCH
/* layout objects for pages with keypad (nanos) */
int nbgl_layoutAddKeypad(nbgl_layout_t     *layout,
                         keyboardCallback_t callback,
                         const char        *text,
                         bool               shuffled);
int nbgl_layoutUpdateKeypad(nbgl_layout_t *layout,
                            uint8_t        index,
                            bool           enableValidate,
                            bool           enableBackspace);
int nbgl_layoutAddHiddenDigits(nbgl_layout_t *layout, uint8_t nbDigits);
int nbgl_layoutUpdateHiddenDigits(nbgl_layout_t *layout, uint8_t index, uint8_t nbActive);
#endif  // HAVE_SE_TOUCH
#endif  // NBGL_KEYPAD
 
/* generic functions */
int nbgl_layoutDraw(nbgl_layout_t *layout);
int nbgl_layoutRelease(nbgl_layout_t *layout);
 
/**********************
 *      MACROS
 **********************/
 
#ifdef __cplusplus
} /* extern "C" */
#endif
 
#endif /* NBGL_LAYOUT_H */