Basic swim GUI for LPC4088
Fork of DMBasicGUI by
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: