legato_state.h

Go to the documentation of this file.

/*******************************************************************************
* Copyright (C) 2020 Microchip Technology Inc. and its subsidiaries.
*
* Subject to your compliance with these terms, you may use Microchip software
* and any derivatives exclusively with Microchip products. It is your
* responsibility to comply with third party license terms applicable to your
* use of third party software (including open source software) that may
* accompany Microchip software.
*
* THIS SOFTWARE IS SUPPLIED BY MICROCHIP "AS IS". NO WARRANTIES, WHETHER
* EXPRESS, IMPLIED OR STATUTORY, APPLY TO THIS SOFTWARE, INCLUDING ANY IMPLIED
* WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, AND FITNESS FOR A
* PARTICULAR PURPOSE.
*
* IN NO EVENT WILL MICROCHIP BE LIABLE FOR ANY INDIRECT, SPECIAL, PUNITIVE,
* INCIDENTAL OR CONSEQUENTIAL LOSS, DAMAGE, COST OR EXPENSE OF ANY KIND
* WHATSOEVER RELATED TO THE SOFTWARE, HOWEVER CAUSED, EVEN IF MICROCHIP HAS
* BEEN ADVISED OF THE POSSIBILITY OR THE DAMAGES ARE FORESEEABLE. TO THE
* FULLEST EXTENT ALLOWED BY LAW, MICROCHIP'S TOTAL LIABILITY ON ALL CLAIMS IN
* ANY WAY RELATED TO THIS SOFTWARE WILL NOT EXCEED THE AMOUNT OF FEES, IF ANY,
* THAT YOU HAVE PAID DIRECTLY TO MICROCHIP FOR THIS SOFTWARE.
*******************************************************************************/

#ifndef LEGATO_STATE_H
#define LEGATO_STATE_H

#ifdef __cplusplus
extern "C" {
#endif

#include "gfx/legato/common/legato_common.h"

#include "gfx/driver/gfx_driver.h"
#include "gfx/legato/core/legato_input.h"
#include "gfx/legato/core/legato_scheme.h"
#include "gfx/legato/string/legato_stringtable.h"
#include "gfx/legato/widget/legato_editwidget.h" 

// *****************************************************************************
typedef void (*leLanguageChangedCallback_FnPtr)(uint32_t);

typedef enum leLayerClearMode
{
    LE_LAYERCLEARMODE_DEFAULT,
    LE_LAYERCLEARMODE_DISABLE,
    LE_LAYERCLEARMODE_FORCE,
} leLayerClearMode;

// *****************************************************************************
struct leLayerState;

typedef struct leLayerState
{
    leWidget root;
    leColorMode colorMode;
    leBool renderHorizontal;
    lePoint driverPosition;
    leLayerClearMode clearMode;

    void* rendererData;

    struct leLayerState* prev;
    struct leLayerState* next;
} leLayerState;

// *****************************************************************************
typedef struct leState
{
    const leStringTable* stringTable; 
    uint32_t languageID; 
    uint32_t widgetIDs; 
    leScheme defaultScheme; 
    leWidget* focus; 
    leEditWidget* edit; 
    leLanguageChangedCallback_FnPtr languageChangedCB; 
    leList layerList; 
#if LE_STREAMING_ENABLED == 1
    leStreamManager* activeStream; 
#endif
} leState;

/* internal use only */
leState* leGetState(void);
// *****************************************************************************
leResult leInitialize(const gfxDisplayDriver* dispDriver,
                      const gfxGraphicsProcessor* gpuDriver);

// *****************************************************************************
void leShutdown(void);

// *****************************************************************************
leResult leUpdate(uint32_t dt);

// TODO documentation
uint32_t leLayerCount(void);

// TODO documentation
int32_t leAddLayer(void);

// TODO documentation
leResult leRemoveLayer(uint32_t idx);

// TODO documentation
leLayerState* leGetLayerState(uint32_t idx);

leColorMode leGetLayerColorMode(uint32_t lyrIdx);

leResult leSetLayerColorMode(uint32_t lyrIdx, leColorMode mode);

leResult leAddRootWidget(leWidget* wgt,
                         uint32_t layer);

/*  Function:
        leResult leRemoveRootWidget(leWidget* wgt, uint32_t layer)

    Summary:
        Removes a custom widget from a static scene root widget.

    Description:
        The library maintains a static list of widgets that are considered
        to be scene roots.  This API removes a child widget from one of the
        static roots.

    Returns:
        leResult

*/
leResult leRemoveRootWidget(leWidget* wgt,
                            uint32_t layer);




leBool leGetLayerRenderHorizontal(uint32_t lyrIdx);

leResult leSetLayerRenderHorizontal(uint32_t lyrIdx, leBool horz);

leLayerClearMode leGetLayerClearMode(uint32_t lyrIdx);

leResult leSetLayerClearMode(uint32_t lyrIdx,
                             leLayerClearMode mode);

#if 0
// *****************************************************************************
leRect leGetDisplayRect();
#endif

// *****************************************************************************
leStringTable* leGetStringTable(void);

// *****************************************************************************
/* Function:
    void leSetStringTable(leStringTable* table)

   Summary:
    Set the StringTable pointer to the specified new StringTableAsset structure  

   Description:
    Set the StringTable pointer to the specified new StringTableAsset structure 

   Precondition:

   Parameters:
    leStringTable*

  Returns:
    void

  Remarks:    
    
*/
void leSetStringTable(const leStringTable* table);

// *****************************************************************************
/* Function:
    uint32_t leGetStringLanguage()

   Summary:
    Returns the language index of the current context  

   Description:
    Returns the language index of the current context

   Precondition:

   Parameters:
    
  Returns:
    uint32_t

  Remarks:    
    
*/
uint32_t leGetStringLanguage(void);

// *****************************************************************************
/* Function:
    void leSetStringLanguage(uint32_t id)

   Summary:
    Sets the current language index 

   Description:
    Sets the current language index

   Precondition:

   Parameters:
    uint32_t

  Returns:
    void

  Remarks:    
    
*/
void leSetStringLanguage(uint32_t id);

// *****************************************************************************
/* Function:
    leScheme* leGetDefaultScheme()

   Summary:
    Returns the pointer to the current default scheme  

   Description:
    Returns the pointer to the current default scheme

   Precondition:

   Parameters:
    
  Returns:
    leScheme*

  Remarks:    
    
*/
leScheme* leGetDefaultScheme(void);

// *****************************************************************************
/* Function:
    leWidget* leGetFocusWidget()

   Summary:
    Return a pointer to the widget in focus 

   Description:
    The focus widget is the widget that is currently receiving all input events.
    This can happen when the user initiates a touch down event on the widget
    and is currently dragging their finger on the display.  The widget will
    receive all touch moved events until a touch up event is received.

   Precondition:

   Parameters:
    
  Returns:
    leWidget*

  Remarks:    
    
*/
leWidget* leGetFocusWidget(void);

// *****************************************************************************
/* Function:
    leResult leSetFocusWidget(leWidget* widget)

   Summary:
    Set into focus the widget specified as the argument 

   Description:
    Set into focus the widget specified as the argument

   Precondition:

   Parameters:
    leWidget*

  Returns:
    leResult

  Remarks:    
    
*/
leResult leSetFocusWidget(leWidget* widget);

// *****************************************************************************
/* Function:
    leEditWidget* leGetEditWidget()

   Summary:
    Gets the widget that is currently recieving all widget edit events.

   Description:
    Edit widgets are widgets that inherit the 'edit widget' API function list.
    These widgets are capable of receiving edit events from other widgets
    that are edit event broadcasters.  A broadcaster could be a 'key pad' and
    a receiver could be a 'text edit' box.

   Precondition:

   Parameters:
    void

  Returns:
    leEditWidget*

  Remarks:    
    
*/
leEditWidget* leGetEditWidget(void);

// *****************************************************************************
/* Function:
    leResult leSetEditWidget(leEditWidget* widget)

   Summary:
    Sets the currently active edit widget.  

   Precondition:

   Parameters:
    leEditWidget* - a widget that inherits the edit widget API

  Returns:
    leResult

  Remarks:    
    
*/
leResult leSetEditWidget(leEditWidget* widget);
    
// *****************************************************************************
/* Function:
    leResult leSetLanguageChangedCallback(leLanguageChangedCallback_FnPtr cb)

   Summary:
    Set the callback function pointer when the language change event occurs  

   Description:
    Set the callback function pointer when the language change event occurs

   Precondition:

   Parameters:
    leLanguageChangedCallback_FnPtr

  Returns:
    leResult

  Remarks:    
    
*/
leResult leSetLanguageChangedCallback(leLanguageChangedCallback_FnPtr cb);
 
// *****************************************************************************
/* Function:
    void leRedrawAll()

   Summary:
    Forces the library to redraw the currently active scene in its entirety.  

   Precondition:

   Parameters:
    
  Returns:
    void

  Remarks:    
    
*/
void leRedrawAll(void);

/*  Function:
        leBool leIsDrawing()
 
    Summary:
        Indicates if any layers of the active screen are currently drawing a
        frame.
        
    Description:
        Indicates if the library currently drawing a frame.  Because frame updates
        can asynchronous to making changes to the UI state it is best to only make 
        updates to the state of a widget only when the layer is not drawing.
        
    Returns:
        leResult    

*/
leBool leIsDrawing(void);

/*  Function:
        leResult leAddRootWidget(leWidget* wgt, uint32_t layer)

    Summary:
        Adds a custom widget to a static scene root widget.

    Description:
        The library maintains a static list of widgets that are considered
        to be scene roots.  The library treats these roots as layers and
        the display driver may configure itself to render these roots
        to different hardware layers.

        This API adds a child widget to one of the static roots.

    Returns:
        leResult

*/


/*  Function:
        leBool leWidgetIsInScene(const leWidget* wgt)

    Summary:
        Searches the active scene for a given widget.

    Description:
        Searches the active scene for a given widget.

    Returns:
        leResult - LE_TRUE if the widget is in the current scene

*/
leBool leWidgetIsInScene(const leWidget* wgt);

int32_t leGetWidgetLayer(const leWidget* wgt);


/*  Function:
        leResult leEdit_StartEdit(const leWidget* wgt)

    Summary:
        Passes a 'start edit' command to the current edit widget,
        if one exists

    Description:
        The edit widget is the widget in the scene that is currently receiving
        edit events.

    Returns:
        leResult - LE_TRUE the command was processed successfully

*/
leResult leEdit_StartEdit(void);

void leEdit_EndEdit(void);

void leEdit_Clear(void);

void leEdit_Accept(void);

/*  Function:
        leResult leEdit_Accept(const leWidget* wgt)

    Summary:
        Passes a 'set' command and a string to the current edit widget,
        if one exists

    Description:
        Passes a 'set' command and a string to the current edit widget,
        if one exists

    Returns:

*/
void leEdit_Set(leString* str);

/*  Function:
        leResult leEdit_Append(const leWidget* wgt)

    Summary:
        Passes an 'append' command and a string to the current edit widget,
        if one exists

    Description:
        Passes an 'append' command and a string to the current edit widget,
        if one exists

    Returns:

*/
void leEdit_Append(leString* str);

/*  Function:
        leResult leEdit_Append(const leWidget* wgt)

    Summary:
        Passes a 'backspace' command to the current edit widget,
        if one exists

    Description:
        Passes a 'backspace' command to the current edit widget,
        if one exists

    Returns:

*/
void leEdit_Backspace(void);

#if LE_STREAMING_ENABLED == 1
/*  Function:
        leStreamManager* leGetActiveStream()

    Summary:
        Gets the global active data stream manager for the library.

    Description:
        A data stream manager is a state machine that is currently
        attempting to stream data from a source that is external
        to the library and possibly local memory.  This stream must
        be handled to completion before any further rendering can take place.

    Returns:

*/
leStreamManager* leGetActiveStream(void);

/*  Function:
        leResult leRunActiveStream()

    Summary:
        Allows the current active data stream to run until it preempts or
        completes.

    Description:
        Allows the current active data stream to run until it preempts or
        completes.

    Returns:

*/
leResult leRunActiveStream(void);

/*  Function:
        void leAbortActiveStream

    Summary:
        Terminates the current active data stream regardless of whether
        it still has data to receive.

    Description:
        Terminates the current active data stream regardless of whether
        it still has data to receive.  It will likely attempt to clean itself up
        as best it can.  Care should be taken in the application to not send data
        to the stream after it has been aborted.

    Returns:

*/
void leAbortActiveStream(void);
#endif

#ifdef __cplusplus
}
#endif

#endif /* LEGATO_STATE_H */