OLEDDisplayUi.h

00001 /**
00002  * The MIT License (MIT)
00003  *
00004  * Copyright (c) 2018 by ThingPulse, Daniel Eichhorn
00005  * Copyright (c) 2018 by Fabrice Weinberg
00006  * Copyright (c) 2019 by Helmut Tschemernjak - www.radioshuttle.de
00007  *
00008  * Permission is hereby granted, free of charge, to any person obtaining a copy
00009  * of this software and associated documentation files (the "Software"), to deal
00010  * in the Software without restriction, including without limitation the rights
00011  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00012  * copies of the Software, and to permit persons to whom the Software is
00013  * furnished to do so, subject to the following conditions:
00014  *
00015  * The above copyright notice and this permission notice shall be included in all
00016  * copies or substantial portions of the Software.
00017  *
00018  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00019  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00020  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00021  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00022  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00023  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
00024  * SOFTWARE.
00025  *
00026  * ThingPulse invests considerable time and money to develop these open source libraries.
00027  * Please support us by buying our products (and not the clones) from
00028  * https://thingpulse.com
00029  *
00030  */
00031 
00032 #ifndef OLEDDISPLAYUI_h
00033 #define OLEDDISPLAYUI_h
00034 
00035 #ifdef ARDUINO
00036 #include <Arduino.h>
00037 #elif __MBED__
00038 #include <mbed.h>
00039 #else
00040 #error "Unkown operating system"
00041 #endif
00042 
00043 #include "OLEDDisplay.h"
00044 
00045 //#define DEBUG_OLEDDISPLAYUI(...) Serial.printf( __VA_ARGS__ )
00046 
00047 #ifndef DEBUG_OLEDDISPLAYUI
00048 #define DEBUG_OLEDDISPLAYUI(...)
00049 #endif
00050 
00051 enum AnimationDirection {
00052   SLIDE_UP,
00053   SLIDE_DOWN,
00054   SLIDE_LEFT,
00055   SLIDE_RIGHT
00056 };
00057 
00058 enum IndicatorPosition {
00059   TOP,
00060   RIGHT,
00061   BOTTOM,
00062   LEFT
00063 };
00064 
00065 enum IndicatorDirection {
00066   LEFT_RIGHT,
00067   RIGHT_LEFT
00068 };
00069 
00070 enum FrameState {
00071   IN_TRANSITION,
00072   FIXED
00073 };
00074 
00075 
00076 const uint8_t ANIMATION_activeSymbol[] PROGMEM = {
00077   0x00, 0x18, 0x3c, 0x7e, 0x7e, 0x3c, 0x18, 0x00
00078 };
00079 
00080 const uint8_t ANIMATION_inactiveSymbol[] PROGMEM = {
00081   0x00, 0x0, 0x0, 0x18, 0x18, 0x0, 0x0, 0x00
00082 };
00083 
00084 
00085 // Structure of the UiState
00086 struct OLEDDisplayUiState {
00087   uint64_t     lastUpdate;
00088   uint16_t      ticksSinceLastStateSwitch;
00089 
00090   FrameState    frameState;
00091   uint8_t       currentFrame;
00092 
00093   bool          isIndicatorDrawen;
00094 
00095   // Normal = 1, Inverse = -1;
00096   int8_t        frameTransitionDirection;
00097 
00098   bool          manuelControll;
00099 
00100   // Custom data that can be used by the user
00101   void*         userData;
00102 };
00103 
00104 struct LoadingStage {
00105   const char* process;
00106   void (*callback)();
00107 };
00108 
00109 typedef void (*FrameCallback)(OLEDDisplay *display,  OLEDDisplayUiState* state, int16_t x, int16_t y);
00110 typedef void (*OverlayCallback)(OLEDDisplay *display,  OLEDDisplayUiState* state);
00111 typedef void (*LoadingDrawFunction)(OLEDDisplay *display, LoadingStage* stage, uint8_t progress);
00112 
00113 class OLEDDisplayUi {
00114   private:
00115     OLEDDisplay             *display;
00116 
00117     // Symbols for the Indicator
00118     IndicatorPosition   indicatorPosition;
00119     IndicatorDirection  indicatorDirection;
00120 
00121     const uint8_t*         activeSymbol;
00122     const uint8_t*         inactiveSymbol;
00123 
00124     bool                shouldDrawIndicators;
00125 
00126     // Values for the Frames
00127     AnimationDirection  frameAnimationDirection;
00128 
00129     int8_t              lastTransitionDirection;
00130 
00131     uint16_t            ticksPerFrame;      // ~ 5000ms at 30 FPS
00132     uint16_t            ticksPerTransition; // ~  500ms at 30 FPS
00133 
00134     bool                autoTransition;
00135 
00136     FrameCallback*      frameFunctions;
00137     uint8_t             frameCount;
00138 
00139     // Internally used to transition to a specific frame
00140     int8_t              nextFrameNumber;
00141 
00142     // Values for Overlays
00143     OverlayCallback*    overlayFunctions;
00144     uint8_t             overlayCount;
00145 
00146     // Will the Indicator be drawen
00147     // 3 Not drawn in both frames
00148     // 2 Drawn this frame but not next
00149     // 1 Not drown this frame but next
00150     // 0 Not known yet
00151     uint8_t                indicatorDrawState;
00152 
00153     // Loading screen
00154     LoadingDrawFunction loadingDrawFunction;
00155     
00156     // UI State
00157     OLEDDisplayUiState      state;
00158 
00159     // Bookeeping for update
00160     uint8_t             updateInterval;
00161 
00162     uint8_t             getNextFrameNumber();
00163     void                drawIndicator();
00164     void                drawFrame();
00165     void                drawOverlays();
00166     void                tick();
00167     void                resetState();
00168 
00169   public:
00170 
00171     OLEDDisplayUi(OLEDDisplay *display);
00172 
00173     /**
00174      * Initialise the display
00175      */
00176     void init();
00177 
00178     /**
00179      * Configure the internal used target FPS
00180      */
00181     void setTargetFPS(uint8_t fps);
00182 
00183     // Automatic Controll
00184     /**
00185      * Enable automatic transition to next frame after the some time can be configured with `setTimePerFrame` and `setTimePerTransition`.
00186      */
00187     void enableAutoTransition();
00188 
00189     /**
00190      * Disable automatic transition to next frame.
00191      */
00192     void disableAutoTransition();
00193 
00194     /**
00195      * Set the direction if the automatic transitioning
00196      */
00197     void setAutoTransitionForwards();
00198     void setAutoTransitionBackwards();
00199 
00200     /**
00201      *  Set the approx. time a frame is displayed
00202      */
00203     void setTimePerFrame(uint16_t time);
00204 
00205     /**
00206      * Set the approx. time a transition will take
00207      */
00208     void setTimePerTransition(uint16_t time);
00209 
00210     // Customize indicator position and style
00211 
00212     /**
00213      * Draw the indicator.
00214      * This is the defaut state for all frames if
00215      * the indicator was hidden on the previous frame
00216      * it will be slided in.
00217      */
00218     void enableIndicator();
00219 
00220     /**
00221      * Don't draw the indicator.
00222      * This will slide out the indicator
00223      * when transitioning to the next frame.
00224      */
00225     void disableIndicator();
00226 
00227     /**
00228      * Enable drawing of indicators
00229      */
00230     void enableAllIndicators();
00231 
00232     /**
00233      * Disable draw of indicators.
00234      */
00235     void disableAllIndicators();
00236 
00237     /**
00238      * Set the position of the indicator bar.
00239      */
00240     void setIndicatorPosition(IndicatorPosition pos);
00241 
00242     /**
00243      * Set the direction of the indicator bar. Defining the order of frames ASCENDING / DESCENDING
00244      */
00245     void setIndicatorDirection(IndicatorDirection dir);
00246 
00247     /**
00248      * Set the symbol to indicate an active frame in the indicator bar.
00249      */
00250     void setActiveSymbol(const uint8_t* symbol);
00251 
00252     /**
00253      * Set the symbol to indicate an inactive frame in the indicator bar.
00254      */
00255     void setInactiveSymbol(const uint8_t* symbol);
00256 
00257 
00258     // Frame settings
00259 
00260     /**
00261      * Configure what animation is used to transition from one frame to another
00262      */
00263     void setFrameAnimation(AnimationDirection dir);
00264 
00265     /**
00266      * Add frame drawing functions
00267      */
00268     void setFrames(FrameCallback* frameFunctions, uint8_t frameCount);
00269 
00270     // Overlay
00271 
00272     /**
00273      * Add overlays drawing functions that are draw independent of the Frames
00274      */
00275     void setOverlays(OverlayCallback* overlayFunctions, uint8_t overlayCount);
00276 
00277 
00278     // Loading animation
00279     /**
00280      * Set the function that will draw each step
00281      * in the loading animation
00282      */
00283     void setLoadingDrawFunction(LoadingDrawFunction loadingFunction);
00284 
00285 
00286     /**
00287      * Run the loading process
00288      */
00289     void runLoadingProcess(LoadingStage* stages, uint8_t stagesCount);
00290 
00291 
00292     // Manual Control
00293     void nextFrame();
00294     void previousFrame();
00295 
00296     /**
00297      * Switch without transition to frame `frame`.
00298      */
00299     void switchToFrame(uint8_t frame);
00300 
00301     /**
00302      * Transition to frame `frame`, when the `frame` number is bigger than the current
00303      * frame the forward animation will be used, otherwise the backwards animation is used.
00304      */
00305     void transitionToFrame(uint8_t frame);
00306 
00307     // State Info
00308     OLEDDisplayUiState* getUiState();
00309 
00310     int8_t update();
00311 };
00312 #endif