legato_widget_radial_menu.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.
*******************************************************************************/
 
/*******************************************************************************
 Module for Microchip Graphics Library - Legato User Interface Library
 
  Company:
    Microchip Technology Inc.
 
  File Name:
    legato_widget_radial_menu.h
 
  Summary:
    
 
  Description:
    This module implements radial menu widget functions.
*******************************************************************************/
 
#ifndef LEGATO_RADIALMENU_H
#define LEGATO_RADIALMENU_H
 
#include "gfx/legato/common/legato_common.h"
 
#if LE_RADIALMENU_WIDGET_ENABLED == 1
 
#include "gfx/legato/widget/legato_widget.h"
#include "gfx/legato/widget/image/legato_widget_image.h"
#include "gfx/legato/datastructure/legato_list.h"
#include "gfx/legato/string/legato_string.h"
 
typedef struct leRadialMenuWidget leRadialMenuWidget;
 
typedef void (*leRadialMenuWidget_ItemProminenceChangedEvent)(leRadialMenuWidget*, leWidget*, int32_t);
 
// *****************************************************************************
// *****************************************************************************
// Section: Data Types and Constants
// *****************************************************************************
// *****************************************************************************
typedef enum leRadialMenuWidgetState
{
    LE_RADIAL_MENU_INIT,
    LE_RADIAL_MENU_INPUT_READY,
    LE_RADIAL_MENU_HANDLE_USER_MOVE_REQUEST,
    LE_RADIAL_MENU_RESET_TO_INPUT_POS            
} leRadialMenuWidgetState;
 
typedef enum leRadialMenuWidgetInterpolationMode
{
    LE_RADIAL_MENU_INTERPOLATE_OFF,
    LE_RADIAL_MENU_INTERPOLATE_GRADUAL,
    LE_RADIAL_MENU_INTERPOLATE_PROMINENT
} leRadialMenuWidgetInterpolationMode;
 
/* internal use only */typedef struct leRadialMenuWidget leRadialMenuWidget;
 
#define LE_RADIALMENUWIDGET_VTABLE(THIS_TYPE) \
    LE_WIDGET_VTABLE(THIS_TYPE) \
    \
    leBool    (*isProminent)(const THIS_TYPE* _this, const leWidget* widget); \
    leWidget* (*getProminent)(const THIS_TYPE* _this); \
    leResult  (*setProminent)(THIS_TYPE* _this, const leWidget* widget); \
    int32_t   (*getProminentIndex)(const THIS_TYPE* _this); \
    leResult  (*setProminentIndex)(THIS_TYPE* _this, int32_t index); \
    leResult  (*setNumberOfItemsShown)(THIS_TYPE* _this, uint32_t cnt); \
    leResult  (*setHighlightProminent)(THIS_TYPE* _this, leBool hl); \
    int32_t   (*getMajorAxis)(const THIS_TYPE* _this); \
    leResult  (*setMajorAxis)(THIS_TYPE* _this, int32_t a); \
    int32_t   (*getMinorAxis)(const THIS_TYPE* _this); \
    leResult  (*setMinorAxis)(THIS_TYPE* _this, int32_t b); \
    int32_t   (*getTheta)(const THIS_TYPE* _this); \
    leResult  (*setTheta)(THIS_TYPE* _this, int32_t tht); \
    leResult  (*setScaleMode)(THIS_TYPE* _this, leRadialMenuWidgetInterpolationMode mode); \
    leResult  (*setScaleRange)(THIS_TYPE* _this, int32_t min, int32_t max); \
    leResult  (*setBlendMode)(THIS_TYPE* _this, leRadialMenuWidgetInterpolationMode mode); \
    leResult  (*setBlendRange)(THIS_TYPE* _this, int32_t min, int32_t max); \
    leResult  (*setTouchArea)(THIS_TYPE* _this, int32_t x, int32_t y, int32_t width, int32_t height); \
    leResult  (*setDrawEllipse)(THIS_TYPE* _this, leBool b); \
    leRadialMenuWidget_ItemProminenceChangedEvent (*getItemProminenceChangedEventCallback)(const THIS_TYPE* _this); \
    leResult  (*setItemProminenceChangedEventCallback)(THIS_TYPE* _this, leRadialMenuWidget_ItemProminenceChangedEvent cb);
 
typedef struct leRadialMenuWidgetVTable
{
    LE_RADIALMENUWIDGET_VTABLE(leRadialMenuWidget)
} leRadialMenuWidgetVTable; 
 
