Diff: SlideShow/SlideShow.h

Revision:

13:bff2288c2c61

Parent:

5:f4de114c31c3

Child:

14:647b1896ed84

--- a/SlideShow/SlideShow.h	Thu Feb 19 14:37:29 2015 +0100
+++ b/SlideShow/SlideShow.h	Mon Mar 09 10:40:55 2015 +0100
@@ -1,14 +1,68 @@
+/*
+ *  Copyright 2014 Embedded Artists AB
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
 
 #ifndef SLIDESHOW_H
 #define SLIDESHOW_H
 
 #include "mbed.h"
 #include "rtos.h"
-//#include "LcdController.h"
 #include "Image.h"
 #include "Renderer.h"
 
 /**
+ * SlideShow example
+ *
+ * For information on how to use the SlideShow and some examples see
+ * https://developer.mbed.org/teams/Embedded-Artists/wiki/LPC4088DM-Using-the-SlideShow-Engine
+ *
+ * @code
+ * #include "mbed.h"
+ * #include "SlideShow.h"
+ * #include "Renderer.h"
+ *
+ * static void tRender(void const *args)
+ * {
+ *   Renderer* s = (Renderer*)args;
+ *   s->render();
+ * }
+ * 
+ * int main(void) {
+ *    // initialize the display
+ *    ...
+ *
+ *    // create the renderer that will handle the display
+ *    Renderer r;
+ *
+ *    // create the slideshow
+ *    SlideShow s(&r);
+ *    
+ *    // parse and validate the script
+ *    SlideShow::SlideShowError err = s.prepare("/mci/myscript.txt");
+ *    if (err != SlideShow::Ok) {
+ *        // handle error here
+ *    }
+ *
+ *    // Create the thread to handle the display
+ *    Thread tr(tRender, &r, osPriorityHigh);
+ *    r.setRenderThread(&tr);
+ *
+ *    // Run the slideshow
+ *    s.run();
+ * }
+ * @endcode
  */
 class SlideShow {
 public:
@@ -23,14 +77,73 @@
         FileError,
     };
 
+    /** A function that the script can call during execution
+     *
+     *  @param calloutId   identifier given in setCalloutHandler()
+     *  @param ss          the slideshow instance
+     *  @param identifier  parameter to the "callout" tag in the script
+     *
+     *  @returns
+     *       Ok on success
+     *       One of the SlideShowError error codes on failure
+     */
     typedef SlideShowError (*calloutFunc)(int calloutId, SlideShow* ss, int identifier);
 
-    SlideShow(Renderer* r, /*LcdController::Config* screen,*/ const char* pathPrefix=NULL, uint8_t* bkg=NULL, int xoff=0, int yoff=0, int layer=0, Mutex* fileMutex=NULL);
+    /** Create a new slideshow
+     *
+     *  @param r           the renderer
+     *  @param pathPrefix  optional path to prepend to all paths in the script file
+     *  @param xoff        optional x coordinate to draw the slideshow at, default is 0
+     *  @param yoff        optional y coordinate to draw the slideshow at, default is 0
+     *  @param layer       optional z-order, higher layers are drawn on top of lower layers
+     *  @param fileMutex   optional mutex to prevent simultaneous access of the file system
+     */
+    SlideShow(Renderer* r, const char* pathPrefix=NULL, int xoff=0, int yoff=0, int layer=0, Mutex* fileMutex=NULL);
     ~SlideShow();
+    
+    /** Parses the script file and prepares internal structures
+     *
+     *  @param scriptFile  the script with the slideshow
+     *
+     *  @returns
+     *       Ok on success
+     *       One of the SlideShowError error codes on failure
+     */
     SlideShowError prepare(const char* scriptFile);
+    
+    /** Run the slideshow
+     *
+     *  This function will run until the script ends. If the script has
+     *  an eternal loop then this function will never return.
+     *
+     *  @returns
+     *       Ok on success
+     *       One of the SlideShowError error codes on failure
+     */
     SlideShowError run();
+    
+    /** Register a function that the script can call.
+     *
+     *  A callout function allows the use of the "callout" tag in a
+     *  slideshow script to e.g. notify the system or to trigger
+     *  something.
+     *
+     *  There can only be one callout function.
+     */
     void setCalloutHandler(calloutFunc func, int calloutId);
+    
+    /** Decouples this SlideShow from the Renderer
+     */
     void releaseScreen(void);
+    
+    /** Stops the SlideShow.
+     *
+     *  The SlideShow will be stopped at the next suitable time,
+     *  typically before processing the next step in the script.
+     *
+     *  This function is typically called upon an external trigger
+     *  like the user pressing a button to end the slideshow.
+     */
     void stop() { abortBeforeNextStep = true; }
 
 private: