Diff: RA8875.h

Revision:

149:c62c4b2d6a15

Parent:

147:3494792458d9

Child:

151:ae94daaaf8ad

Child:

152:a013ac0133e4

--- a/RA8875.h	Tue Jun 13 23:12:26 2017 +0000
+++ b/RA8875.h	Sun Aug 06 17:05:54 2017 +0000
@@ -336,10 +336,13 @@
     /// print screen callback
     ///
     /// The special form of the print screen will pass one blob at a time 
-    /// to the callback. There are basic command declaring that the stream
+    /// to the callback. There are basic commands declaring that the stream
     /// can be opened, a block written, and the stream closed. There is
     /// also a command to communicate the total size being delivered.
     ///
+    /// If the idle callback is registered, it will be activated passing
+    /// a parameter indicating the percent complete, which may be of value.
+    ///
     /// @code
     /// lcd.PrintScreen(x,y,w,h,callback);
     /// ... 
@@ -376,7 +379,8 @@
         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
+        touchcal_wait,      ///< driver is performing a touch calibration
+        progress,           ///< communicates progress
     } IdleReason_T;
     
     /// Idle Callback 
@@ -395,7 +399,7 @@
     ///     when the CPU is largely idle.
     ///
     /// @code
-    /// RetCode_t myIdle_handler(RA8875::IdleReason_T reason)
+    /// RetCode_t myIdle_handler(RA8875::IdleReason_T reason, uint16_t param)
     /// {
     ///     idleFlasher = !idleFlasher;
     ///     if (it_has_been_too_long())
@@ -406,10 +410,12 @@
     /// @endcode
     ///
     /// @param reason informs the callback why it is idle.
+    /// @param param is a 2nd parameter, which is used for certain reason codes
+    ///        for 'progress' reason code, param ranges from 0 to 100 (percent)
     /// @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 reason);
+    typedef RetCode_t (* IdleCallback_T)(IdleReason_T reason, uint16_t param = 0);
 
     /// Basic constructor for a display based on the RAiO RA8875 
     /// display controller, which can be used with no touchscreen,
@@ -2556,6 +2562,9 @@
     /// only layer 1 is visible, then the bitmap is only layer 1. However,
     /// if there is some other operation in effect (transparent mode).
     ///
+    /// If the idle callback is registered, it will be activated passing
+    /// a parameter indicating the percent complete, which may be of value.
+    ///
     /// @param[in] x is the left edge of the region to capture
     /// @param[in] y is the top edge of the region to capture
     /// @param[in] w is the width of the region to capture
@@ -2578,6 +2587,9 @@
     /// if there is some other operation in effect (transparent mode), it
     /// will return the blended image.
     ///
+    /// If the idle callback is registered, it will be activated passing
+    /// a parameter indicating the percent complete, which may be of value.
+    ///
     /// @param[in] x is the left edge of the region to capture
     /// @param[in] y is the top edge of the region to capture
     /// @param[in] w is the width of the region to capture
@@ -2645,6 +2657,26 @@
     /// a watchdog, when you may have called an API that will "hang" waiting
     /// on the user.
     ///
+    /// @code
+    /// RetCode_t myIdle_handler(RA8875::IdleReason_T reason, uint16_t param)
+    /// {
+    ///     static uint16_t lastProgress = 0xFFFF;
+    ///
+    ///     if (reason == RA8875::progress && param != lastProgress) {
+    ///         printf("Progress %3d%%\r\n", param);
+    ///         lastProgress = progress;
+    ///     }
+    ///     return noerror;
+    /// }
+    ///
+    ///     ...
+    ///     lcd.AttachIdleHandler(myIdle_handler);
+    ///     ...
+    ///     RetCode_t r = lcd.PrintScreen(0,0,LCD_W,LCD_H,"/local/print.bmp");
+    ///     if (r ...)
+    /// @endcode
+    ///
+    ///
     /// @param callback is the idle callback function. Without a callback function
     ///     it will unregister the handler.
     ///
@@ -2938,7 +2970,7 @@
     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);
+    RetCode_t (* idle_callback)(IdleReason_T reason, uint16_t param);
 };