Diff: RA8875.h

Revision:

123:2f45e80fec5f

Parent:

114:dbfb996bfbf3

Child:

124:1690a7ae871c

--- a/RA8875.h	Tue May 17 22:33:06 2016 +0000
+++ b/RA8875.h	Mon Jul 25 10:55:58 2016 +0000
@@ -272,9 +272,34 @@
     /// @param cmd is the command to execute. See @ref filecmd_t.
     /// @param buffer is a pointer to the buffer being passed.
     /// @param size is the number of bytes in the buffer.
+    /// @returns the noerror signal.
     ///
     typedef RetCode_t (* PrintCallback_T)(filecmd_t cmd, uint8_t * buffer, uint16_t size);
     
+    typedef enum {
+        unknown,            ///< reason has not been assigned (this should not happen)
+        status_wait,        ///< driver is polling the status register while busy
+        command_wait,       ///< driver is polling the command register while busy
+        getc_wait,          ///< user has called the getc function
+        touch_wait,         ///< user has called the touch function
+        touchcal_wait       ///< driver is performing a touch calibration
+    } IdleReason_T;
+    
+    /// Idle Callback 
+    ///
+    /// This defines the interface for an idle callback. That is, when the 
+    /// driver is held up, pending some event, it can call a registered
+    /// idle function. This could be most useful for servicing a watchdog.
+    ///
+    /// The user code, which is notified via this API, can force the idle
+    /// to abort, by returning the external_abort value back to the driver.
+    ///
+    /// @param info informs the callback why it is idle.
+    /// @returns noerror to allow the driver continue waiting.
+    /// @returns external_abort if the pending action should be aborted.
+    ///
+    typedef RetCode_t (* IdleCallback_T)(IdleReason_T info);
+
     /// Constructor for a display based on the RAiO RA8875 
     /// display controller.
     ///
@@ -518,6 +543,38 @@
     RetCode_t TouchPanelInit(uint8_t bTpEnable, uint8_t bTpAutoManual, uint8_t bTpDebounce, 
         uint8_t bTpManualMode, uint8_t bTpAdcClkDiv, uint8_t bTpAdcSampleTime);
     
+    
+    /// Get the screen calibrated point of touch.
+    ///
+    /// This method determines if there is a touch and if so it will provide
+    /// the screen-relative touch coordinates. This method can be used in
+    /// a manner similar to Serial.readable(), to determine if there was a 
+    /// touch and indicate that - but not care about the coordinates. Alternately,
+    /// if a valid pointer to a point_t is provided, then if a touch is detected
+    /// the point_t will be populated with data. 
+    ///
+    /// @code
+    ///     Timer t;
+    ///     t.start();
+    ///     do {
+    ///        point_t point = {0, 0};
+    ///        if (display.TouchPanelReadable(&point)) {
+    ///            display.pixel(point, Red);
+    ///        }
+    ///    } while (t.read_ms() < 30000);
+    /// @endcode
+    ///
+    /// @param[out] TouchPoint is a pointer to a point_t, which is set as the touch point, if a touch is registered.
+    /// @returns a value indicating the state of the touch,
+    ///         - no_cal:   no calibration matrix is available, touch coordinates are not returned.
+    ///         - no_touch: no touch is detected, touch coordinates are not returned.
+    ///         - touch:    touch is detected, touch coordinates are returned.
+    ///         - held:     held after touch, touch coordinates are returned.
+    ///         - release:  indicates a release, touch coordinates are returned.
+    ///
+    TouchCode_t TouchPanelReadable(point_t * TouchPoint = NULL);
+
+
     /// Poll the TouchPanel and on a touch event return the a to d filtered x, y coordinates.
     ///
     /// This method reads the touch controller, which has a 10-bit range for each the
@@ -563,37 +620,6 @@
     ///
     TouchCode_t TouchPanelA2DRaw(int *x, int *y);
     
-    /// Get the screen calibrated point of touch.
-    ///
-    /// This method determines if there is a touch and if so it will provide
-    /// the screen-relative touch coordinates. This method can be used in
-    /// a manner similar to Serial.readable(), to determine if there was a 
-    /// touch and indicate that - but not care about the coordinates. Alternately,
-    /// if a valid pointer to a point_t is provided, then if a touch is detected
-    /// the point_t will be populated with data. 
-    ///
-    /// @code
-    ///     Timer t;
-    ///     t.start();
-    ///     do {
-    ///        point_t point = {0, 0};
-    ///        if (display.TouchPanelReadable(&point)) {
-    ///            display.pixel(point, Red);
-    ///        }
-    ///    } while (t.read_ms() < 30000);
-    /// @endcode
-    ///
-    /// @param[in, out] TouchPoint is a pointer to a point_t, which is set as the touch point, if a touch is registered.
-    /// @returns a value indicating the state of the touch,
-    ///         - no_cal:   no calibration matrix is available, touch coordinates are not returned.
-    ///         - no_touch: no touch is detected, touch coordinates are not returned.
-    ///         - touch:    touch is detected, touch coordinates are returned.
-    ///         - held:     held after touch, touch coordinates are returned.
-    ///         - release:  indicates a release, touch coordinates are returned.
-    ///
-    TouchCode_t TouchPanelReadable(point_t * TouchPoint = NULL);
-
-
     /// Wait for a touch panel touch and return it.
     /// 
     /// This method is similar to Serial.getc() in that it will wait for a touch
@@ -2023,9 +2049,10 @@
     /// Then, the PrintScreen(x,y,w,h) method is called. Each chunk of data in the
     /// BMP file to be created is passed to this callback.
     /// 
-    /// @param callback is the callback function.
+    /// @param callback is the optional callback function. Without a callback function
+    ///     it will unregister the handler.
     ///
-    void AttachPrintHandler(PrintCallback_T callback) { c_callback = callback; }
+    void AttachPrintHandler(PrintCallback_T callback = NULL) { c_callback = callback; }
 
     /// PrintScreen callback registration.
     ///
@@ -2063,6 +2090,18 @@
     ///
     RetCode_t PrintScreen(uint16_t layer, loc_t x, loc_t y, dim_t w, dim_t h, const char *Name_BMP);
     
+    /// idle callback registration.
+    ///
+    /// This method attaches a simple c-compatible callback of type XXXXXXXXXXX.
+    /// Then, at any time when the display driver is waiting, it will call the
+    /// registered function. This is probably most useful if you want to service
+    /// a watchdog, when you may have called an API that will "hang" waiting
+    /// on the user.
+    ///
+    /// @param callback is the idle callback function. Without a callback function
+    ///     it will unregister the handler.
+    ///
+    void AttachIdleHandler(IdleCallback_T callback = NULL) { idle_callback = callback; }
 
 #ifdef PERF_METRICS
     /// Clear the performance metrics to zero.
@@ -2281,6 +2320,8 @@
     RetCode_t (* c_callback)(filecmd_t cmd, uint8_t * buffer, uint16_t size);
     FPointerDummy  *obj_callback;
     RetCode_t (FPointerDummy::*method_callback)(filecmd_t cmd, uint8_t * buffer, uint16_t size);
+    
+    RetCode_t (* idle_callback)(IdleReason_T reason);
 };