enum leRadialMenuItemState
{
    LE_RMI_NOT_VISIBLE,
    LE_RMI_WAITING_FOR_SORT,
    LE_RMI_VISIBLE,
    LE_RMI_PROMINENT
};
 
typedef struct leRadialMenuItemNode
{
    leWidget* widget; // point to the widget of the item
    lePoint point;
    int32_t angle;
    int32_t absAngle;
    int32_t adjustedAngle;
    int32_t paintAngle;
    uint32_t percent;
 
    leRect origSize;  //the original size of the widget, it is a reference point for scaling
    uint32_t origAlphaAmount; //the original alpha value of the widget, it is a reference point for scaling
 
    enum leRadialMenuItemState state;
 
} leRadialMenuItemNode;
 
// *****************************************************************************
typedef struct leRadialMenuWidget
{
    leWidget widget; // widget base class
    
    const leRadialMenuWidgetVTable* fn;
 
    leRadialMenuWidgetState state;
 
    int32_t prominentIndex;
 
    leBool drawEllipse; // indicates if the radial menu is selected
    leBool highlightProminent; // highlight the prominent widget
 
    struct
    {
    leBool invalid;
        int32_t a;  // the half-length of the 0-180 axis of the ellipse
        int32_t b;  // the half-length of the 90-270 axis of the ellipse
        int32_t theta; // the angle of rotation of the entire ellipse
    } ellipse;
 
    struct
    {
        uint32_t maxWidth;
        uint32_t maxHeight;
        uint32_t alpha;
        int32_t firstVisibleItem;
        uint32_t lastZ;
    } paintState;
 
    leBool touchPressed; // keep track of users touch input
    int32_t rotationDegrees;
    int32_t angleSlice;
    
    leRadialMenuWidgetInterpolationMode scaleMode;  // the enable item size scaling within the widget
 
    int32_t maxSizePercent;  // the maximum size scale between 1 - 200%
    int32_t minSizePercent;  // the minimum size scale between 1 - 200%
 
    uint32_t touchX; // the x offset of the touch area as a percentage
    uint32_t touchY; // the y offset of the touch area as a percentage
    uint32_t touchWidth; // the width of the touch area as a percentage
    uint32_t touchHeight; // the height of the touch area as a percentage
 
    leRect touchArea; // the area specified within the widget that touch events are detected in pixels
 
    int32_t minFlickDelta; // amount of distance that must be dragged in a single
    // frame to trigger momentum mode
 
    int32_t momentum; // current momentum value
    int32_t maxMomentum; // maximum momentum value
    int32_t momentumFalloff; // momentum falloff rate
    int32_t rotation; // determines actual rotation of the wheel
    int32_t rotationCounter; // time-based limiter for rotation calculations
    int32_t rotationTick; // rotation time accumulator
 
    int32_t snapState;
    int32_t snapCounter;
    int32_t snapMagnitude;
 
    leRadialMenuWidgetInterpolationMode blendMode; // the enable item alpha scaling within the widget
 
    int32_t maxAlphaAmount;  // the maximum alpha between 0 - 255
    int32_t minAlphaAmount;  // the minimum alpha between 0 - 255
 
    uint32_t itemsShown; // keeps count of how many items to visible, this number should be less than or equal to total number of widget items
    leList widgetList; // this is the list of widgets
    leBool positionsInvalid;
    
    leRadialMenuWidget_ItemProminenceChangedEvent itemProminenceChangedEvent; // whenever a new item is in prominence event callback
} leRadialMenuWidget;
 
 
// *****************************************************************************
// *****************************************************************************
// Section: Routines
// *****************************************************************************
// *****************************************************************************
 
LIB_EXPORT leRadialMenuWidget* leRadialMenuWidget_New();
 
LIB_EXPORT void leRadialMenuWidget_Constructor(leRadialMenuWidget* wgt);
 
#ifdef _DOXYGEN_
#define THIS_TYPE struct leWidget
 
// *****************************************************************************
/* Virtual Member Function:
    leBool isProminent(const leRadialMenuWidget* _this,
                       const leWidget* widget)
 
  Summary:
     Evaluates a widget to see if it is the prominent widget
 
  Description:
     Evaluates a widget to see if it is the prominent widget
 
  Parameters:
    const leRadialMenuWidget* _this - The radial menu bar widget to operate on
    const leWidget* widget -
 
  Remarks:
    Usage - _this->fn->isProminent(_this, widget);
 
  Returns:
    leBool - the prominent indicator
*/
 
