Screen

Collaboration diagram for Screen:

Data Structures
struct	SCREEN_S

Typedefs
typedef void(*	SCREEN_CALLBACK) (void *screen)
typedef struct SCREEN_S	SCREEN_STRUCT

Functions
bool	gui_screen_navigate (SCREEN_STRUCT *screen)
bool	gui_screen_back ()
SCREEN_STRUCT *	gui_screen_get_current ()
void	gui_screen_update ()

Detailed Description

The Screen Submodule provides an api to navigate between different "screens" on the UI. Each screen must provide an enter, update and a leave method; which will be called from this module at the right time. The implemented screens of the application are documented in the Screens module.

Typedef Documentation

typedef void(* SCREEN_CALLBACK) (void *screen)

Prototype for Event Listeners (called when the screen is entered, left or should be updated)

Parameters

screen

The pointer to the SCREEN_STRUCT where the event occurred

Definition at line 47 of file screen.h.

typedef struct SCREEN_S SCREEN_STRUCT

Structure to configure the Screen

Function Documentation

bool gui_screen_back

(

)

Navigate one screen back as soon as the app enters the main loop again. It's safe to call this method from an interrupt

Returns

true on success

Definition at line 85 of file screen.c.

{
    if (screen_list == NULL) { //the list head is emtpy, nothing to go back to
        return false;
    }

    SCREEN_STRUCT* current = screen_list;
    SCREEN_STRUCT* last = NULL;

    //Find second last element in list
    while (current->next != NULL) {
        last = current;
        current = current->next;
    }

    if (last == NULL) {
        return false;    //There's only a single screen, there's no going back here
    }

    if (current != screen_current) {
        return false;    //The last entry in the list is not the current screen. List corrupted?
    }

    screen_goto = last; //"send message" to main loop, to switch the screen
    return true;
}

Here is the caller graph for this function:

SCREEN_STRUCT* gui_screen_get_current

(

)

Returns the currently active screen

Returns

A Pointer to the active SCREEN_STRUCT

Definition at line 35 of file screen.c.

{
    return screen_current;
}

bool gui_screen_navigate

(

SCREEN_STRUCT *

screen

)

Navigate to the given screen as soon as the app enters the main loop again (and gui_screen_update() is called) It's safe to call this method from an interrupt

Note

Do not pass a screen which is already in your history of screens!

Parameters

screen

A Pointer to the preinitialized SCREEN_STRUCT

Returns

true on success

Definition at line 74 of file screen.c.

{
    if (screen == NULL || screen == screen_current || screen == screen_goto) { //invalid argument passed
        return false;
    }

    screen->next = NULL; //this will become the new tail of the list, so the next pointer must be NULL
    screen_goto = screen; //"send message" to main loop, to switch the screen
    return true;
}

Here is the caller graph for this function:

void gui_screen_update

(

)

Updates the current screen. Switches the screen if gui_screen_navigate() or gui_screen_back() have been called since the last call to this method. This method should be called repeatedly from the main loop (e.g. app_process())

Definition at line 41 of file screen.c.

{
    if (screen_goto != NULL) { //we received the task to switch the screen
        SCREEN_STRUCT* go = (SCREEN_STRUCT*) screen_goto; //Backup volatile variable
        screen_goto = NULL; //reset the "goto instruction", since we're processing it now

        if (go->next != NULL) { //The screen is not the last in the list, so we're going back
            if (go->next != screen_current) { //this condition should always be false
                return; //list corrupted?
            }

            screen_current->on_leave(screen_current); //let the current screen free/unregister it's resources
            go->next = NULL; //remove the current screen from the list
        } else { //we're going forward (to a new screen)
            if (screen_current != NULL) { //this is not the first screen
                screen_current->on_leave(screen_current); //let the current screen free/unregister it's resources
                screen_current->next = go; //append the new screen to the end of the list
            } else { //first screen ever seen
                screen_list = go; //set the new screen as list-head
            }
        }

        go->on_enter(go); //let the new screen allocate/register it's resources
        screen_current = go; //the new screen is now the current screen. Transition done
    }

    if (screen_current != NULL) { //A screen has been set
        screen_current->on_update(screen_current); //Update current screen
    }
}

Here is the caller graph for this function: