00001 /********************************************************************************* 00002 * 00003 * Razor! Engine - A modular C++ presentation engine 00004 * 00005 * $Id$ 00006 * 00007 * Copyright (c) 2000 Tilo Christ. All Rights Reserved. 00008 * 00009 * This library is free software; you can redistribute it and/or 00010 * modify it under the terms of the GNU Lesser General Public 00011 * License as published by the Free Software Foundation; either 00012 * version 2.1 of the License, or (at your option) any later version. 00013 * 00014 * This library is distributed in the hope that it will be useful, 00015 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00016 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00017 * Lesser General Public License for more details. 00018 * 00019 * You should have received a copy of the GNU Lesser General Public 00020 * License along with this library; if not, write to the Free Software 00021 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 00022 * 00023 **********************************************************************************/ 00024 00025 00026 #ifndef ACTIONENGINE_H 00027 #define ACTIONENGINE_H 00028 00029 #include <PalmOS.h> 00030 00031 #include "Canvas.h" 00032 00033 00034 /** 00035 * ActionEngine defines the interface for the application-specific 00036 * behavior. It is triggered in regular intervals and has to react 00037 * by providing a visual representation of the current state. 00038 */ 00039 class ActionEngine 00040 { 00041 public: 00042 /** 00043 * Construct a new ActionEngine 00044 */ 00045 ActionEngine() 00046 { 00047 } 00048 00049 00050 /** 00051 * Destroy the ActionEngine 00052 */ 00053 virtual ~ActionEngine() {} 00054 00055 /** 00056 * Reset the ActionEngine. 00057 */ 00058 virtual void restart() = 0; 00059 00060 /** 00061 * Progress to the next period. Update the internal state of your 00062 * ActionEngine, but <em>DO NOT DRAW ANYTHING!</em>. Only draw 00063 * in your draw() operation. 00064 */ 00065 virtual void nextPeriod() = 0; 00066 00067 00068 /** 00069 * This method is invoked before the draw() method in order to 00070 * find out, whether the background of the drawing canvas shall 00071 * be left untouched since the last draw, erased to white, or 00072 * you don't care. 00073 * Don't cache this value, since it might change during each period! 00074 * 00075 * @return Same semantics as initMode parameter of WinScreenLock function of PalmOS 3.5: 00076 * <ul> 00077 * <li> winLockCopy - Provide the same screen contents as drawn by the last invocation of draw() 00078 * <li> winLockErase - Erase to white, 00079 * <li> winLockDontCare - Don't care. 00080 * </ul> 00081 */ 00082 virtual WinLockInitType getWinLockMode() const = 0; 00083 00084 00085 /** 00086 * Draw the visual appearance of the action onto the canvas. 00087 * 00088 * @param bounds this needs to be filled in with the coordinates of the area 00089 * that was modified by the paint operations. 00090 */ 00091 virtual void draw(RectangleType *bounds) const = 0; 00092 00093 00094 /// @name Input management 00095 //@{ 00096 /** 00097 * Receive an input event. 00098 * The ActionEngine can freely decide whether it wants to 00099 * react to it, or not. 00100 */ 00101 virtual void receiveEvent(const EventType* evtPtr) = 0; 00102 //@} 00103 00104 00105 /// @name Save & Restore 00106 //@{ 00107 /** 00108 * Get the save buffer. The contents of this buffer will 00109 * be saved away for later restoration. 00110 */ 00111 virtual void* getSaveStateBuffer() = 0; 00112 00113 /** 00114 * Release the save buffer. This is invoked when the 00115 * restore buffer is no longer needed. 00116 */ 00117 virtual void releaseSaveStateBuffer(void *stateBuffer) const = 0; 00118 00119 /** 00120 * Return the size of the buffer which contains the 00121 * state. This size is assumed to be the size of 00122 * the save state buffer and of the restore state buffer. 00123 */ 00124 virtual Int16 getStateBufferSize() const = 0; 00125 00126 /** 00127 * Get the restore buffer. This buffer will be 00128 * filled in with the stored state of the ActionEngine 00129 * and then presented to restoreState. 00130 */ 00131 virtual void* getRestoreStateBuffer() = 0; 00132 00133 /** 00134 * Release the restore buffer. This is invoked when the 00135 * restore buffer is no longer needed. 00136 */ 00137 virtual void releaseRestoreStateBuffer(void *stateBuffer) const = 0; 00138 00139 /** 00140 * Set the current state from the restore buffer. The 00141 * buffer is guaranteed to be identical to the one 00142 * which was returned by getRestoreStateBuffer(). 00143 */ 00144 virtual void restoreState(void *stateBuffer) = 0; 00145 //@} 00146 }; 00147 00148 00149 #endif