// *****************************************************************************
/* Virtual Member Function:
    leWidget* getProminent(const leRadialMenuWidget* _this)
 
  Summary:
     Gets the prominent child widget
 
  Description:
     Gets the prominent child widget
 
  Parameters:
    const leRadialMenuWidget* _this - The radial menu widget to operate on
 
  Remarks:
    Usage - _this->fn->getProminent(_this);
 
  Returns:
    leWidget* - the prominent child widget
*/
 
// *****************************************************************************
/* Virtual Member Function:
    leResult setProminent(leRadialMenuWidget* _this,
                          const leWidget* widget)
 
  Summary:
     Sets a widget as prominent
 
  Description:
     Sets a widget as prominent
 
  Parameters:
    leRadialMenuWidget* _this - The radial menu bar widget to operate on
    const leWidget* widget - the widget to test
 
  Remarks:
    Usage - _this->fn->setProminent(_this, widget);
 
  Returns:
    leResult - the result of the operation
*/
virtual leResult setProminent(leRadialMenuWidget* _this,
                              const leWidget* widget);
 
 
// *****************************************************************************
/* Virtual Member Function:
    int32_t getProminentIndex(const leRadialMenuWidget* _this)
 
  Summary:
     Gets the prominent item index
 
  Description:
     Gets the prominent item index
 
  Parameters:
    const leRadialMenuWidget* _this - The radial menu bar widget to operate on
 
  Remarks:
    Usage - _this->fn->getProminentIndex(_this);
 
  Returns:
    int32_t - the prominent index
*/
virtual int32_t getProminentIndex(const leRadialMenuWidget* _this);
 
// *****************************************************************************
/* Virtual Member Function:
    leResult setProminentIndex(leRadialMenuWidget* _this,
                               int32_t index)
 
  Summary:
     Sets the prominent item index
 
  Description:
     Sets the prominent item index
 
  Parameters:
    leRadialMenuWidget* _this - The radial menu bar widget to operate on
    int32_t index - the desired prominent index
 
  Remarks:
    Usage - _this->fn->setProminentIndex(_this, index);
 
  Returns:
    leResult - the result of the operation
*/
virtual leResult setProminentIndex(leRadialMenuWidget* _this,
                                   int32_t index);
 
// *****************************************************************************
/* Virtual Member Function:
    leResult setNumberOfItemsShown(leRadialMenuWidget* _this,
                                   uint32_t cnt)
 
  Summary:
     Sets the number of items shown
 
  Description:
     Sets the number of items shown
 
  Parameters:
    leRadialMenuWidget* _this - The radial menu bar widget to operate on
    uint32_t cnt - the item count
 
  Remarks:
    Usage - _this->fn->setNumberOfItemsShown(_this, cnt);
 
  Returns:
    leResult - the result of the operation
*/
 
// *****************************************************************************
/* Virtual Member Function:
    leResult setHighlightProminent(leRadialMenuWidget* _this,
                                   leBool hl)
 
  Summary:
     Sets the highlight prominent setting value
 
  Description:
     Sets the highlight prominent setting value
 
  Parameters:
    leRadialMenuWidget* _this - The radial menu bar widget to operate on
    leBool hl - the setting value
 
  Remarks:
    Usage - _this->fn->setHighlightProminent(_this, hl);
 
  Returns:
    leResult - the result of the operation
*/
virtual leResult setHighlightProminent(leRadialMenuWidget* _this,
                                       leBool hl);
 
// *****************************************************************************
/* Virtual Member Function:
    int32_t getTheta(const leRadialMenuWidget* _this)
 
  Summary:
     Gets the menu ellipse rotation coefficient
 
  Description:
     Gets the menu ellipse rotation coefficient
 
  Parameters:
    const leRadialMenuWidget* _this - The radial menu bar widget to operate on
 
  Remarks:
    Usage - _this->fn->getTheta(_this);
 
  Returns:
    int32_t - the theta value
*/
virtual int32_t getTheta(const leRadialMenuWidget* _this);
 
// *****************************************************************************
/* Virtual Member Function:
    leResult setTheta(leRadialMenuWidget* _this,
                      int32_t tht)
 
  Summary:
     Sets the menu ellipse rotation coefficient
 
  Description:
     Sets the menu ellipse rotation coefficient
 
  Parameters:
    leRadialMenuWidget* _this - The radial menu bar widget to operate on
    int32_t tht - the theta value
 
  Remarks:
    Usage - _this->fn->setTheta(_this, tht);
 
  Returns:
    leResult - the result of the operation
*/
virtual leResult setTheta(leRadialMenuWidget* _this,
                          int32_t tht);
 
