Main Page   Class Hierarchy   Compound List   File List   Compound Members   File Members

ActionEngine.h

Go to the documentation of this file.
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

Razor! Engine Developer's Guide. Copyright © by Tilo Christ. All Rights Reserved. Last updated: 4 Nov 2000