// *****************************************************************************
/* Virtual Member Function:
    leResult setEllipseType(leRadialMenuWidget* _this,
                            leRadialMenuEllipseType type)
 
  Summary:
     Sets the menu ellipse type
 
  Description:
     Sets the menu ellipse type
 
  Parameters:
    leRadialMenuWidget* _this - The radial menu bar widget to operate on
    leRadialMenuEllipseType type - the type
 
  Remarks:
    Usage - _this->fn->setEllipseType(_this, type);
 
  Returns:
    leResult - the result of the operation
*/
virtual leResult setEllipseType(leRadialMenuWidget* _this,
                                leRadialMenuEllipseType type);
 
// *****************************************************************************
/* Virtual Member Function:
    leResult addWidget(leRadialMenuWidget* _this,
                       leWidget* wgt)
 
  Summary:
     Adds a widget to the ellipse
 
  Description:
     Adds a widget to the ellipse
 
  Parameters:
    leRadialMenuWidget* _this - The radial menu bar widget to operate on
    leWidget* wgt - the widget to add
 
  Remarks:
    Usage - _this->fn->addWidget(_this, wgt);
 
  Returns:
    leResult - the result of the operation
*/
virtual leResult addWidget(leRadialMenuWidget* _this,
                           leWidget* wgt);
 
// *****************************************************************************
/* Virtual Member Function:
    leResult removeWidget(leRadialMenuWidget* _this,
                          leWidget* wgt)
 
  Summary:
     Removes a widget from the ellipse
 
  Description:
     Removes a widget from the ellipse
 
  Parameters:
    leRadialMenuWidget* _this - The radial menu bar widget to operate on
    leWidget* wgt - the widget to remove
 
  Remarks:
    Usage - _this->fn->removeWidget(_this, wgt);
 
  Returns:
    leResult - the result of the operation
*/
virtual leResult removeWidget(leRadialMenuWidget* _this,
                              leWidget* wgt);
 
// *****************************************************************************
/* Virtual Member Function:
    leWidget* getWidgetAtIndex(const leRadialMenuWidget* _this,
                               int32_t idx)
 
  Summary:
     Gets a widget at a given index
 
  Description:
     Gets a widget at a given index
 
  Parameters:
    const leRadialMenuWidget* _this - The radial menu bar widget to operate on
    int32_t idx - the index
 
  Remarks:
    Usage - _this->fn->getWidgetAtIndex(_this, idx);
 
  Returns:
    leWidget* - the widget
*/
virtual leWidget* getWidgetAtIndex(const leRadialMenuWidget* _this,
                                   int32_t idx);
 
// *****************************************************************************
/* Virtual Member Function:
    leResult setWidgetAtIndex(leRadialMenuWidget* _this,
                              int32_t idx,
                              leWidget* wgt)
 
  Summary:
     Sets a widget at a given index
 
  Description:
     Sets a widget at a given index
 
  Parameters:
    leRadialMenuWidget* _this - The radial menu bar widget to operate on
    int32_t idx - the index
    leWidget* wgt - the widget to set
 
  Remarks:
    Usage - _this->fn->setWidgetAtIndex(_this, idx, wgt);
 
  Returns:
    leResult - the result of the operation
*/
virtual leResult setWidgetAtIndex(leRadialMenuWidget* _this,
                                  int32_t idx,
                                  leWidget* wgt);
 
// *****************************************************************************
/* Virtual Member Function:
    leResult removeAllWidgets(leRadialMenuWidget* _this)
 
  Summary:
     Removes all widgets from the menu
 
  Description:
     Removes all widgets from the menu
 
  Parameters:
    leRadialMenuWidget* _this - The radial menu bar widget to operate on
 
  Remarks:
    Usage - _this->fn->removeAllWidgets(_this);
 
  Returns:
    leResult - the result of the operation
*/
virtual leResult removeAllWidgets(leRadialMenuWidget* _this);
 
// *****************************************************************************
/* Virtual Member Function:
    leResult setScaleMode(leRadialMenuWidget* _this,
                          leRadialMenuWidgetInterpolationMode mode)
 
  Summary:
     Sets the menu item scaling mode
 
  Description:
     Sets the menu item scaling mode
 
  Parameters:
    leRadialMenuWidget* _this - The radial menu bar widget to operate on
    leRadialMenuWidgetInterpolationMode mode -
 
  Remarks:
    Usage - _this->fn->setScaleMode(_this, mode);
 
  Returns:
    leResult - the result of the operation
*/
virtual leResult setScaleMode(leRadialMenuWidget* _this,
                              leRadialMenuWidgetInterpolationMode mode);
 
// *****************************************************************************
/* Virtual Member Function:
    leResult setScaleRange(leRadialMenuWidget* _this,
                           int32_t min,
                           int32_t max)
 
  Summary:
     Sets the scale range for menu items
 
  Description:
     Sets the scale range for menu items
 
  Parameters:
    leRadialMenuWidget* _this - The radial menu bar widget to operate on
    int32_t min - the minimum value
    int32_t max - the maximum value
 
  Remarks:
    Usage - _this->fn->setScaleRange(_this, min, max);
 
  Returns:
    leResult - the result of the operation
*/
virtual leResult setScaleRange(leRadialMenuWidget* _this,
                               int32_t min,
                               int32_t max);
 
// *****************************************************************************
/* Virtual Member Function:
    leResult setBlendMode(leRadialMenuWidget* _this,
                          leRadialMenuWidgetInterpolationMode mode)
 
  Summary:
     Sets the menu item blending mode
 
  Description:
     Sets the menu item blending mode
 
  Parameters:
    leRadialMenuWidget* _this - The radial menu bar widget to operate on
    leRadialMenuWidgetInterpolationMode mode -
 
  Remarks:
    Usage - _this->fn->setBlendMode(_this, mode);
 
  Returns:
    leResult - the result of the operation
*/
virtual leResult setBlendMode(leRadialMenuWidget* _this,
                              leRadialMenuWidgetInterpolationMode mode);
 
// *****************************************************************************
/* Virtual Member Function:
    leResult setBlendRange(leRadialMenuWidget* _this,
                           int32_t min,
                           int32_t max)
 
  Summary:
     Sets the blending range
 
  Description:
     Sets the blending range
 
  Parameters:
    leRadialMenuWidget* _this - The radial menu bar widget to operate on
    int32_t min - the minimum value
    int32_t max - the maximum value
 
  Remarks:
    Usage - _this->fn->setBlendRange(_this, min, max);
 
  Returns:
    leResult - the result of the operation
*/
virtual leResult setBlendRange(leRadialMenuWidget* _this,
                               int32_t min,
                               int32_t max);
 
// *****************************************************************************
/* Virtual Member Function:
    leResult setTouchArea(leRadialMenuWidget* _this,
                          int32_t x,
                          int32_t y,
                          int32_t width,
                          int32_t height)
 
  Summary:
     Sets the menu touch area
 
  Description:
     Sets the menu touch area
 
  Parameters:
    leRadialMenuWidget* _this - The radial menu bar widget to operate on
    int32_t x - the X value
    int32_t y - the Y value
    int32_t width - the width value
    int32_t height - the height value
 
  Remarks:
    Usage - _this->fn->setTouchArea(_this, x, y, width, height);
 
  Returns:
    leResult - the result of the operation
*/
virtual leResult setTouchArea(leRadialMenuWidget* _this,
                              int32_t x,
                              int32_t y,
                              int32_t width,
                              int32_t height);
 
// *****************************************************************************
/* Virtual Member Function:
    leResult setDrawEllipse(leRadialMenuWidget* _this,
                            leBool b)
 
  Summary:
     Sets the draw ellipse setting value
 
  Description:
     Sets the draw ellipse setting value
 
  Parameters:
    leRadialMenuWidget* _this - The radial menu bar widget to operate on
    leBool b - the setting value
 
  Remarks:
    Usage - _this->fn->setDrawEllipse(_this, b);
 
  Returns:
    leResult - the result of the operation
*/
virtual leResult setDrawEllipse(leRadialMenuWidget* _this,
                                leBool b);
 
virtual leRadialMenuWidget_ItemSelectedEvent getItemSelectedEventCallback(const leRadialMenuWidget* _this)
 
 
virtual leResult setItemSelectedEventCallback(leRadialMenuWidget* _this,
                                              leRadialMenuWidget_ItemSelectedEvent cb);
 
virtual leRadialMenuWidget_ItemProminenceChangedEvent getItemProminenceChangedEventCallback
                                                    (const leRadialMenuWidget* _this)
 
 
virtual leResult setItemProminenceChangedEventCallback(leRadialMenuWidget* _this,
                                                       leRadialMenuWidget_ItemProminenceChangedEvent cb)
 
#undef THIS_TYPE
#endif
 
#endif // LE_RADIALMENU_WIDGET_ENABLED
#endif /* LEGATO_RADIALMENU_H */